@intx/harness 0.1.2 → 0.3.0

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

@@ -0,0 +1,188 @@
+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";
+/**
+ * Env extension the composition layer requires beyond `BaseEnv`. Tools
+ * shipped by this package declare the matching `requires` so
+ * `validateEnv` can blame either at the env entry point.
+ *
+ * `onReplySendFailed` is invoked when the reply drain catches a failure
+ * from `connectorRouter.composeReply` or `transport.send` for an
+ * outbound `connector.reply`. The reply is dropped and the router
+ * state is not advanced; the callback is the only programmatic surface
+ * a caller has to observe the loss. Production deployments that need
+ * retry semantics layer them on top of this callback.
+ *
+ * The callback may be synchronous or async; the reply drain awaits its
+ * resolution so an async callback's rejection is observed (and logged)
+ * rather than surfacing as an unhandled promise rejection.
+ *
+ * `onReplyDrainTerminated` is invoked when the reply drain's `for await`
+ * loop exits abnormally -- the only documented case is a
+ * `StreamBackpressureError` thrown by the agent's event stream when the
+ * drain's per-consumer buffer overruns `streamBufferMax`. After this
+ * fires the harness is no longer forwarding `connector.reply` events to
+ * the transport: in-process `agent.send()` callers still resolve, but
+ * outbound replies are silently dropped until `close()`. Production
+ * deployments that need to alert on this failure mode subscribe via
+ * this callback; the harness only emits a `logger.warn` otherwise. The
+ * callback may be synchronous or async and is awaited the same way
+ * `onReplySendFailed` is, so an async rejection is observed (and
+ * logged) rather than escaping as an unhandled rejection.
+ */
+export interface MailEnv extends BaseEnv {
+    transport: MessageTransport;
+    address: string;
+    onConnectorStateChanged?: (state: ConnectorThreadState | null) => void;
+    onReplySendFailed?: (cause: unknown) => void | Promise<void>;
+    onReplyDrainTerminated?: (cause: unknown) => void | Promise<void>;
+}
+/**
+ * Narrowed public surface returned by `createHarness`. `close` is the
+ * only direct surface; everything else is a pass-through to the
+ * underlying agent. `stream` is exposed so observability consumers can
+ * subscribe to the reactor's event stream without having to grab the
+ * agent reference.
+ */
+export interface Harness {
+    close(): Promise<void>;
+    deliver(message: InboundMessage): void;
+    setSource(source: InferenceSource): void;
+    setSources(sources: InferenceSource[], defaultSource: string): void;
+    stream: Agent["stream"];
+    readonly blobReader: BlobReader;
+}
+/**
+ * Mail-tool factory shape. The `createMailTools` constructor in
+ * `@intx/tools-mail` builds a runner from a transport-bearing
+ * capability set; the harness wraps that into a single `defineTool`
+ * bundle whose `requires` names the env keys the wrapper touches.
+ *
+ * Callers (e.g. the sidecar) supply the wrapper as a tool factory on
+ * their `AgentDefinition`. `createHarness` does not synthesize it
+ * internally -- the caller is the layer that knows which mail-tool
+ * 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
+ * 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 declare function createWrappedStorageOverrides(baseStorage: ContextStore, connectorRouter: ReturnType<typeof createConnectorRouter>, isInMemoryStateAuthoritative: () => boolean): Pick<ContextStore, "load" | "writeMetadata">;
+/**
+ * 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 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
+ * 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 declare function createHarness<EnvReq extends MailEnv>(def: AgentDefinition<EnvReq>, env: EnvReq): Promise<Harness>;