@intx/agent 0.1.2 → 0.3.0

package/dist/canonicalize.d.ts

@@ -0,0 +1,15 @@
+export declare class CanonicalizationError extends Error {
+    readonly path: readonly string[];
+    constructor(message: string, path: readonly string[]);
+}
+/**
+ * Produce stable bytes for a value tree. The output is the UTF-8
+ * encoded form of a canonical JSON document with sorted object keys,
+ * NFC-normalized strings, and no whitespace. Throws
+ * `CanonicalizationError` on any non-JSON value or cycle.
+ *
+ * Equality of two outputs implies equality of the canonical structural
+ * form of the inputs; consumers may safely hash the output to compare
+ * value identity across local-dev and production bundles.
+ */
+export declare function canonicalizeForHash(value: unknown): Uint8Array;

package/dist/canonicalize.js

@@ -0,0 +1,160 @@
+// Deterministic JSON serialization for deploy-hash inputs.
+//
+// `canonicalizeForHash` produces stable bytes from a value tree that
+// participates in the deploy hash (notably `DirectorRef.config` and the
+// `AgentDefinition` envelope). The output is the encoded form of a
+// canonical JSON document: object keys NFC-normalized then sorted,
+// strings normalized to NFC, no whitespace. Non-JSON values (Date, Map,
+// Set, function, undefined, symbol, NaN, +/-Infinity) are rejected so
+// the hash cannot silently absorb a value the JSON receiver could not
+// reproduce.
+//
+// The implementation builds a normalized JS value tree first, then
+// `JSON.stringify`s it. The intermediate tree lets the cycle check and
+// type rejections share a single recursive walk.
+//
+// Key-ordering caveat. The walk sorts NFC-normalized keys
+// lexicographically before assigning them into the intermediate plain
+// object. `JSON.stringify` then walks the object's own keys in the
+// engine's iteration order, which per ECMA-262
+// (OrdinaryOwnPropertyKeys) lists integer-indexed string keys first in
+// ascending numeric order, then the remaining keys in insertion order.
+// For purely string-keyed maps the emitted bytes follow the algorithm's
+// lex sort; for integer-keyed maps (string keys like "1", "2", "10")
+// the engine re-orders the integer prefix numerically, so the emitted
+// bytes do not match a strict lex sort of the same keys
+// ("1","10","2"). The behavior is deterministic across every JS engine
+// that implements OrdinaryOwnPropertyKeys (i.e. every engine since
+// ES2020), so deploy-hash equality across producers is preserved. A
+// future engine that changed this rule would change the canonical
+// bytes; if that becomes a concern, replace `JSON.stringify` with a
+// hand-rolled emitter that walks the sorted-key list directly.
+const encoder = new TextEncoder();
+export class CanonicalizationError extends Error {
+    path;
+    constructor(message, path) {
+        super(path.length === 0
+            ? message
+            : `${message} (at ${path.length === 1 ? path[0] : path.join(".")})`);
+        this.name = "CanonicalizationError";
+        this.path = path;
+    }
+}
+function normalize(value, path, seen) {
+    if (value === null)
+        return null;
+    if (typeof value === "boolean")
+        return value;
+    if (typeof value === "string") {
+        return value.normalize("NFC");
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new CanonicalizationError(`non-finite number (${String(value)}) is not valid JSON`, path);
+        }
+        return value;
+    }
+    if (typeof value === "undefined") {
+        throw new CanonicalizationError("undefined is not valid JSON", path);
+    }
+    if (typeof value === "symbol") {
+        throw new CanonicalizationError("symbol is not valid JSON", path);
+    }
+    if (typeof value === "function") {
+        throw new CanonicalizationError("function is not valid JSON", path);
+    }
+    if (typeof value === "bigint") {
+        throw new CanonicalizationError("bigint is not valid JSON", path);
+    }
+    // Objects: arrays, plain records, or rejected built-ins. After the
+    // primitive checks above, the only remaining narrowed type is
+    // `object`.
+    const obj = value;
+    if (seen.has(obj)) {
+        throw new CanonicalizationError("cycle detected", path);
+    }
+    seen.add(obj);
+    try {
+        if (Array.isArray(obj)) {
+            const out = [];
+            for (let i = 0; i < obj.length; i++) {
+                out.push(normalize(obj[i], [...path, `[${String(i)}]`], seen));
+            }
+            return out;
+        }
+        if (obj instanceof Date ||
+            obj instanceof Map ||
+            obj instanceof Set ||
+            obj instanceof RegExp ||
+            obj instanceof Promise ||
+            obj instanceof Error ||
+            obj instanceof ArrayBuffer ||
+            ArrayBuffer.isView(obj)) {
+            throw new CanonicalizationError(`${obj.constructor.name} is not valid JSON`, path);
+        }
+        const proto = Object.getPrototypeOf(obj);
+        if (proto !== Object.prototype && proto !== null) {
+            let protoName = "unknown";
+            if (typeof proto === "object" &&
+                proto !== null &&
+                "constructor" in proto &&
+                typeof proto.constructor === "function") {
+                protoName = proto.constructor.name;
+            }
+            throw new CanonicalizationError(`non-plain object (prototype ${protoName}) is not valid JSON`, path);
+        }
+        // After the proto check, `obj` is a plain Record<string, unknown>.
+        // Index it through a generic record type to drop symbol keys (which
+        // Object.keys also drops).
+        const record = Object.fromEntries(Object.entries(obj));
+        // Normalize keys to NFC before sorting and before indexing the
+        // output. Two failure modes ride on this ordering: (a) if two
+        // distinct raw keys normalize to the same NFC form, silently
+        // overwriting one with the other would drop data and the deploy
+        // hash would no longer be a faithful function of the input; (b)
+        // sorting raw keys and then normalizing produces an output key
+        // order that is not the canonical NFC-sorted order, so two
+        // producers (one pre-normalizing, one not) would hash the same
+        // logical value to different bytes. Normalize first, raise on any
+        // NFC collision, then sort.
+        const byNFC = new Map();
+        for (const rawKey of Object.keys(record)) {
+            const nfcKey = rawKey.normalize("NFC");
+            const existing = byNFC.get(nfcKey);
+            if (existing !== undefined && existing !== rawKey) {
+                throw new CanonicalizationError(`keys ${JSON.stringify(existing)} and ${JSON.stringify(rawKey)} ` +
+                    `NFC-normalize to the same value (${JSON.stringify(nfcKey)})`, path);
+            }
+            byNFC.set(nfcKey, rawKey);
+        }
+        const nfcKeys = [...byNFC.keys()].sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+        const out = {};
+        for (const nfcKey of nfcKeys) {
+            const rawKey = byNFC.get(nfcKey);
+            if (rawKey === undefined)
+                continue;
+            out[nfcKey] = normalize(record[rawKey], [...path, rawKey], seen);
+        }
+        return out;
+    }
+    finally {
+        seen.delete(obj);
+    }
+}
+/**
+ * Produce stable bytes for a value tree. The output is the UTF-8
+ * encoded form of a canonical JSON document with sorted object keys,
+ * NFC-normalized strings, and no whitespace. Throws
+ * `CanonicalizationError` on any non-JSON value or cycle.
+ *
+ * Equality of two outputs implies equality of the canonical structural
+ * form of the inputs; consumers may safely hash the output to compare
+ * value identity across local-dev and production bundles.
+ */
+export function canonicalizeForHash(value) {
+    const normalized = normalize(value, [], new WeakSet());
+    // JSON.stringify with no replacer and no space arg produces the
+    // canonical form modulo key ordering, which `normalize` has already
+    // resolved by constructing plain records with sorted keys.
+    return encoder.encode(JSON.stringify(normalized));
+}

