@nylorun/runtime 0.22.0-beta → 0.24.0-beta

package/dist/harness-api/record.js

@@ -11,8 +11,14 @@
  *
  * Rows store the request's hash (`requestHash`) and, for a model call, the request without its
  * prompt: drift is a hash compare. Rows written before carry their full request, hashed on read.
+ *
+ * Every row a run journals keeps when it was journaled (`startedAt`, R7.1), and a rejoin keeps
+ * it: an outcome's `durationMs` is the journal's window, from the intent to the outcome. A model
+ * call's outcome event also carries what the meter recorded for it (`modelOutcomeFacts`). A tool
+ * row keeps its span's context (`traceparent`, R7.4), which the `execute` answer carries to the
+ * harness and the Tool Gate reads with the row.
  */
-import { HarnessApiError, effectRequestHash, } from "@nylorun/core/harness-api";
+import { HARNESS_TOOLS_CAPABILITY, HarnessApiError, effectRequestHash, isEffectIdOf, } from "@nylorun/core/harness-api";
 import { isFlowEffect, isFlowToolEffect, recordVerdict, settleAgentEffect, } from "../core/flow-host.js";
 import { sandboxCapabilityOf } from "../sandbox/capability.js";
 import { abortOn, isReadArtifactCall, isSaveArtifactCall } from "../harness/calls.js";
@@ -26,8 +32,13 @@ import { manifestFor, mcpToolOf } from "../mcp/snapshot.js";
 import { isHttpToolCall } from "../gates/http-tool.js";
 import { ownedSession } from "../tenant/context.js";
 import { isGateToolEffect, linkedOutcome, recoversModelCalls, recoversToolCalls, resolveNewFlowEffect, } from "../tenant/effects.js";
-import { assistantMessage, contextCompacted, modelFailed, toolCompleted, } from "../tenant/transcript.js";
+import { assistantMessage, contextCompacted, modelFailed, modelOutcomeFacts, } from "../tenant/transcript.js";
 import { abortKind } from "../tenant/worker.js";
