@namzu/sdk 46.0.0 → 48.0.0

package/dist/toolsets/manager.d.ts

@@ -0,0 +1,201 @@
+import type { ToolResultGuardrailSpec } from '../types/guardrail/index.js';
+import type { Message, ToolRevealReceipt } from '../types/message/index.js';
+import type { LLMToolSchema, PreparedToolExecution, ToolAvailability, ToolContext, ToolDefinition, ToolExecutionResult, ToolPreparationResult, ToolTierConfig, ToolsView } from '../types/tool/index.js';
+import type { ToolSourceRef, Toolset } from './types.js';
+export type { ToolExecutionResult };
+/**
+ * What `refresh()` reports after re-resolving a live toolset's change.
+ *
+ * `refused` is a newly-contributed name that would have collided with a name
+ * already served by another toolset — the incumbent keeps serving and the
+ * newcomer never reaches the manager, unlike a construction-time collision,
+ * which throws instead (nothing was serving anyone yet, so there is nothing
+ * to protect by continuing).
+ */
+export interface ToolsetChangeReport {
+    /** Names a toolset started contributing that nobody else already served. */
+    readonly added: readonly string[];
+    /** Names whose owning toolset stopped contributing them, with no other toolset picking them up. */
+    readonly removed: readonly string[];
+    /**
+     * Names whose OWNING toolset now returns a different `ToolDefinition`
+     * object under the same name. The previously admitted definition keeps
+     * serving — see the class doc on why identity, not content, is what
+     * `toLLMTools`'s prompt-cache stability depends on.
+     */
+    readonly drifted: readonly string[];
+    /** A new contributor for a name some other toolset already serves. Refused, not applied. */
+    readonly refused: readonly {
+        readonly name: string;
+        readonly reason: string;
+    }[];
+}
+export interface ToolManagerConfig {
+    readonly toolsets: readonly Toolset[];
+    /**
+     * Screens run against every tool result before anything downstream reads
+     * it. Wins over whatever the turn's own `ToolContext.toolResultGuardrails`
+     * supplies when this is present — including `[]`, which means none —
+     * because a manager built with an explicit policy has stated it. See
+     * `executeRetained` below.
+     */
+    readonly resultGuardrails?: readonly ToolResultGuardrailSpec[];
+    readonly tierConfig?: ToolTierConfig;
+    /**
+     * The turn's own message history, read fresh on every `availability`
+     * call rather than captured once — see {@link ToolManager.availability}.
+     */
+    readonly messages: () => readonly Message[];
+}
+/**
+ * The runtime-owned resolver of {@link Toolset}s.
+ *
+ * It is built once from a fixed list of toolsets and never mutates its own
+ * membership: a toolset changing live (`onChange`) is only adopted when the caller calls
+ * {@link refresh}, at an iteration boundary the caller chooses — never
+ * mid-call. This is what keeps `toLLMTools`'s wire rendering byte-stable
+ * between refreshes: `toolWireSchema` (`registry/tool/schema.ts`) memoizes a
+ * tool's rendered schema by the object identity of `ToolDefinition.inputSchema`,
+ * not by anything owned by whichever object resolved the tool, so returning
+ * the SAME `ToolDefinition` object for the same name across calls — which a
+ * fixed, never-mutated resolution trivially does — is what keeps the cache
+ * hit.
+ *
+ * Availability has no stored, mutable map (unlike `ToolRegistry.availability`).
+ * It is DERIVED: an unready source is suspended; otherwise a tool is
+ * deferred iff its owner declared `deferred()` and no source-bound receipt
+ * in the turn's post-compaction history has loaded its schema. See
+ * {@link ToolManager.availability}.
+ *
+ * The execution pipeline below (`prepareExecution`/`executePrepared`/
+ * `execute`/`executeRetained`) is copied from `ToolRegistry`'s, per plan.md
+ * §2: "Diff it line by line; the only permitted changes are where it read
+ * `this.availability`, `tool.provenance` or registry identity." Those three
+ * substitutions are exactly: `this.availability(name)` (derived, above) for
+ * `this.getAvailability(name)`; `this.sourceOf(name)` for `tool.provenance`;
+ * and `this.toolsByName` for `this.items`. Every check, in the same order,
+ * with the same messages, is unchanged.
+ */
+export declare class ToolManager {
+    private readonly toolsets;
+    private readonly resultGuardrails?;
+    private readonly tierConfig?;
+    private readonly messagesAccessor;
+    private readonly log;
+    private toolsByName;
+    private ownerToolsetByName;
+    private defaultAvailabilityByName;
+    /**
+     * The object each name's owning toolset returned the LAST time `refresh()`
+     * (or construction) observed it — distinct from `toolsByName`, which holds
+     * whatever was first admitted under that name and never changes on drift.
+     * `refresh()` diffs against this map, not `toolsByName`, so a name that
+     * drifted once and has been stable ever since is not reported as drifted
+     * again just because some unrelated toolset's change forced a re-walk.
+     */
+    private lastObservedByName;
+    private dirty;
+    private readonly unsubscribeToolsetChanges;
+    private disposed;
+    private readonly preparations;
+    constructor(config: ToolManagerConfig);
+    /** Stop observing live toolsets when this manager's owner finishes; the host owns their connections. */
+    dispose(): void;
+    /**
+     * First resolution, at construction. Toolset order, then tool order,
+     * matching `combineToolsets` (`./combine.ts`) — a name contributed by two
+     * sources throws {@link ToolsetConflictError} naming both, because
+     * nothing has served anyone yet: unlike {@link refresh}, there is no
+     * incumbent to protect by refusing the newcomer instead.
+     */
+    /**
+     * The checks `ToolRegistry.registerOne` used to run before admitting a
+     * tool, copied verbatim: a legal name; `enforceModelInput` requires a
+     * `modelInputSchema` (nothing to constrain generation against
+     * otherwise) and that schema must itself fit the strict-decoding subset
+     * `assertStrictSchema` checks (existing is not enough — it also has to
+     * be sendable); a declared `tier` must be one `this.tierConfig` lists.
+     */
+    private assertAdmissible;
+    private resolveInitial;
+    /**
+     * Re-resolve iff a toolset signalled change (`onChange`) since
+     * construction or the last `refresh()` — otherwise returns `undefined`
+     * without re-walking anything, so a caller that refreshes every
+     * iteration boundary pays nothing on the common case where nothing
+     * changed.
+     *
+     * Three outcomes per name, matching plan.md §2:
+     *  - A name only ONE current toolset contributes, that nobody served
+     *    before: `added`.
+     *  - A name a toolset served before and stopped, with no other toolset
+     *    now contributing it: `removed`.
+     *  - A name still contributed by its ORIGINAL owning toolset, under a
+     *    `ToolDefinition` object different from the one that toolset returned
+     *    the LAST time it was observed (construction, or the previous
+     *    `refresh()`): `drifted` — the previously admitted definition keeps
+     *    serving; the new object is held, not adopted, so `toolWireSchema`'s
+     *    identity-keyed cache (see the class doc) survives a live toolset's
+     *    own internal change. Comparing against the last OBSERVATION, not
+     *    the served object, means a name that drifted once and has been
+     *    stable since is reported only on the refresh where it actually
+     *    changed, not again on every later refresh some unrelated toolset's
+     *    change happens to trigger.
+     *  - A name some OTHER toolset starts contributing while its incumbent
+     *    owner still serves it: `refused` — the incumbent wins regardless of
+     *    toolset order; the newcomer is reported, never applied.
+     */
+    refresh(): ToolsetChangeReport | undefined;
+    has(name: string): boolean;
+    get(name: string): ToolDefinition | undefined;
+    listNames(): string[];
+    /** Where `name` came from. Throws for an unknown name, like {@link getOrThrow}. */
+    sourceOf(name: string): ToolSourceRef;
+    private getOrThrow;
+    /**
+     * `'suspended'` when the owning toolset is unready; otherwise `'deferred'`
+     * when it declared deferred and no matching receipt exists in the
+     * post-compaction history; otherwise `'active'`.
+     *
+     * Nothing here is stored: this is a pure read of the toolset's own
+     * declaration plus a scan of `messages()`, recomputed on every call — the
+     * same "safe to call repeatedly, byte-identical between calls" property
+     * `toLLMTools` already has. The scan is bounded to the window AFTER the
+     * last compaction summary (`compaction/summary.ts`'s
+     * `isCompactionMessage` — the one marker a compacted history carries, a
+     * system message whose content starts with `COMPACTION_HEADER`):
+     * compaction is the one deliberate "forget" boundary a derivation like
+     * this one needs, the same way it is the one boundary namzu's own
+     * summarisation treats as a reset. A tool message's own `revealedTools`
+     * (`types/message/index.ts`) is written by the executor from
+     * `ToolResult.reveals`, persisted like any other message field — there is
+     * no separate store to keep in sync, restore on resume, or lose across a
+     * fork.
+     */
+    availability(name: string): ToolAvailability;
+    private wasRevealed;
+    /** Bind a reveal to the source currently serving the named tool. */
+    revealReceipt(name: string): ToolRevealReceipt;
+    private getByAvailability;
+    /**
+     * Ranked lexical search over deferred tools — same scoring
+     * `ToolRegistry.searchDeferred` used (exact name 12 / name-substring 8 /
+     * description 5 / argument-name 3, generic tokens stopped), extended
+     * with an optional cap so a caller does not have to slice the result
+     * itself.
+     */
+    searchDeferred(query: string, limit?: number): readonly ToolDefinition[];
+    private searchByAvailability;
+    toLLMTools(names?: readonly string[]): LLMToolSchema[];
+    toPromptSection(names?: readonly string[]): string;
+    toTierGuidance(): string | null;
+    /** What `ToolContext` gives a running tool: read-only, no mutation. */
+    view(): ToolsView;
+    prepareExecution(toolName: string, rawInput: unknown): ToolPreparationResult;
+    executePrepared(prepared: PreparedToolExecution, context: ToolContext): Promise<ToolExecutionResult>;
+    execute(toolName: string, rawInput: unknown, context: ToolContext): Promise<ToolExecutionResult>;
+    private rejectPreparationWithClosedSpan;
+    private executeRetained;
+    private validationFailure;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/toolsets/manager.d.ts.map

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