package/dist/default-director.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Config the default director accepts via `defineDirector.build`. The
+ * shape mirrors `DefaultDirectorPolicy` from `@intx/inference` modulo
+ * fields that are not yet exposed at the author-facing surface (the
+ * `afterInferenceDone` hook is a function and cannot canonicalize, so
+ * it stays off the public ref shape).
+ */
+export interface DefaultDirectorConfig {
+    mode?: "conversational" | "reactive";
+}
+/**
+ * The default director factory the agent harness registers. The id is
+ * `@intx/agent/default`.
+ */
+export declare const defaultDirectorFactory: import("./director-types.js").AnnotatedDirectorFactory<unknown, import("./env.js").BaseEnv>;
+/**
+ * Convenience constructor for a `DirectorRef` referencing the default
+ * director with the supplied config (or `{}` for "no overrides").
+ *
+ * The registry's `buildDefaultRef()` constructs the same ref shape; this
+ * export exists so author-defined `AgentDefinition` values can name the
+ * default director explicitly when they want to pass non-default config.
+ */
+export declare const buildDefaultDirectorRef: (config: DefaultDirectorConfig) => import("./director-types.js").DirectorRef<DefaultDirectorConfig>;

package/dist/default-director.js

@@ -0,0 +1,45 @@
+// Built-in default director, packaged through the new env-DI surface.
+//
+// `defaultDirectorFactory` is the `AnnotatedDirectorFactory` the agent
+// harness registers under id `@intx/agent/default`. It is the canonical
+// entry point for callers that do not author their own directors.
+//
+// The factory delegates to `@intx/inference`'s `createDefaultDirector`,
+// which is already a `ReactorDirector`. The registry's director shape
+// is `ReactorDirector` directly (see director-types.ts); no
+// translation layer is involved.
+//
+// Configuration: `DefaultDirectorConfig` maps the existing
+// `DefaultDirectorPolicy` fields the factory accepts. The arktype
+// schema validates incoming config from `defineDirector.build(config)`.
+import { type } from "arktype";
+import { createDefaultDirector, } from "@intx/inference";
+import { defineDirector } from "./director.js";
+const DefaultDirectorConfigSchema = type({
+    "mode?": '"conversational" | "reactive"',
+});
+const defined = defineDirector({
+    id: "@intx/agent/default",
+    configSchema: DefaultDirectorConfigSchema,
+    factory: (config, _env, agent) => {
+        const policy = {};
+        if (config.mode !== undefined) {
+            policy.mode = config.mode;
+        }
+        return createDefaultDirector(agent.systemPrompt, [...agent.toolDefinitions], policy);
+    },
+});
+/**
+ * The default director factory the agent harness registers. The id is
+ * `@intx/agent/default`.
+ */
+export const defaultDirectorFactory = defined.factory;
+/**
+ * Convenience constructor for a `DirectorRef` referencing the default
+ * director with the supplied config (or `{}` for "no overrides").
+ *
+ * The registry's `buildDefaultRef()` constructs the same ref shape; this
+ * export exists so author-defined `AgentDefinition` values can name the
+ * default director explicitly when they want to pass non-default config.
+ */
+export const buildDefaultDirectorRef = defined.build;

