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

package/src/submission/repository.ts

@@ -1,5 +1,6 @@
 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。
@@ -56,6 +57,7 @@ export interface StoredSubmission {
   regenerateMessageId: string | null;
   runId: string | null;
   origin: SubmissionOrigin;
+  scheduledMaxExecutionLevel: ExecutionLevel | null;
   unattendedExecutionGrant: RuntimeUnattendedExecutionGrant | null;
   unattendedFailure: string | null;
   retryable?: boolean;
@@ -82,6 +84,7 @@ export interface NewSubmission {
   regenerateMessageId?: string | null;
   runId?: string | null;
   origin?: SubmissionOrigin;
+  scheduledMaxExecutionLevel?: ExecutionLevel;
   unattendedExecutionGrant?: RuntimeUnattendedExecutionGrant;
 }
 
@@ -105,6 +108,7 @@ type SubmissionRow = {
   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;
@@ -136,6 +140,7 @@ function mapRow(row: SubmissionRow): StoredSubmission {
     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,
@@ -173,6 +178,7 @@ export class SubmissionRepository {
              regenerate_message_id,
              run_id,
              origin,
+             scheduled_max_execution_level,
              admission_retryable,
              unattended_execution_grant_json,
              unattended_failure
@@ -276,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, origin, unattended_execution_grant_json
+        run_id, origin, scheduled_max_execution_level, unattended_execution_grant_json
       ) VALUES (
         ${s.submissionId},
         ${s.requestId},
@@ -294,6 +300,7 @@ export class SubmissionRepository {
         ${s.regenerateMessageId ?? null},
         ${s.runId ?? s.submissionId},
         ${s.origin ?? "user"},
+        ${s.scheduledMaxExecutionLevel ?? null},
         ${s.unattendedExecutionGrant
           ? JSON.stringify(s.unattendedExecutionGrant)
           : null}

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 {
   /** 声明方自己的工具名，用于结果详情与诊断，不一定是模型看到的名字。 */

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

@@ -1,7 +1,7 @@
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import { validateToolArguments } from "@earendil-works/pi-ai";
-import { jsonSchema, tool as aiTool, type ToolSet } from "ai";
-import type { PiToolCandidate } from "./compiler";
+import { tool as aiTool, jsonSchema, type ToolSet } from "ai";
+import type { PiToolCandidate } from "../runtime/contracts";
 
 interface NestedToolOptions {
   readonly fallbackToolCallId?: (name: string) => string;

package/src/tools/assistant/ask-user.ts

@@ -0,0 +1,317 @@
+import { StringEnum, Type, type Static } from "@earendil-works/pi-ai";
+import { modelAttachmentText } from "../../conversation/message/conversion";
+import type { PiToolCandidate } from "../runtime/contracts";
+import { candidate } from "./candidate";
+
+const askUserResponseTypes = [
+  "text",
+  "single_select",
+  "multi_select",
+  "attachment",
+] as const;
+
+const askUserQuestion = Type.Object({
+  question: Type.String({
+    minLength: 1,
+    description: "The question or file request to put to the user.",
+  }),
+  responseType: StringEnum(askUserResponseTypes, {
+    description:
+      "Required response UI: text, single_select, multi_select, or attachment.",
+  }),
+  options: Type.Optional(Type.Array(Type.String({ minLength: 1 }), {
+    minItems: 2,
+    maxItems: 6,
+    uniqueItems: true,
+    description:
+      "Required only for single_select or multi_select. Provide 2-6 distinct options; omit for text and attachment.",
+  })),
+  allowCustom: Type.Optional(Type.Boolean({
+    description:
+      "For single_select or multi_select, whether the user may also add free text. Defaults to false.",
+  })),
+  required: Type.Optional(Type.Boolean({
+    default: false,
+    description:
+      "Whether the user must answer this question to submit. Defaults to false.",
+  })),
+}, { additionalProperties: false });
+
+const askUserParameters = Type.Object({
+  questions: Type.Array(askUserQuestion, {
+    minItems: 1,
+    maxItems: 10,
+    description:
+      "All user decisions and files needed to continue. Every question requires responseType. At most one question may use attachment.",
+  }),
+}, { additionalProperties: false });
+
+/**
+ * `ask_user` 的客户端响应体。
+ *
+ * `answers` 与 Tool 输入的 `questions` 按下标一一对应。
+ * 刻意用结构化数组而不是拼好的字符串 —— 选项本身可能含分隔符，拼了再拆是有损的。
+ */
+type AskUserInput = Static<typeof askUserParameters>;
+
+type AskUserFile = {
+  readonly type: "file";
+  readonly url: string;
+  readonly filename: string;
+  readonly mediaType: string;
+  readonly providerMetadata?: unknown;
+};
+
+type AskUserResponse = {
+  readonly answers: ReadonlyArray<{
+    readonly selections: readonly string[];
+    readonly text: string;
+    readonly attachments: readonly AskUserFile[];
+  }>;
+};
+
+function recordOf(value: unknown): Record<string, unknown> | null {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null;
+}
+
+function questionsOf(value: unknown): AskUserInput["questions"] | null {
+  const questions = recordOf(value)?.questions;
+  if (!Array.isArray(questions) || questions.length < 1 || questions.length > 10) {
+    return null;
+  }
+  const normalized: AskUserInput["questions"] = [];
+  let attachmentQuestions = 0;
+  for (const value of questions) {
+    const question = recordOf(value);
+    if (!question || typeof question.question !== "string" || !question.question) {
+      return null;
+    }
+    if (Object.keys(question).some((key) =>
+      key !== "question" && key !== "responseType" && key !== "options" &&
+      key !== "allowCustom" && key !== "required"
+    )) return null;
+    if (
+      question.required !== undefined && typeof question.required !== "boolean"
+    ) return null;
+    const required = question.required === true;
+    let responseType = question.responseType;
+    if (
+      typeof responseType !== "string" ||
+      !askUserResponseTypes.includes(
+        responseType as typeof askUserResponseTypes[number],
+      )
+    ) {
+      return null;
+    }
+    const normalizedQuestion = {
+      question: question.question,
+      responseType: responseType as typeof askUserResponseTypes[number],
+      required,
+    };
+    if (responseType === "attachment") {
+      attachmentQuestions += 1;
+      if (
+        attachmentQuestions > 1 ||
+        question.options !== undefined ||
+        question.allowCustom !== undefined
+      ) return null;
+      normalized.push(normalizedQuestion);
+      continue;
+    }
+    if (responseType === "text") {
+      if (
+        question.options !== undefined ||
+        question.allowCustom !== undefined
+      ) {
+        return null;
+      }
+      normalized.push(normalizedQuestion);
+      continue;
+    }
+    if (
+      !Array.isArray(question.options) ||
+      question.options.length < 2 ||
+      question.options.length > 6 ||
+      !question.options.every((option) =>
+        typeof option === "string" && option.length > 0
+      ) ||
+      new Set(question.options).size !== question.options.length ||
+      (question.allowCustom !== undefined &&
+        typeof question.allowCustom !== "boolean")
+    ) return null;
+    normalized.push({
+      ...normalizedQuestion,
+      options: question.options,
+      ...(question.allowCustom === undefined
+        ? {}
+        : { allowCustom: question.allowCustom }),
+    });
+  }
+  return normalized;
+}
+
+function prepareAskUserArguments(input: unknown): AskUserInput {
+  const value = recordOf(input);
+  if (!value) throw new Error("Invalid ask_user questions");
+  let questions = value.questions;
+  if (typeof questions === "string") {
+    try {
+      questions = JSON.parse(questions);
+    } catch {
+      throw new Error("Invalid ask_user questions");
+    }
+  }
+  const prepared = { ...value, questions };
+  if (!questionsOf(prepared)) throw new Error("Invalid ask_user questions");
+  return prepared as AskUserInput;
+}
+
+// 手写校验而不是拉 TypeBox compiler：这里只需要判真假，
+// 且校验位于 Worker 响应信任边界，不应为每次回答编译 schema。
+function isAskUserResponse(input: unknown, value: unknown): boolean {
+  const questions = questionsOf(input);
+  const answers = recordOf(value)?.answers;
+  if (!questions || !Array.isArray(answers) || answers.length !== questions.length) {
+    return false;
+  }
+
+  return questions.every((question, index) => {
+    const answer = recordOf(answers[index]);
+    if (
+      !answer ||
+      !Array.isArray(answer.selections) ||
+      typeof answer.text !== "string" ||
+      !Array.isArray(answer.attachments) ||
+      Object.keys(answer).some((key) =>
+        key !== "selections" && key !== "text" && key !== "attachments"
+      )
+    ) return false;
+    if (!answer.selections.every((item) => typeof item === "string")) {
+      return false;
+    }
+    if (answer.text.length > 2_000) return false;
+    if (!answer.attachments.every((value) => {
+      const file = recordOf(value);
+      return Boolean(
+        file &&
+        file.type === "file" &&
+        typeof file.url === "string" && file.url.length > 0 &&
+        typeof file.filename === "string" && file.filename.length > 0 &&
+        typeof file.mediaType === "string" && file.mediaType.length > 0 &&
+        (file.providerMetadata === undefined || recordOf(file.providerMetadata)) &&
+        Object.keys(file).every((key) =>
+          key === "type" || key === "url" || key === "filename" ||
+          key === "mediaType" || key === "providerMetadata"
+        )
+      );
+    })) return false;
+
+    if (
+      answer.selections.length === 0 &&
+      !answer.text.trim() &&
+      answer.attachments.length === 0
+    ) return question.required !== true;
+
+    if (question.responseType === "attachment") {
+      return answer.selections.length === 0 && !answer.text &&
+        answer.attachments.length >= 1 && answer.attachments.length <= 8;
+    }
+    if (answer.attachments.length > 0) return false;
+    if (question.responseType === "text") {
+      return answer.selections.length === 0 && answer.text.trim().length > 0;
+    }
+
+    const options = question.options ?? [];
+    if (answer.selections.some((selection) => !options.includes(selection))) {
+      return false;
+    }
+    if (new Set(answer.selections).size !== answer.selections.length) return false;
+    if (
+      question.responseType === "single_select" &&
+      answer.selections.length > 1
+    ) return false;
+    if (!question.allowCustom && answer.text.trim()) return false;
+    return answer.selections.length > 0 || answer.text.trim().length > 0;
+  });
+}
+
+export function askUserPiToolCandidate(): PiToolCandidate {
+  return {
+    ...candidate({
+      name: "ask_user",
+      label: "Ask user",
+      description:
+        "Ask all 1-10 user questions needed to continue in one call. Required input for every question: question and responseType; required defaults to false, so set it to true only when progress cannot continue without an answer. Use responseType text for free text, single_select or multi_select with 2-6 distinct options for choices, and attachment for files. At most one attachment question is allowed and it accepts multiple files. Do not add file-specific fields such as accept or tell the user to use the normal chat composer. The answers return as this tool's result, so continue the same turn after calling it.",
+      parameters: askUserParameters,
+      prepareArguments: prepareAskUserArguments,
+      // 永远不会被调用：执行链在 interaction 闸就 park 住了。留一个失败关闭的
+      // 实现，是为了万一哪次改动绕过了那道闸，能立刻炸出来而不是静默返回空答案。
+      async execute() {
+        throw new Error(
+          "ask_user is client-settled and must not execute on the server",
+        );
+      },
+    }),
+    interaction: {
+      validateResponse: isAskUserResponse,
+      settle: (input, response) => {
+        const questions = questionsOf(input)!;
+        const responseAnswers = (response as AskUserResponse).answers;
+        const answers = questions.map((question, index) => {
+          const answer = responseAnswers[index]!;
+          return {
+            question: question.question,
+            selections: [...answer.selections],
+            text: answer.text.trim(),
+            attachments: answer.attachments.map((file) => {
+              const springbrand = recordOf(
+                recordOf(file.providerMetadata)?.springbrand,
+              );
+              return {
+                name: file.filename,
+                mediaType: file.mediaType,
+                size: typeof springbrand?.size === "number"
+                  ? springbrand.size
+                  : 0,
+                cdnUrl: typeof springbrand?.cdnUrl === "string"
+                  ? springbrand.cdnUrl
+                  : file.url,
+                workspacePath: typeof springbrand?.path === "string"
+                  ? springbrand.path
+                  : "",
+                attachmentId: typeof springbrand?.attachmentId === "string"
+                  ? springbrand.attachmentId
+                  : "",
+                contentVersion:
+                  typeof springbrand?.contentVersion === "string"
+                    ? springbrand.contentVersion
+                    : "",
+              };
+            }),
+          };
+        });
+        return {
+          content: [{
+            type: "text",
+            text: `The user answered:\n${answers.map((answer, index) => {
+              if (answer.attachments.length > 0) {
+                const responseAnswer = responseAnswers[index]!;
+                return `${index + 1}. ${answer.question}\n${responseAnswer.attachments
+                  .map((file) => `   - ${modelAttachmentText(file)}`)
+                  .join("\n")}`;
+              }
+              const parts = [
+                ...answer.selections,
+                ...(answer.text ? [answer.text] : []),
+              ];
+              return `${index + 1}. ${answer.question}\n   ${parts.join(" / ")}`;
+            }).join("\n")}`,
+          }],
+          details: { answers },
+        };
+      },
+    },
+  };
+}

package/src/tools/assistant/candidate.ts

@@ -0,0 +1,15 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { type TSchema } from "@earendil-works/pi-ai";
+import type { PiToolCandidate } from "../runtime/contracts";
+
+export function candidate<T extends TSchema>(tool: AgentTool<T>): PiToolCandidate {
+  return {
+    owner: "runtime-base",
+    requiredExecutionLevel: "safe",
+    source: "action",
+    tool: {
+      ...tool,
+      constrainedSampling: { type: "json_schema", strict: "prefer" },
+    } as AgentTool<T>,
+  };
+}

package/src/tools/assistant/followups.ts

@@ -0,0 +1,34 @@
+import { Type } from "@earendil-works/pi-ai";
+import type { PiToolCandidate } from "../runtime/contracts";
+import { result } from "../runtime/result";
+import { candidate } from "./candidate";
+
+const suggestFollowupsParameters = Type.Object({
+  items: Type.Array(Type.String({
+    description: "A follow-up the user could ask next, phrased as a request.",
+  }), {
+    minItems: 2,
+    maxItems: 4,
+    description: "2-4 concrete, distinct follow-up directions.",
+  }),
+}, { additionalProperties: false });
+
+export function suggestFollowupsPiToolCandidate(): PiToolCandidate {
+  return {
+    ...candidate({
+      name: "suggest_followups",
+      label: "Suggest follow-ups",
+      description:
+        "Offer the user 2-4 optional follow-up directions after completing a substantive task (a report, an analysis, a multi-step job). Call this at most once, after all work and other Tool calls are complete. It MUST be the last Tool call before the final answer. After it returns, write the complete final answer and make no further Tool calls. Do NOT call it for small talk, quick answers, or while a task is still in progress.",
+      parameters: suggestFollowupsParameters,
+      async execute(_toolCallId, input) {
+        return result({ noted: true, count: input.items.length });
+      },
+    }),
+    unattendedExecution: {
+      capability: "runtime-ui",
+      operation: "suggest-followups",
+    },
+    exposureMode: "direct",
+  };
+}

package/src/tools/assistant/index.ts

@@ -0,0 +1,19 @@
+import type { PiToolCandidate } from "../runtime/contracts";
+import { webSearchPiToolCandidate } from "../web/search";
+import type { WebSearch } from "../web/search/api";
+import { askUserPiToolCandidate } from "./ask-user";
+import { suggestFollowupsPiToolCandidate } from "./followups";
+import { updatePlanPiToolCandidate } from "./plan";
+
+export { memoryPiToolCandidate } from "./memory";
+export { normalizeUpdatePlanArguments } from "./plan";
+export * from "./time";
+
+export function basePiToolCandidates(webSearch?: WebSearch): PiToolCandidate[] {
+  return [
+    askUserPiToolCandidate(),
+    suggestFollowupsPiToolCandidate(),
+    updatePlanPiToolCandidate(),
+    ...(webSearch ? [webSearchPiToolCandidate(webSearch)] : []),
+  ];
+}

package/src/tools/assistant/memory.ts

@@ -0,0 +1,73 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { StringEnum, Type } from "@earendil-works/pi-ai";
+import { estimateStringTokens } from "../../lib/token-estimate";
+import type { RuntimeMemoryPort } from "../../config/ports";
+import type { RuntimeMemoryProfile } from "../../config/profile";
+import type { PiToolCandidate } from "../runtime/contracts";
+import { result } from "../runtime/result";
+
+const setContextParameters = Type.Object({
+  label: StringEnum(["memory", "preferences"] as const, {
+    description:
+      "Context block to update: memory for durable facts and active context, preferences for tone and workflow choices.",
+  }),
+  content: Type.String({ description: "Text to store in the selected context block." }),
+  action: Type.Optional(StringEnum(["replace", "append"] as const, {
+    description: 'Whether to replace the block or append to it. Defaults to "replace".',
+  })),
+}, { additionalProperties: false });
+
+/** Writable hot-memory Tool restored from Think Session context blocks. */
+export function memoryPiToolCandidate(
+  memory: RuntimeMemoryPort,
+  profile: Pick<
+    RuntimeMemoryProfile,
+    "memoryTokens" | "preferencesTokens"
+  >,
+): PiToolCandidate {
+  const queues = new Map<string, Promise<void>>();
+  const tool: AgentTool<typeof setContextParameters> = {
+    name: "set_context",
+    label: "Set context",
+    description:
+      "Replace or append durable working context. Use memory for facts and active context; use preferences for tone, format, tools, and workflow preferences.",
+    parameters: setContextParameters,
+    async execute(_toolCallId, { label, content, action = "replace" }) {
+      const run = async () => {
+        const existing = action === "append"
+          ? await memory.get(label) ?? ""
+          : "";
+        const separator = existing && !content.startsWith("\n") ? "\n" : "";
+        const updated = `${existing}${separator}${content}`;
+        const maxTokens = label === "memory"
+          ? profile.memoryTokens
+          : profile.preferencesTokens;
+        const tokens = estimateStringTokens(updated);
+        if (tokens > maxTokens) {
+          throw new Error(
+            `Block "${label}" exceeds maxTokens: ${tokens} > ${maxTokens}`,
+          );
+        }
+        await memory.set(label, updated);
+        return result({ label, action, tokens, maxTokens });
+      };
+      const tail = queues.get(label) ?? Promise.resolve();
+      const output = tail.then(run);
+      const next = output.then(
+        () => { },
+        () => { },
+      );
+      queues.set(label, next);
+      void next.then(() => {
+        if (queues.get(label) === next) queues.delete(label);
+      });
+      return output;
+    },
+  };
+  return {
+    owner: "runtime-memory",
+    requiredExecutionLevel: "safe",
+    source: "action",
+    tool,
+  };
+}