@intx/agent 0.1.2 → 0.3.0

package/dist/director.d.ts

@@ -0,0 +1,70 @@
+import type { AnnotatedDirectorFactory, DirectorConfigSchema, DirectorFactory, DirectorRef } from "./director-types.js";
+import type { BaseEnv } from "./env.js";
+/**
+ * Result of `defineDirector`. The `factory` half is what the registry
+ * stores; the `build` half is what the agent-definition author calls
+ * to construct a `DirectorRef` referencing this director.
+ *
+ * The `factory` field is **type-erased** in its `Config` parameter. The
+ * registry stores factories of heterogeneous config types alongside
+ * each other; if `factory` carried the narrow `Config`, contravariant
+ * function-parameter variance would prevent the assignment. The agent
+ * only invokes the factory with `ref.config: unknown` sourced from a
+ * `DirectorRef`, and the schema has already validated that config at
+ * `build` time, so the erasure is safe at the call site.
+ */
+export interface DefinedDirector<Config, EnvReq extends BaseEnv = BaseEnv> {
+    readonly factory: AnnotatedDirectorFactory<unknown, EnvReq>;
+    build(config: Config): DirectorRef<Config>;
+}
+/**
+ * Define a director factory.
+ *
+ *   - `id` must be package-namespaced. Bare ids throw at definition
+ *     time.
+ *   - `configSchema` is an arktype validator. The schema validates the
+ *     config at `build(config)` time. Consumers that compute a deploy
+ *     hash over the ref call `canonicalizeForHash(ref.config)`
+ *     themselves; `build` does not run that check.
+ *   - `requires` enumerates the env keys the factory touches beyond
+ *     `BaseEnv`. `validateEnv` checks presence at instantiation.
+ *   - `factory(config, env, agentContext)` returns a `ReactorDirector`.
+ *     `agentContext` carries the agent definition's resolved system
+ *     prompt and tool definitions; the factory uses them when its
+ *     director needs to see the model's tools or seed prompt.
+ *
+ * Two-stage construction (factory + build) lets the registry index the
+ * factory by id while callers stamp configs into refs as data. Same
+ * bundle = same factory; refs hash by id and config.
+ */
+export declare function defineDirector<Config, EnvReq extends BaseEnv = BaseEnv>(opts: {
+    readonly id: string;
+    readonly configSchema: DirectorConfigSchema;
+    readonly requires?: readonly string[];
+    readonly factory: DirectorFactory<Config, EnvReq>;
+}): DefinedDirector<Config, EnvReq>;
+/**
+ * Run the registered config schema against a `DirectorRef.config`.
+ * Throws on schema rejection or on a non-callable schema.
+ *
+ * `defineDirector.build(config)` runs this at definition-construction
+ * time. `createAgent` runs it again at resolve time so a caller that
+ * hand-constructs a `DirectorRef` (the type is public; nothing forces
+ * refs through `build`) cannot bypass the schema check and hand a
+ * 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

@@ -0,0 +1,131 @@
+// `defineDirector` -- the env-DI factory shape for author-defined
+// directors.
+//
+// `defineDirector({ id, configSchema, requires?, factory })` returns
+// `{ build, factory }`. The `factory` is an `AnnotatedDirectorFactory`
+// the registry stores by id; the bundle that ships the director
+// re-exports it so a caller can pass it into `createDirectorRegistry`.
+// The `build(config)` constructor produces a `DirectorRef` from a
+// config that the schema validates. Both halves are needed: the
+// registry stores the factory, the agent definition stores the ref.
+//
+// The `defineDirector` runtime does not register the factory as a
+// module-load side effect. Each runtime instance constructs its
+// registry explicitly via `createDirectorRegistry`, listing the
+// 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.
+ *
+ *   - `id` must be package-namespaced. Bare ids throw at definition
+ *     time.
+ *   - `configSchema` is an arktype validator. The schema validates the
+ *     config at `build(config)` time. Consumers that compute a deploy
+ *     hash over the ref call `canonicalizeForHash(ref.config)`
+ *     themselves; `build` does not run that check.
+ *   - `requires` enumerates the env keys the factory touches beyond
+ *     `BaseEnv`. `validateEnv` checks presence at instantiation.
+ *   - `factory(config, env, agentContext)` returns a `ReactorDirector`.
+ *     `agentContext` carries the agent definition's resolved system
+ *     prompt and tool definitions; the factory uses them when its
+ *     director needs to see the model's tools or seed prompt.
+ *
+ * Two-stage construction (factory + build) lets the registry index the
+ * factory by id while callers stamp configs into refs as data. Same
+ * bundle = same factory; refs hash by id and config.
+ */
+export function defineDirector(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 `defineDirector` calls
+    // (e.g. registering the same factory under two ids) needs each
+    // annotated factory 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 = (config, env, agent) => opts.factory(config, env, agent);
+    const annotatedTyped = Object.assign(wrapped, {
+        id: opts.id,
+        requires,
+        configSchema: opts.configSchema,
+    });
+    // Erase the Config parameter for registry storage. The factory body
+    // continues to expect the narrow Config (via the closure on
+    // `opts.factory`); the registry just sees `(config: unknown, ...)`.
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- intentional contravariant erasure for heterogeneous registry storage
+    const annotated = annotatedTyped;
+    function build(config) {
+        validateConfig(config, opts.configSchema);
+        return { id: opts.id, config };
+    }
+    return { factory: annotated, build };
+}
+function validateConfig(config, schema) {
+    // The schema is typed as `unknown` at the type level so this module
+    // does not have to import arktype. At runtime it must be an arktype
+    // validator -- a callable that returns either the validated value or
+    // a `type.errors` instance. If the schema is not callable, treat
+    // that as a definition-time author error.
+    if (typeof schema !== "function") {
+        throw new Error("director configSchema must be an arktype validator (callable)");
+    }
+    const result = schema(config);
+    if (result instanceof type.errors) {
+        throw new Error(`director config validation failed: ${result.summary}`);
+    }
+}
+/**
+ * Run the registered config schema against a `DirectorRef.config`.
+ * Throws on schema rejection or on a non-callable schema.
+ *
+ * `defineDirector.build(config)` runs this at definition-construction
+ * time. `createAgent` runs it again at resolve time so a caller that
+ * hand-constructs a `DirectorRef` (the type is public; nothing forces
+ * refs through `build`) cannot bypass the schema check and hand a
+ * malformed config to the factory.
+ */
+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-validation.d.ts

