@with-logic/elwood 0.1.1 → 0.1.3

package/dist/state/store.js

@@ -8,6 +8,7 @@
 import { existsSync, rmSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { elwoodError, toError } from "../core/errors.js";
+import { assertStatePath } from "./directories.js";
 import { safeSessionDir, secureMkdir, sharedMkdir, writePrivateFileAtomic, writeSharedFile, } from "./files.js";
 import { currentFileOwner, readPrivateFile } from "./private-read.js";
 import { removeSocketHome } from "./socket-home.js";
@@ -29,6 +30,8 @@ export function createSessionRecord(input) {
 }
 export function prepareStateDir(stateDir, options = {}) {
     const root = resolve(stateDir);
+    assertStatePath(root);
+    assertStatePath(join(root, "sessions"));
     if (options.gitignore === true) {
         sharedMkdir(root);
     }
@@ -79,7 +82,10 @@ export function removeSessionFiles(input) {
     // both ran, so teardown removes everything it can and still surfaces the fault.
     let firstError;
     firstError = tryRemove(() => removeSocketHome(input.socketHome), firstError);
-    firstError = tryRemove(() => rmSync(dir, { recursive: true, force: true }), firstError);
+    firstError = tryRemove(() => {
+        assertStatePath(dir);
+        rmSync(dir, { recursive: true, force: true });
+    }, firstError);
     if (firstError !== undefined) {
         throw elwoodError("teardown_failed", "Could not remove Elwood session files.", {
             cause: firstError instanceof Error ? firstError.message : String(firstError),

package/dist/state/store.js.map

@@ -1 +1 @@
-{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/state/store.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/state/store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EACL,cAAc,EACd,WAAW,EACX,WAAW,EACX,sBAAsB,EACtB,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,gBAAgB,EAAkB,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACtF,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAWtD,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,SAAS,CAAC,CAAC;AACvC,CAAC;AAED,OAAO,EAAE,cAAc,IAAI,UAAU,EAAE,CAAC;AAExC,MAAM,UAAU,mBAAmB,CAAC,KAInC;IACC,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,IAAI,QAAQ,CAAC;IAC1C,OAAO;QACL,aAAa,EAAE,CAAC;QAChB,eAAe,EAAE,KAAK,CAAC,EAAE;QACzB,OAAO;QACP,GAAG,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC;QACvB,MAAM,EAAE,EAAE;QACV,KAAK,EAAE,EAAE;KACV,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,eAAe,CAC7B,QAAgB,EAChB,UAA4C,EAAE;IAE9C,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC/B,eAAe,CAAC,IAAI,CAAC,CAAC;IACtB,eAAe,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC;IACxC,IAAI,OAAO,CAAC,SAAS,KAAK,IAAI,EAAE,CAAC;QAC/B,WAAW,CAAC,IAAI,CAAC,CAAC;IACpB,CAAC;SAAM,CAAC;QACN,WAAW,CAAC,IAAI,CAAC,CAAC;IACpB,CAAC;IACD,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;IAC/C,IAAI,OAAO,CAAC,SAAS,KAAK,IAAI,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;QAC7D,eAAe,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC;IACxC,CAAC;IACD,WAAW,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC;AACtC,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,kBAAkB,CAAC,MAAqB,EAAE,UAAkB;IAC1E,sBAAsB,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;AACzF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAAgB,EAChB,EAAU,EACV,QAA+B,gBAAgB,EAAE;IAEjD,MAAM,OAAO,GAAG,CAAC,KAAa,EAAE,EAAE,CAChC,WAAW,CAAC,eAAe,EAAE,gCAAgC,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IAChF,MAAM,IAAI,GAAG,eAAe,CAAC,UAAU,CAAC,cAAc,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IACvF,IAAI,IAAI,KAAK,SAAS;QAAE,MAAM,WAAW,CAAC,iBAAiB,EAAE,+BAA+B,EAAE,EAAE,CAAC,CAAC;IAClG,IAAI,GAAY,CAAC;IACjB,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC;IACxC,CAAC;IACD,MAAM,MAAM,GAAG,qBAAqB,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IAC9C,IAAI,CAAC,MAAM;QAAE,MAAM,WAAW,CAAC,eAAe,EAAE,gCAAgC,EAAE,EAAE,CAAC,CAAC;IACtF,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,qBAAqB,CACnC,MAAqB,EACrB,OAA2B,EAC3B,QAAgB;IAEhB,OAAO,EAAE,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,EAAE,CAAC;AACpE,CAAC;AAUD,oFAAoF;AACpF,MAAM,UAAU,kBAAkB,CAAC,KAA8B;IAC/D,MAAM,GAAG,GAAG,cAAc,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;IAClE,gFAAgF;IAChF,+EAA+E;IAC/E,iFAAiF;IACjF,gFAAgF;IAChF,IAAI,UAAmB,CAAC;IACxB,UAAU,GAAG,SAAS,CAAC,GAAG,EAAE,CAAC,gBAAgB,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC,CAAC;IAC7E,UAAU,GAAG,SAAS,CAAC,GAAG,EAAE;QAC1B,eAAe,CAAC,GAAG,CAAC,CAAC;QACrB,MAAM,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAChD,CAAC,EAAE,UAAU,CAAC,CAAC;IACf,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,WAAW,CAAC,iBAAiB,EAAE,wCAAwC,EAAE;YAC7E,KAAK,EAAE,UAAU,YAAY,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC;YAC5E,UAAU,EAAE,GAAG;SAChB,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAED,oFAAoF;AACpF,SAAS,SAAS,CAAC,IAAgB,EAAE,KAAc;IACjD,IAAI,CAAC;QACH,IAAI,EAAE,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,KAAK,IAAI,KAAK,CAAC;IACxB,CAAC;AACH,CAAC;AAED,SAAS,UAAU,CAAC,GAAW;IAC7B,OAAO,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;AACnC,CAAC"}

package/docs/cli-behavior.md

@@ -17,7 +17,7 @@ sources are:
 
 Each fact below was verified against a real CLI (versions noted where relevant).
 When a fact drives an implementation decision, the code and the matching PRD
-conformance criterion are cited. If you change behavior here, update `PRD.md`
+conformance criterion are cited. If you change behavior here, update `prd/`
 first (see `CLAUDE.md` / `AGENTS.md`), then this file.
 
 ## Readiness

package/docs/cli-output.md

@@ -5,9 +5,9 @@ exit codes, and safe shell recipes. Start with [cli.md](cli.md) for usage.
 
 ## Text, verbose, and stream
 
-Text is the default output protocol. Warnings and diagnostics go to stderr,
-never into the answer on stdout. `--verbose` adds compact elapsed phase,
-tool-name, warning, and cleanup progress; it does not repeat assistant or
+Text is the default output protocol. Live session warnings are quiet by default,
+including during `elwood models`. Errors remain visible. `--verbose` adds compact
+elapsed phase, tool-name, warning, and cleanup progress on stderr; it does not repeat assistant or
 thinking text. `--debug` adds full sanitized event details. `--stream` emits
 assistant text as it arrives and is valid only with text output; use
 `--no-stream` when config enabled streaming but a script needs JSON.
@@ -26,7 +26,9 @@ a downstream pipe closing early triggers cleanup without an uncaught `EPIPE`.
 
 `--output json` emits exactly one version-1 document. Its stable fields are
 `schemaVersion`, `type`, `agent`, `response`, `sessionId`, `durationMs`,
-`cleanup`, and, on failure, `error`:
+`cleanup`, and, on failure, `error`. The examples below use `--ephemeral`, so
+cleanup removes session state and `sessionId` is null. By default, CLI turns
+preserve state and return a resumable session ID once one is available:
 
 ```json
 {
@@ -66,7 +68,8 @@ a usage error or `no_agent_found`) reports `"agent": null`.
 `--output jsonl` emits sequenced version-1 `text`, `thinking`, `tool`,
 `status`, and `warning` records followed by exactly one `result` or `error`
 record. Every record has `sequence` and `elapsedMs`; tool calls and results
-share `toolCallId` when the agent supplies one:
+share `toolCallId` when the agent supplies one. This example also uses
+`--ephemeral`:
 
 ```jsonl
 {"schemaVersion":1,"type":"status","status":"running","sequence":1,"elapsedMs":114}
@@ -77,7 +80,9 @@ share `toolCallId` when the agent supplies one:
 ```
 
 JSONL warning records stay on stdout so the machine protocol remains ordered;
-text and JSON runs surface warnings on stderr.
+text and JSON runs surface session warnings on stderr only with `--verbose`
+or `--debug`. `ELWOOD_VERBOSE=true` or config `verbose: true` also enables them;
+`--no-verbose` overrides inherited verbosity (but not explicit `--debug`).
 
 ## Session and model listings
 
@@ -108,10 +113,35 @@ in JSON mode, and `sessions` never starts an agent:
 check, so a force-killed owner can leave a stale "live" until the session is
 next started or torn down. An empty state directory yields an empty `sessions`
 array (text mode prints a notice on stderr and nothing on stdout). Unreadable
-records are skipped with one stderr warning each.
+records are skipped with one stderr warning each, even without verbosity,
+because the listing omits those results.
 
-`elwood models` starts the agent briefly to read its own model picker, then
-tears the session down:
+`elwood models` probes Claude then Codex, regardless of saved or environment
+agent defaults. Text includes an `AGENT` column. JSON contains successful
+catalogs and canonical per-agent error records in one document:
+
+```json
+{
+  "schemaVersion": 1,
+  "type": "models",
+  "agents": [
+    { "agent": "claude", "models": [] },
+    { "agent": "codex", "models": [] }
+  ],
+  "errors": []
+}
+```
+
+Each probe opens and cancels its model picker and always removes its session
+state. An empty `models` array means that probe succeeded with no rows. If an
+adapter fails, its catalog is absent from `agents` and its canonical error
+record appears in `errors`, including `agent`, `error`, `durationMs`, and
+`cleanup`. Available catalogs remain present. Incomplete results exit nonzero:
+130 for interruption, then 124 for timeout, 2 for usage errors, or 1 for other
+failures, in that precedence order. `--timeout` is a whole-command budget; no
+next probe starts after timeout or Ctrl-C.
+
+Explicit `elwood models --agent claude` retains its single-agent document:
 
 ```json
 {
@@ -125,7 +155,7 @@ tears the session down:
 }
 ```
 
-Failures use the same `error` document and statuses as a run. Useful recipes:
+Single-agent failures use the same `error` document and statuses as a run. Useful recipes:
 
 ```sh
 id=$(elwood sessions --output json | jq -r '.sessions[0].id')

package/docs/cli.md

@@ -83,8 +83,9 @@ Boolean environment values are exactly `true` or `false`.
 Run `elwood --help` for the full flag list. Launch controls include `--model`,
 `--reasoning-effort`, `--persona`, `--claude-permission-mode`,
 `--codex-sandbox`, `--codex-approval-policy`, `--state-dir`, `--verbose`,
-`--debug`, and `--trust` / `--no-trust`. The built-in non-interactive posture
-is Claude `dontAsk`, or Codex `workspace-write` with approval policy `never`.
+`--debug`, and `--trust` / `--no-trust`. Live session warnings are quiet by
+default; use `--verbose` or `--debug` to see them, including for `elwood models`.
+The built-in non-interactive posture is Claude `dontAsk`, or Codex `workspace-write` with approval policy `never`.
 
 For an unattended run that must never stop on a permission prompt, prefer the
 agent-neutral `--high-trust` over per-agent posture flags. It selects Claude

package/docs/codex/cli.md

@@ -0,0 +1,57 @@
+# Codex CLI Notes
+
+Sources researched:
+
+- https://developers.openai.com/codex/cli/features
+- https://developers.openai.com/codex/cli/reference
+- local `codex --help` and `codex --version` output
+
+## Interactive Mode
+
+`codex` launches an interactive full-screen terminal UI. That is the mode Elwood
+must wrap. The parent app should control Codex through PTY input and observe it
+through hooks, not through `codex exec`, the SDK, or app-server APIs.
+
+Codex accepts an optional initial prompt, but Elwood starts without one by
+default and sends prompts later through the terminal input path.
+
+Useful CLI capabilities for Elwood:
+
+- `codex` starts a new interactive session.
+- `codex resume <SESSION_ID>` resumes a specific interactive session.
+- `codex resume --last` resumes the most recent interactive session for the
+  current working directory.
+- `--cd <DIR>` tells Codex which project root to use.
+- `--config key=value` applies one-off TOML configuration overrides.
+- `--model <MODEL>`, `--profile <NAME>`, `--sandbox <MODE>`, and
+  `--ask-for-approval <POLICY>` map naturally to adapter launch options.
+- Some Codex versions expose `--dangerously-bypass-hook-trust`, which lets
+  generated Elwood hooks run for one invocation without requiring a persisted
+  trust prompt. Elwood must detect support before passing it because other Codex
+  versions reject unknown flags. Detection is cached for the lifetime of the
+  Elwood process.
+- Codex can also render interactive trust and update prompts before the session
+  is usable. Elwood should select `Trust all and continue` for hook prompts, and
+  skip TUI update prompts because API-level `autoupdate` runs `codex update`
+  before launch when requested. Detection should use Elwood's headless xterm.js
+  screen snapshot, not raw ANSI/PTY byte parsing.
+- Codex may print non-fatal environment warnings before the session is ready,
+  such as MCP servers that are not logged in. Elwood should preserve raw
+  terminal output and also project recognized warnings into typed `warning`
+  events with remediation commands.
+
+## Resume Implications
+
+Codex stores transcripts locally under Codex-owned state. Elwood should persist
+only the Codex session id needed to call `codex resume <SESSION_ID>`. If that id
+has not arrived through hooks yet, Elwood fails with `resume_unavailable`.
+Elwood must not silently fall back to `codex resume --last` because that can
+attach the caller's Elwood session id to the wrong Codex conversation. A future
+API may add an explicit opt-in fallback, but it is not part of the current
+contract.
+
+## Shell Implications
+
+The process should still be launched from the user's normal interactive login
+shell so `codex` resolution, auth environment, and user shell startup behavior
+match opening Terminal.app manually.

package/docs/codex/config.md

@@ -0,0 +1,47 @@
+# Codex Configuration Notes
+
+Sources researched:
+
+- https://developers.openai.com/codex/config-basic
+- https://developers.openai.com/codex/config-advanced
+- https://developers.openai.com/codex/config-reference
+- https://developers.openai.com/codex/hooks
+
+## Layers
+
+Codex reads configuration from CLI flags and `--config` overrides first, then
+profiles, trusted project `.codex/config.toml` files, user config, system config,
+and built-in defaults.
+
+Project-local `.codex` layers are only loaded when Codex trusts the project.
+Because Elwood should be minimally invasive, it should not edit user or project
+Codex config by default.
+
+## Elwood Strategy
+
+Elwood should generate session-scoped hook bridge files under `.elwood/` and
+inject Codex hook configuration through `--config` one-off overrides. This keeps
+existing `.codex/config.toml` and `~/.codex/config.toml` intact while still
+letting Codex merge user defaults and policies normally.
+Elwood applies `hookTrust="trust-all"` after caller overrides so parent apps
+cannot accidentally create an unusable wrapper session.
+
+The generated command should enable or configure:
+
+- hooks for every supported Codex hook event;
+- the bridge command and timeout for each event;
+- `hookTrust="trust-all"`, because Elwood cannot observe or control Codex
+  without trusted hooks;
+- optional launch policy such as model, profile, sandbox, approval policy, and
+  caller-supplied raw config overrides;
+- `--dangerously-bypass-hook-trust` when the installed Codex CLI advertises it,
+  because the generated hooks are ephemeral Elwood-owned bridge commands. Elwood
+  must omit this flag for Codex versions that do not support it.
+
+If Codex still renders a `Hooks need review` TUI prompt, Elwood should select
+`Trust all and continue` through the headless xterm.js input path so the session
+is usable headlessly.
+
+If a managed Codex requirement disallows unmanaged hooks, Codex may ignore or
+reject Elwood hook config. Elwood should surface startup/bridge failures through
+typed errors where possible and hook runtime failures through `hookError`.

package/docs/codex/hooks.md

@@ -0,0 +1,70 @@
+# Codex Hooks Notes
+
+Sources researched:
+
+- https://developers.openai.com/codex/hooks
+- https://github.com/openai/codex/tree/main/docs
+- local `codex features list` output
+
+## Events
+
+The current documented Codex hook events relevant to Elwood are:
+
+- `SessionStart`
+- `SubagentStart`
+- `PreToolUse`
+- `PermissionRequest`
+- `PostToolUse`
+- `PreCompact`
+- `PostCompact`
+- `UserPromptSubmit`
+- `SubagentStop`
+- `Stop`
+
+`SessionStart`, `PreToolUse`, `PermissionRequest`, `PostToolUse`,
+`UserPromptSubmit`, `SubagentStart`, `SubagentStop`, and `Stop` include a Codex
+permission mode field. Turn-scoped hooks include `turn_id`.
+
+## Matchers
+
+Hook matchers are regex strings. Tool hooks match `tool_name`; compaction hooks
+match `manual` or `auto`; `SessionStart` matches the source such as startup or
+resume; subagent hooks match agent type. `UserPromptSubmit` and `Stop` currently
+ignore matchers.
+
+For file edits, Codex reports the canonical tool name `apply_patch`, while
+matchers may also use `Edit` or `Write`.
+
+Tool hooks currently cover `Bash`, `apply_patch`, and MCP tool calls. They do
+not cover every TUI-visible activity. In particular, Codex docs state that web
+search and other non-shell/non-MCP tool calls do not trigger `PreToolUse` or
+`PostToolUse` today. Reasoning/status lines shown in the TUI are also not hook
+events.
+
+Elwood therefore treats hooks as the control/approval path and uses live-only
+transcript observation as a secondary rendering path for parent apps that need
+to display reasoning phases, web search calls, assistant messages, and other
+Codex-visible activity.
+
+## Response Model
+
+No output with exit code `0` means no decision and Codex continues.
+
+Codex accepts event-specific JSON output. Important shapes for Elwood:
+
+- `PreToolUse` can deny a supported tool call with `permissionDecision: "deny"`
+  and a reason, add additional context, or allow a rewritten tool input.
+- `PermissionRequest` can decide `allow` or `deny` with `{ hookSpecificOutput:
+  { hookEventName, decision: { behavior, message? } } }`. It must not return
+  updated input or permission edits.
+- `Stop` and `SubagentStop` can return `decision: "block"` with a reason to ask
+  Codex to continue instead of marking the turn done.
+- `PostToolUse`, `UserPromptSubmit`, `SubagentStart`, `PreCompact`, and
+  `PostCompact` are observe-only in Elwood until Codex documents a stable
+  response contract for them.
+
+Elwood should fail open when parent handlers are missing, time out, throw, or
+return an invalid response for the event.
+
+Handlers should return `undefined` for no decision. Empty objects are invalid so
+accidentally empty responses surface as `hookError` and fail open.

package/examples/README.md

@@ -0,0 +1,56 @@
+# Elwood Examples
+
+## Minimal: ask and answer (`minimal.ts`)
+
+The smallest possible use of Elwood. Construct a session, `send` a message, get the
+assistant's reply back as a string, ask a follow-up. The session starts lazily on the
+first `send`, so there is no start ceremony and no manual "wait for ready".
+
+```sh
+npm run example:minimal
+```
+
+```ts
+const session = new CodexSession({ autotrust: true });
+const joke = await session.send("Tell me a joke that involves a dog.");
+const rewrite = await session.send("Now rewrite it to be about a cat.");
+await session.close();
+```
+
+## Streaming: watch the work (`stream.ts`)
+
+When you want the intermediate steps, `stream` yields typed events (`thinking`,
+`tool_call`, `tool_result`, `text`) as they arrive. `send` is just this generator
+drained for the `text`, so the two share one turn boundary.
+
+```sh
+npm run example:stream
+```
+
+```ts
+for await (const event of session.stream("List the files, then summarize the project.")) {
+  if (event.type === "text") process.stdout.write(event.text);
+  // event.type is also "thinking" | "tool_call" | "tool_result"
+}
+```
+
+## Full: the raw control surface (`full.ts`)
+
+`full.ts` drops below the ergonomic facade to the low-level API: `startClaude`/
+`startCodex`, raw `activity`/`warning`/`terminal:exit` events, an explicit
+`waitForSettled` helper (from `support.ts`) that watches `status` and
+`terminal:exit`, and CLI flags for agent/cwd/prompt/timeout. Reach for this when you
+need full control over the session lifecycle; most callers want `send`/`stream` above.
+
+```sh
+npm run example:full
+npm run example:full -- --agent codex --cwd . --prompt "Summarize this repo in one paragraph."
+npm run example:full -- --agent claude --cwd . --prompt "Summarize this repo in one paragraph."
+```
+
+All examples use `autotrust: true` so embedded sessions can move past known workspace
+trust prompts. The package scripts run the TypeScript examples under a small Node
+supervisor because `node-pty` owns real PTYs more reliably there and the supervisor can
+kill the example process tree on Ctrl-C. The examples import from `../src/index.ts`
+so they run from a checkout without a build; in your own project import the same
+symbols from `@with-logic/elwood`.

package/examples/full.ts

@@ -0,0 +1,113 @@
+/**
+ * Full runnable Elwood example for starting one agent session, sending one
+ * message, logging rich events, and cleaning up the process.
+ */
+
+import { resolve } from "node:path";
+import { startClaude, startCodex } from "../src/index.ts";
+import {
+  type Agent,
+  cleanupSession,
+  type ExampleSession,
+  errorMessage,
+  isTerminalStatus,
+  textSuffix,
+  waitForSettled,
+} from "./support.ts";
+
+type Options = {
+  readonly agent: Agent;
+  readonly cwd: string;
+  readonly keep: boolean;
+  readonly prompt: string;
+  readonly timeoutMs: number;
+};
+
+const defaultPrompt = "Say hello from Elwood in one short sentence, then stop.";
+const options = parseArgs(process.argv.slice(2));
+let session: ExampleSession | undefined;
+
+try {
+  session = await startSession(options);
+  wireLogs(session);
+  process.stdout.write(`started ${options.agent} session ${session.elwoodSessionId}\n`);
+  await session.sendMessage(options.prompt);
+  if (!(await waitForSettled(session, options.timeoutMs))) {
+    throw new Error(`Timed out after ${options.timeoutMs}ms waiting for the agent to finish.`);
+  }
+} catch (error) {
+  process.stderr.write(`${errorMessage(error)}\n`);
+  process.exitCode = 1;
+} finally {
+  if (session && !options.keep && !isTerminalStatus(session.status)) await cleanupSession(session);
+}
+
+async function startSession(options: Options): Promise<ExampleSession> {
+  const common = { cwd: options.cwd, autotrust: true, initialSize: { cols: 120, rows: 40 } };
+  return options.agent === "claude" ? await startClaude(common) : await startCodex(common);
+}
+
+function wireLogs(session: ExampleSession): void {
+  session.on("activity", (event) => {
+    process.stdout.write(
+      `[activity] ${event.agent}:${event.kind}:${event.label}${textSuffix(event.text)}\n`,
+    );
+  });
+  session.on("warning", (event) => {
+    process.stdout.write(`[warning] ${event.agent}:${event.code} ${event.message}\n`);
+  });
+  session.on("hookError", (event) => {
+    process.stdout.write(`[hookError] ${event.hookEventName}:${event.category} ${event.message}\n`);
+  });
+  session.on("terminal:exit", (event) => {
+    process.stdout.write(`[terminal:exit] code=${event.exitCode}\n`);
+  });
+}
+
+function parseArgs(args: readonly string[]): Options {
+  let agent: Agent = "codex";
+  let cwd = process.cwd();
+  let keep = false;
+  let prompt = defaultPrompt;
+  let timeoutMs = 120_000;
+  let index = 0;
+  while (index < args.length) {
+    const arg = args[index];
+    if (arg === "--help") return printUsageAndExit();
+    if (arg === "--agent")
+      [agent, index] = [parseAgent(requireValue(args, index + 1, arg)), index + 2];
+    else if (arg === "--cwd")
+      [cwd, index] = [resolve(requireValue(args, index + 1, arg)), index + 2];
+    else if (arg === "--prompt") [prompt, index] = [requireValue(args, index + 1, arg), index + 2];
+    else if (arg === "--timeout-ms")
+      [timeoutMs, index] = [Number(requireValue(args, index + 1, arg)), index + 2];
+    else if (arg === "--keep") [keep, index] = [true, index + 1];
+    else throw new Error(`Unknown option: ${arg}`);
+  }
+  if (!prompt) throw new Error("--prompt must not be empty.");
+  if (!Number.isInteger(timeoutMs) || timeoutMs <= 0)
+    throw new Error("--timeout-ms must be positive.");
+  return { agent, cwd: resolve(cwd), keep, prompt, timeoutMs };
+}
+
+function requireValue(args: readonly string[], index: number, flag: string): string {
+  const value = args[index];
+  if (!value) throw new Error(`Missing value for ${flag}.`);
+  return value;
+}
+
+function parseAgent(value: string): Agent {
+  if (value === "claude" || value === "codex") return value;
+  throw new Error("--agent must be claude or codex.");
+}
+
+function printUsageAndExit(): never {
+  process.stdout.write(
+    [
+      "Usage: npm run example:full",
+      '       npm run example:full -- --agent codex --cwd . --prompt "Summarize this repo."',
+      "",
+    ].join("\n"),
+  );
+  process.exit(0);
+}

package/examples/minimal.ts

@@ -0,0 +1,15 @@
+/**
+ * The smallest Elwood example: ask a question, get the answer, ask a follow-up.
+ * The ergonomic facade starts Codex lazily on the first `send` and gives back the
+ * assistant's text as a string (PRD §5.8).
+ */
+
+import { CodexSession } from "../src/index.ts";
+
+const session = new CodexSession({ autotrust: true });
+try {
+  process.stdout.write(`${await session.send("Tell me a joke that involves a dog.")}\n`);
+  process.stdout.write(`${await session.send("Now rewrite it to be about a cat.")}\n`);
+} finally {
+  await session.close();
+}

package/examples/stream.ts

@@ -0,0 +1,39 @@
+/**
+ * Ergonomic streaming: watch a turn's typed events — thinking, tool calls/results, and
+ * assistant text — as they arrive, instead of waiting for the final string (PRD §5.8).
+ * `send` is just this generator drained for text; `stream` is the same turn, live.
+ */
+
+import { ClaudeSession } from "../src/index.ts";
+
+/** Compile-time exhaustiveness guard: reaching this with a real value means a case is missing. */
+function assertNever(value: never): never {
+  throw new Error(`unhandled turn event: ${JSON.stringify(value)}`);
+}
+
+const session = new ClaudeSession({ autotrust: true });
+try {
+  for await (const event of session.stream("List the files here, then summarize the project.")) {
+    switch (event.type) {
+      case "thinking":
+        process.stderr.write(`  (thinking) ${event.text}\n`);
+        break;
+      case "tool_call":
+        process.stdout.write(`→ ${event.name}${event.input ? ` ${event.input}` : ""}\n`);
+        break;
+      case "tool_result":
+        process.stdout.write(`← ${event.output ?? ""}\n`);
+        break;
+      case "text":
+        process.stdout.write(event.text);
+        break;
+      default:
+        // Exhaustiveness: adding a new TurnEvent variant makes this fail to compile, so the
+        // canonical example can never silently ignore a newly-surfaced event kind.
+        assertNever(event);
+    }
+  }
+  process.stdout.write("\n");
+} finally {
+  await session.close();
+}

package/examples/support.ts

@@ -0,0 +1,71 @@
+/**
+ * Shared helpers for runnable Elwood examples.
+ * Implements PRD §11 example behavior.
+ */
+
+import type {
+  ElwoodActivityEvent,
+  ElwoodSessionStatus,
+  ElwoodWarningEvent,
+  HookErrorEvent,
+  Unsubscribe,
+} from "../src/index.ts";
+
+export type Agent = "claude" | "codex";
+export type ExampleSession = {
+  readonly elwoodSessionId: string;
+  readonly status: ElwoodSessionStatus;
+  on(event: "activity", handler: (event: ElwoodActivityEvent) => void): Unsubscribe;
+  on(event: "warning", handler: (event: ElwoodWarningEvent) => void): Unsubscribe;
+  on(event: "hookError", handler: (event: HookErrorEvent) => void): Unsubscribe;
+  on(
+    event: "status",
+    handler: (event: { readonly status: ElwoodSessionStatus }) => void,
+  ): Unsubscribe;
+  on(event: "terminal:exit", handler: (event: { readonly exitCode: number }) => void): Unsubscribe;
+  sendMessage(message: string): Promise<void>;
+  stop(): Promise<void>;
+  kill(): Promise<void>;
+};
+
+export function waitForSettled(session: ExampleSession, timeoutMs: number): Promise<boolean> {
+  if (session.status === "ready" || isTerminalStatus(session.status)) return Promise.resolve(true);
+  return new Promise((resolveWait) => {
+    const done = (result: boolean) => {
+      clearTimeout(timer);
+      for (const unsubscribe of unsubs) unsubscribe();
+      resolveWait(result);
+    };
+    const timer = setTimeout(() => done(false), timeoutMs);
+    const unsubs: Unsubscribe[] = [
+      session.on("status", (event) => {
+        if (event.status === "ready" || isTerminalStatus(event.status)) done(true);
+      }),
+      session.on("terminal:exit", () => done(true)),
+    ];
+  });
+}
+
+export async function cleanupSession(session: ExampleSession): Promise<void> {
+  try {
+    await session.stop();
+  } catch (error) {
+    process.stderr.write(`stop failed, killing session: ${errorMessage(error)}\n`);
+    await session.kill();
+  }
+}
+
+export function isTerminalStatus(status: ElwoodSessionStatus): boolean {
+  return (
+    status === "stopped" || status === "exited" || status === "killed" || status === "torn_down"
+  );
+}
+
+export function textSuffix(text: string | undefined): string {
+  if (!text) return "";
+  return ` ${text.replace(/\s+/g, " ").slice(0, 120)}`;
+}
+
+export function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}