@inflexa-ai/harness 0.36.4 → 0.38.0

package/dist/execution/run-authorizer.d.ts

@@ -14,7 +14,9 @@
  * Mirrors the `SessionPagePublisher` seam: a narrow interface in the harness, the managed
  * realization injected at the composition root.
  */
+import type { ResultAsync } from "neverthrow";
 import type { AuthContext, Provenance, RunFrame, RunSession, Scope } from "../auth/types.js";
+import type { GateFailure, NoticeFailure } from "../lib/hooks.js";
 /**
  * Locates a run credential when no `RunAuthorization` exists: the persisted
  * jti from `cortex_runs` plus the revoking caller's opaque `auth` — the sole
@@ -48,8 +50,8 @@ export interface RunAuthorization {
  * path (a no-op for reused or local authorizations).
  */
 export interface RunAuthorizer {
-    authorize(input: AuthorizeRunInput): Promise<RunAuthorization>;
-    revoke(authorization: RunAuthorization, reason: string): Promise<void>;
+    authorize(input: AuthorizeRunInput): ResultAsync<RunAuthorization, GateFailure>;
+    revoke(authorization: RunAuthorization, reason: string): ResultAsync<void, NoticeFailure>;
     /**
      * Out-of-band revocation for paths holding no `RunAuthorization`. Normal
      * terminal paths use `revoke(authorization, reason)` under the run
@@ -57,5 +59,5 @@ export interface RunAuthorizer {
      * credential's JWT was never persisted and only its jti survives on
      * `cortex_runs`. Local/OSS authorizers no-op — they mint no jti.
      */
-    revokeByJti(ref: RevokeByJtiRef, reason: string): Promise<void>;
+    revokeByJti(ref: RevokeByJtiRef, reason: string): ResultAsync<void, NoticeFailure>;
 }

package/dist/execution/run-canceler.js

@@ -18,6 +18,7 @@
  * terminal frame read-side.
  */
 import { createNoopLogger } from "../lib/console-logger.js";
+import { deliverNotice } from "../lib/hooks.js";
 import { elapsedSinceIso, recordRunCompleted, recordStepCompleted } from "../lib/metrics.js";
 import { unwrapOrThrow } from "../lib/result.js";
 import { markRunCanceledIfActive, queryRun } from "../state/runs.js";