@@ -0,0 +1,59 @@
+import type { AgentDefinition } from "./definition.js";
+import type { DirectorRef, DirectorRegistry } from "./director-types.js";
+import { type BaseEnv } from "./env.js";
+/**
+ * The director ref the agent will resolve against the registry. Falls
+ * back to the registry's canonical default when the definition omits a
+ * director. Used identically by `validateEnv` and
+ * `getRequiredEnvKeys` so the absent-director normalization is
+ * consistent.
+ *
+ * The parameter is typed as `Pick<AgentDefinition<BaseEnv>, "director">`
+ * rather than the full `AgentDefinition<EnvReq>` because the function
+ * only reads `def.director`, which is invariant in `EnvReq`. The
+ * `Pick` is a structural supertype of every `AgentDefinition<EnvReq>`
+ * so every caller passes its own narrower generic without an unsafe
+ * cast at the call site.
+ */
+export declare function effectiveDirectorRef(def: Pick<AgentDefinition<BaseEnv>, "director">, registry: DirectorRegistry): DirectorRef;
+/**
+ * The result of `getRequiredEnvKeys`. `keys` is the env-key set the
+ * supplied definition's tools and director declare (plus the
+ * `BaseEnv` core keys). `unresolvedDirectorId` is `null` when the
+ * director resolved cleanly and the keys list is complete; non-null
+ * when the registry could not resolve the definition's director, in
+ * which case `keys` is the best partial answer (BaseEnv + tool keys
+ * only -- the director's `requires` could not be enumerated).
+ *
+ * `unresolvedDirectorId` is `string | null` rather than an optional
+ * field so the caller has to acknowledge it exists; an optional that
+ * resolves to `undefined` is too easy to ignore.
+ */
+export interface RequiredEnvKeys {
+    readonly keys: readonly string[];
+    readonly unresolvedDirectorId: string | null;
+}
+/**
+ * Returns the env-key surface the supplied definition declares via
+ * `BaseEnv`, tool factory `requires`, and the resolved director's
+ * `requires`. When the registry does not contain the definition's
+ * director, the returned `keys` is the best partial answer (BaseEnv
+ * + tool keys only) and the unresolved id surfaces on
+ * `unresolvedDirectorId` so a single call answers both "what env
+ * keys must I populate?" and "did the director resolve?".
+ */
+export declare function getRequiredEnvKeys(def: AgentDefinition<BaseEnv>, registry: DirectorRegistry): RequiredEnvKeys;
+/**
+ * Presence-only env validation. Throws `AgentEnvError` listing every
+ * missing key, the contributors that declared each one, and any
+ * director ids the registry could not resolve.
+ *
+ * `BaseEnv` contributes its core keys; each tool factory
+ * contributes under the label `tool:<id>`; the director contributes
+ * under `director:<id>`. Multiple contributors blaming the same
+ * missing key collapse into a single error. Unknown director ids land
+ * on the error's separate `unresolvedDirectors` field rather than
+ * being mixed into `missing` (env keys) so consumers can distinguish
+ * the two failure modes.
+ */
+export declare function validateEnv<EnvReq extends BaseEnv>(def: AgentDefinition<EnvReq>, env: EnvReq): void;

