@intx/agent 0.1.2 → 0.3.0

package/dist/source.js

@@ -0,0 +1,118 @@
+// Inference source registry.
+//
+// The agent accepts an array of pre-configured inference sources and a
+// `defaultSource` id at construction. The source whose `id` matches
+// `defaultSource` becomes the active source — the same object reference
+// is what the reactor's assembly holds and reads lazily at each
+// inference call.
+//
+// `setSource` mutates that shared object in place so the next inference
+// call observes the new credentials, model, and bound defaults. In-flight
+// calls keep using the values they read at start-of-call (the reactor
+// does not refetch mid-stream); the swap is therefore safe with respect
+// to torn state.
+import { type } from "arktype";
+import { InferenceSource as InferenceSourceValidator, applyInferenceSourceFields, } from "@intx/types/runtime";
+export class InvalidInferenceSourceError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "InvalidInferenceSourceError";
+    }
+}
+export class SourceNotFoundError extends Error {
+    id;
+    constructor(id) {
+        super(`no source in sources[] has id ${id}`);
+        this.name = "SourceNotFoundError";
+        this.id = id;
+    }
+}
+function validateSources(sources) {
+    if (sources.length === 0) {
+        throw new InvalidInferenceSourceError("sources[] must be non-empty");
+    }
+    const validated = [];
+    const seenIds = new Set();
+    for (const [i, raw] of sources.entries()) {
+        const parsed = InferenceSourceValidator(raw);
+        if (parsed instanceof type.errors) {
+            throw new InvalidInferenceSourceError(`sources[${String(i)}]: ${parsed.summary}`);
+        }
+        if (seenIds.has(parsed.id)) {
+            throw new InvalidInferenceSourceError(`sources[${String(i)}]: duplicate id ${parsed.id}`);
+        }
+        seenIds.add(parsed.id);
+        validated.push(parsed);
+    }
+    return validated;
+}
+export function createSourceRegistry(opts) {
+    // The ordered list, the default index, and the active cursor are private
+    // to the registry. Only the registry mutates which source is active.
+    let list = validateSources(opts.sources);
+    let defaultIndex = indexOfDefault(list, opts.defaultSource);
+    let activeIndex = defaultIndex;
+    const active = { ...sourceAt(list, activeIndex) };
+    function setSource(source) {
+        const parsed = InferenceSourceValidator(source);
+        if (parsed instanceof type.errors) {
+            throw new InvalidInferenceSourceError(parsed.summary);
+        }
+        applyInferenceSourceFields(active, parsed);
+        // A hot-swap is an explicit override of the active source, possibly to a
+        // source that is not in the list at all. Park the cursor at the default
+        // so the next per-cycle resetToPreferredSource is a no-op and the
+        // override survives — even when a failover had moved the cursor off the
+        // default before the swap.
+        activeIndex = defaultIndex;
+    }
+    function setSources(sources, defaultSource) {
+        const validated = validateSources(sources);
+        const index = indexOfDefault(validated, defaultSource);
+        list = validated;
+        defaultIndex = index;
+        activeIndex = index;
+        applyInferenceSourceFields(active, sourceAt(list, activeIndex));
+    }
+    function failOverToNextSource() {
+        if (activeIndex >= list.length - 1)
+            return false;
+        activeIndex += 1;
+        applyInferenceSourceFields(active, sourceAt(list, activeIndex));
+        return true;
+    }
+    function resetToPreferredSource() {
+        // Only undo a failover that actually moved the cursor. When the active
+        // source is already the preferred one, leave `active` untouched — a
+        // caller may have hot-swapped it via setSource (e.g. a director rotating
+        // the model), and that override must survive the per-cycle reset.
+        if (activeIndex === defaultIndex)
+            return;
+        activeIndex = defaultIndex;
+        applyInferenceSourceFields(active, sourceAt(list, activeIndex));
+    }
+    return {
+        active,
+        setSource,
+        setSources,
+        failOverToNextSource,
+        resetToPreferredSource,
+    };
+}
+function indexOfDefault(list, defaultSource) {
+    const match = list.find((s) => s.id === defaultSource);
+    if (match === undefined) {
+        throw new SourceNotFoundError(defaultSource);
+    }
+    return list.indexOf(match);
+}
+function sourceAt(list, index) {
+    const source = list[index];
+    if (source === undefined) {
+        // Unreachable: callers only ever pass an in-range index. The guard
+        // satisfies noUncheckedIndexedAccess without a non-null assertion and
+        // fails loud if that invariant is ever broken.
+        throw new InvalidInferenceSourceError(`no source at index ${String(index)}`);
+    }
+    return source;
+}

package/dist/stream.d.ts

@@ -0,0 +1,16 @@
+import type { ReactorEmittedEvent } from "@intx/inference";
+export declare class StreamBackpressureError extends Error {
+    readonly maxBuffer: number;
+    constructor(maxBuffer: number);
+}
+export type StreamConsumer = {
+    /** Deliver an event to this consumer's buffer. */
+    push(event: ReactorEmittedEvent): void;
+    /** Cleanly terminate the iterator with `done: true`. */
+    close(): void;
+    /** True once close() or an overflow has poisoned the consumer. */
+    readonly closed: boolean;
+    /** Iterator handed back to the caller of `stream()`. */
+    iterator(): AsyncIterableIterator<ReactorEmittedEvent>;
+};
+export declare function createStreamConsumer(maxBuffer: number): StreamConsumer;

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,238 @@
+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>;
+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;
+/**
+ * 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; `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
+ * 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.
+ *   - `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`, 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>;
+/**
+ * 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[];
+    /**
+     * 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;
+/**
+ * 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[];
+    /**
+     * 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;
+}>;
+/** 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;