@namzu/sdk 27.1.0 → 28.0.0

package/dist/types/tool/index.d.ts

@@ -1,15 +1,94 @@
 import type { z } from 'zod';
 import type { Logger } from '../../utils/logger.js';
+import type { CodeNavigationProvider } from '../code-navigation/index.js';
 import type { ToolResultGuardrailSpec } from '../guardrail/index.js';
 import type { RunId } from '../ids/index.js';
 import type { InvocationState } from '../invocation/index.js';
 import type { PermissionMode } from '../permission/index.js';
 import type { Sandbox } from '../sandbox/index.js';
+import type { ToolPresentation } from './presentation.js';
 export interface ToolRegistryRef {
     searchDeferred(query: string): ToolDefinition[];
     activate(names: string[]): void;
     getAvailability(name: string): ToolAvailability;
 }
+/**
+ * The slice of the background job registry a tool is given.
+ *
+ * A structural reference rather than the class, for the reason
+ * `ToolRegistryRef` exists: this type file is imported by everything, and
+ * naming the implementation here would drag a `node:child_process` module
+ * into every consumer's type graph. `owner` is not on this surface at all —
+ * the executor binds it to the run, so a tool cannot start a job that
+ * outlives, or is billed to, somebody else's run.
+ */
+/**
+ * The slice of the skills registry a tool is given.
+ *
+ * Structural for the reason `ToolRegistryRef` is: this file is imported by
+ * everything, and naming `SkillRegistry` here would drag the skill loader's
+ * filesystem imports into every consumer's type graph.
+ */
+export interface SkillRegistryRef {
+    /**
+     * Load a skill's full body, or `undefined` for a name nobody registered.
+     *
+     * Full disclosure by design: a tool call asking for a skill is asking
+     * for its instructions, and returning metadata the model already has in
+     * its manifest would answer a question it did not ask.
+     */
+    load(name: string): Promise<{
+        skill: {
+            metadata: {
+                name: string;
+                description: string;
+                allowedTools?: string;
+                /**
+                 * The literal union, not `string`. Widening it here would
+                 * let a ref satisfy this interface while carrying a value
+                 * `isInvocableBy` cannot read, and the failure would be a
+                 * silent `both` — the fail-open answer.
+                 */
+                invocation?: 'model' | 'operator' | 'both';
+            };
+            body?: string;
+        };
+    } | undefined>;
+    /** Every registered name, for a "did you mean" that names real options. */
+    names(): readonly string[];
+}
+export interface BackgroundJobRegistryRef {
+    start(params: {
+        command: string;
+        workingDirectory: string;
+    }): {
+        id: string;
+        status: string;
+    };
+    get(id: string): {
+        id: string;
+        status: string;
+        exitCode?: number;
+    };
+    read(id: string, opts?: {
+        fromOffset?: number;
+    }): {
+        chunk: string;
+        nextOffset: number;
+        droppedBytes: number;
+        status: string;
+        exitCode?: number;
+    };
+    kill(id: string): Promise<{
+        id: string;
+        status: string;
+    }>;
+    list(): readonly {
+        id: string;
+        command: string;
+        status: string;
+    }[];
+}
 /**
  * Tracks which files the agent has read in the current run.
  * Write tool consults this to enforce the "read before overwrite" invariant
@@ -109,7 +188,101 @@ export interface ToolContext {
      */
     allowedTools?: readonly string[];
     sandbox?: Sandbox;
+    /**
+     * Symbol resolution for this run, when a host wired one up.
+     *
+     * Absent means the `lsp` tool is not registered at all — see
+     * `tools/builtins/lsp.ts` for why a tool that is always present and
+     * always says "unavailable" is worse than one that is not there.
+     */
+    codeNavigation?: CodeNavigationProvider;
     fileReadTracker?: FileReadTracker;
