@namzu/sdk 42.0.2 → 44.0.0

package/README.md

@@ -2,9 +2,9 @@
 type: Reference
 title: "@namzu/sdk"
 description: >-
-  An agent kernel for TypeScript. Runs an agent as a supervised unit of work
-  with an identity, a budget, a permission boundary and pluggable durable
-  stores. Renders no UI, hosts no service, and has no preferred model vendor.
+  An agent kernel for TypeScript. Runs an agent as supervised turns of a
+  session, with an identity, a budget, a permission boundary and a durable
+  session log. Renders no UI, hosts no service, and has no preferred model vendor.
 tags: [readme, package, sdk, agent-kernel]
 status: stable
 generated: { by: human:bahadirarda, at: 2026-08-21T00:00:00Z }
@@ -61,29 +61,29 @@ pre-registered and scriptable.
 
 ## Quick start
 
-This first run needs no API key or network. The mock supplies a scripted model
-reply; the kernel executes the same run loop used by service-backed drivers.
+This first turn needs no API key or network. The mock supplies a scripted model
+reply; the kernel executes the same turn loop used by service-backed drivers.
 
 ```ts
 import { ProviderRegistry, runAgent } from '@namzu/sdk'
 
 const { provider } = ProviderRegistry.create({ type: 'mock', responseText: 'Paris.' })
 
-const { output, run, identity } = await runAgent({
+const { output, turn, identity } = await runAgent({
   provider,
   model: 'mock-model',
   prompt: 'What is the capital of France?',
 })
 
 console.log(output)          // Paris.
-console.log(run.stopReason)  // end_turn
+console.log(turn.stopReason) // end_turn
 console.log(identity)        // { sessionId, topicId, projectId, tenantId }
 ```
 
 Save it as `agent.ts` in an ESM project and run it with `pnpm exec tsx agent.ts`
 after adding `tsx` as a development dependency. `runAgent` creates the four
 identity values when absent and returns them. Pass both `identity` and
-`run.messages` into the next call to continue a conversation; identity alone
+`turn.messages` into the next call to continue a conversation; identity alone
 does not load its history. For store-backed delegation, supply the identity of
 records created in the session store.
 
@@ -116,7 +116,7 @@ const provider = new MockLLMProvider({
   ],
 })
 