@@ -113,26 +114,9 @@ export function createRunCanceler(deps) {
             catch (err) {
                 logger.error("pending-step sweep failed", { runId, ...logger.errorFields(err) });
             }
-            // Best-effort: the billing authority self-heals (defensive open + stale
-            // reaper), so a failed close loses attribution only.
-            let charge = false;
-            try {
-                await runCharge.close({ analysisId: row.analysisId, runId, reason: "canceled", session });
-                charge = true;
-            }
-            catch (err) {
-                logger.error("running-charge close failed", { runId, ...logger.errorFields(err) });
-            }
-            let mandate = row.mandateJti === null;
-            if (row.mandateJti !== null) {
-                try {
-                    await runAuthorizer.revokeByJti({ jti: row.mandateJti, auth: session.auth }, EXTERNAL_CANCEL_REASON);
-                    mandate = true;
-                }
-                catch (err) {
-                    logger.error("mandate revoke failed", { runId, jti: row.mandateJti, ...logger.errorFields(err) });
-                }
-            }
+            const charge = await deliverNotice(logger.with({ runId }), "RunCharge.close", runCharge.close({ analysisId: row.analysisId, runId, outcome: { kind: "canceled" }, session }));
+            const mandate = row.mandateJti === null ||
+                (await deliverNotice(logger.with({ runId, jti: row.mandateJti }), "RunAuthorizer.revokeByJti", runAuthorizer.revokeByJti({ jti: row.mandateJti, auth: session.auth }, EXTERNAL_CANCEL_REASON)));
             // No transition means the run reached a terminal state on its own (or the
             // write failed) — report the row as it stands rather than claiming `canceled`.
             let finalStatus = "canceled";

package/dist/index.d.ts

@@ -24,10 +24,10 @@ export type { ConversationAgentDeps } from "./agents/conversation-agent.js";
 export type { BioToolKeys } from "./tools/bio/keys.js";
 export { createLocalRunAuthorizer } from "./auth/local-run-authorizer.js";
 export type { RunAuthorizer, AuthorizeRunInput, RunAuthorization, RevokeByJtiRef } from "./execution/run-authorizer.js";
-export { createNoopBillingResolver } from "./billing/noop-resolver.js";
-export type { ResolveBilling, ResolvableSession, BillingMap, BillingHeaders, BillingFetchResult } from "./billing/resolver.js";
+export type { GateFailure, NoticeFailure } from "./lib/hooks.js";
+export type { RequestHeaders, ResolveRequestHeaders } from "./providers/request-headers.js";
 export { createNoopRunCharge } from "./billing/noop-run-charge.js";
-export type { RunCharge } from "./billing/run-charge.js";
+export type { RunCharge, RunChargeOutcome } from "./billing/run-charge.js";
 export { createNoopUsageRecorder } from "./billing/noop-usage-recorder.js";
 export type { UsageRecorder, LlmUsageRecord } from "./billing/usage-recorder.js";
 export { createNoopArtifactRegistry } from "./execution/noop-artifact-registry.js";
@@ -63,12 +63,12 @@ export type { RunAgentOptions, RunAgentResult, AgentFinish } from "./loop/run-ag
 export type { AgentDefinition, RunStep, EmitFn, EmitEvent, EventSource } from "./loop/types.js";
 export { passthroughStep } from "./loop/run-step.js";
 export { forStep, forSubAgent, scopeResource, scopeWorkloadId } from "./auth/types.js";
-export type { AgentSession, RequestSession, RunSession, Identity, Scope, Credential, Provenance, RunFrame, AuthContext, ResourceCoordinates, } from "./auth/types.js";
+export type { AgentSession, RequestSession, RunSession, Identity, Scope, Credential, Provenance, RunFrame, AuthContext, ResourceCoordinates, HookSessionView, ResolvableSession, } from "./auth/types.js";
 export { makeLocalAuth } from "./auth/local-auth-context.js";
 export { createAnthropicProvider } from "./providers/anthropic.js";
 export type { AnthropicProviderDeps } from "./providers/anthropic.js";
 export { createConfiguredAiSdkProvider, DEFAULT_MAX_OUTPUT_TOKENS } from "./providers/ai-sdk.js";
-export type { AiSdkProviderConfig, ConfiguredAiSdkProviderDeps } from "./providers/ai-sdk.js";
+export type { AiSdkProviderConfig, ConfiguredAiSdkProviderDeps, ProviderHostPolicy } from "./providers/ai-sdk.js";
 export { createEmbeddingProvider } from "./providers/embedding.js";
 export type { EmbeddingProviderDeps } from "./providers/embedding.js";
 export type { AgentChat, ChatProvider, EmbeddingProvider, ChatRequest, ChatResponse, ChatStreamEvent, ChatUsage, ModelMessage, PromptCachePolicy, ReasoningPolicy, } from "./providers/types.js";
@@ -76,6 +76,10 @@ export { DEFAULT_PROMPT_CACHE, promptCacheProviderOptions, withPromptCacheBreakp
 export { DEFAULT_REASONING } from "./providers/reasoning.js";
 export { toProviderError, isProviderError } from "./providers/errors.js";
 export type { ProviderError } from "./providers/errors.js";
+export { DEFAULT_SUSPEND_ON } from "./providers/errors.js";
+export type { SuspendOn } from "./providers/errors.js";
+export { suspensionOfFailure } from "./workflows/suspension.js";
+export type { Suspension } from "./workflows/suspension.js";
 export { createStreamingChat } from "./providers/streaming-chat.js";
 export { prepareChatTurn } from "./app/chat-turn.js";
 export type { PrepareChatTurnDeps, PrepareChatTurnParams, PrepareChatTurnResult } from "./app/chat-turn.js";
@@ -137,8 +141,10 @@ export type { ResolveWorkspaceRoot } from "./workspace/paths.js";
 export { createSandboxClient } from "./sandbox/create-sandbox.js";
 export type { CreateSandboxClientConfig, SandboxBackendConfig } from "./sandbox/create-sandbox.js";
 export type { SandboxClient } from "./sandbox/client.js";
-export { describeSandboxError, SandboxFailure } from "./sandbox/sandbox-error.js";
-export type { SandboxError } from "./sandbox/sandbox-error.js";
+export type { ResolveSandboxLabels, SandboxLabels, SandboxSpec } from "./sandbox/types.js";
+export type { SpawnSession } from "./auth/types.js";
+export { describeSandboxError, keepSuspendingRefusal, SandboxFailure } from "./sandbox/sandbox-error.js";
+export type { SandboxError, SuspendingRefusal } from "./sandbox/sandbox-error.js";
 export type { ExtendAnalysisFarm, FarmLocation, FarmResolution, FarmSource, PackageRequestOutcome, ResolveAnalysisFarm, ToolchainSource, } from "./sandbox/types.js";
 export { formatQuery, identityAddress, identityKey, identityOf, parseIdentityKey, parseQuery, pythonIdentity, resolveQuery, rIdentity, } from "./sandbox/package-identity.js";
 export type { PackageIdentity, PackageQuery, ParseQueryError, PoolIndex, QueryResolution, Track } from "./sandbox/package-identity.js";

package/dist/index.js

@@ -29,13 +29,11 @@ export { bootHarness } from "./runtime/boot.js";
 export { createConversationAgent } from "./agents/conversation-agent.js";
 // Seam: run authorization.
 export { createLocalRunAuthorizer } from "./auth/local-run-authorizer.js";
-// Seam: billing resolution.
-export { createNoopBillingResolver } from "./billing/noop-resolver.js";
 // Seam: run-level billing bracket.
 export { createNoopRunCharge } from "./billing/noop-run-charge.js";
-// Seam: per-call LLM usage accounting. `record` is fire-and-forget — the loop
-// neither awaits nor guards it, so a realization must not throw and must not
-// block. Wired as the optional `usageRecorder` of `assembleCoreRuntime`;
+// Seam: per-call LLM usage accounting. `record` is a notice: the loop does not
+// wait for its result, and it logs the reason of an err when the result
+// arrives. Wired as the optional `usageRecorder` of `assembleCoreRuntime`;
 // unwired, every call is dropped by `createNoopUsageRecorder`.
 export { createNoopUsageRecorder } from "./billing/noop-usage-recorder.js";
 // Seam: artifact registration.
@@ -135,6 +133,12 @@ export { DEFAULT_REASONING } from "./providers/reasoning.js";
 // directly needs: `chatStream` throws a `ProviderError` value (a plain object,
 // not an `Error`), so a `catch` recognizes it by shape, not `instanceof`.
 export { toProviderError, isProviderError } from "./providers/errors.js";
+// The suspend map of a provider: an HTTP status to the suspend reason of the
+// host. A map from the host replaces `DEFAULT_SUSPEND_ON`, which holds `402`.
+export { DEFAULT_SUSPEND_ON } from "./providers/errors.js";
+// The suspension of work. A host reads the suspend reason of a failed chat turn
+// with `suspensionOfFailure`, by the kind of the error, never by its text.
+export { suspensionOfFailure } from "./workflows/suspension.js";
 // `createStreamingChat` wraps a `ChatProvider` as a streaming `AgentChat` (the
 // type `runAgent`'s `provider` option takes): its `chat` drives the provider's
 // `chatStream` and forwards each text delta to `onText`, so a same-process host
@@ -248,7 +252,9 @@ export { computeInputSignature } from "./execution/input-signature.js";
 export { createSandboxClient } from "./sandbox/create-sandbox.js";
 // The throw of the client seam. An embedder matches the class and reads the
 // typed variant on `error`, instead of a string match on the message.
-export { describeSandboxError, SandboxFailure } from "./sandbox/sandbox-error.js";
+// `createSandbox` gives each failure as an `err`, and `keepSuspendingRefusal`
+// keeps a refusal of the label hook with the suspend flag as a value and throws each other failure.
+export { describeSandboxError, keepSuspendingRefusal, SandboxFailure } from "./sandbox/sandbox-error.js";
 // The identity of a package, the query that asks for one, and the resolution
 // between the two. An embedder reads `by_name` of the dependency graph with
 // these, thus the host lookup, the census, and the graph key never disagree on

package/dist/lib/hooks.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The two kinds of host hook: a gate and a notice.
+ *
+ * A gate gives a value or a permission that the harness must have before it
+ * can continue an operation. A notice reports a fact after the operation. The
+ * type of each hook shows its kind:
+ *
+ *   gate:   (input) => ResultAsync<T, GateFailure>
+ *   notice: (input) => ResultAsync<void, NoticeFailure>
+ *
+ * The harness calls each hook through `passGate` or `deliverNotice`, thus no
+ * call site selects its own failure policy, and no call site puts a `try` or a
+ * `catch` around a hook. A hook gives a failure as an `err`. A hook whose
+ * promise rejects has a defect, and the rejection passes through the helpers
+ * with no change.
+ *
+ * The reason of a failure is the text of the host. The harness carries it and
+ * never reads it. The flag `suspend` is part of the contract, thus the harness
+ * branches on it.
+ */
+import { ResultAsync } from "neverthrow";
+import type { Logger } from "./logger.js";
+export interface GateFailure {
+    readonly reason: string;
+    /** True when the host asks the harness to suspend the work in place of a failure. */
+    readonly suspend: boolean;
+}
+export interface NoticeFailure {
+    readonly reason: string;
+}
+export type GateName = "RunAuthorizer.authorize" | "RunCharge.open" | "ArtifactRegistry.register" | "resolveRequestHeaders" | "resolveSandboxLabels";
+export type NoticeName = "RunAuthorizer.revoke" | "RunAuthorizer.revokeByJti" | "RunCharge.close" | "ArtifactRegistry.sync" | "UsageRecorder.record";
+export type GateRefusal = {
+    readonly kind: "failed";
+    readonly gate: GateName;
+    readonly reason: string;
+} | {
+    readonly kind: "suspended";
+    readonly gate: GateName;
+    readonly reason: string;
+};
+/**
+ * The host can build its `Result` with its own copy of neverthrow. The helper
+ * gives the outcome again as a `Result` of the copy of the harness. Thus the
+ * checkpoint recipes (`runtime/result-serialization.ts`) recognize the class,
+ * and a replay reads the same outcome.
+ */
+export declare function passGate<T>(gate: GateName, result: ResultAsync<T, GateFailure>): ResultAsync<T, GateRefusal>;
+export declare function deliverNotice(log: Logger, notice: NoticeName, result: ResultAsync<void, NoticeFailure>): Promise<boolean>;

package/dist/lib/hooks.js

@@ -0,0 +1,39 @@
+/**
+ * The two kinds of host hook: a gate and a notice.
+ *
+ * A gate gives a value or a permission that the harness must have before it
+ * can continue an operation. A notice reports a fact after the operation. The
+ * type of each hook shows its kind:
+ *
+ *   gate:   (input) => ResultAsync<T, GateFailure>
+ *   notice: (input) => ResultAsync<void, NoticeFailure>
+ *
+ * The harness calls each hook through `passGate` or `deliverNotice`, thus no
+ * call site selects its own failure policy, and no call site puts a `try` or a
+ * `catch` around a hook. A hook gives a failure as an `err`. A hook whose
+ * promise rejects has a defect, and the rejection passes through the helpers
+ * with no change.
+ *
+ * The reason of a failure is the text of the host. The harness carries it and
+ * never reads it. The flag `suspend` is part of the contract, thus the harness
+ * branches on it.
+ */
+import { err, ok, ResultAsync } from "neverthrow";
+/**
+ * The host can build its `Result` with its own copy of neverthrow. The helper
+ * gives the outcome again as a `Result` of the copy of the harness. Thus the
+ * checkpoint recipes (`runtime/result-serialization.ts`) recognize the class,
+ * and a replay reads the same outcome.
+ */
+export function passGate(gate, result) {
+    return new ResultAsync(Promise.resolve(result).then((settled) => settled.isOk()
+        ? ok(settled.value)
+        : err({ kind: settled.error.suspend ? "suspended" : "failed", gate, reason: settled.error.reason })));
+}
+export async function deliverNotice(log, notice, result) {
+    const delivered = await result;
+    if (delivered.isOk())
+        return true;
+    log.error("a notice of the host failed", { notice, reason: delivered.error.reason });
+    return false;
+}

package/dist/lib/result.d.ts

@@ -4,20 +4,31 @@
  * The agent loop and execution boundary model failure as values, not throws.
  * The house rules:
  *
- *  1. `try/catch` lives ONLY inside the thin wrappers at calls to code
- *     external to ours — a third-party SDK, the `pg` driver, `fs`, the DBOS
- *     runtime. Those wrappers turn a throw into an `err(DomainError)`.
- *     Everything above them flows `Result` / `ResultAsync`.
+ *  1. `try/catch` lives ONLY at a boundary:
+ *       - the thin wrappers at calls to code external to ours — a third-party
+ *         SDK, the `pg` driver, `fs`, the DBOS runtime. Those wrappers turn a
+ *         throw into an `err(DomainError)`.
+ *       - an API entry point, where a caller outside the harness gets the
+ *         outcome.
+ *       - a workflow body that gets the throw of a failed step or a failed
+ *         child workflow, and runs its failure path.
+ *       - the dispatch catch of the loop.
+ *     Everything else flows `Result` / `ResultAsync`. A host hook has no
+ *     `try/catch` around it: `passGate` / `deliverNotice` (`lib/hooks.ts`)
+ *     consume its `Result`.
  *  2. Absence is NOT an error. A "not found" stays in the ok channel as a
  *     data variant (`ok({ found: false })`), never an `err`. `err` is
  *     reserved for what used to be `throw`n — an unexpected upstream failure.
  *  3. A `Result` is unwrapped at exactly three edges, each speaking its own
  *     dialect of failure:
  *       - HTTP routes `.match(...)` a `Result` into a response.
- *       - The DBOS step boundary throws on `err` (`unwrapOrThrow` /
- *         `resultStep` in `loop/run-step.ts`): durability records a step as
- *         failed — and retries / fails fast — ONLY on a thrown exception, so
- *         an `err` crossing `DBOS.runStep` MUST become a throw.
+ *       - The DBOS step boundary throws on an `err` that must fail or retry
+ *         the step (`unwrapOrThrow` / `resultStep` in `loop/run-step.ts`):
+ *         durability records a step as failed — and retries / fails fast —
+ *         ONLY on a thrown exception. A step can also return a `Result` as
+ *         its value: `runtime/result-serialization.ts` keeps the `Ok` / `Err`
+ *         class across the checkpoint, DBOS records the step as a success,
+ *         and the body MUST use the `err`.
  *       - Tool dispatch maps `err` into an `is_error` `tool_result`
  *         (`loop/run-agent.ts`).
  *
@@ -43,9 +54,9 @@ export interface DomainError {
 /**
  * A thrown wrapper for a structured error value that is not already an
  * `Error`. The original value rides on `.cause`, so the cause-walking
- * classifiers (`classifyProviderError`, `isBudgetExceeded`) still reach the
- * `status` / `code` signals they look for after a `Result` is rethrown at a
- * boundary.
+ * classifiers (`classifyProviderError`, `findSuspendError`) still reach the
+ * `status` / `code` / `type` signals they look for after a `Result` is
+ * rethrown at a boundary.
  */
 export declare class ResultError extends Error {
     readonly value: unknown;

package/dist/lib/result.js

@@ -4,20 +4,31 @@
  * The agent loop and execution boundary model failure as values, not throws.
  * The house rules:
  *
- *  1. `try/catch` lives ONLY inside the thin wrappers at calls to code
- *     external to ours — a third-party SDK, the `pg` driver, `fs`, the DBOS
- *     runtime. Those wrappers turn a throw into an `err(DomainError)`.
- *     Everything above them flows `Result` / `ResultAsync`.
+ *  1. `try/catch` lives ONLY at a boundary:
+ *       - the thin wrappers at calls to code external to ours — a third-party
+ *         SDK, the `pg` driver, `fs`, the DBOS runtime. Those wrappers turn a
+ *         throw into an `err(DomainError)`.
+ *       - an API entry point, where a caller outside the harness gets the
+ *         outcome.
+ *       - a workflow body that gets the throw of a failed step or a failed
+ *         child workflow, and runs its failure path.
+ *       - the dispatch catch of the loop.
+ *     Everything else flows `Result` / `ResultAsync`. A host hook has no
+ *     `try/catch` around it: `passGate` / `deliverNotice` (`lib/hooks.ts`)
+ *     consume its `Result`.
  *  2. Absence is NOT an error. A "not found" stays in the ok channel as a
  *     data variant (`ok({ found: false })`), never an `err`. `err` is
  *     reserved for what used to be `throw`n — an unexpected upstream failure.
  *  3. A `Result` is unwrapped at exactly three edges, each speaking its own
  *     dialect of failure:
  *       - HTTP routes `.match(...)` a `Result` into a response.
- *       - The DBOS step boundary throws on `err` (`unwrapOrThrow` /
- *         `resultStep` in `loop/run-step.ts`): durability records a step as
- *         failed — and retries / fails fast — ONLY on a thrown exception, so
- *         an `err` crossing `DBOS.runStep` MUST become a throw.
+ *       - The DBOS step boundary throws on an `err` that must fail or retry
+ *         the step (`unwrapOrThrow` / `resultStep` in `loop/run-step.ts`):
+ *         durability records a step as failed — and retries / fails fast —
+ *         ONLY on a thrown exception. A step can also return a `Result` as
+ *         its value: `runtime/result-serialization.ts` keeps the `Ok` / `Err`
+ *         class across the checkpoint, DBOS records the step as a success,
+ *         and the body MUST use the `err`.
  *       - Tool dispatch maps `err` into an `is_error` `tool_result`
  *         (`loop/run-agent.ts`).
  *
@@ -32,9 +43,9 @@ import { Err, Ok } from "neverthrow";
 /**
  * A thrown wrapper for a structured error value that is not already an
  * `Error`. The original value rides on `.cause`, so the cause-walking
- * classifiers (`classifyProviderError`, `isBudgetExceeded`) still reach the
- * `status` / `code` signals they look for after a `Result` is rethrown at a
- * boundary.
+ * classifiers (`classifyProviderError`, `findSuspendError`) still reach the
+ * `status` / `code` / `type` signals they look for after a `Result` is
+ * rethrown at a boundary.
  */
 export class ResultError extends Error {
     value;
@@ -49,9 +60,8 @@ function describe(value) {
         return value.message;
     if (value && typeof value === "object" && "type" in value) {
         // Prefer a human `message` field when the structured error carries one
-        // (e.g. a `ProviderError`) so the wrapped `Error.message` stays
-        // pattern-matchable (`isBudgetExceeded`'s message backstop); fall back
-        // to the `type` discriminant otherwise.
+        // (e.g. a `ProviderError`) so the wrapped `Error.message` names the
+        // failure; fall back to the `type` discriminant otherwise.
         const message = value.message;
         if (typeof message === "string" && message.length > 0)
             return message;

package/dist/loop/run-agent.d.ts

@@ -100,8 +100,8 @@ export interface RunAgentOptions {
     readonly logger?: Logger;
     /**
      * Per-call LLM usage-accounting seam. Omitted falls back to the no-op
-     * recorder. Delivery is fire-and-forget by contract — the loop neither
-     * awaits `record` nor guards it, so a realization must not throw or block.
+     * recorder. `record` is a notice: the loop does not wait for its result,
+     * and it logs the reason of an `err` when the result arrives.
      */
     readonly usageRecorder?: UsageRecorder;
     /**

package/dist/loop/run-agent.js

@@ -3,6 +3,7 @@ import { jsonSchema, tool as aiTool, } from "ai";
 import { createNoopUsageRecorder } from "../billing/noop-usage-recorder.js";
 import { stripNulCharacters } from "../input-sanitization.js";
 import { createNoopLogger } from "../lib/console-logger.js";
+import { deliverNotice } from "../lib/hooks.js";
 import { ATTR_INFLEXA_TOOL_USE_ID, passThroughSpan, stableSpan } from "../lib/otel-spans.js";
 import { ResultError } from "../lib/result.js";
 import { describeZodIssueShapes } from "../lib/zod-issue-shape.js";
@@ -150,8 +151,8 @@ async function runAgentLoop(agent, initial, session, opts) {
      * reported nothing to account for, so it is folded (to no effect) and left
      * out of the ledger rather than entered as an all-absent record.
      *
-     * Delivery is bare — no `await`, no `try` — because the `UsageRecorder`
-     * contract forbids `record` to throw or block.
+     * `record` is a notice. The loop does not wait for its result, thus a
+     * recorder that blocks does not make the run slower.
      */
     const accountForCall = (reply, stepName) => {
         addChatUsage(usage, reply.usage);
@@ -159,7 +160,7 @@ async function runAgentLoop(agent, initial, session, opts) {
         const reported = reply.usage;
         if (reported === undefined || !hasReportedUsage(reported))
             return;
-        usageRecorder.record({
+        void deliverNotice(log, "UsageRecorder.record", usageRecorder.record({
             recordKey: recordKeyFor(session, opts.invocationId, stepName),
             agentId: source.agentId,
             callPath: source.callPath,
@@ -169,7 +170,7 @@ async function runAgentLoop(agent, initial, session, opts) {
             ...(reply.requestedModelId === undefined ? {} : { requestedModelId: reply.requestedModelId }),
             ...(reply.servedModelId === undefined ? {} : { servedModelId: reply.servedModelId }),
             usage: reported,
-        });
+        }));
     };
     /** The rollups this loop stamps on its finish — each absent when nothing reported. */
     const finishUsage = () => ({

package/dist/memory/conversation-display-replay.js

@@ -23,7 +23,20 @@ export function storedMessagesToCortex(messages) {
     let append = null;
     for (const row of messages) {
         if (row.displayEnvelope) {
-            append = conversationUIToCortexMessages(row.displayEnvelope.messages);
+            // The author and the creation time are facts about the ROW, the same as
+            // the rollup below, and the projection holds neither. Both ride the row
+            // that opens the append, and the author reaches the `user` messages
+            // alone, because `role` already names the sender of a reply. Spread
+            // conditionally: an absent value must leave no key, or a consumer that
+            // spreads the message acquires one that overwrites a real value. `Date`
+            // does not survive the JSON crossing typed, hence the ISO string here.
+            const createdAt = row.createdAt === undefined ? {} : { createdAt: row.createdAt.toISOString() };
+            const author = row.author === undefined ? {} : { author: row.author };
+            append = conversationUIToCortexMessages(row.displayEnvelope.messages).map((message) => ({
+                ...message,
+                ...createdAt,
+                ...(message.role === "user" ? author : {}),
+            }));
             out.push(...append);
         }
         // The reported rollup of the turn and its duration both ride the model row that

package/dist/memory/thread-history.d.ts

@@ -55,6 +55,20 @@ export interface StoredMessage {
      * reported no quantity still reads back with the duration that it took.
      */
     readonly durationMs?: number;
+    /**
+     * Who sent the user message of the append this row OPENED — present only on a
+     * genuine-user-start row of a turn appended with one. A row written before the
+     * column existed carries none, because no sender was ever recorded for it.
+     */
+    readonly author?: string;
+    /**
+     * When the store wrote this row: the START time of the append transaction,
+     * thus every row of one append holds the same value, and `seq` alone orders
+     * rows. The read sets it on every row, because the column is `NOT NULL`. It is
+     * optional because a fake or a fixture builds a `StoredMessage` with no row
+     * behind it.
+     */
+    readonly createdAt?: Date;
 }
 /**
  * One atomic append: the exact provider-facing history, the display projection of
@@ -86,6 +100,16 @@ export interface ConversationTurn {
      * reported no quantity still keeps the duration that it took.
      */
     readonly turnDurationMs?: number;
+    /**
+     * Who sent the user message of this turn — the identity the host holds at the
+     * append site. Stored on the FIRST row of the append, and only when that row
+     * is a genuine user start: that row also carries the display projection, thus
+     * the write and the transcript replay read one row under one rule. A record
+     * append opens on a synthetic row, so it stores no author however a caller
+     * spreads one in. The value is NUL-stripped on the way in, the same as the
+     * envelope, because a `text` parameter carrying 0x00 fails the statement.
+     */
+    readonly author?: string;
 }
 /**
  * The append a host uses to record out-of-band work in a thread — an analysis

package/dist/memory/thread-history.js

@@ -181,7 +181,7 @@ export const EVICTION_BLOCK_TURNS = 4;
  */
 export function createThreadHistory(pool, logger) {
     function appendTurn(threadId, turn) {
-        const { modelMessages: messages, displayMessages, turnUsage, turnDurationMs } = turn;
+        const { modelMessages: messages, displayMessages, turnUsage, turnDurationMs, author } = turn;
         if (messages.length === 0)
             return okVoid();
         // The display projection rides the append's FIRST row, so one SELECT of a
@@ -206,6 +206,13 @@ export function createThreadHistory(pool, logger) {
         // the turn. -1 (a turn that persisted no reply — an abort before any output)
         // matches no index below, so nothing is written and the append still succeeds.
         const lastAssistantRow = messages.reduce((last, m, i) => (m.role === "assistant" ? i : last), -1);
+        // The author rides the row the display projection rides, and only when that
+        // row is a message a person actually sent — an assistant row, a tool row,
+        // and the synthetic opening row of a record append are not. NUL is dropped
+        // rather than refused: a 0x00 byte in a `text` parameter fails the
+        // statement, and one byte in a label would roll the whole turn back.
+        const turnAuthor = author === undefined ? null : stripNulCharacters(author);
+        const authorRow = messages[0] !== undefined && isGenuineUserStart(messages[0]) ? 0 : -1;
         return withTransaction(pool, "thread-history.appendTurn", (client) => 
         // Serialize concurrent appends on this thread — without the lock, two
         // transactions can both read the same MAX(seq) and collide on the
@@ -224,14 +231,15 @@ export function createThreadHistory(pool, logger) {
         // `message_envelope::json`, never `::jsonb`; `display_envelope` and
         // `reported_usage::jsonb`, never `::json` — see the column comments
         // in the state-init DDL.
-        `INSERT INTO messages (thread_id, seq, message_envelope, display_envelope, tokens, reported_usage, turn_duration_ms)
-                     VALUES ($1, $2, $3::json, $4::jsonb, $5, $6::jsonb, $7)
+        `INSERT INTO messages (thread_id, seq, message_envelope, display_envelope, tokens, reported_usage, turn_duration_ms, author)
+                     VALUES ($1, $2, $3::json, $4::jsonb, $5, $6::jsonb, $7, $8)
                      ON CONFLICT (thread_id, seq) DO UPDATE
                        SET message_envelope = EXCLUDED.message_envelope,
                            display_envelope = EXCLUDED.display_envelope,
                            tokens = EXCLUDED.tokens,
                            reported_usage = EXCLUDED.reported_usage,
-                           turn_duration_ms = EXCLUDED.turn_duration_ms`, [
+                           turn_duration_ms = EXCLUDED.turn_duration_ms,
+                           author = EXCLUDED.author`, [
             threadId,
             startSeq + i,
             serializeEnvelope(message),
@@ -239,6 +247,7 @@ export function createThreadHistory(pool, logger) {
             countTokens(message.content),
             i === lastAssistantRow ? rollup : null,
             i === lastAssistantRow ? duration : null,
+            i === authorRow ? turnAuthor : null,
         ])).map(() => undefined)), okVoid()))
             .andThen(() => 
         // Thread listings sort on `cortex_analysis_threads.updated_at`, and
@@ -368,12 +377,14 @@ export function createThreadHistory(pool, logger) {
         // `seq::text AS seq` output alias (Postgres resolves an unqualified
         // ORDER BY name to the output column), sorting the bigint as text:
         // "10" before "2". The qualified name forces the bigint column.
-        `SELECT seq::text AS seq, message_envelope, display_envelope, reported_usage, turn_duration_ms::text AS turn_duration_ms
+        `SELECT seq::text AS seq, message_envelope, display_envelope, reported_usage, turn_duration_ms::text AS turn_duration_ms, author, created_at
          FROM messages WHERE thread_id = $1
          ORDER BY messages.seq ASC`, [threadId]);
         // Spread rather than `usage: r.reported_usage ?? undefined`, so a row with
         // no rollup carries no `usage` KEY at all — absent, not present-and-undefined.
-        // The duration obeys the same rule, and it reads from its own column.
+        // The duration and the author obey the same rule, each from its own column.
+        // The creation time is unconditional: its column is NOT NULL, thus it has no
+        // absence to represent.
         const stored = await Promise.all(rows.map(async (r) => {
             const envelope = parseStoredMessageEnvelope(r.message_envelope, `${threadId}/${r.seq}`);
             const displayEnvelope = r.display_envelope == null ? undefined : await parseStoredDisplayEnvelope(r.display_envelope, `${threadId}/${r.seq}/display`, logger);
@@ -384,6 +395,8 @@ export function createThreadHistory(pool, logger) {
                 ...(displayEnvelope ? { displayEnvelope } : {}),
                 ...(r.reported_usage === null ? {} : { usage: r.reported_usage }),
                 ...(r.turn_duration_ms === null ? {} : { durationMs: Number(r.turn_duration_ms) }),
+                ...(r.author === null ? {} : { author: r.author }),
+                createdAt: r.created_at,
             };
         }));
         return groupTurns(stored, (row) => isGenuineUserStart(row.message));

package/dist/provenance/seam.d.ts

@@ -69,7 +69,7 @@ export type RunProvenanceEvent = {
     runId: string;
     /**
      * The body's terminal status. Both boundary sites resolve it through `deriveFinalStatus`,
-     * which records a budget pause as `"canceled"` — so `"suspended_insufficient_funds"` (a
+     * which records a suspension as `"canceled"` — so `"suspended_insufficient_funds"` (a
      * `RunStatus` member) is never emitted here and is deliberately absent from this narrower
      * `ExecuteAnalysisFinalStatus`-minus-`"running"` set.
      */