@intx/agent 0.1.2 → 0.2.2

package/dist/stream.js

@@ -0,0 +1,115 @@
+// Bounded per-consumer fan-out for the agent's reactor event stream.
+//
+// Each call to `agent.stream()` creates a fresh `StreamConsumer`. The
+// agent feeds every reactor event to every consumer; consumers buffer
+// independently. If a consumer falls more than `maxBuffer` events behind
+// it is poisoned with `StreamBackpressureError` and its iterator throws
+// on the next read — the consumer is removed but other consumers keep
+// running.
+//
+// Loud failure matches the defensive-coding rule: silently dropping
+// events would hide consumer bugs, and unbounded buffering would let a
+// stalled consumer balloon the agent's memory. The cap is configurable
+// via `streamBufferMax` on `BaseEnv`.
+export class StreamBackpressureError extends Error {
+    maxBuffer;
+    constructor(maxBuffer) {
+        super(`stream consumer fell more than ${String(maxBuffer)} events behind`);
+        this.name = "StreamBackpressureError";
+        this.maxBuffer = maxBuffer;
+    }
+}
+export function createStreamConsumer(maxBuffer) {
+    if (maxBuffer < 1) {
+        throw new Error(`streamBufferMax must be >= 1, got ${String(maxBuffer)}`);
+    }
+    const buffer = [];
+    const waiters = [];
+    let overflow;
+    let done = false;
+    function settleOverflowedWaiters(err) {
+        while (waiters.length > 0) {
+            const w = waiters.shift();
+            if (w === undefined)
+                return;
+            w.reject(err);
+        }
+    }
+    function settleDoneWaiters() {
+        while (waiters.length > 0) {
+            const w = waiters.shift();
+            if (w === undefined)
+                return;
+            w.resolve({ value: undefined, done: true });
+        }
+    }
+    function push(event) {
+        if (done || overflow !== undefined)
+            return;
+        if (waiters.length > 0) {
+            const w = waiters.shift();
+            if (w === undefined)
+                return;
+            w.resolve({ value: event, done: false });
+            return;
+        }
+        if (buffer.length >= maxBuffer) {
+            overflow = new StreamBackpressureError(maxBuffer);
+            settleOverflowedWaiters(overflow);
+            return;
+        }
+        buffer.push(event);
+    }
+    function close() {
+        if (done)
+            return;
+        done = true;
+        settleDoneWaiters();
+    }
+    function nextResult() {
+        if (overflow !== undefined) {
+            // Drain any buffered events before throwing so the caller sees
+            // every event up to the overflow point.
+            if (buffer.length > 0) {
+                const ev = buffer.shift();
+                if (ev !== undefined) {
+                    return Promise.resolve({ value: ev, done: false });
+                }
+            }
+            return Promise.reject(overflow);
+        }
+        if (buffer.length > 0) {
+            const ev = buffer.shift();
+            if (ev !== undefined) {
+                return Promise.resolve({ value: ev, done: false });
+            }
+        }
+        if (done) {
+            return Promise.resolve({ value: undefined, done: true });
+        }
+        return new Promise((resolve, reject) => {
+            waiters.push({ resolve, reject });
+        });
+    }
+    function iterator() {
+        const it = {
+            next: nextResult,
+            async return() {
+                close();
+                return { value: undefined, done: true };
+            },
+            [Symbol.asyncIterator]() {
+                return it;
+            },
+        };
+        return it;
+    }
+    return {
+        push,
+        close,
+        get closed() {
+            return done || overflow !== undefined;
+        },
+        iterator,
+    };
+}

package/dist/testing/audit-noop.d.ts

@@ -0,0 +1,7 @@
+import type { AuditStore } from "@intx/types/runtime";
+/**
+ * Construct a no-op AuditStore. Each call returns a fresh object so
+ * tests that introspect the store identity (e.g. asserting two agents
+ * received different stores) can do so.
+ */
+export declare function noopAuditStore(): AuditStore;

