@springbrand/agent-runtime 0.3.0-alpha.8 → 0.3.0-alpha.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/agent-runtime",
-  "version": "0.3.0-alpha.8",
+  "version": "0.3.0-alpha.9",
   "type": "module",
   "files": [
     "src",
@@ -13,7 +13,7 @@
     ".": "./src/index.ts",
     "./adapter/cloudflare": "./src/adapter/cloudflare/index.ts",
     "./contracts": "./src/config/public-contracts.ts",
-    "./declared-tool": "./src/tools/declared.ts",
+    "./declared-tool": "./src/tools/adapters/declared.ts",
     "./models": "./src/lib/model-catalog.ts"
   },
   "dependencies": {

package/src/adapter/cloudflare/subagent/definition.ts

@@ -11,8 +11,8 @@ import type { HarnessEvent } from "@earendil-works/pi-agent-core";
 import type { UIMessageChunk } from "ai";
 import {
   AGENT_TYPES,
-} from "../../../tools/subagent-types/registry";
-import type { AgentType } from "../../../tools/subagent-types/contract";
+} from "../../../tools/subagent/types/registry";
+import type { AgentType } from "../../../tools/subagent/types/contract";
 import type {
   RuntimeProviderPort,
   WorkspacePort,
@@ -30,8 +30,8 @@ import {
   decodeSubagentCompletion,
   emptySubagentUsage,
   encodeSubagentCompletion,
-} from "../../../tools/subagent-runtime";
-import type { RuntimeSubagentUsageMetrics } from "../../../tools/subagent-authority";
+} from "../../../tools/subagent/runtime";
+import type { RuntimeSubagentUsageMetrics } from "../../../tools/subagent/authority";
 import { createCloudflareSubAgentTools } from "./tools";
 
 type RunStatus =

package/src/adapter/cloudflare/subagent/runner.ts