package/dist/definition.d.ts

@@ -0,0 +1,139 @@
+import type { ToolPackagePin } from "@intx/types/tool-packages";
+import type { AnnotatedToolFactory } from "./tool.js";
+import type { BaseEnv } from "./env.js";
+import type { DirectorRef } from "./director-types.js";
+/**
+ * Per-source preference describing which providers and models this
+ * agent prefers, in order. The field is **hash-only** -- it
+ * participates in deploy-time hashing and grant computation but is
+ * not consulted for runtime source selection. The agent uses
+ * `env.source` for the active inference call. Downstream tooling that
+ * resolves preferences against available credentials sets the active
+ * `env.source`. Reordering or mutating this field changes the deploy
+ * hash; consumers must treat it as immutable across a deployment.
+ */
+export interface InferencePreference {
+    readonly provider: string;
+    readonly model: string;
+    readonly parameters?: Readonly<Record<string, unknown>>;
+}
+/**
+ * The portable, hashable shape of an agent.
+ *
+ * `EnvReq` is the intersection of every contributor's env requirements
+ * (`BaseEnv` plus whatever each tool factory and the director declare
+ * via `requires`). Use `EnvRequiredByAll` (below) to compute it from a
+ * factory tuple; `defineAgent` does this for you.
+ *
+ * Note on the type-level enforcement: a single `ToolFactory<any>` in
+ * `toolFactories` collapses `EnvRequiredByAll` to `any`, silently
+ * stripping the type-level requirements of every other factory in the
+ * same definition. The runtime `validateEnv` (presence-only) is the
+ * load-bearing safety guarantee; the type level is best-effort
+ * guidance for authors who type their factories tightly.
+ */
+export interface AgentDefinition<EnvReq extends BaseEnv = BaseEnv> {
+    readonly id: string;
+    readonly description?: string;
+    readonly systemPrompt: string;
+    readonly director?: DirectorRef;
+    readonly toolFactories: readonly AnnotatedToolFactory<EnvReq>[];
+    /**
+     * Tool-package names whose `definePlugin` factories this agent uses
+     * (`["@intx/tools-lsp"]`). Unlike a tool factory -- which the agent
+     * imports and places in `toolFactories`, so it is agent-visible -- a
+     * plugin package contributes NO agent-visible factory: its plugin
+     * factory reaches the agent only through `env.plugins`, wired by the
+     * host. This explicit per-agent list is therefore the only way per-step
+     * plugin scoping and the plugin's contributed tool grants can be known
+     * from the definition alone. The field is part of the hashed wire
+     * surface (the live->inert projector carries it), so a tampered plugin
+     * set fails re-verify. Absent when the agent uses no plugins.
+     */
+    readonly plugins?: readonly string[];
+    readonly capabilities: readonly string[];
+    readonly inference: {
+        readonly sources: readonly InferencePreference[];
+    };
+    /**
+     * Free-form metadata the agent itself does not consume. The agent's
+     * runtime does not read this field on any path; it is a passthrough
+     * surface for downstream consumers -- classifiers grouping
+     * definitions, audit consumers filtering on deployment cohort,
+     * tooling rendering a definition catalog. The shape is
+     * `Record<string, string>` deliberately rather than a richer type:
+     * tags are human/operator-supplied identifiers, not structured
+     * data, and any consumer that wants to interpret a tag's content
+     * does so by name agreement with the producer rather than by
+     * shape contract. Producers that need structured per-definition
+     * data should add their own field on a subtype rather than nesting
+     * encoded JSON in a tag value.
+     */
+    readonly tags?: Readonly<Record<string, string>>;
+    /**
+     * Tool-package pins the sidecar materializes for this agent, carried on the
+     * definition so a folded workflow asset is self-contained rather than
+     * depending on pins supplied only at deploy time. Plain-data mirror of the
+     * pins the deploy-tree tool channel consumes.
+     */
+    readonly toolPackagePins?: readonly ToolPackagePin[];
+}
+type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+type EnvRequiredBy<F> = F extends AnnotatedToolFactory<infer E> ? E : never;
+/**
+ * Intersection of env requirements across a tuple of annotated tool
+ * factories, narrowed to extend `BaseEnv`.
+ *
+ * Function parameters are contravariant under TypeScript's strict mode,
+ * so the tuple's element constraint must be `AnnotatedToolFactory<any>`
+ * rather than `AnnotatedToolFactory<BaseEnv>`. A factory typed
+ * `AnnotatedToolFactory<MailEnv>` is **not** assignable to
+ * `AnnotatedToolFactory<BaseEnv>` (it accepts only `MailEnv`, not every
+ * `BaseEnv`), but it is assignable to `AnnotatedToolFactory<any>`. The
+ * runtime `validateEnv` is the load-bearing safety guarantee; the
+ * type level is best-effort guidance.
+ *
+ * **Author-facing footgun.** A single `AnnotatedToolFactory<any>` in
+ * the tuple collapses the intersection to `any` and silently strips
+ * the type-level env requirements of every other factory in the same
+ * `defineAgent` call. Third-party factories typed `<any>` -- whether
+ * by oversight or by deliberate escape -- erase the compile-time
+ * check that the env shape covers their declared `requires`. The
+ * runtime `validateEnv` will still blame the missing keys at
+ * construction, but the author loses the editor-time feedback that
+ * makes env-DI cheap to use. When importing third-party tool
+ * factories, prefer ones whose env shape is explicit, and treat an
+ * `<any>` factory the same way you would treat an `any`-typed
+ * variable elsewhere in the codebase: an opt-out of the type system,
+ * not a default.
+ *
+ * See the note on `AgentDefinition` above.
+ */
+export type EnvRequiredByAll<Factories extends readonly AnnotatedToolFactory<any>[]> = UnionToIntersection<EnvRequiredBy<Factories[number]>> & BaseEnv;
+/**
+ * Configuration accepted by `defineAgent`. Mirrors `AgentDefinition`
+ * but takes `tools` as the input field name (matching the spec's
+ * authoring-time shape) and infers `EnvReq` from the supplied
+ * factories.
+ */
+export interface DefineAgentConfig<Factories extends readonly AnnotatedToolFactory<any>[]> {
+    readonly id: string;
+    readonly description?: string;
+    readonly systemPrompt: string;
+    readonly director?: DirectorRef;
+    readonly tools: Factories;
+    /** Plugin-package names this agent uses; see `AgentDefinition.plugins`. */
+    readonly plugins?: readonly string[];
+    readonly capabilities: readonly string[];
+    readonly inference: {
+        readonly sources: readonly InferencePreference[];
+    };
+    readonly tags?: Readonly<Record<string, string>>;
+}
+/**
+ * Construct an `AgentDefinition` from authoring-time config. The
+ * returned definition has its env requirement computed as the
+ * intersection of every supplied factory's `EnvReq`.
+ */
+export declare function defineAgent<const Factories extends readonly AnnotatedToolFactory<any>[]>(config: DefineAgentConfig<Factories>): AgentDefinition<EnvRequiredByAll<Factories>>;
+export {};

