@intx/agent 0.1.2 → 0.3.0

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export { AgentContextLockError } from "./lock.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, 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, 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";
+export { SendQueueFullError } from "./send-queue.js";
+export { StreamBackpressureError } from "./stream.js";

package/dist/index.js

@@ -0,0 +1,23 @@
+// @intx/agent — in-process agent runtime.
+//
+// Sits on top of `createReactorAssembly` from `@intx/inference` to
+// provide a code-driven agent surface: send a message, stream events,
+// project history, hot-swap inference sources. Peer to `@intx/harness`;
+// the harness drives the reactor from a mail transport (INBOX watch,
+// 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, 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, 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, GateSuspendedWithoutCorrelationError, createAgent, } from "./agent.js";
+export { defineAgent, } from "./definition.js";
+export { effectiveDirectorRef, getRequiredEnvKeys, validateEnv, } from "./env-validation.js";
+export { SendQueueFullError } from "./send-queue.js";
+export { StreamBackpressureError } from "./stream.js";

package/dist/internal-fixtures/mail.d.ts

@@ -0,0 +1,39 @@
+import type { ContextStore, InferenceSource } from "@intx/types/runtime";
+import { type AgentDefinition } from "../definition.js";
+import { type BaseEnv } from "../env.js";
+export declare const MAIL_SOURCE: InferenceSource;
+export declare const MAIL_ADDRESS = "support@fixture.local";
+/**
+ * Env extension declared by the fixture's mail tool. Production code
+ * uses the `MailEnv` from `@intx/harness`; the fixture redeclares the
+ * shape locally to avoid the cross-package import.
+ */
+export interface FixtureMailEnv extends BaseEnv {
+    transport: unknown;
+    address: string;
+}
+/**
+ * A no-op mail tool factory declaring `requires: ["transport",
+ * "address"]`. The bundle's definitions are empty -- the fixture's
+ * tests do not invoke any tool; they verify env validation behaviour.
+ */
+export declare const fixtureMailFactory: import("../index.js").AnnotatedToolFactory<FixtureMailEnv>;
+export declare const mailAgentDefinition: AgentDefinition<FixtureMailEnv>;
+/**
+ * Build a bare `BaseEnv` lacking `transport` and `address`. The mail
+ * factory's `requires` makes this env short; `validateEnv` throws
+ * `AgentEnvError` blaming the factory.
+ */
+export declare function createBareMailEnv(opts: {
+    storage: ContextStore;
+    workdir: string;
+}): BaseEnv;
+/**
+ * Build a transport-bearing `FixtureMailEnv` for the success path.
+ * `transport` is opaque to the fixture (the mail factory's run is a
+ * no-op) so the test does not need to supply a real transport.
+ */
+export declare function createTransportMailEnv(opts: {
+    storage: ContextStore;
+    workdir: string;
+}): FixtureMailEnv;

package/dist/internal-fixtures/mail.js

