@intx/harness 0.1.2 → 0.3.0

package/dist/harness.js

@@ -0,0 +1,446 @@
+// @intx/harness composition layer.
+//
+// The harness imports `@intx/agent` and composes a mail-transport
+// surface on top of `createAgent(def, env)`. The reactor is wrapped
+// exactly once -- inside the agent harness in `@intx/agent`. This
+// module owns transport subscription, the connector router and its
+// state persistence, the INBOX watch loop, and the outbound side of
+// `connector.reply` events.
+//
+// What this module does *not* own: reactor wrapping, audit accumulation
+// or flushing, source-registry hot-swap. Those live in `@intx/agent`
+// and are reached via `agent.deliver`, `agent.setSource`, and
+// `agent.stream()` respectively.
+import { createAgent, defineTool, } from "@intx/agent";
+import { getLogger } from "@intx/log";
+import { createConnectorRouter } from "./connector-router.js";
+const logger = getLogger(["interchange", "harness"]);
+/**
+ * Invoke the caller-supplied `onReplySendFailed` callback and absorb any
+ * failure it raises. Extracted from the reply drain so the await-the-
+ * callback contract is testable in isolation: a bare invocation would
+ * compile (TypeScript admits `async () => void` as satisfying a `void`-
+ * returning signature) but would let an async callback's rejection
+ * escape as an unhandled promise rejection. Awaiting protects against
+ * that; the helper exists so the protection is asserted by a test
+ * rather than implied by inspection of the drain.
+ *
+ * Exported only for the regression test in this package; no external
+ * consumer should call it.
+ *
+ * The export-and-mark-internal shape is the codebase's convention
+ * for helpers that exist to make a production-code contract
+ * testable in isolation. A separate `@intx/harness/testing`
+ * entry-point was considered and rejected: the helper is one
+ * try/catch wrapper around the production callback, tightly
+ * coupled to the `MailEnv` callback type defined adjacent to it.
+ * Moving it would either duplicate the production code in a test
+ * module (defeating the point) or require a parallel entry-point
+ * whose only export is a single function -- bundler ceremony for a
+ * boundary TypeScript cannot enforce anyway, since deep imports
+ * (`@intx/harness/src/harness`) reach the same module regardless
+ * of what `index.ts` re-exports. The docstring convention is
+ * load-bearing here: the marker is the contract.
+ *
+ * `invokeReplyDrainTerminated` (below) follows the same shape for
+ * the same reason.
+ */
+export async function invokeReplySendFailed(callback, cause) {
+    try {
+        await callback(cause);
+    }
+    catch (callbackError) {
+        logger.error `onReplySendFailed callback threw: ${callbackError}`;
+    }
+}
+/**
+ * Invoke the caller-supplied `onReplyDrainTerminated` callback and
+ * absorb any failure it raises. Mirrors `invokeReplySendFailed`:
+ * extracted from the reply drain so the await-the-callback contract
+ * is testable in isolation, exported only for the regression test in
+ * this package.
+ */
+export async function invokeReplyDrainTerminated(callback, cause) {
+    try {
+        await callback(cause);
+    }
+    catch (callbackError) {
+        logger.error `onReplyDrainTerminated callback threw: ${callbackError}`;
+    }
+}
+/**
+ * Build the `load` / `writeMetadata` overrides the harness layers onto
+ * `env.storage`. Extracted from `createHarness` so the dirty-bit gating
+ * on `load()` is directly testable -- the production path constructs
+ * the overrides inline with the same arguments.
+ *
+ * The `isInMemoryStateAuthoritative` callback is read on every `load`
+ * invocation. The harness sets the bit from the router's
+ * `onStateChanged` callback so the gate flips on the same tick a
+ * commit produces its first state change; subsequent loads (whether
+ * driven by reactor recovery, mid-cycle, or anywhere else) leave the
+ * router's in-memory snapshot intact rather than blanking it with the
+ * pre-commit disk value.
+ *
+ * Exported for the regression test in this package; no external
+ * consumer should call it. Same shape and rationale as
+ * `invokeReplySendFailed` and `invokeReplyDrainTerminated` above --
+ * the helper is tightly coupled to the dirty-bit gating semantics
+ * that live in this module, and a separate testing entry-point
+ * would buy bundler ceremony for a boundary TypeScript cannot
+ * enforce. The docstring "internal" marker is the contract.
+ */
+export function createWrappedStorageOverrides(baseStorage, connectorRouter, isInMemoryStateAuthoritative) {
+    return {
+        async load(signal) {
+            const loaded = await baseStorage.load(signal);
+            if (!isInMemoryStateAuthoritative()) {
+                connectorRouter.restore(loaded.connectorState);
+            }
+            return loaded;
+        },
+        async writeMetadata(metadata, signal) {
+            baseStorage.setConnectorState(connectorRouter.snapshot());
+            return baseStorage.writeMetadata(metadata, signal);
+        },
+    };
+}
+/**
+ * Construct an `AnnotatedToolFactory` for a mail-tool bundle. The
+ * factory binds `transport` from env at construction time and produces
+ * a bundle whose lifetime is tied to the agent. Disposal of the
+ * underlying mail tools is the caller's responsibility (the env is the
+ * agent's dependency contract; the caller owns what it puts in env);
+ * the agent itself does not call bundle disposers (see the
+ * `ToolBundle` contract in `@intx/agent`). Callers that need to
+ * dispose mail tools on shutdown retain a reference to the underlying
+ * `MailToolWrapper`'s output and invoke its `dispose` directly --
+ * routing disposal through the bundle the agent receives would still
+ * not fire since the agent never holds it.
+ *
+ * The `requires: ["transport", "address"]` declaration captures the
+ * env-key surface of the entire mail composition path -- the factory
+ * body reads `transport`, and `createHarness` (which the caller pairs
+ * this factory with) reads `env.address` to label rejected-message
+ * log records identifying which agent's router refused the message.
+ * No routing decision keys off `env.address` -- the connector router
+ * routes on per-message thread state, not on the agent's own
+ * address -- so the field is observability-only. It still belongs in
+ * `requires` because the harness's log record assumes the field is
+ * populated; declaring it here lets the agent's `validateEnv` blame a
+ * missing `address` at construction time rather than letting the
+ * watch loop discover it under operational load. Callers that hand-
+ * build a `defineTool` factory for a different mail-tool runner must
+ * remember to surface `address` on their own `requires` if their
+ * `createHarness` consumes it -- the agent has no way to deduce
+ * composition-layer env requirements from a factory body that does
+ * not itself read the field.
+ *
+ * The `requires` set is fixed at the two keys above by design; this
+ * helper is not the extension point for mail-tool runners that need
+ * additional env keys. A mail tool that wants to read (say) a tenant
+ * identifier from env should drop down to `defineTool` directly,
+ * declare its own `requires` with the full surface, and call the
+ * underlying mail-tool constructor inside that factory. Folding an
+ * additional `requires` parameter into `defineMailTools` would push
+ * the "what does the harness need vs. what does the tool runner
+ * need" partition onto the caller, which is exactly the partition
+ * this helper exists to hide.
+ *
+ * `definitions` is the static declaration `defineTool` requires: the
+ * tool names this factory contributes, enumerable without invoking the
+ * wrapper. The caller supplies it because the wrapper binds `transport`
+ * from env and cannot run at declaration time; the caller already holds
+ * the mail-tool runner whose `definitions` name the same tools.
+ */
+export function defineMailTools(wrapper, definitions) {
+    return defineTool({
+        id: "@intx/harness/mail",
+        requires: ["transport", "address"],
+        definitions,
+        factory: (env) => {
+            const bundle = wrapper(env.transport);
+            return {
+                definitions: bundle.definitions,
+                run: (call, signal) => bundle.run(call, signal),
+            };
+        },
+    });
+}
+/**
+ * Construct a composition-layer agent: the underlying agent wrapped
+ * with connector-state-aware storage, transport subscription, INBOX
+ * watch, and connector-reply forwarding.
+ *
+ * The reactor is wrapped exactly once -- inside `createAgent`.
+ * `createHarness` augments env.storage with connector-state load/save
+ * and subscribes to the agent's event stream to intercept
+ * `connector.reply` events for outbound transport sends.
+ */
+export async function createHarness(def, env) {
+    const transport = env.transport;
+    // The wrappedStorage's load() needs to know whether the router's
+    // in-memory state is "fresher" than disk. The dirty bit flips on the
+    // first state change emitted by the router (commit() in the watch
+    // loop, onReplySent() after a connector.reply) and never flips back.
+    // Once dirty, the wrappedStorage refuses to restore from disk -- the
+    // router's in-memory state is authoritative.
+    //
+    // The wrappedStorage subscribes to the router's onStateChanged so the
+    // dirty bit is set the same tick commit() runs, even if a
+    // contextStore.load() races behind it.
+    let inMemoryStateAuthoritative = false;
+    const userOnStateChanged = env.onConnectorStateChanged;
+    const connectorRouter = createConnectorRouter({
+        onStateChanged: (state) => {
+            inMemoryStateAuthoritative = true;
+            if (userOnStateChanged !== undefined)
+                userOnStateChanged(state);
+        },
+    });
+    // Wrap env.storage. The first load() restores connector state from
+    // disk only if no router commit has happened yet -- once a commit
+    // makes the router's state authoritative, subsequent loads return
+    // the store's payload unchanged and leave the in-memory state
+    // intact.
+    //
+    // The router's in-memory state diverges from disk between commit()
+    // (in the watch callback) and the next writeMetadata (at the
+    // reactor's per-cycle checkpoint). A load() landing in that window
+    // must not clobber the in-memory state with the stale disk value --
+    // doing so makes the harness's outbound connector.reply path drop
+    // replies with NoActiveConnectorThreadError when composeReply() runs
+    // after a mid-cycle reload.
+    //
+    // The wrapper is implemented as a Proxy over env.storage so adding a
+    // new method to ContextStore does not require touching the harness:
+    // any method not named in `overrides` forwards to env.storage with
+    // its `this` bound to env.storage. The two overrides intercept
+    // load (cold-boot restore) and writeMetadata (flush router snapshot
+    // before delegate). `setConnectorState` is left to the default
+    // Proxy fall-through path since the harness adds no behaviour beyond
+    // delegation there.
+    const overrides = createWrappedStorageOverrides(env.storage, connectorRouter, () => inMemoryStateAuthoritative);
+    const wrappedStorage = new Proxy(env.storage, {
+        get(target, prop, _receiver) {
+            if (prop === "load")
+                return overrides.load;
+            if (prop === "writeMetadata")
+                return overrides.writeMetadata;
+            const value = Reflect.get(target, prop, target);
+            // Bind methods to the underlying store so isogit-style
+            // closure-captured state and prototype-bound this both resolve
+            // against the real store, not the proxy.
+            return typeof value === "function" ? value.bind(target) : value;
+        },
+    });
+    const agentEnv = { ...env, storage: wrappedStorage };
+    const agent = await createAgent(def, agentEnv);
+    // From here through the final `return`, the agent is constructed
+    // and the workdir lock is held. Anything that throws -- the reply
+    // drain's IIFE-construction expression, `transport.watch()`,
+    // anything in the watch callback's synchronous registration -- has
+    // to release the lock by closing the agent before re-raising; the
+    // caller never sees the agent and cannot do it themselves.
+    // `createAgent` covers its own internal failure paths via its
+    // `succeeded`/`finally` shape; this is the matching coverage for
+    // the harness's own construction tail.
+    let harnessSucceeded = false;
+    try {
+        // Background drain of the agent's event stream. Intercepts
+        // `connector.reply` to send the reply via transport; everything
+        // else flows past unobserved. Other consumers can subscribe to the
+        // exposed `stream()` method to see the same events.
+        //
+        // Reply sends are serialized through `replyChain` so two replies
+        // fired in quick succession do not interleave their
+        // composeReply / transport.send / onReplySent sequence -- the
+        // second reply waits for the first's receipt to land in the router
+        // before composing its own.
+        let stopReplyDrain = false;
+        let replyChain = Promise.resolve();
+        const replyDrainDone = (async () => {
+            try {
+                for await (const event of agent.stream()) {
+                    if (stopReplyDrain)
+                        break;
+                    if (event.type === "connector.reply") {
+                        const replyContent = event.data.content;
+                        replyChain = replyChain.then(async () => {
+                            try {
+                                const parts = connectorRouter.composeReply();
+                                const receipt = await transport.send({
+                                    ...parts,
+                                    content: replyContent,
+                                    type: "conversation.message",
+                                });
+                                connectorRouter.onReplySent(receipt);
+                            }
+                            catch (cause) {
+                                // The reply is dropped and the router state stays at
+                                // its pre-send value. Surface the loss to the caller's
+                                // optional onReplySendFailed callback in addition to
+                                // the operator-facing log so programmatic consumers
+                                // (retries, alerting) can observe what logger.error
+                                // alone hides.
+                                logger.error `Failed to send connector reply: ${cause}`;
+                                if (env.onReplySendFailed !== undefined) {
+                                    await invokeReplySendFailed(env.onReplySendFailed, cause);
+                                }
+                            }
+                        });
+                    }
+                }
+                // Drain any pending reply before the loop exits so close() sees
+                // a settled state.
+                await replyChain;
+            }
+            catch (cause) {
+                // The agent's stream throws on backpressure violations; log and
+                // exit the drain. The reply path stops working but the rest of
+                // the harness keeps running until close() tears it down.
+                // Surface the loss to the caller's optional
+                // `onReplyDrainTerminated` callback so programmatic consumers
+                // (alerting, watchdogs) can observe what `logger.warn` alone
+                // hides.
+                logger.warn `Reply-drain stream terminated: ${cause}`;
+                if (env.onReplyDrainTerminated !== undefined) {
+                    await invokeReplyDrainTerminated(env.onReplyDrainTerminated, cause);
+                }
+            }
+        })();
+        // Delete a message from the INBOX after it has been delivered to the
+        // reactor.
+        //
+        // A failure here is logged and swallowed: the router state has
+        // already been committed and `agent.deliver` has accepted the
+        // message, so re-raising would unwind a half-applied delivery. The
+        // message stays in the INBOX and a future startup (or watch firing)
+        // re-fetches it, re-routes it, and re-delivers it. The router's
+        // persisted state makes that benign on the routing side: the sender
+        // is already a thread participant, so `route()` returns either a
+        // `continue` (which is a no-op state mutation since the sender is
+        // unchanged) or a `passthrough` (no headers match). The agent's
+        // director sees a duplicate `message.received`; idempotent
+        // directors are unaffected, and the audit trail records the
+        // duplicate for post-hoc reconciliation.
+        async function consumeFromInbox(message) {
+            try {
+                await transport.setFlags(message.ref, ["\\Deleted"]);
+                await transport.expunge("INBOX");
+            }
+            catch (cause) {
+                logger.warn `Failed to consume message uid=${message.ref.uid} from INBOX: ${cause}`;
+            }
+        }
+        // INBOX watch loop. Subscribe before the agent's reactor is fully
+        // settled so no message is missed in the window between subscription
+        // and the first watch callback.
+        let stopped = false;
+        const unsubscribe = transport.watch("INBOX", (event) => {
+            if (stopped)
+                return;
+            if (event.type !== "exists")
+                return;
+            const ref = { uid: event.uid, mailbox: "INBOX" };
+            void (async () => {
+                try {
+                    let message;
+                    try {
+                        message = await transport.fetchFull(ref);
+                    }
+                    catch (cause) {
+                        logger.error `Failed to fetch message uid=${event.uid}: ${cause}`;
+                        return;
+                    }
+                    if (stopped)
+                        return;
+                    let decision;
+                    try {
+                        decision = connectorRouter.route(message);
+                    }
+                    catch (cause) {
+                        // A router-rejected message (malformed headers, parse error
+                        // inside the router, etc.) is still surfaced to the agent
+                        // as an inbound `message.received`. The agent's director
+                        // decides what the message means and how to respond;
+                        // dropping it on the floor here would hide messages the
+                        // operator may want to see. The router's state is *not*
+                        // committed for the rejected message, so subsequent replies
+                        // compose against the pre-rejection thread state.
+                        logger.warn `Connector router rejected message uid=${message.ref.uid} for agent ${env.address}: ${cause instanceof Error ? cause.message : String(cause)}`;
+                        if (stopped)
+                            return;
+                        agent.deliver(message);
+                        return;
+                    }
+                    if (decision.kind === "passthrough") {
+                        if (stopped)
+                            return;
+                        agent.deliver(message);
+                        return;
+                    }
+                    // start or continue: commit router state synchronously before
+                    // any await so a concurrent watch callback observes the
+                    // updated state.
+                    connectorRouter.commit(decision);
+                    if (stopped)
+                        return;
+                    agent.deliver(message);
+                    await consumeFromInbox(message);
+                }
+                catch (cause) {
+                    // `agent.deliver` throws `AgentClosedError` synchronously when
+                    // called after the agent has closed. The `if (stopped) return`
+                    // guards above narrow the race window but cannot close it: a
+                    // `close()` call landing between the guard and the synchronous
+                    // throw still surfaces the rejection here. The fetched message
+                    // is dropped; close() is in progress and the harness is
+                    // tearing down, so the loss is expected. Without this catch
+                    // the rejection would escape the void-IIFE as an unhandled
+                    // promise rejection on the event loop.
+                    if (cause instanceof Error && cause.name === "AgentClosedError") {
+                        logger.warn `INBOX watch dropped uid=${event.uid} because the agent closed mid-delivery`;
+                        return;
+                    }
+                    logger.error `INBOX watch failed for uid=${event.uid}: ${cause}`;
+                }
+            })();
+        });
+        async function close() {
+            if (stopped)
+                return;
+            stopped = true;
+            unsubscribe();
+            stopReplyDrain = true;
+            await agent.close();
+            // The reply-drain loop exits once the underlying stream closes
+            // (close() above terminates streamConsumers). Awaiting here makes
+            // close idempotent and lets callers rely on a settled state.
+            await replyDrainDone;
+        }
+        const harness = {
+            close,
+            deliver: (message) => agent.deliver(message),
+            setSource: (source) => agent.setSource(source),
+            setSources: (sources, defaultSource) => agent.setSources(sources, defaultSource),
+            stream: () => agent.stream(),
+            blobReader: agent.blobReader,
+        };
+        harnessSucceeded = true;
+        return harness;
+    }
+    finally {
+        if (!harnessSucceeded) {
+            // Close the agent without waiting on its shutdown timeout so a
+            // synchronous post-`createAgent` throw does not stall the
+            // caller's failure path. The `.catch` swallows any rejection
+            // from the close: the caller is already receiving the original
+            // throw, and a noisier-than-original close failure here would
+            // mask it.
+            void agent.close().catch(() => {
+                // Swallow per the comment above.
+            });
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { createHarness, defineMailTools, type Harness, type MailEnv, type MailToolWrapper, } from "./harness.js";
+export { createHarnessRuntimeCapabilities } from "./runtime-capabilities.js";
+export type { HarnessRuntimeCapabilitiesOptions } from "./runtime-capabilities.js";
+export { createCredentialProviderRegistry, createHttpCredentialProvider, builtinCredentialProviders, } from "./credential-providers.js";
+export type { CredentialProviderRegistry, FetchLike, HttpCredentialProviderOptions, } from "./credential-providers.js";
+export { createCredentialCapability, reconcileDeclaredCredentials, } from "./credential-capability.js";
+export type { CredentialCapabilityDeps, HostCredentialCapability, ResolvedCredentialBinding, } from "./credential-capability.js";
+export { createConnectorRouter, NoActiveConnectorThreadError, } from "./connector-router.js";
+export type { ConnectorRouter, ConnectorReplyParts, ConnectorRouterOptions, RouteDecision, } from "./connector-router.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { createHarness, defineMailTools, } from "./harness.js";
+export { createHarnessRuntimeCapabilities } from "./runtime-capabilities.js";
+export { createCredentialProviderRegistry, createHttpCredentialProvider, builtinCredentialProviders, } from "./credential-providers.js";
+export { createCredentialCapability, reconcileDeclaredCredentials, } from "./credential-capability.js";
+export { createConnectorRouter, NoActiveConnectorThreadError, } from "./connector-router.js";

package/dist/runtime-capabilities.d.ts

@@ -0,0 +1,6 @@
+import { type RuntimeCapabilities } from "@intx/types/runtime-capabilities";
+import type { MessageTransport } from "@intx/types/runtime";
+export interface HarnessRuntimeCapabilitiesOptions {
+    transport: MessageTransport;
+}
+export declare function createHarnessRuntimeCapabilities(opts: HarnessRuntimeCapabilitiesOptions): RuntimeCapabilities;

package/dist/runtime-capabilities.js

@@ -0,0 +1,10 @@
+// Harness-side factory for the RuntimeCapabilities that tool packages
+// consume. The wrapper exists so callers (sidecar, alternate runtimes)
+// pass a config object keyed by domain (`transport`) and the harness
+// owns the translation to RuntimeCapabilityMap keys (`mail.transport`).
+// When new capabilities are added, callers' shapes evolve through this
+// wrapper, not at the call site.
+import { createRuntimeCapabilities, } from "@intx/types/runtime-capabilities";
+export function createHarnessRuntimeCapabilities(opts) {
+    return createRuntimeCapabilities({ "mail.transport": opts.transport });
+}

package/package.json

@@ -1,19 +1,35 @@
 {
   "name": "@intx/harness",
-  "version": "0.1.2",
+  "description": "Mail-transport composition layer over @intx/agent adding INBOX watch and connector routing",
+  "version": "0.3.0",
   "license": "LGPL-2.1-only",
   "type": "module",
   "exports": {
     ".": {
-      "types": "./src/index.ts",
-      "default": "./src/index.ts"
+      "intx-src": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     }
   },
   "dependencies": {
-    "@intx/inference": "0.0.0",
-    "@intx/log": "0.0.0",
-    "@intx/mime": "0.0.0",
-    "@intx/types": "0.0.0",
+    "@intx/agent": "0.3.0",
+    "@intx/authz": "0.3.0",
+    "@intx/log": "0.3.0",
+    "@intx/types": "0.3.0"
+  },
+  "devDependencies": {
+    "@intx/inference-testing": "0.3.0",
+    "@intx/mime": "0.3.0",
+    "@intx/storage-isogit": "0.3.0",
     "arktype": "^2.1.29"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
   }
 }

package/src/config.ts

@@ -1,135 +0,0 @@
-import type {
-  MessageTransport,
-  CryptoProvider,
-  ConnectorThreadState,
-  ContextStore,
-  AuditStore,
-  ToolRunner,
-  ToolDefinition,
-  InferenceSource,
-  InferenceEvent,
-  ReactorDirector,
-  BeforeToolExtension,
-} from "@intx/types/runtime";
-import type { AuthzCallResult, DefaultDirectorPolicy } from "@intx/inference";
-
-/**
- * Configuration passed to `createHarness`. All required fields must be
- * provided; none have defaults that silently mask missing values.
- */
-export type HarnessConfig = {
-  /** The agent's SMTP address, e.g. "agent@tenant.interchange.network". */
-  address: string;
-
-  /** System prompt for the agent's reasoning. */
-  systemPrompt: string;
-
-  /** Active inference source (id, provider, model, API key, etc.). */
-  source: InferenceSource;
-
-  /** Message transport implementation (SMTP/IMAP or in-memory). */
-  transport: MessageTransport;
-
-  /** Cryptographic provider for signing outbound messages. */
-  crypto: CryptoProvider;
-
-  /** Context store for persisting message history. */
-  storage: ContextStore;
-
-  /**
-   * Caller-supplied tool runner with the full set of tool definitions
-   * the model should see. The harness forwards this runner directly to
-   * the reactor; it does not layer additional tools on top. Callers
-   * composing multiple tool packages (e.g. mail + posix) should merge
-   * them with `mergeToolRunners` before passing the result here.
-   */
-  tools: ToolRunner & { definitions: ToolDefinition[] };
-
-  /** Callback invoked for every inference event emitted by the reactor. */
-  onEvent: (event: InferenceEvent) => void;
-
-  /**
-   * Optional callback invoked whenever the connector router's state changes
-   * (commit of a start/continue decision, an outbound reply send advancing
-   * lastMessageId, or load-time restore from the context store). Fires only
-   * on a real state change, not on no-op operations. Used by the sidecar to
-   * lift connector-state updates onto the hub-bound event channel.
-   */
-  onConnectorStateChanged?: (state: ConnectorThreadState | null) => void;
-
-  /**
-   * Optional custom director. When omitted, the default conversational director
-   * is used (message.received → infer → execute_tools loop → reply → wait).
-   */
-  director?: ReactorDirector;
-
-  /**
-   * Policy overrides for the default director. Mutually exclusive with
-   * `director`. Each field controls a specific decision point in the default
-   * director's event handling loop.
-   */
-  defaultDirectorPolicy?: DefaultDirectorPolicy;
-
-  /**
-   * Extensions that run before each tool call. Return a string to block the
-   * call (the string becomes the tool result), or undefined to allow it.
-   * When using `authorize`, the harness creates and prepends an authz
-   * extension automatically — do not also pass one here.
-   */
-  beforeToolExtensions?: BeforeToolExtension[];
-
-  /**
-   * Audit store for persisting tool invocation records. When provided,
-   * the harness creates an audit collector and flushes completed records
-   * at checkpoint boundaries and shutdown.
-   *
-   * Requires `authorize` to be set so the authz extension's onDecision
-   * callback can feed governance decisions to the collector.
-   */
-  auditStore?: AuditStore;
-
-  /**
-   * Authorization function for tool calls. When provided, the harness
-   * constructs an authz extension internally and prepends it to
-   * `beforeToolExtensions`. Callers should not also pass a manually
-   * constructed authz extension via `beforeToolExtensions`.
-   */
-  authorize?: (resource: string, action: string) => Promise<AuthzCallResult>;
-};
-
-export function validateConfig(config: HarnessConfig): void {
-  if (config.address.trim() === "") {
-    throw new Error("HarnessConfig.address must not be empty");
-  }
-  if (config.systemPrompt.trim() === "") {
-    throw new Error("HarnessConfig.systemPrompt must not be empty");
-  }
-  if (config.source.id.trim() === "") {
-    throw new Error("HarnessConfig.source.id must not be empty");
-  }
-  if (config.source.provider.trim() === "") {
-    throw new Error("HarnessConfig.source.provider must not be empty");
-  }
-  if (config.source.model.trim() === "") {
-    throw new Error("HarnessConfig.source.model must not be empty");
-  }
-  if (config.source.apiKey.trim() === "") {
-    throw new Error("HarnessConfig.source.apiKey must not be empty");
-  }
-  if (config.source.baseURL.trim() === "") {
-    throw new Error("HarnessConfig.source.baseURL must not be empty");
-  }
-  if (
-    config.director !== undefined &&
-    config.defaultDirectorPolicy !== undefined
-  ) {
-    throw new Error(
-      "HarnessConfig.director and HarnessConfig.defaultDirectorPolicy are mutually exclusive",
-    );
-  }
-  if (config.auditStore !== undefined && config.authorize === undefined) {
-    throw new Error(
-      "HarnessConfig.authorize is required when auditStore is provided",
-    );
-  }
-}