-const { output, run } = await runAgent({
+const { output, turn } = await runAgent({
   provider,
   model: 'mock-model',
   tools,
@@ -127,22 +127,29 @@ const { output, run } = await runAgent({
 })
 
 console.log(output) // 42
-console.log(run.messages.filter((message) => message.role === 'tool'))
+console.log(turn.messages.filter((message) => message.role === 'tool'))
 ```
 
 To use inference, install a [provider driver](#install) and replace the mock
-provider and model with that driver's configuration. The tools and run call
-stay the same.
-
-These runs use the kernel's budgets, tool loop and checkpoint persistence.
-`ReactiveAgent` exposes additional configuration such as compaction and durable
-store routing; its `run` config requires `sessionId`, `topicId`, `projectId` and
+provider and model with that driver's configuration. The tools and the
+`runAgent` call stay the same.
+
+Each call is one turn of a session, with the kernel's budgets, tool loop and
+checkpoints. The session is recorded in one append-only log under
+`NAMZU_HOME` (default `~/.namzu`), in `projects/<slug>/<session-id>.jsonl`,
+and nothing is written under the working directory; see the
+[session log](https://github.com/cogitave/namzu/blob/main/docs/sdk/session-log.md).
+A session has at most one active turn: starting another while one is running
+or paused throws `TurnInProgressError`. `ReactiveAgent` exposes additional
+configuration such as compaction and where the session is stored; the config
+passed to its `run` method requires `sessionId`, `topicId`, `projectId` and
 `tenantId`. OS isolation is explicit rather than ambient: supply a
-`sandboxProvider` when the host requires it. Direct SDK runs use a disposable
+`sandboxProvider` when the host requires it. Direct SDK turns use a disposable
 sandbox workspace unless `sandbox: { workspace: 'working-directory' }` is
-selected and the provider advertises support for rooting itself at the run's
-declared working directory. Configure durable stores and
-telemetry exporters when the process must outlive or export the in-memory run.
+selected and the provider advertises support for rooting itself at the turn's
+declared working directory. Pass an `InMemorySessionLog` as `sessionLog` to
+keep a session entirely in memory, and configure telemetry exporters when the
+process must export what it did.
 
 ## What you get
 
@@ -150,8 +157,8 @@ telemetry exporters when the process must outlive or export the in-memory run.
 |---|---|
 | **Boundary** | a permission gate decides before dispatch; configured sandbox providers add OS confinement |
 | **Budget** | tokens, money, wall clock and iterations, enforced rather than hoped for |
-| **Identity** | tenant → project → topic → session → run, on every record and span |
-| **Durability** | pluggable run/checkpoint stores can preserve a record beyond the process |
+| **Identity** | tenant → project → topic → session → turn → message, on every record and span |
+| **Durability** | one hash-chained log per session, with checkpoints beside it, survives the process; SQLite is only a rebuildable index |
 | **Compaction** | a conversation about to overflow is shrunk without being corrupted |
 | **Observability** | telemetry and log seams whose providers and sinks the host owns |
 
@@ -163,18 +170,18 @@ is completed exactly once. Hosts receive `message_history_repaired` with source
 and counts before the model call; conversation and tool content stay out of the
 event.
 
-Stored image and document references are materialized under the run's caller
-signal before provider work starts. A pre-cancelled run performs no attachment
-store I/O; cancellation also settles the run when a custom or remote store
+Stored image and document references are materialized under the turn's caller
+signal before provider work starts. A pre-cancelled turn performs no attachment
+store I/O; cancellation also settles the turn when a custom or remote store
 ignores the signal, while retaining the unresolved references in its durable
 message record. `AttachmentStore.get` receives an optional
 `AttachmentOperationOptions` so implementations can stop their own I/O. The
 caller keeps ownership of its controller, and a late store result is never
-published into a cancelled run. `resumeRun` carries its already-selected
+published into a cancelled turn. `resumeSession` carries its already-selected
 checkpoint snapshot into the same boundary, so cancellation neither rereads a
 non-cooperative checkpoint backend nor replaces prior history, usage, or a new
 queued reference with an incomplete snapshot. The selected checkpoint also
-carries its durable trace parent into the cancelled run, preserving one
+carries its durable trace parent into the cancelled turn, preserving one
 cross-process timeline without a second checkpoint read.
 
 Hosts that discover scoped repository policy can supply a
@@ -182,7 +189,7 @@ Hosts that discover scoped repository policy can supply a
 `SupervisorAgent`. Its first-request snapshot is structurally tagged and
 retained; completed registry calls, including nested dispatch, can publish a
 replacement immediately after the complete tool-result batch. Each callback
-receives the run signal and the exact accepted message prefix; each returned
+receives the turn signal and the exact accepted message prefix; each returned
 snapshot is committed before the next observation starts, so cancellation can
 discard an unfinished suffix without losing accepted policy state. This
 channel does not create a human continuation, so a terminal tool or stop
@@ -190,12 +197,12 @@ predicate cannot strand the update. Canonical project-relative `AGENTS.md`
 provenance survives compaction and lets a reconstructed host re-read disk
 authority rather than trusting persisted policy text.
 
-High-level `ReactiveAgent` and `SupervisorAgent` configurations also accept a
-`pathBuilder`. Supplying one makes runs, checkpoints, emergency saves, memory
-and task state use that exact durable hierarchy instead of falling back to the
-working directory. `DiskSessionStore` can bind a Project to a canonical
-`rootPath`; the binding is tenant-scoped, immutable and published safely when
-multiple processes race to open the same workspace.
+High-level `ReactiveAgent` and `SupervisorAgent` configurations also accept
+`paths`, a `SessionPaths`. Supplying one puts the session log, its child
+sessions, checkpoints, token ledger and task state under that root instead of
+`resolveNamzuHome()`. A project id is minted once per working directory into
+`projects/<slug>/project.json`; two processes that open the same directory at
+the same moment adopt the same id.
 
 `TopicManager` is the lifecycle authority for the durable subject above a
 session. Supply it to agent and handoff dependencies as `topicManager`; spawn

package/dist/advisory/budget.js

@@ -8,14 +8,14 @@
  * a configuration that cannot do what it says is an error, not a default.
  */
 export function assertBudgetEnforceable(config) {
-    if (config.budget?.maxCostPerRun === undefined)
+    if (config.budget?.maxCostPerTurn === undefined)
         return;
     const unpriced = config.advisors.filter((a) => a.pricing === undefined).map((a) => a.id);
     if (unpriced.length === 0)
         return;
-    throw new Error(`Advisory budget sets maxCostPerRun but ${unpriced.length === 1 ? 'advisor' : 'advisors'} ` +
+    throw new Error(`Advisory budget sets maxCostPerTurn but ${unpriced.length === 1 ? 'advisor' : 'advisors'} ` +
         `${unpriced.join(', ')} carr${unpriced.length === 1 ? 'ies' : 'y'} no pricing, so cost ` +
         'cannot be measured and the cap could never be reached. Give each advisor a `pricing` ' +
-        'entry, or drop the cost cap and bound the run with `maxCallsPerRun`.');
+        'entry, or drop the cost cap and bound the turn with `maxCallsPerTurn`.');
 }
 //# sourceMappingURL=budget.js.map

package/dist/advisory/budget.js.map

@@ -1 +1 @@
-{"version":3,"file":"budget.js","sourceRoot":"","sources":["../../src/advisory/budget.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAGvC;IACA,IAAI,MAAM,CAAC,MAAM,EAAE,aAAa,KAAK,SAAS;QAAE,OAAM;IAEtD,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;IACxF,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAM;IAEjC,MAAM,IAAI,KAAK,CACd,0CAA0C,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,GAAG;QAC1F,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,uBAAuB;QACxF,uFAAuF;QACvF,sEAAsE,CACvE,CAAA;AACF,CAAC"}
+{"version":3,"file":"budget.js","sourceRoot":"","sources":["../../src/advisory/budget.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAGvC;IACA,IAAI,MAAM,CAAC,MAAM,EAAE,cAAc,KAAK,SAAS;QAAE,OAAM;IAEvD,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;IACxF,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAM;IAEjC,MAAM,IAAI,KAAK,CACd,2CAA2C,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,GAAG;QAC3F,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,uBAAuB;QACxF,uFAAuF;QACvF,wEAAwE,CACzE,CAAA;AACF,CAAC"}

package/dist/advisory/context.d.ts

@@ -4,12 +4,12 @@ import type { AdvisoryCallContext } from './executor.js';
 import type { AdvisoryExecutor } from './executor.js';
 import type { AdvisorRegistry } from './registry.js';
 /**
- * What the run looks like right now, for an advisory call that did not come
+ * What the turn looks like right now, for an advisory call that did not come
  * from the iteration loop.
  *
- * A function rather than a snapshot because the tool is built once per run
+ * A function rather than a snapshot because the tool is built once per turn
  * and called at an unknown later point: capturing the context at
- * construction would hand every advisor the state the run had before it
+ * construction would hand every advisor the state the turn had before it
  * started.
  */
 export type AdvisoryCallContextProvider = () => AdvisoryCallContext;
@@ -21,7 +21,7 @@ export declare class AdvisoryContext {
     private readonly budget;
     private callContextProvider;
     constructor(registry: AdvisorRegistry, executor: AdvisoryExecutor, evaluator: TriggerEvaluator, budget?: AdvisoryBudget);
-    /** Wired by the runtime once the run exists. */
+    /** Wired by the runtime once the turn exists. */
     setCallContextProvider(provider: AdvisoryCallContextProvider): void;
     /**
      * The call context for a tool-initiated consultation.
@@ -40,7 +40,7 @@ export declare class AdvisoryContext {
         total: number | undefined;
         used: number;
     };
-    /** Advisory spend so far this run, summed from the recorded calls. */
+    /** Advisory spend so far this turn, summed from the recorded calls. */
     spentCost(): number;
     checkBudget(): {
         allowed: boolean;

package/dist/advisory/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/advisory/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AACpF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AACtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AACrD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAEpD;;;;;;;;GAQG;AACH,MAAM,MAAM,2BAA2B,GAAG,MAAM,mBAAmB,CAAA;AAEnE,qBAAa,eAAe;IAC3B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAA;IAClC,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAA;IACnC,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAA;IACpC,QAAQ,CAAC,WAAW,EAAE,kBAAkB,EAAE,CAAK;IAE/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;IACnD,OAAO,CAAC,mBAAmB,CAAyC;gBAGnE,QAAQ,EAAE,eAAe,EACzB,QAAQ,EAAE,gBAAgB,EAC1B,SAAS,EAAE,gBAAgB,EAC3B,MAAM,CAAC,EAAE,cAAc;IAQxB,gDAAgD;IAChD,sBAAsB,CAAC,QAAQ,EAAE,2BAA2B,GAAG,IAAI;IAInE;;;;;;;;;OASG;IACH,WAAW,IAAI,mBAAmB;IAIlC,UAAU,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI;IAI5C,eAAe,IAAI;QAAE,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE;IAO7F,sEAAsE;IACtE,SAAS,IAAI,MAAM;IAInB,WAAW,IAAI;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;CAwBpD"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/advisory/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AACpF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AACtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AACrD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAEpD;;;;;;;;GAQG;AACH,MAAM,MAAM,2BAA2B,GAAG,MAAM,mBAAmB,CAAA;AAEnE,qBAAa,eAAe;IAC3B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAA;IAClC,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAA;IACnC,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAA;IACpC,QAAQ,CAAC,WAAW,EAAE,kBAAkB,EAAE,CAAK;IAE/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;IACnD,OAAO,CAAC,mBAAmB,CAAyC;gBAGnE,QAAQ,EAAE,eAAe,EACzB,QAAQ,EAAE,gBAAgB,EAC1B,SAAS,EAAE,gBAAgB,EAC3B,MAAM,CAAC,EAAE,cAAc;IAQxB,iDAAiD;IACjD,sBAAsB,CAAC,QAAQ,EAAE,2BAA2B,GAAG,IAAI;IAInE;;;;;;;;;OASG;IACH,WAAW,IAAI,mBAAmB;IAIlC,UAAU,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI;IAI5C,eAAe,IAAI;QAAE,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE;IAO7F,uEAAuE;IACvE,SAAS,IAAI,MAAM;IAInB,WAAW,IAAI;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;CAwBpD"}

package/dist/advisory/context.js

@@ -11,7 +11,7 @@ export class AdvisoryContext {
         this.evaluator = evaluator;
         this.budget = budget;
     }
-    /** Wired by the runtime once the run exists. */
+    /** Wired by the runtime once the turn exists. */
     setCallContextProvider(provider) {
         this.callContextProvider = provider;
     }
@@ -33,11 +33,11 @@ export class AdvisoryContext {
     }
     getBudgetStatus() {
         const used = this.callHistory.length;
-        const total = this.budget?.maxCallsPerRun;
+        const total = this.budget?.maxCallsPerTurn;
         const remaining = total !== undefined ? total - used : undefined;
         return { remaining, total, used };
     }
-    /** Advisory spend so far this run, summed from the recorded calls. */
+    /** Advisory spend so far this turn, summed from the recorded calls. */
     spentCost() {
         return this.callHistory.reduce((sum, call) => sum + call.cost.totalCost, 0);
     }
@@ -46,18 +46,18 @@ export class AdvisoryContext {
         if (remaining !== undefined && remaining <= 0) {
             return {
                 allowed: false,
-                reason: `Advisory budget exhausted: ${total} calls used of ${total} allowed per run`,
+                reason: `Advisory budget exhausted: ${total} calls used of ${total} allowed per turn`,
             };
         }
         // Checked before the call, not after: a cap that only reports
         // overspend once it has happened is a log line, not a budget.
-        const costCap = this.budget?.maxCostPerRun;
+        const costCap = this.budget?.maxCostPerTurn;
         if (costCap !== undefined) {
             const spent = this.spentCost();
             if (spent >= costCap) {
                 return {
                     allowed: false,
-                    reason: `Advisory budget exhausted: cost ${spent} of ${costCap} allowed per run`,
+                    reason: `Advisory budget exhausted: cost ${spent} of ${costCap} allowed per turn`,
                 };
             }
         }

package/dist/advisory/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/advisory/context.ts"],"names":[],"mappings":"AAiBA,MAAM,OAAO,eAAe;IAClB,QAAQ,CAAiB;IACzB,QAAQ,CAAkB;IAC1B,SAAS,CAAkB;IAC3B,WAAW,GAAyB,EAAE,CAAA;IAE9B,MAAM,CAA4B;IAC3C,mBAAmB,CAAyC;IAEpE,YACC,QAAyB,EACzB,QAA0B,EAC1B,SAA2B,EAC3B,MAAuB;QAEvB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAA;QACxB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAA;QACxB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAA;QAC1B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;IACrB,CAAC;IAED,gDAAgD;IAChD,sBAAsB,CAAC,QAAqC;QAC3D,IAAI,CAAC,mBAAmB,GAAG,QAAQ,CAAA;IACpC,CAAC;IAED;;;;;;;;;OASG;IACH,WAAW;QACV,OAAO,IAAI,CAAC,mBAAmB,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,CAAA;IACtE,CAAC;IAED,UAAU,CAAC,MAA0B;QACpC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IAC9B,CAAC;IAED,eAAe;QACd,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,MAAM,CAAA;QACpC,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,cAAc,CAAA;QACzC,MAAM,SAAS,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,SAAS,CAAA;QAChE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;IAClC,CAAC;IAED,sEAAsE;IACtE,SAAS;QACR,OAAO,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAA;IAC5E,CAAC;IAED,WAAW;QACV,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC,eAAe,EAAE,CAAA;QACnD,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,IAAI,CAAC,EAAE,CAAC;YAC/C,OAAO;gBACN,OAAO,EAAE,KAAK;gBACd,MAAM,EAAE,8BAA8B,KAAK,kBAAkB,KAAK,kBAAkB;aACpF,CAAA;QACF,CAAC;QAED,8DAA8D;QAC9D,8DAA8D;QAC9D,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,EAAE,aAAa,CAAA;QAC1C,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC3B,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,EAAE,CAAA;YAC9B,IAAI,KAAK,IAAI,OAAO,EAAE,CAAC;gBACtB,OAAO;oBACN,OAAO,EAAE,KAAK;oBACd,MAAM,EAAE,mCAAmC,KAAK,OAAO,OAAO,kBAAkB;iBAChF,CAAA;YACF,CAAC;QACF,CAAC;QAED,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;IACzB,CAAC;CACD"}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/advisory/context.ts"],"names":[],"mappings":"AAiBA,MAAM,OAAO,eAAe;IAClB,QAAQ,CAAiB;IACzB,QAAQ,CAAkB;IAC1B,SAAS,CAAkB;IAC3B,WAAW,GAAyB,EAAE,CAAA;IAE9B,MAAM,CAA4B;IAC3C,mBAAmB,CAAyC;IAEpE,YACC,QAAyB,EACzB,QAA0B,EAC1B,SAA2B,EAC3B,MAAuB;QAEvB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAA;QACxB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAA;QACxB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAA;QAC1B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;IACrB,CAAC;IAED,iDAAiD;IACjD,sBAAsB,CAAC,QAAqC;QAC3D,IAAI,CAAC,mBAAmB,GAAG,QAAQ,CAAA;IACpC,CAAC;IAED;;;;;;;;;OASG;IACH,WAAW;QACV,OAAO,IAAI,CAAC,mBAAmB,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,CAAA;IACtE,CAAC;IAED,UAAU,CAAC,MAA0B;QACpC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IAC9B,CAAC;IAED,eAAe;QACd,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,MAAM,CAAA;QACpC,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,eAAe,CAAA;QAC1C,MAAM,SAAS,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,SAAS,CAAA;QAChE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;IAClC,CAAC;IAED,uEAAuE;IACvE,SAAS;QACR,OAAO,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAA;IAC5E,CAAC;IAED,WAAW;QACV,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC,eAAe,EAAE,CAAA;QACnD,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,IAAI,CAAC,EAAE,CAAC;YAC/C,OAAO;gBACN,OAAO,EAAE,KAAK;gBACd,MAAM,EAAE,8BAA8B,KAAK,kBAAkB,KAAK,mBAAmB;aACrF,CAAA;QACF,CAAC;QAED,8DAA8D;QAC9D,8DAA8D;QAC9D,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,EAAE,cAAc,CAAA;QAC3C,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC3B,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,EAAE,CAAA;YAC9B,IAAI,KAAK,IAAI,OAAO,EAAE,CAAC;gBACtB,OAAO;oBACN,OAAO,EAAE,KAAK;oBACd,MAAM,EAAE,mCAAmC,KAAK,OAAO,OAAO,mBAAmB;iBACjF,CAAA;YACF,CAAC;QACF,CAAC;QAED,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;IACzB,CAAC;CACD"}

package/dist/advisory/evaluator.js

@@ -32,10 +32,10 @@ export class TriggerEvaluator {
         this.callCount++;
     }
     isBudgetExhausted() {
-        if (this.budget?.maxCallsPerRun === undefined) {
+        if (this.budget?.maxCallsPerTurn === undefined) {
             return false;
         }
-        return this.callCount >= this.budget.maxCallsPerRun;
+        return this.callCount >= this.budget.maxCallsPerTurn;
     }
     isCooldownSatisfied(trigger, currentIteration) {
         if (trigger.cooldownIterations === undefined) {

package/dist/advisory/evaluator.js.map

@@ -1 +1 @@
-{"version":3,"file":"evaluator.js","sourceRoot":"","sources":["../../src/advisory/evaluator.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"evaluator.js","sourceRoot":"","sources":["../../src/advisory/evaluator.ts"],"names":[],"mappings":"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"}

package/dist/advisory/parse.d.ts

@@ -17,7 +17,7 @@ export declare const ADVISORY_RESPONSE_CONTRACT: string;
  * parser returned `{ advice }` and nothing else, so an advisor's decisions
  * never reached working state and its warnings never reached the executing
  * agent. Both consumers were written, tested against hand-built results,
- * and permanently unreachable in a real run.
+ * and permanently unreachable in a real turn.
  */
 export declare function parseAdvisoryResponse(rawContent: string): AdvisoryResult;
 //# sourceMappingURL=parse.d.ts.map

package/dist/advisory/parse.js

@@ -30,7 +30,7 @@ function itemsIn(block) {
  * parser returned `{ advice }` and nothing else, so an advisor's decisions
  * never reached working state and its warnings never reached the executing
  * agent. Both consumers were written, tested against hand-built results,
- * and permanently unreachable in a real run.
+ * and permanently unreachable in a real turn.
  */
 export function parseAdvisoryResponse(rawContent) {
     const warnings = [];

package/dist/agents/AbstractAgent.d.ts

@@ -1,19 +1,19 @@
 import type { Agent, AgentCapabilities, AgentInput, AgentMetadata, AgentType, BaseAgentConfig, BaseAgentResult } from '../types/agent/index.js';
 import type { AgentManagerContract } from '../types/agent/manager.js';
-import type { RunId } from '../types/ids/index.js';
-import { type CancelCause } from '../types/run/cancel-cause.js';
-import type { RunEvent, RunEventListener } from '../types/run/index.js';
+import type { SessionId, TurnId } from '../types/ids/index.js';
+import { type CancelCause } from '../types/session/cancel-cause.js';
+import type { SessionEvent, SessionEventListener } from '../types/session/events.js';
 import { type Logger } from '../utils/logger.js';
 export declare abstract class AbstractAgent<TConfig extends BaseAgentConfig = BaseAgentConfig, TResult extends BaseAgentResult = BaseAgentResult> implements Agent<TConfig, TResult> {
     abstract readonly type: AgentType;
     readonly metadata: AgentMetadata;
     protected log: Logger;
     /**
-     * The logger bound at construction, before any run id exists. `this.log`
-     * is rebound to a CHILD of this on every `bindRun` call — never the other
-     * way — so `forRun()` (which builds a fresh shell from `this.metadata`)
+     * The logger bound at construction, before any turn exists. `this.log`
+     * is rebound to a CHILD of this on every `bindTurn` call — never the other
+     * way — so `forTurn()` (which builds a fresh shell from `this.metadata`)
      * can hand the new instance the same base identity without also handing
-     * it a stale run id from whichever run happened to be live last.
+     * it a stale turn id from whichever turn happened to be live last.
      */
     private readonly baseLog;
     protected abortController: AbortController;
@@ -24,34 +24,36 @@ export declare abstract class AbstractAgent<TConfig extends BaseAgentConfig = Ba
      * IN-FLIGHT ONLY, and deliberately: a settled entry kept around would
      * turn deduplication into caching, and caching an agent's answer is a
      * decision about staleness that only the host can make. A retry that
-     * arrives after the first finished runs again, which is the honest
+     * arrives after the first finished turns again, which is the honest
      * behaviour — the world may have moved.
      */
     private readonly inflightByKey;
     protected agentManager?: AgentManagerContract;
-    protected currentRunId?: RunId;
+    /** The session this instance is running a turn of, once `bindTurn` recorded it. */
+    protected currentSessionId?: SessionId;
+    protected currentTurnId?: TurnId;
     constructor(metadata: AgentMetadata, log?: Logger);
-    abstract run(input: AgentInput, config: TConfig, listener?: RunEventListener): Promise<TResult>;
+    abstract run(input: AgentInput, config: TConfig, listener?: SessionEventListener): Promise<TResult>;
     /**
-     * A fresh shell of this agent, for a run that must not share one.
+     * A fresh shell of this agent, for a turn that must not share one.
      *
-     * See {@link Agent.forRun}. An agent is a shell around metadata — every
-     * per-run decision arrives in `config` and `input` — so a second instance
-     * costs one object and gives the run its own abort controller and run id,
+     * See {@link Agent.forTurn}. An agent is a shell around metadata — every
+     * per-turn decision arrives in `config` and `input` — so a second instance
+     * costs one object and gives the turn its own abort controller and turn id,
      * which is precisely what the invocation lock is protecting.
      *
      * Rebuilt from `this.constructor` and `this.metadata`, which covers every
      * agent in this package: they all take metadata and nothing else. A
      * subclass with a different constructor signature will throw here, and the
      * answer to that is `this` — the caller then shares the shell and gets the
-     * existing refusal on a concurrent run, which is the behaviour before this
+     * existing refusal on a concurrent turn, which is the behaviour before this
      * existed. Losing parallelism is a worse outcome than not having it; losing
-     * the run is not on the table.
+     * the turn is not on the table.
      *
      * A host whose agent needs real construction arguments supplies
      * `AgentDefinition.createAgent` instead, which wins over this.
      */
-    forRun(): this;
+    forTurn(): this;
     /**
      * Acquire the invocation lock to prevent concurrent execution.
      * Returns a Disposable that must be disposed to release the lock.
@@ -76,11 +78,11 @@ export declare abstract class AbstractAgent<TConfig extends BaseAgentConfig = Ba
      * invocations of one agent instance were not prevented at all, and the
      * error type that announces the refusal could never be thrown.
      *
-     * They genuinely are unsafe. `abortController` and `currentRunId` are
-     * INSTANCE state: two overlapping runs share one abort controller, so
-     * cancelling either kills both, and the second clobbers the first's run
-     * id, so `cancel()` afterwards cancels the wrong run. Neither failure
-     * announces itself — the first run simply stops, or the wrong one does.
+     * They genuinely are unsafe. `abortController` and `currentSessionId` are
+     * INSTANCE state: two overlapping turns share one abort controller, so
+     * cancelling either kills both, and the second clobbers the first's
+     * session, so `cancel()` afterwards cancels the wrong children. Neither failure
+     * announces itself — the first turn simply stops, or the wrong one does.
      *
      * A host that wants parallelism constructs a second instance, which is
      * cheap; sharing one was never the supported shape, it merely was not
@@ -93,7 +95,7 @@ export declare abstract class AbstractAgent<TConfig extends BaseAgentConfig = Ba
      *
      * The failure this exists for: a caller sends a request, the connection
      * drops, the caller retries. Without a key the retry is a second full
-     * run — a second set of model calls, and a second set of whatever the
+     * turn — a second set of model calls, and a second set of whatever the
      * tools did. The invocation lock alone does not help, because refusing
      * the retry with an error is not what the caller wanted either; they
      * wanted the answer.
@@ -113,37 +115,42 @@ export declare abstract class AbstractAgent<TConfig extends BaseAgentConfig = Ba
      * operator's behalf is not — and a default would attribute every
      * unlabelled cancellation to a person who did not press anything.
      *
-     * Children get `'parent'` regardless of what stopped this run: from a
+     * Children get `'parent'` regardless of what stopped this turn: from a
      * child's side, the fact is that its parent went away.
      */
     cancel(cause?: CancelCause): Promise<void>;
     getCapabilities(): AgentCapabilities;
-    protected createRunId(): RunId;
+    /** A fresh id for the turn this invocation runs. */
+    protected createTurnId(): TurnId;
     /**
-     * Rebind this instance's logger to a specific run, so every record
-     * `this.log` writes for the DURATION of that run carries `namzu.run.id` —
-     * and every record after the NEXT call carries that run's id, not this
-     * one.
+     * The session this invocation's turn belongs to: the config's, or a new
+     * one when the host named none (a one-shot agent is a one-turn session).
+     */
+    protected resolveSessionId(configured: SessionId | undefined): SessionId;
+    /**
+     * Rebind this instance's logger to a specific turn, so every record
+     * `this.log` writes for the DURATION of that turn carries `namzu.turn.id`
+     * and the session id — and every record after the NEXT call carries that
+     * turn's ids, not this one's.
      *
      * Constructor-time binding was the bug this exists to fix: an agent
-     * constructed once and invoked twice (`forRun` aside — a host is free to
-     * reuse one instance across sequential runs, and every concrete `run()`
+     * constructed once and invoked twice (`forTurn` aside — a host is free to
+     * reuse one instance across sequential turns, and every concrete `run()`
      * takes fresh `input`/`config` precisely to allow it) held ONE logger for
-     * its whole lifetime, so a warning from run two carried run one's id, or
+     * its whole lifetime, so a warning from turn two carried turn one's id, or
      * none. Every concrete `run()` implementation calls this before touching
-     * `this.log`, right after resolving the run's id — see `RouterAgent`,
+     * `this.log`, right after resolving the turn's id — see `RouterAgent`,
      * `PipelineAgent`, `SupervisorAgent` and `ReactiveAgent`.
      *
-     * `log` lets a per-run override (`BaseAgentConfig.logger`, a host setting
+     * `log` lets a per-turn override (`BaseAgentConfig.logger`, a host setting
      * on ONE call to `.run()`) win over the agent's construction-time base,
      * without reconstructing the agent to get it.
      *
-     * Also the one place `currentRunId` is actually assigned. It was declared
-     * and read by `cancel()` but never written — a run could never be
-     * cancelled by id because nothing ever recorded which run was current.
+     * Also the one place `currentSessionId` is assigned, which is what
+     * `cancel()` reads to cancel this session's delegated children.
      */
-    protected bindRun(runId: RunId, log?: Logger): void;
-    protected createEmptyResult(runId: RunId, startTime: number): BaseAgentResult;
-    protected emitEvent(event: RunEvent, listener?: RunEventListener): Promise<void>;
+    protected bindTurn(sessionId: SessionId, turnId: TurnId, log?: Logger): void;
+    protected createEmptyResult(sessionId: SessionId, turnId: TurnId, startTime: number): BaseAgentResult;
+    protected emitEvent(event: SessionEvent, listener?: SessionEventListener): Promise<void>;
 }
 //# sourceMappingURL=AbstractAgent.d.ts.map

package/dist/agents/AbstractAgent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AbstractAgent.d.ts","sourceRoot":"","sources":["../../src/agents/AbstractAgent.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACX,KAAK,EACL,iBAAiB,EACjB,UAAU,EACV,aAAa,EACb,SAAS,EACT,eAAe,EACf,eAAe,EACf,MAAM,yBAAyB,CAAA;AAChC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AACrE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAA;AAClD,OAAO,EAAE,KAAK,WAAW,EAAgB,MAAM,8BAA8B,CAAA;AAC7E,OAAO,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAKvE,OAAO,EAAE,KAAK,MAAM,EAAiB,MAAM,oBAAoB,CAAA;AAG/D,8BAAsB,aAAa,CAClC,OAAO,SAAS,eAAe,GAAG,eAAe,EACjD,OAAO,SAAS,eAAe,GAAG,eAAe,CAChD,YAAW,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC;IAEnC,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACjC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAA;IAChC,SAAS,CAAC,GAAG,EAAE,MAAM,CAAA;IACrB;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,SAAS,CAAC,eAAe,EAAE,eAAe,CAAA;IAC1C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAgB;IAE/C;;;;;;;;OAQG;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAsC;IAEpE,SAAS,CAAC,YAAY,CAAC,EAAE,oBAAoB,CAAA;IAE7C,SAAS,CAAC,YAAY,CAAC,EAAE,KAAK,CAAA;gBAElB,QAAQ,EAAE,aAAa,EAAE,GAAG,CAAC,EAAE,MAAM;IAYjD,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;IAE/F;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,IAAI,IAAI;IAmBd;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CAAC,qBAAqB;IAI/B;;;;;;;;;;;;;;;;OAgBG;cACa,mBAAmB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAS1E;;;;;;;;;;;;;;;;;;OAkBG;cACa,mBAAmB,CAAC,CAAC,EACpC,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACpB,OAAO,CAAC,CAAC,CAAC;IAuBb;;;;;;;;OAQG;IACG,MAAM,CAAC,KAAK,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAQhD,eAAe,IAAI,iBAAiB;IAIpC,SAAS,CAAC,WAAW,IAAI,KAAK;IAI9B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,SAAS,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI;IAKnD,SAAS,CAAC,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,GAAG,eAAe;cAY7D,SAAS,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;CAUtF"}
+{"version":3,"file":"AbstractAgent.d.ts","sourceRoot":"","sources":["../../src/agents/AbstractAgent.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACX,KAAK,EACL,iBAAiB,EACjB,UAAU,EACV,aAAa,EACb,SAAS,EACT,eAAe,EACf,eAAe,EACf,MAAM,yBAAyB,CAAA;AAChC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AACrE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAA;AAC9D,OAAO,EAAE,KAAK,WAAW,EAAiB,MAAM,kCAAkC,CAAA;AAClF,OAAO,KAAK,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAA;AAKpF,OAAO,EAAE,KAAK,MAAM,EAAiB,MAAM,oBAAoB,CAAA;AAG/D,8BAAsB,aAAa,CAClC,OAAO,SAAS,eAAe,GAAG,eAAe,EACjD,OAAO,SAAS,eAAe,GAAG,eAAe,CAChD,YAAW,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC;IAEnC,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACjC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAA;IAChC,SAAS,CAAC,GAAG,EAAE,MAAM,CAAA;IACrB;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,SAAS,CAAC,eAAe,EAAE,eAAe,CAAA;IAC1C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAgB;IAE/C;;;;;;;;OAQG;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAsC;IAEpE,SAAS,CAAC,YAAY,CAAC,EAAE,oBAAoB,CAAA;IAE7C,mFAAmF;IACnF,SAAS,CAAC,gBAAgB,CAAC,EAAE,SAAS,CAAA;IAEtC,SAAS,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;gBAEpB,QAAQ,EAAE,aAAa,EAAE,GAAG,CAAC,EAAE,MAAM;IAYjD,QAAQ,CAAC,GAAG,CACX,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,OAAO,EACf,QAAQ,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,OAAO,CAAC;IAEnB;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,IAAI,IAAI;IAmBf;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CAAC,qBAAqB;IAI/B;;;;;;;;;;;;;;;;OAgBG;cACa,mBAAmB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAS1E;;;;;;;;;;;;;;;;;;OAkBG;cACa,mBAAmB,CAAC,CAAC,EACpC,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACpB,OAAO,CAAC,CAAC,CAAC;IAuBb;;;;;;;;OAQG;IACG,MAAM,CAAC,KAAK,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAQhD,eAAe,IAAI,iBAAiB;IAIpC,oDAAoD;IACpD,SAAS,CAAC,YAAY,IAAI,MAAM;IAIhC;;;OAGG;IACH,SAAS,CAAC,gBAAgB,CAAC,UAAU,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS;IAIxE;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,SAAS,CAAC,QAAQ,CAAC,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI;IAS5E,SAAS,CAAC,iBAAiB,CAC1B,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GACf,eAAe;cAaF,SAAS,CAAC,KAAK,EAAE,YAAY,EAAE,QAAQ,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;CAU9F"}