@@ -12,7 +12,7 @@ import {
 import type { Api, AssistantMessage, Model, Models } from "@earendil-works/pi-ai";
 import { z } from "zod";
 import { assembleSubagentPrompt } from "../../../lib/prompt";
-import type { AgentType } from "../../../tools/subagent-types/contract";
+import type { AgentType } from "../../../tools/subagent/types/contract";
 import { structuredOutputStream } from "../../../models";
 import {
   openSessionHarness,

package/src/adapter/cloudflare/subagent/tools.ts

@@ -15,13 +15,13 @@ import type {
 } from "@earendil-works/pi-agent-core";
 import { Type } from "@earendil-works/pi-ai";
 import type { WorkspacePort } from "../../../config/ports";
-import type { AgentType } from "../../../tools/subagent-types/contract";
+import type { AgentType } from "../../../tools/subagent/types/contract";
 import {
   compileHarnessTools,
   type CompileHarnessToolsOptions,
   type PiToolCandidate,
 } from "../../../tools";
-import { workspacePiToolCandidates } from "../../../tools/workspace-sandbox";
+import { workspacePiToolCandidates } from "../../../tools/workspace";
 
 const READONLY_WORKSPACE_TOOLS = new Set([
   "read",

package/src/adapter/cloudflare/universal-agent/preparation.ts

@@ -9,16 +9,16 @@ import type {
   RuntimeSubagentPort,
   WorkspacePort,
 } from "../../../config/ports";
-import { decodeSubagentCompletion } from "../../../tools/subagent-runtime";
+import { decodeSubagentCompletion } from "../../../tools/subagent/runtime";
 import type { RuntimeDegradation } from "../../../config/degradation";
 import type { RuntimeMemoryProfile } from "../../../config/profile";
-import { AGENT_TYPES } from "../../../tools/subagent-types/registry";
+import { AGENT_TYPES } from "../../../tools/subagent/types/registry";
 import type { RuntimeAgentConfigContext } from "../../../config/agent-context";
 import {
   createBrowserExecutionFactory,
   createWorkspaceCodeExecutionFactory,
   type RuntimeBrowserBinding,
-} from "../../../tools/core-host";
+} from "../../../tools/codemode/adapter";
 import {
   createCloudflareSandboxAdapter,
   type SandboxAdmission,

package/src/adapter/cloudflare/universal-agent/tools.ts

@@ -7,15 +7,13 @@ import type {
 } from "../../../config/ports";
 import type { RuntimeDegradation } from "../../../config/degradation";
 import type { RuntimeMemoryProfile } from "../../../config/profile";
-import type { WorkspaceRevisionRestorePort } from "../../../tools/workspace-versioning";
+import type { WorkspaceRevisionRestorePort } from "../../../tools/workspace/versioning";
 import { schedulePiToolCandidates } from "../../../tools/schedule";
-import { workspaceRevisionPiToolCandidate } from "../../../tools/workspace-revision";
-import {
-  sandboxPiToolCandidates,
-} from "../../../tools/workspace-sandbox";
+import { workspaceRevisionPiToolCandidate } from "../../../tools/workspace/revision";
+import { sandboxPiToolCandidates } from "../../../tools/sandbox";
 import type { RuntimeCodeExecutionFactory } from "../../../config/ports";
 import type { ToolAssemblyResult } from "../../../config/definition";
-import type { PiToolCandidate } from "../../../tools/compiler";
+import type { PiToolCandidate } from "../../../tools/runtime/contracts";
 
 export function assembleUniversalAgentTools(options: {
   hostTools?: readonly PiToolCandidate[];

package/src/adapter/cloudflare/workspace/version-control.ts

@@ -5,7 +5,7 @@ import {
   type WorkspaceRevision,
   type WorkspaceRevisionManifest,
   type WorkspaceVersionPort,
-} from "../../../tools/workspace-versioning";
+} from "../../../tools/workspace/versioning";
 import { createWorkspaceGitFs } from "./git-fs";
 
 const PAGE_SIZE = 256;

package/src/config/agent-context.ts

@@ -8,7 +8,7 @@ import type { RuntimeConfigUpdateResult } from "./runtime-config";
 import type {
   TemporaryAgentRequest,
   TemporaryAgentRunContext,
-} from "../tools/temporary-agent/core";
+} from "../tools/subagent/temporary/core";
 
 /**
  * 描述 Agent 寻址路径中的一级父子节点。

package/src/config/assembler.ts

@@ -37,10 +37,7 @@ import {
   type PiRuntimeAssembly,
 } from "./assembly-snapshot";
 import type { AgentTool } from "@earendil-works/pi-agent-core";
-import type {
-  PiToolCandidate,
-  ToolExposureMode,
-} from "../tools/compiler";
+import type { PiToolCandidate, ToolExposureMode } from "../tools/runtime/contracts";
 import type {
   AssembleRuntimeSnapshotInput,
   RuntimeSettings,
@@ -51,17 +48,11 @@ import type {
   RuntimeToolSurfacePolicy,
 } from "./definition";
 import type { RuntimeCodeExecutionFactory } from "./ports";
-import {
-  basePiToolCandidates,
-  memoryPiToolCandidate,
-} from "../tools/base";
-import {
-  BROWSER_EXECUTE_TOOL_NAME,
-  browserExecutionPiToolCandidate,
-  codeExecutionPiToolCandidate,
-} from "../tools/core";
+import { basePiToolCandidates } from "../tools/assistant";
+import { memoryPiToolCandidate } from "../tools/assistant/memory";
+import { BROWSER_EXECUTE_TOOL_NAME, browserExecutionPiToolCandidate, codeExecutionPiToolCandidate } from "../tools/codemode";
 import { skillPiToolCandidates } from "../tools/skill";
-import { createWebSearch, WEB_SEARCH_MODEL } from "../tools/web-search";
+import { createWebSearch, WEB_SEARCH_MODEL } from "../tools/web/search";
 import { subagentPiToolCandidates } from "../tools/subagent";
 import { resolvePiModel } from "../models";
 import {
@@ -305,17 +296,12 @@ async function createToolSurface(
             typeof candidate.tool.execute === "function",
         );
         const codeExecutionCandidates = Object.freeze([...mergeable]);
-        const codeExecutionToolNames = new Set(
-          codeExecutionCandidates.map(({ tool }) => tool.name),
-        );
         const codeExecution = input.codeExecution.create(
           codeExecutionCandidates,
         );
-        const topLevelOnly = directVisible.filter(
-          ({ tool }) => !codeExecutionToolNames.has(tool.name),
-        );
+        const directToolNames = new Set(directVisible.map(({ tool }) => tool.name));
         const routeList = (deferred: boolean) => {
-          const matches = topLevelOnly.filter((candidate) =>
+          const matches = directVisible.filter((candidate) =>
             (defersTool?.(candidate.tool.name) === true) === deferred
           );
           return matches.length > 0
@@ -327,8 +313,9 @@ async function createToolSurface(
         };
         const routeGuidance = [
           "## Tool routing",
-          "Top-level deferred Tools are not callable through `tools.*`. Use Provider Tool Search with their exact name, then call them directly.",
+          "For top-level deferred Tools, use Provider Tool Search with their exact name, then call them directly.",
           "Top-level immediate Tools are already available outside execute; call them directly.",
+          "Only Code Mode Tools listed below are callable inside execute through tools.<name>. Tools marked execute-only are not registered as top-level Tools.",
           "",
           "## Top-level deferred Tools",
           routeList(true),
@@ -336,21 +323,20 @@ async function createToolSurface(
           "## Top-level immediate Tools",
           routeList(false),
           "",
+          "## Code Mode Tools",
+          codeExecutionCandidates.length > 0
+            ? codeExecutionCandidates.map(({ tool }) =>
+                `- \`tools.${tool.name}\` — ${directToolNames.has(tool.name) ? "also available as a top-level Tool" : "execute-only"}`
+              ).join("\n")
+            : "- None.",
+          "",
         ].join("\n");
-        const materializeGuidance = codeExecutionCandidates.some(
-            ({ tool }) => tool.name === "materialize_skill_resource",
-          )
-          ? "Skill resource copying is available only inside execute through " +
-            "`tools.materialize_skill_resource({ name, path, destination })`; " +
-            "no Direct Tool is registered for it. " +
-            "Copy multiple resources sequentially in one execute so durable replay preserves call order.\n\n"
-          : "";
         return Object.freeze({
           candidates: Object.freeze([
             classify(codeExecutionPiToolCandidate({
               ...codeExecution,
               description:
-                routeGuidance + "\n" + materializeGuidance + codeExecution.description,
+                routeGuidance + "\n" + codeExecution.description,
             })),
             ...directVisible.map(classify),
           ]),

package/src/config/assembly-snapshot.ts

@@ -18,7 +18,7 @@ import type {
 import type { RuntimeProviderPort } from "./ports";
 import { assembleSystemPrompt } from "../lib/prompt";
 import { resolvePiModel } from "../models";
-import type { PiToolCandidate } from "../tools/compiler";
+import type { PiToolCandidate } from "../tools/runtime/contracts";
 
 /**
  * 收集完动态 Extension/MCP 候选后，一次性生成最终 Tool Surface。

package/src/config/definition.ts

@@ -17,7 +17,7 @@ import type {
 } from "./profile";
 import type { RuntimeExtensionConfig } from "../context/extension/contracts";
 import type { RuntimeDegradation } from "./degradation";
-import type { PiToolCandidate } from "../tools/compiler";
+import type { PiToolCandidate } from "../tools/runtime/contracts";
 import type {
   RuntimeAgentContext,
   RuntimeAgentPlanningContext,

package/src/config/model-guidance.ts

@@ -1,5 +1,5 @@
 import type { Context } from "@earendil-works/pi-ai";
-import type { PiToolCandidate } from "../tools/compiler";
+import type { PiToolCandidate } from "../tools/runtime/contracts";
 
 /** Only descriptions and guidance may vary inside a pinned Submission. */
 export async function refreshModelGuidance(

package/src/config/ports.ts

@@ -5,13 +5,13 @@ import type { ScheduleSpec, RuntimeSchedulePreparation } from "../submission/con
 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 "../tools/compiler";
+import type { PiToolCandidate } from "../tools/runtime/contracts";
 import type {
   RuntimeEventConfirmation,
   RuntimeLifecycleFact,
   RuntimeSubagentUsageEvent,
   RuntimeSubagentUsageMetrics,
-} from "../tools/subagent-authority";
+} from "../tools/subagent/authority";
 export type { RuntimeModelInputModality } from "./profile";
 export type {
   RuntimeEventConfirmation,
@@ -22,7 +22,7 @@ export type {
   RuntimeSubmissionAdmissionHook,
   RuntimeSubmissionAdmissionInput,
   RuntimeSubmissionAdmissionResult,
-} from "../tools/subagent-authority";
+} from "../tools/subagent/authority";
 
 // #region Workspace 端口
 

package/src/config/public-contracts.ts

@@ -17,7 +17,7 @@ export * from "../conversation/message";
 export * from "../submission/contracts";
 export * from "../conversation/state";
 export * from "../lib/execution-level";
-export type { WorkspaceRevision, WorkspaceRevisionManifest } from "../tools/workspace-versioning";
+export type { WorkspaceRevision, WorkspaceRevisionManifest } from "../tools/workspace/versioning";
 export type {
   RuntimeEventConfirmation,
   RuntimeLifecycleFact,
@@ -27,4 +27,4 @@ export type {
   RuntimeSubmissionAdmissionHook,
   RuntimeSubmissionAdmissionInput,
   RuntimeSubmissionAdmissionResult,
-} from "../tools/subagent-authority";
+} from "../tools/subagent/authority";

package/src/context/extension/assembly.ts

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

package/src/context/memory/budget/gate.ts

@@ -29,7 +29,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;

package/src/conversation/state.ts

@@ -1,6 +1,6 @@
 import type { ApprovalReceipt } from "../submission/contracts";
 import type { StoredSubmission } from "../submission/repository";
-import type { PendingApprovalSummary } from "../tools/approval/repository";
+import type { PendingApprovalSummary } from "../tools/runtime/approval/repository";
 import type { PiCanonicalUserInput } from "./message/contract";
 
 export type RuntimeLoadPhase = "config" | "assembly" | "mcp" | "pi";

package/src/index.ts

@@ -51,7 +51,7 @@ export type { RuntimeAssemblyView } from "./config/assembly-view";
 export * from "./adapter/cloudflare/define-agent";
 export type { ToolInteractionResponsePreparation } from "./adapter/cloudflare/agent";
 export * from "./conversation/state";
-export * from "./tools/workspace-versioning";
+export * from "./tools/workspace/versioning";
 export * from "./lib/execution-level";
 export type {
   RuntimeAssemblyInput,
@@ -84,10 +84,10 @@ export type {
 } from "./lib/host-actions";
 export {
   AGENT_TYPES,
-} from "./tools/subagent-types/registry";
+} from "./tools/subagent/types/registry";
 export type {
   AgentType,
-} from "./tools/subagent-types/contract";
+} from "./tools/subagent/types/contract";
 export type {
   PiToolCandidate,
   ToolExposureMode,
@@ -129,15 +129,15 @@ export type {
   TemporaryAgentLaunch,
   TemporaryAgentRequest,
   TemporaryAgentRunContext,
-} from "./tools/temporary-agent/core";
-export { TEMPORARY_AGENT_LAUNCH_KEY } from "./tools/temporary-agent/core";
+} from "./tools/subagent/temporary/core";
+export { TEMPORARY_AGENT_LAUNCH_KEY } from "./tools/subagent/temporary/core";
 export {
   temporaryAgentExtensionIsSafe,
   temporaryAgentToolAllowed,
-} from "./tools/temporary-agent/runner";
+} from "./tools/subagent/temporary/runner";
 export {
   createTemporaryAgentWorkspace,
-} from "./tools/temporary-agent/workspace";
+} from "./tools/subagent/temporary/workspace";
 export {
   createPiModels,
   modelRequestUrl,

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 " +

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

@@ -716,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")
@@ -797,9 +811,6 @@ export function migrateLegacyPiSession(
         const knownSubmissions = new Set(
           submissions.map((row) => row.submission_id),
         );
-        const submissionStatuses = new Map(
-          submissions.map((row) => [row.submission_id, row.status]),
-        );
         for (const submission of submissions) {
           if (submission.status !== "pending" || !submission.queued_input_json)
             continue;
@@ -862,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);
+                }
               }
             }
           }
@@ -875,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);
+                }
               }
             }
           }
@@ -944,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/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/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 {
   /** 声明方自己的工具名，用于结果详情与诊断，不一定是模型看到的名字。 */