@@ -0,0 +1,86 @@
+// Mail-participating agent fixture for the reactor-once tests.
+//
+// The fixture's definition has a tool factory that declares
+// `requires: ["transport", "address"]`. A bare `BaseEnv` is short on
+// those keys; instantiation must fail with `AgentEnvError`. A
+// transport-bearing env satisfies the requirement and instantiation
+// succeeds; the reactor-once assertion lives in `mail.test.ts`.
+//
+// The fixture does not import `@intx/harness` -- the composition
+// layer's reactor-once invariant is exercised by the harness's own
+// tests against its own surface; cross-importing harness here would
+// introduce a `@intx/agent <-> @intx/harness` cycle.
+import { defineAgent } from "../definition.js";
+import { createDefaultDirectorRegistry } from "../director-registry.js";
+import {} from "../env.js";
+import { noopAuditStore } from "../testing/audit-noop.js";
+import { permissiveAuthorize } from "../testing/authorize-allow.js";
+import { defineTool } from "../tool.js";
+export const MAIL_SOURCE = {
+    id: "anthropic:claude-opus-4-6",
+    provider: "anthropic",
+    baseURL: "https://api.anthropic.com",
+    apiKey: "sk-test-mail",
+    model: "claude-opus-4-6",
+};
+export const MAIL_ADDRESS = "support@fixture.local";
+/**
+ * A no-op mail tool factory declaring `requires: ["transport",
+ * "address"]`. The bundle's definitions are empty -- the fixture's
+ * tests do not invoke any tool; they verify env validation behaviour.
+ */
+export const fixtureMailFactory = defineTool({
+    id: "@intx-fixtures/mail/bundle",
+    requires: ["transport", "address"],
+    definitions: [],
+    factory: () => ({
+        definitions: [],
+        async run(call) {
+            return { callId: call.id, content: "" };
+        },
+    }),
+});
+export const mailAgentDefinition = defineAgent({
+    id: "mail-fixture",
+    description: "Mail-participating fixture agent",
+    systemPrompt: "You handle mail.",
+    tools: [fixtureMailFactory],
+    capabilities: [],
+    inference: {
+        sources: [{ provider: MAIL_SOURCE.provider, model: MAIL_SOURCE.model }],
+    },
+});
+/**
+ * Build a bare `BaseEnv` lacking `transport` and `address`. The mail
+ * factory's `requires` makes this env short; `validateEnv` throws
+ * `AgentEnvError` blaming the factory.
+ */
+export function createBareMailEnv(opts) {
+    return {
+        sources: [MAIL_SOURCE],
+        defaultSource: MAIL_SOURCE.id,
+        storage: opts.storage,
+        workdir: opts.workdir,
+        audit: noopAuditStore(),
+        authorize: permissiveAuthorize(),
+        directors: createDefaultDirectorRegistry(),
+    };
+}
+/**
+ * Build a transport-bearing `FixtureMailEnv` for the success path.
+ * `transport` is opaque to the fixture (the mail factory's run is a
+ * no-op) so the test does not need to supply a real transport.
+ */
+export function createTransportMailEnv(opts) {
+    return {
+        sources: [MAIL_SOURCE],
+        defaultSource: MAIL_SOURCE.id,
+        storage: opts.storage,
+        workdir: opts.workdir,
+        audit: noopAuditStore(),
+        authorize: permissiveAuthorize(),
+        directors: createDefaultDirectorRegistry(),
+        transport: { kind: "fake-transport" },
+        address: MAIL_ADDRESS,
+    };
+}

package/dist/internal-fixtures/planner.d.ts

@@ -0,0 +1,19 @@
+import type { ContextStore, InferenceSource } from "@intx/types/runtime";
+import { type AgentDefinition } from "../definition.js";
+import type { BaseEnv } from "../env.js";
+export declare const PLANNER_SOURCE: InferenceSource;
+/**
+ * Planner-shape definition: no tool factories, capabilities, or
+ * director ref. The default director from the registry handles the
+ * loop; the bare env covers every required `BaseEnv` key.
+ */
+export declare const plannerAgentDefinition: AgentDefinition<BaseEnv>;
+/**
+ * Build a bare `BaseEnv` for the planner fixture. The caller supplies
+ * the storage and workdir; everything else is filled from
+ * `@intx/agent/testing` no-ops.
+ */
+export declare function createPlannerEnv(opts: {
+    storage: ContextStore;
+    workdir: string;
+}): BaseEnv;

package/dist/internal-fixtures/planner.js

@@ -0,0 +1,49 @@
+// Planner-shape agent fixture for the reactor-once tests.
+//
+// A pure in-process agent: no transport, no connector, no mail. Used by
+// `planner.test.ts` to assert that `createAgent(def, env)` wraps the
+// reactor exactly once per instantiation against a bare `BaseEnv`.
+import { defineAgent } from "../definition.js";
+import { createDefaultDirectorRegistry } from "../director-registry.js";
+import { noopAuditStore } from "../testing/audit-noop.js";
+import { permissiveAuthorize } from "../testing/authorize-allow.js";
+export const PLANNER_SOURCE = {
+    id: "anthropic:claude-opus-4-6",
+    provider: "anthropic",
+    baseURL: "https://api.anthropic.com",
+    apiKey: "sk-test-planner",
+    model: "claude-opus-4-6",
+};
+/**
+ * Planner-shape definition: no tool factories, capabilities, or
+ * director ref. The default director from the registry handles the
+ * loop; the bare env covers every required `BaseEnv` key.
+ */
+export const plannerAgentDefinition = defineAgent({
+    id: "planner",
+    description: "Decomposes goals into a plan",
+    systemPrompt: "You are the planner.",
+    tools: [],
+    capabilities: [],
+    inference: {
+        sources: [
+            { provider: PLANNER_SOURCE.provider, model: PLANNER_SOURCE.model },
+        ],
+    },
+});
+/**
+ * Build a bare `BaseEnv` for the planner fixture. The caller supplies
+ * the storage and workdir; everything else is filled from
+ * `@intx/agent/testing` no-ops.
+ */
+export function createPlannerEnv(opts) {
+    return {
+        sources: [PLANNER_SOURCE],
+        defaultSource: PLANNER_SOURCE.id,
+        storage: opts.storage,
+        workdir: opts.workdir,
+        audit: noopAuditStore(),
+        authorize: permissiveAuthorize(),
+        directors: createDefaultDirectorRegistry(),
+    };
+}

