Concepts

Accept, execute and observe

An accepted prompt returns status: "accepted" and an owner-issued commandId after the durable commit. Repeating the same request identity and input replays the receipt. Changing the input under that identity is a conflict.

The runtime wakes reconciliation, acquires run resources, executes the model and tools, releases resources and records settlement. The host owns provider configuration and retry policy. Shiitake owns durable Session facts and work.

session.read() returns a bounded baseline. session.watch() owns a baseline and live changes resource. Close the watch when its consumer leaves. Addressing a Session performs no I/O. A client uses createShiitakeClient from the /client entry with the host’s authorized transport. Releasing that client does not cancel host work.

Cancellation targets an accepted commandId. too_late is an ordinary outcome when that work can no longer be withdrawn. session.abort() addresses current execution. Neither a cancelled observation nor a closed browser proves a tool has stopped.

Extensions and authority

Use defineExtension from /extensions. Configuration, collections and documents are declared before callbacks. The host’s grants are separate from the definition’s requests. Product feature names belong to the host roster.

Commands, settled hooks and timer hooks run synchronously within the owner transaction. Prompt and tool builders run outside that write transaction. Activation resources use the Effect scope. An extension failure records a stop reason. Resuming it replays missed settled work through its cursor.

Clients bind an extension contract with bindSessionExtension or bindAgentExtension from /client. Projection slots describe observed state, not assumed completion. See the prompt/tool test, state binding test and close test.

If the host supplies a Files surface, it must also supply tools and the Session’s gateTool. The same gate checks direct Files tools and the Files operations inside execute. A missing gate fails before model execution. Extension tool authority and final external access also remain host decisions.