Concepts

Tools and control

A tool pairs Pi’s descriptor with prepare(call, signal). Preparation decodes and authorizes the exact call. It returns either a typed rejection or a prepared executor. The Promise executor yields parts through an AsyncIterable. The Effect executor uses a Stream. Every executor must observe cancellation.

Run, turn, message and tool events carry causal identities. They let the host record which execution produced an observation. They do not create durable Session storage. Hosts may select parallel or sequential tool execution, steer active work and queue follow-up input through the existing control interfaces.

A tool opts into safe crash replay only when it is read-only or explicitly idempotent. The host persists the checkpoints needed to use resume. Declaring replay: "safe" does not make an external write idempotent. Pi’s provider messages and replay fields pass through unchanged.

Cancellation, retries and errors

Abort the Promise facade’s signal or interrupt the Effect fiber. Mule aborts the Pi stream and running tools and records one cancelled run_end. The Promise facade preserves an Error abort reason and rejects with it. A non-Error reason becomes an AbortError. An operation that ignores abort still needs its host to account for the backing work.

Tool preparation rejections and execution failures become model-visible error results, so the run can continue. Fatal model or control failures produce a failed run_end. A failed listener cannot be trusted to record that terminal event. Preserve the rejection and its cause when reporting it.

retry selects Pi’s bounded retry policy for each assistant call. Omitting it means no retry. Provider Retry-After evidence and retry observations use the existing run interfaces. Mule does not choose a provider policy for your host. modelStreamIdleTimeoutMs bounds silence between provider events.

Mule owns no model catalog, credential store, durable Session database, compaction service or process-restart scheduler. Compose those in the host.