@springbrand/agent-runtime 0.3.0-alpha.1 → 0.3.0-alpha.10

package/src/lib/artifacts.ts

@@ -4,9 +4,12 @@
 /** Stable narrow reference shared by messages, RPC responses and the UI. */
 export interface ArtifactRef {
   kind: "artifact_ref";
+  artifactId: string;
   path: string;
   bytes: number;
   hash: string;
+  workspaceRevision: string;
+  availability: "available" | "unavailable";
   preview: string;
   note: string;
 }
@@ -14,6 +17,15 @@ export interface ArtifactRef {
 export interface SpillWorkspace {
   /** 把溢出的 Artifact 内容写入指定 Workspace 路径。 */
   writeFile(path: string, content: string, mimeType?: string): Promise<void>;
+  /** 写入后验证物理文件，防止只持久化了一个不存在或被截断的引用。 */
+  stat?(path: string): Promise<{
+    type: "file" | "directory" | "symlink";
+    size: number;
+    updatedAt: number;
+    contentVersion?: string;
+  } | null>;
+  /** 写入后验证内容摘要；Artifact 全部是 UTF-8 文本。 */
+  readFileBytes?(path: string): Promise<Uint8Array | null>;
 }
 
 /**
@@ -33,6 +45,10 @@ export async function sha256Hex(text: string): Promise<string> {
   return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
 }
 
+function artifactId(hash: string): string {
+  return `artifact_${hash.slice(0, 24)}`;
+}
+
 /**
  * 把 Tool 结果转成可存储的文本，并选择 `.txt` 或 `.json` 扩展名。
  *
@@ -52,3 +68,5 @@ export function serializeOutput(output: unknown): { text: string; ext: "txt" | "
     return { text: String(output), ext: "txt" };
   }
 }
+
+export { artifactId };

package/src/lib/execution-level.ts

@@ -25,3 +25,16 @@ export function maxExecutionLevel(
     )
   ]!;
 }
+
+/** The most permissive level shared by an Agent and a Scheduled Task ceiling. */
+export function minExecutionLevel(
+  left: ExecutionLevel,
+  right: ExecutionLevel,
+): ExecutionLevel {
+  return EXECUTION_LEVELS[
+    Math.min(
+      EXECUTION_LEVELS.indexOf(left),
+      EXECUTION_LEVELS.indexOf(right),
+    )
+  ]!;
+}

package/src/lib/prompt.ts

@@ -17,9 +17,8 @@ export const PERSONA =
 // Names the stable runtime environment.
 export const RUNTIME =
   "Runtime: this agent runs on Cloudflare Workers. When execute is present, its Code Mode Dynamic Worker is your " +
-  "instrument — code there runs with outbound network access (fetch), your " +
-  "workspace filesystem (state.*), and the tools.* methods listed in its own description. Use it for raw or customized HTTP " +
-  "requests, parsing a payload, hitting several known endpoints, or computing over a file. Write plain " +
+  "instrument — code there runs with your workspace filesystem (state.*) and the tools.* methods listed in its own description. " +
+  "Use it for tool composition, parsing a payload, or computing over a file. Write plain " +
   "JavaScript — the sandbox evaluates " +
   "it directly, so TypeScript type annotations (`: number`, `as Type`) are a syntax error, and there " +
   "is no Python interpreter or package manager to invoke. Use the JS/Workers equivalent of what you " +
@@ -58,8 +57,7 @@ export const TOOLS =
   "use state.* for workspace file operations, tools.* for other host capabilities, and sequential calls for repeated or durable operations. " +
   "Top-level-only Tools remain Direct even when called repeatedly. " +
   "For web tasks, use web_search for web discovery, current facts, cited research, " +
-  "and public URL analysis. For web access specifically, use execute Code Mode only for raw or customized network requests, structured " +
-  "API calls, or when web_search cannot retrieve the required content; do not use execute for ordinary web " +
+  "and public URL analysis; do not use execute for ordinary web " +
   "searches. When execute is absent, use the actually exposed Direct Tools. When sandbox_* tools are present, use that isolated Linux environment for Python/Node, " +
   "package managers, system commands, builds, tests and background processes; its filesystem is temporary, " +
   "persistent inputs are copied in automatically on first use, /userspace is read-only, and only explicitly " +
@@ -70,7 +68,10 @@ export const TOOLS =
   "prioritize verification, saving durable results, and the final response. " +
   "When related Tool calls can run independently, all are available inside execute, and execute is present, run them inside that execute rather than as parallel top-level calls; " +
   "only independent top-level-only Direct Tools should be issued together in one turn. When you reference " +
-  "code, cite it as file_path:line_number.";
+  "code, cite it as file_path:line_number. " +
+  "When schedule tools are available, prepare a standalone Requirement (at most 1000 Unicode characters), a name (at most 50), a time rule and an explicit timezone. Ask for missing information. " +
+  "Use local once/daily/weekly rules for new scheduled tasks. The Host prepares the authorization scope and the user must confirm before saving; never claim a task was created before the Tool succeeds. " +
+  "One source Chat may create multiple tasks. Before editing, list tasks and use the exact Task ID; ask when the target is ambiguous. Never attach source history or hidden context to the Requirement.";
 
 // A real browser is the only way to observe what a page actually does, and the
 // shared failure mode is a browser tool that returns nothing and looks clean.

package/src/lib/token-estimate.ts

@@ -0,0 +1,8 @@
+/** Conservative token estimate for prompt budgeting, not provider billing. */
+export function estimateStringTokens(text: string): number {
+  if (!text) return 0;
+  return Math.ceil(Math.max(
+    text.length / 4,
+    text.split(/\s+/u).filter(Boolean).length * 1.3,
+  ));
+}

package/src/models/index.ts

@@ -790,6 +790,7 @@ function configuredModel(
       ? {
           compat: {
             ...anthropicMessagesCompat,
+            // OpenRouter rejects Anthropic's mid-conversation effort messages and block binding.
             supportsMidConvoEffort: false,
             supportsEagerToolInputStreaming: false,
             supportsStrictTools:

package/src/session/cloudflare/migration.ts

@@ -43,6 +43,13 @@ const RETIRED_SCHEDULE_CALLBACKS = [
   "_chatRecoveryRetry",
 ] as const;
 
+const LEGACY_TERMINAL_SUBMISSION_STATUSES = new Set([
+  "completed",
+  "failed",
+  "aborted",
+  "skipped",
+]);
+
 type LegacyRecord = Record<string, unknown> & {
   id: string;
   parentId: string | null;
@@ -310,6 +317,34 @@ function hasToolExecution(value: ToolExecution | undefined): boolean {
       typeof value.args === "object" && !Array.isArray(value.args));
 }
 
+/** A terminal Submission cannot resume, so its stale lane pointer is not active work. */
+function clearTerminalOperationPointers(sql: SqlStorage): void {
+  if (!hasTable(sql, "pi_submissions")) return;
+  const lanes = sql.exec<{ key: string; body: string }>(
+    "SELECT key, body FROM pi_values WHERE namespace = ?",
+    laneState("").namespace,
+  ).toArray();
+  for (const lane of lanes) {
+    const state = JSON.parse(lane.body) as LaneState;
+    if (state.currentOperationId === null) continue;
+    const terminal = sql.exec(
+      `SELECT 1 FROM pi_submissions
+       WHERE submission_id = ?
+         AND status IN ('completed', 'failed', 'aborted', 'skipped')
+       LIMIT 1`,
+      state.currentOperationId,
+    ).toArray().length === 1;
+    if (!terminal) continue;
+    sql.exec(
+      `UPDATE pi_values
+       SET body = json_set(body, '$.currentOperationId', json('null'))
+       WHERE namespace = ? AND key = ?`,
+      laneState("").namespace,
+      lane.key,
+    );
+  }
+}
+
 /** Old active tool outcomes cannot be reconstructed from error text or approval facts. */
 function assertActiveToolProvenance(sql: SqlStorage): void {
   const read = <T>(address: Value<T>): T | undefined => {
@@ -379,6 +414,7 @@ export function migrateCurrentPiSession(
     if (version !== 1 && version !== 2) {
       throw new Error(`Unsupported Cloudflare Pi storage version: ${version}`);
     }
+    clearTerminalOperationPointers(sql);
     assertActiveToolProvenance(sql);
     if (version === 1) removeRetiredRuntimeArtifacts(sql);
     repairDuplicatedUserSidecars(sql);
@@ -680,6 +716,20 @@ export function migrateLegacyPiSession(
               .map((row) => [row.message_id, row.submission_id] as const)
           : [],
       );
+      const submissionStatuses = new Map(
+        hasTable(sql, "pi_submissions")
+          ? sql
+              .exec<{ submission_id: string; status: string }>(
+                "SELECT submission_id, status FROM pi_submissions",
+              )
+              .toArray()
+              .map((row) => [row.submission_id, row.status] as const)
+          : [],
+      );
+      const terminalSubmission = (submissionId: string): boolean =>
+        LEGACY_TERMINAL_SUBMISSION_STATUSES.has(
+          submissionStatuses.get(submissionId) ?? "",
+        );
       const results = new Map<string, ToolResultMessage>();
       for (const entry of converted.values()) {
         if (entry.type !== "message" || entry.message.role !== "toolResult")
@@ -809,8 +859,12 @@ export function migrateLegacyPiSession(
             if (!knownSubmissions.has(row.submission_id))
               throw new Error("Dangling recovery submission");
             const record = decodePiToolRecoveryMilestone(row.body);
-            if (!record || record.turnId !== row.submission_id)
+            if (!record || record.turnId !== row.submission_id) {
+              if (LEGACY_TERMINAL_SUBMISSION_STATUSES.has(
+                submissionStatuses.get(row.submission_id) ?? "",
+              )) continue;
               throw new Error("Invalid legacy recovery milestone");
+            }
             const bodies = bySubmission.get(row.submission_id) ?? [];
             bodies.push(row.body);
             bySubmission.set(row.submission_id, bodies);
@@ -819,8 +873,12 @@ export function migrateLegacyPiSession(
                 .canonicalToolResults) {
                 const key = `${row.submission_id}:${result.toolCallId}`;
                 const previous = results.get(key);
-                if (previous) assertSameToolResult(previous, result);
-                results.set(key, result);
+                if (previous && !terminalSubmission(row.submission_id)) {
+                  assertSameToolResult(previous, result);
+                }
+                if (!previous || !terminalSubmission(row.submission_id)) {
+                  results.set(key, result);
+                }
               }
             }
           }
@@ -832,8 +890,12 @@ export function migrateLegacyPiSession(
               if (call.result) {
                 const key = `${submissionId}:${call.toolCallId}`;
                 const previous = results.get(key);
-                if (previous) assertSameToolResult(previous, call.result);
-                results.set(key, call.result);
+                if (previous && !terminalSubmission(submissionId)) {
+                  assertSameToolResult(previous, call.result);
+                }
+                if (!previous || !terminalSubmission(submissionId)) {
+                  results.set(key, call.result);
+                }
               }
             }
           }
@@ -901,7 +963,9 @@ export function migrateLegacyPiSession(
           const recorded = results.get(
             `${row.submission_id}:${row.tool_call_id}`,
           );
-          if (recorded) assertSameToolResult(recorded, expected);
+          if (recorded && !terminalSubmission(row.submission_id)) {
+            assertSameToolResult(recorded, expected);
+          }
         }
       }
       // The old table remains an inert backup. Failure rolls back DDL, data and the version together.

package/src/skills/springbrand-worker-website/index.ts

@@ -163,7 +163,7 @@ export const SPRINGBRAND_WORKER_WEBSITE_SKILL = {
     "5. Call `get_browser_console_logs` for the home page and for every primary internal page. Check navigation responses, missing assets, exceptions, CSP or CORS failures, and client fetch failures.",
     "6. Open the Website with the available browser evidence tools. For a multi-page Website, follow real links from the home page to every primary internal page and verify navigation back to the home page. Check at least the normal desktop viewport and one narrow viewport; capture and inspect a screenshot when visual appearance matters.",
     "7. Fix every failure, redeploy, and repeat the same checks. A clean home page does not prove a multi-page Website works.",
-    "8. After browser verification succeeds, call `save_creation` exactly once with the existing entry HTML Working Copy path. For the recommended layout, that is `/creations/<website-name>/public/index.html`.",
+    "8. After browser verification succeeds, call `save_creation` exactly once with a user-visible title and the existing entry HTML Working Copy path. For the recommended layout, that path is `/creations/<website-name>/public/index.html`.",
     "9. Do not call the Website complete until `save_creation` returns an `artifactId`. Do not save referenced assets as separate Creations.",
     "",
     "## Publication contract",

package/src/submission/admission.ts

@@ -12,7 +12,9 @@ import {
   SubmissionQueueFullError,
   type SubmissionInput,
 } from "./lifecycle";
-import { isTerminalSubmissionStatus, submissionAbortReason, type StoredSubmission, type SubmissionRepository } from "./repository";
+import { isTerminalSubmissionStatus, submissionAbortReason, type StoredSubmission, type SubmissionOrigin, type SubmissionRepository } from "./repository";
+import type { RuntimeUnattendedExecutionGrant } from "./contracts";
+import type { ExecutionLevel } from "../lib/execution-level";
 
 // Pending records retain identity indefinitely; only recent attempts reserve capacity.
 const ADMISSION_ATTEMPT_WINDOW_MS = 60_000;
@@ -23,6 +25,12 @@ export interface SubmitMessageOptions {
   userMessageId?: string;
   userMessage?: UIMessage & { role: "user" };
   regenerate?: boolean;
+  /** `scheduled` marks a Run injection that locks ordinary input until it ends. */
+  origin?: SubmissionOrigin;
+  /** Maximum execution level allowed by the Schedule Definition. */
+  scheduledMaxExecutionLevel?: ExecutionLevel;
+  /** Trusted Host grant; accepted only for a scheduled Submission. */
+  unattendedExecutionGrant?: RuntimeUnattendedExecutionGrant;
   /** Internal transfer of a durable accepted steer; never a public message option. */
   steerHandoff?: { submissionId: string; steerId: string };
 }
@@ -182,6 +190,9 @@ export class SubmissionAdmission {
               ? options.userMessageId ?? null
               : null,
             runId,
+            origin: options.origin,
+            scheduledMaxExecutionLevel: options.scheduledMaxExecutionLevel,
+            unattendedExecutionGrant: options.unattendedExecutionGrant,
           });
           const admitted = this.options.submissions.find(runId)!;
           this.options.onAdmitted(admitted, admission?.accepted === true);

package/src/submission/contracts.ts

@@ -13,6 +13,8 @@ export const APPROVAL_DECISIONS = [
   "allow_level",
 ] as const satisfies readonly ApprovalDecision["decision"][];
 
+export type { RuntimeUnattendedExecutionGrant } from "./unattended";
+
 /**
  * 记录一次待审批 Tool 执行的身份、摘要和原始输入。
  *
@@ -58,12 +60,35 @@ export type ScheduleJob =
  *
  * 触发条件与工作放在同一份规格里，使更新时可以原地替换两者，不用改变任务标识。
  */
+/**
+ * 一条按任务时区解释的当地时间规则。
+ *
+ * @remarks
+ * `once` 在单个本地日历日触发;`daily` 每个本地日触发;`weekly` 在选中的每个本地星期触发
+ * (0 = 周日 … 6 = 周六)。所有星期共用同一个本地钟点。
+ *
+ * 规则只描述当地墙上时间;缺失/重复钟点、起止日期和夏令时语义由
+ * `adapter/cloudflare/scheduling` 的公共计算边界处理。
+ */
+export type LocalScheduleRule =
+  | { kind: "once"; date: string; time: string }
+  | { kind: "daily"; time: string }
+  | { kind: "weekly"; weekdays: number[]; time: string };
+
 export interface ScheduleSpec {
   trigger:
     | { kind: "once-at"; at: string }
     | { kind: "once-in"; seconds: number }
     | { kind: "cron"; cron: string }
-    | { kind: "interval"; seconds: number };
+    | { kind: "interval"; seconds: number }
+    | {
+        kind: "local";
+        rule: LocalScheduleRule;
+        /** 含当天的最早生效本地日期 `YYYY-MM-DD`。 */
+        startDate?: string;
+        /** 含当天的最后生效本地日期 `YYYY-MM-DD`。 */
+        endDate?: string;
+      };
   job: ScheduleJob;
   label?: string;
   /**
@@ -115,7 +140,9 @@ export type MessageDelivery = "steer" | "enqueue";
 export type MessageDispatchErrorCode =
   | "queue_full"
   | "not_steerable"
-  | "invalid_message";
+  | "invalid_message"
+  /** A scheduled Run owns this Session's input until it reaches a terminal state. */
+  | "input_locked";
 
 export type MessageDispatchReceipt =
   | {
@@ -139,3 +166,16 @@ export type MessageDispatchReceipt =
       code: MessageDispatchErrorCode;
       message: string;
     };
+
+/** Complete, credential-free task version prepared by a trusted Host for human confirmation. */
+export interface RuntimeSchedulePreparation {
+  candidateId: string;
+  candidateVersion: string;
+  id?: string;
+  prompt: string;
+  label: string;
+  trigger: ScheduleSpec["trigger"];
+  timezone: string;
+  nextRunAt?: number;
+  authorization: { version: string; missing: string[]; scope: string };
+}

package/src/submission/delivery.ts

@@ -2,7 +2,7 @@ import type { UIMessage } from "ai";
 import type { PiCanonicalUserInput } from "../conversation/message/contract";
 import type { RuntimeTelemetryCoordinator } from "../telemetry/coordinator";
 import type { RuntimeTurnEvents } from "../telemetry/turn-events";
-import type { HarnessHumanDecisions } from "../tools/human-decisions";
+import type { HarnessHumanDecisions } from "../tools/runtime/human-decisions";
 import type { SubmitMessageOptions } from "./admission";
 import {
   projectSubmissionReceipt,

package/src/submission/finalization.ts

@@ -4,7 +4,7 @@ import type { ConversationHistory } from "../conversation/history";
 import type { MessageUiRepository } from "../conversation/repository";
 import type { RuntimeTelemetryCoordinator } from "../telemetry/coordinator";
 import type { RuntimeTurnEvents } from "../telemetry/turn-events";
-import type { HarnessHumanDecisions } from "../tools/human-decisions";
+import type { HarnessHumanDecisions } from "../tools/runtime/human-decisions";
 import { USER_STOP_REASON } from "./contracts";
 import type { SubmissionOutcome } from "./lifecycle";
 import { isTerminalSubmissionStatus, type StoredSubmission, type SubmissionRepository } from "./repository";

package/src/submission/repository.ts

@@ -1,5 +1,7 @@
 import type { SqlTaggedTemplate } from "agents/chat";
 import type { LaneSnapshot } from "@earendil-works/pi-agent-core";
+import type { ExecutionLevel } from "../lib/execution-level";
+import type { RuntimeUnattendedExecutionGrant } from "./unattended";
 
 // Submission 的统一定义见 ./index.ts。
 // #region 状态与行类型
@@ -11,6 +13,14 @@ export type SubmissionStatus =
   | "skipped"
   | "error";
 
+/**
+ * 谁发起了这条 Submission。
+ *
+ * `scheduled` 是定时 Run 的注入:它在本 Session 未结束期间独占输入,
+ * 普通 `user` Submission 必须被拒绝,而不是排队等它结束。
+ */
+export type SubmissionOrigin = "user" | "scheduled";
+
 const TERMINAL_SUBMISSION_STATUSES: ReadonlySet<SubmissionStatus> = new Set([
   "completed",
   "aborted",
@@ -23,7 +33,7 @@ const TERMINAL_SUBMISSION_STATUSES: ReadonlySet<SubmissionStatus> = new Set([
 // 终态集合收口在一处防止各生命周期的判断漂移；增加状态时必须先确认它是否真的不可再继续。
 export function isTerminalSubmissionStatus(
   status: SubmissionStatus,
-): boolean {
+): status is Exclude<SubmissionStatus, "pending" | "running"> {
   return TERMINAL_SUBMISSION_STATUSES.has(status);
 }
 
@@ -46,6 +56,10 @@ export interface StoredSubmission {
   userMessageId: string | null;
   regenerateMessageId: string | null;
   runId: string | null;
+  origin: SubmissionOrigin;
+  scheduledMaxExecutionLevel: ExecutionLevel | null;
+  unattendedExecutionGrant: RuntimeUnattendedExecutionGrant | null;
+  unattendedFailure: string | null;
   retryable?: boolean;
 }
 
@@ -69,6 +83,9 @@ export interface NewSubmission {
   userMessageId?: string | null;
   regenerateMessageId?: string | null;
   runId?: string | null;
+  origin?: SubmissionOrigin;
+  scheduledMaxExecutionLevel?: ExecutionLevel;
+  unattendedExecutionGrant?: RuntimeUnattendedExecutionGrant;
 }
 
 type SubmissionRow = {
@@ -90,7 +107,11 @@ type SubmissionRow = {
   user_message_id: string | null;
   regenerate_message_id: string | null;
   run_id: string | null;
+  origin: string | null;
+  scheduled_max_execution_level: string | null;
   admission_retryable: number | null;
+  unattended_execution_grant_json: string | null;
+  unattended_failure: string | null;
 };
 
 // #endregion
@@ -118,6 +139,12 @@ function mapRow(row: SubmissionRow): StoredSubmission {
     userMessageId: row.user_message_id,
     regenerateMessageId: row.regenerate_message_id,
     runId: row.run_id,
+    origin: row.origin === "scheduled" ? "scheduled" : "user",
+    scheduledMaxExecutionLevel: row.scheduled_max_execution_level as ExecutionLevel | null,
+    unattendedExecutionGrant: row.unattended_execution_grant_json
+      ? JSON.parse(row.unattended_execution_grant_json) as RuntimeUnattendedExecutionGrant
+      : null,
+    unattendedFailure: row.unattended_failure,
     retryable: row.admission_retryable === null
       ? undefined
       : row.admission_retryable === 1,
@@ -150,7 +177,11 @@ export class SubmissionRepository {
              queued_input_json, queued_ui_message_json, user_message_id,
              regenerate_message_id,
              run_id,
-             admission_retryable
+             origin,
+             scheduled_max_execution_level,
+             admission_retryable,
+             unattended_execution_grant_json,
+             unattended_failure
       FROM pi_submissions
       WHERE submission_id = ${id}
     `[0];
@@ -251,7 +282,7 @@ export class SubmissionRepository {
         created_at, assembly_revision, assembly_descriptor, runtime_key,
         assistant_message_id, queued_input_json, queued_ui_message_json,
         user_message_id, regenerate_message_id,
-        run_id
+        run_id, origin, scheduled_max_execution_level, unattended_execution_grant_json
       ) VALUES (
         ${s.submissionId},
         ${s.requestId},
@@ -267,11 +298,31 @@ export class SubmissionRepository {
         ${s.queuedUiMessageJson ?? null},
         ${s.userMessageId ?? null},
         ${s.regenerateMessageId ?? null},
-        ${s.runId ?? s.submissionId}
+        ${s.runId ?? s.submissionId},
+        ${s.origin ?? "user"},
+        ${s.scheduledMaxExecutionLevel ?? null},
+        ${s.unattendedExecutionGrant
+          ? JSON.stringify(s.unattendedExecutionGrant)
+          : null}
       )
     `;
   }
 
+  /**
+   * 是否存在一条未结束的定时 Submission。
+   *
+   * 定时 Run 未结束时它独占本 Session 的输入:普通消息在准入前被拒绝,
+   * 不排队等待。Run 进入终态后查询自然为空,普通追问恢复。
+   */
+  hasUnfinishedScheduled(): boolean {
+    return (
+      this.sql<{ count: number }>`
+        SELECT COUNT(*) AS count FROM pi_submissions
+        WHERE status IN ('pending', 'running') AND origin = 'scheduled'
+      `[0]?.count ?? 0
+    ) > 0;
+  }
+
   insertRejected(s: {
     submissionId: string;
     requestId: string;
@@ -310,6 +361,15 @@ export class SubmissionRepository {
     return updated.length === 1;
   }
 
+  recordUnattendedFailure(id: string, reason: string): void {
+    this.sql`
+      UPDATE pi_submissions
+      SET unattended_failure = COALESCE(unattended_failure, ${reason})
+      WHERE submission_id = ${id}
+        AND status IN ('pending', 'running')
+    `;
+  }
+
   // 只在当前状态属于 from 时把 Submission 切换到 to，否则返回 false。
   // SubmissionLifecycle 开始 Turn 时调用，调用方用返回值识别过期或重复的状态切换。
   // Cloudflare SQLite 查询是同步的，两条语句之间不会让其他事件交错；UPDATE 再次带旧状态条件，不能去掉这层幂等保护。

package/src/submission/unattended.ts

@@ -0,0 +1,40 @@
+/** Host-confirmed authority pinned to one scheduled task Requirement version.
+ * Credentials never belong in scope; only trusted Host ports consume it.
+ */
+export interface RuntimeUnattendedExecutionGrant {
+  readonly taskId: string;
+  readonly requirementVersion: string;
+  readonly authorizationVersion: string;
+  readonly scope: Readonly<Record<string, unknown>>;
+}
+
+export function pinnedUnattendedExecutionGrant(
+  value: RuntimeUnattendedExecutionGrant,
+): RuntimeUnattendedExecutionGrant {
+  for (const [name, version] of [
+    ["task ID", value.taskId],
+    ["Requirement", value.requirementVersion],
+    ["authorization", value.authorizationVersion],
+  ] as const) {
+    if (typeof version !== "string" || !version.trim()) {
+      throw new Error(`Unattended execution ${name} is required`);
+    }
+  }
+  if (!value.scope || typeof value.scope !== "object" || Array.isArray(value.scope)) {
+    throw new Error("Unattended execution scope must be an object");
+  }
+  try {
+    const scope = JSON.parse(JSON.stringify(value.scope)) as unknown;
+    if (!scope || typeof scope !== "object" || Array.isArray(scope)) {
+      throw new Error("scope changed shape during serialization");
+    }
+    return Object.freeze({
+      taskId: value.taskId,
+      requirementVersion: value.requirementVersion,
+      authorizationVersion: value.authorizationVersion,
+      scope: scope as Readonly<Record<string, unknown>>,
+    });
+  } catch (error) {
+    throw new Error("Unattended execution scope must be JSON-serializable", { cause: error });
+  }
+}

package/src/telemetry/coordinator.ts

@@ -5,7 +5,7 @@ import { TelemetryRecorder } from "./recorder";
 import { RuntimeTelemetry } from "./runtime-telemetry";
 import type { AgentTelemetryBinding } from "./contract";
 import type { PiGenerationLifecycleEvent } from "../models";
-import type { TemporaryAgentLifecycleEvent } from "../tools/temporary-agent/coordinator";
+import type { TemporaryAgentLifecycleEvent } from "../tools/subagent/temporary/coordinator";
 
 const TELEMETRY_COLD_BUFFER_LIMIT = 1_000;
 

package/src/telemetry/subagent-lifecycle.ts

@@ -2,7 +2,7 @@ import type {
   RuntimeEventConfirmation,
   RuntimeLifecycleFact,
   RuntimeSubagentUsageEvent,
-} from "../tools/subagent-authority";
+} from "../tools/subagent/authority";
 
 export interface RuntimeLifecycleSink {
   save(

package/src/telemetry/turn-events.ts

@@ -7,7 +7,7 @@ import type {
   RuntimeTurnEventsPort,
 } from "../config/ports";
 import type { StoredSubmission } from "../submission/repository";
-import { decodeSubagentCompletion, isZeroSubagentUsage, subagentTerminalStatus, type RuntimeSubagentRunMetadata } from "../tools/subagent-runtime";
+import { decodeSubagentCompletion, isZeroSubagentUsage, subagentTerminalStatus, type RuntimeSubagentRunMetadata } from "../tools/subagent/runtime";
 import type { RuntimeTelemetryCoordinator } from "./coordinator";
 import { summarizeModelUsage } from "./model-usage";
 import type { RuntimeEventOutboxRepository } from "./runtime-event-repository";

package/src/tools/README.md

@@ -0,0 +1,44 @@
+# Runtime Tools
+
+工具按功能归组。根 `index.ts` 只维护包内统一导出；功能目录的 `index.ts` 定义或组合该功能的 Pi Tool。
+
+| 目录 | 职责 |
+| --- | --- |
+| `runtime/` | 公共工具契约、Harness 编译、执行决策、审批与客户端交互结算 |
+| `adapters/` | AI SDK ↔ Pi 转换，以及外部工具声明到 Pi Candidate 的适配 |
+| `codemode/` | `execute` 和 `browser_execute` 的 Pi Tool 定义、Cloudflare 执行适配、Workspace Connector |
+| `assistant/` | 用户问答、计划、后续建议、记忆与时间工具 |
+| `workspace/` | 持久 Workspace 文件操作、写入串行化与版本操作工具 |
+| `sandbox/` | 临时 Linux Sandbox 的命令、进程和显式文件发布工具 |
+| `skill/` | Skill 工具组合、资源读取与复制、脚本运行与输出投影 |
+| `subagent/` | 子 Agent 工具、权限、运行记录、类型和临时 Agent 协调 |
+| `schedule/` | 定时任务的 Pi Tool 定义 |
+| `web/` | 网页获取与 Provider-native 搜索 |
+| `mcp/` | MCP Tool 接入及使用 MCP Session 的 Connector Gateway |
+| `extension/` | 已加载 Extension 的发现工具；Extension 装载仍归 `context/extension/` |
+
+## Code Mode
+
+```text
+codemode/index.ts                 Pi Tool 定义、执行级别与调用截止
+        |
+        v
+RuntimeCodeExecutionPort         内部执行接口
+        |
+        v
+codemode/adapter.ts              Cloudflare 执行器组装、描述与结果适配
+        |
+        +-- workspace-connector.ts   state.* 方法、发现与校验
+        +-- ../adapters/pi-to-ai.ts  现有 Pi 工具到 Cloudflare ToolSet 的转换
+```
+
+`pi-to-ai.ts` 也被 Skill 脚本执行使用，因此放在共用 `adapters/` 中。工具声明仍以 Pi 为唯一事实源。
+
+## 修改位置
+
+- 修改某个工具：进入对应功能目录，测试与实现放在一起。
+- 修改所有工具共用的执行策略：进入 `runtime/`，不要复制到每个工具。
+- 修改外部协议转换：进入 `adapters/`，不新增另一份工具定义。
+- 小功能可以只有 `index.ts`，不强制拆分 Adapter、Service 或 Repository。
+- `runtime/result.ts` 只共享结果包装与进度报告；`assistant/candidate.ts` 只共享助手工具已有的元数据默认值。
+- 包的公共导出名及 `@springbrand/agent-runtime/declared-tool` 子路径保持不变。内部路径变更需要同步 Vitest 测试池配置。