@intx/agent 0.2.2 → 0.4.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

@@ -42,6 +42,7 @@
 // contract; the caller owns the lifetime of what it puts in env.
 import { createReactorAssembly, } from "@intx/inference";
 import { createDefaultDependencies } from "@intx/inference/providers";
+import { createUnconfiguredCredentialResolver } from "./credential-resolver.js";
 import { getLogger } from "@intx/log";
 import { createInboundMessage } from "@intx/mime";
 import { validateDirectorConfig } from "./director.js";
@@ -71,6 +72,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 +408,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
@@ -446,11 +490,13 @@ export async function createAgent(def, env) {
             source: sourceRegistry.active,
             failOverToNextSource: () => sourceRegistry.failOverToNextSource(),
             resetToPreferredSource: () => sourceRegistry.resetToPreferredSource(),
+            readMaterial: env.readCurrentMaterial ?? createUnconfiguredCredentialResolver(),
             toolRunner: resolvedTools.runner,
             contextStore,
             onEvent: handleEvent,
             auditStore,
             authorize,
+            toolDefinitions: resolvedTools.definitions,
             onShutdown: async () => {
                 try {
                     await flushErrors();
@@ -463,6 +509,9 @@ export async function createAgent(def, env) {
             ...(env.sizeCapMaxChars !== undefined
                 ? { sizeCapMaxChars: env.sizeCapMaxChars }
                 : {}),
+            ...(env.doomLoopThreshold !== undefined
+                ? { doomLoopThreshold: env.doomLoopThreshold }
+                : {}),
             deps,
             ...(env.compactors !== undefined ? { compactors: env.compactors } : {}),
         });

package/dist/credential-resolver.d.ts

@@ -0,0 +1,16 @@
+import type { CredentialMaterialResolver } from "@intx/types";
+/**
+ * A resolver that fails closed on every call. `createAgent` installs this when
+ * the env supplies no `readCurrentMaterial`, so an agent whose inference never
+ * resolves a credential (a mock adapter emitting no credential sentinel) needs
+ * no resolver, while one that DOES reach a credential surfaces a clear error
+ * rather than a confusing `undefined`.
+ */
+export declare function createUnconfiguredCredentialResolver(): CredentialMaterialResolver;
+/**
+ * A resolver over a fixed `credentialId -> secret` map. For callers that hold
+ * their secrets in memory rather than a live cell -- examples, tests, and any
+ * single-process agent. Fails closed when a source references a credential the
+ * map does not carry, mirroring the cell reader's revoked/absent behavior.
+ */
+export declare function createStaticCredentialResolver(materials: Record<string, string>): CredentialMaterialResolver;

package/dist/credential-resolver.js

@@ -0,0 +1,33 @@
+// Helpers for the inference credential-material resolver seam
+// (`CredentialMaterialResolver` in `@intx/types`). An inference call resolves
+// its source's secret by `credentialId` through this seam instead of reading an
+// inline `apiKey`, so the source config carries no secret. The sidecar backs it
+// with the run's live credential cell; the helpers here cover the two simpler
+// cases.
+/**
+ * A resolver that fails closed on every call. `createAgent` installs this when
+ * the env supplies no `readCurrentMaterial`, so an agent whose inference never
+ * resolves a credential (a mock adapter emitting no credential sentinel) needs
+ * no resolver, while one that DOES reach a credential surfaces a clear error
+ * rather than a confusing `undefined`.
+ */
+export function createUnconfiguredCredentialResolver() {
+    return (credentialId) => {
+        throw new Error(`no credential resolver configured for this agent, but an inference call needs the secret for credential ${credentialId}; supply env.readCurrentMaterial`);
+    };
+}
+/**
+ * A resolver over a fixed `credentialId -> secret` map. For callers that hold
+ * their secrets in memory rather than a live cell -- examples, tests, and any
+ * single-process agent. Fails closed when a source references a credential the
+ * map does not carry, mirroring the cell reader's revoked/absent behavior.
+ */
+export function createStaticCredentialResolver(materials) {
+    return (credentialId) => {
+        const secret = materials[credentialId];
+        if (secret === undefined) {
+            throw new Error(`no credential material for ${credentialId} in the static resolver`);
+        }
+        return { secret };
+    };
+}

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/env.d.ts

@@ -1,4 +1,5 @@
 import type { AuthzCallResult, Dependencies } from "@intx/inference";
+import type { CredentialMaterialResolver } from "@intx/types";
 import type { AuditStore, Compactor, ContextStore, InferenceSource } from "@intx/types/runtime";
 import type { DirectorRegistry } from "./director-types.js";
 export type { Dependencies };
@@ -50,6 +51,12 @@ export interface BaseEnv {
      * `workdir` values pointing at the same on-disk storage directory
      * will silently corrupt each other -- the invariant is the caller's
      * to maintain.
+     *
+     * This is the lock and storage boundary, not the working tree the
+     * filesystem tools operate on. A tool that needs a working directory
+     * (e.g. `@intx/tools-posix`) reads that from its own env-DI key
+     * declared through `defineTool({ requires })`, which the caller may
+     * point at a directory distinct from `workdir`.
      */
     workdir: string;
     /** Audit sink. Required; no read-site fallback. */
@@ -90,6 +97,18 @@ export interface BaseEnv {
      * Optional; do not require this field on the production path.
      */
     deps?: Dependencies;
+    /**
+     * Resolves an inference source's credential secret by `credentialId` from the
+     * run's credential-material cell at send time -- the same cell tool
+     * credentials resolve from, so the source config carries no inline secret.
+     *
+     * Optional at this boundary only to spare callers whose inference never
+     * resolves a credential (a mock adapter that emits no credential sentinel).
+     * `createAgent` fills a fail-closed default that throws if an inference call
+     * actually needs a secret; a caller that does real credentialed inference (the
+     * sidecar step env, an example, a test with a real adapter) MUST supply one.
+     */
+    readCurrentMaterial?: CredentialMaterialResolver;
     /**
      * Optional deterministic session id. Production callers omit and let
      * the agent generate a fresh UUID; tests that assert on audit-record
@@ -101,6 +120,13 @@ export interface BaseEnv {
      * Forwarded to the reactor assembly's size-cap transform.
      */
     sizeCapMaxChars?: number;
+    /**
+     * Override for the default doom-loop detection threshold: the number of
+     * identical consecutive tool-call turns that ends the run (default 3).
+     * Forwarded to the reactor. Must be a positive integer, or `false` to
+     * disable doom-loop detection entirely.
+     */
+    doomLoopThreshold?: number | false;
     /**
      * Maximum number of pending sends (active + queued). Beyond this,
      * `send()` rejects with `SendQueueFullError`. Defaults to 16.

package/dist/index.d.ts

@@ -1,14 +1,15 @@
 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 { createStaticCredentialResolver, createUnconfiguredCredentialResolver, } from "./credential-resolver.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,17 @@
 // 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 { createStaticCredentialResolver, createUnconfiguredCredentialResolver, } from "./credential-resolver.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

@@ -20,7 +20,7 @@ export const MAIL_SOURCE = {
     id: "anthropic:claude-opus-4-6",
     provider: "anthropic",
     baseURL: "https://api.anthropic.com",
-    apiKey: "sk-test-mail",
+    credentialId: "sk-test-mail",
     model: "claude-opus-4-6",
 };
 export const MAIL_ADDRESS = "support@fixture.local";
@@ -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/internal-fixtures/planner.js

@@ -11,7 +11,7 @@ export const PLANNER_SOURCE = {
     id: "anthropic:claude-opus-4-6",
     provider: "anthropic",
     baseURL: "https://api.anthropic.com",
-    apiKey: "sk-test-planner",
+    credentialId: "sk-test-planner",
     model: "claude-opus-4-6",
 };
 /**

package/dist/testing/index.d.ts

@@ -1,2 +1,3 @@
 export { noopAuditStore } from "./audit-noop.js";
 export { permissiveAuthorize } from "./authorize-allow.js";
+export { waitForReactorDone } from "./reactor-waiters.js";

package/dist/testing/index.js

@@ -15,3 +15,4 @@
 // codebase.
 export { noopAuditStore } from "./audit-noop.js";
 export { permissiveAuthorize } from "./authorize-allow.js";
+export { waitForReactorDone } from "./reactor-waiters.js";

package/dist/testing/reactor-waiters.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Resolve once the stream emits `reactor.done`.
+ *
+ * Throws if the stream ends without it: returning would resolve as though the
+ * run had completed, and the caller would then fail on a later assertion
+ * instead of on the real cause.
+ *
+ * Typed structurally so a caller need not import the reactor's event union to
+ * await its terminal event.
+ */
+export declare function waitForReactorDone(stream: AsyncIterable<{
+    type: string;
+}>): Promise<void>;

package/dist/testing/reactor-waiters.js

@@ -0,0 +1,23 @@
+// Waiter over a reactor's emitted-event stream.
+//
+// A reactor run ends with a `reactor.done` event, including on the fatal
+// error path, so a test that needs the run finished waits for that event
+// rather than for an interval. CONVENTIONS.md names this shape as the one to
+// copy; it lives here so it is imported rather than copied again.
+/**
+ * Resolve once the stream emits `reactor.done`.
+ *
+ * Throws if the stream ends without it: returning would resolve as though the
+ * run had completed, and the caller would then fail on a later assertion
+ * instead of on the real cause.
+ *
+ * Typed structurally so a caller need not import the reactor's event union to
+ * await its terminal event.
+ */
+export async function waitForReactorDone(stream) {
+    for await (const event of stream) {
+        if (event.type === "reactor.done")
+            return;
+    }
+    throw new Error("reactor event stream ended before reactor.done");
+}

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.4.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.4.0",
+    "@intx/log": "0.4.0",
+    "@intx/mime": "0.4.0",
+    "@intx/types": "0.4.0",
     "arktype": "^2.1.29"
   },
   "devDependencies": {
-    "@intx/storage-isogit": "0.2.2"
+    "@intx/storage-isogit": "0.4.0"
   },
   "files": [
     "dist",