@north-light/crouter 0.3.333 → 0.3.335

package/dist/builtin-memory/crouter-plugin/README.md

@@ -11,12 +11,12 @@ when-and-why-to-read: When you need Plugin overview, this knowledge should be
 
 Start with the `node_modules/@north-light/crouter-plugin/README.md` for a complete plugin that a developer can paste into an empty file. Then read the page that matches the work at hand:
 
-- [Getting started](getting-started.md) — the deployment and install sequence.
-- [Commands](commands.md) — command trees and descriptions that let an agent choose a command.
-- [Parameters and handler input](parameters.md) — every `param.*` builder and the inferred handler input type.
-- [Output](output.md) — every `field.*` builder and handler result validation.
-- [Errors and streaming](errors.md) — `LeafError`, HTTP errors, and NDJSON streaming leaves.
-- [Deployment](deploying.md) — Fetch frameworks, mount paths, proxies, authentication, and archive compression.
-- [Bundles and memory docs](bundles-and-memory.md) — generating an archive and shipping memory docs.
+- [[crouter-plugin/getting-started]] — the deployment and install sequence.
+- [[crouter-plugin/commands]] — command trees and descriptions that let an agent choose a command.
+- [[crouter-plugin/parameters]] — every `param.*` builder and the inferred handler input type.
+- [[crouter-plugin/output]] — every `field.*` builder and handler result validation.
+- [[crouter-plugin/errors]] — `LeafError`, HTTP errors, and NDJSON streaming leaves.
+- [[crouter-plugin/deploying]] — Fetch frameworks, mount paths, proxies, authentication, and archive compression.
+- [[crouter-plugin/bundles-and-memory]] — generating an archive and shipping memory docs.
 
 The package exports only `LeafError`, `ManifestInvalidError`, `PluginDefinitionError`, `buildBundle`, `buildCommandManifest`, `createFetchHandler`, `defineBranch`, `defineLeaf`, `definePlugin`, `defineStreamingLeaf`, `field`, `kebab`, and `param`. Those are the complete authoring surface.

package/dist/builtin-memory/crouter-plugin/commands.md

@@ -13,6 +13,6 @@ when-and-why-to-read: When you need Commands, this knowledge should be read
 
 Use `defineBranch` to group commands and give it `children`. Use `defineLeaf` for a request that returns one object. A leaf requires `params`, `output`, `effects`, and `handler`; `params` may be omitted when the command has no input. `effects` is a non-empty list shown to the agent. Say whether a command mutates an application, creates billable resources, or is read-only.
 
-`defineStreamingLeaf` has the same declaration shape, but its handler returns `AsyncIterable<object>`. It marks the generated REST mapping as streaming and is covered in [Errors and streaming](errors.md).
+`defineStreamingLeaf` has the same declaration shape, but its handler returns `AsyncIterable<object>`. It marks the generated REST mapping as streaming and is covered in [[crouter-plugin/errors]].
 
 All command and parameter keys are derived into the manifest. Do not add a route path, HTTP method, REST mapping, or separate manifest to a command definition. The package always generates `POST` with all parameters in the JSON body.

package/dist/builtin-memory/crouter-plugin/deploying.md

@@ -27,4 +27,4 @@ Pass `token` to require `Authorization: Bearer <token>` on archive and command r
 
 The install response is an uncompressed tar with `Content-Type: application/x-tar`. Do not configure a proxy, CDN, or framework middleware to gzip or otherwise compress it. Crtr rejects compressed archive bytes. The handler sends an ETag and supports conditional `If-None-Match` requests automatically.
 
-A non-streaming successful command response is a bare JSON result object. Error responses are JSON error envelopes on non-2xx statuses. See [Errors and streaming](errors.md) for the exact error shape.
+A non-streaming successful command response is a bare JSON result object. Error responses are JSON error envelopes on non-2xx statuses. See [[crouter-plugin/errors]] for the exact error shape.

package/dist/builtin-memory/crouter-plugin/getting-started.md

@@ -22,4 +22,4 @@ The endpoint receives `GET` to provide the install archive and `POST` to run a c
 
 Run `crtr pkg plugin show acme` after installation to inspect the installed command tree, and `crtr sys doctor` to check the installed package. A plugin name collision with crtr or another installed plugin is determined during installation and cannot be predicted from an application repository alone.
 
-Continue with [deployment](deploying.md) before mounting the handler below the origin root or behind a proxy.
+Continue with [[crouter-plugin/deploying]] before mounting the handler below the origin root or behind a proxy.

package/dist/builtin-memory/crouter-sdk/guides/README.md

@@ -0,0 +1,19 @@
+---
+kind: knowledge
+when-and-why-to-read: When composing crouter SDK namespaces into an application,
+  read this because it helps you choose a complete runnable starting point.
+---
+
+# SDK recipes
+
+These recipes turn the SDK namespaces into complete applications: a bounded extraction, an assistant that waits for events, a research pipeline, a human approval step, and application-owned memory.
+
+| Recipe | Use it when | It ends with |
+|---|---|---|
+| [[crouter-sdk/guides/typed-extraction]] | You need one structured answer and no follow-up. | A typed object or an explicit failure. |
+| [[crouter-sdk/guides/event-driven-assistant]] | Events arrive over time from a webhook, queue, or watcher. | A resident node that wakes for each event. |
+| [[crouter-sdk/guides/fan-out-pipeline]] | One task needs independent research before a synthesis. | An orchestrator's final report. |
+| [[crouter-sdk/guides/human-approval]] | A person must decide before work continues. | A node resumed by an inbox answer. |
+| [[crouter-sdk/guides/app-memory]] | Several runs need the same durable application knowledge. | A profile-owned document read by a scoped run. |
+
+Start with typed extraction for a request/response job. Use a resident node when the same assistant should react again later. Use an orchestrator only when child work can proceed independently; otherwise keep the composition in your application.

package/dist/builtin-memory/crouter-sdk/guides/app-memory.md