package/dist/lock.d.ts

@@ -0,0 +1,16 @@
+export declare class AgentContextLockError extends Error {
+    readonly workdir: string;
+    constructor(workdir: string);
+}
+export type ContextDirLock = {
+    /** Absolute, resolved path of the locked directory. */
+    readonly path: string;
+    /** Release the lock. Idempotent. */
+    release(): void;
+};
+/**
+ * Acquire the process-wide lock for `workdir`. Throws
+ * `AgentContextLockError` if another agent already holds it. The
+ * returned `release` is idempotent.
+ */
+export declare function acquireContextDirLock(workdir: string): ContextDirLock;

package/dist/lock.js

@@ -0,0 +1,47 @@
+// Process-wide registry of held workdir locks.
+//
+// The agent enforces a runtime singleton-per-workdir invariant: at most one
+// in-process agent may own a given workdir at a time. Holding two agents
+// against the same workdir simultaneously corrupts both the git state of
+// any isogit-backed `ContextStore` rooted there and the audit collector's
+// bookkeeping.
+//
+// This is a best-effort in-process check. It does not coordinate across OS
+// processes, and it compares lexically-resolved absolute paths — two paths
+// that point to the same directory through symlinks or `..`/`/./` segments
+// are normalized by `path.resolve`, but a hard link or a separately mounted
+// bind to the same inode will not be detected. Callers are responsible for
+// ensuring `env.workdir` matches the directory backing their `env.storage`
+// (see `BaseEnv.workdir` for the documented invariant).
+import { resolve } from "node:path";
+const heldLocks = new Set();
+export class AgentContextLockError extends Error {
+    workdir;
+    constructor(workdir) {
+        super(`an agent is already open for workdir: ${workdir}`);
+        this.name = "AgentContextLockError";
+        this.workdir = workdir;
+    }
+}
+/**
+ * Acquire the process-wide lock for `workdir`. Throws
+ * `AgentContextLockError` if another agent already holds it. The
+ * returned `release` is idempotent.
+ */
+export function acquireContextDirLock(workdir) {
+    const path = resolve(workdir);
+    if (heldLocks.has(path)) {
+        throw new AgentContextLockError(path);
+    }
+    heldLocks.add(path);
+    let released = false;
+    return {
+        path,
+        release() {
+            if (released)
+                return;
+            released = true;
+            heldLocks.delete(path);
+        },
+    };
+}

package/dist/namespace.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Validate a package-namespaced id. Throws with a precise diagnostic
+ * when the id is not in one of the two supported shapes.
+ *
+ *   "@intx/agent/default"             -> ok (scoped)
+ *   "@my-org/my-workflow/special"     -> ok (scoped)
+ *   "lodash-style/director-name"      -> ok (unscoped)
+ *   "default"                         -> rejected (no package portion)
+ *   "@intx/agent"                     -> rejected (missing name segment)
+ *   "@intx/agent/"                    -> rejected (empty name segment)
+ */
+export declare function validateNamespacedId(id: string): void;

package/dist/namespace.js

