@try-works/dsh-tool-mode 0.0.0-stage → 0.5.45

package/lib/planning.d.ts

@@ -0,0 +1,256 @@
+/**
+ * The host-side `tools_plan` discipline (NDL-02, NDL-03).
+ *
+ * The Needle extension implements the ENGINE half of the planning contract: one-shot
+ * proposals over a caller-supplied tool list, with the list validated by the extension
+ * itself. What NDL-02 forbids is the HOST trusting that caller-supplied list. The list is
+ * the authorization surface: whatever schemas the planner receives, it may propose calls
+ * against, and a caller who could hand over the whole registry — or a list of its own
+ * invention — would be using `tools_plan` as a permission oracle. So the host owns four
+ * things the extension never sees:
+ *
+ * 1. **The frozen snapshot.** At first use, the host captures the currently registered
+ *    tool schemas (name, description, parameters — nothing executable) into a snapshot
+ *    that is deep-copied and deep-frozen. Later registry changes cannot leak into it, and
+ *    a holder of the snapshot cannot mutate it. The planner receives ONLY entries from
+ *    this snapshot; it never receives the caller's declared tool list, an unfiltered
+ *    registry, or anything callable (NDL-02's "narrow public broker").
+ *
+ * 2. **The requested-name gate.** The caller asks for names; the host intersects them
+ *    with the LIVE registry. Unknown names (never registered, or withdrawn), excluded
+ *    names (management and composition), duplicates, and live-but-unsnapshotted names are
+ *    all REJECTED — the whole call fails with every rejection named, never a silently
+ *    smaller offer set (the CODE-03 "reject rather than omit" discipline).
+ *
+ * 3. **Host-side re-validation.** When the provider returns proposals, the host
+ *    re-validates every proposal against the SNAPSHOT schema, not the provider's own
+ *    verdict. A proposal the engine fabricated outside the offered set, or arguments that
+ *    violate the frozen schema, are moved to `rejected` with the violations named.
+ *
+ * 4. **Fresh policy checks.** A proposal is DATA; executing it goes through the registry's
+ *    own admission later (NDL-03). The host still refuses to return a proposal whose tool
+ *    is no longer registered — deactivated or withdrawn after the snapshot was captured —
+ *    so a caller never receives a proposal for a tool that is not currently callable.
+ *
+ * Everything here is a pure function over plain data: the DSH context, the store and the
+ * lifecycle stay in the host wiring, so the discipline is testable without mounting a
+ * plugin and without the pinned engine artifacts.
+ *
+ * @module @try-works/dsh-tool-mode/planning
+ */
+/** The caller-facing name of the planning contract (NDL-02). */
+export declare const PLANNING_TOOL_NAME = "tools_plan";
+/**
+ * Tool names the planning surface must never offer or propose (NDL-02 + CODE-07).
+ *
+ * The program-binding exclusions are reused rather than restated: a proposal targeting
+ * `tool_mode_run` (the recursive composition door) or the management surface would hand a
+ * caller the same proxy grant CODE-07 withholds from programs. `tools_plan` itself is
+ * added so a plan can never propose planning — recursive planning is noise, and the
+ * planning tool is not a leaf inference tool.
+ *
+ * SEALED like {@link EXCLUDED_BINDINGS} — a frozen ARRAY, because freezing a `Set` does
+ * not stop `add`/`delete` — so the planning surface and the program-binding surface
+ * cannot desynchronize through a runtime mutation.
+ */
+export declare const PLANNING_EXCLUDED_TOOLS: readonly string[];
+/**
+ * Intersect the live registry with the planner's exclusions AND, when present, the
+ * external caller's grant (SEC-04/NDL-02). An external caller granted only
+ * `tools_plan` must not plan over tools it could not invoke itself.
+ * @param names - live registry tool names.
+ * @param excluded - tool names the planner never offers.
+ * @param callerGrant - the external client's granted names, or undefined for the host.
+ * @returns the eligible leaf set.
+ */
+export declare function filterPlanningLiveTools(names: readonly string[], excluded?: readonly string[], callerGrant?: readonly string[]): ReadonlySet<string>;
+/** The registry view a tool schema is captured from (the DSH `ToolSchema` projection). */
+export interface RegistryToolSchema {
+    readonly name: string;
+    readonly description: string;
+    /** The model-facing JSON Schema of the arguments. */
+    readonly parameters: Readonly<Record<string, unknown>>;
+}
+/** One frozen entry in the snapshot. */
+export interface SnapshotTool {
+    readonly name: string;
+    readonly description: string;
+    /** Deep-frozen: the snapshot is data nobody can edit after capture. */
+    readonly parameters: Readonly<Record<string, unknown>>;
+}
+/** The frozen host-approved schema snapshot (NDL-02). */
+export interface ToolSchemaSnapshot {
+    /** The catalog generation at capture, so a snapshot is attributable. */
+    readonly generation: number;
+    /** Frozen entries, keyed by name. */
+    readonly tools: ReadonlyMap<string, SnapshotTool>;
+}
+/**
+ * Capture the frozen host-approved tool schema snapshot (NDL-02).
+ *
+ * The capture is a DEEP COPY: mutating the registry afterwards — registering a tool,
+ * withdrawing one, changing a description — cannot change the snapshot, and mutating the
+ * snapshot is refused by the runtime because every node is frozen. Excluded names are
+ * skipped rather than captured-then-filtered, so a management tool's schema never enters
+ * the snapshot at all.
+ *
+ * An empty description is replaced with a stated placeholder rather than captured empty:
+ * the planner-side input contract requires a non-empty description, and a capture that
+ * guaranteed a later refusal would freeze a call failure into the snapshot.
+ * @param schemas - the registry view at capture time.
+ * @param options - the generation, and optionally the excluded names (defaults to
+ *   {@link PLANNING_EXCLUDED_TOOLS}).
+ * @returns the frozen snapshot.
+ */
+export declare function captureToolSchemaSnapshot(schemas: readonly RegistryToolSchema[], options: {
+    readonly generation: number;
+    readonly excluded?: readonly string[];
+}): ToolSchemaSnapshot;
+/** Why one requested name was refused. */
+export interface PlanningRejection {
+    readonly name: string;
+    readonly reason: 'duplicate' | 'excluded' | 'unknown' | 'not-in-snapshot';
+    /** What the caller can do about it. */
+    readonly remedy: string;
+}
+/** The outcome of the requested-name gate. */
+export type PlanningDecision = {
+    readonly ok: true;
+    readonly offered: readonly SnapshotTool[];
+} | {
+    readonly ok: false;
+    readonly rejections: readonly PlanningRejection[];
+};
+/**
+ * Intersect the requested names with the live registry and the frozen snapshot (NDL-02).
+ *
+ * All-or-nothing, mirroring the CODE-03 bindings gate: if ANY requested name is
+ * unattainable the whole call is refused with every rejection named, because handing the
+ * caller a smaller offer set than it asked for would produce a plan for a different
+ * request than the one it stated.
+ * @param snapshot - the frozen snapshot, the ONLY source of schemas.
+ * @param requested - the names the caller asked to plan over.
+ * @param liveLeaf - the leaf tool names currently registered, exclusions already applied.
+ * @param excluded - the names refused by policy regardless of registration. Defaults to
+ *   {@link PLANNING_EXCLUDED_TOOLS}.
+ * @returns the offered entries, or every rejection.
+ */
+export declare function offerToolsFromSnapshot(snapshot: ToolSchemaSnapshot, requested: readonly string[], liveLeaf: ReadonlySet<string>, excluded?: readonly string[]): PlanningDecision;
+/**
+ * Describe a refused request for a caller (NDL-02).
+ * @param rejections - the refusals.
+ * @returns a readable summary naming every rejection and why.
+ */
+export declare function describePlanningRejections(rejections: readonly PlanningRejection[]): string;
+/** One proposal record, normalized from the provider's payload. */
+export interface ProposalEntry {
+    readonly name: string;
+    readonly arguments: Record<string, unknown>;
+    readonly offered: boolean;
+    readonly valid: boolean;
+    readonly issues: readonly string[];
+}
+/** What a re-check pass produced. */
+export interface RecheckOutcome {
+    /** The payload with proposals that failed any re-check moved to `rejected`. */
+    readonly payload: Record<string, unknown>;
+    /** Non-fatal notes naming what was moved; free of caller content. */
+    readonly warnings: readonly string[];
+}
+/**
+ * Raised when a provider returns a proposal record that is not proposal-shaped.
+ *
+ * The provider's declared output contract types every field and closes the record, so a
+ * malformed entry is a PROVIDER DEFECT — and it is surfaced as one rather than silently
+ * coerced. Coercing a non-object `arguments` into `{}` would present a record the
+ * provider never produced as if the host had validated it, and dropping undeclared
+ * fields would hide a contract violation the output validator should refuse.
+ */
+export declare class ProviderDefectError extends Error {
+    readonly name = "ProviderDefectError";
+}
+/**
+ * Re-check the provider's proposals against the frozen snapshot, the per-call offered set
+ * AND the live authorization state (NDL-02, NDL-03).
+ *
+ * The provider's own validation is not trusted here: it validated against the list the
+ * HOST built, but the host still re-checks every proposal before it reaches a caller,
+ * because a proposal is the one thing a caller will treat as authorized. Four checks:
+ *
+ * - the name must be IN the frozen snapshot (the engine cannot invent a plannable tool);
+ * - the arguments must satisfy the SNAPSHOT's schema, compiled fresh per snapshot entry;
+ * - the name must be in the OFFERED set for THIS call — a provider proposing a tool the
+ *   caller never requested must not pass it through as valid, even when it is
+ *   snapshotted, schema-valid and still registered;
+ * - the tool must STILL BE AUTHORIZED right now (NDL-03): a tool deactivated, withdrawn
+ *   or quarantined after capture fails the fresh policy check, and the proposal is
+ *   refused rather than returned as if it were executable.
+ *
+ * A proposal failing any check is MOVED to `rejected` with the issues appended, and one
+ * bounded warning per moved proposal is returned for the receipt and the meta envelope.
+ * A proposal record that is not proposal-shaped throws {@link ProviderDefectError}: the
+ * defect belongs to the provider, and silently repairing it would hide the violation.
+ * @param snapshot - the frozen snapshot.
+ * @param payload - the provider's result.
+ * @param offeredNames - the names the HOST offered for this call.
+ * @param isCurrentlyAuthorized - the live authorization predicate, read at re-check time;
+ *   `true` admits, a string is the refusal reason.
+ * @returns the amended payload and the warnings.
+ */
+export declare function recheckProposals(snapshot: ToolSchemaSnapshot, payload: Record<string, unknown>, offeredNames: ReadonlySet<string>, isCurrentlyAuthorized: (name: string) => true | string): RecheckOutcome;
+/**
+ * The input the HOST advertises and validates for `tools_plan` (NDL-02).
+ *
+ * The caller names tools as STRINGS — a requested eligible subset, never a grant and
+ * never full declarations. The extension's own shipped input schema (full tool objects)
+ * remains its provider contract; the host is the broker that turns requested names into
+ * snapshot entries, so a caller never supplies the schemas the planner reasons over.
+ * Bounds mirror the shipped extension input, so the advertised surface and the transport
+ * surface cannot admit different requests.
+ */
+export declare const PLANNING_TOOL_INPUT_SCHEMA: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["request", "tools"];
+    readonly properties: {
+        readonly request: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly maxLength: 32768;
+            readonly description: "The user request the plan is derived from, verbatim.";
+        };
+        readonly tools: {
+            readonly type: "array";
+            readonly minItems: 1;
+            readonly maxItems: 64;
+            readonly description: "The tool names to plan over. A requested eligible subset, never a grant; unknown or excluded names refuse the call.";
+            readonly items: {
+                readonly type: "string";
+                readonly minLength: 1;
+            };
+        };
+        readonly system: {
+            readonly type: "string";
+            readonly maxLength: 4096;
+            readonly description: "Session facts the model should assume: the date, the locale, the device.";
+        };
+        readonly max_new_tokens: {
+            readonly type: "integer";
+            readonly minimum: 16;
+            readonly maximum: 4096;
+            readonly description: "Response-token budget for the planner.";
+        };
+    };
+};
+/**
+ * Whether a declared input schema has the planning shape (a `tools` array property).
+ *
+ * The NAME alone is not enough to treat a contribution as the planning contract: a
+ * package that named a tool `tools_plan` without the planning input would otherwise be
+ * served through the planning pipeline and fail in ways nobody could see. The name plus
+ * the shape is the contract; the host refuses the name without the shape.
+ * @param schema - the declared input schema.
+ * @returns whether the schema declares an array-valued `tools` property.
+ */
+export declare function hasPlanningInputShape(schema: Readonly<Record<string, unknown>> | undefined): boolean;
+//# sourceMappingURL=planning.d.ts.map