@@ -0,0 +1,73 @@
+---
+kind: knowledge
+when-and-why-to-read: When an application's agents need shared durable
+  knowledge, read this because a profile store gives runs one owned memory
+  location and scopes can allow reading without writing.
+---
+
+# Application memory
+
+Use this recipe when several runs need the same application guidance. Run `npx tsx examples/guides/app-memory.ts /path/to/repo`; it ensures a profile, creates a profile-owned knowledge document if it does not already exist, then starts a run allowed to read but not write memory.
+
+```ts
+import Crouter, { NotFoundError } from '@north-light/crouter-sdk';
+import { resolve } from 'node:path';
+import { z } from 'zod';
+
+const client = new Crouter();
+const cwd = resolve(process.argv[2] ?? process.cwd());
+const profileName = process.env.APP_PROFILE ?? 'release-notes-app';
+
+const profile = await client.profiles.ensure(profileName, {
+  projects: [{ path: cwd, memory: 'content' }],
+});
+
+try {
+  await client.memory.retrieve('release/voice', { profile: profile.id, store: 'profile' });
+} catch (error) {
+  if (!(error instanceof NotFoundError)) throw error;
+  await client.memory.create({
+    name: 'release/voice',
+    kind: 'knowledge',
+    when_and_why_to_read: 'When writing release notes, read this because it defines the product voice and terms customers recognize.',
+    body: 'Use short factual sentences. Name the user-visible result before implementation details.',
+    frontmatter: { surfaces: ['{"on":"boot","at":"preview"}'] },
+    profile: profile.id,
+    store: 'profile',
+  });
+}
+
+const result = await client.nodes.parse({
+  cwd,
+  model: process.env.GUIDE_MODEL,
+  profile: profile.id,
+  root: true,
+  root_lifecycle: 'terminal',
+  deadline: '5m',
+  scopes: ['memory:read'],
+  prompt: 'Write one short release note announcing that customers can download invoices as CSV from account settings. Do not write or update memory.',
+  output_schema: z.object({ release_note: z.string() }),
+});
+
+if (result.kind === 'result') {
+  console.log(result.output_parsed.release_note);
+} else if (result.reason === 'declined') {
+  console.error(`agent declined: ${result.declined?.reason ?? 'no reason supplied'}`);
+  process.exitCode = 2;
+} else {
+  console.error(`agent failed: ${result.reason}`, result.detail);
+  process.exitCode = 1;
+}
+```
+
+A profile is the application's durable identity: it names the memory store and the projects whose context the profile can reach. The routing line is part of the document, not decoration. State both the moment the agent should read it and the reason it matters; a document with a vague routing line will not surface when the agent needs it.
+
+The `boot`/`preview` surface exposes the document's routing line when this profile's agent starts. The task asks for a release note without naming `release/voice`; in the local run the agent read that document before producing the note. Without a surface entry, a memory document appears only in its directory listing and its routing line cannot select it at boot. The run passes `scopes: ['memory:read']`. That is an allow-list: node-targeted memory reads are allowed and writes are refused because `memory:write` is absent. The application itself is not narrowed by those node scopes, so keep application credentials and its memory mutation policy separate from the agent's capabilities.
+
+Observed against the local daemon with `APP_PROFILE=release-notes-app-guide-boot-preview GUIDE_MODEL=openai-codex/gpt-6-sol:high`:
+
+```text
+You can now download your invoices as a CSV from account settings.
+```
+
+Use profile memory for knowledge shared across the application's related projects. Put facts that belong to one repository in project memory instead, and temporary run notes in node memory. See [[crouter-concepts/memory]] for the ownership tiers and [[crouter-concepts/profiles-kinds-and-modes]] for what a profile changes.

package/dist/builtin-memory/crouter-sdk/guides/event-driven-assistant.md

@@ -0,0 +1,91 @@
+---
+kind: knowledge
+when-and-why-to-read: When an assistant must react to later webhook, queue, or
+  file-watcher events, read this because a resident node sleeps until
+  nodes.message delivers the next event.
+---
+
+# Event-driven assistant
+
+Use this recipe for an assistant that reacts to an event source instead of ending after one request. Run `npx tsx examples/guides/event-driven-assistant.ts /path/to/repo`, then type events into standard input to stand in for a webhook handler or file watcher.
+
+```ts
+import Crouter from '@north-light/crouter-sdk';
+import { resolve } from 'node:path';
+import { createInterface } from 'node:readline';
+
+const client = new Crouter();
+const cwd = resolve(process.argv[2] ?? process.cwd());
+
+const assistant = await client.nodes.create({
+  name: 'event assistant',
+  cwd,
+  model: process.env.GUIDE_MODEL,
+  root: true,
+  root_lifecycle: 'resident',
+  no_kickoff: true,
+  situational_context: `You are a standing assistant. Each inbox message is an event from an external source. For each event, briefly state what happened and one useful next action, then push that response as an update report with crtr push update. Do not push final. End the turn and go dormant after reporting. Do not poll or schedule a timer: another event will arrive as a message.`,
+});
+
+console.log(`assistant node: ${assistant.node_id}`);
+console.log('Type an event and press Enter. Press Ctrl-C to stop the assistant.');
+
+const input = createInterface({ input: process.stdin, crlfDelay: Infinity });
+let stopping: Promise<void> | undefined;
+
+function stop(): Promise<void> {
+  if (stopping !== undefined) return stopping;
+  input.close();
+  stopping = client.nodes.cancel(assistant.node_id).then(() => undefined);
+  return stopping;
+}
+
+process.once('SIGINT', () => {
+  void stop().catch((error: unknown) => {
+    console.error(error);
+    process.exitCode = 1;
+  });
+});
+
+for await (const line of input) {
+  if (stopping !== undefined) break;
+  if (line.trim() === '') continue;
+  try {
+    const previous = (await client.nodes.reports.list(assistant.node_id, { limit: 1 }))[0]?.path;
+    if (stopping !== undefined) break;
+    await client.nodes.message(assistant.node_id, { body: line });
+    while (stopping === undefined) {
+      const report = (await client.nodes.reports.list(assistant.node_id, { limit: 1 }))[0];
+      if (stopping !== undefined) break;
+      if (report !== undefined && report.path !== previous) {
+        console.log(report.body);
+        break;
+      }
+      const state = await client.nodes.retrieve(assistant.node_id);
+      if (stopping !== undefined) break;
+      if (state.fault?.retry.disposition === 'fatal' || state.status === 'dead' || state.status === 'canceled') {
+        throw new Error(`assistant stopped without reporting: ${state.fault?.message ?? state.status}`);
+      }
+      await new Promise((resolve) => setTimeout(resolve, 1000));
+    }
+  } catch (error) {
+    if (stopping === undefined) throw error;
+  }
+}
+
+await stop();
+```
+
+The external source owns detection. When it receives an event, it calls `nodes.message(nodeId, { body })`. `no_kickoff` leaves the resident node waiting for the first event, while `situational_context` tells it how to handle every event. A dormant resident node wakes for the message; a running node reads it at its next turn boundary. Keep the returned node id with the application so each later event reaches the same context and memory. The agent pushes one update report per event, which the application reads through `nodes.reports.list` and prints. The application checks for a fatal node fault rather than waiting forever for a report that cannot arrive.
+
+The agent does not poll or schedule a timer: the daemon wakes it on each message, and it goes dormant after reporting. This console program polls for the report associated with the event it just sent; an application with its own event loop can also consume the node's event stream. Ctrl-C calls `nodes.cancel()` only because this interactive example needs an explicit way to stop.
+
+Observed against the local daemon with `GUIDE_MODEL=openai-codex/gpt-6-sol:high` after sending `Build completed with 2 failing checks: lint and unit tests.`:
+
+```text
+assistant node: 3zl47w7d-mud5amcx-67978c9b
+Type an event and press Enter. Press Ctrl-C to stop the assistant.
+The build completed, but **lint and unit tests failed**. Inspect the two failing check logs first to identify the errors.
+```
+
+Use a resident node only when future events belong to the same ongoing assistant. For bounded work, use [[crouter-sdk/guides/typed-extraction]]. See [[crouter-concepts/lifecycle-and-wakes]] for why waiting is free and [[crouter-concepts/why-a-daemon]] for why the process can outlive the terminal that started it.

package/dist/builtin-memory/crouter-sdk/guides/fan-out-pipeline.md

