@intx/harness 0.1.2

package/README.md

@@ -0,0 +1,38 @@
+# @intx/harness
+
+Agent harness runtime. Composes the inference reactor, tool
+runners, deploy-tree reader, default director, runtime
+capabilities, and connector router into a single supervisor that
+sits between the message transport and the reactor.
+
+The harness watches the agent's INBOX, routes inbound messages by
+thread, sends connector replies with the right threading headers,
+and drives the reactor loop to completion. Consumed by
+`@intx/agent` for in-process agents and by `@intx/hub-agent` for
+sidecar-hosted agents.
+
+```ts
+import { createHarness, mergeToolRunners } from "@intx/harness";
+
+const harness = createHarness({
+  address: "agent@tenant.interchange.network",
+  systemPrompt,
+  source, // InferenceSource: id, provider, model, apiKey, baseURL
+  transport, // MessageTransport
+  crypto, // CryptoProvider
+  storage, // ContextStore
+  tools: mergeToolRunners([mailTools, posixTools]),
+  onEvent: (event) => {
+    // event: InferenceEvent — persist or forward
+  },
+});
+
+harness.start();
+```
+
+`HarnessConfig` in `src/config.ts` lists the optional fields:
+`director` or `defaultDirectorPolicy` (mutually exclusive),
+`beforeToolExtensions`, `auditStore`, `authorize`, and
+`onConnectorStateChanged`. `mergeToolRunners` composes multiple
+`ToolRunner` implementations into a single runner that dispatches
+by tool definition name.

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@intx/harness",
+  "version": "0.1.2",
+  "license": "LGPL-2.1-only",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@intx/inference": "0.0.0",
+    "@intx/log": "0.0.0",
+    "@intx/mime": "0.0.0",
+    "@intx/types": "0.0.0",
+    "arktype": "^2.1.29"
+  }
+}

package/src/config.ts

@@ -0,0 +1,135 @@
+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",
+    );
+  }
+}