package/dist/testing/audit-noop.js

@@ -0,0 +1,25 @@
+// No-op AuditStore for tests and examples.
+//
+// Returns immediately for every commit; returns empty arrays for every
+// load. Useful when the agent is exercised in tests that do not assert
+// audit content, or in examples whose purpose is the agent surface
+// rather than the audit ledger. Production callers must supply a real
+// audit store.
+/**
+ * Construct a no-op AuditStore. Each call returns a fresh object so
+ * tests that introspect the store identity (e.g. asserting two agents
+ * received different stores) can do so.
+ */
+export function noopAuditStore() {
+    return {
+        async commitAudit(_records) {
+            // No-op.
+        },
+        async commitErrors(_errors) {
+            // No-op.
+        },
+        async loadAudit(_sessionId) {
+            return [];
+        },
+    };
+}

package/dist/testing/authorize-allow.d.ts

@@ -0,0 +1,8 @@
+import type { AuthorizeFn } from "../env.js";
+/**
+ * Construct a permissive AuthorizeFn that allows every call. The
+ * returned function ignores its arguments (including the third
+ * per-call context parameter) and returns the same shape the
+ * production authz extension expects.
+ */
+export declare function permissiveAuthorize(): AuthorizeFn;

package/dist/testing/authorize-allow.js

@@ -0,0 +1,19 @@
+// Permissive AuthorizeFn for tests and examples.
+//
+// Returns { effect: "allow" } for every call. Useful when the agent is
+// exercised without grants -- the test cares about the agent surface
+// rather than the authz decision. Production callers must supply a real
+// authorize function tied to actual policy.
+/**
+ * Construct a permissive AuthorizeFn that allows every call. The
+ * returned function ignores its arguments (including the third
+ * per-call context parameter) and returns the same shape the
+ * production authz extension expects.
+ */
+export function permissiveAuthorize() {
+    return async (_resource, _action, _context) => ({
+        effect: "allow",
+        matchingGrants: [],
+        resolvedBy: null,
+    });
+}

package/dist/testing/index.d.ts

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

package/dist/testing/index.js

@@ -0,0 +1,17 @@
+// @intx/agent/testing -- no-op implementations of the env contract's
+// required fields, for tests and examples.
+//
+// The exports here silently permit every authz decision and discard
+// every audit record. They exist so test fixtures, the in-tree
+// examples, and short-lived demos can satisfy `BaseEnv` without
+// bringing in a real audit store or policy engine. Production
+// deployments replace these with a real `AuditStore` (durably
+// recording audit and error events) and a real `authorize` callback
+// (gating tool calls per the deployment's policy). Importing from
+// this subpath in production silently disables auditing and allows
+// every tool call, which is almost never what a production caller
+// actually wants -- treat the subpath the same way you would treat a
+// hard-coded `() => true` permission check elsewhere in the
+// codebase.
+export { noopAuditStore } from "./audit-noop.js";
+export { permissiveAuthorize } from "./authorize-allow.js";

package/dist/tool.d.ts

