my-durable 0.0.0-stage → 0.0.2

package/ai_docs/durable_pi/vacation-planner.md

@@ -0,0 +1,57 @@
+> Source: [packages/coding-agent/src/experimental/vacation/README.md](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/src/experimental/vacation/README.md)
+> Retrieved with Firecrawl: 2026-10-05. Repository snapshot: `b78e6a9085343ec0f308c3d377da72528b4cf7ee`.
+> Relative documentation links point to local copies where available, otherwise to the source snapshot.
+
+# vacation
+
+A durable vacation planning agent with a TUI, built on `@earendil-works/pi-durable`. It is a copy of the durable coding
+agent in [`../durable`](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/src/experimental/durable) with the coding tools and pi's coding prompt replaced by a vacation planner. It only
+looks like a coding agent because it reuses pi's interactive TUI components.
+
+From a pi checkout, after `npm install` and `npm run build`:
+
+```bash
+node packages/coding-agent/src/experimental/vacation/main.ts
+node packages/coding-agent/src/experimental/vacation/main.ts --continue
+```
+
+Without a build, preload the source resolver so the workspace packages load from `src` instead of `dist`:
+
+```bash
+node --import ./packages/coding-agent/src/experimental/source-resolver.ts packages/coding-agent/src/experimental/vacation/main.ts
+```
+
+A new session starts with pi's default model and thinking level from `settings.json`. `--continue` opens the newest
+session for the current directory. Sessions live under
+`~/.pi/agent/experimental/vacation-sessions/<cwd-hash>/<session>/session.sqlite`. Log in with pi itself; credentials are
+shared.
+
+## What it shows
+
+- **Background subagent:** the `research` tool starts a subagent in its own conversation and returns at once. A
+  background task delivers the request and posts the subagent's report back to the main conversation as a new message,
+  so you keep chatting with the main agent while the research runs.
+- **Parallel durable tool calls:** the subagent's `search` calls run in parallel, each as its own task in the task
+  panel. The results are canned; each topic takes a different time.
+- **Recovery:** `search` is safe to rerun. Kill the process while a search runs and start it again with `--continue`:
+  finished searches are kept, the unfinished one runs again, and the report still arrives. Request IDs keep a restart
+  from sending the request or the report twice.
+- **Everything else from the durable coding agent:** steering, follow-ups, `/agents`, `/compact`, `/tasks`, `/model`.
+
+## Try it
+
+1. "Plan a weekend in Vienna for two. Hand the research to a subagent."
+2. While the searches run, ask the main agent something else.
+3. Ctrl+C while only the trains search is left, then start again with `--continue`.
+4. `/agents` to watch or steer the subagent, `/agents` again to go back to main.
+
+## Layout
+
+| file | role |
+| --- | --- |
+| `vacation.ts` | the vacation extensions: `search`, `research`, the report task, and the prompt |
+| `main.ts` | arguments, open, run, close |
+| `sessions.ts` | session directories and the lock |
+| `harness-setup.ts` | HTTP setup, settings, the registry, the initial model |
+| `runtime.ts` | Harness and the plain `DurableView` and `DurableController` |
+| `tui.ts` | rendering with pi's interactive components |

package/ai_docs/pi/chord.md

