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

package/src/pi/runtime-adapter/recovery.ts

@@ -1,11 +1,15 @@
 import {
   applyRecoveredPiApprovalDecision,
+  applyRecoveredPiToolInteractionSettlement,
   commitPiRecoveryContinuation,
   encodePiToolRecoveryMilestone,
   planPiToolRecovery,
   replayPiToolRecovery,
+  stagePiAssemblyRepin,
   stagePiRecoveryContinuation,
   type PiToolApproval,
+  type PiToolInteraction,
+  type PiToolInteractionCancelReason,
   type PiToolRecoveryMilestone,
   type PiToolRecoveryPlan,
   type PiToolRecoveryState,
@@ -55,6 +59,32 @@ export type PiRecoveryCommand =
       readonly kind: "record-approval";
       readonly approval: PiToolApproval;
     }
+  | {
+      readonly kind: "record-interaction";
+      readonly interaction: PiToolInteraction;
+    }
+  /** 停在人机等待期间换了装配：记下这次被承认的身份迁移。 */
+  | {
+      readonly kind: "repin-assembly";
+      readonly nextAssemblyRevision: string;
+    }
+  | {
+      readonly kind: "interaction-settlement";
+      readonly interactionId: string;
+      readonly settlement:
+        | {
+            readonly kind: "respond";
+            readonly response: unknown;
+            readonly result: {
+              readonly content: ToolResultMessage["content"];
+              readonly details: unknown;
+            };
+          }
+        | {
+            readonly kind: "cancel";
+            readonly reason: PiToolInteractionCancelReason;
+          };
+    }
   | {
       readonly kind: "record-tool-result";
       readonly toolCallId: string;
@@ -109,6 +139,17 @@ export type PiDurableMutation =
       readonly status: "approved" | "rejected";
       readonly decidedAt: number;
       readonly reason?: string;
+    }
+  | {
+      readonly kind: "record-interaction";
+      readonly interaction: PiToolInteraction;
+    }
+  | {
+      readonly kind: "settle-interaction";
+      readonly interactionId: string;
+      readonly status: "responded" | "cancelled";
+      readonly settledAt: number;
+      readonly responseJson?: string;
     };
 
 export type PiRecoveryEffect =
@@ -131,7 +172,11 @@ export type PiRecoveryEffect =
     }
   | {
       readonly kind: "wait";
-      readonly reason?: "approval" | "uncertain-tool" | "complete";
+      readonly reason?:
+        | "approval"
+        | "interaction"
+        | "uncertain-tool"
+        | "complete";
     }
   | { readonly kind: "resume-turn" };
 
@@ -198,6 +243,31 @@ function approvalExecutionId(continuationKey: string): string | null {
   return match?.[1] ?? null;
 }
 
+// 把 Tool 自己的 settle 映射产出的内容包成一条权威 ToolResult。
+// interaction-settlement 命令处理 respond 分支时调用它。
+// 记录必须已经存在 —— 拿不到 toolCallId/toolName 就无法把结果绑回原调用，这时失败关闭而不是编一个 id。
+function interactionToolResult(
+  interaction: PiToolInteraction | undefined,
+  result: {
+    readonly content: ToolResultMessage["content"];
+    readonly details: unknown;
+  },
+  timestamp: number,
+): ToolResultMessage {
+  if (!interaction) {
+    throw new Error("Pi Tool interaction is missing for its response");
+  }
+  return {
+    role: "toolResult",
+    toolCallId: interaction.toolCallId,
+    toolName: interaction.toolName,
+    content: result.content,
+    details: result.details,
+    isError: false,
+    timestamp,
+  };
+}
+
 // 把纯恢复计划翻译成持久化操作和 Runtime 下一步动作。
 // decidePiRecovery 在命令应用并重放最新状态后调用它。
 // pending 续跑必须先形成里程碑并重放，再允许 dispatch，避免外部动作早于可恢复状态落盘。
@@ -223,6 +293,11 @@ function fromPlan(
         mutations: [],
         effect: { kind: "wait", reason: "approval" },
       };
+    case "parked-interaction":
+      return {
+        mutations: [],
+        effect: { kind: "wait", reason: "interaction" },
+      };
     case "park-uncertain-tool":
       return {
         mutations: [],
@@ -425,6 +500,112 @@ export function decidePiRecovery(
       applied = true;
     }
   }