@@ -0,0 +1,182 @@
+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>;
+export type StringToolHandler = (args: Record<string, unknown>, signal: AbortSignal) => Promise<string>;
+export type AgentTool = {
+    kind: "full";
+    definition: ToolDefinition;
+    handler: ToolHandler;
+} | {
+    kind: "string";
+    definition: ToolDefinition;
+    handler: StringToolHandler;
+};
+export declare function tool(args: {
+    definition: ToolDefinition;
+    handler: ToolHandler;
+}): AgentTool;
+export declare function stringTool(args: {
+    definition: ToolDefinition;
+    handler: StringToolHandler;
+}): AgentTool;
+/**
+ * Adapt a pre-built ToolRunner (e.g. the one returned by
+ * `createPosixTools`) into a list of AgentTools that can be passed to
+ * `createAgent({ tools })`. Each definition becomes a full-handler
+ * AgentTool that delegates to the runner's `run`.
+ *
+ * Use this when integrating tool packages whose public surface is a
+ * single ToolRunner rather than individual handlers.
+ */
+export declare function fromToolRunner(runner: {
+    readonly definitions: readonly ToolDefinition[];
+    run: ToolRunner["run"];
+}): AgentTool[];
+export declare class DuplicateToolError extends Error {
+    readonly toolName: string;
+    constructor(toolName: string);
+}
+export type AgentToolRunner = ToolRunner & {
+    readonly definitions: readonly ToolDefinition[];
+};
+/**
+ * A bundle of tools constructed by an `AnnotatedToolFactory`. Exposes
+ * the set of tool definitions the model sees, a single dispatcher
+ * (`run`), and an optional disposer the caller invokes after the agent
+ * closes.
+ *
+ * Disposer ownership lives with the caller -- the env is the agent's
+ * dependency contract; the caller owns the lifetime of what it puts in
+ * env. The agent does not invoke `dispose` itself.
+ */
+export interface ToolBundle {
+    readonly definitions: readonly ToolDefinition[];
+    run(call: ToolCall, signal: AbortSignal): Promise<ToolResult>;
+    dispose?(): Promise<void>;
+}
+/**
+ * Factory function shape -- consumes an env extending `BaseEnv` and
+ * produces a `ToolBundle`. The factory is invoked once per agent
+ * instantiation.
+ */
+export type ToolFactory<EnvReq extends BaseEnv = BaseEnv> = (env: EnvReq) => ToolBundle;
+/**
+ * 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.
+ */
+export interface ToolFactoryMeta {
+    readonly id: string;
+    readonly requires: readonly string[];
+}
+/**
+ * A tool factory carrying its runtime metadata. `defineTool` is the only
+ * sanctioned construction path.
+ *
+ * The intersection `ToolFactory<EnvReq> & ToolFactoryMeta` is the
+ * type-level surface; at runtime the meta fields are attached to the
+ * factory function via `Object.assign`.
+ */
+export type AnnotatedToolFactory<EnvReq extends BaseEnv = BaseEnv> = ToolFactory<EnvReq> & ToolFactoryMeta;
+/**
+ * Define a tool bundle factory.
+ *
+ *   - `id` must be package-namespaced ("@vendor/pkg/name" or
+ *     "pkg/name"). Bare ids throw `Error` at definition time.
+ *   - `requires` enumerates the env keys this factory touches beyond
+ *     `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.
+ *   - `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.
+ */
+export declare function defineTool<EnvReq extends BaseEnv = BaseEnv>(opts: {
+    id: string;
+    requires?: readonly string[];
+    factory: ToolFactory<EnvReq>;
+}): AnnotatedToolFactory<EnvReq>;
+/**
+ * A plugin contributes capabilities (extra tools, middleware, anything
+ * a host plugin protocol defines) without producing a `ToolBundle`
+ * itself. Plugins are first-class entries in an `interchange.tools`
+ * module alongside `AnnotatedToolFactory` exports.
+ *
+ * The shape the factory returns is host-defined: tool packages that
+ * accept plugins read `env.plugins` and dispatch by structural shape
+ * (or by an explicit kind marker the host agrees on). The agent
+ * runtime does not interpret plugin shapes; it only delivers them.
+ *
+ * The marker is a `Symbol.for`-registered key (PLUGIN_MARKER) so a
+ * duck-typed loader can separate plugins from `AnnotatedToolFactory`s
+ * without re-running `defineTool`/`definePlugin` against each export.
+ * Using a registered symbol (rather than a string key like `_plugin`)
+ * prevents third-party objects from accidentally satisfying the
+ * marker check by happening to have a property of the same name.
+ */
+export type PluginFactory<EnvReq extends BaseEnv, Result> = (env: EnvReq) => Result;
+/**
+ * Registered symbol that tags `AnnotatedPluginFactory` values. Exported
+ * so consumers that need to introspect plugin factories directly can
+ * read the marker without re-registering the key.
+ */
+export declare const PLUGIN_MARKER: unique symbol;
+export interface AnnotatedPluginMeta {
+    readonly id: string;
+    readonly requires: readonly string[];
+    readonly [PLUGIN_MARKER]: true;
+}
+export type AnnotatedPluginFactory<EnvReq extends BaseEnv = BaseEnv, Result = unknown> = PluginFactory<EnvReq, Result> & AnnotatedPluginMeta;
+/**
+ * Constant on every plugin instance returned by `definePlugin`. Hosts
+ * that need to distinguish plugin instances from arbitrary objects
+ * received via `env.plugins` check this field before duck-typing on
+ * shape. The string value is the operative form of the contract — the
+ * value-side marker exists because the factory-side symbol marker
+ * (PLUGIN_MARKER above) is only visible to code that imported it,
+ * while the kind string travels through pure-JSON inspection too.
+ */
+export declare const TOOL_PLUGIN_KIND: "tool-plugin";
+/** Type-level form of the kind marker. */
+export type ToolPluginKind = typeof TOOL_PLUGIN_KIND;
+/**
+ * Predicate hosts use to confirm a value off `env.plugins` was minted
+ * by `definePlugin` rather than happening to satisfy a shape-based
+ * check. Returns true iff the value is an object carrying the
+ * literal `kind: "tool-plugin"` marker.
+ */
+export declare function isToolPluginInstance(value: unknown): value is Record<string, unknown> & {
+    kind: ToolPluginKind;
+};
+/**
+ * Define a plugin factory. The plugin's `Result` is host-defined and
+ * surfaces in `env.plugins` for the host-side tool factories that
+ * consume it. The returned instance is tagged with
+ * `kind: "tool-plugin"` so hosts can identify plugin instances
+ * structurally without falling back to duck-typing on the result's
+ * own shape.
+ *
+ * `id` must be package-namespaced — same rule as `defineTool` — so
+ * audit provenance threads through plugins as cleanly as through
+ * tools.
+ */
+export declare function definePlugin<Result extends object, EnvReq extends BaseEnv = BaseEnv>(opts: {
+    id: string;
+    requires?: readonly string[];
+    factory: PluginFactory<EnvReq, Result>;
+}): AnnotatedPluginFactory<EnvReq, Result & {
+    kind: ToolPluginKind;
+}>;
+/** Type predicate distinguishing plugin factories from tool factories. */
+export declare function isAnnotatedPluginFactory(value: unknown): value is AnnotatedPluginFactory;
+/**
+ * Build a `ToolRunner` that dispatches by tool name. Throws
+ * `DuplicateToolError` at construction if any two tools share a name.
+ *
+ * At call time, unknown tool names and exceptions from handlers are
+ * converted to `ToolResult { isError: true }` so the contract on
+ * `ToolRunner.run` ("must not throw") is upheld.
+ */
+export declare function createToolRunner(tools: AgentTool[]): AgentToolRunner;