+    /**
+     * Where work that outlives this call is held.
+     *
+     * Absent means the host has provided nowhere to put a background job, and
+     * a tool asked for one must REFUSE rather than fall back to `cmd &`. The
+     * fallback is not a lesser version of this — under the local sandbox's
+     * `linux-namespace` tier the wrapping `sh` is PID 1 of a fresh PID
+     * namespace, so a backgrounded grandchild dies the moment that shell
+     * exits, on the successful path. It returns in milliseconds looking like
+     * it worked, with the work already dead.
+     */
+    backgroundJobs?: BackgroundJobRegistryRef;
+    /**
+     * Where the `skill` tool reads from.
+     *
+     * Absent means the run has no skills, and the tool says so rather than
+     * reporting an empty list — "no skills here" and "no registry" are
+     * different answers.
+     */
+    skills?: SkillRegistryRef;
+    /**
+     * How this run reaches the web.
+     *
+     * Two independent halves, and either may be absent. This kernel ships a
+     * guarded fetch provider and NO search backend, so `search` missing is
+     * the ordinary case rather than a failure — the tools say which piece is
+     * missing so an operator can tell a wiring decision from a fault.
+     */
+    web?: {
+        readonly fetch?: {
+            fetch(request: {
+                url: string;
+                signal?: AbortSignal;
+            }): Promise<{
+                url: string;
+                status: number;
+                contentType?: string;
+                body: string;
+                truncated: boolean;
+                redirects: readonly string[];
+            }>;
+        };
+        readonly search?: {
+            search(request: {
+                query: string;
+                limit?: number;
+                signal?: AbortSignal;
+            }): Promise<{
+                query: string;
+                hits: readonly {
+                    title: string;
+                    url: string;
+                    snippet?: string;
+                }[];
+            }>;
+        };
+    };
+    /**
+     * Adopt the tool scope a skill declared.
+     *
+     * Called by the `skill` tool when a loaded skill names `allowed-tools`.
+     * The scope INTERSECTS what the turn already allows and takes effect from
+     * the next batch — a skill loaded alongside other calls must not
+     * retroactively refuse them.
+     */
+    adoptSkillScope?: (scope: {
+        skill: string;
+        allowedTools: readonly string[];
+    }) => void;
+    /**
+     * Run another tool through the same dispatch this call came through.
+     *
+     * For `run_code`, whose whole purpose is calling tools in a loop. NOT
+     * added to {@link ToolRegistryRef}: that ref is about discovering and
+     * activating tools, and putting `execute` on it would make "can dispatch"
+     * a property of holding a registry reference rather than a capability a
+     * host wired deliberately.
+     *
+     * Available to every tool, which is worth being explicit about rather
+     * than quietly true. Tools are host-installed code — the model cannot add
+     * one — so the trust boundary this protects is the MODEL's reach, and
+     * that is bounded where it has always been: `allowedTools` is enforced at
+     * dispatch, so a tool calling through here reaches exactly what a
+     * `tool_use` block would have.
+     */
+    dispatchTool?: (name: string, input: unknown) => Promise<ToolResult>;
     /**
      * The `tool_use_id` of the assistant block that triggered this
      * execution. Tools that spawn background work (e.g. coordinator
@@ -204,7 +377,7 @@ export interface ToolResult {
      */
     retryable?: boolean;
 }