package/dist/env-validation.js

@@ -0,0 +1,180 @@
+// Presence-only env validation.
+//
+// `validateEnv(def, env)` walks the env keys every contributor in the
+// definition declared and asserts each is present and non-nullish on
+// the supplied env. The check is structural-shallow: a key is "present"
+// when `env[key] !== undefined && env[key] !== null`. Value shape is
+// not validated -- tool factories whose env contents are structurally
+// wrong are expected to fail loud at construction.
+//
+// `getRequiredEnvKeys(def, registry)` returns the env-key surface in
+// a `RequiredEnvKeys` struct alongside an `unresolvedDirectorId` field
+// that surfaces the registry's inability to resolve the definition's
+// director (so a UI consumer learns both pieces of information in a
+// single call). `validateEnv` walks the key set inline rather than
+// delegating to this helper -- it needs per-key blame metadata that
+// the flat key list does not carry -- so the two functions stay in
+// sync through the shared `BASE_ENV_KEYS` constant and the
+// `effectiveDirectorRef` helper below.
+//
+// `effectiveDirectorRef(def, registry)` is the shared helper both
+// `validateEnv` and `getRequiredEnvKeys` use to normalize the
+// absent-director case. Defined once so the absent-director shape
+// stays consistent across callers.
+import { UnknownDirectorIdError } from "./director-registry.js";
+import { AgentEnvError } from "./env.js";
+const BASE_ENV_KEYS = [
+    "sources",
+    "defaultSource",
+    "storage",
+    "workdir",
+    "audit",
+    "authorize",
+    "directors",
+];
+/**
+ * The director ref the agent will resolve against the registry. Falls
+ * back to the registry's canonical default when the definition omits a
+ * director. Used identically by `validateEnv` and
+ * `getRequiredEnvKeys` so the absent-director normalization is
+ * consistent.
+ *
+ * The parameter is typed as `Pick<AgentDefinition<BaseEnv>, "director">`
+ * rather than the full `AgentDefinition<EnvReq>` because the function
+ * only reads `def.director`, which is invariant in `EnvReq`. The
+ * `Pick` is a structural supertype of every `AgentDefinition<EnvReq>`
+ * so every caller passes its own narrower generic without an unsafe
+ * cast at the call site.
+ */
+export function effectiveDirectorRef(def, registry) {
+    return def.director ?? registry.buildDefaultRef();
+}
+/**
+ * Returns the env-key surface the supplied definition declares via
+ * `BaseEnv`, tool factory `requires`, and the resolved director's
+ * `requires`. When the registry does not contain the definition's
+ * director, the returned `keys` is the best partial answer (BaseEnv
+ * + tool keys only) and the unresolved id surfaces on
+ * `unresolvedDirectorId` so a single call answers both "what env
+ * keys must I populate?" and "did the director resolve?".
+ */
+export function getRequiredEnvKeys(def, registry) {
+    const keys = new Set(BASE_ENV_KEYS);
+    for (const factory of def.toolFactories) {
+        for (const key of factory.requires) {
+            keys.add(key);
+        }
+    }
+    const ref = effectiveDirectorRef(def, registry);
+    let unresolvedDirectorId = null;
+    try {
+        const directorFactory = registry.resolve(ref);
+        for (const key of directorFactory.requires) {
+            keys.add(key);
+        }
+    }
+    catch (cause) {
+        // Same policy as `validateEnv`: only swallow the documented
+        // unknown-id case. Other faults from a custom registry propagate
+        // so the caller sees the real exception.
+        if (!(cause instanceof UnknownDirectorIdError))
+            throw cause;
+        unresolvedDirectorId = ref.id;
+    }
+    return Object.freeze({
+        keys: Object.freeze([...keys]),
+        unresolvedDirectorId,
+    });
+}
+/**
+ * Presence-only env validation. Throws `AgentEnvError` listing every
+ * missing key, the contributors that declared each one, and any
+ * director ids the registry could not resolve.
+ *
+ * `BaseEnv` contributes its core keys; each tool factory
+ * contributes under the label `tool:<id>`; the director contributes
+ * under `director:<id>`. Multiple contributors blaming the same
+ * missing key collapse into a single error. Unknown director ids land
+ * on the error's separate `unresolvedDirectors` field rather than
+ * being mixed into `missing` (env keys) so consumers can distinguish
+ * the two failure modes.
+ */
+export function validateEnv(def, env) {
+    const missing = new Set();
+    const blame = new Set();
+    // Per-contributor map of the keys that contributor declared as
+    // missing. Built in parallel with the flat `missing` / `blame`
+    // sets so we can surface the contributor → key association without
+    // changing the flat-array shape callers already consume.
+    const byContributor = new Map();
+    const noteMissing = (key, contributor) => {
+        missing.add(key);
+        blame.add(contributor);
+        let bucket = byContributor.get(contributor);
+        if (bucket === undefined) {
+            bucket = new Set();
+            byContributor.set(contributor, bucket);
+        }
+        bucket.add(key);
+    };
+    const unresolvedDirectors = new Set();
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- shape-erase env to index by key without enumerating the union of generic env keys
+    const envRecord = env;
+    for (const key of BASE_ENV_KEYS) {
+        const value = envRecord[key];
+        if (value === undefined || value === null) {
+            noteMissing(key, "BaseEnv");
+        }
+    }
+    for (const factory of def.toolFactories) {
+        for (const key of factory.requires) {
+            const value = envRecord[key];
+            if (value === undefined || value === null) {
+                noteMissing(key, `tool:${factory.id}`);
+            }
+        }
+    }
+    // Director resolution can throw on unknown ids. Presence of the
+    // director registry itself is already covered by the BaseEnv loop
+    // above. If the registry is missing here, we have already recorded
+    // it and cannot dereference -- short-circuit on that case. If
+    // resolve throws (unknown director id), surface the id through
+    // AgentEnvError's `unresolvedDirectors` field so the caller gets a
+    // single uniform exception path while still being able to
+    // distinguish "missing env key" from "unknown director id"
+    // programmatically.
+    if (env.directors !== undefined && env.directors !== null) {
+        // `effectiveDirectorRef` is `Pick<AgentDefinition, "director">`-shaped
+        // -- every `AgentDefinition<EnvReq>` is a structural supertype of
+        // that pick, so no cast is needed here.
+        const ref = effectiveDirectorRef(def, env.directors);
+        try {
+            const directorFactory = env.directors.resolve(ref);
+            for (const key of directorFactory.requires) {
+                const value = envRecord[key];
+                if (value === undefined || value === null) {
+                    noteMissing(key, `director:${directorFactory.id}`);
+                }
+            }
+        }
+        catch (cause) {
+            // Only catch the documented unknown-id case. Other faults from a
+            // custom registry (TypeError on a malformed ref, an internal
+            // Map failure, etc.) propagate so the caller sees the real
+            // exception rather than a silently-relabelled "unresolved
+            // director id."
+            if (!(cause instanceof UnknownDirectorIdError))
+                throw cause;
+            unresolvedDirectors.add(ref.id);
+        }
+    }
+    if (missing.size > 0 || unresolvedDirectors.size > 0) {
+        const frozenByContributor = new Map();
+        for (const [contributor, keys] of byContributor) {
+            frozenByContributor.set(contributor, Object.freeze([...keys]));
+        }
+        throw new AgentEnvError([...missing], [...blame], frozenByContributor, [
+            ...unresolvedDirectors,
+        ]);
+    }
+}