@@ -0,0 +1,268 @@
+> Source: [packages/chord/README.md](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/chord/README.md)
+> Retrieved with Firecrawl: 2026-10-05. Repository snapshot: `b78e6a9085343ec0f308c3d377da72528b4cf7ee`.
+> Relative documentation links point to local copies where available, otherwise to the source snapshot.
+
+# @earendil-works/chord
+
+Chord is an application-composition runtime for systems assembled from
+plugins/extensions. It provides facets, services, replicated state, and a
+pluggable remote-service boundary. It is developed as a standalone package in
+the Pi monorepo, but it is not a Pi package: it does not depend on any other Pi
+workspace package and can be used by unrelated applications.
+
+## What Chord is for
+
+A single application feature may need to run in several environments: for
+example, an agent worker, a terminal UI, and a remote WebUI.  Chord provides the
+generic machinery to write such extensions in a way that is both delightful for
+humans as well as agents.
+
+The design has a few connected pieces:
+
+- **Plugins** are synchronous setup units that declare the services they provide
+  and require. After every plugin has declared its shape, a host validates the
+  complete dependency graph, binds services, activates providers before consumers,
+  and disposes resources in reverse dependency order.  These units are called
+  *facets*.
+
+- **Facets** are parts of a plugin.  Each facet is bundled up separately and runs
+  in the process or environment where it's supposed to run.  You can use facets
+  to split a plugin into separate pieces that need to be loaded into different
+  processes and environments (think backend, browser, TUI etc.)
+
+- **Services** are typed, stable tokens with either one provider (**singleton**)
+  or dynamic keyed instances (**keyed**).  A service can be process-local, with
+  an unrestricted JavaScript contract, or remotely exposable. Consumers retain a
+  stable facade while a provider disconnects or is replaced.
+
+- **Replicated state** exposes authoritative state to local and remote
+  connected consumers. Producers publish atomic overlay transactions with
+  `change(context, callback)`; consumers receive complete immutable values. Draft
+  proxies exist only during the callback and become unusable afterward. Preparation
+  materializes a structurally shared immutable candidate and one exact decoded
+  operation batch, while each remote client/state stream owns independent path-codec
+  state. Replicas become unready on disconnect or replacement until rehydrated.
+
+- **Delta tracking** records and coalesces operations over tracked plain JSON.
+  It preserves common string and array operations, supports durable base
+  batches, and validates untrusted operations as they are applied. Batches
+  guarantee convergence but are not canonical or necessarily minimal.
+
+- **Remote service sources** advertise services available outside a facet host
+  and open bindings for the services its facets require. Bindings carry logical
+  calls and subscriptions through an application-supplied adapter. Chord
+  requires strict-JSON arguments, results, snapshots, updates, and catalogues,
+  but does not prescribe framing, routing, transport, or an application wire
+  envelope. `JsonRepresentation<T>` derives a wire-safe type for application data
+  with unknown payloads, while `isJsonValue()` validates received values at an
+  adapter boundary. Symmetric RPC peers are planned as one optional
+  implementation of this boundary.
+
+- **Context** Chord provides a Go-like context system for cancellation and
+  invocation-scoped application values. Applications can carry permissions or
+  telemetry through those values without Chord depending on either.
+
+The current runtime exports service tokens, singleton and keyed providers,
+remote bindings, replicated state, facet hosts, and facet loaders from
+`@earendil-works/chord`. Import public types and general runtime APIs from the
+package root. Context constants and functions live in
+`@earendil-works/chord/context` because their generic names should not pollute
+the root API.
+Chord-owned identifiers use the `chord.*` namespace and its reserved service
+prefix is `$chord.*`.
+
+## Remote service adapters
+
+Chord owns its transport-independent service wire grammar. Consumer adapters
+use `createServiceCatalogueCall()`, `createServiceSubscribeCall()`, and
+`createServiceUnsubscribeCall()` for `$chord.service` control calls.
+`createRemoteServiceEndpoint()` handles those calls for one provider consumer,
+including subscription activation and cleanup. `parseServiceCall()`,
+`parseServiceCatalogue()`, and the decoded/wire snapshot and update parsers
+validate Chord semantics after an adapter has established a strict-JSON
+boundary. `RemoteServiceErrorCode` and `REMOTE_SERVICE_ERROR_CODES` define the
+service errors that may cross that boundary.
+
+Replicated state operations use one `createServiceStateEncoder()` at the
+provider side and one `createServiceStateDecoder()` at the consumer side for
+each subscription. Those registries create an independent Delta path dictionary
+for every instance/member state and reset it on replacement, unavailability,
+close, or fresh hydration. Applications may place these values inside any
+routing, request, response, or event envelope; Chord does not prescribe that
+outer protocol.
+
+Provider subscriptions atomically capture a snapshot and buffer subsequent
+updates until activation. Activation and reentrant publication use the same FIFO.
+The provider retains at most 100 pending updates per subscription, excluding the
+running delivery. Adding update 101 replaces the entire pending queue with
+`{ type: "reset", snapshot }`: a current full subscription snapshot whose state
+members contain `[["r", value]]` and their new sequence baselines. It also captures
+current instance membership, so discarded spawn/close/replacement events cannot
+leave stale instances behind. Live keyed generations retain their existing handles.
+The reset carries the context of the publication that triggered overflow.
+
+Consumers and codecs must handle this explicit reset before accepting subsequent
+ordinary deltas. A root operation in an ordinary `state` update does **not** permit
+a sequence gap. Resets restart the subscription's path dictionaries, and later
+deltas must be contiguous from each reset baseline. Transport adapters must
+preserve snapshot/reset/update order; they must not drop encoded delta batches or
+assume their own asynchronous queues are bounded by the provider's queue.
+
+## Tracking JSON deltas
+
+Import the standalone transactional tracker from `@earendil-works/chord/delta`:
+
+```ts
+import { applyImmutable, track } from "@earendil-works/chord/delta";
+
+const tracker = track({ output: "", count: 0 });
+const change = tracker.beginChange();
+change.state.output += "done\n";
+change.state.count += 1;
+const prepared = change.prepare();
+
+tracker.adopt(prepared);
+const replica = applyImmutable(prepared.base, prepared.ops);
+```
+
+`tracker.value` is always the latest adopted immutable revision. Preparation does
+not change authority; adoption validates the preparation and swaps the root pointer.
+Assigned containers are copied by value and unchanged subtrees may be shared between
+revisions.
+
+The tracker uses trusted immutable ownership rather than defensive copying or
+freezing. `track(initial)`, `prepareReplace(value)`, `replicatedState(initial)`, and
+`replace(context, value)` take ownership of alias-free strict-JSON roots without
+walking them. Callers must not mutate transferred or published data. Values placed
+through drafts are already copied, so that walk also rejects non-strict JSON before
+the draft changes. Published values are not frozen. In-process loopback consumers
+may share their containers with the provider; mutating a consumed value violates
+the contract and can corrupt authority. Clone or serialize at any mutable trust
+boundary.
+
+Replicated state provides the same model through a callback:
+
+```ts
+const initial = { output: "", count: 0 };
+const status = env.replicatedState(initial); // transfers ownership of initial
+status.change(context, (draft) => {
+	draft.output += "done\n";
+	draft.count += 1;
+});
+```
+
+A successful `change()` publishes exactly one atomic revision. If its callback
+throws, the original value and sequence remain unchanged. Draft handles become
+unusable when the callback returns. Chord emits string append and front-truncate
+operations, array splices and permutations, sets, and deletes; large edit sets may
+fold into a complete replacement. Remote connection plumbing encodes each batch
+independently for every client/state pairing.
+
+### Public state subscriptions
+
+`state.subscribe(async (value, context, delivery) => { ... })` serializes callbacks
+independently for each subscription. Hydration starts immediately when a value is
+available, and its returned promise must settle before updates start. Synchronous
+callbacks still run synchronously. Read the captured `value` inside an asynchronous
+callback: `state.value` may already refer to a later revision.
+
+Each subscription retains at most 100 pending complete-value deliveries, excluding
+the running callback. On overflow, only the newest pending value, context, and
+delivery metadata are retained; a not-yet-started initial hydration is preserved.
+Thus public delivery sequences may skip. This is a frame-count policy, not a byte
+limit. Internal exact-operation subscriptions remain synchronous and receive every
+revision, independently of slow public callbacks.
+
+The returned unsubscribe function immediately discards pending work and prevents
+new callbacks. It neither aborts nor waits for the running callback. Synchronous
+throws and promise rejections are observed, reported, and do not stop other
+subscriptions or subsequent callbacks. Attached sources and remote bindings use
+their `onError` handler; local mutable states (and attached sources without a
+handler) report failures by throwing in a microtask. Unsubscribing does not hide a
+later rejection from the running callback.
+
+The standalone [Delta guide](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/chord/src/delta/README.md) defines the complete ownership,
+lifecycle, operation, and replica contracts.
+
+## Bundling and loading facets
+
+`@earendil-works/chord/bundler` uses esbuild to turn ESM or TypeScript application
+entries into independent, content-addressed CommonJS files. The package-level API
+reads plugin identity and build configuration from `package.json`, then applies
+facet path conventions supplied by the host application:
+
+```json
+{
+  "name": "@example/my-plugin",
+  "version": "1.0.0",
+  "type": "module",
+  "peerDependencies": {
+    "@earendil-works/chord": "^0.84.4"
+  },
+  "chord": {
+    "facets": {
+      "worker": "./src/custom-worker.ts",
+      "presentation": false
+    }
+  }
+}
+```
+
+```ts
+import { bundleFacetPackage } from "@earendil-works/chord/bundler";
+
+await bundleFacetPackage({
+	packagePath: "/path/to/my-plugin",
+	outdir: "/application-owned/plugin-builds/my-plugin",
+	defaultFacets: {
+		worker: "src/worker.ts",
+		presentation: "src/presentation.ts",
+	},
+});
+```
+
+Existing conventional files become entries unless `chord.facets` overrides or
+disables them. Peer dependencies are externalized and resolved against the host
+when loading. Chord never installs dependencies or runs package lifecycle
+scripts. `bundleFacets()` remains available as the lower-level API for callers
+that already have explicit plugin identity and entry mappings.
+
+The output directory contains one `.cjs` file per entry plus
+`chord-facets.json`. Load one application-selected entry through the Node-only
+loader:
+
+```ts
+import { createFacetBundleLoader } from "@earendil-works/chord/node";
+
+const loader = createFacetBundleLoader({
+	manifestPath: "/application-owned/plugin-builds/my-plugin/chord-facets.json",
+	entry: "worker",
+	resolveExternal: (specifier) => import.meta.resolve(specifier),
+});
+const loaded = await loader.load();
+```
+
+Each `load()` verifies SHA-256 integrity and compiles the CommonJS body directly
+with `node:vm` instead of putting the plugin into Node's CommonJS or ESM module
+cache. Externals are resolved by the host and loaded through a restricted
+`require`; esbuild lowers dynamic imports so they use the same path. Disposing a
+retired generation releases the loader's facet references, making its compiled
+code eligible for garbage collection once plugin-owned resources are also gone.
+
+For transport to another Node host, `readFacetBundleArtifact()` packages one
+verified manifest entry with its source, and `createFacetBundleArtifactLoader()`
+materializes fresh temporary generations while resolving externals against the
+receiving host.
+
+To reload, load a candidate, pass its facets to `FacetHost.reload()`, dispose the
+candidate on failure, and dispose the retired `LoadedFacets` only after a
+successful cutover. The host activates and validates the candidate while the
+currently active providers remain routed, then replaces each singleton directly
+without an unavailable interval. Stable service handles therefore do not become
+disconnected during an ordinary reload. Keyed instances
+remain incarnation-specific and replacements receive fresh generations. The
+bundler writes a complete temporary directory before replacing the previous
+output, so loaders do not observe partially built generations.
+
+See [PLANNING.md](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/chord/PLANNING.md) for the broader RPC and generation-loading
+architecture.