package/lib/planning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planning.d.ts","sourceRoot":"","sources":["../src/planning.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAiBH,gEAAgE;AAChE,eAAO,MAAM,kBAAkB,eAAe,CAAA;AAE9C;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,uBAAuB,mBAA4D,CAAA;AAEhG;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,QAAQ,GAAE,SAAS,MAAM,EAA4B,EACrD,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,GAC9B,WAAW,CAAC,MAAM,CAAC,CAMrB;AAED,0FAA0F;AAC1F,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,qDAAqD;IACrD,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CACvD;AAED,wCAAwC;AACxC,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CACvD;AAED,yDAAyD;AACzD,MAAM,WAAW,kBAAkB;IACjC,wEAAwE;IACxE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,qCAAqC;IACrC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;CAClD;AA0CD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,SAAS,kBAAkB,EAAE,EACtC,OAAO,EAAE;IAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC9E,kBAAkB,CA8BpB;AAED,0CAA0C;AAC1C,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,UAAU,GAAG,SAAS,GAAG,iBAAiB,CAAA;IACzE,uCAAuC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,8CAA8C;AAC9C,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAA;CAAE,GAChE;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,SAAS,iBAAiB,EAAE,CAAA;CAAE,CAAA;AAE7E;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,kBAAkB,EAC5B,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,EAC7B,QAAQ,GAAE,SAAS,MAAM,EAA4B,GACpD,gBAAgB,CA2ClB;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,SAAS,iBAAiB,EAAE,GAAG,MAAM,CAG3F;AAED,mEAAmE;AACnE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC3C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;CACnC;AAED,qCAAqC;AACrC,MAAM,WAAW,cAAc;IAC7B,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACzC,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CACrC;AAED;;;;;;;;GAQG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,SAAkB,IAAI,yBAAwB;CAC/C;AAmDD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,EACjC,qBAAqB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,GACrD,cAAc,CA0FhB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8B7B,CAAA;AAEV;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,GAAG,OAAO,CAQpG"}