package/dist/env.d.ts

@@ -0,0 +1,160 @@
+import type { AuthzCallResult, Dependencies } from "@intx/inference";
+import type { AuditStore, Compactor, ContextStore, InferenceSource } from "@intx/types/runtime";
+import type { DirectorRegistry } from "./director-types.js";
+export type { Dependencies };
+/**
+ * Authorization callback shape. Tools call `authorize` before invoking;
+ * the reactor assembly's authz extension threads the call through. The
+ * shape matches `@intx/inference`'s `AuthzExtensionOptions.authorize`.
+ *
+ * `Ctx` parameterizes the per-call context the closure receives.
+ * `unknown` is the default: bare callers do not interpret it. Higher-
+ * layer runtimes that have a richer notion of context (the workflow
+ * runtime supplies `{ stepId, attempt, runId }` via `@intx/workflow`'s
+ * `AuthorizeContext`) construct a closure whose third arg is ignored
+ * and which delegates to a runtime-typed authorize with the context
+ * captured at closure-build time. The third arg in the public signature
+ * is plumbing so the inference layer can pass through whatever shape
+ * the caller's runtime chooses without learning that runtime's
+ * vocabulary.
+ */
+export type AuthorizeFn<Ctx = unknown> = (resource: string, action: string, context: Ctx) => Promise<AuthzCallResult>;
+/**
+ * Required base env for every agent. Tools declare additional keys via
+ * `defineTool({ requires })`; directors via `defineDirector({ requires })`.
+ *
+ * `audit` and `authorize` are required. `directors` is required so
+ * `createAgent` can resolve the agent definition's `DirectorRef` (or
+ * fall back to the registry's canonical default) without invoking any
+ * read-site fallback.
+ */
+export interface BaseEnv {
+    /**
+     * Ordered inference sources supplied at instantiation. The agent copies
+     * these into its own internal source registry; the head of the priority
+     * order (the source whose id is `defaultSource`) starts active, and the
+     * tail is the failover chain. Later `setSource`/`setSources` calls mutate
+     * the registry's copy, not these objects.
+     */
+    sources: InferenceSource[];
+    /** Id of the source that starts active (the head of the priority order). */
+    defaultSource: string;
+    /** Backing context store. The caller owns its lifetime. */
+    storage: ContextStore;
+    /**
+     * The directory the agent treats as its singleton lock boundary.
+     *
+     * For isogit-backed storage this MUST equal the directory passed to
+     * `createIsogitStore`. Two agents constructed against the same
+     * `workdir` fail the lock; two agents constructed against differing
+     * `workdir` values pointing at the same on-disk storage directory
+     * will silently corrupt each other -- the invariant is the caller's
+     * to maintain.
+     */
+    workdir: string;
+    /** Audit sink. Required; no read-site fallback. */
+    audit: AuditStore;
+    /** Authorization callback. Required; no read-site fallback. */
+    authorize: AuthorizeFn;
+    /** Director registry. Required; no read-site fallback. */
+    directors: DirectorRegistry;
+    /**
+     * Compactors registered for this deployment, keyed by name. The
+     * director picks a registered name and emits
+     * `caps.compact(name, reason)`; the reactor resolves the name against
+     * this map and runs the compactor's `apply()` on the conversation
+     * turns. Registered names are surfaced to the director factory at
+     * construction via `agentContext.compactorNames` so the director
+     * picks against a known set rather than guessing by convention.
+     *
+     * Optional: omitting the field is the same shape as registering an
+     * empty map. A `caps.compact(name, …)` call against an absent or
+     * empty registry produces the reactor's existing
+     * "no compactor registered" fatal error.
+     *
+     * Field placement mirrors `directors`: "what's registered at this
+     * deployment" is an env question, not an agent-definition question.
+     */
+    compactors?: Record<string, Compactor>;
+    /**
+     * Inference dependencies (notably `fetch` and the adapter registry) for
+     * the reactor's underlying `runInference` call.
+     *
+     * Production callers omit this field -- `createAgent` fills it from
+     * `@intx/inference/providers`' `createDefaultDependencies()`, which binds
+     * `globalThis.fetch` and the built-in adapter registry. Pass an explicit
+     * `Dependencies` to override: tests supply `setupHarness().deps` from
+     * `@intx/inference-testing` for a deterministic stub fetch, and hosts with
+     * custom adapters pass a registry built via `loadAdapterRegistry`.
+     *
+     * Optional; do not require this field on the production path.
+     */
+    deps?: Dependencies;
+    /**
+     * Optional deterministic session id. Production callers omit and let
+     * the agent generate a fresh UUID; tests that assert on audit-record
+     * sessionIds supply a stable value.
+     */
+    sessionId?: string;
+    /**
+     * Override for the default 10 000-character tool-result size cap.
+     * Forwarded to the reactor assembly's size-cap transform.
+     */
+    sizeCapMaxChars?: number;
+    /**
+     * Maximum number of pending sends (active + queued). Beyond this,
+     * `send()` rejects with `SendQueueFullError`. Defaults to 16.
+     */
+    sendQueueMax?: number;
+    /**
+     * Maximum events any single `stream()` consumer may buffer. Beyond
+     * this, the next read on that consumer's iterator throws
+     * `StreamBackpressureError`; other consumers are unaffected. Defaults
+     * to 1024.
+     */
+    streamBufferMax?: number;
+    /**
+     * Maximum milliseconds `close()` waits for the reactor's shutdown
+     * sequence (audit flush, in-flight commits) before releasing the
+     * lock and returning. Defaults to 5000. Zero disables the wait
+     * (useful for tests whose reactor shutdown is intentionally blocked).
+     */
+    closeTimeoutMs?: number;
+    /**
+     * Plugin instances produced by plugin factories the host loaded
+     * before instantiating tool factories. Each entry is the value the
+     * plugin factory returned (`AnnotatedPluginFactory`'s `Result`).
+     *
+     * Tool packages that accept plugins read this field and filter for
+     * plugins they recognise (by structural shape or a kind marker the
+     * host-side packages agree on). The agent runtime delivers plugins
+     * without interpreting them — composition is the receiving tool
+     * package's responsibility.
+     */
+    plugins?: readonly unknown[];
+}
+/**
+ * Thrown by `validateEnv` when the env-shape check fails. Two failure
+ * modes are reported separately so consumers can react to each:
+ *
+ * - `missing` lists the env key names that were absent. `contributors`
+ *   lists every tool / director / `BaseEnv` label that declared at
+ *   least one missing key (`BaseEnv` is the contributor for the six
+ *   core fields). `missingByContributor` pairs each contributor with
+ *   the specific keys it declared as missing so consumers can render
+ *   an error UI that tells the author which factory blamed which key
+ *   (the flat `missing` and `contributors` arrays carry the same data
+ *   without the join).
+ * - `unresolvedDirectors` lists the `DirectorRef.id`s the registry
+ *   could not resolve (the agent definition referenced a director the
+ *   registry does not contain). These land on a separate field rather
+ *   than being mixed into `missing` (env-key names) so consumers can
+ *   distinguish the two failure modes programmatically.
+ */
+export declare class AgentEnvError extends Error {
+    readonly missing: readonly string[];
+    readonly contributors: readonly string[];
+    readonly missingByContributor: ReadonlyMap<string, readonly string[]>;
+    readonly unresolvedDirectors: readonly string[];
+    constructor(missing: readonly string[], contributors: readonly string[], missingByContributor?: ReadonlyMap<string, readonly string[]>, unresolvedDirectors?: readonly string[]);
+}

