wolli 0.0.3 → 0.0.4

package/docs/sdk.md

@@ -7,7 +7,7 @@ The SDK provides programmatic access to a wolli agent. It has two faces, and whi
 
 > Wolli's RPC transport is **HTTP/SSE over a loopback socket**, not stdin/stdout JSONL. There is no `--mode rpc` subprocess. A client attaches to a running daemon over `http://127.0.0.1:<port>`; the daemon owns the agent's lifecycle and outlives any one client.
 
-If you are building a client against an already-deployed agent, you almost always want the daemon face — start at [Quick Start](#quick-start). If you are embedding the engine itself, read [Core Concepts](#core-concepts).
+If you are building a client against an existing agent, you almost always want the daemon face — start at [Quick Start](#quick-start). If you are embedding the engine itself, read [Core Concepts](#core-concepts).
 
 ## Table of Contents
 
@@ -132,7 +132,7 @@ const { repo, session, env, cwd } = await openAgentSession("my-agent", {
 });
 ```
 
-`AgentRuntime` (exported as `AgentRuntime`, `AgentRuntimeOptions`) is the **daemon's internal engine**. It owns N resident sessions keyed by id, the single extension + integration runners, the model registry, auth, reload, and cleanup. The daemon (`runDaemon`) constructs one `AgentRuntime` and wraps the [HTTP/SSE routes](#rpc-mode) around it; `AgentRuntime` is what `createAgentSession` ultimately feeds.
+`AgentRuntime` (exported as `AgentRuntime`, `AgentRuntimeOptions`) is the **daemon's internal engine**. It owns N resident sessions keyed by id, the single integration, workflow, and hook runners, the model registry, auth, reload, and cleanup. The daemon (`runDaemon`) constructs one `AgentRuntime` and wraps the [HTTP/SSE routes](#rpc-mode) around it; `AgentRuntime` is what `createAgentSession` ultimately feeds.
 
 > `AgentRuntime` and its per-session `AgentSession` are documented here as the engine the daemon runs, **not** as an embedding path. They are not a turnkey `new AgentRuntime(...)` SDK surface — their options (`authStorage`, `integrationAccounts`, `integrationStore`, a resolved `model`) are the daemon's to assemble. To embed in-process, use `createAgentSession()` + the harness; to drive an agent remotely, use the [daemon client](#rpc-mode).
 
@@ -195,7 +195,7 @@ harness.subscribe((event) => {
 });
 ```
 
-> Wolli does **not** emit `compaction_start`/`compaction_end`, `auto_retry_start`/`auto_retry_end`, or `extension_error` on the forwarded stream. It **does** add `model_update`, `thinking_level_update`, and (over the daemon) `scoped_models_update`. See [Events over the daemon](#events-1) for the exact forwarded allowlist.
+> Wolli does **not** emit `compaction_start`/`compaction_end` or `auto_retry_start`/`auto_retry_end` on the forwarded stream. It **does** add `model_update`, `thinking_level_update`, and (over the daemon) `scoped_models_update`. See [Events over the daemon](#events-1) for the exact forwarded allowlist.
 
 ## Options Reference
 
@@ -249,7 +249,7 @@ Build the frozen prompt with `buildSystemPrompt()`, then pass the resulting stri
 import { buildSystemPrompt } from "@opsyhq/wolli";
 
 const systemPrompt = buildSystemPrompt({
-  config,            // AgentConfig (name, purpose, deployedAt)
+  config,            // AgentConfig (name)
   soul,              // frozen SOUL.md snapshot ("" when absent)
   memory,            // frozen MEMORY.md snapshot
   user,              // frozen USER.md snapshot
@@ -259,7 +259,7 @@ const systemPrompt = buildSystemPrompt({
 });
 ```
 
-The prompt is composed from the agent's identity (name + purpose), a frozen snapshot of curated memory (SOUL / MEMORY / USER), a deployed-vs-forming instruction block, and a docs-guidance block. It is **frozen for the session's lifetime** — edits to memory take effect next session.
+The prompt is composed from the agent's identity (its name), a frozen snapshot of curated memory (SOUL / MEMORY / USER), an onboarding block while the SOUL.md snapshot is empty, and a docs-guidance block. It is **frozen for the session's lifetime** — edits to memory take effect next session.
 
 ### Tools
 
@@ -269,38 +269,37 @@ Pass an `AgentTool[]` to `createAgentSession({ tools })`. Wolli ships built-in t
 import {
   createReadTool, createWriteTool, createEditTool,
   createBashTool, createGrepTool, createFindTool, createLsTool,
-  createMemoryTool, createDeployTool,
+  createMemoryTool,
 } from "@opsyhq/wolli";
 ```
 
 > There is no `tools: ["read", "bash"]` string allowlist and no `noTools`/`excludeTools` here — you build the `AgentTool[]` explicitly and pass it. The daemon assembles the active set itself; over the client, read it with [`listTools()`](#sessionhandle).
 
-### Extensions, Skills, Context Files, Slash Commands
+### Skills, Context Files, Slash Commands
 
-`createAgentSession()` accepts `resources?: AgentHarnessResources` — skills and prompt templates pre-mapped into the harness shapes for explicit invocation (`harness.skill()` / `harness.promptFromTemplate()`). Full discovery (extensions, skills, prompt templates, integrations) is the `AgentRuntime`'s job, not a `createAgentSession()` option.
+`createAgentSession()` accepts `resources?: AgentHarnessResources` — skills and prompt templates pre-mapped into the harness shapes for explicit invocation (`harness.skill()` / `harness.promptFromTemplate()`). Full discovery (integrations, workflows, hooks, tools, providers, skills, prompt templates) is the `AgentRuntime`'s job, not a `createAgentSession()` option.
 
 Helpers for assembling resources yourself:
 
 ```typescript
-import { loadSkills, BUILTIN_SLASH_COMMANDS, discoverAndLoadExtensions } from "@opsyhq/wolli";
+import { loadSkills, BUILTIN_SLASH_COMMANDS } from "@opsyhq/wolli";
 ```
 
-Over the daemon client, inspect the resolved set with [`listSkills()` / `listContexts()` / `getCommands()` / `listTools()` / `listIntegrations()`](#sessionhandle). See [extensions.md](extensions.md), [skills.md](skills.md), and [integrations.md](integrations.md).
+Over the daemon client, inspect the resolved set with [`listSkills()` / `listContexts()` / `getCommands()` / `listTools()` / `listIntegrations()`](#sessionhandle). See [skills.md](skills.md) and [integrations.md](integrations.md).
 
 ### Session Management
 
-In-process, sessions come from [`openAgentSession()`](#openagentsession-and-agentruntime-internal-engine) (resume latest / by id / fresh) backed by a `JsonlSessionRepo` tree. Read a stored session tree with `SessionManager`. Over the daemon, the runtime owns session replacement — see [`Agent.createSession()`](#agent) and the `create_session` command. A **forming** (not-yet-deployed) agent refuses new sessions: it stays in its birth session until `deploy`.
+In-process, sessions come from [`openAgentSession()`](#openagentsession-and-agentruntime-internal-engine) (resume latest / by id / fresh) backed by a `JsonlSessionRepo` tree. Read a stored session tree with `SessionManager`. Over the daemon, the runtime owns session replacement — see [`Agent.createSession()`](#agent) and the `create_session` command.
 
 ### Settings Management
 
-`AgentSettingsManager` reads and writes the agent's `agent.json` (`AgentConfig`: name, purpose, createdAt, port, token, the `deployedAt` deploy latch, and a `settings` override block — the default model lives in `settings.defaultModel`, read via `getDefaultModel()`) and the shared settings.
+`AgentSettingsManager` reads and writes the agent's `agent.json` (`AgentConfig`: name, createdAt, port, token, and a `settings` override block — the default model lives in `settings.defaultModel`, read via `getDefaultModel()`) and the shared settings.
 
 ```typescript
 import { AgentSettingsManager } from "@opsyhq/wolli";
 
 const store = AgentSettingsManager.create("my-agent");
 store.getDefaultModel();
-store.getAgentDeployed();
 ```
 
 ## Return Value
@@ -313,7 +312,7 @@ interface CreateAgentSessionResult {
 }
 ```
 
-That is the whole result — no extensions result, no model-fallback message. Everything else (events, model state, the session tree) is reached through the harness and the `session`/`repo` you passed in.
+That is the whole result — no model-fallback message. Everything else (events, model state, the session tree) is reached through the harness and the `session`/`repo` you passed in.
 
 ## Complete Example
 
@@ -410,7 +409,7 @@ AuthStorage, ModelRegistry    // credentials + model resolution
 AgentSettingsManager          // agent.json (AgentConfig)
 SessionManager                // session tree
 createReadTool, createWriteTool, createEditTool, createBashTool,
-createGrepTool, createFindTool, createLsTool, createMemoryTool, createDeployTool
+createGrepTool, createFindTool, createLsTool, createMemoryTool
 
 // ── Daemon engine (internal, but exported) ──
 AgentRuntime, type AgentRuntimeOptions
@@ -442,7 +441,7 @@ GET  /events                  (SSE) root control stream: agent snapshot + sessio
 GET  /sessions                       the session list (DaemonAgentState)
 GET  /sessions/:id/events     (SSE) one session's curated event stream (attaching makes it live)
 POST /sessions/:id/control           a command for that session; its sync response is the body
-POST /sessions/:id/ui-response        a client's answer to that session's parked extension dialog
+POST /sessions/:id/ui-response        a client's answer to that session's parked dialog
 GET  /health                         liveness; the only route with no auth
 ```
 
@@ -469,7 +468,7 @@ Authorization: Bearer <token>
 
 **Correlation id.** Set `id` on a command to match its response; events never carry an `id`.
 
-**Replay ring.** Each session's broadcaster keeps the last **256** events (`RING_SIZE`) with a monotonic sequence id as the SSE `id:`. On reconnect, send `Last-Event-ID: <n>` and the daemon replays buffered frames with `id > n` (bounded by the watermark captured at attach, so live and replayed frames stay disjoint). Extension-UI request frames and control-stream lifecycle frames carry **no** `id` and are not replayable.
+**Replay ring.** Each session's broadcaster keeps the last **256** events (`RING_SIZE`) with a monotonic sequence id as the SSE `id:`. On reconnect, send `Last-Event-ID: <n>` and the daemon replays buffered frames with `id > n` (bounded by the watermark captured at attach, so live and replayed frames stay disjoint). Dialog-UI request frames and control-stream lifecycle frames carry **no** `id` and are not replayable.
 
 ### Commands
 
@@ -483,16 +482,15 @@ Authorization: Bearer <token>
 | | `compact` | `{ customInstructions? }` |
 | | `wait_for_idle` | resolves when the turn loop is idle |
 | | `clear_queue` | returns the cleared `{ steering, followUp }` |
-| Session | `create_session` | additive; returns the new session snapshot; a forming agent refuses |
-| | `reload` | re-discover extensions/skills/prompts and rebuild the runner |
-| | `deploy` | flip the deploy latch, install the OS unit, swap to a fresh deployed session |
+| Session | `create_session` | additive; returns the new session snapshot |
+| | `reload` | re-discover integrations/workflows/hooks/tools/providers/skills/prompts and rebuild the runners |
 | | `shutdown` | ack, then self-exit (frees the fixed port) |
 | State | `get_state` | the session snapshot |
 | | `get_messages` / `get_entries` | conversation messages / tree entries |
-| | `get_commands` | slash commands (extension + prompt + skill) |
+| | `get_commands` | slash commands (prompt + skill) |
 | | `get_resource_summary` | counts + diagnostics |
 | | `get_tool_info` / `get_integration_info` / `get_skills` / `get_plugins` / `get_context_info` | capability reads |
-| Mutation | `seed_assistant_message` / `append_message` | birth opener seed / resumed-message append |
+| Mutation | `seed_assistant_message` / `append_message` | opener seed / resumed-message append |
 | Plugins | `install_plugin` / `remove_plugin` / `update_plugins` | single-writer; the daemon reloads itself after |
 | | `onboard_plugin` | runs the just-installed plugin's integration onboarding |
 | Model | `set_thinking_level` | `{ level }` |
@@ -502,7 +500,7 @@ Authorization: Bearer <token>
 | Auth | `login` / `logout` | `{ provider, authType }`; runs daemon-side, credentials never cross the wire |
 | | `get_login_providers` / `get_logout_providers` | eligible providers |
 
-> This is wolli's set, not pi's. There is no `cycle_model`, `cycle_thinking_level`, `set_steering_mode`/`set_follow_up_mode`, `bash`, `fork`/`clone`/`switch_session`, `export_html`, `get_session_stats`, or `set_session_name`. Wolli adds `deploy`, `shutdown`, `reload`, `create_session`, `install_plugin`/`remove_plugin`/`update_plugins`/`onboard_plugin`, `login`/`logout`/`get_login_providers`/`get_logout_providers`, `get_available_models`, `set_scoped_models`/`set_enabled_models`, and the granular `get_*_info` reads.
+> This is wolli's set, not pi's. There is no `cycle_model`, `cycle_thinking_level`, `set_steering_mode`/`set_follow_up_mode`, `bash`, `fork`/`clone`/`switch_session`, `export_html`, `get_session_stats`, or `set_session_name`. Wolli adds `shutdown`, `reload`, `create_session`, `install_plugin`/`remove_plugin`/`update_plugins`/`onboard_plugin`, `login`/`logout`/`get_login_providers`/`get_logout_providers`, `get_available_models`, `set_scoped_models`/`set_enabled_models`, and the granular `get_*_info` reads.
 
 Example — `set_model`:
 
@@ -526,7 +524,7 @@ Each session streams a **curated subset** of the harness's event surface out of
 | `thinking_level_update` | thinking level changed (`.level`) |
 | `scoped_models_update` | session model scope changed (`.scopedModels`) — host-originated, not a harness own-event |
 
-> Wolli forwards `model_update`, `thinking_level_update`, and `scoped_models_update` (none of which pi's RPC has) and drops `compaction_*`, `auto_retry_*`, and `extension_error`. `scoped_models_update` is bridged onto the session broadcaster by the runtime after `setScopedModels()` resolves.
+> Wolli forwards `model_update`, `thinking_level_update`, and `scoped_models_update` (none of which pi's RPC has) and drops `compaction_*` and `auto_retry_*`. `scoped_models_update` is bridged onto the session broadcaster by the runtime after `setScopedModels()` resolves.
 
 **Control stream (`GET /events`).** A low-volume root stream whose `hello` frame is the agent snapshot (`DaemonAgentState`) and whose later frames are session-lifecycle events, so a client tracking the open-session list never has to poll:
 
@@ -536,29 +534,29 @@ Each session streams a **curated subset** of the harness's event surface out of
 { "type": "session_renamed", "sessionId": "abc123", "sessionName": "my-feature-work" }
 ```
 
-### Extension UI Protocol
+### Dialog UI Protocol
 
-When a daemon-side extension calls `ctx.ui.select()`, `ctx.ui.confirm()`, etc., the daemon translates it into a request/response sub-protocol layered on the session stream.
+When a daemon-side workflow or integration calls `ctx.ui.select()`, `ctx.ui.confirm()`, etc., the daemon translates it into a request/response sub-protocol layered on the session stream.
 
-- **Dialog methods** (`select`, `confirm`, `input`, `editor`) push an `extension_ui_request` frame, park a promise keyed by `id`, and block until the client answers with `POST /sessions/:id/ui-response`.
-- **Fire-and-forget methods** (`notify`, `setStatus`, `setWidget`, `setTitle`, `setEditorText`) push a request frame with no expected response.
+- **Awaited dialogs** (`select`, `confirm`, `input`) push a `ui_request` frame, park a promise keyed by `id`, and block until the client answers with `POST /sessions/:id/ui-response`.
+- **The fire-and-forget `notify`** pushes a request frame with no expected response.
 
-Request frames are **not** `AgentHarnessEvent`s: they bypass the curated forwarded set and the replay ring (no SSE `id`, so a reconnect never re-delivers a stale dialog). All nine `method` literals are **camelCase** — `select`, `confirm`, `input`, `editor`, `notify`, `setStatus`, `setWidget`, `setTitle`, `setEditorText`.
+Request frames are **not** `AgentHarnessEvent`s: they bypass the curated forwarded set and the replay ring (no SSE `id`, so a reconnect never re-delivers a stale dialog). All four `method` literals are lowercase — `select`, `confirm`, `input`, `notify`.
 
 ```json
-{ "type": "extension_ui_request", "id": "uuid-1", "method": "select",
+{ "type": "ui_request", "id": "uuid-1", "method": "select",
   "title": "Allow command?", "options": ["Allow", "Block"], "timeout": 10000 }
 ```
 
 Answer (`POST /sessions/:id/ui-response`):
 
 ```json
-{ "type": "extension_ui_response", "id": "uuid-1", "value": "Allow" }
-{ "type": "extension_ui_response", "id": "uuid-2", "confirmed": true }
-{ "type": "extension_ui_response", "id": "uuid-3", "cancelled": true }
+{ "type": "ui_response", "id": "uuid-1", "value": "Allow" }
+{ "type": "ui_response", "id": "uuid-2", "confirmed": true }
+{ "type": "ui_response", "id": "uuid-3", "cancelled": true }
 ```
 
-A dialog with a `timeout` (ms) auto-resolves to its default when it expires. Surfaces that need real TUI access are degraded daemon-side: `custom()` returns `undefined`; `getEditorText()` returns `""`; `getToolsExpanded()` returns `false`; `setWorkingMessage`/`setWorkingIndicator`/`setFooter`/`setHeader`/`setEditorComponent` are no-ops; `pasteToEditor()` delegates to `setEditorText`; the theme family is inert. When the last client detaches, the session's parked dialogs resolve as cancelled (so a signal-less `editor` never hangs forever).
+A dialog with a `timeout` (ms) auto-resolves to its default when it expires. When the last client detaches, the session's parked dialogs resolve as cancelled (so a signal-less dialog never hangs forever).
 
 ### Error Handling
 
@@ -645,9 +643,9 @@ The agent collection on disk — holds no required state.
 import { Wolli } from "@opsyhq/wolli";
 
 const wolli = new Wolli();
-wolli.list();                                  // Agent[] — every agent under the agents root
-wolli.get("my-agent");                         // Agent | undefined
-wolli.create("my-agent", { purpose, model }); // create the home tree, return the handle
+wolli.list();                              // Agent[] — every agent under the agents root
+wolli.get("my-agent");                     // Agent | undefined
+await wolli.create("my-agent", { model }); // create the home tree, install + start the OS unit, return the handle
 ```
 
 #### Agent
@@ -664,7 +662,6 @@ await agent.getSession(id);             // open (or return cached) SessionHandle
 await agent.getLatestSession();         // the most-recent session (the daemon guarantees one exists)
 
 await agent.createSession();            // additive: a fresh session snapshot (caller switches to it)
-await agent.deploy();                   // commit the deploy + drive the stop-then-start daemon handoff
 await agent.restart();                  // bounce the daemon so it picks up code changes
 await agent.delete();                   // uninstall the OS unit, stop the daemon, delete the home dir
 
@@ -672,13 +669,13 @@ const off = agent.on("sessionAdded", (s) => { /* … */ });  // control-stream l
 agent.close();                          // close every session stream + the control stream
 ```
 
-> `connect()` opens **no** session — call `getSession(id)` / `getLatestSession()` afterward. `createSession`/`deploy` are agent-level (they spawn a session and may swap the transport), so they live on `Agent`, not `SessionHandle`.
+> `connect()` opens **no** session — call `getSession(id)` / `getLatestSession()` afterward. `createSession` is agent-level (it spawns a session), so it lives on `Agent`, not `SessionHandle`.
 
 #### SessionHandle
 
 The per-session proxy. Verbs round-trip through `agent.send(sessionId, …)`; the session's SSE feeds the local snapshot/queue caches.
 
-> **Ordering.** Opening a handle (`getSession`/`getLatestSession`) attaches the SSE stream — which is also what makes the session **live** on the daemon (rehydrating it if idle). Call `subscribe(...)` (and set `onUiRequest`) **before** `prompt(...)`, or you miss the leading deltas and any extension dialog that turn raises. `prompt()` resolves on acceptance; await `waitForIdle()` for completion. When the last handle closes, the daemon evicts the session (unless a turn is still streaming) — so keep the handle open for the whole turn, and remember a closed handle's parked dialogs resolve as cancelled.
+> **Ordering.** Opening a handle (`getSession`/`getLatestSession`) attaches the SSE stream — which is also what makes the session **live** on the daemon (rehydrating it if idle). Call `subscribe(...)` (and set `onUiRequest`) **before** `prompt(...)`, or you miss the leading deltas and any dialog that turn raises. `prompt()` resolves on acceptance; await `waitForIdle()` for completion. When the last handle closes, the daemon evicts the session (unless a turn is still streaming) — so keep the handle open for the whole turn, and remember a closed handle's parked dialogs resolve as cancelled.
 
 ```typescript
 const session = await agent.getLatestSession();
@@ -692,7 +689,7 @@ await session.clearQueue();
 
 // Subscribe to the curated session events.
 const unsubscribe = session.subscribe((event) => { /* AgentHarnessEvent */ });
-session.onUiRequest = (req) => { /* extension-UI dialog frame */ };
+session.onUiRequest = (req) => { /* dialog-UI request frame */ };
 await session.respondUi(req.id, { value: "Allow" });
 
 // Reads (cached snapshot vs round-trip).
@@ -723,11 +720,9 @@ await session.onboardPlugin(source);
 session.close();
 ```
 
-> The client's extension surface is **inert** — the runner lives server-side: `getShortcuts()` returns an empty map, `getMessageRenderer()` returns `undefined`, `emitUserBash()` resolves `undefined`, and `createShortcutContext()` throws. The only live extension bridge is `onUiRequest` + `respondUi`.
-
 ## Integrations
 
-Integrations (per-agent service connections with their own onboarding and producer loops) are configured and onboarded over the daemon (`onboard_plugin`, `login`) and inspected with `SessionHandle.listIntegrations()`. The integration authoring API (`createIntegrationRuntime`, `Integration`, `IntegrationAction`, onboarding context) is re-exported from the barrel. See [integrations.md](integrations.md) for the full surface.
+Integrations (per-agent service connections with their own onboarding and producer loops) are configured and onboarded over the daemon (`onboard_plugin`, `login`) and inspected with `SessionHandle.listIntegrations()`. The integration authoring API (`defineIntegration`, `Integration`, `IntegrationAction`, onboarding context) is re-exported from the barrel. See [integrations.md](integrations.md) for the full surface.
 
 ## Configuration and Environment
 
@@ -748,13 +743,13 @@ Per-agent on-disk layout (`~/.wolli/agents/<name>/`):
 
 ```
 agents/<name>/
-  agent.json        AgentConfig: name, purpose, port, token, deployedAt latch, settings (incl. defaultModel)
-  SOUL.md           who the agent is / what it's for (authored at deploy)
+  agent.json        AgentConfig: name, port, token, settings (incl. defaultModel)
+  SOUL.md           who the agent is / what it's for (authored by the agent; first line is its purpose)
   MEMORY.md         durable notes (edited via the memory tool)
   USER.md           facts about the human
   sessions/         JsonlSessionRepo session tree
   workspace/        the stable cwd passed to every session
-  integrations.json per-(service, account) credential registry
+  integrations.json per-service credential registry
   store/            per-integration runtime state, one file per service
   approvals.json    durable host-escalation prefix rules
 ```

package/docs/tools.md

@@ -0,0 +1,81 @@
+# Tools
+
+Typed actions the model calls, authored as one file per tool under `tools/`.
+
+A tool is a typed action the model can call during a turn (an HTTP request, a conversion, a query against a service you run). Authored tools run in the daemon process alongside the built-in suite: `bash`, `read`, `write`, `edit`, `grep`, `find`, `ls`, and `memory`. The built-ins route file and shell work through the agent's sandboxed environments; author a tool when the model needs an action that lives outside them. wolli loads every file under `tools/` into session tooling at startup. There is no mid-session registration.
+
+## Define a tool
+
+One file defines one tool, default-exporting `defineTool`:
+
+`~/.wolli/agents/assistant/tools/http_get.ts`
+
+```ts
+import { defineTool } from "wolli";
+import { Type } from "typebox";
+
+export default defineTool({
+  name: "http_get",
+  label: "HTTP GET",
+  description:
+    "Fetch a URL over HTTP GET and return the status line and body. Bodies over 50KB are truncated.",
+  promptSnippet: "Fetch a URL over HTTP GET",
+  parameters: Type.Object({
+    url: Type.String({ description: "Absolute http(s) URL" }),
+  }),
+  async execute(toolCallId, { url }, signal) {
+    const response = await fetch(url, { signal });
+    const body = (await response.text()).slice(0, 50_000);
+    return {
+      content: [{ type: "text", text: `${response.status} ${response.statusText}\n\n${body}` }],
+      details: { status: response.status },
+    };
+  },
+});
+```
+
+The `name` field is the identifier the model uses in tool calls; keep it matched to the filename. `label` is the human-readable name clients display for the running call. wolli evaluates the file at runtime; there is no build step.
+
+## What the model sees
+
+The model decides whether and how to call a tool from the definition's prompt-facing fields. `description` is the contract: state what the tool does, what it returns, and its limits, written for the model. `promptSnippet` is a one-line entry in the Available tools section of the default system prompt; a tool without one stays callable but is not advertised there. `promptGuidelines` appends bullets to the system prompt's Guidelines section while the tool is active, the place for usage rules ("Prefer `http_get` over `bash` with curl.").
+
+`parameters` is a TypeBox schema. wolli validates every call's arguments against it before `execute` runs, and per-property `description` strings reach the model, so constraints belong in the schema rather than in prose.
+
+## The `execute` function
+
+wolli calls `execute` in the daemon once the arguments pass validation. `toolCallId` identifies this call; the same id marks the call in the session record. `params` arrives typed from the `parameters` schema. `signal` fires when the turn is aborted; pass it to cancellation-aware work, as the example does with `fetch`.
+
+Long-running tools stream progress through `onUpdate`, which accepts the same shape as the return value:
+
+```ts
+onUpdate?.({ content: [{ type: "text", text: `fetched ${done} of ${total} pages` }], details: { done } });
+```
+
+Clients render each partial result in place while the call runs. Both `signal` and `onUpdate` are optional to handle; a short tool can ignore them. The fifth argument, `ctx`, carries `session`, the session facade for the session that made the call, and `integration`, which takes an imported [integration](./integrations.md) definition as a typed key and returns its flat action handle — the same resolver workflow handlers get, so a tool can call the actions of the integration it ships with.
+
+The return value carries `content`, the text or image parts the model reads, and `details`, structured data for logs and client rendering that stays out of model context. Throw an `Error` on failure instead of encoding it in `content`.
+
+## Execution
+
+Tool calls run as steps of the turn. Every call is recorded with its `toolCallId` as a child step under the `session.prompt` step that produced it, so a routed conversation shows exactly which tools each turn used. See [Workflows](./workflows.md) for the run tree these steps land in.
+
+`executionMode` controls concurrency within a batch of calls. Set `"sequential"` when a tool must not overlap other tool calls (it mutates shared state, say), or `"parallel"` when overlapping is safe; omitted, the session default applies.
+
+Do not return secrets, credentials, or unbounded output from a tool. Everything in `content` enters the model's context and persists in the session record; filter, bound, and redact results before returning them, the way the example caps the body at 50KB.
+
+## Tool, skill, or workflow
+
+| Need | Use |
+| --- | --- |
+| A typed action the model invokes mid-turn (an API call, a query) | A tool |
+| A procedure or reference the model reads and follows | A [skill](./skills.md) |
+| Code that fires on events and routes work into sessions | A [workflow](./workflows.md) |
+
+A tool extends what the model can do, a skill extends what it knows, and a workflow runs without being asked. Prefer a skill when prose over the built-in suite covers the job; author a tool only when the model needs a new typed action.
+
+## What to read next
+
+- [Workflows](./workflows.md): event-triggered routing code and the run tree tool calls nest under
+- [Skills](./skills.md): markdown capability documents the model loads when relevant
+- [Integrations](./integrations.md): transports that connect the agent to outside services

package/docs/workflows.md

@@ -0,0 +1,170 @@
+# Workflows
+
+Route events into sessions and automate the agent from `workflows/`.
+
+A workflow is a typed reaction to an event, or a callable operation, authored under `~/.wolli/agents/<name>/workflows/`. A file may define several — one per exported `defineWorkflow` result — and each export's name is the workflow's name (a `default` export takes the filename). Each firing of the trigger is a run, and everything the handler does through `ctx` is recorded as steps. Keep module scope free of state; wolli may reload the file at any time.
+
+A chat channel is a few workflows in one file: the inbound router binds each chat to its own session by tag, and the reply ships the answer back on the same tag.
+
+`~/.wolli/agents/assistant/workflows/telegram-chat.ts`
+
+```ts
+import { wolli } from "wolli";
+import telegram from "../integrations/telegram";
+
+// msg is typed from the event schema
+export const inbound = telegram.on("message", async (msg, ctx) => {
+  const chatTag = { "telegram:chat": String(msg.chatId) };
+  const [match] = await ctx.agent.findSessions(chatTag);
+  const session = match
+    ? await ctx.agent.openSession(match.id)
+    : await ctx.agent.createSession({
+        setup: (s) => s.appendTags(chatTag),
+      });
+  // followUp queues behind a running turn instead of interrupting it.
+  await session.sendUserMessage(msg.text, { deliverAs: "followUp" });
+});
+
+export const reply = wolli.on("agent_end", async (evt, ctx) => {
+  const chat = ctx.session.getTags()["telegram:chat"];
+  if (!chat) return; // not a telegram-bound session
+  const text = evt.messages
+    .filter((m) => m.role === "assistant")
+    .at(-1)
+    ?.content.filter((c) => c.type === "text")
+    .map((c) => c.text)
+    .join("")
+    .trim();
+  if (!text) return; // a pure tool-call turn sends nothing
+  await ctx.integration(telegram).sendMessage({ chatId: Number(chat), text });
+});
+```
+
+Two chats run in parallel because each holds its own tagged session, and any workflow can locate that session later with the same tag query.
+
+## Triggers
+
+`.on(...)` and `defineWorkflow(...)` are the two ways to author a workflow. `.on` is the sugar; `defineWorkflow` is the primitive it funnels through, and the only way to write a callable. There are three trigger kinds.
+
+An integration event: import the integration and bind one of its events with `.on`, as `inbound` does with `telegram.on("message", ...)`. The event name is typed from the integration, and the payload arrives typed and validated. `telegram.on("message", run)` is exactly `defineWorkflow({ on: telegram.events.message, run })` — the descriptor is inert data carrying the (service, event) address and the payload type.
+
+An agent lifecycle event: `wolli.on("<event>", run)`, no integration import needed.
+
+`workflows/turn-metrics.ts`
+
+```ts
+import { wolli } from "wolli";
+
+// evt is typed via AgentEventMap
+export default wolli.on("turn_end", async (evt, ctx) => {
+  console.log(`turn ${evt.turnIndex} ran ${evt.toolResults.length} tools`);
+});
+```
+
+A callable: no trigger, so no object to hang `.on` off — use `defineWorkflow` and declare `input` and `output` TypeBox schemas. The agent invokes a callable workflow by name.
+
+`workflows/fetch-page.ts`
+
+```ts
+import { defineWorkflow } from "wolli";
+import { Type } from "typebox";
+
+export default defineWorkflow({
+  input: Type.Object({ url: Type.String() }),
+  output: Type.Object({ excerpt: Type.String() }),
+  async run(input) {
+    const res = await fetch(input.url);
+    return { excerpt: (await res.text()).slice(0, 500) };
+  },
+});
+```
+
+### Lifecycle events
+
+This is the complete set. Handlers are observe-only; a workflow watches these events and cannot modify them.
+
+| Event | Fires when |
+| --- | --- |
+| `session_start` | a session starts, loads, or reloads |
+| `session_shutdown` | a session is torn down on quit, reload, or replacement |
+| `agent_start` | an agent loop begins processing a prompt |
+| `agent_end` | the loop finishes, with the turn's messages |
+| `turn_start` | a turn inside the loop begins |
+| `turn_end` | a turn ends, with the assistant message and tool results |
+| `message_start` | a user, assistant, or tool-result message begins |
+| `message_update` | an assistant message streams a token update |
+| `message_end` | a message completes |
+| `tool_execution_start` | a tool call starts |
+| `tool_execution_update` | a tool call reports partial output |
+| `tool_execution_end` | a tool call finishes, with its result |
+| `model_select` | the session switches models |
+| `thinking_level_select` | the session changes thinking level |
+
+## The handler and ctx
+
+The handler receives the trigger payload and a context scoped to the run. `inbound` already used `ctx.agent`, the this-agent surface: `findSessions(tags)` subset-matches session tags newest first, `openSession(id)` rehydrates a stored session, `createSession(opts)` starts a fresh one, `listSessions()` enumerates them, and `cwd` is the agent home path. Lifecycle-triggered runs also carry the session that produced the event:
+
+`workflows/greet-new-session.ts`
+
+```ts
+import { wolli } from "wolli";
+import telegram from "../integrations/telegram";
+
+export default wolli.on("session_start", async (evt, ctx) => {
+  const chat = ctx.session.getTags()["telegram:chat"]; // the producing session
+  if (!chat || evt.reason !== "new") return;
+  const text = await ctx.step("compose-greeting", () => "Fresh session ready.");
+  await ctx.integration(telegram).sendMessage({ chatId: Number(chat), text });
+});
+```
+
+`ctx.integration(telegram)` takes the imported definition as a typed key and returns a flat action handle; parameters are validated on every call. `ctx.step(name, fn)` wraps inline logic in a named, recorded step. `ctx.signal` is the run's `AbortSignal`; pass it to anything long-running.
+
+`ctx.session` exists only on lifecycle-triggered runs, as the facade of the producing session (`prompt`, `sendUserMessage`, `getTags`, `setTags`, plus the read-only `getSessionName()` and `model` a router surfaces, e.g. in a `/status` command). Integration-event and callable runs have no producing session, so the field is absent. The same rule gates `ctx.ui`, four dialog primitives (`select`, `confirm`, `input`, `notify`) available only when `ctx.session` exists. Everywhere else the run is headless; a workflow that needs an answer from a user asks through its channel.
+
+## Runs and steps
+
+Each trigger firing creates a run named after the workflow, and every call through `ctx` lands in it as a step: `ctx.agent.*` calls, integration actions, `ctx.step` blocks, and session deliveries. `session.prompt` and `session.sendUserMessage` record one step each; what the prompted agent does inside the turn lives in that session's own history, not in the run. A routed chat message and its reply record like this:
+
+```
+run: inbound (telegram:message)
+  step: agent.findSessions        (auto)
+  step: agent.createSession       (auto)
+  step: session.sendUserMessage   (auto)
+run: reply (agent_end)
+  step: integration.call sendMessage (auto)
+```
+
+Step results are data. A step that produces a live object records its identity instead: a session step records the session id, and `ctx` rehydrates the handle when the handler touches it. Keep your own `ctx.step` return values serializable. There is no resume; a run that crashes does not continue, and its record shows how far it got.
+
+## Replies ride the session's tags
+
+`reply` reads the tag off the producing session, not off the channel: `ctx.session.getTags()["telegram:chat"]`. Because the reply rides the producing session's tags, the answer returns to the chat that started the turn, not to whoever messaged last. This composes across integrations: when a scheduler `due` event prompts a telegram-tagged session, `agent_end` fires with that session, the tag is present, and the digest lands in the chat. Neither workflow knows the other exists.
+
+Channel commands are inline logic in the inbound workflow, not a registration system:
+
+```ts
+// In inbound, before the session lookup:
+if (msg.text.startsWith("/")) return handleCommand(msg, ctx); // /new, /status
+```
+
+## Failure
+
+A thrown handler fails the run. wolli records the failure alongside the steps that completed before it, and does not retry. Catch the errors you can act on inside the handler; let the rest fail the run so the record stays honest.
+
+## Workflow vs tool vs skill vs integration
+
+| Need | Use |
+| --- | --- |
+| React to an event, or route it into a session | a workflow |
+| Give the model an action it can call mid-turn | a tool |
+| Teach the agent a procedure in prose | a skill |
+| Speak a service's protocol (transport, events, actions) | an integration |
+
+Integrations move bytes; workflows decide where they go. When logic could live in either, put the transport in the integration and the decision in a workflow.
+
+## What to read next
+
+- [Integrations](./integrations.md): the transport half, `defineIntegration`, events, and actions.
+- [Tools](./tools.md): typed actions loaded into session tooling.
+- [Skills](./skills.md): markdown capability documents the agent reads.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "wolli",
-	"version": "0.0.3",
+	"version": "0.0.4",
 	"description": "Persistent, purposeful agent CLI with memory and identity",
 	"type": "module",
 	"piConfig": {