@@ -0,0 +1,57 @@
+---
+kind: knowledge
+when-and-why-to-read: When independent parts of one job need separate agent work
+  before one synthesis, read this because an orchestrator can spawn children,
+  wait for reports, and publish a final result while the SDK streams progress.
+---
+
+# Fan-out pipeline
+
+Use this recipe when one result needs independent investigation first. Run `npx tsx examples/guides/fan-out-pipeline.ts /path/to/repo`; it asks an orchestrator to inspect a package through two children, prints live text and pushed reports, then prints the final reports retained on the node.
+
+```ts
+import Crouter from '@north-light/crouter-sdk';
+import { resolve } from 'node:path';
+
+const client = new Crouter();
+const cwd = resolve(process.argv[2] ?? process.cwd());
+
+const stream = client.nodes.stream({
+  name: 'research pipeline',
+  cwd,
+  root: true,
+  root_lifecycle: 'terminal',
+  mode: 'orchestrator',
+  deadline: '10m',
+  prompt: `Research the package in this directory. Spawn two focused children: one should inspect package.json and one should inspect the README. Wait for their reports, reconcile them, then push a final report with the package name, purpose, and one risk or unknown.`,
+});
+
+const node = await stream.node;
+console.log(`orchestrator node: ${node.node_id}`);
+
+for await (const event of stream) {
+  if (event.type === 'node.output_text.delta') process.stdout.write(event.delta);
+  if (event.type === 'node.report.pushed') console.log(`\nreport: ${event.report.body}`);
+}
+
+const outcome = await stream.finalOutcome();
+const reports = await client.nodes.reports.list(node.node_id, { limit: 10 });
+console.log(`\nfinal outcome: ${outcome.kind}`);
+for (const report of reports) console.log(`[${report.tier}] ${report.body}`);
+
+if (outcome.kind !== 'result') process.exitCode = 1;
+```
+
+`nodes.stream()` creates the orchestrator and observes it. It does not run the orchestration in your process: the node owns its children, waits for their pushed reports, and produces the synthesis. The stream gives your application live output and reports; `nodes.reports.list()` gives it the durable report view after settlement.
+
+Keep orchestration inside the canvas when children need the canvas's report delivery, durable waits, and a parent that can be inspected or resumed. Keep it in your application when tasks are simple independent calls and the application already owns their scheduling and aggregation. Do not use an orchestrator merely because a task is long; it earns the extra structure only when child work can run independently.
+
+A local run created `j6amiqxs-mud4drnk-330da196`; after its two children reported, `waitForOutcome()` returned:
+
+```text
+{ "kind": "result", "reason": "finalized" }
+```
+
+The same run's `nodes.stream()` observer ended during a dormant gap before it could print this outcome. A separate daemon fix is correcting that observer behavior; the example remains the intended streamed shape, but its streamed path has not yet been observed end to end.
+
+See [[crouter-concepts/nodes-and-the-canvas]] for reports and durable identities, and [[crouter-concepts/profiles-kinds-and-modes]] for the base-versus-orchestrator decision.

package/dist/builtin-memory/crouter-sdk/guides/human-approval.md

@@ -0,0 +1,79 @@
+---
+kind: knowledge
+when-and-why-to-read: When a person must approve or reject work before an agent
+  continues, read this because the SDK can create an inbox request whose answer
+  wakes the requesting node.
+---
+
+# Human approval
+
+Use this recipe when a decision belongs to a person, not a timeout or an agent guess. Run `npx tsx examples/guides/human-approval.ts /path/to/repo`; it prints an inbox ticket id. Answer the page in the crtr human inbox and the worker wakes with that answer before it reports its result.
+
+```ts
+import Crouter from '@north-light/crouter-sdk';
+import { resolve } from 'node:path';
+
+const client = new Crouter();
+const cwd = resolve(process.argv[2] ?? process.cwd());
+
+const worker = await client.nodes.create({
+  name: 'approval worker',
+  cwd,
+  root: true,
+  root_lifecycle: 'terminal',
+  no_kickoff: true,
+});
+
+const request = await client.human.requests.create({
+  creator_cwd: cwd,
+  requester_node_id: worker.node_id,
+  delivery: { placement: 'panel', inbox: true, reply: true },
+  page: {
+    dialect: 'jsx',
+    source: `export default function Approval() {
+  return (
+    <Page title="Approve the release?" subtitle="The worker will continue with your choice.">
+      <UserQuestion
+        id="approval"
+        label="Release action"
+        body="Approve to continue the release, or reject to stop it."
+        mode="single"
+        options={[
+          { id: 'approve', label: 'Approve', recommended: true },
+          { id: 'reject', label: 'Reject' },
+        ]}
+      />
+    </Page>
+  );
+}`,
+  },
+});
+
+const ticket = await client.human.requests.retrieve(request.request_id);
+if (ticket.inbox_ticket_id === null) throw new Error('the approval request was not added to the inbox');
+
+await client.nodes.message(worker.node_id, {
+  body: `A human approval request is open. Wait for its reply. When it arrives, state whether the release was approved or rejected, then push a final report.`,
+});
+
+console.log(`approval ticket: ${ticket.inbox_ticket_id}`);
+console.log('Answer it in the crtr human inbox. The worker will wake with the response.');
+
+const outcome = await client.nodes.waitForOutcome(worker.node_id);
+console.log(`worker outcome: ${outcome.kind}`);
+if (outcome.kind !== 'result') process.exitCode = 1;
+```
+
+The application creates the page through `client.human.requests.create()` and names the worker as `requester_node_id`. `delivery.reply: true` makes the settled answer travel back to that node. The page's `UserQuestion` supplies a known response shape, so the person sees an explicit approve or reject decision instead of an unstructured prompt.
+
+The worker is terminal because this is a bounded approval run: it waits after setup, wakes when the person answers, then publishes its final result. The pending human request keeps that wait durable. The application does not poll the node or invent a fallback deadline; the human reply is a canvas event. `client.human.inbox` can list, inspect, and answer inbox tickets when your application provides its own human interface.
+
+Observed against the local daemon after an approve response:
+
+```text
+approval ticket: a643479ca7a79758bf86f32d24bd8c9b22e16509cd60996c5e4fe0bc5f097d45
+Answer it in the crtr human inbox. The worker will wake with the response.
+worker outcome: result
+```
+
+See [[crouter-concepts/lifecycle-and-wakes]] for the wake model and [[crouter-concepts/scopes-and-trust]] for why the daemon, rather than the application, owns delivery of the answer.

package/dist/builtin-memory/crouter-sdk/guides/typed-extraction.md

@@ -0,0 +1,53 @@
+---
+kind: knowledge
+when-and-why-to-read: When an application needs one bounded structured answer
+  with no follow-up, read this because nodes.parse returns a typed outcome union
+  instead of hiding agent failures.
+---
+
+# Typed extraction
+
+Use this recipe to extract a small fact set from files in one working directory. Run it with `npx tsx examples/guides/typed-extraction.ts /path/to/repo`; it prints a package name and version or exits with an explicit agent outcome.
+
+```ts
+import Crouter from '@north-light/crouter-sdk';
+import { resolve } from 'node:path';
+import { z } from 'zod';
+
+const client = new Crouter();
+const cwd = resolve(process.argv[2] ?? process.cwd());
+
+const extraction = await client.nodes.parse({
+  prompt: 'Read package.json in this directory. Return its name and version.',
+  cwd,
+  root: true,
+  root_lifecycle: 'terminal',
+  deadline: '5m',
+  output_schema: z.object({
+    name: z.string(),
+    version: z.string(),
+  }),
+});
+
+if (extraction.kind === 'result') {
+  console.log(`package ${extraction.output_parsed.name}@${extraction.output_parsed.version}`);
+} else if (extraction.reason === 'declined') {
+  console.error(`agent declined: ${extraction.declined?.reason ?? 'no reason supplied'}`);
+  process.exitCode = 2;
+} else {
+  console.error(`agent failed: ${extraction.reason}`, extraction.detail);
+  process.exitCode = 1;
+}
+```
+
+`nodes.parse()` creates a terminal root, waits for it, and returns the structured result typed from the Zod schema. The schema belongs at the boundary where your application consumes the answer, not in a second parser after the run.
+
+Observed against the local daemon in this checkout:
+
+```text
+package @north-light/crouter@0.3.332
+```
+
+Handle every outcome arm. A result contains `output_parsed`; a decline says the agent could not honestly meet the schema; another failure carries its reason and detail. Transport and daemon failures still throw, so let those reach your normal application error handling.
+
+This is the right shape for bounded work: one prompt, one answer, and no future message. If a user or external event must return to the same agent later, use a resident node instead. See [[crouter-concepts/nodes-and-the-canvas]] for why an SDK node has durable identity, and [[crouter-concepts/lifecycle-and-wakes]] for the terminal-versus-resident decision.