+  if (input.command.kind === "repin-assembly") {
+    const milestone = stagePiAssemblyRepin(
+      state,
+      input.command.nextAssemblyRevision,
+      input.now,
+    );
+    if (milestone) {
+      const mutation = milestoneMutation(
+        `assembly-repin:${input.command.nextAssemblyRevision}`,
+        milestone,
+      );
+      mutations.push(mutation);
+      bodies = [...bodies, mutation.body];
+      state = replayPiToolRecovery(bodies);
+      applied = true;
+    }
+  }
+  if (input.command.kind === "record-interaction") {
+    const interaction = input.command.interaction;
+    const existing = state.interactions[interaction.interactionId];
+    if (existing) {
+      // 同一个 interactionId 必须描述同一次 Tool 调用，否则重放会把响应投给错的调用。
+      // 口径与 record-approval 的冲突检查一致。
+      if (
+        existing.requestId !== interaction.requestId ||
+        existing.toolCallId !== interaction.toolCallId ||
+        existing.toolName !== interaction.toolName ||
+        existing.inputJson !== interaction.inputJson
+      ) {
+        throw new Error(
+          `Conflicting Pi Tool interaction: ${interaction.interactionId}`,
+        );
+      }
+    } else {
+      const mutation = milestoneMutation(
+        `interaction:${interaction.interactionId}:${interaction.status}`,
+        {
+          ...recoveryIdentity(input),
+          type: "interaction",
+          interaction,
+        },
+      );
+      mutations.push(
+        { kind: "record-interaction", interaction },
+        mutation,
+      );
+      bodies = [...bodies, mutation.body];
+      state = replayPiToolRecovery(bodies);
+      applied = true;
+    }
+  }
+  if (input.command.kind === "interaction-settlement") {
+    const command = input.command;
+    const settlement = applyRecoveredPiToolInteractionSettlement(
+      state,
+      command.settlement.kind === "respond"
+        ? {
+            interactionId: command.interactionId,
+            kind: "respond",
+            response: command.settlement.response,
+            toolResult: interactionToolResult(
+              state.interactions[command.interactionId],
+              command.settlement.result,
+              input.now,
+            ),
+            settledAt: input.now,
+          }
+        : {
+            interactionId: command.interactionId,
+            kind: "cancel",
+            reason: command.settlement.reason,
+            settledAt: input.now,
+          },
+    );
+    applied = settlement.outcome.kind !== "noop";
+    if (applied) {
+      const record = settlement.milestones.find(
+        (milestone) => milestone.type === "interaction",
+      );
+      if (!record || record.type !== "interaction") {
+        throw new Error("Pi interaction settlement milestone is missing");
+      }
+      mutations.push({
+        kind: "settle-interaction",
+        interactionId: record.interaction.interactionId,
+        status: record.interaction.status as "responded" | "cancelled",
+        settledAt: record.interaction.respondedAt ?? input.now,
+        ...(record.interaction.responseJson === undefined
+          ? {}
+          : { responseJson: record.interaction.responseJson }),
+      });
+      settlement.milestones.forEach((milestone, index) => {
+        mutations.push(milestoneMutation(
+          milestone.type === "interaction"
+            ? `interaction:${command.interactionId}:${record.interaction.status}`
+            : `interaction-result:${command.interactionId}:${index}`,
+          milestone,
+        ));
+      });
+      bodies = [
+        ...bodies,
+        ...settlement.milestones.map(encodePiToolRecoveryMilestone),
+      ];
+      state = replayPiToolRecovery(bodies);
+    }
+  }
   if (input.command.kind === "record-tool-result") {
     const command = input.command;
     const toolResult: ToolResultMessage = {
@@ -649,6 +830,12 @@ export class PiRuntimeRecoveryAdapter
           reason: "Pi Turn is waiting for Tool approval",
         } as const;
       }