@@ -0,0 +1,39 @@
+// Package-namespaced id validation for tool and director factories.
+//
+// Ids must be either scoped ("@scope/pkg/name") or unscoped
+// ("pkg/name"). The package portion is the identity anchor; the trailing
+// segment names the tool or director within that package. Bare ids
+// without a package portion are rejected at definition time so two
+// independently-authored bundles cannot accidentally collide on an
+// otherwise plausible name like "default".
+// Per-segment character set. Mirrors what npm and most package-manager
+// ecosystems accept inside an id segment: alphanumerics, dot, hyphen,
+// underscore. Whitespace (space, tab, newline) and other punctuation
+// are excluded so an id never carries characters that would render
+// strangely in error messages, break log-line parsing, or trip
+// downstream tooling that splits on whitespace.
+const SEGMENT = "[A-Za-z0-9._-]+";
+// Scoped: "@scope/pkg/name". Three slash-separated segments; the first
+// starts with "@" followed by the segment character set. Each segment
+// must be non-empty.
+const SCOPED = new RegExp(`^@${SEGMENT}\\/${SEGMENT}\\/${SEGMENT}$`);
+// Unscoped: "pkg/name". Two slash-separated segments. The package
+// segment cannot start with "@" -- that route is the scoped form.
+const UNSCOPED = new RegExp(`^${SEGMENT}\\/${SEGMENT}$`);
+/**
+ * Validate a package-namespaced id. Throws with a precise diagnostic
+ * when the id is not in one of the two supported shapes.
+ *
+ *   "@intx/agent/default"             -> ok (scoped)
+ *   "@my-org/my-workflow/special"     -> ok (scoped)
+ *   "lodash-style/director-name"      -> ok (unscoped)
+ *   "default"                         -> rejected (no package portion)
+ *   "@intx/agent"                     -> rejected (missing name segment)
+ *   "@intx/agent/"                    -> rejected (empty name segment)
+ */
+export function validateNamespacedId(id) {
+    if (!SCOPED.test(id) && !UNSCOPED.test(id)) {
+        throw new Error(`id must be package-namespaced ` +
+            `(e.g. "@vendor/pkg/name" or "pkg/name"); got ${JSON.stringify(id)}`);
+    }
+}

package/dist/send-queue.d.ts

@@ -0,0 +1,25 @@
+export declare class SendQueueFullError extends Error {
+    readonly maxDepth: number;
+    constructor(maxDepth: number);
+}
+export type SendQueueOptions<T> = {
+    maxDepth: number;
+    /**
+     * Called when a job moves from pending to active. The consumer drives
+     * the underlying work and must eventually call `resolveActive` or
+     * `rejectActive` exactly once.
+     */
+    start: (item: T) => void;
+};
+export type SendQueue<T, R> = {
+    enqueue(item: T, signal?: AbortSignal): Promise<R>;
+    /** Mark the active job complete with success and pump the next. */
+    resolveActive(value: R): void;
+    /** Mark the active job complete with failure and pump the next. */
+    rejectActive(reason: unknown): void;
+    /** Reject the active job (if any) and every pending job with `reason`. */
+    drain(reason: unknown): void;
+    /** Current pending count (queued + active). */
+    readonly depth: number;
+};
+export declare function createSendQueue<T, R>(opts: SendQueueOptions<T>): SendQueue<T, R>;

package/dist/send-queue.js