package/dist/daemon/api/handlers/node-events.js

@@ -1,6 +1,6 @@
-var O=Object.defineProperty;var o=(n,e)=>O(n,"name",{value:e,configurable:!0});import{randomUUID as q}from"node:crypto";import{ApiError as E}from"../../../api/errors.js";import{BrokerClient as C}from"../../../core/broker-client/client.js";import{getNode as b}from"../../../core/canvas/canvas.js";import{isPidAlive as B}from"../../../core/canvas/pid.js";import{BROKER_VIEW_SOCKET_WAIT_MS as k}from"../../../core/runtime/view-socket.js";import{toNodeOutcomeDTO as M}from"../map.js";import{reportsForNode as L}from"./reports.js";const D=15e3,$=6e4,x=250,P=512,T=256*1024,j=1e3,G=32*1024*1024;class V{static{o(this,"NodeEventRing")}events=[];bytes=0;nextSequence=1;earliestAvailable=1;append(e){const t={...e,sequence_number:this.nextSequence++},s=Buffer.byteLength(JSON.stringify(t),"utf8");if(s>T)return this.events=[],this.bytes=0,this.earliestAvailable=this.nextSequence,t;for(this.events.push(t),this.bytes+=s;this.events.length>P||this.bytes>T;){const r=this.events.shift();if(r===void 0)break;this.bytes-=Buffer.byteLength(JSON.stringify(r),"utf8"),this.earliestAvailable=r.sequence_number+1}return t}replay(e){if(e===void 0)return{gap:null,events:this.events};const t=e<this.earliestAvailable-1||e>=this.nextSequence?A(this.earliestAvailable):null;return{gap:t,events:t===null?this.events.filter(s=>s.sequence_number>e):this.events}}get empty(){return this.events.length===0}}function A(n){return{type:"error",error:{code:"stream_gap",message:"the requested event cursor is older than this daemon can resume",details:{earliest_sequence:n}}}}o(A,"streamGap");function H(n){return n===null?"arguments: null":Array.isArray(n)?`arguments: array (${n.length} items)`:typeof n=="object"?`arguments: object (${Object.keys(n).length} fields)`:`arguments: ${typeof n}`}o(H,"toolSummary");function m(n){if(typeof n!="object"||n===null)return"";const e=n.content;return typeof e=="string"?e:Array.isArray(e)?e.filter(t=>typeof t=="object"&&t!==null).filter(t=>t.type==="text"&&typeof t.text=="string").map(t=>t.text).join(""):""}o(m,"assistantText");class w{static{o(this,"NodeEventTranslationState")}toolSummaries=new Map;emittedAssistantText="";resetAssistantText(){this.emittedAssistantText=""}emitAssistantTextDelta(e){const t=m(e),s=t.startsWith(this.emittedAssistantText)?t.slice(this.emittedAssistantText.length):t;return this.emittedAssistantText=t,s}seedAssistantText(e){const t=m(e);return this.emittedAssistantText=t,t}}function z(n,e,t=new w){switch(e.type){case"message_start":return e.message.role==="assistant"&&t.resetAssistantText(),[];case"message_update":{if(e.message.role!=="assistant")return[];const s=t.emitAssistantTextDelta(e.message);return s===""?[]:[{type:"node.output_text.delta",node_id:n,delta:s}]}case"message_end":{if(e.message.role!=="assistant")return[];const s=m(e.message);return t.resetAssistantText(),[{type:"node.output_text.done",node_id:n,text:s}]}case"tool_execution_start":{const s=H(e.args);return t.toolSummaries.set(e.toolCallId,s),[{type:"node.tool_call.started",node_id:n,tool_call_id:e.toolCallId,tool:e.toolName,summary:s}]}case"tool_execution_end":{const s=t.toolSummaries.get(e.toolCallId)??"[arguments unavailable]";return t.toolSummaries.delete(e.toolCallId),[{type:"node.tool_call.completed",node_id:n,tool_call_id:e.toolCallId,tool:e.toolName,status:e.isError?"error":"ok",summary:s}]}case"turn_start":return[{type:"node.turn.started",node_id:n}];case"turn_end":return[{type:"node.turn.completed",node_id:n}];default:return[]}}o(z,"translateBrokerFrame");class J{static{o(this,"NodeEventHub")}nodeId;remove;ring=new V;subscribers=new Set;observer;observerErrorAt;poll;reconnect;idleClose;status;settledRevision;settledOutcome;settledSequence;snapshotSeeded=!1;reportsSeeded=!1;translationState=new w;fresh=!0;constructor(e,t){this.nodeId=e,this.remove=t}subscribe(e,t){const s=this.fresh&&e!==void 0;this.fresh=!1,this.start();const r=this.settledOutcome!==void 0,d=s?{gap:A(1),events:this.ring.replay(void 0).events}:this.ring.replay(e);r||(this.subscribers.add(t),this.status!=="dormant"&&this.openObserver());let h=!1;return queueMicrotask(()=>{if(!h){d.gap!==null&&t(d.gap);for(const l of d.events)t(l)}}),r&&this.scheduleIdleClose(),{unsubscribe:o(()=>{h=!0,r||this.unsubscribe(t)},"unsubscribe"),terminal:r}}report(e){this.settledRevision===void 0&&this.publish({type:"node.report.pushed",node_id:this.nodeId,report:e})}start(){this.idleClose!==void 0&&(clearTimeout(this.idleClose),this.idleClose=void 0),this.poll===void 0&&(this.check(),this.settledRevision===void 0&&(this.seedReports(),this.poll=setInterval(()=>this.check(),x)))}seedReports(){if(!this.reportsSeeded){this.reportsSeeded=!0;for(const e of L(this.nodeId).reverse())this.report(e)}}check(){const e=b(this.nodeId);if(e===null){this.fail("stream_error",`node ${this.nodeId} no longer exists`);return}const t=M(e);if(t!==null){this.settledRevision!==t.revision&&(this.settledRevision=t.revision,this.settledOutcome=t,this.settledSequence=this.publish({type:"node.settled",node_id:this.nodeId,outcome:t}).sequence_number,this.stopObserver(),this.stopPoll());return}const s=e.pi_pid===null?"dormant":e.status;if(s==="dormant"){this.status!=="dormant"&&(this.status=s,this.publish({type:"node.status.changed",node_id:this.nodeId,status:s}));return}this.status===void 0?this.status=s:this.status!=="dormant"&&this.status!==s&&(this.status=s,this.publish({type:"node.status.changed",node_id:this.nodeId,status:s})),this.openObserver()}openObserver(){if(this.observer!==void 0||this.subscribers.size===0)return;const e=new C(this.nodeId);this.observer=e,e.on("connect",()=>{this.observerErrorAt=void 0;const t=b(this.nodeId);this.status==="dormant"&&t!==null&&t.pi_pid!==null&&(this.status=t.status,this.publish({type:"node.status.changed",node_id:this.nodeId,status:t.status})),e.send({type:"hello",role:"observer",client_id:q(),attends:!1})}),e.on("frame",t=>{try{t.type==="welcome"&&this.seedSnapshot(t.snapshot);for(const s of z(this.nodeId,t,this.translationState))this.publish(s)}catch(s){this.fail("stream_error",s instanceof Error?s.message:String(s))}}),e.on("error",()=>{const t=b(this.nodeId),s=Date.now();t!==null&&t.pi_pid!==null&&B(t.pi_pid)&&(this.observerErrorAt??=s,s-this.observerErrorAt<k)||this.fail("stream_error","observer connection failed")}),e.on("close",()=>{this.observer===e&&(this.observer=void 0,!(this.subscribers.size===0||this.settledRevision!==void 0)&&(this.status!=="dormant"&&(this.publish({type:"node.status.changed",node_id:this.nodeId,status:"dormant"}),this.status="dormant"),this.scheduleReconnect()))}),e.connect()}seedSnapshot(e){if(this.snapshotSeeded)return;this.snapshotSeeded=!0;const t=e.messages.filter(r=>r.role==="assistant"),s=e.state.isStreaming?t.pop():void 0;for(const r of t)this.publish({type:"node.output_text.done",node_id:this.nodeId,text:m(r)});s!==void 0&&this.publish({type:"node.output_text.delta",node_id:this.nodeId,delta:this.translationState.seedAssistantText(s)})}scheduleReconnect(){this.reconnect===void 0&&(this.reconnect=setTimeout(()=>{this.reconnect=void 0,this.check()},x))}publish(e){const t=this.ring.append(e);for(const s of[...this.subscribers])s(t);return t}fail(e,t){const s={type:"error",error:{code:e,message:t}};for(const r of[...this.subscribers])r(s);this.stopObserver(),this.stopPoll()}unsubscribe(e){this.subscribers.delete(e),this.subscribers.size===0&&this.scheduleIdleClose()}scheduleIdleClose(){this.idleClose===void 0&&(this.idleClose=setTimeout(()=>{this.stopObserver(),this.stopPoll(),this.remove()},$))}stopObserver(){this.reconnect!==void 0&&(clearTimeout(this.reconnect),this.reconnect=void 0);const e=this.observer;this.observer=void 0,e?.close()}stopPoll(){this.poll!==void 0&&(clearInterval(this.poll),this.poll=void 0)}}class W{static{o(this,"NodeEventStreams")}hubs=new Map;subscribe(e,t,s){let r=this.hubs.get(e);return r===void 0&&(r=new J(e,()=>this.hubs.delete(e)),this.hubs.set(e,r)),r.subscribe(t,s)}report(e,t){this.hubs.get(e)?.report(t)}}const F=new W;function K(n){const e=n.get("after");if(e===null||e==="")return{};if(!/^(?:0|[1-9]\d*)$/.test(e))throw new E(400,"invalid_request","`after` must be a non-negative integer");const t=Number(e);if(!Number.isSafeInteger(t))throw new E(400,"invalid_request","`after` must be a safe integer");return{after:t}}o(K,"parseQuery");function I(n){const{type:e,...t}=n;return`event: ${e}
+var O=Object.defineProperty;var o=(n,e)=>O(n,"name",{value:e,configurable:!0});import{randomUUID as q}from"node:crypto";import{ApiError as E}from"../../../api/errors.js";import{BrokerClient as C}from"../../../core/broker-client/client.js";import{getNode as b}from"../../../core/canvas/canvas.js";import{isPidAlive as B}from"../../../core/canvas/pid.js";import{BROKER_VIEW_SOCKET_WAIT_MS as k}from"../../../core/runtime/view-socket.js";import{toNodeOutcomeDTO as M}from"../map.js";import{reportsForNode as L}from"./reports.js";const D=15e3,$=6e4,x=250,P=512,T=256*1024,j=1e3,G=32*1024*1024;class V{static{o(this,"NodeEventRing")}events=[];bytes=0;nextSequence=1;earliestAvailable=1;append(e){const t={...e,sequence_number:this.nextSequence++},s=Buffer.byteLength(JSON.stringify(t),"utf8");if(s>T)return this.events=[],this.bytes=0,this.earliestAvailable=this.nextSequence,t;for(this.events.push(t),this.bytes+=s;this.events.length>P||this.bytes>T;){const r=this.events.shift();if(r===void 0)break;this.bytes-=Buffer.byteLength(JSON.stringify(r),"utf8"),this.earliestAvailable=r.sequence_number+1}return t}replay(e){if(e===void 0)return{gap:null,events:this.events};const t=e<this.earliestAvailable-1||e>=this.nextSequence?A(this.earliestAvailable):null;return{gap:t,events:t===null?this.events.filter(s=>s.sequence_number>e):this.events}}get empty(){return this.events.length===0}}function A(n){return{type:"error",error:{code:"stream_gap",message:"the requested event cursor is older than this daemon can resume",details:{earliest_sequence:n}}}}o(A,"streamGap");function H(n){return n===null?"arguments: null":Array.isArray(n)?`arguments: array (${n.length} items)`:typeof n=="object"?`arguments: object (${Object.keys(n).length} fields)`:`arguments: ${typeof n}`}o(H,"toolSummary");function m(n){if(typeof n!="object"||n===null)return"";const e=n.content;return typeof e=="string"?e:Array.isArray(e)?e.filter(t=>typeof t=="object"&&t!==null).filter(t=>t.type==="text"&&typeof t.text=="string").map(t=>t.text).join(""):""}o(m,"assistantText");class w{static{o(this,"NodeEventTranslationState")}toolSummaries=new Map;emittedAssistantText="";resetAssistantText(){this.emittedAssistantText=""}emitAssistantTextDelta(e){const t=m(e),s=t.startsWith(this.emittedAssistantText)?t.slice(this.emittedAssistantText.length):t;return this.emittedAssistantText=t,s}seedAssistantText(e){const t=m(e);return this.emittedAssistantText=t,t}}function z(n,e,t=new w){switch(e.type){case"message_start":return e.message.role==="assistant"&&t.resetAssistantText(),[];case"message_update":{if(e.message.role!=="assistant")return[];const s=t.emitAssistantTextDelta(e.message);return s===""?[]:[{type:"node.output_text.delta",node_id:n,delta:s}]}case"message_end":{if(e.message.role!=="assistant")return[];const s=m(e.message);return t.resetAssistantText(),[{type:"node.output_text.done",node_id:n,text:s}]}case"tool_execution_start":{const s=H(e.args);return t.toolSummaries.set(e.toolCallId,s),[{type:"node.tool_call.started",node_id:n,tool_call_id:e.toolCallId,tool:e.toolName,summary:s}]}case"tool_execution_end":{const s=t.toolSummaries.get(e.toolCallId)??"[arguments unavailable]";return t.toolSummaries.delete(e.toolCallId),[{type:"node.tool_call.completed",node_id:n,tool_call_id:e.toolCallId,tool:e.toolName,status:e.isError?"error":"ok",summary:s}]}case"turn_start":return[{type:"node.turn.started",node_id:n}];case"turn_end":return[{type:"node.turn.completed",node_id:n}];default:return[]}}o(z,"translateBrokerFrame");class J{static{o(this,"NodeEventHub")}nodeId;remove;ring=new V;subscribers=new Set;observer;observerErrorAt;poll;reconnect;idleClose;status;settledRevision;settledOutcome;settledSequence;snapshotSeeded=!1;reportsSeeded=!1;translationState=new w;fresh=!0;constructor(e,t){this.nodeId=e,this.remove=t}subscribe(e,t){const s=this.fresh&&e!==void 0;this.fresh=!1,this.start();const r=this.settledOutcome!==void 0,d=s?{gap:A(1),events:this.ring.replay(void 0).events}:this.ring.replay(e);r||(this.subscribers.add(t),this.status!=="dormant"&&this.openObserver());let h=!1;return queueMicrotask(()=>{if(!h){d.gap!==null&&t(d.gap);for(const l of d.events)t(l)}}),r&&this.scheduleIdleClose(),{unsubscribe:o(()=>{h=!0,r||this.unsubscribe(t)},"unsubscribe"),terminal:r}}report(e){this.settledRevision===void 0&&this.publish({type:"node.report.pushed",node_id:this.nodeId,report:e})}start(){this.idleClose!==void 0&&(clearTimeout(this.idleClose),this.idleClose=void 0),this.poll===void 0&&(this.check(),this.settledRevision===void 0&&(this.seedReports(),this.poll=setInterval(()=>this.check(),x)))}seedReports(){if(!this.reportsSeeded){this.reportsSeeded=!0;for(const e of L(this.nodeId).reverse())this.report(e)}}check(){const e=b(this.nodeId);if(e===null){this.fail("stream_error",`node ${this.nodeId} no longer exists`);return}const t=M(e);if(t!==null){this.settledRevision!==t.revision&&(this.settledRevision=t.revision,this.settledOutcome=t,this.settledSequence=this.publish({type:"node.settled",node_id:this.nodeId,outcome:t}).sequence_number,this.stopObserver(),this.stopPoll());return}const s=e.pi_pid===null?"dormant":e.status;if(s==="dormant"){this.observerErrorAt=void 0,this.status!=="dormant"&&(this.status=s,this.publish({type:"node.status.changed",node_id:this.nodeId,status:s}));return}this.status===void 0?this.status=s:this.status!=="dormant"&&this.status!==s&&(this.status=s,this.publish({type:"node.status.changed",node_id:this.nodeId,status:s})),this.openObserver()}openObserver(){if(this.observer!==void 0||this.subscribers.size===0)return;const e=new C(this.nodeId);this.observer=e,e.on("connect",()=>{this.observerErrorAt=void 0;const t=b(this.nodeId);this.status==="dormant"&&t!==null&&t.pi_pid!==null&&(this.status=t.status,this.publish({type:"node.status.changed",node_id:this.nodeId,status:t.status})),e.send({type:"hello",role:"observer",client_id:q(),attends:!1})}),e.on("frame",t=>{try{t.type==="welcome"&&this.seedSnapshot(t.snapshot);for(const s of z(this.nodeId,t,this.translationState))this.publish(s)}catch(s){this.fail("stream_error",s instanceof Error?s.message:String(s))}}),e.on("error",()=>{const t=b(this.nodeId),s=Date.now();if(t!==null&&t.pi_pid!==null&&B(t.pi_pid)){if(this.observerErrorAt??=s,s-this.observerErrorAt<k)return;this.fail("stream_error","observer connection failed");return}this.observerErrorAt=void 0}),e.on("close",()=>{this.observer===e&&(this.observer=void 0,!(this.subscribers.size===0||this.settledRevision!==void 0)&&(this.status!=="dormant"&&(this.publish({type:"node.status.changed",node_id:this.nodeId,status:"dormant"}),this.status="dormant"),this.scheduleReconnect()))}),e.connect()}seedSnapshot(e){if(this.snapshotSeeded)return;this.snapshotSeeded=!0;const t=e.messages.filter(r=>r.role==="assistant"),s=e.state.isStreaming?t.pop():void 0;for(const r of t)this.publish({type:"node.output_text.done",node_id:this.nodeId,text:m(r)});s!==void 0&&this.publish({type:"node.output_text.delta",node_id:this.nodeId,delta:this.translationState.seedAssistantText(s)})}scheduleReconnect(){this.reconnect===void 0&&(this.reconnect=setTimeout(()=>{this.reconnect=void 0,this.check()},x))}publish(e){const t=this.ring.append(e);for(const s of[...this.subscribers])s(t);return t}fail(e,t){const s={type:"error",error:{code:e,message:t}};for(const r of[...this.subscribers])r(s);this.stopObserver(),this.stopPoll()}unsubscribe(e){this.subscribers.delete(e),this.subscribers.size===0&&this.scheduleIdleClose()}scheduleIdleClose(){this.idleClose===void 0&&(this.idleClose=setTimeout(()=>{this.stopObserver(),this.stopPoll(),this.remove()},$))}stopObserver(){this.reconnect!==void 0&&(clearTimeout(this.reconnect),this.reconnect=void 0);const e=this.observer;this.observer=void 0,e?.close()}stopPoll(){this.poll!==void 0&&(clearInterval(this.poll),this.poll=void 0)}}class W{static{o(this,"NodeEventStreams")}hubs=new Map;subscribe(e,t,s){let r=this.hubs.get(e);return r===void 0&&(r=new J(e,()=>this.hubs.delete(e)),this.hubs.set(e,r)),r.subscribe(t,s)}report(e,t){this.hubs.get(e)?.report(t)}}const F=new W;function K(n){const e=n.get("after");if(e===null||e==="")return{};if(!/^(?:0|[1-9]\d*)$/.test(e))throw new E(400,"invalid_request","`after` must be a non-negative integer");const t=Number(e);if(!Number.isSafeInteger(t))throw new E(400,"invalid_request","`after` must be a safe integer");return{after:t}}o(K,"parseQuery");function I(n){const{type:e,...t}=n;return`event: ${e}
 data: ${JSON.stringify(t)}
 
-`}o(I,"sseRecord");async function U(n){const e=n.params.id??"";if(b(e)===null)throw new E(404,"node_not_found",`no node ${e}`);const{after:t}=K(n.query),{req:s,res:r}=n;r.writeHead(200,{"content-type":"text/event-stream; charset=utf-8","cache-control":"no-cache",connection:"keep-alive"});let d=!1,h=!1,l=!1,c=0;const u=[];let v,f;const _=o(()=>{r.writableEnded||r.end()},"finish"),p=o(()=>{if(!d){if(d=!0,f!==void 0&&clearInterval(f),v?.(),s.destroyed||r.destroyed){u.length=0,c=0,_();return}if(l||u.length>0){h=!0;return}_()}},"close"),g=o(()=>{for(l=!1;u.length>0;){const i=u.shift();if(c-=Buffer.byteLength(i,"utf8"),!r.write(i)){l=!0,r.once("drain",g);return}}h&&_()},"flush"),N=o(()=>{if(d)return;u.length=0,c=0;const i=I({type:"error",error:{code:"stream_dropped",message:"stream reader is too slow"}});u.push(i),c=Buffer.byteLength(i,"utf8"),d=!0,h=!0,f!==void 0&&clearInterval(f),v?.(),l||g()},"dropSlowReader"),y=o(i=>{if(d)return!1;if(l||u.length>0){const a=Buffer.byteLength(i,"utf8");return u.length>=j||c+a>G?(N(),!1):(u.push(i),c+=a,!0)}return r.write(i)||(l=!0,r.once("drain",g)),!0},"write"),S=o((i,a)=>{d||y(I({type:"error",error:{code:i,message:a}})),p()},"fail"),R=o(i=>{try{if(!y(I(i)))return;(i.type==="node.settled"||i.type==="error"&&i.error.code!=="stream_gap")&&p()}catch(a){S("stream_error",a instanceof Error?a.message:String(a))}},"onEvent");f=setInterval(()=>{try{d||y(`: keepalive
+`}o(I,"sseRecord");async function U(n){const e=n.params.id??"";if(b(e)===null)throw new E(404,"node_not_found",`no node ${e}`);const{after:t}=K(n.query),{req:s,res:r}=n;r.writeHead(200,{"content-type":"text/event-stream; charset=utf-8","cache-control":"no-cache",connection:"keep-alive"});let d=!1,h=!1,l=!1,c=0;const u=[];let v,f;const _=o(()=>{r.writableEnded||r.end()},"finish"),p=o(()=>{if(!d){if(d=!0,f!==void 0&&clearInterval(f),v?.(),r.destroyed){u.length=0,c=0,_();return}if(l||u.length>0){h=!0;return}_()}},"close"),g=o(()=>{for(l=!1;u.length>0;){const i=u.shift();if(c-=Buffer.byteLength(i,"utf8"),!r.write(i)){l=!0,r.once("drain",g);return}}h&&_()},"flush"),N=o(()=>{if(d)return;u.length=0,c=0;const i=I({type:"error",error:{code:"stream_dropped",message:"stream reader is too slow"}});u.push(i),c=Buffer.byteLength(i,"utf8"),d=!0,h=!0,f!==void 0&&clearInterval(f),v?.(),l||g()},"dropSlowReader"),y=o(i=>{if(d)return!1;if(l||u.length>0){const a=Buffer.byteLength(i,"utf8");return u.length>=j||c+a>G?(N(),!1):(u.push(i),c+=a,!0)}return r.write(i)||(l=!0,r.once("drain",g)),!0},"write"),S=o((i,a)=>{d||y(I({type:"error",error:{code:i,message:a}})),p()},"fail"),R=o(i=>{try{if(!y(I(i)))return;(i.type==="node.settled"||i.type==="error"&&i.error.code!=="stream_gap")&&p()}catch(a){S("stream_error",a instanceof Error?a.message:String(a))}},"onEvent");f=setInterval(()=>{try{d||y(`: keepalive
 
 `)}catch(i){S("stream_error",i instanceof Error?i.message:String(i))}},D),s.once("close",p);try{const i=F.subscribe(e,t,R);v=i.unsubscribe,i.terminal&&queueMicrotask(p)}catch(i){S("stream_error",i instanceof Error?i.message:String(i))}return{status:200}}o(U,"handleEvents");const ie=[{method:"GET",pattern:"/v1/nodes/:id/events",handler:U}];export{V as NodeEventRing,w as NodeEventTranslationState,ie as nodeEventRoutes,F as nodeEventStreams,z as translateBrokerFrame};

package/docs/sdk/guides/README.md

@@ -0,0 +1,18 @@
+---
+title: SDK recipes
+description: When composing crouter SDK namespaces into an application, read this because it helps you choose a complete runnable starting point.
+---
+
+# SDK recipes
+
+These recipes turn the SDK namespaces into complete applications: a bounded extraction, an assistant that waits for events, a research pipeline, a human approval step, and application-owned memory.
+
+| Recipe | Use it when | It ends with |
+|---|---|---|
+| [Typed extraction](./typed-extraction.md) | You need one structured answer and no follow-up. | A typed object or an explicit failure. |
+| [Event-driven assistant](./event-driven-assistant.md) | Events arrive over time from a webhook, queue, or watcher. | A resident node that wakes for each event. |
+| [Fan-out pipeline](./fan-out-pipeline.md) | One task needs independent research before a synthesis. | An orchestrator's final report. |
+| [Human approval](./human-approval.md) | A person must decide before work continues. | A node resumed by an inbox answer. |
+| [Application memory](./app-memory.md) | Several runs need the same durable application knowledge. | A profile-owned document read by a scoped run. |
+
+Start with typed extraction for a request/response job. Use a resident node when the same assistant should react again later. Use an orchestrator only when child work can proceed independently; otherwise keep the composition in your application.

package/docs/sdk/guides/app-memory.md

@@ -0,0 +1,22 @@
+---
+title: Application memory
+description: When an application's agents need shared durable knowledge, read this because a profile store gives runs one owned memory location and scopes can allow reading without writing.
+---
+
+# Application memory
+
+Use this recipe when several runs need the same application guidance. Run `npx tsx examples/guides/app-memory.ts /path/to/repo`; it ensures a profile, creates a profile-owned knowledge document if it does not already exist, then starts a run allowed to read but not write memory.
+
+<include lang="ts">../../../examples/guides/app-memory.ts</include>
+
+A profile is the application's durable identity: it names the memory store and the projects whose context the profile can reach. The routing line is part of the document, not decoration. State both the moment the agent should read it and the reason it matters; a document with a vague routing line will not surface when the agent needs it.
+
+The `boot`/`preview` surface exposes the document's routing line when this profile's agent starts. The task asks for a release note without naming `release/voice`; in the local run the agent read that document before producing the note. Without a surface entry, a memory document appears only in its directory listing and its routing line cannot select it at boot. The run passes `scopes: ['memory:read']`. That is an allow-list: node-targeted memory reads are allowed and writes are refused because `memory:write` is absent. The application itself is not narrowed by those node scopes, so keep application credentials and its memory mutation policy separate from the agent's capabilities.
+
+Observed against the local daemon with `APP_PROFILE=release-notes-app-guide-boot-preview GUIDE_MODEL=openai-codex/gpt-6-sol:high`:
+
+```text
+You can now download your invoices as a CSV from account settings.
+```
+
+Use profile memory for knowledge shared across the application's related projects. Put facts that belong to one repository in project memory instead, and temporary run notes in node memory. See [memory](../../concepts/memory.md) for the ownership tiers and [profiles, kinds, and modes](../../concepts/profiles-kinds-and-modes.md) for what a profile changes.

package/docs/sdk/guides/event-driven-assistant.md

@@ -0,0 +1,24 @@
+---
+title: Event-driven assistant
+description: When an assistant must react to later webhook, queue, or file-watcher events, read this because a resident node sleeps until nodes.message delivers the next event.
+---
+
+# Event-driven assistant
+
+Use this recipe for an assistant that reacts to an event source instead of ending after one request. Run `npx tsx examples/guides/event-driven-assistant.ts /path/to/repo`, then type events into standard input to stand in for a webhook handler or file watcher.
+
+<include lang="ts">../../../examples/guides/event-driven-assistant.ts</include>
+
+The external source owns detection. When it receives an event, it calls `nodes.message(nodeId, { body })`. `no_kickoff` leaves the resident node waiting for the first event, while `situational_context` tells it how to handle every event. A dormant resident node wakes for the message; a running node reads it at its next turn boundary. Keep the returned node id with the application so each later event reaches the same context and memory. The agent pushes one update report per event, which the application reads through `nodes.reports.list` and prints. The application checks for a fatal node fault rather than waiting forever for a report that cannot arrive.
+
+The agent does not poll or schedule a timer: the daemon wakes it on each message, and it goes dormant after reporting. This console program polls for the report associated with the event it just sent; an application with its own event loop can also consume the node's event stream. Ctrl-C calls `nodes.cancel()` only because this interactive example needs an explicit way to stop.
+
+Observed against the local daemon with `GUIDE_MODEL=openai-codex/gpt-6-sol:high` after sending `Build completed with 2 failing checks: lint and unit tests.`:
+
+```text
+assistant node: 3zl47w7d-mud5amcx-67978c9b
+Type an event and press Enter. Press Ctrl-C to stop the assistant.
+The build completed, but **lint and unit tests failed**. Inspect the two failing check logs first to identify the errors.
+```
+
+Use a resident node only when future events belong to the same ongoing assistant. For bounded work, use [typed extraction](./typed-extraction.md). See [lifecycle and wakes](../../concepts/lifecycle-and-wakes.md) for why waiting is free and [why a daemon](../../concepts/why-a-daemon.md) for why the process can outlive the terminal that started it.

package/docs/sdk/guides/fan-out-pipeline.md

@@ -0,0 +1,24 @@
+---
+title: Fan-out pipeline
+description: When independent parts of one job need separate agent work before one synthesis, read this because an orchestrator can spawn children, wait for reports, and publish a final result while the SDK streams progress.
+---
+
+# Fan-out pipeline
+
+Use this recipe when one result needs independent investigation first. Run `npx tsx examples/guides/fan-out-pipeline.ts /path/to/repo`; it asks an orchestrator to inspect a package through two children, prints live text and pushed reports, then prints the final reports retained on the node.
+
+<include lang="ts">../../../examples/guides/fan-out-pipeline.ts</include>
+
+`nodes.stream()` creates the orchestrator and observes it. It does not run the orchestration in your process: the node owns its children, waits for their pushed reports, and produces the synthesis. The stream gives your application live output and reports; `nodes.reports.list()` gives it the durable report view after settlement.
+
+Keep orchestration inside the canvas when children need the canvas's report delivery, durable waits, and a parent that can be inspected or resumed. Keep it in your application when tasks are simple independent calls and the application already owns their scheduling and aggregation. Do not use an orchestrator merely because a task is long; it earns the extra structure only when child work can run independently.
+
+A local run created `j6amiqxs-mud4drnk-330da196`; after its two children reported, `waitForOutcome()` returned:
+
+```text
+{ "kind": "result", "reason": "finalized" }
+```
+
+The same run's `nodes.stream()` observer ended during a dormant gap before it could print this outcome. A separate daemon fix is correcting that observer behavior; the example remains the intended streamed shape, but its streamed path has not yet been observed end to end.
+
+See [nodes and the canvas](../../concepts/nodes-and-the-canvas.md) for reports and durable identities, and [profiles, kinds, and modes](../../concepts/profiles-kinds-and-modes.md) for the base-versus-orchestrator decision.

package/docs/sdk/guides/human-approval.md

@@ -0,0 +1,24 @@
+---
+title: Human approval
+description: When a person must approve or reject work before an agent continues, read this because the SDK can create an inbox request whose answer wakes the requesting node.
+---
+
+# Human approval
+
+Use this recipe when a decision belongs to a person, not a timeout or an agent guess. Run `npx tsx examples/guides/human-approval.ts /path/to/repo`; it prints an inbox ticket id. Answer the page in the crtr human inbox and the worker wakes with that answer before it reports its result.
+
+<include lang="ts">../../../examples/guides/human-approval.ts</include>
+
+The application creates the page through `client.human.requests.create()` and names the worker as `requester_node_id`. `delivery.reply: true` makes the settled answer travel back to that node. The page's `UserQuestion` supplies a known response shape, so the person sees an explicit approve or reject decision instead of an unstructured prompt.
+
+The worker is terminal because this is a bounded approval run: it waits after setup, wakes when the person answers, then publishes its final result. The pending human request keeps that wait durable. The application does not poll the node or invent a fallback deadline; the human reply is a canvas event. `client.human.inbox` can list, inspect, and answer inbox tickets when your application provides its own human interface.
+
+Observed against the local daemon after an approve response:
+
+```text
+approval ticket: a643479ca7a79758bf86f32d24bd8c9b22e16509cd60996c5e4fe0bc5f097d45
+Answer it in the crtr human inbox. The worker will wake with the response.
+worker outcome: result
+```
+
+See [lifecycle and wakes](../../concepts/lifecycle-and-wakes.md) for the wake model and [scopes and trust](../../concepts/scopes-and-trust.md) for why the daemon, rather than the application, owns delivery of the answer.

package/docs/sdk/guides/typed-extraction.md

@@ -0,0 +1,22 @@
+---
+title: Typed extraction
+description: When an application needs one bounded structured answer with no follow-up, read this because nodes.parse returns a typed outcome union instead of hiding agent failures.
+---
+
+# Typed extraction
+
+Use this recipe to extract a small fact set from files in one working directory. Run it with `npx tsx examples/guides/typed-extraction.ts /path/to/repo`; it prints a package name and version or exits with an explicit agent outcome.
+
+<include lang="ts">../../../examples/guides/typed-extraction.ts</include>
+
+`nodes.parse()` creates a terminal root, waits for it, and returns the structured result typed from the Zod schema. The schema belongs at the boundary where your application consumes the answer, not in a second parser after the run.
+
+Observed against the local daemon in this checkout:
+
+```text
+package @north-light/crouter@0.3.332
+```
+
+Handle every outcome arm. A result contains `output_parsed`; a decline says the agent could not honestly meet the schema; another failure carries its reason and detail. Transport and daemon failures still throw, so let those reach your normal application error handling.
+
+This is the right shape for bounded work: one prompt, one answer, and no future message. If a user or external event must return to the same agent later, use a resident node instead. See [nodes and the canvas](../../concepts/nodes-and-the-canvas.md) for why an SDK node has durable identity, and [lifecycle and wakes](../../concepts/lifecycle-and-wakes.md) for the terminal-versus-resident decision.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.333",
+  "version": "0.3.335",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.333",
+  "version": "0.3.335",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.333",
+      "version": "0.3.335",
       "hasInstallScript": true,
       "license": "GPL-3.0-only",
       "workspaces": [
@@ -10859,28 +10859,28 @@
     },
     "packages/crouter-api": {
       "name": "@north-light/crouter-api",
-      "version": "0.3.333",
+      "version": "0.3.335",
       "license": "GPL-3.0-only"
     },
     "packages/crouter-env-docker": {
       "name": "@north-light/crouter-env-docker",
-      "version": "0.3.333",
+      "version": "0.3.335",
       "license": "GPL-3.0-only"
     },
     "packages/crouter-plugin": {
       "name": "@north-light/crouter-plugin",
-      "version": "0.3.333",
+      "version": "0.3.335",
       "license": "GPL-3.0-only",
       "dependencies": {
-        "@north-light/crouter-api": "^0.3.333"
+        "@north-light/crouter-api": "^0.3.335"
       }
     },
     "packages/crouter-sdk": {
       "name": "@north-light/crouter-sdk",
-      "version": "0.3.333",
+      "version": "0.3.335",
       "license": "GPL-3.0-only",
       "dependencies": {
-        "@north-light/crouter-api": "^0.3.333"
+        "@north-light/crouter-api": "^0.3.335"
       }
     }
   }