package/dist/definition.js

@@ -0,0 +1,40 @@
+// `AgentDefinition` -- the portable, hashable data that names what an
+// agent is. Together with `defineAgent`, it produces a deploy unit:
+// hashing the definition yields a deploy hash, walking the definition
+// surfaces the capability and credential grants downstream tooling
+// can require approval for at deploy time, and resolving it against a
+// runtime env (`createAgent(def, env)`) yields a running Agent.
+//
+// `AgentDefinition` deliberately holds no instance state. It is data
+// passed around by callers and consumed by downstream tooling (deploy
+// scaffolding, metadata registries, admin surfaces). Everything that
+// is per-instance (the active inference source, the storage handle,
+// the authorize callback, the audit sink, the directors registry)
+// lives in the env supplied at `createAgent` time.
+/**
+ * Construct an `AgentDefinition` from authoring-time config. The
+ * returned definition has its env requirement computed as the
+ * intersection of every supplied factory's `EnvReq`.
+ */
+export function defineAgent(config) {
+    // The widened factory tuple is structurally identical; the cast
+    // adjusts the type's `EnvReq` parameter to match the inferred
+    // intersection.
+    const toolFactories = 
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- adjusting EnvReq parameter; structurally identical
+    config.tools;
+    const definition = {
+        id: config.id,
+        systemPrompt: config.systemPrompt,
+        toolFactories,
+        capabilities: config.capabilities,
+        inference: config.inference,
+        ...(config.plugins !== undefined ? { plugins: config.plugins } : {}),
+        ...(config.description !== undefined
+            ? { description: config.description }
+            : {}),
+        ...(config.director !== undefined ? { director: config.director } : {}),
+        ...(config.tags !== undefined ? { tags: config.tags } : {}),
+    };
+    return definition;
+}