package/dist/tool.js

@@ -0,0 +1,215 @@
+// Tool registration and dispatch.
+//
+// Two registration shapes are supported for per-tool authoring:
+//
+//   `tool({ definition, handler })`        - handler receives the full
+//                                            ToolCall and returns the full
+//                                            ToolResult. Use when the
+//                                            handler needs the callId or
+//                                            wants to set isError/detail/
+//                                            pendingMarker.
+//
+//   `stringTool({ definition, handler })`  - sugar for the common case of
+//                                            "compute a string from the
+//                                            parsed arguments." The callId
+//                                            is filled in from the
+//                                            surrounding ToolCall, and
+//                                            isError is false unless the
+//                                            handler throws.
+//
+// `createToolRunner(tools)` builds a `ToolRunner` that dispatches by tool
+// name. Per the ToolRunner contract (packages/types/src/runtime.ts), `run`
+// must not throw -- unknown tool names and handler exceptions are surfaced
+// as `ToolResult` with `isError: true` so the model sees them and can
+// recover.
+//
+// `defineTool({ id, requires?, factory })` is the env-DI factory shape.
+// It produces an
+// `AnnotatedToolFactory` whose `factory(env)` returns a `ToolBundle`
+// exposing a set of tool definitions, a dispatcher, and an optional
+// disposer. Bundle-style (rather than per-tool) factory shapes match
+// the existing posix-tools and mail-tools ergonomics; a package that
+// wants per-tool granularity wraps each tool in its own single-
+// definition bundle.
+import { validateNamespacedId } from "./namespace.js";
+export function tool(args) {
+    return { kind: "full", definition: args.definition, handler: args.handler };
+}
+export function stringTool(args) {
+    return {
+        kind: "string",
+        definition: args.definition,
+        handler: args.handler,
+    };
+}
+/**
+ * Adapt a pre-built ToolRunner (e.g. the one returned by
+ * `createPosixTools`) into a list of AgentTools that can be passed to
+ * `createAgent({ tools })`. Each definition becomes a full-handler
+ * AgentTool that delegates to the runner's `run`.
+ *
+ * Use this when integrating tool packages whose public surface is a
+ * single ToolRunner rather than individual handlers.
+ */
+export function fromToolRunner(runner) {
+    return runner.definitions.map((definition) => ({
+        kind: "full",
+        definition,
+        handler: (call, signal) => runner.run(call, signal),
+    }));
+}
+export class DuplicateToolError extends Error {
+    toolName;
+    constructor(toolName) {
+        super(`duplicate tool name: ${toolName}`);
+        this.name = "DuplicateToolError";
+        this.toolName = toolName;
+    }
+}
+/**
+ * Define a tool bundle factory.
+ *
+ *   - `id` must be package-namespaced ("@vendor/pkg/name" or
+ *     "pkg/name"). Bare ids throw `Error` at definition time.
+ *   - `requires` enumerates the env keys this factory touches beyond
+ *     `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.
+ *   - `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.
+ */
+export function defineTool(opts) {
+    validateNamespacedId(opts.id);
+    const requires = Object.freeze([
+        ...(opts.requires ?? []),
+    ]);
+    // 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
+    // bundles) needs each `AnnotatedToolFactory` to be a distinct
+    // identity with its own metadata; a direct `Object.assign` on
+    // `opts.factory` would let the second call silently overwrite the
+    // first's annotations.
+    const wrapped = (env) => opts.factory(env);
+    return Object.assign(wrapped, {
+        id: opts.id,
+        requires,
+    });
+}
+/**
+ * Registered symbol that tags `AnnotatedPluginFactory` values. Exported
+ * so consumers that need to introspect plugin factories directly can
+ * read the marker without re-registering the key.
+ */
+export const PLUGIN_MARKER = Symbol.for("@intx/agent.plugin");
+/**
+ * Constant on every plugin instance returned by `definePlugin`. Hosts
+ * that need to distinguish plugin instances from arbitrary objects
+ * received via `env.plugins` check this field before duck-typing on
+ * shape. The string value is the operative form of the contract — the
+ * value-side marker exists because the factory-side symbol marker
+ * (PLUGIN_MARKER above) is only visible to code that imported it,
+ * while the kind string travels through pure-JSON inspection too.
+ */
+export const TOOL_PLUGIN_KIND = "tool-plugin";
+/**
+ * Predicate hosts use to confirm a value off `env.plugins` was minted
+ * by `definePlugin` rather than happening to satisfy a shape-based
+ * check. Returns true iff the value is an object carrying the
+ * literal `kind: "tool-plugin"` marker.
+ */
+export function isToolPluginInstance(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    if (!("kind" in value))
+        return false;
+    return value.kind === TOOL_PLUGIN_KIND;
+}
+/**
+ * Define a plugin factory. The plugin's `Result` is host-defined and
+ * surfaces in `env.plugins` for the host-side tool factories that
+ * consume it. The returned instance is tagged with
+ * `kind: "tool-plugin"` so hosts can identify plugin instances
+ * structurally without falling back to duck-typing on the result's
+ * own shape.
+ *
+ * `id` must be package-namespaced — same rule as `defineTool` — so
+ * audit provenance threads through plugins as cleanly as through
+ * tools.
+ */
+export function definePlugin(opts) {
+    validateNamespacedId(opts.id);
+    const requires = Object.freeze([
+        ...(opts.requires ?? []),
+    ]);
+    const wrapped = (env) => {
+        const instance = opts.factory(env);
+        // Re-stamping the marker is harmless if the factory chose to set
+        // it itself; otherwise we add it. Either way the returned value
+        // carries the contract.
+        return Object.assign(instance, { kind: TOOL_PLUGIN_KIND });
+    };
+    return Object.assign(wrapped, {
+        id: opts.id,
+        requires,
+        [PLUGIN_MARKER]: true,
+    });
+}
+/** Type predicate distinguishing plugin factories from tool factories. */
+export function isAnnotatedPluginFactory(value) {
+    if (typeof value !== "function")
+        return false;
+    if (!(PLUGIN_MARKER in value))
+        return false;
+    // `PLUGIN_MARKER in value` narrows `value` to include the symbol
+    // key, so the index access below is type-safe without a cast.
+    return value[PLUGIN_MARKER] === true;
+}
+/**
+ * Build a `ToolRunner` that dispatches by tool name. Throws
+ * `DuplicateToolError` at construction if any two tools share a name.
+ *
+ * At call time, unknown tool names and exceptions from handlers are
+ * converted to `ToolResult { isError: true }` so the contract on
+ * `ToolRunner.run` ("must not throw") is upheld.
+ */
+export function createToolRunner(tools) {
+    const byName = new Map();
+    for (const t of tools) {
+        if (byName.has(t.definition.name)) {
+            throw new DuplicateToolError(t.definition.name);
+        }
+        byName.set(t.definition.name, t);
+    }
+    const definitions = tools.map((t) => t.definition);
+    return {
+        definitions,
+        async run(call, signal) {
+            const found = byName.get(call.name);
+            if (found === undefined) {
+                return {
+                    callId: call.id,
+                    content: `unknown tool: ${call.name}`,
+                    isError: true,
+                };
+            }
+            try {
+                if (found.kind === "full") {
+                    return await found.handler(call, signal);
+                }
+                const text = await found.handler(call.arguments, signal);
+                return { callId: call.id, content: text };
+            }
+            catch (err) {
+                return {
+                    callId: call.id,
+                    content: err instanceof Error ? err.message : String(err),
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/package.json

@@ -1,19 +1,37 @@
 {
   "name": "@intx/agent",
-  "version": "0.1.2",
+  "version": "0.2.2",
   "license": "LGPL-2.1-only",
   "type": "module",
   "exports": {
     ".": {
-      "types": "./src/index.ts",
-      "default": "./src/index.ts"
+      "intx-src": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "intx-src": "./src/testing/index.ts",
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
     }
   },
   "dependencies": {
-    "@intx/inference": "0.0.0",
-    "@intx/mime": "0.0.0",
-    "@intx/storage-isogit": "0.0.0",
-    "@intx/types": "0.0.0",
+    "@intx/inference": "0.2.2",
+    "@intx/log": "0.2.2",
+    "@intx/mime": "0.2.2",
+    "@intx/types": "0.2.2",
     "arktype": "^2.1.29"
+  },
+  "devDependencies": {
+    "@intx/storage-isogit": "0.2.2"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
   }
 }