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

package/src/models/provider-streams.ts

@@ -0,0 +1,45 @@
+import type {
+  Api,
+  Model,
+  ProviderEnv,
+  ProviderStreams,
+} from "@earendil-works/pi-ai";
+
+/**
+ * ProviderStreams 是普通对象，不是 class。完整适配先 spread 底层全部方法，再覆盖需要装饰的入口。
+ * 只手写 stream / streamSimple 会丢掉 Pi 后续挂上的 fetchDeferred / cancelDeferred。
+ */
+export function overlayProviderStreams(
+  base: ProviderStreams,
+  overlay: Partial<ProviderStreams>,
+): ProviderStreams {
+  return { ...base, ...overlay };
+}
+
+/**
+ * 在保留其余方法的前提下，把每个已知的 model 入口改写到 remap 后的模型。
+ * 未知的未来方法仍通过 spread 透传，避免再出现白名单丢方法。
+ */
+export function remapProviderStreamModels(
+  streams: ProviderStreams,
+  remap: (model: Model<Api>, env: ProviderEnv | undefined) => Model<Api>,
+): ProviderStreams {
+  return overlayProviderStreams(streams, {
+    stream: (model, context, options) =>
+      streams.stream(remap(model, options?.env), context, options),
+    streamSimple: (model, context, options) =>
+      streams.streamSimple(remap(model, options?.env), context, options),
+    ...(streams.fetchDeferred
+      ? {
+          fetchDeferred: (model, handle, options) =>
+            streams.fetchDeferred!(remap(model, options?.env), handle, options),
+        }
+      : {}),
+    ...(streams.cancelDeferred
+      ? {
+          cancelDeferred: (model, handle, options) =>
+            streams.cancelDeferred!(remap(model, options?.env), handle, options),
+        }
+      : {}),
+  });
+}

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);
@@ -400,7 +436,6 @@ function assertSameToolResult(
     "content",
     "details",
     "usage",
-    "addedToolNames",
     "isError",
   ] as const) {
     if (!isEqual(left[key], right[key]))
@@ -420,11 +455,8 @@ function legacyToolResultMessage(input: {
     toolCallId: input.toolCallId,
     toolName: input.toolName,
     content: input.result.content ?? [],
-    details: input.result.details,
+    details: input.result.details as JsonValue | undefined,
     ...(input.result.usage ? { usage: input.result.usage } : {}),
-    ...(input.result.addedToolNames?.length
-      ? { addedToolNames: input.result.addedToolNames }
-      : {}),
     isError: input.isError,
     timestamp: input.timestamp,
   };
@@ -680,6 +712,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 +855,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 +869,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 +886,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 +959,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 测试池配置。

package/src/tools/{ai-adapter.ts → adapters/ai-to-pi.ts}

@@ -1,13 +1,10 @@
 // 本文件把 ai-sdk Tool 转成 Pi AgentTool。
 // `@cloudflare/think`、Agents Skills 和 Workspace 等上游工厂生成 ai-sdk Tool 时调用这个边界。
-// 转换只保留在这里，才能让后续治理和结算始终看到同一种 AgentTool 结果；核心术语见 `../../index.ts` 入口说明。
+// 转换只保留在这里，才能让后续治理和结算始终看到同一种 AgentTool 结果；核心术语见 `src/index.ts` 入口说明。
 
-import type {
-  AgentTool,
-  AgentToolResult,
-} from "@earendil-works/pi-agent-core";
+import type { AgentTool, AgentToolResult } from "@earendil-works/pi-agent-core";
 import { asSchema, type Tool as AiTool } from "ai";
-import { serializeOutput } from "../lib/artifacts";
+import { serializeOutput } from "../../lib/artifacts";
 
 /** 控制一个 ai-sdk Tool 如何投影到 Pi AgentTool。 */
 export interface AiToolAdapterOptions {
@@ -141,9 +138,9 @@ export function aiToolToPi(
         .toModelOutput;
       const content = typeof toModelOutput === "function"
         ? modelContent(await (toModelOutput as (input: {
-            input: unknown;
-            output: unknown;
-          }) => unknown)({ input: params, output: raw }))
+          input: unknown;
+          output: unknown;
+        }) => unknown)({ input: params, output: raw }))
         : null;
       return {
         content: content ?? [{

package/src/tools/{declared.ts → adapters/declared.ts}

@@ -1,5 +1,5 @@
 import type { AgentTool, AgentToolResult } from "@earendil-works/pi-agent-core";
-import type { PiToolCandidate } from "./compiler";
+import type { PiToolCandidate } from "../runtime/contracts";
 
 /**
  * 一个由 Runtime 之外声明、由 Runtime 之外执行的工具。
@@ -15,7 +15,7 @@ import type { PiToolCandidate } from "./compiler";
  * 本模块只引入类型，因此可经 `@springbrand/agent-runtime/declared-tool` 单独导入：
  * 声明方在 Node 下也能装配自己的工具，不必为此加载 Workers 运行时。
  *
- * `Pi`、`Tool Candidate` 与 `Runtime` 等核心术语见 `../../index.ts`。
+ * `Pi`、`Tool Candidate` 与 `Runtime` 等核心术语见 `src/index.ts`。
  */
 export interface PiDeclaredTool {
   /** 声明方自己的工具名，用于结果详情与诊断，不一定是模型看到的名字。 */
@@ -49,6 +49,7 @@ export interface PiDeclaredToolPolicy<Reply = unknown> {
   readonly modelName: string;
   readonly requiredExecutionLevel: PiToolCandidate["requiredExecutionLevel"];
   readonly requiredExecutionLevelForInput?: PiToolCandidate["requiredExecutionLevelForInput"];
+  readonly unattendedExecution?: PiToolCandidate["unattendedExecution"];
   readonly exposureMode?: PiToolCandidate["exposureMode"];
   readonly retry?: PiToolCandidate["retry"];
   readonly source?: PiToolCandidate["source"];
@@ -117,6 +118,9 @@ export function createPiDeclaredToolCandidate<Reply = unknown>(
     ...(policy.requiredExecutionLevelForInput
       ? { requiredExecutionLevelForInput: policy.requiredExecutionLevelForInput }
       : {}),
+    ...(policy.unattendedExecution
+      ? { unattendedExecution: policy.unattendedExecution }
+      : {}),
     ...(policy.exposureMode ? { exposureMode: policy.exposureMode } : {}),
     ...(policy.retry ? { retry: policy.retry } : {}),
     ...(policy.source ? { source: policy.source } : {}),