package/dist/director-registry.d.ts

@@ -0,0 +1,47 @@
+import type { AnnotatedDirectorFactory, DirectorRegistry } from "./director-types.js";
+import type { BaseEnv } from "./env.js";
+/**
+ * Erased annotated-factory shape the registry stores. `Config` is
+ * widened to `unknown` so factories with different configuration types
+ * can coexist in the same registry without contravariant assignment
+ * failures.
+ */
+type RegisteredFactory = AnnotatedDirectorFactory<unknown, BaseEnv>;
+/**
+ * Thrown by `DirectorRegistry.resolve` when the supplied ref names an
+ * id the registry does not contain. The error is named separately from
+ * `Error` so callers (specifically `validateEnv`) can distinguish an
+ * unknown-id failure from other runtime faults a custom `directors`
+ * implementation might raise. Custom `DirectorRegistry` implementations
+ * are expected to throw `UnknownDirectorIdError` on the unknown-id
+ * path; anything else propagates as a real failure.
+ */
+export declare class UnknownDirectorIdError extends Error {
+    readonly directorId: string;
+    constructor(directorId: string);
+}
+/**
+ * Build a director registry from a flat list of factories. Throws
+ * `Error` at construction on duplicate ids or when `defaultId` is not
+ * present in `factories`.
+ */
+export declare function createDirectorRegistry(opts: {
+    readonly factories: readonly RegisteredFactory[];
+    readonly defaultId: string;
+}): DirectorRegistry;
+/**
+ * The canonical built-ins-only registry. Convenience for callers that
+ * do not ship their own director factories. Callers with custom
+ * factories pass them into `createDirectorRegistry` directly.
+ */
+export declare function createDefaultDirectorRegistry(): DirectorRegistry;
+/**
+ * Build the director registry for a workflow closure: the built-in default
+ * plus the closure's own `defineDirector` factories. A closure that ships no
+ * directors passes `loaded: []` and composes to `[defaultDirectorFactory]` --
+ * identical to `createDefaultDirectorRegistry`. A closure director whose id
+ * shadows the built-in (or another loaded director) throws at construction,
+ * the same fail-loud `createDirectorRegistry` applies to any duplicate.
+ */
+export declare function createWorkflowDirectorRegistry(loaded: readonly AnnotatedDirectorFactory<unknown, BaseEnv>[]): DirectorRegistry;
+export {};