+      if (decision.effect.reason === "interaction") {
+        return {
+          kind: "park",
+          reason: "Pi Turn is waiting for a client Tool interaction response",
+        } as const;
+      }
       if (decision.effect.reason === "uncertain-tool") {
         return {
           kind: "park",

package/src/pi/runtime-adapter/transcript.ts

@@ -29,6 +29,10 @@ import {
 import type { PiCanonicalMessageCommit } from "./execution";
 import type { PiRecoveredToolSettlement } from "./recovery";
 import type { RuntimeModelUsageEvent } from "../../kernel/bindings";
+import {
+  isModelStreamStallMessage,
+  isRecoverableAssistantError,
+} from "./models";
 
 /**
  * 本文件负责保存 Pi 的规范消息，并按浏览器或 Extension Host 的需要投影历史。
@@ -196,6 +200,15 @@ function hostText(message: UserMessage | AssistantMessage): string {
 export class PiRuntimeTranscript {
   private readonly store: PiTranscriptStore;
 
+  private modelBranch() {
+    return this.store.branch().filter((entry) =>
+      entry.type !== "message" ||
+      entry.message.role !== "assistant" ||
+      (!isModelStreamStallMessage(entry.message.errorMessage) &&
+        !isRecoverableAssistantError(entry.message))
+    );
+  }
+
   /**
    * 用当前 Agent 的 SQLite、Runtime 持久化端口和 Pi 模型表创建 Transcript。
    *
@@ -383,7 +396,7 @@ export class PiRuntimeTranscript {
    * 这里只返回 `message` entry；compaction 等 Session entry 由上下文转换阶段处理，不能混入原始消息列表。
    */
   async canonicalMessages(): Promise<AgentMessage[]> {
-    return this.store.branch().flatMap((entry) =>
+    return this.modelBranch().flatMap((entry) =>
       entry.type === "message" ? [entry.message] : []
     );
   }
@@ -449,7 +462,7 @@ export class PiRuntimeTranscript {
       onCompactionPersisted?: (event: RuntimeModelUsageEvent) => void;
     },
   ): Promise<AgentMessage[]> {
-    const branch = this.store.branch();
+    const branch = this.modelBranch();
     const current = branch.flatMap((entry) =>
       entry.type === "message" ? [entry.message] : []
     );
@@ -616,10 +629,47 @@ export class PiRuntimeTranscript {
   async browserMessages(): Promise<UIMessage[]> {
     const result: UIMessage[] = [];
     const seenAssistantSubmissions = new Set<string>();
+    const entries = await this.storedMessages();
+    const assistantSubmissions = new Set(entries.flatMap((entry) =>
+      entry.submissionId && entry.message.role === "assistant"
+        ? [entry.submissionId]
+        : []
+    ));
+    let pendingFailedSubmissionId: string | undefined;
+    const flushFailedSubmission = () => {
+      if (!pendingFailedSubmissionId) return;
+      const submissionId = pendingFailedSubmissionId;
+      pendingFailedSubmissionId = undefined;
+      const submission = this.durability.findSubmissionProjection(submissionId);
+      if (submission?.status !== "error") return;
+      const completedAt = submission.completedAt ?? submission.createdAt;
+      result.push({
+        id: submission.assistantMessageId,
+        role: "assistant",
+        parts: [],
+        metadata: {
+          createdAt: submission.createdAt,
+          completedAt,
+          turnDurationMs: Math.max(
+            0,
+            completedAt - submission.createdAt,
+          ),
+          turnStatus: "error",
+          ...(submission.error ? { error: submission.error } : {}),
+        },
+      });
+      seenAssistantSubmissions.add(submissionId);
+    };
     let activeAssistant:
       | { submissionId: string; index: number }
       | undefined;
-    for (const entry of await this.storedMessages()) {
+    for (const entry of entries) {
+      if (
+        pendingFailedSubmissionId &&
+        entry.submissionId !== pendingFailedSubmissionId
+      ) {
+        flushFailedSubmission();
+      }
       if (entry.message.role === "user") {
         const body = this.durability.readUserSidecar(entry.id);
         result.push(userUIMessage(entry.message, {
@@ -629,6 +679,13 @@ export class PiRuntimeTranscript {
             ? JSON.parse(body) as UIUserSidecar
             : undefined,
         }));
+        if (
+          entry.submissionId &&
+          !assistantSubmissions.has(entry.submissionId) &&
+          !seenAssistantSubmissions.has(entry.submissionId)
+        ) {
+          pendingFailedSubmissionId = entry.submissionId;
+        }
         activeAssistant = undefined;
         continue;
       }
@@ -744,6 +801,7 @@ export class PiRuntimeTranscript {
         }
       }
     }
+    flushFailedSubmission();
     return result;
   }
 

package/src/pi/tool/ai-adapter.ts

@@ -38,6 +38,52 @@ function resolveDescription(tool: AiTool): string {
   return typeof raw === "string" ? raw : "";
 }
 
+function modelContent(
+  output: unknown,
+): AgentToolResult<unknown>["content"] | null {
+  if (typeof output !== "object" || output === null) return null;
+  const modelOutput = output as { type?: unknown; value?: unknown };
+  if (
+    (modelOutput.type === "text" || modelOutput.type === "error-text") &&
+    typeof modelOutput.value === "string"
+  ) {
+    return [{ type: "text", text: modelOutput.value }];
+  }
+  if (modelOutput.type === "json") {
+    return [{ type: "text", text: serializeOutput(modelOutput.value).text }];
+  }
+  if (modelOutput.type !== "content" || !Array.isArray(modelOutput.value)) {
+    return null;
+  }
+
+  const content: AgentToolResult<unknown>["content"] = [];
+  for (const block of modelOutput.value) {
+    if (typeof block !== "object" || block === null) continue;
+    const item = block as {
+      type?: unknown;
+      text?: unknown;
+      data?: unknown;
+      mediaType?: unknown;
+    };
+    if (item.type === "text" && typeof item.text === "string") {
+      content.push({ type: "text", text: item.text });
+      continue;
+    }
+    if (
+      (item.type === "file-data" || item.type === "image-data") &&
+      typeof item.data === "string" &&
+      typeof item.mediaType === "string"
+    ) {
+      content.push({
+        type: "image",
+        data: item.data,
+        mimeType: item.mediaType,
+      });
+    }
+  }
+  return content.length > 0 ? content : null;
+}
+
 /**
  * 把一个可执行的 ai-sdk Tool 转成 Pi AgentTool。
  *
@@ -91,8 +137,19 @@ export function aiToolToPi(
         context: undefined,
       });
       const details = options.details ? options.details(raw) : raw;
+      const toModelOutput = (tool as { toModelOutput?: unknown })
+        .toModelOutput;
+      const content = typeof toModelOutput === "function"
+        ? modelContent(await (toModelOutput as (input: {
+            input: unknown;
+            output: unknown;
+          }) => unknown)({ input: params, output: raw }))
+        : null;
       return {
-        content: [{ type: "text", text: serializeOutput(details).text }],
+        content: content ?? [{
+          type: "text",
+          text: serializeOutput(details).text,
+        }],
         details,
       };
     },

package/src/pi/tool/base.ts

@@ -2,9 +2,16 @@ import type {
   AgentTool,
   AgentToolResult,
 } from "@earendil-works/pi-agent-core";
-import { Type, type TSchema } from "@earendil-works/pi-ai";
+import { Type, type Static, type TSchema } from "@earendil-works/pi-ai";
+import { estimateStringTokens } from "agents/experimental/memory/utils";
+import type { RuntimeMemoryPort } from "../../kernel/bindings";
+import type { RuntimeMemoryProfile } from "../../kernel/profile";
 import { serializeOutput } from "../../lib/artifacts";
 import type { PiToolCandidate } from "./compiler";
+import {
+  toolRegistryFromPiCandidates,
+  type ToolRegistry,
+} from "../../tool-registry";
 import { webSearchPiToolCandidate } from "./web-search";
 import type { WebSearch } from "./web-search/api";
 
@@ -23,6 +30,34 @@ const askUserParameters = Type.Object({
   })),
 });
 
+/**
+ * `ask_user` 的客户端响应体。
+ *
+ * `selections` 是选中的选项原文（多选时多于一项），`text` 是可选的补充说明。
+ * 刻意用结构化数组而不是拼好的字符串 —— 选项本身可能含分隔符，拼了再拆是有损的。
+ */
+const askUserResponse = Type.Object({
+  selections: Type.Array(Type.String()),
+  text: Type.Optional(Type.String()),
+});
+
+// 手写校验而不是拉 TypeBox 的 compiler：这里只需要判真假，
+// 且校验必须在 Worker 冷启动路径上零成本。
+function isAskUserResponse(value: unknown): boolean {
+  if (typeof value !== "object" || value === null) return false;
+  const record = value as Record<string, unknown>;
+  if (!Array.isArray(record.selections)) return false;
+  if (!record.selections.every((item) => typeof item === "string")) {
+    return false;
+  }
+  if (record.text !== undefined && typeof record.text !== "string") {
+    return false;
+  }
+  // 什么都没选、也没写字，等于没回答 —— 不该被当成一次有效结算。
+  return record.selections.length > 0 ||
+    (typeof record.text === "string" && record.text.trim().length > 0);
+}
+
 const suggestFollowupsParameters = Type.Object({
   items: Type.Array(Type.String({
     description: "A follow-up the user could ask next, phrased as a request.",
@@ -42,13 +77,63 @@ const updatePlanParameters = Type.Object({
       Type.Literal("pending"),
       Type.Literal("in_progress"),
       Type.Literal("done"),
-    ], { description: "Current status of this step." }),
+    ], {
+      description:
+        'Current status. Use "done" for a finished step; never use "completed".',
+    }),
   }), {
     description:
       "The complete, ordered plan. Overwrites any previously reported plan.",
   }),
 });
 
+type UpdatePlanArguments = Static<typeof updatePlanParameters>;
+
+function normalizeStepStatus(
+  status: unknown,
+): UpdatePlanArguments["steps"][number]["status"] {
+  switch (status) {
+    case "done":
+    case "completed": // Anthropic models sometimes output "completed"
+      return "done";
+    case "in_progress":
+    case "inProgress": // camelCase variant
+      return "in_progress";
+    default: // covers "pending", "todo" (Google), and any other unknown value
+      return "pending";
+  }
+}
+
+export function normalizeUpdatePlanArguments(
+  input: unknown,
+): UpdatePlanArguments {
+  if (input === null || typeof input !== "object") {
+    return input as UpdatePlanArguments;
+  }
+  const value = input as Record<string, unknown>;
+  if (!Array.isArray(value.steps)) return input as UpdatePlanArguments;
+  return {
+    ...value,
+    steps: value.steps.map((step) => {
+      if (step === null || typeof step !== "object") return step;
+      const s = step as Record<string, unknown>;
+      return { ...s, status: normalizeStepStatus(s.status) };
+    }),
+  } as UpdatePlanArguments;
+}
+
+const setContextParameters = Type.Object({
+  label: Type.Union([
+    Type.Literal("memory"),
+    Type.Literal("preferences"),
+  ]),
+  content: Type.String(),
+  action: Type.Optional(Type.Union([
+    Type.Literal("replace"),
+    Type.Literal("append"),
+  ])),
+});
+
 function result<T>(details: T): AgentToolResult<T> {
   return {
     content: [{ type: "text", text: serializeOutput(details).text }],
@@ -59,7 +144,6 @@ function result<T>(details: T): AgentToolResult<T> {
 function candidate<T extends TSchema>(tool: AgentTool<T>): PiToolCandidate {
   return {
     owner: "runtime-base",
-    authorized: true,
     requiredExecutionLevel: "safe",
     source: "action",
     tool,
@@ -71,16 +155,41 @@ export function basePiToolCandidates(
   webSearch?: WebSearch,
 ): PiToolCandidate[] {
   return [
-    candidate({
-      name: "ask_user",
-      label: "Ask user",
-      description:
-        "Ask the user to choose among a small set of options. Call this tool whenever you need the user to make a choice from limited options — do NOT write plain text like 'please pick A / B / C'. After calling this tool, end your turn and wait for the user's reply.",
-      parameters: askUserParameters,
-      async execute() {
-        return result({ asked: true });
+    // ask_user 是 client-settled tool：它没有 execute，结果由用户点选后经
+    // respondToolInteraction 投递回来。工具调用会一直 park 到那时候。
+    {
+      ...candidate({
+        name: "ask_user",
+        label: "Ask user",
+        description:
+          "Ask the user to choose among a small set of options. Call this tool whenever you need the user to make a choice from limited options — do NOT write plain text like 'please pick A / B / C'. The user's choice comes back to you as this tool's result, so just continue once you have it. Do NOT end your turn after calling this tool.",
+        parameters: askUserParameters,
+        // 永远不会被调用：执行链在 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 answer = response as Static<typeof askUserResponse>;
+          const parts = [
+            ...answer.selections,
+            ...(answer.text?.trim() ? [answer.text.trim()] : []),
+          ];
+          return {
+            content: [{
+              type: "text",
+              text: `The user answered: ${parts.join(" / ")}`,
+            }],
+            details: answer,
+          };
+        },
       },
-    }),
+    },
     candidate({
       name: "suggest_followups",
       label: "Suggest follow-ups",
@@ -97,6 +206,7 @@ export function basePiToolCandidates(
       description:
         "Maintain the user-visible plan for the current task. Call this whenever a task involves 2 or more steps, and again every time the plan or a step's status changes. Always pass the FULL plan — it replaces the previous plan entirely (idempotent overwrite), so omitted steps disappear.",
       parameters: updatePlanParameters,
+      prepareArguments: normalizeUpdatePlanArguments,
       async execute(_toolCallId, input) {
         return result({
           ok: true,
@@ -108,3 +218,71 @@ export function basePiToolCandidates(
     ...(webSearch ? [webSearchPiToolCandidate(webSearch)] : []),
   ];
 }
+
+/** 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,
+  };
+}
+
+/** 从 Memory Port 生成 `set_context` Tool。 */
+export function createMemoryTools(
+  memory: RuntimeMemoryPort,
+  profile: Pick<
+    RuntimeMemoryProfile,
+    "memoryTokens" | "preferencesTokens"
+  >,
+): ToolRegistry {
+  return toolRegistryFromPiCandidates([
+    memoryPiToolCandidate(memory, profile),
+  ]);
+}