-export interface ToolDefinition<TInput = unknown> {
+export interface ToolDefinition<TInput = unknown> extends ToolPresentation<TInput> {
     name: string;
     description: string;
     inputSchema: z.ZodType<TInput, z.ZodTypeDef, unknown>;
@@ -404,4 +577,5 @@ export interface ToolRegistryContract {
     assignTiers(mapping: Record<string, string>): void;
 }
 export * from './repair.js';
+export type { ToolCallView, ToolPresentation, ToolResultView } from './presentation.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/tool/index.d.ts.map

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

package/dist/types/tool/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/tool/index.ts"],"names":[],"mappings":"AAmcA,cAAc,aAAa,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/tool/index.ts"],"names":[],"mappings":"AA4lBA,cAAc,aAAa,CAAA"}

package/dist/types/tool/presentation.d.ts

@@ -0,0 +1,53 @@
+import type { ToolResult } from './index.js';
+/**
+ * How a tool call should be shown, decided by the tool.
+ *
+ * Presentation lived in one host as four free functions switching on a
+ * lowercased tool NAME: `name === 'write'` and `name === 'edit'` got a
+ * diff, everything else got a truncated string. So a tool the host had
+ * never heard of — an MCP server's, a plugin's, a second host's — could
+ * not get a diff no matter what it did, and every new host started from
+ * the raw arguments and rebuilt the same switch.
+ *
+ * The tool knows what it is doing; the host knows how its surface renders.
+ * These are the three shapes one host had already found it needed, closed
+ * deliberately: an open union would let a tool ask for a rendering no host
+ * has, which is a request that fails silently at the far end.
+ */
+export type ToolCallView = 
+/** A line of text. What everything that is not a diff or a command gets. */
+{
+    readonly kind: 'generic';
+    readonly label: string;
+}
+/**
+ * A change to a document. `path` is optional because not every diff is
+ * a file — a tool patching a remote record has a before and an after
+ * and no path a host could open.
+ */
+ | {
+    readonly kind: 'diff';
+    readonly path?: string;
+    readonly before: string;
+    readonly after: string;
+}
+/** A command and what it printed. */
+ | {
+    readonly kind: 'terminal';
+    readonly command?: string;
+    readonly output: string;
+};
+/** The same three shapes, for what a call produced. */
+export type ToolResultView = ToolCallView;
+/**
+ * Optional presentation hooks on a tool definition.
+ *
+ * Both may return `undefined`, which means "no opinion" and is different
+ * from returning a generic view: the first defers to the host's fallback,
+ * the second asserts that a plain label is the right rendering.
+ */
+export interface ToolPresentation<TInput = unknown> {
+    presentCall?(input: TInput): ToolCallView | undefined;
+    presentResult?(input: TInput, result: ToolResult): ToolResultView | undefined;
+}
+//# sourceMappingURL=presentation.d.ts.map

package/dist/types/tool/presentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presentation.d.ts","sourceRoot":"","sources":["../../../src/types/tool/presentation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5C;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,YAAY;AACvB,4EAA4E;AAC1E;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE;AACtD;;;;GAIG;GACD;IACA,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACrB;AACH,qCAAqC;GACnC;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAEpF,uDAAuD;AACvD,MAAM,MAAM,cAAc,GAAG,YAAY,CAAA;AAEzC;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB,CAAC,MAAM,GAAG,OAAO;IACjD,WAAW,CAAC,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAAA;IACrD,aAAa,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,cAAc,GAAG,SAAS,CAAA;CAC7E"}

package/dist/types/tool/presentation.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=presentation.js.map

package/dist/types/tool/presentation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presentation.js","sourceRoot":"","sources":["../../../src/types/tool/presentation.ts"],"names":[],"mappings":""}

package/dist/types/{thread → topic}/entity.d.ts

@@ -1,49 +1,55 @@
 import type { TenantId } from '../ids/index.js';
-import type { ProjectId, ThreadId } from '../session/ids.js';
+import type { ProjectId, TopicId } from '../session/ids.js';
 /**
- * Lifecycle state of a Thread.
+ * Lifecycle state of a Topic.
  *
  * - `open` — accepts new Sessions and new Runs under existing Sessions.
  * - `archived` — read-only tombstone. No new Sessions may be created; existing
  *   Sessions remain navigable. Transitioning `open → archived` requires that
- *   no Session under the Thread is in a non-terminal state (guarded at the
+ *   no Session under the Topic is in a non-terminal state (guarded at the
  *   store level by listing + status fan-in).
  *
- * There is no `active` variant — Thread does NOT derive status from its child
- * Sessions the way a Session does from its Runs. Thread is a pure container
- * (Phase 0 decision B.1: Thread is container-only, no message stream, no
+ * There is no `active` variant — Topic does NOT derive status from its child
+ * Sessions the way a Session does from its Runs. Topic is a pure container
+ * (Phase 0 decision B.1: Topic is container-only, no message stream, no
  * fan-in). Its status is an explicit owner action.
  */
-export type ThreadStatus = 'open' | 'archived';
+export type TopicStatus = 'open' | 'archived';
 /**
  * Topic-level container sitting between {@link ProjectId Project} and
  * {@link import('../session/ids.js').SessionId Session} in the five-layer hierarchy
- * (Project → Thread → Session → SubSession → Run).
+ * (Project → Topic → Session → SubSession → Run).
  *
- * A Thread groups together many Sessions that address the same coherent
+ * NZ-TOPIC-01 renamed this entity from `Thread` to `Topic` — its own docstring
+ * already called it a "Topic-level container" before the identifier caught up.
+ * NZ-TOPIC-04 narrows the exported {@link import('../ids/index.js').TopicId}
+ * from the pre-0.2.0 `thd_` shape to `top_`; on-disk records written under
+ * the old prefix are migrated on read (`store/session/disk.ts`).
+ *
+ * A Topic groups together many Sessions that address the same coherent
  * topic or line-of-work within a Project (e.g. "auth refactor", "billing
- * incident"). Sessions under the same Thread share Project-level shared
+ * incident"). Sessions under the same Topic share Project-level shared
  * resources (memory, vaults, knowledge bases) but have independent actor
  * state, handoff history, and Run streams.
  *
- * ## Why Thread is a first-class layer (A2A-connection surface)
+ * ## Why Topic is a first-class layer (A2A-connection surface)
  *
  * The layer exists because of how enterprise sharing works in Namzu:
  *
  * - **Project is the folder-bound sharing unit.** An enterprise team shares
  *   a Project (`.namzu/` in a repo, a long-lived goal scope). Everyone with
  *   Project access sees its shape but not necessarily its active work.
- * - **Thread is the path-independent, A2A-attachable topic surface.** A
- *   Project can have multiple Threads — one per objective or line-of-work —
- *   and the Threads can be partitioned by device, user, or agent identity.
- *   A2A (agent-to-agent) connections attach at the Thread level: connecting
- *   to a Thread exposes every Session under it and the ability to join the
+ * - **Topic is the path-independent, A2A-attachable topic surface.** A
+ *   Project can have multiple Topics — one per objective or line-of-work —
+ *   and the Topics can be partitioned by device, user, or agent identity.
+ *   A2A (agent-to-agent) connections attach at the Topic level: connecting
+ *   to a Topic exposes every Session under it and the ability to join the
  *   ongoing work.
  * - **Sessions are the immediate work unit.** A user or agent enters a
- *   Thread and opens/resumes Sessions for the concrete interval of work.
+ *   Topic and opens/resumes Sessions for the concrete interval of work.
  *
  * This is the mental model ses_001 ratified (Phase 0, 2026-04-18). The
- * Thread layer has no counterpart elsewhere — it is Namzu's answer to
+ * Topic layer has no counterpart elsewhere — it is Namzu's answer to
  * the question "how do you expose a multi-session topic to A2A without
  * coupling it to the Project's filesystem identity?".
  *
@@ -53,23 +59,25 @@ export type ThreadStatus = 'open' | 'archived';
  *   - Container only. No own message stream, no own Run stream. Messages
  *     live in Sessions (Phase 0 decision B.1).
  *   - `title` is a user-facing label. **Titles are NOT unique within a
- *     Project.** Callers disambiguate by {@link ThreadId}; the title is
+ *     Project.** Callers disambiguate by {@link TopicId}; the title is
  *     freeform display text. If a product surface needs uniqueness (e.g.
  *     a human-typed slug), that constraint lives at the API layer, not in
  *     the kernel.
- *   - `ownerVersion` is the CAS counter for mutations — `updateThread` and
+ *   - `ownerVersion` is the CAS counter for mutations — `updateTopic` and
  *     archival transitions require a matching version and reject
- *     {@link StaleThreadError} on mismatch. Mirrors the
- *     {@link import('./entity.js').Session} handoff CAS pattern (§6.1).
+ *     {@link import('../../session/errors.js').StaleThreadError} on mismatch
+ *     (error class name is unchanged this release — see NZ-TOPIC-01 risks).
+ *     Mirrors the {@link import('./entity.js').Session} handoff CAS pattern
+ *     (§6.1).
  *   - No fan-in `deriveStatus()` helper — status is owner-managed, not
- *     Run-derived. This is the Thread-vs-Session contract boundary.
+ *     Run-derived. This is the Topic-vs-Session contract boundary.
  */
-export interface Thread {
-    id: ThreadId;
+export interface Topic {
+    id: TopicId;
     projectId: ProjectId;
     tenantId: TenantId;
     title: string;
-    status: ThreadStatus;
+    status: TopicStatus;
     ownerVersion: number;
     createdAt: Date;
     updatedAt: Date;

package/dist/types/topic/entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../../../src/types/topic/entity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAE3D;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,UAAU,CAAA;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,MAAM,WAAW,KAAK;IACrB,EAAE,EAAE,OAAO,CAAA;IACX,SAAS,EAAE,SAAS,CAAA;IACpB,QAAQ,EAAE,QAAQ,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,WAAW,CAAA;IACnB,YAAY,EAAE,MAAM,CAAA;IACpB,SAAS,EAAE,IAAI,CAAA;IACf,SAAS,EAAE,IAAI,CAAA;CACf"}

package/dist/types/{thread → topic}/entity.js.map

@@ -1 +1 @@
-{"version":3,"file":"entity.js","sourceRoot":"","sources":["../../../src/types/thread/entity.ts"],"names":[],"mappings":""}
+{"version":3,"file":"entity.js","sourceRoot":"","sources":["../../../src/types/topic/entity.ts"],"names":[],"mappings":""}

package/dist/types/topic/index.d.ts

@@ -0,0 +1,5 @@
+export type { TopicStore, CreateTopicParams } from './store.js';
+export type { Topic, TopicStatus } from './entity.js';
+export { StaleObjectiveError } from './objective.js';
+export type { ObjectiveAdvance, ObjectiveAdvanceResult, ObjectiveBlock, ObjectivePhase, ObjectiveRefusal, ObjectiveRoundVerdict, TopicObjective, } from './objective.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/topic/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/topic/index.ts"],"names":[],"mappings":"AAUA,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAC/D,YAAY,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAErD,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAA;AACpD,YAAY,EACX,gBAAgB,EAChB,sBAAsB,EACtB,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,qBAAqB,EACrB,cAAc,GACd,MAAM,gBAAgB,CAAA"}

package/dist/types/topic/index.js

@@ -0,0 +1,11 @@
+// Sub-barrel for the Topic type surface (Convention #4).
+// Concrete types live in sibling files; re-export them here so consumers
+// import via `../types/topic/index.js`.
+//
+// NZ-TOPIC-01: this barrel used to be `types/thread/index.ts`, exporting
+// `ThreadStore`/`CreateThreadParams`/`Thread`/`ThreadStatus`. None of those
+// four names was ever part of the SDK's public surface (verified against
+// public-runtime.ts / public-types.ts, including their wildcard re-export
+// chains), so they were free to rename outright with no deprecated alias.
+export { StaleObjectiveError } from './objective.js';
+//# sourceMappingURL=index.js.map

package/dist/types/topic/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/topic/index.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,yEAAyE;AACzE,wCAAwC;AACxC,EAAE;AACF,yEAAyE;AACzE,4EAA4E;AAC5E,yEAAyE;AACzE,0EAA0E;AAC1E,0EAA0E;AAK1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAA"}

package/dist/types/topic/objective.d.ts

@@ -0,0 +1,86 @@
+import type { RunId, TenantId, TopicId } from '../ids/index.js';
+/**
+ * Work that outlives one run.
+ *
+ * Nothing in this kernel survived a single `query()` call. `stopWhen` and
+ * `prepareStep` shape one loop, the completion inbox holds one run open for
+ * a worker, and the topic manager owned a container with no work state in
+ * it at all — so a host wanting "keep going until X is done, stop safely if
+ * it stalls or runs long, let a human pause and inspect" had to hand-roll
+ * the store, the round cap and the compare-and-set outside the SDK.
+ *
+ * The Topic's own docstring already called it "one per objective or
+ * line-of-work". This is that objective, written down.
+ */
+export type ObjectivePhase = 'active' | 'paused' | 'blocked' | 'complete';
+/** Why an objective stopped, in a form a caller can branch on. */
+export interface ObjectiveBlock {
+    /**
+     * A code, not just prose. `round_cap` and "the model gave up" are
+     * different situations with different next moves, and a message alone
+     * makes a host parse English to tell them apart.
+     */
+    readonly code: 'round_cap' | 'runner_failed' | 'external';
+    readonly message: string;
+}
+export interface TopicObjective {
+    readonly id: string;
+    readonly topicId: TopicId;
+    readonly tenantId: TenantId;
+    /** Compare-and-set counter, `0` before the first write. */
+    readonly revision: number;
+    readonly objective: string;
+    readonly phase: ObjectivePhase;
+    readonly blockedReason?: ObjectiveBlock;
+    /**
+     * The hard stop.
+     *
+     * Not a suggestion and not a timeout: an objective that cannot tell it
+     * is stuck will keep spending money on rounds that make no progress, and
+     * a wall-clock bound stops a slow objective rather than a stalled one.
+     */
+    readonly maxRounds: number;
+    /**
+     * Rounds BEGUN, not rounds finished.
+     *
+     * Debited before the work runs, so a round that crashes still counts. A
+     * counter that only advanced on success lets an objective failing every
+     * round spin forever, which is precisely the runaway the cap exists to
+     * stop.
+     */
+    readonly roundsStarted: number;
+    readonly lastRunId?: RunId;
+    readonly updatedAt: number;
+}
+/** A write whose `revision` no longer matches what is stored. */
+export declare class StaleObjectiveError extends Error {
+    readonly details: {
+        id: string;
+        expectedRevision: number;
+        actualRevision: number;
+    };
+    constructor(details: {
+        id: string;
+        expectedRevision: number;
+        actualRevision: number;
+    });
+}
+/** Why an `advanceObjective` did nothing. */
+export interface ObjectiveRefusal {
+    readonly kind: 'refused';
+    readonly reason: string;
+    readonly phase: ObjectivePhase;
+}
+export interface ObjectiveAdvance {
+    readonly kind: 'advanced';
+    readonly objective: TopicObjective;
+}
+export type ObjectiveAdvanceResult = ObjectiveAdvance | ObjectiveRefusal;
+/** What one round decided. */
+export interface ObjectiveRoundVerdict {
+    /** `undefined` leaves the phase alone: the round ran and said nothing. */
+    readonly phase?: Extract<ObjectivePhase, 'complete' | 'blocked'>;
+    readonly blockedReason?: ObjectiveBlock;
+    readonly runId?: RunId;
+}
+//# sourceMappingURL=objective.d.ts.map

package/dist/types/topic/objective.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"objective.d.ts","sourceRoot":"","sources":["../../../src/types/topic/objective.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AAE/D;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAA;AAEzE,kEAAkE;AAClE,MAAM,WAAW,cAAc;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,eAAe,GAAG,UAAU,CAAA;IACzD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAA;IAC9B,QAAQ,CAAC,aAAa,CAAC,EAAE,cAAc,CAAA;IACvC;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B;;;;;;;OAOG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,KAAK,CAAA;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC1B;AAED,iEAAiE;AACjE,qBAAa,mBAAoB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,CAAA;gBAEtE,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE;CAOrF;AAED,6CAA6C;AAC7C,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAA;CAC9B;AAED,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAA;CAClC;AAED,MAAM,MAAM,sBAAsB,GAAG,gBAAgB,GAAG,gBAAgB,CAAA;AAExE,8BAA8B;AAC9B,MAAM,WAAW,qBAAqB;IACrC,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,cAAc,EAAE,UAAU,GAAG,SAAS,CAAC,CAAA;IAChE,QAAQ,CAAC,aAAa,CAAC,EAAE,cAAc,CAAA;IACvC,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAA;CACtB"}

package/dist/types/topic/objective.js

@@ -0,0 +1,10 @@
+/** A write whose `revision` no longer matches what is stored. */
+export class StaleObjectiveError extends Error {
+    details;
+    constructor(details) {
+        super(`Stale objective ${details.id}: expected revision=${details.expectedRevision}, actual=${details.actualRevision}`);
+        this.name = 'StaleObjectiveError';
+        this.details = details;
+    }
+}
+//# sourceMappingURL=objective.js.map

package/dist/types/topic/objective.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"objective.js","sourceRoot":"","sources":["../../../src/types/topic/objective.ts"],"names":[],"mappings":"AA2DA,iEAAiE;AACjE,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IACpC,OAAO,CAAkE;IAElF,YAAY,OAAyE;QACpF,KAAK,CACJ,mBAAmB,OAAO,CAAC,EAAE,uBAAuB,OAAO,CAAC,gBAAgB,YAAY,OAAO,CAAC,cAAc,EAAE,CAChH,CAAA;QACD,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAA;QACjC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;IACvB,CAAC;CACD"}

package/dist/types/topic/state.d.ts

@@ -0,0 +1,56 @@
+import type { TenantId, TopicId } from '../ids/index.js';
+import type { PermissionMode } from '../permission/index.js';
+/**
+ * State that outlives a run but belongs to the conversation, not to a run.
+ *
+ * `PermissionMode` was resolved once per run and copied into the executor,
+ * so leaving plan mode meant ending the run and starting a fresh one with
+ * `permissionMode: 'auto'` — discarding the in-flight step and the
+ * tool-schema context with it. The look-around, propose, get-approval,
+ * continue-in-the-SAME-conversation flow could not be built on that, and
+ * `approve_plan` already existed with its approval changing nothing about
+ * the mode.
+ *
+ * Its own record beside the Topic rather than a field on it, with its own
+ * schema version. The Topic record is identity and ownership; this is
+ * mutable session state that changes several times within one conversation
+ * and whose writers are not the Topic's writers. Merging them would make
+ * every mode toggle a CAS conflict against a title rename.
+ */
+export interface TopicState {
+    readonly topicId: TopicId;
+    readonly tenantId: TenantId;
+    /**
+     * Compare-and-set counter, starting at 0 for a record's first write.
+     *
+     * Separate from the Topic's `ownerVersion` on purpose — see above. A
+     * host toggling the mode and a manager renaming the topic must not
+     * invalidate each other.
+     */
+    readonly revision: number;
+    readonly permissionMode: PermissionMode;
+    /**
+     * Messages left for the run that has not started yet.
+     *
+     * On the same record as the mode and under the same revision, so a host
+     * queueing a message and one toggling the mode cannot silently overwrite
+     * each other — they collide loudly instead, which is what a shared
+     * conversation needs.
+     */
+    readonly queuedMessages?: readonly import('../message/index.js').Message[];
+    readonly updatedAt: number;
+}
+/** A write whose `revision` no longer matches what is stored. */
+export declare class StaleTopicStateError extends Error {
+    readonly details: {
+        topicId: TopicId;
+        expectedRevision: number;
+        actualRevision: number;
+    };
+    constructor(details: {
+        topicId: TopicId;
+        expectedRevision: number;
+        actualRevision: number;
+    });
+}
+//# sourceMappingURL=state.d.ts.map

package/dist/types/topic/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../src/types/topic/state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AACxD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAE5D;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAA;IACvC;;;;;;;OAOG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,OAAO,qBAAqB,EAAE,OAAO,EAAE,CAAA;IAC1E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC1B;AAED,iEAAiE;AACjE,qBAAa,oBAAqB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,OAAO,EAAE;QACjB,OAAO,EAAE,OAAO,CAAA;QAChB,gBAAgB,EAAE,MAAM,CAAA;QACxB,cAAc,EAAE,MAAM,CAAA;KACtB,CAAA;gBAEW,OAAO,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE;CAO3F"}

package/dist/types/topic/state.js

@@ -0,0 +1,10 @@
+/** A write whose `revision` no longer matches what is stored. */
+export class StaleTopicStateError extends Error {
+    details;
+    constructor(details) {
+        super(`Stale topic state for ${details.topicId}: expected revision=${details.expectedRevision}, actual=${details.actualRevision}`);
+        this.name = 'StaleTopicStateError';
+        this.details = details;
+    }
+}
+//# sourceMappingURL=state.js.map

package/dist/types/topic/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../../src/types/topic/state.ts"],"names":[],"mappings":"AA4CA,iEAAiE;AACjE,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IACrC,OAAO,CAIf;IAED,YAAY,OAA+E;QAC1F,KAAK,CACJ,yBAAyB,OAAO,CAAC,OAAO,uBAAuB,OAAO,CAAC,gBAAgB,YAAY,OAAO,CAAC,cAAc,EAAE,CAC3H,CAAA;QACD,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAA;QAClC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;IACvB,CAAC;CACD"}