@springbrand/agent-runtime 0.2.0-alpha.72 → 0.3.0-alpha.10

package/src/{pi/runtime-adapter/assembly.ts → config/pinning.ts}

@@ -1,16 +1,17 @@
+import { sha256Hex } from "../lib/artifacts";
 import type {
   RuntimeBindings,
   RuntimeGatewaySession,
   RuntimePlatformPort,
-} from "../../kernel/bindings";
-import type { RuntimeDegradation } from "../../kernel/degradation";
+} from "./ports";
+import type { RuntimeDegradation } from "./degradation";
 import type {
   RuntimeExtensionPermissions,
-} from "../../kernel/extensions";
-import type { RuntimeProfile } from "../../kernel/profile";
-import type { ExecutionLevel } from "../../lib/execution-level";
-import type { RuntimeSnapshot } from "../../runtime-assembler";
-import type { FinalizedPiToolSurface, PiRuntimeAssembly } from "../assembly";
+} from "../context/extension/contracts";
+import type { RuntimeProfile } from "./profile";
+import type { ExecutionLevel } from "../lib/execution-level";
+import type { RuntimeSnapshot } from "./assembler";
+import type { FinalizedPiToolSurface, PiRuntimeAssembly } from "../context";
 import {
   assemblePiSystemContext,
   assemblePiExtensions,
@@ -18,14 +19,35 @@ import {
   type PiExtensionAssembly,
   type PiExtensionContextContribution,
   type PiLoadedExtension,
-} from "../assembly";
+} from "../context";
 import {
   createPiGatewayToolCandidates,
   createPiMcpToolCandidates,
   listExtensionsPiToolCandidate,
   type PiMcpHost,
   type PiToolCandidate,
-} from "../tool";
+} from "../tools";
+
+export interface RuntimeAssemblyPin {
+  readonly revision: string;
+  readonly descriptor: string;
+}
+
+/** A saved pin is reusable only with its original Runtime key and intact descriptor. */
+export async function validateRuntimeAssemblyPin(
+  runtimeKey: string,
+  pin: RuntimeAssemblyPin,
+): Promise<boolean> {
+  if (!runtimeKey) {
+    throw new Error("Cannot safely recover a pinned Submission without its original Runtime key");
+  }
+  if (!pin.revision && !pin.descriptor) return false;
+  if (!pin.revision || !pin.descriptor) throw new Error("Submission assembly pin is incomplete");
+  if (pin.revision !== await sha256Hex(pin.descriptor)) {
+    throw new Error("Pinned Runtime assembly descriptor is invalid");
+  }
+  return true;
+}
 
 /**
  * 本文件负责准备 Pi 的扩展与工具，并为每次提交固定可恢复的运行描述。
@@ -85,7 +107,7 @@ interface PreparedPiAssembly {
  * 提供准备 Pi 所需的已校验 Runtime 快照和 Host 端口。
  *
  * @remarks
- * `PiRuntimeAdapter.prepare` 在加载 Runtime 配置时传入它。
+ * `HarnessRuntimeConfig.prepare` 在加载 Runtime 配置时传入它。
  *
  * 扩展绑定仍由 Host 创建，因为 Cloudflare 绑定属于 Worker 的能力边界。
  *
@@ -128,13 +150,18 @@ export interface PreparedPiRuntime {
  * 提供把一次提交固定到当前 Runtime 所需的值。
  *
  * @remarks
- * Runtime 在写入提交前的准入阶段把它交给 `PiRuntimeAdapter.pin`。
+ * Runtime 在写入提交前的准入阶段把它交给 `HarnessRuntimeConfig.pin`。
  *
  * 扩展没有可读上下文时不需要读取函数，所以该端口保持可选。
  */
 export interface PinPiRuntimeOptions {
   readonly prepared: PreparedPiRuntime;
   readonly baseRevision: string;
+  /**
+   * Whether this Submission may inherit automatic hot and cold Memory context.
+   * Scheduled task input is intentionally isolated from those sources.
+   */
+  readonly includeMemory?: boolean;
   /**
    * 读取一个扩展要写入固定系统提示词的上下文。
    *
@@ -165,7 +192,7 @@ export interface PinnedPiRuntime {
  * 描述一条已存提交可以恢复到哪份 Pi 配置。
  *
  * @remarks
- * `PreparedPiTurnAdapter` 在重建 Turn 前读取这个 JSON 结构。
+ * `HarnessRuntimeConfig.harnessInputs` 在打开或恢复 operation 前读取这个 JSON 结构。
  *
  * 基础版本作为准入时元数据保留，创建 Turn 时不与当前 Runtime 比较。
  */
@@ -227,9 +254,20 @@ function describeTools(candidates: readonly PiToolCandidate[]) {
       description: candidate.tool.description ?? candidate.tool.label,
       parameters: candidate.tool.parameters,
       requiredExecutionLevel: candidate.requiredExecutionLevel,
+      ...(candidate.confirmation ? { confirmation: true } : {}),
       ...(candidate.alwaysRequiresApproval
         ? { alwaysRequiresApproval: true }
         : {}),
+      ...(candidate.unattendedExecution
+        ? {
+            unattendedExecution: {
+              capability: candidate.unattendedExecution.capability,
+              operation: candidate.unattendedExecution.operation,
+              objectConstrained:
+                candidate.unattendedExecution.objectForInput !== undefined,
+            },
+          }
+        : {}),
       ...(candidate.deferLoading ? { deferLoading: true } : {}),
       ...(candidate.source ? { source: candidate.source } : {}),
       retry: piToolRetryPolicy(candidate),
@@ -282,7 +320,7 @@ function describeRuntime(
 class PreparedRuntime implements PreparedPiRuntime {
   // 把公开版本数据与受身份保护的内部准备状态放在同一个句柄里。
   // 只有 preparePiRuntime 会构造它，并在返回前冻结实例。
-  // owner 使用对象身份区分 PiRuntimeAdapter，避免不同适配器的句柄被混用。
+  // owner 使用对象身份区分 HarnessRuntimeConfig，避免不同适配器的句柄被混用。
   constructor(
     readonly revisionDescriptor: string,
     readonly degradations: readonly RuntimeDegradation[],
@@ -305,7 +343,7 @@ class PreparedRuntime implements PreparedPiRuntime {
 }
 
 /**
- * 为创建它的 PiRuntimeAdapter 打开准备句柄。
+ * 为创建它的 HarnessRuntimeConfig 打开准备句柄。
  *
  * @remarks
  * 固定配置和创建 Turn 都会先调用它，再读取快照、装配结果或工具候选。
@@ -326,7 +364,7 @@ export function readPreparedPiRuntime(
  * 读取已存的固定描述。
  *
  * @remarks
- * `PreparedPiTurnAdapter` 在新建或恢复 Pi Turn 前调用它。
+ * `HarnessRuntimeConfig.harnessInputs` 在新建或恢复 Pi operation 前调用它。
  *
  * Prepared Runtime 提供当前执行能力，descriptor 仅保留 Submission 固定的 Turn 字段。
  */
@@ -415,7 +453,7 @@ async function preparePiAssembly(
  * 为一份已校验的 Runtime 快照准备扩展和工具状态。
  *
  * @remarks
- * `PiRuntimeAdapter.prepare` 在 Runtime 配置阶段、快照生效前调用它。
+ * `HarnessRuntimeConfig.prepare` 在 Runtime 配置阶段、快照生效前调用它。
  *
  * 冻结句柄会保存最终候选列表，对外只提供版本描述和降级结果。
  */
@@ -459,11 +497,14 @@ export async function pinPiRuntime(
 ): Promise<PinnedPiRuntime> {
   const state = readPreparedPiRuntime(options.prepared, owner);
   const { snapshot, assembly } = state;
+  const includeMemory = options.includeMemory !== false;
   const context = await assemblePiSystemContext({
     baseSystemPrompt: snapshot.pi.systemPrompt,
-    memory: snapshot.profile.memory,
-    memoryPort: snapshot.bindings.memory,
-    workspace: snapshot.bindings.workspace,
+    memory: includeMemory
+      ? snapshot.profile.memory
+      : { ...snapshot.profile.memory, enabled: false },
+    memoryPort: includeMemory ? snapshot.bindings.memory : undefined,
+    workspace: includeMemory ? snapshot.bindings.workspace : undefined,
     skills: snapshot.bindings.skills.sources,
     extensionContexts: assembly.context,
     readExtensionContext: options.readExtensionContext,

package/src/{kernel/bindings.ts → config/ports.ts}

@@ -1,15 +1,18 @@
+export type { RuntimeSchedulePreparation } from "../submission/contracts";
+import type { RuntimeModelInputModality } from "./profile";
 import type { SkillSource } from "agents/skills";
-import type { ScheduleSpec } from "./receipts";
-import type { RuntimeActivityProjection } from "./state";
+import type { ScheduleSpec, RuntimeSchedulePreparation } from "../submission/contracts";
+import type { RuntimeActivityProjection } from "../conversation/state";
 import type { ExecutionLevel } from "../lib/execution-level";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
-import type { PiToolCandidate } from "../pi/tool/compiler";
+import type { PiToolCandidate } from "../tools/runtime/contracts";
 import type {
   RuntimeEventConfirmation,
   RuntimeLifecycleFact,
   RuntimeSubagentUsageEvent,
   RuntimeSubagentUsageMetrics,
-} from "./submission-authority";
+} from "../tools/subagent/authority";
+export type { RuntimeModelInputModality } from "./profile";
 export type {
   RuntimeEventConfirmation,
   RuntimeLifecycleFact,
@@ -19,7 +22,7 @@ export type {
   RuntimeSubmissionAdmissionHook,
   RuntimeSubmissionAdmissionInput,
   RuntimeSubmissionAdmissionResult,
-} from "./submission-authority";
+} from "../tools/subagent/authority";
 
 // #region Workspace 端口
 
@@ -624,7 +627,7 @@ export interface RuntimeGatewayPort {
 }
 
 /** Safe catalog from an external Host; credentials and SDK clients stay there. */
-export type RuntimeMcpHost = import("../pi/tool/mcp").PiMcpHost & {
+export type RuntimeMcpHost = import("../tools/mcp").PiMcpHost & {
   readonly servers: readonly import("./profile").RuntimeMcpServer[];
 };
 
@@ -667,16 +670,25 @@ export interface RuntimeScheduleAgentSummary {
  * 让 Runtime 通过 Host 管理当前用户的定时任务。
  *
  * @remarks
- * Schedule Plugin 在装配时把它交给基础工具，模型在用户要求创建、查询或取消时调用。
+ * Host 提供准备与提交操作；Runtime 在现有持久化审批中固定候选并等待用户确认。
  *
- * 任务归属和持久化留在 Host，Runtime 只传递 `ScheduleSpec` 和窄结果。
+ * 任务事实、候选版本、授权检查和保存幂等由 Host 持有，不存放凭据。
  */
+export interface RuntimeScheduleConfirmationPort {
+  /** Read-only preparation; bind the full candidate and authorization to this stable intent. */
+  prepare(request: RuntimeScheduleUpdate & { intentId: string; id?: string }): Promise<RuntimeSchedulePreparation>;
+  /** Atomically check candidate/version, live authorization and quotas. Replay must return the same task. */
+  commit(prepared: RuntimeSchedulePreparation, context: { intentId: string; signal: AbortSignal }): Promise<{ id: string }>;
+}
+
 export interface RuntimeSchedulePort {
+  /** Required for chat creation/editing. Legacy management callers retain their CRUD contract. */
+  confirmation?: RuntimeScheduleConfirmationPort;
   /**
    * 创建一条定时任务并返回它的 ID。
    *
    * @remarks
-   * `schedule` 工具在把用户的时间与提示词组成 `ScheduleSpec` 后调用。
+   * 保留给既有宿主管理调用者；聊天 `schedule` 只经 confirmation.commit 保存。
    *
    * Host 在该边界内绑定用户与会话，Runtime 不携带业务归属 ID。
    */
@@ -827,7 +839,7 @@ export interface RuntimeModelUsageEvent {
  * 结算事件刻意不带参数，因为它只用来记账；开始事件必须带，因为它唯一的用处
  * 就是让 Host 立刻知道「正在写的是什么」——只有工具名的话，「write 开始了」
  * 和「一个网页正在生成」之间的差别就丢了，而后者才是盯着屏幕的人要看的。
- * 参数本来就随 Tool 输入里程碑落库，这里没有多暴露任何东西。
+ * 参数本来就随 Pi Tool 调用写入 Session，这里没有多暴露任何东西。
  */
 export interface RuntimeToolStartEvent {
   readonly submissionId: string;
@@ -942,12 +954,6 @@ export type RuntimeModelProtocol =
   | "google-generative-ai"
   | "openai-codex-responses";
 
-export type RuntimeModelInputModality =
-  | "text"
-  | "image"
-  | "file"
-  | "audio"
-  | "video";
 
 /**
  * 描述一个已解析凭据的模型 API 端点。
@@ -1024,6 +1030,16 @@ export interface RuntimePlatformPort {
     requiredExecutionLevel: ExecutionLevel;
     signal: AbortSignal;
   }): Promise<void>;
+  /**
+   * Match a pinned scheduled-task grant against the concrete Tool operation
+   * and recheck the Host-owned live account authorization.
+   *
+   * This callback must fail closed by throwing a user-safe, specific reason.
+   * It is called before dispatch and again at the effect boundary so a grant
+   * revocation cannot be hidden by an earlier decision.
+   */
+  /** @deprecated Scheduled execution is authorized locally by execution level. */
+  authorizeUnattendedExecution?(request: unknown): Promise<void>;
 }
 
 /**

package/src/{kernel → config}/profile.ts

@@ -1,5 +1,12 @@
 import type { ExecutionLevel } from "../lib/execution-level";
 
+export type RuntimeModelInputModality =
+  | "text"
+  | "image"
+  | "file"
+  | "audio"
+  | "video";
+
 /**
  * 指定模型在一次 Turn 中可以使用的推理强度。
  *

package/src/{kernel → config}/public-contracts.ts

@@ -11,13 +11,13 @@
  * @packageDocumentation
  */
 export * from "./profile";
-export * from "./runtime-assembly-view";
+export * from "./assembly-view";
 export * from "./runtime-config";
-export * from "../pi/message";
-export * from "./receipts";
-export * from "./state";
+export * from "../conversation/message";
+export * from "../submission/contracts";
+export * from "../conversation/state";
 export * from "../lib/execution-level";
-export type { WorkspaceRevision, WorkspaceRevisionManifest } from "../workspace-versioning";
+export type { WorkspaceRevision, WorkspaceRevisionManifest } from "../tools/workspace/versioning";
 export type {
   RuntimeEventConfirmation,
   RuntimeLifecycleFact,
@@ -27,4 +27,4 @@ export type {
   RuntimeSubmissionAdmissionHook,
   RuntimeSubmissionAdmissionInput,
   RuntimeSubmissionAdmissionResult,
-} from "./submission-authority";
+} from "../tools/subagent/authority";

package/src/{kernel → config}/runtime-load.ts

@@ -1,4 +1,4 @@
-import type { RuntimeLoadPhase, RuntimeLoadState } from "./state";
+import type { RuntimeLoadPhase, RuntimeLoadState } from "../conversation/state";
 
 /** Hard ceiling for one Host-owned Runtime definition phase. */
 export const RUNTIME_LOAD_TIMEOUT_MS = 180_000;

package/src/{pi/assembly/context.ts → context/assembly.ts}

@@ -1,212 +1,12 @@
-import { summarizeModelUsage } from "../../model-usage";
-import { BACKGROUND_CONTEXT, withAbortSignal } from "@earendil-works/pi-agent-core/harness/context";
-import {
-  buildSessionContext,
-  compact as compactPiTranscript,
-  DEFAULT_COMPACTION_SETTINGS,
-  estimateContextTokens,
-  estimateTokens,
-  prepareCompaction,
-  type AgentMessage,
-  type CompactionEntry,
-  type Entry,
-} from "@earendil-works/pi-agent-core";
-import type {
-  AssistantMessage,
-  Model,
-  Models,
-  RetryPolicy,
-  Usage,
-} from "@earendil-works/pi-ai";
-import { estimateStringTokens } from "agents/experimental/memory/utils";
-import type { RuntimeMemoryPort } from "../../kernel/bindings";
-import type { RuntimeDegradation } from "../../kernel/degradation";
-import type { RuntimeMemoryProfile } from "../../kernel/profile";
-import type { PiExtensionContextContribution } from "./extensions";
-
-/**
- * 压缩这一次 LLM 调用的重试策略。
- *
- * 为什么必须显式传:pi 的 `retryAssistantCall` 是 opt-in 的 —— d.ts 原话
- * 「When `policy` is undefined or disabled, the first response is returned
- * unchanged」。升到 0.83 不传这个参数,行为与 0.80.6 完全一样(零重试)。
- *
- * 为什么压缩值得重试:压缩失败不是「少一次摘要」,是**下一轮直接撞 provider
- * 的上下文窗口上限、整个 turn 挂掉**。而它跑在 Workers 里,瞬时网络错误是常态。
- *
- * 为什么只有 2 次、退避从 500ms 起:压缩发生在 turn 的关键路径上,DO 的墙钟
- * 是真金白银(等 LLM 不占 CPU 配额但占用户的等待)。2 次退避总计约 1.5s,
- * 够穿过瞬时抖动,又不至于把一次失败拖成用户可感知的卡顿。
- */
-const COMPACTION_RETRY: RetryPolicy = {
-  enabled: true,
-  maxRetries: 2,
-  baseDelayMs: 500,
-};
+import { estimateStringTokens } from "../lib/token-estimate";
+import type { RuntimeMemoryPort } from "../config/ports";
+import type { RuntimeDegradation } from "../config/degradation";
+import type { RuntimeMemoryProfile } from "../config/profile";
+import type { PiExtensionContextContribution } from "./extension/assembly";
 
 const COLD_MEMORY_INDEX = "/userspace/memories/MEMORY.md";
 const TRUNCATION_MARKER = "\n[truncated to memory budget]";
 
-function compactionUsage(responses: readonly AssistantMessage[], requested: Model<any>) {
-  const [first, ...remaining] = responses;
-  return first ? { modelUsage: summarizeModelUsage(requested, [first, ...remaining]) } : {};
-}
-
-// #region Transcript compaction
-
-/**
- * 把当前 Pi 会话分支压缩成下一轮可以直接使用的消息。
- *
- * @remarks
- * Transcript 在每轮开始前传入当前分支、模型和 token 阈值，并在返回压缩条目后自行追加到 Session。
- *
- * 这里先用 Pi 的 Session 管线重建上下文，任何失败都退回未压缩消息，以避免压缩失败损坏持久化会话。
- *
- * 核心术语见包入口 `index.ts`。
- */
-export async function compactPiContext(input: Readonly<{
-  branch: readonly Entry[];
-  compactAfterTokens: number;
-  force?: boolean;
-  models: Models;
-  model: Model<any>;
-  signal?: AbortSignal;
-}>): Promise<{
-  messages: AgentMessage[];
-  compactionEntry?: Omit<
-    CompactionEntry,
-    "id" | "parentId" | "seq" | "timestamp"
-  >;
-  modelUsage?: {
-    api: string;
-    provider: string;
-    model: string;
-    responseModel?: string;
-    stopReason?: string;
-    usage: Usage;
-  };
-  didCompact: boolean;
-  degraded: boolean;
-}> {
-  const responses: AssistantMessage[] = [];
-  const branch = [...input.branch];
-  const context = input.signal ? withAbortSignal(input.signal, BACKGROUND_CONTEXT) : BACKGROUND_CONTEXT;
-  let currentMessages = branch.flatMap((entry) =>
-    entry.type === "message" ? [entry.message] : []
-  );
-  try {
-    currentMessages = await buildSessionContext(branch, undefined, context);
-    const settings = DEFAULT_COMPACTION_SETTINGS;
-    if (
-      !settings.enabled ||
-      (!input.force && estimateContextTokens(currentMessages).tokens <
-        input.compactAfterTokens)
-    ) {
-      return {
-        messages: currentMessages,
-        didCompact: false,
-        degraded: false,
-      };
-    }
-
-    const preparation = prepareCompaction(branch, settings);
-    if (!preparation.ok) {
-      return {
-        messages: currentMessages,
-        didCompact: false,
-        degraded: true,
-        ...compactionUsage(responses, input.model),
-      };
-    }
-    if (!preparation.value) {
-      return {
-        messages: currentMessages,
-        didCompact: false,
-        degraded: false,
-      };
-    }
-
-    const models = {
-      completeSimple: async (
-        model: Model<any>,
-        context: Parameters<Models["completeSimple"]>[1],
-        options?: Parameters<Models["completeSimple"]>[2],
-      ) => {
-        const response = await input.models.completeSimple(model, context, options);
-        responses.push(response);
-        input.signal?.throwIfAborted();
-        return response;
-      },
-    } as Models;
-    const compacted = await compactPiTranscript(
-      preparation.value,
-      models,
-      input.model,
-      undefined,
-      undefined,
-      COMPACTION_RETRY,
-      undefined,
-      context,
-    );
-    if (!compacted.ok) {
-      return {
-        messages: currentMessages,
-        didCompact: false,
-        degraded: true,
-        ...compactionUsage(responses, input.model),
-      };
-    }
-
-    const compactionEntry = {
-      type: "compaction",
-      fromHook: false,
-      ...compacted.value,
-    } satisfies Omit<
-      CompactionEntry,
-      "id" | "parentId" | "seq" | "timestamp"
-    >;
-    const previewEntry: CompactionEntry = {
-      ...compactionEntry,
-      id: `compaction-preview:${branch[branch.length - 1]?.id ?? "root"}`,
-      parentId: branch[branch.length - 1]?.id ?? null,
-      timestamp: Date.now(),
-      seq: (branch.at(-1)?.seq ?? 0) + 1,
-    };
-    const messages = await buildSessionContext(
-      [...branch, previewEntry], undefined, context,
-    );
-    if (
-      input.force &&
-      messages.reduce((total, message) => total + estimateTokens(message), 0) >=
-        currentMessages.reduce(
-          (total, message) => total + estimateTokens(message),
-          0,
-        )
-    ) {
-      return {
-        messages: currentMessages,
-        didCompact: false,
-        degraded: true,
-        ...compactionUsage(responses, input.model),
-      };
-    }
-    return {
-      messages,
-      compactionEntry,
-      ...compactionUsage(responses, input.model),
-      didCompact: true,
-      degraded: false,
-    };
-  } catch {
-    return {
-      messages: currentMessages,
-      didCompact: false,
-      degraded: true,
-      ...compactionUsage(responses, input.model),
-    };
-  }
-}
-
 // 作用：把一段上下文裁到指定 token 预算内。
 // 调用：内存和 Extension 上下文在拼入 system prompt 前调用。
 // 原因：二分搜索每次都用同一个 token 估算器验证，改成字符数截断会突破真实预算。
@@ -246,8 +46,6 @@ function renderBlock(
   return `${separator}\n${label} (${description})\n${separator}\n${content}`;
 }
 
-// #endregion
-
 // #region System context sources
 
 // 作用：同时收集当前 Session 内存和用户管理的冷内存索引。

package/src/{pi/assembly/extensions.ts → context/extension/assembly.ts}

@@ -8,12 +8,12 @@ import type {
   LoadedRuntimeExtension,
   RuntimeExtensionConfig,
   RuntimeExtensionPermissions,
-} from "../../kernel/extensions";
-import type { RuntimeDegradation } from "../../kernel/degradation";
-import { withRuntimeLoadTimeout } from "../../kernel/runtime-load";
+} from "./contracts";
+import type { RuntimeDegradation } from "../../config/degradation";
+import { withRuntimeLoadTimeout } from "../../config/runtime-load";
 import { sanitizeExtensionName } from "../../lib/extension-name";
-import type { PiToolCandidate } from "../tool/compiler";
-import { createPiDeclaredToolCandidate } from "../tool/declared";
+import type { PiToolCandidate } from "../../tools/runtime/contracts";
+import { createPiDeclaredToolCandidate } from "../../tools/adapters/declared";
 
 export interface PiExtensionContextContribution {
   readonly extensionName: string;

package/src/context/extension/index.ts

@@ -0,0 +1,3 @@
+export * from "./assembly";
+export * from "./contracts";
+export * from "./repository";

package/src/context/index.ts

@@ -0,0 +1,6 @@
+export * from "./assembly";
+export * from "./extension/assembly";
+export * from "./extension/contracts";
+export * from "./extension/repository";
+export * from "./memory/budget/gate";
+export * from "../config/assembly-snapshot";

package/src/{layers/context → context/memory}/budget/gate.ts

@@ -1,4 +1,5 @@
 import {
+  artifactId,
   type ArtifactRef,
   serializeOutput,
   sha256Hex,
@@ -29,7 +30,7 @@ import {
 /**
  * 持久化单个字符串叶子的上限。
  *
- * MUST ≥ 单页 read 的上限（见 `workspace-sandbox.ts` 的 `READ_PAGE_MAX_CHARS`），
+ * MUST ≥ 单页 read 的上限（见 `tools/workspace/index.ts` 的 `READ_PAGE_MAX_CHARS`），
  * 否则持久记录会比模型当轮看到的内容还少，会话恢复后出现凭空缺页。
  */
 export const STORAGE_LEAF_MAX_CHARS = 64 * 1024;
@@ -44,8 +45,8 @@ export const SPILL_THRESHOLD = 32 * 1024;
 /**
  * 历史里一条旧 Tool 结果重放多少。
  *
- * 这条最紧，因为它对每个 Turn 的**全部**历史消息生效（见
- * `pi/runtime-adapter/execution.ts` 的 `projectToolResultsForModel`）：
+ * 这条最紧，因为 `projectToolOutputForModel` 会把它应用到每个 Turn
+ * 重放的全部历史 Tool 结果：
  * 放宽 1 KB 就是 N 条历史 × 1 KB。
  */
 export const MODEL_REPLAY_THRESHOLD = 16 * 1024;
@@ -161,11 +162,26 @@ export async function spillDurableToolOutput(
       text,
       ext === "json" ? "application/json" : "text/plain",
     );
+    if (!options.workspace.stat || !options.workspace.readFileBytes) {
+      throw new Error("Workspace artifact verification is unavailable");
+    }
+    const stat = await options.workspace.stat(path);
+    const expectedBytes = new TextEncoder().encode(text).byteLength;
+    if (!stat || stat.type !== "file" || stat.size !== expectedBytes) {
+      throw new Error("Workspace artifact failed size verification");
+    }
+    const stored = await options.workspace.readFileBytes(path);
+    if (!stored || new TextDecoder().decode(stored) !== text) {
+      throw new Error("Workspace artifact failed content verification");
+    }
     return {
       kind: "artifact_ref",
+      artifactId: artifactId(hash),
       path,
-      bytes: new TextEncoder().encode(text).byteLength,
-      hash: hash.slice(0, 16),
+      bytes: expectedBytes,
+      hash,
+      workspaceRevision: stat.contentVersion ?? `${stat.updatedAt}:${stat.size}`,
+      availability: "available",
       preview: text.slice(0, PREVIEW_CHARS),
       // 出口指令必须是可执行的：只说“去 read 这个路径”会诱导模型整读，而整读一个
       // 刚刚因为过大被外置的文件毫无意义。这里明确要求分页，并告知 read 会返回