@intx/agent 0.2.2 → 0.3.0

package/README.md

@@ -16,13 +16,13 @@ import {
   defineAgent,
 } from "@intx/agent";
 import { noopAuditStore, permissiveAuthorize } from "@intx/agent/testing";
-import { createIsogitStore } from "@intx/storage-isogit";
+import { createIsogitStore } from "@intx/storage-isogit/node";
 
 // `apiKey` and `model` come from the caller's env / config; pick the
 // shape that fits the deployment. The snippet below uses literals so
 // it copy-pastes cleanly.
 const apiKey = process.env.ANTHROPIC_API_KEY ?? "";
-const model = "claude-sonnet-4-6";
+const model = "claude-sonnet-5";
 const source = {
   id: `anthropic:${model}`,
   provider: "anthropic",

package/dist/agent.d.ts

@@ -1,5 +1,5 @@
 import { type ReactorEmittedEvent } from "@intx/inference";
-import type { BlobReader, ContextCommit, ConversationTurn, InboundMessage, InferenceSource } from "@intx/types/runtime";
+import type { ApprovalSnapshot, BlobReader, ContextCommit, ConversationTurn, InboundMessage, InferenceSource } from "@intx/types/runtime";
 import type { AgentDefinition } from "./definition.js";
 import type { BaseEnv } from "./env.js";
 export type SendOptions = {
@@ -17,6 +17,7 @@ export type SendOptions = {
     from?: string;
 };
 export type SendResult = {
+    type: "reply";
     /** Reply text emitted by the director's `reply` action. */
     reply: string;
     /**
@@ -24,7 +25,35 @@ export type SendResult = {
      * the reactor's `inference.done` event preceding `connector.reply`.
      */
     turn: ConversationTurn;
+} | {
+    /**
+     * The reactor parked on a gate before producing a reply. The cycle
+     * is not finished -- it will resume when the correlated external
+     * decision is delivered. `correlationId` identifies the pending
+     * operation the caller resumes against.
+     */
+    type: "suspended";
+    correlationId: string;
+    /**
+     * Approver-facing snapshot of the parked tool call, when the reactor
+     * carried one on the gate-blocked event. Forwarded so the runtime can
+     * register it with the suspension. Absent for suspensions with no
+     * snapshot (an authz extension wired with no tool definitions).
+     */
+    approvalSnapshot?: ApprovalSnapshot;
 };
+/**
+ * A `reactor.gate.blocked` event settled the active send but carried no
+ * `correlationId`, so the resulting suspension has no handle a caller
+ * could resume against. The reactor omits `correlationId` for gates
+ * parked without a correlation (e.g. a director suspend with no
+ * correlated external decision), and `send()` cannot hand back an
+ * unresumable outcome -- it surfaces this instead.
+ */
+export declare class GateSuspendedWithoutCorrelationError extends Error {
+    readonly gateId: string;
+    constructor(gateId: string);
+}
 export type Agent = {
     send(content: string | InboundMessage, opts?: SendOptions): Promise<SendResult>;
     stream(): AsyncIterable<ReactorEmittedEvent>;

package/dist/agent.js

@@ -71,6 +71,22 @@ const DEFAULT_SEND_TO = "agent@local";
 const DEFAULT_SEND_QUEUE_MAX = 16;
 const DEFAULT_STREAM_BUFFER_MAX = 1024;
 const DEFAULT_CLOSE_TIMEOUT_MS = 5000;
+/**
+ * A `reactor.gate.blocked` event settled the active send but carried no
+ * `correlationId`, so the resulting suspension has no handle a caller
+ * could resume against. The reactor omits `correlationId` for gates
+ * parked without a correlation (e.g. a director suspend with no
+ * correlated external decision), and `send()` cannot hand back an
+ * unresumable outcome -- it surfaces this instead.
+ */
+export class GateSuspendedWithoutCorrelationError extends Error {
+    gateId;
+    constructor(gateId) {
+        super(`reactor suspended on gate ${gateId} without a correlationId; the send has no handle to resume against`);
+        this.name = "GateSuspendedWithoutCorrelationError";
+        this.gateId = gateId;
+    }
+}
 export class AgentClosedError extends Error {
     constructor() {
         super("agent is closed");
@@ -391,7 +407,34 @@ export async function createAgent(def, env) {
                     const turn = activeCycle.lastAssistantTurn ??
                         buildSyntheticTurn(event.data.content);
                     activeCycle = null;
-                    sendQueue.resolveActive({ reply: event.data.content, turn });
+                    sendQueue.resolveActive({
+                        type: "reply",
+                        reply: event.data.content,
+                        turn,
+                    });
+                }
+                else if (event.type === "reactor.gate.blocked") {
+                    // The reactor parked on a gate before producing a reply. This
+                    // is a terminal outcome for the active send: the cycle will not
+                    // continue until the correlated external decision is delivered,
+                    // and a parked cycle does not emit connector.reply or
+                    // reactor.done, so leaving the send unsettled would hang the
+                    // caller. Resolve with the suspended outcome so the caller can
+                    // resume against the correlationId. A gate parked without a
+                    // correlationId is unresumable -- surface it rather than hand
+                    // back an outcome with no handle.
+                    const { correlationId, approvalSnapshot } = event.data;
+                    activeCycle = null;
+                    if (correlationId === undefined) {
+                        sendQueue.rejectActive(new GateSuspendedWithoutCorrelationError(event.data.gateId));
+                    }
+                    else {
+                        sendQueue.resolveActive({
+                            type: "suspended",
+                            correlationId,
+                            ...(approvalSnapshot !== undefined ? { approvalSnapshot } : {}),
+                        });
+                    }
                 }
                 else if (event.type === "reactor.error" && event.data.fatal) {
                     // Only fatal reactor errors terminate the active send. Non-fatal
@@ -451,6 +494,7 @@ export async function createAgent(def, env) {
             onEvent: handleEvent,
             auditStore,
             authorize,
+            toolDefinitions: resolvedTools.definitions,
             onShutdown: async () => {
                 try {
                     await flushErrors();

package/dist/definition.d.ts

@@ -1,3 +1,4 @@
+import type { ToolPackagePin } from "@intx/types/tool-packages";
 import type { AnnotatedToolFactory } from "./tool.js";
 import type { BaseEnv } from "./env.js";
 import type { DirectorRef } from "./director-types.js";
@@ -37,6 +38,19 @@ export interface AgentDefinition<EnvReq extends BaseEnv = BaseEnv> {
     readonly systemPrompt: string;
     readonly director?: DirectorRef;
     readonly toolFactories: readonly AnnotatedToolFactory<EnvReq>[];
+    /**
+     * Tool-package names whose `definePlugin` factories this agent uses
+     * (`["@intx/tools-lsp"]`). Unlike a tool factory -- which the agent
+     * imports and places in `toolFactories`, so it is agent-visible -- a
+     * plugin package contributes NO agent-visible factory: its plugin
+     * factory reaches the agent only through `env.plugins`, wired by the
+     * host. This explicit per-agent list is therefore the only way per-step
+     * plugin scoping and the plugin's contributed tool grants can be known
+     * from the definition alone. The field is part of the hashed wire
+     * surface (the live->inert projector carries it), so a tampered plugin
+     * set fails re-verify. Absent when the agent uses no plugins.
+     */
+    readonly plugins?: readonly string[];
     readonly capabilities: readonly string[];
     readonly inference: {
         readonly sources: readonly InferencePreference[];
@@ -56,6 +70,13 @@ export interface AgentDefinition<EnvReq extends BaseEnv = BaseEnv> {
      * encoded JSON in a tag value.
      */
     readonly tags?: Readonly<Record<string, string>>;
+    /**
+     * Tool-package pins the sidecar materializes for this agent, carried on the
+     * definition so a folded workflow asset is self-contained rather than
+     * depending on pins supplied only at deploy time. Plain-data mirror of the
+     * pins the deploy-tree tool channel consumes.
+     */
+    readonly toolPackagePins?: readonly ToolPackagePin[];
 }
 type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
 type EnvRequiredBy<F> = F extends AnnotatedToolFactory<infer E> ? E : never;
@@ -101,6 +122,8 @@ export interface DefineAgentConfig<Factories extends readonly AnnotatedToolFacto
     readonly systemPrompt: string;
     readonly director?: DirectorRef;
     readonly tools: Factories;
+    /** Plugin-package names this agent uses; see `AgentDefinition.plugins`. */
+    readonly plugins?: readonly string[];
     readonly capabilities: readonly string[];
     readonly inference: {
         readonly sources: readonly InferencePreference[];

package/dist/definition.js

@@ -29,6 +29,7 @@ export function defineAgent(config) {
         toolFactories,
         capabilities: config.capabilities,
         inference: config.inference,
+        ...(config.plugins !== undefined ? { plugins: config.plugins } : {}),
         ...(config.description !== undefined
             ? { description: config.description }
             : {}),

package/dist/director-registry.d.ts

@@ -35,4 +35,13 @@ export declare function createDirectorRegistry(opts: {
  * factories pass them into `createDirectorRegistry` directly.
  */
 export declare function createDefaultDirectorRegistry(): DirectorRegistry;
+/**
+ * Build the director registry for a workflow closure: the built-in default
+ * plus the closure's own `defineDirector` factories. A closure that ships no
+ * directors passes `loaded: []` and composes to `[defaultDirectorFactory]` --
+ * identical to `createDefaultDirectorRegistry`. A closure director whose id
+ * shadows the built-in (or another loaded director) throws at construction,
+ * the same fail-loud `createDirectorRegistry` applies to any duplicate.
+ */
+export declare function createWorkflowDirectorRegistry(loaded: readonly AnnotatedDirectorFactory<unknown, BaseEnv>[]): DirectorRegistry;
 export {};

package/dist/director-registry.js

@@ -71,3 +71,17 @@ export function createDefaultDirectorRegistry() {
         defaultId: defaultDirectorFactory.id,
     });
 }
+/**
+ * Build the director registry for a workflow closure: the built-in default
+ * plus the closure's own `defineDirector` factories. A closure that ships no
+ * directors passes `loaded: []` and composes to `[defaultDirectorFactory]` --
+ * identical to `createDefaultDirectorRegistry`. A closure director whose id
+ * shadows the built-in (or another loaded director) throws at construction,
+ * the same fail-loud `createDirectorRegistry` applies to any duplicate.
+ */
+export function createWorkflowDirectorRegistry(loaded) {
+    return createDirectorRegistry({
+        factories: [defaultDirectorFactory, ...loaded],
+        defaultId: defaultDirectorFactory.id,
+    });
+}

package/dist/director.d.ts

@@ -54,3 +54,17 @@ export declare function defineDirector<Config, EnvReq extends BaseEnv = BaseEnv>
  * malformed config to the factory.
  */
 export declare function validateDirectorConfig(config: unknown, schema: DirectorConfigSchema): void;
+/**
+ * Structural check for an `AnnotatedDirectorFactory` export. The shape is
+ * callable + `{ id: string, requires: string[], configSchema: function }`.
+ * The `configSchema` field is the discriminator against tool factories
+ * (which carry only `id` and `requires`); without it, any tool-factory
+ * export from a directors-entry module would be accepted as a director.
+ *
+ * Shared by the tool-package loader (`@intx/tool-packaging`) and the
+ * workflow-closure director loader (`@intx/workflow-host`) so both accept
+ * and reject exactly the same shapes -- one accept/reject rule the
+ * approval-time probe and the runtime cannot drift apart on. Two copies of
+ * "is this a valid director" would be a silent congruence hole.
+ */
+export declare function isAnnotatedDirectorFactory(value: unknown): value is AnnotatedDirectorFactory<unknown, BaseEnv>;

package/dist/director.js

@@ -15,6 +15,7 @@
 // factories it wants rather than relying on import-order.
 import { type } from "arktype";
 import { validateNamespacedId } from "./namespace.js";
+import { isAnnotatedPluginFactory } from "./tool.js";
 /**
  * Define a director factory.
  *
@@ -90,3 +91,41 @@ function validateConfig(config, schema) {
 export function validateDirectorConfig(config, schema) {
     validateConfig(config, schema);
 }
+/**
+ * Structural check for an `AnnotatedDirectorFactory` export. The shape is
+ * callable + `{ id: string, requires: string[], configSchema: function }`.
+ * The `configSchema` field is the discriminator against tool factories
+ * (which carry only `id` and `requires`); without it, any tool-factory
+ * export from a directors-entry module would be accepted as a director.
+ *
+ * Shared by the tool-package loader (`@intx/tool-packaging`) and the
+ * workflow-closure director loader (`@intx/workflow-host`) so both accept
+ * and reject exactly the same shapes -- one accept/reject rule the
+ * approval-time probe and the runtime cannot drift apart on. Two copies of
+ * "is this a valid director" would be a silent congruence hole.
+ */
+export function isAnnotatedDirectorFactory(value) {
+    if (typeof value !== "function")
+        return false;
+    if (isAnnotatedPluginFactory(value))
+        return false;
+    if (!("id" in value) || !("requires" in value))
+        return false;
+    if (!("configSchema" in value))
+        return false;
+    const id = value.id;
+    const requires = value.requires;
+    const configSchema = value.configSchema;
+    if (typeof id !== "string")
+        return false;
+    if (!Array.isArray(requires))
+        return false;
+    if (!requires.every((r) => typeof r === "string"))
+        return false;
+    // `defineDirector` requires a callable arktype validator. A non-callable
+    // schema would crash later inside config validation; reject here so the
+    // failure surfaces at load time rather than at first config-validation.
+    if (typeof configSchema !== "function")
+        return false;
+    return true;
+}

package/dist/index.d.ts

@@ -1,14 +1,14 @@
 export { AgentContextLockError } from "./lock.js";
-export { type AgentTool, type AgentToolRunner, type AnnotatedPluginFactory, type AnnotatedPluginMeta, type AnnotatedToolFactory, type PluginFactory, type StringToolHandler, type ToolBundle, type ToolFactory, type ToolFactoryMeta, type ToolHandler, DuplicateToolError, PLUGIN_MARKER, TOOL_PLUGIN_KIND, type ToolPluginKind, createToolRunner, defineTool, definePlugin, fromToolRunner, isAnnotatedPluginFactory, isToolPluginInstance, stringTool, tool, } from "./tool.js";
+export { type AgentTool, type AgentToolRunner, type AnnotatedPluginFactory, type AnnotatedPluginMeta, type AnnotatedToolFactory, type PluginFactory, type StringToolHandler, type ToolBundle, type ToolDeclaration, type ToolFactory, type ToolFactoryMeta, type ToolHandler, DuplicateToolError, PLUGIN_MARKER, TOOL_PLUGIN_KIND, type ToolPluginKind, createToolRunner, defineTool, definePlugin, fromToolRunner, isAnnotatedPluginFactory, isToolPluginInstance, stringTool, tool, toolApprovalEffect, } from "./tool.js";
 export { type AuthorizeFn, type BaseEnv, type Dependencies, AgentEnvError, } from "./env.js";
 export { type AnnotatedDirectorFactory, type DirectorAgentContext, type DirectorConfigSchema, type DirectorFactory, type DirectorFactoryMeta, type DirectorRef, type DirectorRegistry, } from "./director-types.js";
 export { validateNamespacedId } from "./namespace.js";
 export { CanonicalizationError, canonicalizeForHash } from "./canonicalize.js";
-export { type DefinedDirector, defineDirector } from "./director.js";
-export { createDefaultDirectorRegistry, createDirectorRegistry, UnknownDirectorIdError, } from "./director-registry.js";
+export { type DefinedDirector, defineDirector, isAnnotatedDirectorFactory, } from "./director.js";
+export { createDefaultDirectorRegistry, createDirectorRegistry, createWorkflowDirectorRegistry, UnknownDirectorIdError, } from "./director-registry.js";
 export { type DefaultDirectorConfig, buildDefaultDirectorRef, defaultDirectorFactory, } from "./default-director.js";
 export { type SourceRegistry, InvalidInferenceSourceError, SourceNotFoundError, createSourceRegistry, } from "./source.js";
-export { type Agent, type SendOptions, type SendResult, AgentClosedError, createAgent, } from "./agent.js";
+export { type Agent, type SendOptions, type SendResult, AgentClosedError, GateSuspendedWithoutCorrelationError, createAgent, } from "./agent.js";
 export { type AgentDefinition, type DefineAgentConfig, type EnvRequiredByAll, type InferencePreference, defineAgent, } from "./definition.js";
 export { effectiveDirectorRef, getRequiredEnvKeys, validateEnv, } from "./env-validation.js";
 export type { RequiredEnvKeys } from "./env-validation.js";

package/dist/index.js

@@ -7,16 +7,16 @@
 // connector threads, outbound replies via MessageTransport) while the
 // agent drives it from in-process calls.
 export { AgentContextLockError } from "./lock.js";
-export { DuplicateToolError, PLUGIN_MARKER, TOOL_PLUGIN_KIND, createToolRunner, defineTool, definePlugin, fromToolRunner, isAnnotatedPluginFactory, isToolPluginInstance, stringTool, tool, } from "./tool.js";
+export { DuplicateToolError, PLUGIN_MARKER, TOOL_PLUGIN_KIND, createToolRunner, defineTool, definePlugin, fromToolRunner, isAnnotatedPluginFactory, isToolPluginInstance, stringTool, tool, toolApprovalEffect, } from "./tool.js";
 export { AgentEnvError, } from "./env.js";
 export {} from "./director-types.js";
 export { validateNamespacedId } from "./namespace.js";
 export { CanonicalizationError, canonicalizeForHash } from "./canonicalize.js";
-export { defineDirector } from "./director.js";
-export { createDefaultDirectorRegistry, createDirectorRegistry, UnknownDirectorIdError, } from "./director-registry.js";
+export { defineDirector, isAnnotatedDirectorFactory, } from "./director.js";
+export { createDefaultDirectorRegistry, createDirectorRegistry, createWorkflowDirectorRegistry, UnknownDirectorIdError, } from "./director-registry.js";
 export { buildDefaultDirectorRef, defaultDirectorFactory, } from "./default-director.js";
 export { InvalidInferenceSourceError, SourceNotFoundError, createSourceRegistry, } from "./source.js";
-export { AgentClosedError, createAgent, } from "./agent.js";
+export { AgentClosedError, GateSuspendedWithoutCorrelationError, createAgent, } from "./agent.js";
 export { defineAgent, } from "./definition.js";
 export { effectiveDirectorRef, getRequiredEnvKeys, validateEnv, } from "./env-validation.js";
 export { SendQueueFullError } from "./send-queue.js";

package/dist/internal-fixtures/mail.js

@@ -32,6 +32,7 @@ export const MAIL_ADDRESS = "support@fixture.local";
 export const fixtureMailFactory = defineTool({
     id: "@intx-fixtures/mail/bundle",
     requires: ["transport", "address"],
+    definitions: [],
     factory: () => ({
         definitions: [],
         async run(call) {

package/dist/tool.d.ts

@@ -1,3 +1,4 @@
+import type { GrantEffect } from "@intx/types";
 import type { ToolCall, ToolDefinition, ToolResult, ToolRunner } from "@intx/types/runtime";
 import type { BaseEnv } from "./env.js";
 export type ToolHandler = (call: ToolCall, signal: AbortSignal) => Promise<ToolResult>;
@@ -60,14 +61,44 @@ export interface ToolBundle {
  * instantiation.
  */
 export type ToolFactory<EnvReq extends BaseEnv = BaseEnv> = (env: EnvReq) => ToolBundle;
+/**
+ * Static, per-definition declaration a tool factory carries so callers
+ * (e.g. the deploy-time capability walk) can enumerate the tool names a
+ * factory contributes WITHOUT instantiating it. `approval` marks a tool
+ * as requiring per-invocation approval; it is a deliberate subset of
+ * GrantEffect (only "ask" is expressible here — a declaration can request
+ * a gate, never a pre-deny).
+ */
+export interface ToolDeclaration {
+    readonly name: string;
+    readonly approval?: "ask";
+}
+/**
+ * Map a tool's static approval mark to the `GrantEffect` floor its
+ * `tool:<name>` grant carries: an `ask`-marked tool floors at `ask` (its
+ * invocation must clear an approval gate), every other tool floors at
+ * `allow`.
+ *
+ * This is the single canonical derivation of a tool's authorization floor
+ * from its declaration. Both the deploy-time capability walk (hub-side)
+ * and the per-step tool authorization (sidecar-side) route through here so
+ * a pinned tool loaded in the child derives the SAME floor the walk would
+ * have derived from an inline declaration. A divergence between the two
+ * sites would let a pinned `ask` tool authorize as `allow` (or vice
+ * versa), so the mapping lives in exactly one place.
+ */
+export declare function toolApprovalEffect(declaration: Pick<ToolDeclaration, "approval">): GrantEffect;
 /**
  * Runtime metadata attached to a `ToolFactory` by `defineTool`. `id` is
  * package-namespaced; `requires` enumerates env keys the factory touches
- * beyond `BaseEnv`'s six core fields.
+ * beyond `BaseEnv`'s six core fields; `definitions` statically declares
+ * the tool names the factory contributes so callers can enumerate them
+ * without instantiating the factory.
  */
 export interface ToolFactoryMeta {
     readonly id: string;
     readonly requires: readonly string[];
+    readonly definitions: readonly ToolDeclaration[];
 }
 /**
  * A tool factory carrying its runtime metadata. `defineTool` is the only
@@ -87,15 +118,20 @@ export type AnnotatedToolFactory<EnvReq extends BaseEnv = BaseEnv> = ToolFactory
  *     `BaseEnv`'s six core fields. The runtime `validateEnv` checks
  *     presence; the factory itself may also fail loud at construction
  *     if the env contents are structurally wrong.
+ *   - `definitions` statically declares the tool names this factory
+ *     contributes so callers (e.g. the deploy-time capability walk) can
+ *     enumerate them without instantiating the factory.
  *   - `factory(env)` returns a `ToolBundle`. Invoked once per agent
  *     instantiation; the bundle's lifetime is tied to that agent.
  *
  * The returned object is the same callable as the supplied `factory`
- * with `id` and a frozen `requires` array attached.
+ * with `id`, a frozen `requires` array, and a frozen `definitions`
+ * array attached.
  */
 export declare function defineTool<EnvReq extends BaseEnv = BaseEnv>(opts: {
     id: string;
     requires?: readonly string[];
+    definitions: readonly ToolDeclaration[];
     factory: ToolFactory<EnvReq>;
 }): AnnotatedToolFactory<EnvReq>;
 /**
@@ -126,6 +162,20 @@ export declare const PLUGIN_MARKER: unique symbol;
 export interface AnnotatedPluginMeta {
     readonly id: string;
     readonly requires: readonly string[];
+    /**
+     * Static declaration of the tool names this plugin contributes at
+     * runtime, so a caller can enumerate the plugin's tool grant surface
+     * WITHOUT instantiating it (which for a plugin like LSP would start a
+     * language-server subprocess). A plugin adds its tools indirectly -- it
+     * hands a host-defined shape to the tool package that consumes
+     * `env.plugins`, which then registers the plugin's tools under its own
+     * bundle -- so the plugin's contributed tool names are otherwise
+     * invisible until run time. The deploy-time capability walk reads this
+     * field to authorize a plugin-contributed tool the same way it
+     * authorizes a factory-declared tool. Empty when the plugin contributes
+     * no standalone tool (middleware-only plugins).
+     */
+    readonly definitions: readonly ToolDeclaration[];
     readonly [PLUGIN_MARKER]: true;
 }
 export type AnnotatedPluginFactory<EnvReq extends BaseEnv = BaseEnv, Result = unknown> = PluginFactory<EnvReq, Result> & AnnotatedPluginMeta;
@@ -165,6 +215,12 @@ export declare function isToolPluginInstance(value: unknown): value is Record<st
 export declare function definePlugin<Result extends object, EnvReq extends BaseEnv = BaseEnv>(opts: {
     id: string;
     requires?: readonly string[];
+    /**
+     * Static declaration of the tool names this plugin contributes at run
+     * time. Omit for a middleware-only plugin that adds no standalone tool.
+     * See `AnnotatedPluginMeta.definitions`.
+     */
+    definitions?: readonly ToolDeclaration[];
     factory: PluginFactory<EnvReq, Result>;
 }): AnnotatedPluginFactory<EnvReq, Result & {
     kind: ToolPluginKind;

package/dist/tool.js

@@ -66,6 +66,23 @@ export class DuplicateToolError extends Error {
         this.toolName = toolName;
     }
 }
+/**
+ * Map a tool's static approval mark to the `GrantEffect` floor its
+ * `tool:<name>` grant carries: an `ask`-marked tool floors at `ask` (its
+ * invocation must clear an approval gate), every other tool floors at
+ * `allow`.
+ *
+ * This is the single canonical derivation of a tool's authorization floor
+ * from its declaration. Both the deploy-time capability walk (hub-side)
+ * and the per-step tool authorization (sidecar-side) route through here so
+ * a pinned tool loaded in the child derives the SAME floor the walk would
+ * have derived from an inline declaration. A divergence between the two
+ * sites would let a pinned `ask` tool authorize as `allow` (or vice
+ * versa), so the mapping lives in exactly one place.
+ */
+export function toolApprovalEffect(declaration) {
+    return declaration.approval === "ask" ? "ask" : "allow";
+}
 /**
  * Define a tool bundle factory.
  *
@@ -75,17 +92,24 @@ export class DuplicateToolError extends Error {
  *     `BaseEnv`'s six core fields. The runtime `validateEnv` checks
  *     presence; the factory itself may also fail loud at construction
  *     if the env contents are structurally wrong.
+ *   - `definitions` statically declares the tool names this factory
+ *     contributes so callers (e.g. the deploy-time capability walk) can
+ *     enumerate them without instantiating the factory.
  *   - `factory(env)` returns a `ToolBundle`. Invoked once per agent
  *     instantiation; the bundle's lifetime is tied to that agent.
  *
  * The returned object is the same callable as the supplied `factory`
- * with `id` and a frozen `requires` array attached.
+ * with `id`, a frozen `requires` array, and a frozen `definitions`
+ * array attached.
  */
 export function defineTool(opts) {
     validateNamespacedId(opts.id);
     const requires = Object.freeze([
         ...(opts.requires ?? []),
     ]);
+    const definitions = Object.freeze([
+        ...opts.definitions,
+    ]);
     // Wrap the caller's factory rather than mutating it. A caller that
     // shares a factory function across multiple `defineTool` calls
     // (e.g. registering the same constructor under two ids in different
@@ -97,6 +121,7 @@ export function defineTool(opts) {
     return Object.assign(wrapped, {
         id: opts.id,
         requires,
+        definitions,
     });
 }
 /**
@@ -145,6 +170,9 @@ export function definePlugin(opts) {
     const requires = Object.freeze([
         ...(opts.requires ?? []),
     ]);
+    const definitions = Object.freeze([
+        ...(opts.definitions ?? []),
+    ]);
     const wrapped = (env) => {
         const instance = opts.factory(env);
         // Re-stamping the marker is harmless if the factory chose to set
@@ -155,6 +183,7 @@ export function definePlugin(opts) {
     return Object.assign(wrapped, {
         id: opts.id,
         requires,
+        definitions,
         [PLUGIN_MARKER]: true,
     });
 }

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@intx/agent",
-  "version": "0.2.2",
+  "description": "In-process agent runtime: construct an agent, send it a message, get a reply",
+  "version": "0.3.0",
   "license": "LGPL-2.1-only",
   "type": "module",
   "exports": {
@@ -16,14 +17,14 @@
     }
   },
   "dependencies": {
-    "@intx/inference": "0.2.2",
-    "@intx/log": "0.2.2",
-    "@intx/mime": "0.2.2",
-    "@intx/types": "0.2.2",
+    "@intx/inference": "0.3.0",
+    "@intx/log": "0.3.0",
+    "@intx/mime": "0.3.0",
+    "@intx/types": "0.3.0",
     "arktype": "^2.1.29"
   },
   "devDependencies": {
-    "@intx/storage-isogit": "0.2.2"
+    "@intx/storage-isogit": "0.3.0"
   },
   "files": [
     "dist",