@intx/harness 0.2.2 → 0.4.0

package/README.md

@@ -17,15 +17,19 @@ import {
 } from "@intx/agent";
 import { noopAuditStore, permissiveAuthorize } from "@intx/agent/testing";
 import { createHarness, defineMailTools } from "@intx/harness";
-import { createIsogitStore } from "@intx/storage-isogit";
+import { createIsogitStore } from "@intx/storage-isogit/node";
 
-const mailFactory = defineMailTools(() => ({
-  definitions: myMailTools.definitions,
-  run: (call, signal) => myMailTools.run(call, signal),
-}));
+const mailFactory = defineMailTools(
+  () => ({
+    definitions: myMailTools.definitions,
+    run: (call, signal) => myMailTools.run(call, signal),
+  }),
+  myMailTools.definitions.map((def) => ({ name: def.name })),
+);
 
 const posixFactory = defineTool({
   id: "@my-org/agent/posix",
+  definitions: myPosixTools.definitions.map((def) => ({ name: def.name })),
   factory: () => ({
     definitions: myPosixTools.definitions,
     run: (call, signal) => myPosixTools.run(call, signal),

package/dist/credential-capability.d.ts

@@ -0,0 +1,65 @@
+import { type GrantRule } from "@intx/authz";
+import type { CredentialCapability, CredentialMaterialSource } from "@intx/types";
+import type { ToolCredentialDeclaration } from "@intx/types/package-json";
+import type { CredentialProviderRegistry } from "./credential-providers.js";
+/**
+ * A binding resolved at launch: which credential backs a declared handle, which
+ * provider shapes it, the origin it authenticates to, and how to read its
+ * current material. The material source is an indirection over a mutable cell so
+ * a rotation reaches an already-shaped handle without a rebuild.
+ */
+export interface ResolvedCredentialBinding {
+    /** The credential row id the handle resolved to; the `credential:{id}` the
+     *  use-grant check runs against. */
+    credentialId: string;
+    /** The provider plugin key that shapes this credential's handle. */
+    providerKey: string;
+    /** The provider origin the shaped handle authenticates to. */
+    origin: string;
+    /** Reads the current secret material (rotation indirection). */
+    readCurrentMaterial: CredentialMaterialSource;
+}
+/**
+ * Reconcile a tool package's declared credential handles (its C5 `interchange.
+ * credentials`) against the handles a binding actually resolved for it. A
+ * declared handle with no binding is a launch-blocking misconfiguration -- the
+ * tool needs a credential the definition never bound -- so this fails the launch
+ * loudly rather than letting the gap surface as a resolve-time throw at the
+ * tool's first use. It is the throw-on-missing of `resolve`, pulled earlier to
+ * launch where the whole set is known.
+ */
+export declare function reconcileDeclaredCredentials(consumer: string, declared: readonly ToolCredentialDeclaration[], boundHandles: ReadonlySet<string>): void;
+export interface CredentialCapabilityDeps {
+    /**
+     * The consumer identity of the tool package this capability serves
+     * (`tool:<package>`, from `toolConsumer`). Gate 2 checks each grant's
+     * `{ tool }` condition against this value; an empty identity fails closed.
+     */
+    consumer: string;
+    /** Resolved bindings keyed by the handle the tool declared. */
+    bindings: ReadonlyMap<string, ResolvedCredentialBinding>;
+    /** The registry that shapes a credential into a mediated handle. */
+    providers: CredentialProviderRegistry;
+    /** The grants in effect for this deploy (the consumer's run grants). */
+    grants: GrantRule[];
+}
+/**
+ * A `CredentialCapability` plus a host-only `dispose`. The tool sees only
+ * `resolve`; the host runs `dispose` on teardown to release every handle shaped
+ * through this capability (an http handle holds nothing; a future key-file /
+ * socket handle would).
+ */
+export interface HostCredentialCapability extends CredentialCapability {
+    dispose(): Promise<void>;
+}
+/**
+ * Build the consumer-gated `credentials` capability for one tool package.
+ *
+ * `resolve(handle)` fails closed at every step: an unbound handle throws; a
+ * handle the consumer is not authorized to use throws (Gate 2 -- the same
+ * `authorizeAction` the model-source path uses, here supplied the credential-use
+ * condition registry and this consumer). Only an authorized handle is shaped,
+ * once, and memoized so repeated resolves return the same instance and there is
+ * a single thing to dispose.
+ */
+export declare function createCredentialCapability(deps: CredentialCapabilityDeps): HostCredentialCapability;

package/dist/credential-capability.js

@@ -0,0 +1,98 @@
+// The consumer-gated `credentials` capability: the sub-registry a tool queries
+// by its declared handle to obtain a mediated credential. It is the runtime
+// gate that enforces the `{ tool }` condition on a materialized
+// `credential:{id}` / `use` grant -- the check the launch-time grant
+// materialization sets up but does not itself evaluate.
+//
+// The gate lives here, at the point of use, and fails closed: a handle resolves
+// only when the calling consumer holds `credential:{id}` / `use` with the
+// grant's `{ tool }` condition matching this consumer. The shaping of the
+// handle is delegated to the provider registry; the material is read fresh per
+// use (rotation indirection) from the source the binding carries.
+import { authorizeAction, CREDENTIAL_USE_CONDITIONS, } from "@intx/authz";
+/**
+ * Reconcile a tool package's declared credential handles (its C5 `interchange.
+ * credentials`) against the handles a binding actually resolved for it. A
+ * declared handle with no binding is a launch-blocking misconfiguration -- the
+ * tool needs a credential the definition never bound -- so this fails the launch
+ * loudly rather than letting the gap surface as a resolve-time throw at the
+ * tool's first use. It is the throw-on-missing of `resolve`, pulled earlier to
+ * launch where the whole set is known.
+ */
+export function reconcileDeclaredCredentials(consumer, declared, boundHandles) {
+    const missing = declared
+        .map((declaration) => declaration.handle)
+        .filter((handle) => !boundHandles.has(handle));
+    if (missing.length > 0) {
+        throw new Error(`consumer ${consumer} declares credential handle(s) that no binding resolves: ${missing.join(", ")}`);
+    }
+}
+/**
+ * Build the consumer-gated `credentials` capability for one tool package.
+ *
+ * `resolve(handle)` fails closed at every step: an unbound handle throws; a
+ * handle the consumer is not authorized to use throws (Gate 2 -- the same
+ * `authorizeAction` the model-source path uses, here supplied the credential-use
+ * condition registry and this consumer). Only an authorized handle is shaped,
+ * once, and memoized so repeated resolves return the same instance and there is
+ * a single thing to dispose.
+ */
+export function createCredentialCapability(deps) {
+    // Memoize the in-flight PROMISE, not the resolved handle, so two concurrent
+    // resolves of the same handle share one gate+shape and yield one instance
+    // (caching the value would let both miss the memo and shape twice, orphaning
+    // a handle). A deterministic failure -- unbound handle, denied gate, unknown
+    // provider -- caches too; it stays failed for this deploy, which is correct
+    // since grants do not change mid-deploy.
+    const shaped = new Map();
+    function shapeHandle(handle) {
+        return (async () => {
+            const binding = deps.bindings.get(handle);
+            if (binding === undefined) {
+                throw new Error(`no credential is bound to handle "${handle}" for consumer ${deps.consumer}`);
+            }
+            // Gate 2: fail closed unless the consumer holds credential:{id} / use with
+            // the grant's { tool } condition matching this consumer.
+            const decision = await authorizeAction(deps.grants, `credential:${binding.credentialId}`, "use", { registry: CREDENTIAL_USE_CONDITIONS, consumer: deps.consumer });
+            if (!decision.ok) {
+                throw new Error(`consumer ${deps.consumer} is not authorized to use credential ${binding.credentialId} (${decision.reason})`);
+            }
+            const provider = deps.providers.resolve(binding.providerKey);
+            return provider.shape({
+                origin: binding.origin,
+                readCurrentMaterial: binding.readCurrentMaterial,
+            });
+        })();
+    }
+    return {
+        resolve(handle) {
+            const existing = shaped.get(handle);
+            if (existing !== undefined)
+                return existing;
+            const pending = shapeHandle(handle);
+            shaped.set(handle, pending);
+            return pending;
+        },
+        async dispose() {
+            // Dispose EVERY successfully-shaped handle even if one throws -- a single
+            // bad handle must not strand the rest -- then surface any failures loudly
+            // rather than swallowing them.
+            const settled = await Promise.allSettled([...shaped.values()]);
+            shaped.clear();
+            const errors = [];
+            for (const result of settled) {
+                if (result.status !== "fulfilled")
+                    continue;
+                try {
+                    await result.value.dispose();
+                }
+                catch (error) {
+                    errors.push(error);
+                }
+            }
+            if (errors.length > 0) {
+                throw new AggregateError(errors, "one or more credential handles failed to dispose");
+            }
+        },
+    };
+}

package/dist/credential-providers.d.ts

@@ -0,0 +1,56 @@
+import type { CredentialProvider } from "@intx/types";
+/** Resolves a provider identifier to the plugin that shapes its handles. */
+export interface CredentialProviderRegistry {
+    has(key: string): boolean;
+    resolve(key: string): CredentialProvider;
+}
+/**
+ * Build a registry from a list of providers. The list is copied into a private
+ * `Map`, so callers cannot mutate the set after construction and lookups never
+ * reach `Object.prototype`. A duplicate key is a wiring error and throws at
+ * construction rather than silently shadowing.
+ */
+export declare function createCredentialProviderRegistry(providers: readonly CredentialProvider[]): CredentialProviderRegistry;
+/**
+ * The minimal call signature the shaped handle needs from `fetch`. The global
+ * `fetch` satisfies it; a test stub can too, without implementing the extra
+ * members (`preconnect`) the full `fetch` type carries.
+ */
+export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+/** Options for the built-in HTTP provider. */
+export interface HttpCredentialProviderOptions {
+    /**
+     * The `fetch` the shaped handle delegates to once the request is
+     * origin-checked and the auth header is injected. Defaults to the global
+     * `fetch`; injectable so origin-pinning can be exercised without a network.
+     */
+    fetch?: FetchLike;
+}
+/**
+ * The built-in HTTP credential provider. It shapes an `HttpMediatedCredential`:
+ * an authed `fetch` pinned to the credential's provider origin, injecting the
+ * current secret as a bearer token per request. The material is read fresh on
+ * every call, so a rotation that updates the underlying cell is picked up
+ * without rebuilding the handle.
+ *
+ * Origin pinning is load-bearing security: the handle authenticates only the
+ * initial, origin-checked request and never follows redirects. A request whose
+ * resolved origin is not the pinned one is refused, and a server 3xx is
+ * returned to the caller unfollowed (`redirect: "manual"`), so the bearer is
+ * never sent to any origin but the pinned one. Transparent redirect-following
+ * is intentionally not provided: a tool re-issues a same-origin redirect target
+ * through the handle (a cross-origin one is refused). This keeps token safety
+ * in the handle rather than resting on the injected `fetch`'s redirect
+ * behavior.
+ *
+ * Bearer is the only auth scheme today; providers that authenticate differently
+ * (a `token` scheme, an `x-api-key` header) are separate plugins, not a branch
+ * here.
+ */
+export declare function createHttpCredentialProvider(opts?: HttpCredentialProviderOptions): CredentialProvider;
+/**
+ * The built-in credential providers every host registers. A single `http`
+ * provider today; a host composes additional providers by extending the list
+ * passed to `createCredentialProviderRegistry`.
+ */
+export declare function builtinCredentialProviders(): CredentialProvider[];

package/dist/credential-providers.js

@@ -0,0 +1,123 @@
+// Credential provider plugins: the seam that shapes a resolved provider-backed
+// credential into a mediated handle a consumer can use. A provider owns HOW the
+// handle authenticates (an authed `fetch`, a future key-file + socket); it is
+// given a material source and never acquires material or decides authorization
+// -- both happen upstream, at the delivery boundary, before a provider is
+// consulted.
+//
+// The registry mirrors @intx/inference's AdapterRegistry: a Map-backed lookup
+// keyed by provider identifier, prototype-pollution-safe (a Map never consults
+// Object.prototype, so an untrusted key like "toString" resolves to the loud
+// unknown-provider error rather than an inherited member), throw-on-missing.
+/**
+ * Build a registry from a list of providers. The list is copied into a private
+ * `Map`, so callers cannot mutate the set after construction and lookups never
+ * reach `Object.prototype`. A duplicate key is a wiring error and throws at
+ * construction rather than silently shadowing.
+ */
+export function createCredentialProviderRegistry(providers) {
+    const byKey = new Map();
+    for (const provider of providers) {
+        if (byKey.has(provider.key)) {
+            throw new Error(`Duplicate credential provider key: ${provider.key}`);
+        }
+        byKey.set(provider.key, provider);
+    }
+    return {
+        has(key) {
+            return byKey.has(key);
+        },
+        resolve(key) {
+            const provider = byKey.get(key);
+            if (provider === undefined) {
+                throw new Error(`Unknown credential provider: ${key}`);
+            }
+            return provider;
+        },
+    };
+}
+/**
+ * The built-in HTTP credential provider. It shapes an `HttpMediatedCredential`:
+ * an authed `fetch` pinned to the credential's provider origin, injecting the
+ * current secret as a bearer token per request. The material is read fresh on
+ * every call, so a rotation that updates the underlying cell is picked up
+ * without rebuilding the handle.
+ *
+ * Origin pinning is load-bearing security: the handle authenticates only the
+ * initial, origin-checked request and never follows redirects. A request whose
+ * resolved origin is not the pinned one is refused, and a server 3xx is
+ * returned to the caller unfollowed (`redirect: "manual"`), so the bearer is
+ * never sent to any origin but the pinned one. Transparent redirect-following
+ * is intentionally not provided: a tool re-issues a same-origin redirect target
+ * through the handle (a cross-origin one is refused). This keeps token safety
+ * in the handle rather than resting on the injected `fetch`'s redirect
+ * behavior.
+ *
+ * Bearer is the only auth scheme today; providers that authenticate differently
+ * (a `token` scheme, an `x-api-key` header) are separate plugins, not a branch
+ * here.
+ */
+export function createHttpCredentialProvider(opts) {
+    const fetchImpl = opts?.fetch ?? globalThis.fetch;
+    return {
+        key: "http",
+        shape(context) {
+            const pinnedOrigin = new URL(context.origin).origin;
+            return {
+                kind: "http",
+                async fetch(input, init) {
+                    const target = resolveTargetUrl(input, pinnedOrigin);
+                    if (target.origin !== pinnedOrigin) {
+                        throw new Error(`http credential is pinned to ${pinnedOrigin}; refusing cross-origin request to ${target.origin}`);
+                    }
+                    // Read the secret fresh on every call so a rotation of the underlying
+                    // material cell reaches this handle without a rebuild.
+                    const { secret } = context.readCurrentMaterial();
+                    // redirect:"manual" is dictated by the handle, never inherited from
+                    // caller input. The origin check guards only the INITIAL url, so
+                    // following a server 3xx to a foreign origin would carry the bearer
+                    // off the pinned host. Instead the 3xx is returned to the caller
+                    // unfollowed: a same-origin target is re-issued through the handle
+                    // (which re-pins and re-auths); a cross-origin one is refused above.
+                    if (input instanceof Request) {
+                        // Re-issue the caller's request (method, body preserved) with the
+                        // auth header added and the redirect mode forced; its url was
+                        // origin-checked above.
+                        const headers = new Headers(input.headers);
+                        headers.set("authorization", `Bearer ${secret}`);
+                        return fetchImpl(new Request(input, { headers, redirect: "manual" }));
+                    }
+                    const headers = new Headers(init?.headers);
+                    headers.set("authorization", `Bearer ${secret}`);
+                    return fetchImpl(target, { ...init, headers, redirect: "manual" });
+                },
+                dispose() {
+                    // An http handle allocates no resources; nothing to release.
+                },
+            };
+        },
+    };
+}
+/**
+ * The built-in credential providers every host registers. A single `http`
+ * provider today; a host composes additional providers by extending the list
+ * passed to `createCredentialProviderRegistry`.
+ */
+export function builtinCredentialProviders() {
+    return [createHttpCredentialProvider()];
+}
+/**
+ * Resolve the URL a request targets. A relative string resolves against the
+ * pinned origin (so a tool can call `/repos`); an absolute string or URL keeps
+ * its own origin (and is refused by the caller if it differs); a `Request`
+ * carries an absolute URL already.
+ */
+function resolveTargetUrl(input, pinnedOrigin) {
+    if (typeof input === "string") {
+        return new URL(input, pinnedOrigin);
+    }
+    if (input instanceof URL) {
+        return input;
+    }
+    return new URL(input.url);
+}

package/dist/harness.d.ts

@@ -1,4 +1,4 @@
-import { type Agent, type AgentDefinition, type AnnotatedToolFactory, type BaseEnv, type ToolBundle } from "@intx/agent";
+import { type Agent, type AgentDefinition, type AnnotatedToolFactory, type BaseEnv, type ToolBundle, type ToolDeclaration } from "@intx/agent";
 import type { BlobReader, ConnectorThreadState, ContextStore, InboundMessage, InferenceSource, MessageTransport } from "@intx/types/runtime";
 import { createConnectorRouter } from "./connector-router.js";
 /**
@@ -64,45 +64,6 @@ export interface Harness {
  * implementation to use.
  */
 export type MailToolWrapper = (transport: MessageTransport) => Omit<ToolBundle, "dispose">;
-/**
- * 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 declare function invokeReplySendFailed(callback: NonNullable<MailEnv["onReplySendFailed"]>, cause: unknown): Promise<void>;
-/**
- * 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 declare function invokeReplyDrainTerminated(callback: NonNullable<MailEnv["onReplyDrainTerminated"]>, cause: unknown): Promise<void>;
 /**
  * Build the `load` / `writeMetadata` overrides the harness layers onto
  * `env.storage`. Extracted from `createHarness` so the dirty-bit gating
@@ -118,12 +79,11 @@ export declare function invokeReplyDrainTerminated(callback: NonNullable<MailEnv
  * 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.
+ * consumer should call it. 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 declare function createWrappedStorageOverrides(baseStorage: ContextStore, connectorRouter: ReturnType<typeof createConnectorRouter>, isInMemoryStateAuthoritative: () => boolean): Pick<ContextStore, "load" | "writeMetadata">;
 /**
@@ -167,8 +127,14 @@ export declare function createWrappedStorageOverrides(baseStorage: ContextStore,
  * 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 declare function defineMailTools(wrapper: MailToolWrapper): AnnotatedToolFactory<MailEnv>;
+export declare function defineMailTools(wrapper: MailToolWrapper, definitions: readonly ToolDeclaration[]): AnnotatedToolFactory<MailEnv>;
 /**
  * Construct a composition-layer agent: the underlying agent wrapped
  * with connector-state-aware storage, transport subscription, INBOX

package/dist/harness.js

@@ -14,60 +14,8 @@
 import { createAgent, defineTool, } from "@intx/agent";
 import { getLogger } from "@intx/log";
 import { createConnectorRouter } from "./connector-router.js";
+import { driveConnectorReplies } from "./reply-drain.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
@@ -83,12 +31,11 @@ export async function invokeReplyDrainTerminated(callback, cause) {
  * 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.
+ * consumer should call it. 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 {
@@ -146,11 +93,18 @@ export function createWrappedStorageOverrides(baseStorage, connectorRouter, isIn
  * 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) {
+export function defineMailTools(wrapper, definitions) {
     return defineTool({
         id: "@intx/harness/mail",
         requires: ["transport", "address"],
+        definitions,
         factory: (env) => {
             const bundle = wrapper(env.transport);
             return {
@@ -230,8 +184,8 @@ export async function createHarness(def, env) {
     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()`,
+    // and the workdir lock is held. Anything that throws -- the
+    // `driveConnectorReplies` setup, `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.
@@ -245,63 +199,24 @@ export async function createHarness(def, env) {
         // 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);
-                }
-            }
-        })();
+        // The shared `driveConnectorReplies` helper owns the loop: reply
+        // serialization (a second reply waits for the first's receipt to
+        // advance the router before composing its own), per-reply failure
+        // surfacing to `onReplySendFailed`, and abnormal-termination
+        // surfacing to `onReplyDrainTerminated`. The warm workflow-host
+        // path drives replies through the same helper.
+        const replyDrain = driveConnectorReplies({
+            stream: agent.stream(),
+            composeReply: () => connectorRouter.composeReply(),
+            send: (message) => transport.send(message),
+            onReplySent: (receipt) => connectorRouter.onReplySent(receipt),
+            ...(env.onReplySendFailed !== undefined
+                ? { onSendFailed: env.onReplySendFailed }
+                : {}),
+            ...(env.onReplyDrainTerminated !== undefined
+                ? { onTerminated: env.onReplyDrainTerminated }
+                : {}),
+        });
         // Delete a message from the INBOX after it has been delivered to the
         // reactor.
         //
@@ -405,12 +320,12 @@ export async function createHarness(def, env) {
                 return;
             stopped = true;
             unsubscribe();
-            stopReplyDrain = true;
+            replyDrain.stop();
             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;
+            await replyDrain.done;
         }
         const harness = {
             close,

package/dist/index.d.ts

@@ -1,5 +1,11 @@
 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";
+export { driveConnectorReplies } from "./reply-drain.js";
+export type { AgentEventStream, ConnectorReplyDrain, ConnectorReplyDrainOpts, ReplySettlement, } from "./reply-drain.js";

package/dist/index.js

@@ -1,3 +1,6 @@
 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";
+export { driveConnectorReplies } from "./reply-drain.js";

package/dist/reply-drain.d.ts

@@ -0,0 +1,123 @@
+import type { Agent } from "@intx/agent";
+import type { OutboundMessage, SendReceipt } from "@intx/types/runtime";
+import type { ConnectorReplyParts } from "./connector-router.js";
+/**
+ * The agent event stream the drain consumes -- exactly `agent.stream()`'s
+ * type. The stream yields the reactor's full emitted-event union (wider than
+ * `InferenceEvent`: it also carries `message.received`), so the drain accepts
+ * that union and lets every non-`connector.reply` event flow past untouched.
+ */
+export type AgentEventStream = ReturnType<Agent["stream"]>;
+export interface ConnectorReplyDrainOpts {
+    /** The agent event stream to drain. Each `connector.reply` sends a reply. */
+    stream: AgentEventStream;
+    /**
+     * Produce the threading headers (`to`, `cc`, `inReplyTo`, `subject`) for
+     * the active connector thread. Throws when no thread is active; the throw
+     * is caught per reply and routed to `onSendFailed`.
+     */
+    composeReply: () => ConnectorReplyParts;
+    /**
+     * Send the composed reply. The drain builds the `OutboundMessage` from
+     * `composeReply()`'s parts plus the reply content and a
+     * `conversation.message` type; the caller's `send` routes it to the
+     * transport / outbound bridge.
+     */
+    send: (message: OutboundMessage) => Promise<SendReceipt>;
+    /**
+     * Resolve the full RFC 5322 References chain for a reply whose parent is
+     * `inReplyTo` (the Message-Id of the message being answered). Returns the
+     * parent's own References plus the parent's Message-Id, in order, so the
+     * outbound reply carries the complete conversational ancestry rather than
+     * a truncated single element. Returns `undefined` when the parent cannot be
+     * located (the very first reply on a fresh thread, or a malformed id); the
+     * drain then omits `references` and the transport derives `[inReplyTo]`.
+     *
+     * Optional: a caller with no mailbox to consult (`createHarness`) omits it,
+     * leaving the pre-existing single-element threading unchanged. The warm
+     * workflow-host wiring supplies it from the deployment's committed mailbox.
+     */
+    resolveReferences?: (inReplyTo: string) => Promise<string[] | undefined>;
+    /**
+     * Advance connector state after a successful send. May be synchronous
+     * (the in-process router's `onReplySent`) or asynchronous (a durable
+     * store that persists the advanced `lastMessageId`); the drain awaits it
+     * before composing the next reply.
+     */
+    onReplySent: (receipt: SendReceipt) => void | Promise<void>;
+    /**
+     * Invoked when `composeReply`, `send`, or `onReplySent` throws for one
+     * reply. The reply is dropped and the connector thread stays at its
+     * pre-send value. The drain awaits the callback (so an async callback's
+     * rejection is observed and logged, not left as an unhandled rejection)
+     * and absorbs any error it raises.
+     */
+    onSendFailed?: (cause: unknown) => void | Promise<void>;
+    /**
+     * Invoked when the stream's `for await` loop exits abnormally -- the
+     * documented case is a backpressure error thrown by the agent event
+     * stream. After it fires the drain no longer forwards replies. Awaited
+     * and absorbed the same way as `onSendFailed`.
+     */
+    onTerminated?: (cause: unknown) => void | Promise<void>;
+}
+/**
+ * The settled outcome of one reply the drain processed. `ok` distinguishes a
+ * durably-sent reply (the send acked and `onReplySent` advanced the thread)
+ * from a failed one (compose, send, or `onReplySent` threw). A caller gating a
+ * side effect on the reply reaching the transport awaits the barrier and acts
+ * only on `ok: true`; `ok: false` carries the failure `cause` so the caller can
+ * surface it rather than treat the reply as sent.
+ */
+export type ReplySettlement = {
+    readonly ok: true;
+    readonly receipt: SendReceipt;
+} | {
+    readonly ok: false;
+    readonly cause: unknown;
+};
+export interface ConnectorReplyDrain {
+    /**
+     * Settles once the drain loop has exited and its last pending reply has
+     * drained. Always resolves -- per-reply and terminal failures are routed
+     * to the callbacks, never thrown out of here -- so a caller can await it
+     * on teardown without guarding a rejection.
+     */
+    readonly done: Promise<void>;
+    /**
+     * Signal the loop to stop at the next event. The loop also exits on its
+     * own when the underlying stream ends (e.g. the agent closes); `stop()`
+     * is the cooperative early exit for a caller tearing down before then.
+     */
+    stop(): void;
+    /**
+     * The count of replies that have SETTLED so far -- sent-and-acked or failed.
+     * Monotonic. A per-turn caller captures this BEFORE the `agent.send` that may
+     * produce a reply, then, for a turn that did produce a `connector.reply`,
+     * awaits `waitForReplyAfter(captured)` to block until THIS turn's reply
+     * settles. The capture-before-send ordering is required: the agent resolves
+     * `agent.send` in the same synchronous step that pushes the `connector.reply`
+     * onto this drain's stream, so the reply is not yet enqueued when `send`
+     * resolves -- a post-send snapshot would miss it.
+     */
+    replySeq(): number;
+    /**
+     * Resolve once more than `n` replies have settled -- i.e. the reply at index
+     * `n` (the `(n + 1)`th reply the drain processed) has settled -- with that
+     * reply's settlement. Because the warm agent is strictly serial and the drain
+     * is FIFO, a turn that captured `n` from `replySeq()` before its send and
+     * produced exactly one reply awaits reply `n` here.
+     *
+     * When the drain loop exits (stream end, `stop()`, or an abnormal
+     * termination) before reply `n` settles, resolves with a failure settlement
+     * rather than hanging, so a caller awaiting a reply that will never arrive
+     * fails its turn instead of blocking forever.
+     */
+    waitForReplyAfter(n: number): Promise<ReplySettlement>;
+}
+/**
+ * Drive an agent's `connector.reply` events out through a transport. Returns
+ * immediately with a handle; the drain runs in the background until the
+ * stream ends or `stop()` is called.
+ */
+export declare function driveConnectorReplies(opts: ConnectorReplyDrainOpts): ConnectorReplyDrain;

package/dist/reply-drain.js

@@ -0,0 +1,179 @@
+// Shared connector reply drain for the agent harness.
+//
+// A director emits a `connector.reply` event when the agent produces an
+// outbound reply on its connector thread. Draining that event means:
+// compose the threading headers for the active thread, send the reply
+// through the transport, then advance the thread's `lastMessageId` from
+// the send receipt. This module owns that loop so both the harness
+// composition layer (`createHarness`) and the warm workflow-host agent
+// path drive replies through one implementation rather than each keeping
+// its own copy.
+//
+// The loop subscribes an agent event stream and serializes every reply
+// through a single chain: two replies fired in quick succession do not
+// interleave their compose / send / onReplySent sequence -- the second
+// waits for the first's receipt to advance the thread before composing
+// against it. A per-reply failure (compose, send, or onReplySent) is
+// surfaced to `onSendFailed` and the reply is dropped with the thread left
+// at its pre-send state; an abnormal stream termination (e.g. an agent
+// stream backpressure violation) is surfaced to `onTerminated`. Neither
+// escapes the returned `done` promise -- it always resolves -- so a caller
+// can await teardown without guarding a rejection.
+import { getLogger } from "@intx/log";
+const logger = getLogger(["interchange", "harness", "reply-drain"]);
+async function invokeAbsorbing(callback, cause, label) {
+    try {
+        await callback(cause);
+    }
+    catch (callbackError) {
+        logger.error `${label} callback threw: ${callbackError}`;
+    }
+}
+/**
+ * Drive an agent's `connector.reply` events out through a transport. Returns
+ * immediately with a handle; the drain runs in the background until the
+ * stream ends or `stop()` is called.
+ */
+export function driveConnectorReplies(opts) {
+    let stopped = false;
+    // Reply sends are serialized through `replyChain` so two replies fired in
+    // quick succession do not interleave their compose / send / onReplySent
+    // sequence -- the second waits for the first's receipt to advance the
+    // thread before composing its own.
+    let replyChain = Promise.resolve();
+    // Per-turn settle barrier. `settlements[i]` is the outcome of the `i`th reply
+    // the drain processed; `settlements.length` is the monotonic settled count a
+    // caller snapshots through `replySeq()`. Waiters block until the settled
+    // count passes their target index, then resolve with that reply's outcome. A
+    // reply is recorded here on BOTH success and failure so a waiter never hangs;
+    // the outcome's `ok` tells the caller which happened.
+    const settlements = [];
+    let terminated = false;
+    let waiters = [];
+    const terminalSettlement = () => ({
+        ok: false,
+        cause: new Error("connector reply drain terminated before the reply was sent"),
+    });
+    function settlementAt(index) {
+        const settlement = settlements[index];
+        if (settlement === undefined) {
+            // Reached only if a waiter resolves for an index the drain never
+            // recorded -- an internal invariant break, surfaced loudly rather than
+            // handed back as a silent fallback.
+            throw new Error(`connector reply drain: settlement ${String(index)} missing though ` +
+                `${String(settlements.length)} replies have settled`);
+        }
+        return settlement;
+    }
+    function recordSettlement(settlement) {
+        settlements.push(settlement);
+        const settledCount = settlements.length;
+        const stillWaiting = [];
+        for (const waiter of waiters) {
+            if (settledCount > waiter.target) {
+                waiter.resolve(settlementAt(waiter.target));
+            }
+            else {
+                stillWaiting.push(waiter);
+            }
+        }
+        waiters = stillWaiting;
+    }
+    function releaseWaitersOnTermination() {
+        terminated = true;
+        const outstanding = waiters;
+        waiters = [];
+        for (const waiter of outstanding) {
+            // A waiter whose reply settled before teardown gets its real outcome; one
+            // whose reply never arrived (the drain stopped first) gets a terminal
+            // failure so the caller fails its turn rather than blocking.
+            waiter.resolve(settlements.length > waiter.target
+                ? settlementAt(waiter.target)
+                : terminalSettlement());
+        }
+    }
+    const done = (async () => {
+        try {
+            for await (const event of opts.stream) {
+                if (stopped)
+                    break;
+                if (event.type !== "connector.reply")
+                    continue;
+                const content = event.data.content;
+                replyChain = replyChain.then(async () => {
+                    try {
+                        const parts = opts.composeReply();
+                        // Resolve the full References ancestry for the parent this reply
+                        // answers, when the caller supplies a resolver. A resolver miss
+                        // (parent absent, malformed id) yields `undefined`, and the
+                        // transport derives `[inReplyTo]` as before.
+                        const references = opts.resolveReferences !== undefined
+                            ? await opts.resolveReferences(parts.inReplyTo)
+                            : undefined;
+                        const receipt = await opts.send({
+                            ...parts,
+                            content,
+                            type: "conversation.message",
+                            ...(references !== undefined && references.length > 0
+                                ? { references }
+                                : {}),
+                        });
+                        await opts.onReplySent(receipt);
+                        recordSettlement({ ok: true, receipt });
+                    }
+                    catch (cause) {
+                        // The reply is dropped and the connector thread stays at its
+                        // pre-send value. Surface the loss to `onSendFailed` in addition
+                        // to the operator-facing log so programmatic consumers (retries,
+                        // alerting) can observe what the log alone hides. Record the
+                        // failure on the barrier too, so a per-turn caller awaiting this
+                        // reply sees `ok: false` rather than treating it as sent.
+                        logger.error `Failed to send connector reply: ${cause}`;
+                        if (opts.onSendFailed !== undefined) {
+                            await invokeAbsorbing(opts.onSendFailed, cause, "onSendFailed");
+                        }
+                        recordSettlement({ ok: false, cause });
+                    }
+                });
+            }
+        }
+        catch (cause) {
+            // The agent's stream throws on backpressure violations; log and exit.
+            // The reply path stops working but the caller's other consumers keep
+            // running until teardown. Surface the loss to `onTerminated` so
+            // programmatic consumers (alerting, watchdogs) can observe it.
+            logger.warn `Reply-drain stream terminated: ${cause}`;
+            if (opts.onTerminated !== undefined) {
+                await invokeAbsorbing(opts.onTerminated, cause, "onTerminated");
+            }
+        }
+        finally {
+            // Drain the pending reply before the loop exits so its settlement is
+            // recorded and a caller awaiting `done` sees a settled state. Then
+            // release any barrier waiter still blocked on a reply that will never
+            // arrive, so a per-turn caller cannot hang past teardown.
+            await replyChain;
+            releaseWaitersOnTermination();
+        }
+    })();
+    return {
+        done,
+        stop() {
+            stopped = true;
+        },
+        replySeq() {
+            return settlements.length;
+        },
+        waitForReplyAfter(n) {
+            if (settlements.length > n) {
+                return Promise.resolve(settlementAt(n));
+            }
+            if (terminated) {
+                return Promise.resolve(terminalSettlement());
+            }
+            return new Promise((resolve) => {
+                waiters.push({ target: n, resolve });
+            });
+        },
+    };
+}

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@intx/harness",
-  "version": "0.2.2",
+  "description": "Mail-transport composition layer over @intx/agent adding INBOX watch and connector routing",
+  "version": "0.4.0",
   "license": "LGPL-2.1-only",
   "type": "module",
   "exports": {
@@ -11,14 +12,15 @@
     }
   },
   "dependencies": {
-    "@intx/agent": "0.2.2",
-    "@intx/log": "0.2.2",
-    "@intx/types": "0.2.2"
+    "@intx/agent": "0.4.0",
+    "@intx/authz": "0.4.0",
+    "@intx/log": "0.4.0",
+    "@intx/types": "0.4.0"
   },
   "devDependencies": {
-    "@intx/inference-testing": "0.2.2",
-    "@intx/mime": "0.2.2",
-    "@intx/storage-isogit": "0.2.2",
+    "@intx/inference-testing": "0.4.0",
+    "@intx/mime": "0.4.0",
+    "@intx/storage-isogit": "0.4.0",
     "arktype": "^2.1.29"
   },
   "files": [