package/dist/env.js

@@ -0,0 +1,53 @@
+// The agent's runtime environment contract.
+//
+// `BaseEnv` is what every `createAgent(def, env)` call requires. Tools
+// and directors may extend it with additional keys declared via their
+// `defineTool` / `defineDirector` `requires` metadata; the runtime
+// `validateEnv` (see `env-validation.ts`)
+// asserts presence of every declared key before the agent constructs a
+// reactor.
+//
+// `audit`, `authorize`, and `directors` are required fields. There are
+// no read-site defaults: a caller that omits them is making an
+// affirmative choice the env contract rejects. No-op implementations for
+// tests and examples ship from `@intx/agent/testing`.
+/**
+ * Thrown by `validateEnv` when the env-shape check fails. Two failure
+ * modes are reported separately so consumers can react to each:
+ *
+ * - `missing` lists the env key names that were absent. `contributors`
+ *   lists every tool / director / `BaseEnv` label that declared at
+ *   least one missing key (`BaseEnv` is the contributor for the six
+ *   core fields). `missingByContributor` pairs each contributor with
+ *   the specific keys it declared as missing so consumers can render
+ *   an error UI that tells the author which factory blamed which key
+ *   (the flat `missing` and `contributors` arrays carry the same data
+ *   without the join).
+ * - `unresolvedDirectors` lists the `DirectorRef.id`s the registry
+ *   could not resolve (the agent definition referenced a director the
+ *   registry does not contain). These land on a separate field rather
+ *   than being mixed into `missing` (env-key names) so consumers can
+ *   distinguish the two failure modes programmatically.
+ */
+export class AgentEnvError extends Error {
+    missing;
+    contributors;
+    missingByContributor;
+    unresolvedDirectors;
+    constructor(missing, contributors, missingByContributor = new Map(), unresolvedDirectors = []) {
+        const parts = [];
+        if (missing.length > 0) {
+            parts.push(`missing required keys: ${missing.join(", ")} ` +
+                `(required by: ${contributors.join(", ")})`);
+        }
+        if (unresolvedDirectors.length > 0) {
+            parts.push(`unresolved director ids: ${unresolvedDirectors.join(", ")}`);
+        }
+        super(`agent env validation failed: ${parts.join("; ")}`);
+        this.name = "AgentEnvError";
+        this.missing = missing;
+        this.contributors = contributors;
+        this.missingByContributor = missingByContributor;
+        this.unresolvedDirectors = unresolvedDirectors;
+    }
+}