package/ai_docs/pi/cli-integration.md

@@ -0,0 +1,110 @@
+> Source: [packages/coding-agent/docs/cli-integration.md](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/docs/cli-integration.md)
+> Retrieved with Firecrawl: 2026-10-05. Repository snapshot: `b78e6a9085343ec0f308c3d377da72528b4cf7ee`.
+> Relative documentation links point to local copies where available, otherwise to the source snapshot.
+
+# CLI Integration
+
+By default, running `pi` opens the interactive terminal interface. When input or output is piped or redirected, Pi uses print mode instead. You can also select print, JSON, or RPC mode explicitly for scripts and applications.
+
+All four modes use the same agent, sessions, resources, and tools. The mode determines how input enters Pi, how output is exposed, and whether the process remains available for more commands.
+
+The SDK is not a CLI mode. It embeds the agent directly in a Node.js or Bun process. See the [SDK](sdk.md) when direct TypeScript access is preferable to a process boundary.
+
+## Choose a mode
+
+| Mode | Interface | Lifetime | Use it when |
+|---|---|---|---|
+| Interactive | Terminal UI | Until the user exits | A person is working with Pi directly |
+| Print | Final text on stdout | One invocation | A script needs the final assistant response |
+| JSON | JSONL events on stdout | One invocation | A process needs structured progress from a run |
+| RPC | JSONL commands, responses, and events | Long-lived | A process needs bidirectional control |
+
+CLI options still select the working directory, model, tools, resources, and session persistence independently of the mode. See [Command Line](cli.md) for the complete startup options.
+
+## Print to stdout
+
+Print mode runs the supplied prompts, writes the final assistant text to stdout, and exits:
+
+```bash
+pi --print "Summarize the changes in this repository"
+```
+
+Use print mode when only the final text is needed, including command substitution, pipelines, and one-shot jobs. Intermediate events are not exposed.
+
+Print mode writes errors to stderr. A final assistant response with an `error` or `aborted` stop reason produces a nonzero exit status.
+
+When no mode is selected explicitly, non-TTY stdin or stdout also selects print mode. This allows piped input and output without adding `--print`.
+
+## Stream JSON events
+
+JSON mode writes a session header followed by agent and session events as newline-delimited JSON:
+
+```bash
+pi --mode json "Review this repository" > events.jsonl
+```
+
+This is structured event output, not a single JSON result or a constraint on the format of the model’s response.
+
+All prompts are supplied when the process starts. The process streams events for that run and then exits; it does not accept later commands.
+
+A failed or aborted assistant response appears in the event stream but does not by itself produce a nonzero exit status. Inspect the events when success or failure matters. Pi still exits nonzero if the invocation throws an error.
+
+Streaming `message_update` records contain deltas rather than a growing message snapshot. Assemble live output from the delta events, then replace it with the authoritative message from `message_end`.
+
+`agent_end` can be followed by automatic recovery or queued work. `agent_settled` marks the end of automatic work for the current run.
+
+Stdout is reserved for JSONL. Diagnostics and application logging are written to stderr. See [JSON Event Stream](json.md) for framing, event shapes, and reconstruction rules.
+
+## Control Pi with RPC
+
+RPC mode keeps Pi running while another process sends commands and receives responses and events:
+
+```bash
+pi --mode rpc --no-session
+```
+
+Commands are JSON objects written to stdin. Responses and events are JSON objects written to stdout. Every record occupies one line.
+
+Add an `id` to commands that need correlation. The matching response repeats that ID. Events generally have no command ID because they describe session activity rather than one request.
+
+A successful `prompt` response means the prompt was accepted, queued, or handled. It does not mean the run completed. Continue consuming events through `agent_settled` when completion matters.
+
+RPC commands can change models, inspect state, manage sessions, run shell commands, and answer extension UI requests.
+
+Extension dialogs form a request-response subprotocol. Other extension UI updates are notifications that a client may display or ignore. TUI-only extension capabilities are unavailable or degraded outside interactive mode.
+
+For Node.js or TypeScript integrations, prefer `RpcClient` from `@earendil-works/pi-coding-agent`. It starts a Pi RPC child process, correlates requests, exposes typed command methods, and delivers session events to listeners.
+
+The [RPC client example](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/examples/rpc-client.ts) sends one prompt, streams text and tool activity, waits for `agent_settled`, and shuts down the child process. It is included in the repository’s TypeScript checks.
+
+`RpcClient.promptAndWait()` installs its event listener before sending the prompt, avoiding a race with fast completions. For separate operations, subscribe before calling `prompt()` and call `waitForIdle()` only while a run is active.
+
+The client requires a path to a runnable Pi CLI. The repository example points at `dist/cli.js`, so the package must be built before that example runs from a checkout.
+
+If you are building a client without `RpcClient`, start with [RPC Protocol](rpc.md), then use [RPC Commands](rpc-commands.md) and [JSON Event Stream](json.md) as the wire references.
+
+## Fork and rebrand Pi
+
+A source fork can change the CLI name and configuration directory through `package.json`:
+
+```json
+{
+  "piConfig": {
+    "name": "my-agent",
+    "configDir": ".my-agent"
+  }
+}
+```
+
+Change the top-level `bin` field to set the executable name. These settings affect the CLI banner, configuration paths, and derived environment variable names.
+
+## Examples and references
+
+- [RPC client](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/examples/rpc-client.ts): typed Node.js integration
+- [RPC extension UI](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/examples/rpc-extension-ui.ts): custom terminal client with extension dialogs
+- [Command Line](cli.md): startup options and mode selection
+- [JSON Event Stream](json.md): JSON event reference
+- [RPC Protocol](rpc.md): RPC lifecycle, framing, errors, and shutdown
+- [RPC Commands](rpc-commands.md): command and response reference
+- [RPC Extension UI](rpc-extension-ui.md): extension interaction subprotocol
+- [SDK examples](https://github.com/earendil-works/pi/blob/b78e6a9085343ec0f308c3d377da72528b4cf7ee/packages/coding-agent/examples/sdk): in-process TypeScript integrations