+import { redactTokens } from "./redact.js";
+import { toolCallDecision } from "../gates/policy.js";
+import { traceKey } from "../traces/key.js";
+import { effectSpanOf, traceparentOf, turnTraceIdOf } from "../traces/ids.js";
+import { MAX_TOOL_ATTEMPTS, firstSend, interrupted, settleToolRow, toolKindOf, } from "./tool-journal.js";
 const TURN_CANCELLED = () => new HarnessApiError("turn_cancelled", "Turn cancelled");
 /** The hash a journal row's request was recorded with. */
 export function hashOf(row) {
@@ -35,10 +46,9 @@ export function hashOf(row) {
 }
 /** The completed outcomes of a segment, which a run replays without asking. */
 export async function bulkOutcomes(t, session, checkpoint) {
-    const prefix = `${checkpoint.turnId}:${checkpoint.segment}:`;
     const rows = await t.effectsForTurn(session.id, checkpoint.turnId, ["completed"]);
     return rows
-        .filter((row) => row.request.effectId.startsWith(prefix) && row.outcome)
+        .filter((row) => isEffectIdOf(row.request.effectId, checkpoint.turnId, checkpoint.segment) && row.outcome)
         .map((row) => ({ effectId: row.request.effectId, requestHash: hashOf(row), outcome: row.outcome }));
 }
 /**
@@ -48,10 +58,14 @@ export async function bulkOutcomes(t, session, checkpoint) {
 export async function recordIntent(scope, effect, requestHash) {
     const { ctx, lease, signal } = scope;
     const request = effect;
+    // Read before the transaction: the first read of the Tenant may create the key.
+    const key = await traceKey(ctx.store);
     const answer = await ctx.store.tx(async (t) => {
         const s = await ownedSession(t, lease, request.sessionId);
         if (s.status === "cancelled" || s.activeTurnId !== request.turnId)
             throw TURN_CANCELLED();
+        // A tool call's span context (R7.4), kept on its row.
+        const traced = () => ({ traceparent: toolTraceparent(key, ctx.store.tenantId, s, request) });
         // An aborted advance starts no effect; the advance decides what the abort means.
         signal.throwIfAborted();
         const existing = await t.get("effects", request.effectId);
@@ -61,12 +75,12 @@ export async function recordIntent(scope, effect, requestHash) {
             if (existing.status === "completed")
                 return { status: "completed", outcome: existing.outcome };
             // A call its previous owner left running at the gate: re-send it, same key and request,
-            // to join it or collect its outcome (P1.2 for model calls, F4.1 for remote MCP and HTTP
-            // tool calls).
+            // to join it or collect its outcome (P1.2).
             if (existing.status === "invoking" && request.kind === "model" && recoversModelCalls(ctx))
                 return { status: "execute", rejoin: true };
-            if (existing.status === "invoking" && recoversToolCalls(ctx) && isGateToolEffect(s, existing.request))
-                return { status: "execute", rejoin: true };
+            // A tool call a crash, a shutdown or a lost gate hop interrupted (R5.3, R5.4).
+            if (existing.status === "invoking" && existing.request.kind === "tool")
+                return resend(t, s, existing, recoversToolCalls(ctx));
             if (request.kind === "agent" && existing.status === "pending" && existing.agentSessionId) {
                 const agent = await t.get("sessions", existing.agentSessionId);
                 const outcome = await linkedOutcome(t, existing, agent);
@@ -86,26 +100,38 @@ export async function recordIntent(scope, effect, requestHash) {
         if (request.kind !== "model" && effectRequestHash(request) !== requestHash)
             throw new HarnessApiError("invalid", "The request hash does not match the request");
         if (flowHttp) {
-            await t.put("effects", request.effectId, { request, requestHash, status: "invoking" });
+            const row = { request, requestHash, status: "invoking", ...firstSend({ toolKind: "http" }), ...traced() };
             await t.event(s.id, s.activeTurnId, "node.started", {
                 path: request.path,
                 kind: "http",
                 key: request.key,
                 ...(request.iterations !== undefined ? { iterations: request.iterations } : {}),
-            });
-            return { status: "execute" };
+            }, scope.writer);
+            const decided = await bypolicy(t, s, row, "http");
+            if (decided)
+                return decided;
+            await t.put("effects", request.effectId, row);
+            return { status: "execute", traceparent: row.traceparent };
         }
         if (request.kind === "delegation") {
             // Lifecycle points of an agent used as a tool: journaled once, so replays never re-emit.
             const outcome = { value: null };
-            await t.put("effects", request.effectId, { request, requestHash, status: "completed", outcome });
+            const at = new Date().toISOString();
+            await t.put("effects", request.effectId, {
+                request,
+                requestHash,
+                status: "completed",
+                outcome,
+                startedAt: at,
+                settledAt: at,
+            });
             const settled = request.effectId.endsWith(":settled");
             const callId = request.context?.callId;
             await t.event(s.id, s.activeTurnId, settled ? "delegation.completed" : "delegation.started", {
                 agent: request.agent,
                 ...(typeof callId === "string" ? { callId } : {}),
                 ...request.input,
-            });
+            }, scope.writer);
             return { status: "completed", outcome };
         }
         const agentManifest = manifestFor(s.manifest, request.agent);
@@ -124,24 +150,41 @@ export async function recordIntent(scope, effect, requestHash) {
                     isReadArtifactCall(agentManifest, request) ||
                     isSkillToolCall(agentManifest, request) ||
                     // `tool_search` (R2b C10) reads the session's pinned MCP snapshot: core serves it.
-                    isToolSearchCall(agentManifest, request)));
+                    isToolSearchCall(agentManifest, request) ||
+                    // A tool the run's harness declared and runs itself (R4.2, Q3).
+                    (request.capabilityId === HARNESS_TOOLS_CAPABILITY &&
+                        scope.nativeTools?.has(request.toolName ?? "") === true)));
         if (!executed) {
             // A tool that would run the developer's code: refused at save (a turn's manifest only
             // removes tools), so this is a backstop, as is an MCP tool the turn disabled, which the
             // model was never offered. The model sees the failure; nothing runs.
             const disabled = request.kind === "tool" && mcpToolOf(s.mcpSnapshot, request) !== undefined;
-            const outcome = { value: disabled ? disabledTool(request) : unrunnableTool(request) };
-            await t.put("effects", request.effectId, { request, requestHash, status: "completed", outcome });
-            const transcript = toolCompleted(request, outcome.value);
-            if (transcript)
-                await t.event(s.id, request.turnId, "tool.completed", transcript);
+            const row = {
+                request,
+                requestHash,
+                status: "invoking",
+                ...toolKindOf(s, agentManifest, request),
+                attempts: 0,
+            };
+            const outcome = await settleToolRow(t, s, row, disabled ? disabledTool(request) : unrunnableTool(request), { writer: coreIn(scope) });
             return { status: "completed", outcome };
         }
-        await t.put("effects", request.effectId, {
+        const row = {
+            // A model row keeps no prompt; a tool row its whole request.
             request: storedRequest(request),
             requestHash,
             status: "invoking",
-        });
+            ...(request.kind === "tool"
+                ? { ...firstSend(toolKindOf(s, agentManifest, request)), ...traced() }
+                : { startedAt: new Date().toISOString() }),
+        };
+        // The Tenant's tool policy decides an MCP or HTTP tool call as it is journaled (R5 step 2).
+        if (row.toolKind === "mcp" || row.toolKind === "http") {
+            const decided = await bypolicy(t, s, row, row.toolKind);
+            if (decided)
+                return decided;
+        }
+        await t.put("effects", request.effectId, row);
         // `save_artifact` writes the Tenant's artifacts: core runs it, reading the file through the
         // workspace capability, wherever the sandbox is.
         if (request.kind === "tool" && isSaveArtifactCall(agentManifest, request))
@@ -154,7 +197,7 @@ export async function recordIntent(scope, effect, requestHash) {
             return { skill: agentManifest };
         if (isToolSearchCall(agentManifest, request))
             return "search";
-        return { status: "execute" };
+        return { status: "execute", ...(row.traceparent ? { traceparent: row.traceparent } : {}) };
     });
     if (answer === "save")
         return runInCore(scope, request, () => callSaveArtifact(scope.ctx, request, scope.signal));
@@ -177,6 +220,9 @@ export async function recordIntent(scope, effect, requestHash) {
  * the outcome as the intent's answer.
  */
 async function runInCore(scope, request, call) {
+    // Core ran the call: its outcome is what core saw, not the harness's claim (R4.9).
+    const writer = coreIn(scope);
+    const core = { ctx: scope.ctx, lease: scope.lease, signal: scope.signal, ...(writer ? { writer } : {}) };
     let value;
     try {
         value = await call();
@@ -184,11 +230,70 @@ async function runInCore(scope, request, call) {
     catch (error) {
         if (isOwnershipLost(error))
             throw error;
-        return recordOutcome(scope, request.effectId, {
+        return recordOutcome(core, request.effectId, {
             error: error instanceof Error ? error.message : String(error),
         });
     }
-    return recordOutcome(scope, request.effectId, { value });
+    return recordOutcome(core, request.effectId, { value });
+}
+/** Core's own write during the scope's run (R4.9): core saw it, in that run. */
+function coreIn(scope) {
+    const runId = scope.writer?.runId;
+    return runId === undefined ? undefined : { source: { kind: "core", id: "runtime" }, runId };
+}
+/**
+ * The answer to a tool row still `invoking` (R5.3, R5.4): a crash, a shutdown or a lost gate
+ * hop interrupted its send. An MCP or HTTP call (it crosses the Tool Gate, which hands the tool
+ * its key) is sent again, one more attempt, until `MAX_TOOL_ATTEMPTS`; then it fails to the
+ * model. Any other call (sandbox, core-served) has no key to dedupe on: it fails to the model
+ * now, and is not run again (Q2).
+ */
+async function resend(t, s, row, rejoin) {
+    if (!isGateToolEffect(s, row.request)) {
+        const outcome = await settleToolRow(t, s, row, interrupted("A crash interrupted this call before its outcome was recorded. It may have run; it is not run again."));
+        return { status: "completed", outcome };
+    }
+    const attempts = (row.attempts ?? 1) + 1;
+    if (attempts > MAX_TOOL_ATTEMPTS) {
+        const outcome = await settleToolRow(t, s, row, interrupted(`The call was interrupted ${MAX_TOOL_ATTEMPTS} times and may have run.`));
+        return { status: "completed", outcome };
+    }
+    row.attempts = attempts;
+    await t.put("effects", row.request.effectId, row);
+    const traced = row.traceparent ? { traceparent: row.traceparent } : {};
+    return rejoin ? { status: "execute", rejoin: true, ...traced } : { status: "execute", ...traced };
+}
+/** The span context of tool call `request` (R7.4): its turn's trace, and its own span. */
+function toolTraceparent(key, tenantId, s, request) {
+    const traceId = turnTraceIdOf(key, { tenantId, sessionId: s.id, turnId: request.turnId }, s.turnTrace);
+    return traceparentOf(traceId, effectSpanOf(key, request.effectId));
+}
+/**
+ * The Tenant's tool policy on a tool call being journaled (R5 step 2, `gates/policy.ts`), or
+ * undefined when it runs. `deny`: the call fails to the model as `tool.denied`, unsent. `ask`:
+ * the row waits as `held` and the effect is pending; the segment ends waiting, the turn pauses,
+ * and `approve` answers it (`tenant/commands.ts`). The Tool Gate refuses a row not `invoking`, so
+ * neither runs whichever harness sends it. Writes `row`.
+ */
+async function bypolicy(t, s, row, kind) {
+    const decision = await toolCallDecision(t, s, row.request, kind);
+    if (decision.effect === "allow")
+        return undefined;
+    // Nothing was sent.
+    row.attempts = 0;
+    if (decision.effect === "deny") {
+        const outcome = await settleToolRow(t, s, row, {
+            kind: "failed",
+            code: "tool.denied",
+            message: decision.reason,
+            retryable: false,
+        });
+        return { status: "completed", outcome };
+    }
+    row.status = "held";
+    row.hold = { reason: decision.reason, at: new Date().toISOString() };
+    await t.put("effects", row.request.effectId, row);
+    return { status: "pending" };
 }
 /** The failed outcome of an MCP tool the turn's manifest disables (R2b C9). */
 function disabledTool(request) {
@@ -203,7 +308,7 @@ function unrunnableTool(request) {
     return {
         kind: "failed",
         code: "tool.unavailable",
-        message: `Tool '${request.toolName ?? ""}' runs your code, and the Runtime runs no code of yours during a session. Make it an http() tool or serve it from a remote MCP server.`,
+        message: `Tool '${request.toolName ?? ""}' runs your code, but the Runtime runs agents from their manifests alone. Make it an http() tool or serve it from a remote MCP server.`,
     };
 }
 /**
@@ -211,24 +316,38 @@ function unrunnableTool(request) {
  * `error` that left it uncertain. Only a cancel discards an outcome in hand (§10.7): after any
  * other abort (shutdown, deadline) it is recorded, so the next advance replays it.
  */
-export async function recordOutcome(scope, effectId, result) {
+export async function recordOutcome(scope, effectId, reported) {
     const { ctx, lease, signal } = scope;
+    const result = "error" in reported ? { error: redactTokens(reported.error) } : reported;
     if ("error" in result) {
-        await ctx.store.tx(async (t) => {
+        return ctx.store.tx(async (t) => {
             const s = await t.assertEpoch(lease.sessionId, lease.epoch);
             const effect = await t.get("effects", effectId);
             if (!effect)
-                return;
+                return { status: "uncertain" };
             const { request } = effect;
+            const active = s && s.status !== "cancelled" && s.activeTurnId === request.turnId;
+            // A tool call whose fate the harness could not learn fails to the model (R5.3): it may
+            // have run, and nothing sends it again. A cancel already settled it.
+            if (request.kind === "tool") {
+                if (effect.status === "completed")
+                    return { status: "completed", outcome: effect.outcome };
+                if (effect.status !== "invoking" || !active)
+                    return { status: "uncertain" };
+                effect.error = result.error;
+                const outcome = await settleToolRow(t, s, effect, interrupted(`${result.error} (the call may have run; it is not sent again)`), { writer: coreIn(scope) });
+                return { status: "completed", outcome };
+            }
             effect.status = "uncertain";
             effect.error = result.error;
             await t.put("effects", effectId, effect);
-            if (s && s.status !== "cancelled" && s.activeTurnId === request.turnId)
-                await t.event(s.id, request.turnId, "effect.uncertain", { effectId, message: result.error });
+            if (active)
+                await t.event(s.id, request.turnId, "effect.uncertain", { effectId, message: result.error }, scope.writer);
+            return { status: "uncertain" };
         });
-        return { status: "uncertain" };
     }
-    const value = await shaped(scope, effectId, result.value);
+    // What a harness reports never carries the Runtime's own tokens into the record (R4).
+    const value = await shaped(scope, effectId, redactTokens(result.value));
     return ctx.store.tx(async (t) => {
         const s = await t.assertEpoch(lease.sessionId, lease.epoch);
         const effect = await t.get("effects", effectId);
@@ -237,29 +356,40 @@ export async function recordOutcome(scope, effectId, result) {
         const { request } = effect;
         if (s.status === "cancelled" || s.activeTurnId !== request.turnId || abortKind(signal) === "cancel")
             throw TURN_CANCELLED();
+        if (request.kind === "tool") {
+            // Settled already: a re-send after a lost hop collected what the first send recorded.
+            if (effect.status === "completed")
+                return { status: "completed", outcome: effect.outcome };
+            // What the call returned is the harness's claim, or, for a tool core ran, core's (R4.9).
+            const outcome = await settleToolRow(t, s, effect, value, { writer: scope.writer });
+            if (request.context?.role === "verify-http")
+                await recordVerdict(t, request, value);
+            return { status: "completed", outcome };
+        }
         effect.status = "completed";
         effect.outcome = { value };
+        effect.settledAt = new Date().toISOString();
         await t.put("effects", effectId, effect);
         const model = request.kind === "model";
         const failed = model ? modelFailed(request, value) : undefined;
-        // A summary call is never an assistant message; the last one publishes context.compacted.
+        // A summary call is never an assistant message; it publishes context.compacted, `partial`
+        // unless it is the last.
         const summarizing = model && Boolean(request.context.compaction);
         const compacted = summarizing && !failed ? contextCompacted(request, value) : undefined;
-        const transcript = failed || summarizing
-            ? undefined
-            : model
-                ? assistantMessage(request, value)
-                : toolCompleted(request, value);
+        const transcript = failed || summarizing || !model ? undefined : assistantMessage(request, value);
         if (request.context?.role === "verify-http")
             await recordVerdict(t, request, value);
+        const writer = scope.writer;
+        // The call's span (R7.1): the journal's window, and the meter's row for it when a gate ran it.
+        const facts = failed || compacted || transcript
+            ? modelOutcomeFacts(effectId, effect, await t.modelUsageOf(effectId))
+            : undefined;
         if (failed)
-            await t.event(s.id, request.turnId, "model.failed", failed);
+            await t.event(s.id, request.turnId, "model.failed", { ...failed, ...facts }, writer);
         if (compacted)
-            await t.event(s.id, request.turnId, "context.compacted", compacted);
-        if (transcript && model)
-            await t.event(s.id, request.turnId, "message.assistant", transcript);
-        else if (transcript)
-            await t.event(s.id, request.turnId, "tool.completed", transcript);
+            await t.event(s.id, request.turnId, "context.compacted", { ...compacted, ...facts }, writer);
+        if (transcript)
+            await t.event(s.id, request.turnId, "message.assistant", { ...transcript, ...facts }, writer);
         return { status: "completed", outcome: effect.outcome };
     });
 }

package/dist/harness-api/redact.d.ts

@@ -0,0 +1,3 @@
+export declare const REDACTED_TOKEN = "[nylorun token redacted]";
+/** `value` with every Nylorun-signed token in its strings replaced; the same value when there is none. */
+export declare function redactTokens<T>(value: T): T;

package/dist/harness-api/redact.js

@@ -0,0 +1,45 @@
+/**
+ * Keeps the Runtime's own tokens out of the record (track R4). A harness runs
+ * model-written commands with the egress token in their proxy variables, and holds its run and
+ * host tokens; a command that prints its environment, or a model that repeats it, would put
+ * them into a tool result, an assistant message or a transcript edit. Core replaces every
+ * Nylorun-signed token (a compact JWT whose `typ` is `nylorun-…`) in what a harness reports with
+ * `[nylorun token redacted]` before recording it, whichever harness reported it. Other values
+ * pass through unchanged, and the walk keeps the value's shape.
+ */
+import { tokenType } from "../tenant/jwt.js";
+export const REDACTED_TOKEN = "[nylorun token redacted]";
+/** A compact JWT: three base64url parts, the first two JSON objects. */
+const COMPACT_JWT = /eyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{16,}/g;
+function redactString(text) {
+    if (!text.includes("eyJ"))
+        return text;
+    return text.replace(COMPACT_JWT, (token) => (tokenType(token)?.startsWith("nylorun-") ? REDACTED_TOKEN : token));
+}
+/** `value` with every Nylorun-signed token in its strings replaced; the same value when there is none. */
+export function redactTokens(value) {
+    if (typeof value === "string")
+        return redactString(value);
+    if (Array.isArray(value)) {
+        let changed = false;
+        const next = value.map((item) => {
+            const redacted = redactTokens(item);
+            if (redacted !== item)
+                changed = true;
+            return redacted;
+        });
+        return (changed ? next : value);
+    }
+    if (value !== null && typeof value === "object") {
+        let changed = false;
+        const next = {};
+        for (const [key, item] of Object.entries(value)) {
+            const redacted = redactTokens(item);
+            if (redacted !== item)
+                changed = true;
+            next[key] = redacted;
+        }
+        return (changed ? next : value);
+    }
+    return value;
+}

package/dist/harness-api/server.d.ts

@@ -5,6 +5,12 @@ import type { RunOf } from "../tenant/run-grants.js";
 export interface HarnessPeer {
     /** For logs. */
     readonly name: string;
+    /**
+     * The harness id its credential is for (R4.1): `nylorun` for the harness token, a custom
+     * harness's id for its own token. Its `hello` must name it. Absent for an in-process
+     * harness, which may name any id; a pod's host is checked against its Environment's harness.
+     */
+    readonly harness?: string;
     /** A pod sandbox's engine (F7.2): the sandbox it hosts, at the host epoch of its token. */
     readonly host?: {
         readonly sandboxId: string;
@@ -28,6 +34,8 @@ export interface RunOffer {
      * only a harness that hosts no sandbox does.
      */
     readonly pod?: string;
+    /** The session's harness (R4.1): only a connection that said this id takes it. Default ours. */
+    readonly harness?: string;
     /** How long to wait for a harness to take it. Default the server's `offerWaitMs`. */
     readonly waitMs?: number;
 }

package/dist/harness-api/server.js

@@ -25,10 +25,10 @@
  * `connection.lost`.
  */
 import { randomUUID } from "node:crypto";
-import { HARNESS_API_VERSION, HARNESS_CLAIMS, HarnessApiError, } from "@nylorun/core/harness-api";
+import { DEFAULT_HARNESS, HARNESS_API_VERSION, HARNESS_CLAIMS, MAX_HARNESS_STATE_BYTES, isHarnessId, HarnessApiError, } from "@nylorun/core/harness-api";
 import { definitionFilesOf } from "@nylorun/core/contracts";
 import { isOwnershipLost } from "../store/ownership.js";
-import { ownedSession } from "../tenant/context.js";
+import { harnessOf, ownedSession } from "../tenant/context.js";
 import { mcpDiscovered, pinDeferral, sessionToolsOf, } from "../mcp/snapshot.js";
 import { contextWindowOf } from "../model/catalog.js";
 import { turnManifestOf } from "../tenant/session.js";
@@ -36,6 +36,7 @@ import { sandboxWorkspaceKey, workspacePrefix } from "../sandbox/records.js";
 import { abortKind } from "../tenant/worker.js";
 import { readDefinitionFile } from "../tenant/definition-files.js";
 import { recordIntent, recordOutcome } from "./record.js";
+import { redactTokens } from "./redact.js";
 import { beat, renewEveryMs, tokenOf } from "./renew.js";
 /** No attached harness serves workspaces (or, with `pod`, that pod sandbox's). */
 export class NoWorkspaceHarness extends Error {
@@ -48,6 +49,8 @@ export class NoWorkspaceHarness extends Error {
         this.pod = pod;
     }
 }
+/** What our harness said in `hello` before harness ids (R4.1): refused, with the new id. */
+const LEGACY_NAME = "@nylorun/harness";
 const OUTPUTS = [
     "turn.completed",
     "turn.paused",
@@ -62,8 +65,11 @@ export function createHarnessApiServer(ctx, options = {}) {
     const queued = [];
     const runs = new Map();
     let closed = false;
-    /** A harness may take a run: a pod sandbox's host its sandbox's runs, any other the rest. */
-    const takes = (connection, run) => connection.host?.sandboxId === run.offer.pod;
+    /**
+     * A harness may take a run of its own harness id (R4.1): a pod sandbox's host its sandbox's
+     * runs, any other the rest.
+     */
+    const takes = (connection, run) => connection.harness === (run.offer.harness ?? DEFAULT_HARNESS) && connection.host?.sandboxId === run.offer.pod;
     /** Hands queued runs to waiting harnesses that may take them, in order. */
     const match = () => {
         for (let i = 0; i < queued.length;) {
@@ -89,16 +95,30 @@ export function createHarnessApiServer(ctx, options = {}) {
             throw new HarnessApiError("run_not_held", `Run ${runId} is not held by this harness`);
         return run;
     };
+    /** What a harness reports is its claim (R4.9): its harness id and, in a run, the run. */
+    const writerOf = (connection, runId) => ({
+        source: { kind: "harness", id: connection.harness ?? connection.peer.name },
+        evidence: "claimed",
+        ...(runId === undefined ? {} : { runId }),
+    });
     const scope = (run) => ({
         ctx,
         lease: run.offer.lease,
         signal: run.offer.controller.signal,
+        ...(run.connection?.tools ? { nativeTools: run.connection.tools } : {}),
+        ...(run.connection ? { writer: writerOf(run.connection, run.grant.runId) } : {}),
     });
     const serve = (connection) => async (method, params, signal) => {
         const p = params;
         if (method === "hello") {
-            const { capabilities } = p;
+            const { api, name, capabilities } = p;
+            // R3's next version adds a window of supported versions; until then there is one.
+            if (api !== HARNESS_API_VERSION)
+                throw new HarnessApiError("invalid", `unsupported Harness API version ${api}: this Runtime speaks ${HARNESS_API_VERSION}`);
+            connection.harness = await harnessIdOf(connection, name);
             connection.workspace = capabilities.workspace !== undefined;
+            if (capabilities.tools?.length)
+                connection.tools = new Set(capabilities.tools.map((tool) => tool.name));
             return {
                 api: HARNESS_API_VERSION,
                 tenantId: ctx.config.tenantId,
@@ -109,6 +129,8 @@ export function createHarnessApiServer(ctx, options = {}) {
         }
         if (method === "event")
             return claim(connection, p);
+        if (method === "lease" && connection.harness === undefined)
+            throw new HarnessApiError("invalid", "Say hello first: a harness leases runs of the id it names");
         if (method === "lease")
             return new Promise((resolve, reject) => {
                 const entry = { connection, resolve };
@@ -121,8 +143,12 @@ export function createHarnessApiServer(ctx, options = {}) {
                 });
                 match();
             });
-        if (OUTPUTS.includes(method))
-            return output(held(connection, String(p.runId), method), method, p);
+        if (OUTPUTS.includes(method)) {
+            const run = held(connection, String(p.runId), method);
+            if (connection.harness !== DEFAULT_HARNESS)
+                checkCustomOutput(run, method, p);
+            return output(run, method, p);
+        }
         const run = held(connection, String(p.runId));
         switch (method) {
             case "lease.renew":
@@ -150,6 +176,27 @@ export function createHarnessApiServer(ctx, options = {}) {
                 throw new HarnessApiError("invalid", `Unknown request ${method}`);
         }
     };
+    /**
+     * The harness id a `hello` names (R4.1): a harness id, and the one the connection's credential
+     * is for. A pod's host must be its Environment's harness, so an image that is not the harness
+     * its recipe names never takes the Environment's runs.
+     */
+    const harnessIdOf = async (connection, name) => {
+        if (!isHarnessId(name))
+            throw new HarnessApiError("invalid", name === LEGACY_NAME
+                ? `A harness names its harness id in hello: ours is ${DEFAULT_HARNESS}. Update the harness image (it said ${LEGACY_NAME}).`
+                : `hello.name ${JSON.stringify(name)} is not a harness id: lowercase letters, digits and dashes, starting with a letter`);
+        const bound = connection.peer.harness;
+        if (bound !== undefined && bound !== name)
+            throw new HarnessApiError("invalid", `This credential is for the ${bound} harness, not ${name}`);
+        if (connection.host) {
+            const environment = await ctx.store.tx((t) => t.environment(connection.host.sandboxId));
+            const expected = environment?.applied.harness ?? DEFAULT_HARNESS;
+            if (expected !== name)
+                throw new HarnessApiError("invalid", `Environment ${connection.host.sandboxId} runs the ${expected} harness, and this pod says ${name}`);
+        }
+        return name;
+    };
     /**
      * A `sandbox.*` event the harness claims: for a run it holds (the run's session, or the
      * session owning its sandbox), or a session one of its workspace requests acts for. A
@@ -169,7 +216,7 @@ export function createHarnessApiServer(ctx, options = {}) {
             throw new HarnessApiError("run_not_held", `This harness may not claim events of ${event.sessionId}`);
         const record = event.record;
         if (record &&
-            (event.type !== "sandbox.state" ||
+            (event.type !== "environment.state" ||
                 record.sessionId !== event.sessionId ||
                 !record.key.startsWith(workspacePrefix(ctx.config.tenantId)) ||
                 (connection.host !== undefined &&
@@ -179,7 +226,7 @@ export function createHarnessApiServer(ctx, options = {}) {
             await ctx.store.tx(async (t) => {
                 if (record)
                     await t.put("sandboxes", record.key, record);
-                await t.event(event.sessionId, event.turnId, event.type, event.payload);
+                await t.event(event.sessionId, event.turnId, event.type, redactTokens(event.payload), writerOf(connection, event.runId));
             });
         }
         catch (error) {
@@ -211,7 +258,7 @@ export function createHarnessApiServer(ctx, options = {}) {
                 current.mcpSnapshot = pinDeferral(snapshot, current.manifest, contextWindow);
                 current.mcpDiagnostics = diagnostics;
                 await t.put("sessions", current.id, current);
-                await t.event(current.id, run.grant.turnId, "mcp.discovered", mcpDiscovered(current.mcpSnapshot, diagnostics));
+                await t.event(current.id, run.grant.turnId, "mcp.discovered", mcpDiscovered(current.mcpSnapshot, diagnostics), run.connection ? writerOf(run.connection, run.grant.runId) : undefined);
             }
             else if (diagnostics.length > 0) {
                 const prior = [...(current.mcpDiagnostics ?? [])];
@@ -241,6 +288,27 @@ export function createHarnessApiServer(ctx, options = {}) {
             throw new HarnessApiError("unavailable", `The Object store has no bytes for ${sha256}`);
         return { base64: Buffer.from(bytes).toString("base64") };
     };
+    /**
+     * A custom harness's output (R4.2): its state is its own, stored as sent and never read, so it
+     * must be JSON and at most `MAX_HARNESS_STATE_BYTES`; a larger one fails the turn, as an engine
+     * that threw would. It cannot pause for approvals in v2 (Q14): approvals read our engine's plan
+     * until R5 makes them core holds.
+     */
+    const checkCustomOutput = (run, method, params) => {
+        if (method === "turn.paused")
+            throw new HarnessApiError("invalid", "A custom harness cannot pause for approvals in Harness API 2");
+        if (params.state === undefined || run.outputs.has(method))
+            return;
+        const bytes = Buffer.byteLength(JSON.stringify(params.state) ?? "");
+        if (bytes <= MAX_HARNESS_STATE_BYTES)
+            return;
+        output(run, "turn.failed", {
+            runId: run.grant.runId,
+            status: "failed",
+            thrown: { code: "invalid", message: `The harness's state is ${bytes} bytes, over ${MAX_HARNESS_STATE_BYTES}` },
+        }).catch(() => undefined);
+        throw new HarnessApiError("invalid", `state over 256 KiB (${bytes} bytes): the turn failed`);
+    };
     const output = (run, method, params) => {
         const known = run.outputs.get(method);
         if (known)
@@ -262,7 +330,10 @@ export function createHarnessApiServer(ctx, options = {}) {
         status() {
             return {
                 connected: connections.size,
-                workspace: [...connections].some((connection) => connection.workspace && !connection.host && !connection.channel.closed),
+                workspace: [...connections].some((connection) => connection.workspace &&
+                    !connection.host &&
+                    connection.harness === DEFAULT_HARNESS &&
+                    !connection.channel.closed),
             };
         },
         hosting(sandboxId) {
@@ -275,10 +346,19 @@ export function createHarnessApiServer(ctx, options = {}) {
         },
         async workspace(method, params, signal, target) {
             const pod = target?.pod;
-            const connection = [...connections].find((item) => item.workspace && !item.channel.closed && item.host?.sandboxId === pod);
+            const session = params.session?.ownerId;
+            // A pod's workspace is its host's, whatever harness it is. Any other session's is served
+            // by its own harness, if that harness serves workspaces: our harness's workspaces are not
+            // a custom harness's files (R4.1). Sweeps and removes go to ours.
+            const harness = pod !== undefined || session === undefined
+                ? DEFAULT_HARNESS
+                : harnessOf((await ctx.store.tx((t) => t.get("sessions", session))) ?? {});
+            const connection = [...connections].find((item) => item.workspace &&
+                !item.channel.closed &&
+                item.host?.sandboxId === pod &&
+                (pod !== undefined || item.harness === harness));
             if (!connection)
                 throw new NoWorkspaceHarness(pod);
-            const session = params.session?.ownerId;
             if (session)
                 connection.claims.set(session, (connection.claims.get(session) ?? 0) + 1);
             else