package/dist/director-registry.js

@@ -0,0 +1,87 @@
+// Per-runtime director registry implementation.
+//
+// `createDirectorRegistry({ factories, defaultId })` builds a registry
+// from a flat list of `AnnotatedDirectorFactory` values and a designated
+// default id. Id collisions and a missing default fail at construction
+// rather than first lookup. `createDefaultDirectorRegistry()` is the
+// canonical built-ins-only registry the agent harness ships for callers
+// that do not author their own directors.
+import { defaultDirectorFactory } from "./default-director.js";
+/**
+ * Thrown by `DirectorRegistry.resolve` when the supplied ref names an
+ * id the registry does not contain. The error is named separately from
+ * `Error` so callers (specifically `validateEnv`) can distinguish an
+ * unknown-id failure from other runtime faults a custom `directors`
+ * implementation might raise. Custom `DirectorRegistry` implementations
+ * are expected to throw `UnknownDirectorIdError` on the unknown-id
+ * path; anything else propagates as a real failure.
+ */
+export class UnknownDirectorIdError extends Error {
+    directorId;
+    constructor(directorId) {
+        super(`unknown director in registry: ${directorId}`);
+        this.name = "UnknownDirectorIdError";
+        this.directorId = directorId;
+    }
+}
+/**
+ * Build a director registry from a flat list of factories. Throws
+ * `Error` at construction on duplicate ids or when `defaultId` is not
+ * present in `factories`.
+ */
+export function createDirectorRegistry(opts) {
+    const byId = new Map();
+    for (const factory of opts.factories) {
+        if (byId.has(factory.id)) {
+            throw new Error(`director id collision in registry: ${factory.id}`);
+        }
+        byId.set(factory.id, factory);
+    }
+    const defaultFactory = byId.get(opts.defaultId);
+    if (defaultFactory === undefined) {
+        throw new Error(`default director ${opts.defaultId} not in registry factories`);
+    }
+    return {
+        resolve(ref) {
+            const factory = byId.get(ref.id);
+            if (factory === undefined) {
+                throw new UnknownDirectorIdError(ref.id);
+            }
+            return factory;
+        },
+        defaultFactory() {
+            return defaultFactory;
+        },
+        buildDefaultRef() {
+            // Construct fresh each call. There is no module-load constant for
+            // the default ref; the spec is explicit about avoiding implicit
+            // module-load side effects in the director surface.
+            return { id: defaultFactory.id, config: {} };
+        },
+    };
+}
+/**
+ * The canonical built-ins-only registry. Convenience for callers that
+ * do not ship their own director factories. Callers with custom
+ * factories pass them into `createDirectorRegistry` directly.
+ */
+export function createDefaultDirectorRegistry() {
+    return createDirectorRegistry({
+        factories: [defaultDirectorFactory],
+        defaultId: defaultDirectorFactory.id,
+    });
+}
+/**
+ * Build the director registry for a workflow closure: the built-in default
+ * plus the closure's own `defineDirector` factories. A closure that ships no
+ * directors passes `loaded: []` and composes to `[defaultDirectorFactory]` --
+ * identical to `createDefaultDirectorRegistry`. A closure director whose id
+ * shadows the built-in (or another loaded director) throws at construction,
+ * the same fail-loud `createDirectorRegistry` applies to any duplicate.
+ */
+export function createWorkflowDirectorRegistry(loaded) {
+    return createDirectorRegistry({
+        factories: [defaultDirectorFactory, ...loaded],
+        defaultId: defaultDirectorFactory.id,
+    });
+}

package/dist/director-types.d.ts

