@nylorun/runtime 0.23.0-beta → 0.24.0-beta

package/dist/tenant/transcript.d.ts

@@ -4,6 +4,9 @@
  * Payload schemas: `@nylorun/core/contracts` (`parseTranscriptEvent`).
  */
 import type { HostEffect } from "@nylorun/harness/run";
+import type { TOOL_CALL_KINDS, TOOL_CALL_STATUSES } from "@nylorun/core/contracts";
+export type ToolCallStatus = (typeof TOOL_CALL_STATUSES)[number];
+export type ToolCallKind = (typeof TOOL_CALL_KINDS)[number];
 /** The model's tool call id and the harness invocation, for tool effects. */
 export declare function toolIds(context: unknown): {
     callId: string;
@@ -11,7 +14,9 @@ export declare function toolIds(context: unknown): {
 } | Record<string, never>;
 /**
  * `message.assistant` for a completed model effect: the step's text and tool calls. The
- * provider returns a `ModelCandidate` or a bare string; anything else writes no event.
+ * provider returns a `ModelCandidate` or a bare string. A step that said nothing (no text, no
+ * tool calls; a structured answer) is still one event, with `text: ""` (R7.1): every model call
+ * has its outcome row. Readers that build a conversation skip it (`isEmptyAssistantMessage`).
  */
 export declare function assistantMessage(request: HostEffect, value: unknown): {
     agent: import("@nylorun/core/define").AgentRef;
@@ -46,7 +51,8 @@ export declare function assistantMessage(request: HostEffect, value: unknown): {
 } | undefined;
 /**
  * `context.compacted` for a model effect that summarized history (Model Calls §8): the
- * engine replaced the older transcript with that summary.
+ * engine replaced the older transcript with that summary. A partial summary (one call of
+ * several) is marked `partial: true` (R7.1): only the last call's event replaced the history.
  */
 export declare function contextCompacted(request: HostEffect, value: unknown): {
     agent: import("@nylorun/core/define").AgentRef;
@@ -54,12 +60,14 @@ export declare function contextCompacted(request: HostEffect, value: unknown): {
     trigger: "overflow" | "threshold";
     tokensBefore: number;
     tokensAfter: number;
+    partial?: true | undefined;
 } | {
     agent?: undefined;
     invocationId?: string | undefined;
     trigger: "overflow" | "threshold";
     tokensBefore: number;
     tokensAfter: number;
+    partial?: true | undefined;
 } | undefined;
 /** `model.failed` for a model effect that completed with a failure outcome (Model Calls §6.4). */
 export declare function modelFailed(request: HostEffect, value: unknown): {
@@ -75,59 +83,149 @@ export declare function modelFailed(request: HostEffect, value: unknown): {
     message: string;
     retryable: boolean;
 } | undefined;
-/** `tool.completed` for a tool the Runtime ran: its output, or the tool error it reported. */
-export declare function toolCompleted(request: HostEffect, value: unknown): {
+/** A gate's own start and end of a call (R7.1). */
+export interface GateTimes {
+    readonly startedAt: string;
+    readonly endedAt: string;
+}
+/** What the usage ledger holds for a model call (R7.1): its `model_usage` row's columns. */
+export interface MeteredCall {
+    readonly startedAt: string | null;
+    readonly endedAt: string | null;
+    readonly firstTokenMs: number | null;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly totalTokens: number;
+    readonly cachedTokens: number;
+    readonly costUsd: number;
+}
+/** From `startedAt` to `endedAt` in whole milliseconds; undefined unless both are times. */
+export declare function durationBetween(startedAt: string | undefined, endedAt: string | undefined): number | undefined;
+/**
+ * The timing a model call's outcome event carries (R7.1): its effect id, the journal's window
+ * (`startedAt` on the row to `settledAt`), and, when the gate metered the call (`metered`), the
+ * gate's own start and end, the first token's time and the metered usage.
+ */
+export declare function modelOutcomeFacts(effectId: string, window: {
+    startedAt?: string;
+    settledAt?: string;
+}, metered: MeteredCall | undefined): {
+    effectId: string;
+    durationMs?: number | undefined;
+    gate?: {
+        startedAt: string;
+        endedAt: string;
+    } | undefined;
+    firstTokenMs?: number | undefined;
+    meteredUsage?: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        cachedTokens?: number | undefined;
+        costUsd?: number | undefined;
+    } | undefined;
+};
+/** What the Tenant's tool policy did with a call, when it did more than allow it (R7.1). */
+export interface ToolPolicyFact {
+    readonly decision: "ask" | "deny";
+    readonly reason: string;
+    readonly approvedBy?: string;
+}
+/** What the journal knows of a tool call when it ends (R5.1, R7.1), for its `tool.completed`. */
+export interface ToolCallFacts {
+    readonly status: ToolCallStatus;
+    readonly kind?: ToolCallKind;
+    readonly server?: string;
+    readonly attempts?: number;
+    readonly durationMs?: number;
+    readonly effectId?: string;
+    readonly gate?: GateTimes;
+    readonly policy?: ToolPolicyFact;
+}
+/**
+ * `tool.completed` for a tool call that ended: its output, or the tool error it reported, and
+ * how it ended (R5.1).
+ */
+export declare function toolCompleted(request: HostEffect, value: unknown, facts?: ToolCallFacts): {
     agent: import("@nylorun/core/define").AgentRef;
     error: {
         code: string;
         message: string;
         server?: string | undefined;
-        vault?: string | undefined;
         retryable?: boolean | undefined;
     };
     output?: undefined;
     redacted: number;
     capabilityId: string;
     toolName: string;
+    status?: "cancelled" | "completed" | "failed" | undefined;
+    kind?: "http" | "mcp" | "platform" | "sandbox" | undefined;
+    server?: string | undefined;
+    attempts?: number | undefined;
+    durationMs?: number | undefined;
+    effectId?: string | undefined;
+    gate?: GateTimes | undefined;
+    policy?: ToolPolicyFact | undefined;
 } | {
     agent?: undefined;
     error: {
         code: string;
         message: string;
         server?: string | undefined;
-        vault?: string | undefined;
         retryable?: boolean | undefined;
     };
     output?: undefined;
     redacted: number;
     capabilityId: string;
     toolName: string;
+    status?: "cancelled" | "completed" | "failed" | undefined;
+    kind?: "http" | "mcp" | "platform" | "sandbox" | undefined;
+    server?: string | undefined;
+    attempts?: number | undefined;
+    durationMs?: number | undefined;
+    effectId?: string | undefined;
+    gate?: GateTimes | undefined;
+    policy?: ToolPolicyFact | undefined;
 } | {
-    redacted?: undefined;
     agent: import("@nylorun/core/define").AgentRef;
     error: {
         code: string;
         message: string;
         server?: string | undefined;
-        vault?: string | undefined;
         retryable?: boolean | undefined;
     };
     output?: undefined;
+    redacted?: undefined;
     capabilityId: string;
     toolName: string;
+    status?: "cancelled" | "completed" | "failed" | undefined;
+    kind?: "http" | "mcp" | "platform" | "sandbox" | undefined;
+    server?: string | undefined;
+    attempts?: number | undefined;
+    durationMs?: number | undefined;
+    effectId?: string | undefined;
+    gate?: GateTimes | undefined;
+    policy?: ToolPolicyFact | undefined;
 } | {
-    redacted?: undefined;
     agent?: undefined;
     error: {
         code: string;
         message: string;
         server?: string | undefined;
-        vault?: string | undefined;
         retryable?: boolean | undefined;
     };
     output?: undefined;
+    redacted?: undefined;
     capabilityId: string;
     toolName: string;
+    status?: "cancelled" | "completed" | "failed" | undefined;
+    kind?: "http" | "mcp" | "platform" | "sandbox" | undefined;
+    server?: string | undefined;
+    attempts?: number | undefined;
+    durationMs?: number | undefined;
+    effectId?: string | undefined;
+    gate?: GateTimes | undefined;
+    policy?: ToolPolicyFact | undefined;
 } | {
     agent: import("@nylorun/core/define").AgentRef;
     error?: undefined;
@@ -135,6 +233,14 @@ export declare function toolCompleted(request: HostEffect, value: unknown): {
     redacted: number;
     capabilityId: string;
     toolName: string;
+    status?: "cancelled" | "completed" | "failed" | undefined;
+    kind?: "http" | "mcp" | "platform" | "sandbox" | undefined;
+    server?: string | undefined;
+    attempts?: number | undefined;
+    durationMs?: number | undefined;
+    effectId?: string | undefined;
+    gate?: GateTimes | undefined;
+    policy?: ToolPolicyFact | undefined;
 } | {
     agent?: undefined;
     error?: undefined;
@@ -142,20 +248,44 @@ export declare function toolCompleted(request: HostEffect, value: unknown): {
     redacted: number;
     capabilityId: string;
     toolName: string;
+    status?: "cancelled" | "completed" | "failed" | undefined;
+    kind?: "http" | "mcp" | "platform" | "sandbox" | undefined;
+    server?: string | undefined;
+    attempts?: number | undefined;
+    durationMs?: number | undefined;
+    effectId?: string | undefined;
+    gate?: GateTimes | undefined;
+    policy?: ToolPolicyFact | undefined;
 } | {
-    redacted?: undefined;
     agent: import("@nylorun/core/define").AgentRef;
     error?: undefined;
     output: unknown;
+    redacted?: undefined;
     capabilityId: string;
     toolName: string;
+    status?: "cancelled" | "completed" | "failed" | undefined;
+    kind?: "http" | "mcp" | "platform" | "sandbox" | undefined;
+    server?: string | undefined;
+    attempts?: number | undefined;
+    durationMs?: number | undefined;
+    effectId?: string | undefined;
+    gate?: GateTimes | undefined;
+    policy?: ToolPolicyFact | undefined;
 } | {
-    redacted?: undefined;
     agent?: undefined;
     error?: undefined;
     output: unknown;
+    redacted?: undefined;
     capabilityId: string;
     toolName: string;
+    status?: "cancelled" | "completed" | "failed" | undefined;
+    kind?: "http" | "mcp" | "platform" | "sandbox" | undefined;
+    server?: string | undefined;
+    attempts?: number | undefined;
+    durationMs?: number | undefined;
+    effectId?: string | undefined;
+    gate?: GateTimes | undefined;
+    policy?: ToolPolicyFact | undefined;
 } | {
     callId: string;
     invocationId: string;
@@ -164,13 +294,20 @@ export declare function toolCompleted(request: HostEffect, value: unknown): {
         code: string;
         message: string;
         server?: string | undefined;
-        vault?: string | undefined;
         retryable?: boolean | undefined;
     };
     output?: undefined;
     redacted: number;
     capabilityId: string;
     toolName: string;
+    status?: "cancelled" | "completed" | "failed" | undefined;
+    kind?: "http" | "mcp" | "platform" | "sandbox" | undefined;
+    server?: string | undefined;
+    attempts?: number | undefined;
+    durationMs?: number | undefined;
+    effectId?: string | undefined;
+    gate?: GateTimes | undefined;
+    policy?: ToolPolicyFact | undefined;
 } | {
     callId: string;
     invocationId: string;
@@ -179,15 +316,21 @@ export declare function toolCompleted(request: HostEffect, value: unknown): {
         code: string;
         message: string;
         server?: string | undefined;
-        vault?: string | undefined;
         retryable?: boolean | undefined;
     };
     output?: undefined;
     redacted: number;
     capabilityId: string;
     toolName: string;
+    status?: "cancelled" | "completed" | "failed" | undefined;
+    kind?: "http" | "mcp" | "platform" | "sandbox" | undefined;
+    server?: string | undefined;
+    attempts?: number | undefined;
+    durationMs?: number | undefined;
+    effectId?: string | undefined;
+    gate?: GateTimes | undefined;
+    policy?: ToolPolicyFact | undefined;
 } | {
-    redacted?: undefined;
     callId: string;
     invocationId: string;
     agent: import("@nylorun/core/define").AgentRef;
@@ -195,14 +338,21 @@ export declare function toolCompleted(request: HostEffect, value: unknown): {
         code: string;
         message: string;
         server?: string | undefined;
-        vault?: string | undefined;
         retryable?: boolean | undefined;
     };
     output?: undefined;
+    redacted?: undefined;
     capabilityId: string;
     toolName: string;
+    status?: "cancelled" | "completed" | "failed" | undefined;
+    kind?: "http" | "mcp" | "platform" | "sandbox" | undefined;
+    server?: string | undefined;
+    attempts?: number | undefined;
+    durationMs?: number | undefined;
+    effectId?: string | undefined;
+    gate?: GateTimes | undefined;
+    policy?: ToolPolicyFact | undefined;
 } | {
-    redacted?: undefined;
     callId: string;
     invocationId: string;
     agent?: undefined;
@@ -210,12 +360,20 @@ export declare function toolCompleted(request: HostEffect, value: unknown): {
         code: string;
         message: string;
         server?: string | undefined;
-        vault?: string | undefined;
         retryable?: boolean | undefined;
     };
     output?: undefined;
+    redacted?: undefined;
     capabilityId: string;
     toolName: string;
+    status?: "cancelled" | "completed" | "failed" | undefined;
+    kind?: "http" | "mcp" | "platform" | "sandbox" | undefined;
+    server?: string | undefined;
+    attempts?: number | undefined;
+    durationMs?: number | undefined;
+    effectId?: string | undefined;
+    gate?: GateTimes | undefined;
+    policy?: ToolPolicyFact | undefined;
 } | {
     callId: string;
     invocationId: string;
@@ -225,6 +383,14 @@ export declare function toolCompleted(request: HostEffect, value: unknown): {
     redacted: number;
     capabilityId: string;
     toolName: string;
+    status?: "cancelled" | "completed" | "failed" | undefined;
+    kind?: "http" | "mcp" | "platform" | "sandbox" | undefined;
+    server?: string | undefined;
+    attempts?: number | undefined;
+    durationMs?: number | undefined;
+    effectId?: string | undefined;
+    gate?: GateTimes | undefined;
+    policy?: ToolPolicyFact | undefined;
 } | {
     callId: string;
     invocationId: string;
@@ -234,22 +400,46 @@ export declare function toolCompleted(request: HostEffect, value: unknown): {
     redacted: number;
     capabilityId: string;
     toolName: string;
+    status?: "cancelled" | "completed" | "failed" | undefined;
+    kind?: "http" | "mcp" | "platform" | "sandbox" | undefined;
+    server?: string | undefined;
+    attempts?: number | undefined;
+    durationMs?: number | undefined;
+    effectId?: string | undefined;
+    gate?: GateTimes | undefined;
+    policy?: ToolPolicyFact | undefined;
 } | {
-    redacted?: undefined;
     callId: string;
     invocationId: string;
     agent: import("@nylorun/core/define").AgentRef;
     error?: undefined;
     output: unknown;
+    redacted?: undefined;
     capabilityId: string;
     toolName: string;
+    status?: "cancelled" | "completed" | "failed" | undefined;
+    kind?: "http" | "mcp" | "platform" | "sandbox" | undefined;
+    server?: string | undefined;
+    attempts?: number | undefined;
+    durationMs?: number | undefined;
+    effectId?: string | undefined;
+    gate?: GateTimes | undefined;
+    policy?: ToolPolicyFact | undefined;
 } | {
-    redacted?: undefined;
     callId: string;
     invocationId: string;
     agent?: undefined;
     error?: undefined;
     output: unknown;
+    redacted?: undefined;
     capabilityId: string;
     toolName: string;
+    status?: "cancelled" | "completed" | "failed" | undefined;
+    kind?: "http" | "mcp" | "platform" | "sandbox" | undefined;
+    server?: string | undefined;
+    attempts?: number | undefined;
+    durationMs?: number | undefined;
+    effectId?: string | undefined;
+    gate?: GateTimes | undefined;
+    policy?: ToolPolicyFact | undefined;
 } | undefined;

package/dist/tenant/transcript.js

@@ -9,7 +9,9 @@ export function toolIds(context) {
 const agentOf = (request) => request.agent ? { agent: request.agent } : {};
 /**
  * `message.assistant` for a completed model effect: the step's text and tool calls. The
- * provider returns a `ModelCandidate` or a bare string; anything else writes no event.
+ * provider returns a `ModelCandidate` or a bare string. A step that said nothing (no text, no
+ * tool calls; a structured answer) is still one event, with `text: ""` (R7.1): every model call
+ * has its outcome row. Readers that build a conversation skip it (`isEmptyAssistantMessage`).
  */
 export function assistantMessage(request, value) {
     const invocationId = request.context
@@ -31,8 +33,6 @@ export function assistantMessage(request, value) {
             typeof block.name === "string")
             toolCalls.push({ callId: block.id, name: block.name, input: block.args });
     }
-    if (!text && toolCalls.length === 0)
-        return undefined;
     const candidate = (typeof value === "object" && value !== null ? value : {});
     const producer = candidate.evidence?.extras?.producer;
     return {
@@ -53,11 +53,12 @@ export function assistantMessage(request, value) {
 }
 /**
  * `context.compacted` for a model effect that summarized history (Model Calls §8): the
- * engine replaced the older transcript with that summary.
+ * engine replaced the older transcript with that summary. A partial summary (one call of
+ * several) is marked `partial: true` (R7.1): only the last call's event replaced the history.
  */
 export function contextCompacted(request, value) {
     const compaction = request.context?.compaction;
-    if (!compaction || compaction.partial || isModelFailureOutcome(value))
+    if (!compaction || isModelFailureOutcome(value))
         return undefined;
     const summary = typeof value === "string"
         ? value
@@ -74,6 +75,7 @@ export function contextCompacted(request, value) {
         trigger: compaction.trigger === "overflow" ? "overflow" : "threshold",
         tokensBefore,
         tokensAfter: keptTokens + Math.ceil(summary.trim().length / 4),
+        ...(compaction.partial ? { partial: true } : {}),
         ...agentOf(request),
     };
 }
@@ -91,8 +93,48 @@ export function modelFailed(request, value) {
         ...agentOf(request),
     };
 }
-/** `tool.completed` for a tool the Runtime ran: its output, or the tool error it reported. */
-export function toolCompleted(request, value) {
+/** From `startedAt` to `endedAt` in whole milliseconds; undefined unless both are times. */
+export function durationBetween(startedAt, endedAt) {
+    const started = startedAt ? Date.parse(startedAt) : NaN;
+    const ended = endedAt ? Date.parse(endedAt) : NaN;
+    if (!Number.isFinite(started) || !Number.isFinite(ended))
+        return undefined;
+    return Math.max(0, Math.round(ended - started));
+}
+/**
+ * The timing a model call's outcome event carries (R7.1): its effect id, the journal's window
+ * (`startedAt` on the row to `settledAt`), and, when the gate metered the call (`metered`), the
+ * gate's own start and end, the first token's time and the metered usage.
+ */
+export function modelOutcomeFacts(effectId, window, metered) {
+    const durationMs = durationBetween(window.startedAt, window.settledAt);
+    return {
+        effectId,
+        ...(durationMs === undefined ? {} : { durationMs }),
+        ...(metered?.startedAt && metered.endedAt
+            ? { gate: { startedAt: metered.startedAt, endedAt: metered.endedAt } }
+            : {}),
+        ...(metered?.firstTokenMs !== null && metered?.firstTokenMs !== undefined
+            ? { firstTokenMs: metered.firstTokenMs }
+            : {}),
+        ...(metered
+            ? {
+                meteredUsage: {
+                    inputTokens: metered.inputTokens,
+                    outputTokens: metered.outputTokens,
+                    totalTokens: metered.totalTokens,
+                    ...(metered.cachedTokens > 0 ? { cachedTokens: metered.cachedTokens } : {}),
+                    ...(metered.costUsd > 0 ? { costUsd: metered.costUsd } : {}),
+                },
+            }
+            : {}),
+    };
+}
+/**
+ * `tool.completed` for a tool call that ended: its output, or the tool error it reported, and
+ * how it ended (R5.1).
+ */
+export function toolCompleted(request, value, facts) {
     const ids = toolIds(request.context);
     if (!("callId" in ids))
         return undefined;
@@ -102,11 +144,8 @@ export function toolCompleted(request, value) {
             error: {
                 code: String(outcome.code ?? "tool.failed"),
                 message: String(outcome.message ?? ""),
-                // `credential_rejected` (R2b C1): which server, and which vault's credential.
+                // `credential_rejected` (R2b C1): which server.
                 ...(typeof outcome.server === "string" ? { server: outcome.server } : {}),
-                ...(outcome.vault === "installation" || outcome.vault === "user"
-                    ? { vault: outcome.vault }
-                    : {}),
                 ...(typeof outcome.retryable === "boolean" ? { retryable: outcome.retryable } : {}),
             },
         }
@@ -121,6 +160,18 @@ export function toolCompleted(request, value) {
         ...ids,
         capabilityId: request.capabilityId,
         toolName: request.toolName,
+        ...(facts
+            ? {
+                status: facts.status,
+                ...(facts.kind === undefined ? {} : { kind: facts.kind }),
+                ...(facts.server === undefined ? {} : { server: facts.server }),
+                ...(facts.attempts === undefined ? {} : { attempts: facts.attempts }),
+                ...(facts.durationMs === undefined ? {} : { durationMs: facts.durationMs }),
+                ...(facts.effectId === undefined ? {} : { effectId: facts.effectId }),
+                ...(facts.gate === undefined ? {} : { gate: facts.gate }),
+                ...(facts.policy === undefined ? {} : { policy: facts.policy }),
+            }
+            : {}),
         ...result,
         ...redacted,
         ...agentOf(request),

package/dist/tenant/turn-timing.d.ts

@@ -0,0 +1,43 @@
+/**
+ * A turn's timing and totals (R7.1), so the event that ends it is its span. The session body
+ * keeps when its active turn started (`turnStartedAt`, set beside `activeTurnId`), how long it
+ * has waited paused for a person (`pausedMs`), and since when it waits (`pausedAt`, while
+ * paused). `turn.completed`, `turn.failed` and `turn.cancelled` carry `endTurn`'s facts.
+ *
+ * A turn started before the Runtime recorded these has no `turnStartedAt`: its end carries no
+ * `durationMs`.
+ */
+import type { Tx } from "../store/types.js";
+/** The turn timing a session body keeps. */
+export interface TurnTiming {
+    turnStartedAt?: string;
+    /** The trace context the turn's message arrived with (R7.4); it ends with the turn. */
+    turnTrace?: unknown;
+    pausedMs?: number;
+    pausedAt?: string;
+}
+/** A new turn starts now. Mutates `s`. */
+export declare function startTurn(s: TurnTiming, now?: Date): void;
+/** The turn waits for a person from now, unless it already does. Mutates `s`. */
+export declare function pauseTurn(s: TurnTiming, now?: Date): void;
+/** A paused turn goes on: its wait is added to `pausedMs`. No-op when it was not paused. */
+export declare function resumeTurn(s: TurnTiming, now?: Date): void;
+/**
+ * The facts the event that ends turn `turnId` carries: `durationMs` from its start to now, waits
+ * included, so the turn's span holds every crossing in it; `pausedMs`, how long it waited paused
+ * (a wait still open ends now, as for a cancel); the session's agent;
+ * and the turn's totals from the usage ledger (one read, as `/v1/tenant/usage` totals a turn;
+ * `steps` are the model calls the gate metered). Clears the turn's timing from `s`.
+ */
+export declare function endTurn(t: Tx, s: TurnTiming & {
+    agentId: string;
+}, turnId: string | null, now?: Date): Promise<{
+    durationMs?: number;
+    pausedMs?: number;
+    agentId: string;
+    totals?: {
+        steps: number;
+        tokens: number;
+        costUsd: number;
+    };
+}>;

package/dist/tenant/turn-timing.js

@@ -0,0 +1,39 @@
+import { durationBetween } from "./transcript.js";
+/** A new turn starts now. Mutates `s`. */
+export function startTurn(s, now = new Date()) {
+    s.turnStartedAt = now.toISOString();
+    s.pausedMs = 0;
+    delete s.pausedAt;
+}
+/** The turn waits for a person from now, unless it already does. Mutates `s`. */
+export function pauseTurn(s, now = new Date()) {
+    s.pausedAt ??= now.toISOString();
+}
+/** A paused turn goes on: its wait is added to `pausedMs`. No-op when it was not paused. */
+export function resumeTurn(s, now = new Date()) {
+    if (s.pausedAt === undefined)
+        return;
+    s.pausedMs = (s.pausedMs ?? 0) + (durationBetween(s.pausedAt, now.toISOString()) ?? 0);
+    delete s.pausedAt;
+}
+/**
+ * The facts the event that ends turn `turnId` carries: `durationMs` from its start to now, waits
+ * included, so the turn's span holds every crossing in it; `pausedMs`, how long it waited paused
+ * (a wait still open ends now, as for a cancel); the session's agent;
+ * and the turn's totals from the usage ledger (one read, as `/v1/tenant/usage` totals a turn;
+ * `steps` are the model calls the gate metered). Clears the turn's timing from `s`.
+ */
+export async function endTurn(t, s, turnId, now = new Date()) {
+    resumeTurn(s, now);
+    const elapsed = durationBetween(s.turnStartedAt, now.toISOString());
+    const totals = turnId ? await t.modelUsageTotals({ scope: "turn", id: turnId }) : undefined;
+    const facts = {
+        ...(elapsed === undefined ? {} : { durationMs: Math.max(0, elapsed), pausedMs: s.pausedMs ?? 0 }),
+        agentId: s.agentId,
+        ...(totals ? { totals: { steps: totals.calls, tokens: totals.tokens, costUsd: totals.costUsd } } : {}),
+    };
+    delete s.turnStartedAt;
+    delete s.pausedMs;
+    delete s.turnTrace;
+    return facts;
+}

package/dist/tenant/types.d.ts

@@ -119,6 +119,8 @@ export interface TenantHandle {
     attachHarness?(channel: HarnessChannel, peer: HarnessPeer): () => void;
     /** The Tenant's side of a sandbox pod's join (F7.2); absent without sandbox pods. */
     hostAuthority?(): HostAuthority | undefined;
+    /** The custom harness a per-harness token is for (R4.1), or undefined. */
+    harnessOfToken?(token: string): Promise<string | undefined>;
     /** The Tenant's harnesses (F6.2), for `/ready`. */
     harnessStatus?(): HarnessStatus;
 }

package/dist/traces/ids.d.ts

@@ -0,0 +1,42 @@
+/** The Tenant's trace key (`traces/key.ts`). */
+export type TraceKey = Buffer;
+export declare function traceIdOf(key: TraceKey, tenantId: string, sessionId: string, turnId: string): string;
+export declare function turnSpanOf(key: TraceKey, turnId: string): string;
+export declare function effectSpanOf(key: TraceKey, effectId: string): string;
+export declare function egressSpanOf(key: TraceKey, sessionId: string, seq: number): string;
+export declare function eventSpanOf(key: TraceKey, sessionId: string, seq: number): string;
+/** W3C trace context (R7.4): `traceparent`, and `tracestate` when the caller sent one. */
+export interface TraceContext {
+    readonly traceparent: string;
+    readonly tracestate?: string;
+}
+/**
+ * A `traceparent` as W3C trace context reads it: its trace id and parent span id, or undefined
+ * when it is malformed (version `ff`, an all-zero id, or another shape), which a receiver
+ * ignores. A version above `00` may carry more fields after the flags.
+ */
+export declare function parseTraceparent(value: string): {
+    traceId: string;
+    spanId: string;
+} | undefined;
+/**
+ * The trace context a request's headers carry (R7.4), or undefined without a valid
+ * `traceparent`. A `tracestate` too long or with control characters is dropped, never the
+ * `traceparent`. Kept normalized: `00-<trace>-<span>-<flags>`.
+ */
+export declare function traceContextOf(headers: {
+    get(name: string): string | null | undefined;
+}): TraceContext | undefined;
+/** `00-<trace>-<span>-01`: the context a turn or a crossing hands on (sampled). */
+export declare function traceparentOf(traceId: string, spanId: string): string;
+/**
+ * The trace id of turn `turnId`: the one its message arrived with (`inbound`, R7.4), else
+ * derived. The same as `turnTraceOf` reads from the turn's `command.message`.
+ */
+export declare function turnTraceIdOf(key: TraceKey, ids: {
+    tenantId: string;
+    sessionId: string;
+    turnId: string;
+}, inbound?: {
+    readonly traceparent: string;
+}): string;