@@ -0,0 +1,147 @@
+// FIFO queue for serializing send() calls against a single reactor.
+//
+// The agent processes one reactor cycle at a time, so concurrent send()
+// callers are queued. Each queued item carries the caller's resolve/reject
+// hooks and an optional AbortSignal:
+//
+//   - If the signal is already aborted when enqueue() is called the queue
+//     rejects synchronously without enqueueing.
+//   - If the signal fires while the item is still queued the item is
+//     removed and rejected.
+//   - If the signal fires while the item is active the caller-facing
+//     promise rejects immediately, but the reactor cycle continues in the
+//     background. The queue does not start the next item until the consumer
+//     reports the cycle done via resolveActive/rejectActive. This keeps the
+//     queue ordered against actual reactor cycles — two send() promises
+//     cannot interleave at the reactor level.
+//
+// Queue depth (active + pending) is bounded by `maxDepth`; exceeding it
+// throws `SendQueueFullError` synchronously from enqueue() so a buggy
+// caller flooding sends fails loud instead of silently buffering.
+export class SendQueueFullError extends Error {
+    maxDepth;
+    constructor(maxDepth) {
+        super(`send queue is full (max depth ${String(maxDepth)})`);
+        this.name = "SendQueueFullError";
+        this.maxDepth = maxDepth;
+    }
+}
+function abortReason(signal) {
+    return signal.reason ?? new DOMException("aborted", "AbortError");
+}
+export function createSendQueue(opts) {
+    const pending = [];
+    let active = null;
+    function settle(job, kind, value) {
+        if (job.settled)
+            return;
+        job.settled = true;
+        if (job.abortHandler !== undefined && job.signal !== undefined) {
+            job.signal.removeEventListener("abort", job.abortHandler);
+        }
+        if (kind === "resolve") {
+            // The queue's value type is checked at enqueue / resolveActive; the
+            // generic narrowing here is safe by construction.
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- generic resolve value
+            job.resolve(value);
+        }
+        else {
+            job.reject(value);
+        }
+    }
+    function pump() {
+        while (active === null && pending.length > 0) {
+            const next = pending.shift();
+            if (next === undefined)
+                return;
+            if (next.signal?.aborted === true) {
+                settle(next, "reject", abortReason(next.signal));
+                continue;
+            }
+            active = next;
+            opts.start(next.item);
+            return;
+        }
+    }
+    function enqueue(item, signal) {
+        if (signal?.aborted === true) {
+            return Promise.reject(abortReason(signal));
+        }
+        const depth = pending.length + (active !== null ? 1 : 0);
+        if (depth >= opts.maxDepth) {
+            throw new SendQueueFullError(opts.maxDepth);
+        }
+        let resolve;
+        let reject;
+        const promise = new Promise((res, rej) => {
+            resolve = res;
+            reject = rej;
+        });
+        const job = {
+            item,
+            ...(signal !== undefined ? { signal } : {}),
+            resolve,
+            reject,
+            settled: false,
+        };
+        if (signal !== undefined) {
+            const handler = () => {
+                const reason = abortReason(signal);
+                if (active === job) {
+                    // In flight: settle the caller now; the consumer will eventually
+                    // call resolveActive/rejectActive which becomes a no-op and
+                    // advances the queue.
+                    settle(job, "reject", reason);
+                }
+                else {
+                    const idx = pending.indexOf(job);
+                    if (idx >= 0)
+                        pending.splice(idx, 1);
+                    settle(job, "reject", reason);
+                }
+            };
+            signal.addEventListener("abort", handler, { once: true });
+            job.abortHandler = handler;
+        }
+        pending.push(job);
+        pump();
+        return promise;
+    }
+    function resolveActive(value) {
+        if (active === null)
+            return;
+        const job = active;
+        active = null;
+        settle(job, "resolve", value);
+        pump();
+    }
+    function rejectActive(reason) {
+        if (active === null)
+            return;
+        const job = active;
+        active = null;
+        settle(job, "reject", reason);
+        pump();
+    }
+    function drain(reason) {
+        const drained = [];
+        if (active !== null) {
+            drained.push(active);
+            active = null;
+        }
+        drained.push(...pending);
+        pending.length = 0;
+        for (const job of drained) {
+            settle(job, "reject", reason);
+        }
+    }
+    return {
+        enqueue,
+        resolveActive,
+        rejectActive,
+        drain,
+        get depth() {
+            return pending.length + (active !== null ? 1 : 0);
+        },
+    };
+}

package/dist/source.d.ts

@@ -0,0 +1,43 @@
+import { type InferenceSource } from "@intx/types/runtime";
+export declare class InvalidInferenceSourceError extends Error {
+    constructor(message: string);
+}
+export declare class SourceNotFoundError extends Error {
+    readonly id: string;
+    constructor(id: string);
+}
+export type SourceRegistry = {
+    /**
+     * The mutable active source. The same object reference is held by the
+     * reactor; mutating it (through `setSource`, `setSources`,
+     * `failOverToNextSource`, or `resetToPreferredSource`) is what swaps the
+     * source for subsequent inference calls.
+     */
+    readonly active: InferenceSource;
+    /** Replace the active source's fields in place. */
+    setSource(source: InferenceSource): void;
+    /**
+     * Replace the whole ordered list and position the active source at
+     * `defaultSource`. Used when the control plane pushes a re-resolved
+     * source list to a running agent.
+     */
+    setSources(sources: InferenceSource[], defaultSource: string): void;
+    /**
+     * Fail over the active source to the next entry in priority order, in
+     * place. Returns false when the active source is already the last in the
+     * list — there is no further failover target. The ordered list and the
+     * cursor are private; only the registry mutates which source is active,
+     * so the single-active-source invariant the reactor relies on holds.
+     */
+    failOverToNextSource(): boolean;
+    /**
+     * Reset the active source to the most-preferred (highest-priority) one, in
+     * place. The reactor calls this at the start of each inference cycle so a
+     * failover never permanently demotes the agent off its preferred source.
+     */
+    resetToPreferredSource(): void;
+};
+export declare function createSourceRegistry(opts: {
+    sources: InferenceSource[];
+    defaultSource: string;
+}): SourceRegistry;