@@ -0,0 +1,80 @@
+import type { ReactorDirector, ToolDefinition } from "@intx/types/runtime";
+import type { BaseEnv } from "./env.js";
+/**
+ * Agent-instance properties a director factory needs at construction.
+ * Sourced from the `AgentDefinition` the agent harness is instantiating:
+ * the system prompt and the resolved tool definitions the model will
+ * see. Held separately from `BaseEnv` because these values are derived
+ * from the agent definition, not supplied by the caller as runtime env.
+ *
+ * `compactorNames` is the exception to the "derived from definition"
+ * shape: it lists the names the deployer registered on `env.compactors`
+ * and is surfaced here so the director picks a known name to pass to
+ * `caps.compact(name, reason)`. The list is empty when the deployer
+ * omits the env field. The shape mirrors `toolDefinitions` for the
+ * same reason: a director that emits an action keyed by name benefits
+ * from learning the registered names at construction rather than
+ * trusting the deployer by convention.
+ */
+export interface DirectorAgentContext {
+    readonly systemPrompt: string;
+    readonly toolDefinitions: readonly ToolDefinition[];
+    readonly compactorNames: readonly string[];
+}
+/**
+ * Reference to a director shipped with a bundle. The package-namespaced
+ * id is the identity. The bundle that ships the director includes the
+ * factory that maps the id back to runtime code; same bundle = same
+ * factory, so no separate `factoryHash` is needed.
+ *
+ * `config` is canonical-JSON-serializable so deploy-hash consumers can
+ * stably hash the ref via `canonicalizeForHash(ref.config)`.
+ */
+export interface DirectorRef<Config = unknown> {
+    readonly id: string;
+    readonly config: Config;
+}
+/**
+ * Factory function shape that produces a `ReactorDirector` from a
+ * validated config, the agent's runtime env, and the agent-instance
+ * context (`DirectorAgentContext`: system prompt, resolved tool
+ * definitions, registered compactor names). The implementation lives
+ * in the same bundle as the agent definition; the registry resolves it
+ * from `DirectorRef.id`.
+ */
+export type DirectorFactory<Config = unknown, EnvReq extends BaseEnv = BaseEnv> = (config: Config, env: EnvReq, agent: DirectorAgentContext) => ReactorDirector;
+/**
+ * Arktype validator for a director's config. Stored as `unknown` at the
+ * type level so this module does not have to import arktype; the
+ * concrete `defineDirector` runtime validates it.
+ */
+export type DirectorConfigSchema = unknown;
+/**
+ * Runtime metadata attached to a `DirectorFactory` by `defineDirector`.
+ * The factory carries its package-namespaced id, its env-key
+ * requirements, and the arktype schema that validates its config.
+ */
+export interface DirectorFactoryMeta {
+    readonly id: string;
+    readonly requires: readonly string[];
+    readonly configSchema: DirectorConfigSchema;
+}
+/**
+ * A director factory with its runtime metadata attached. The registry
+ * stores these; `defineDirector` produces them.
+ */
+export type AnnotatedDirectorFactory<Config = unknown, EnvReq extends BaseEnv = BaseEnv> = DirectorFactory<Config, EnvReq> & DirectorFactoryMeta;
+/**
+ * Per-runtime director registry. Populated explicitly at startup from
+ * the bundle's `defineDirector` calls plus built-ins from `@intx/agent`.
+ * No module-load side effects.
+ *
+ * `resolve` returns the factory for a given ref; `defaultFactory` is the
+ * canonical built-in; `buildDefaultRef` constructs the default ref on
+ * demand (each call constructs a fresh object, no module-load constant).
+ */
+export interface DirectorRegistry {
+    resolve(ref: DirectorRef): AnnotatedDirectorFactory;
+    defaultFactory(): AnnotatedDirectorFactory;
+    buildDefaultRef(): DirectorRef;
+}

package/dist/director-types.js

@@ -0,0 +1,13 @@
+// Type-only surface for the director registry.
+//
+// The runtime implementations -- `createDirectorRegistry`,
+// `defineDirector`, and the built-in default factory -- live in
+// adjacent files. This module holds only the type-level shapes the env
+// contract (`BaseEnv`) depends on, so the env primitives can typecheck
+// independently.
+//
+// `DirectorFactory` returns a `ReactorDirector` directly. The only
+// director that flows through the registry today is the built-in
+// default, which is already `ReactorDirector`-shaped; no translation
+// layer is needed.
+export {};