@springbrand/agent-runtime 0.1.3-alpha.0 → 0.1.3-alpha.2

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

@@ -2,8 +2,10 @@ import type { StreamFn } from "@earendil-works/pi-agent-core";
 import {
   createModels,
   createProvider,
+  isRetryableAssistantError,
   lazyStream,
   type Api,
+  type AssistantMessage,
   type AssistantMessageEvent,
   type Model,
   type MutableModels,
@@ -35,6 +37,12 @@ import {
 import {
   openaiCodexProvider,
 } from "@earendil-works/pi-ai/providers/openai-codex";
+import {
+  cloudflareStreams,
+} from "@earendil-works/pi-ai/providers/cloudflare-stream";
+import {
+  ChatStreamStalledError,
+} from "agents/chat";
 import type {
   RuntimeModelEndpoint,
   RuntimeModelProtocol,
@@ -50,46 +58,216 @@ const CATALOGS = {
 } satisfies Record<RuntimeModelProtocol, readonly Model<Api>[]>;
 
 const PROVIDER_MAX_RETRIES = 2;
-const MODEL_STREAM_STALL_TIMEOUT_MS = 120_000;
+export const MODEL_STREAM_STALL_TIMEOUT_MS = 60_000;
+export const MODEL_STREAM_STALL_MESSAGE =
+  `Chat stream stalled: no activity for ${MODEL_STREAM_STALL_TIMEOUT_MS}ms; the turn was aborted by the stall watchdog.`;
+const MODEL_STREAM_STALL_DETAILS_PREFIX = `${MODEL_STREAM_STALL_MESSAGE}\n`;
+
+export interface ModelStreamStallDetails {
+  lastMeaningfulActivityAt: number;
+  lastMeaningfulActivityType:
+    | AssistantMessageEvent["type"]
+    | "model_stream_started";
+  idleMs: number;
+}
+
+export function isModelStreamStallMessage(message?: string): message is string {
+  return message === MODEL_STREAM_STALL_MESSAGE ||
+    message?.startsWith(MODEL_STREAM_STALL_DETAILS_PREFIX) === true;
+}
+
+export function readModelStreamStallDetails(
+  message?: string,
+): ModelStreamStallDetails | undefined {
+  if (!message?.startsWith(MODEL_STREAM_STALL_DETAILS_PREFIX)) return;
+  try {
+    const value = JSON.parse(
+      message.slice(MODEL_STREAM_STALL_DETAILS_PREFIX.length),
+    ) as Partial<ModelStreamStallDetails>;
+    if (
+      typeof value.lastMeaningfulActivityAt !== "number" ||
+      typeof value.lastMeaningfulActivityType !== "string" ||
+      typeof value.idleMs !== "number"
+    ) return;
+    return value as ModelStreamStallDetails;
+  } catch {
+    return;
+  }
+}
+
+export function isRecoverableAssistantError(
+  message: AssistantMessage,
+): boolean {
+  if (
+    message.stopReason === "error" &&
+    /thought[_ ]signature/i.test(message.errorMessage ?? "")
+  ) return false;
+  return isRetryableAssistantError(message) ||
+    (message.stopReason === "error" &&
+      /upstream http\/2 stream failed/i.test(message.errorMessage ?? ""));
+}
+
+function pdfPayload(payload: unknown, api: Api): unknown {
+  if (Array.isArray(payload)) {
+    return payload.map((value) => pdfPayload(value, api));
+  }
+  if (typeof payload !== "object" || payload === null) return payload;
+
+  const value = payload as Record<string, unknown>;
+  if (api === "anthropic-messages" && value.type === "image") {
+    const source = value.source as Record<string, unknown> | undefined;
+    if (source?.media_type === "application/pdf") {
+      return { ...value, type: "document" };
+    }
+  }
+  if (api === "openai-completions" && value.type === "image_url") {
+    const image = value.image_url as Record<string, unknown> | undefined;
+    if (
+      typeof image?.url === "string" &&
+      image.url.startsWith("data:application/pdf;base64,")
+    ) {
+      return {
+        type: "file",
+        file: { filename: "workspace.pdf", file_data: image.url },
+      };
+    }
+  }
+  if (api === "openai-codex-responses" && value.type === "input_image") {
+    if (
+      typeof value.image_url === "string" &&
+      value.image_url.startsWith("data:application/pdf;base64,")
+    ) {
+      return {
+        type: "input_file",
+        filename: "workspace.pdf",
+        file_data: value.image_url,
+      };
+    }
+  }
+
+  return Object.fromEntries(
+    Object.entries(value).map(([key, child]) => [
+      key,
+      pdfPayload(child, api),
+    ]),
+  );
+}
+
+function meaningfulModelProgress(
+  event: AssistantMessageEvent,
+  streamedContent: Set<string>,
+): AssistantMessageEvent["type"] | undefined {
+  switch (event.type) {
+    case "text_delta":
+    case "thinking_delta": {
+      if (!event.delta.trim()) return undefined;
+      streamedContent.add(`${event.type}:${event.contentIndex}`);
+      return event.type;
+    }
+    case "text_end":
+      if (streamedContent.has(`text_delta:${event.contentIndex}`)) return;
+      return event.content.trim() ? event.type : undefined;
+    case "thinking_end":
+      if (streamedContent.has(`thinking_delta:${event.contentIndex}`)) return;
+      return event.content.trim() ? event.type : undefined;
+    case "toolcall_end":
+      return event.type;
+    default:
+      return undefined;
+  }
+}
 
 async function* stopStalledModelStream(
   source: AsyncIterable<AssistantMessageEvent>,
   watchdog: AbortController,
 ): AsyncGenerator<AssistantMessageEvent> {
   const iterator = source[Symbol.asyncIterator]();
-  while (true) {
-    let timer: ReturnType<typeof setTimeout> | undefined;
-    const next = await Promise.race([
-      iterator.next(),
-      new Promise<never>((_, reject) => {
-        timer = setTimeout(() => {
-          const error = new Error(
-            `Model stream stalled for ${MODEL_STREAM_STALL_TIMEOUT_MS} ms`,
-          );
-          watchdog.abort(error);
-          reject(error);
-        }, MODEL_STREAM_STALL_TIMEOUT_MS);
-      }),
-    ]).finally(() => {
-      if (timer !== undefined) clearTimeout(timer);
-    });
-    if (next.done) {
-      throw new Error("Model stream ended without a terminal event");
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let stalled = false;
+  let stallError: ChatStreamStalledError | undefined;
+  let idleWaitMs = 0;
+  const streamedContent = new Set<string>();
+  let lastMeaningfulActivityAt = Date.now();
+  let lastMeaningfulActivityType:
+    ModelStreamStallDetails["lastMeaningfulActivityType"] =
+      "model_stream_started";
+  const stop = (idleMs: number) => {
+    stalled = true;
+    stallError = new ChatStreamStalledError(
+      MODEL_STREAM_STALL_DETAILS_PREFIX + JSON.stringify({
+        lastMeaningfulActivityAt,
+        lastMeaningfulActivityType,
+        idleMs,
+      } satisfies ModelStreamStallDetails),
+    );
+    watchdog.abort(stallError);
+    return stallError;
+  };
+  const arm = (
+    delayMs: number,
+    waitStartedAt: number,
+  ) => new Promise<never>((_, reject) => {
+    timer = setTimeout(() => {
+      reject(stop(idleWaitMs + Date.now() - waitStartedAt));
+    }, delayMs);
+  });
+  try {
+    while (true) {
+      const waitStartedAt = Date.now();
+      const nextPromise = iterator.next();
+      nextPromise.catch(() => {});
+      let next: IteratorResult<AssistantMessageEvent>;
+      try {
+        next = await Promise.race([
+          nextPromise,
+          arm(
+            Math.max(0, MODEL_STREAM_STALL_TIMEOUT_MS - idleWaitMs),
+            waitStartedAt,
+          ),
+        ]);
+      } catch (error) {
+        if (stalled) throw stallError;
+        throw error;
+      } finally {
+        clearTimeout(timer);
+        timer = undefined;
+      }
+      if (stalled) throw stallError;
+      if (next.done) break;
+      const event = next.value;
+      if (event.type === "done" || event.type === "error") {
+        yield event;
+        return;
+      }
+      idleWaitMs += Date.now() - waitStartedAt;
+      const progress = meaningfulModelProgress(event, streamedContent);
+      if (progress) {
+        lastMeaningfulActivityAt = Date.now();
+        lastMeaningfulActivityType = progress;
+        idleWaitMs = 0;
+      }
+      yield event;
     }
-    yield next.value;
-    if (next.value.type === "done" || next.value.type === "error") return;
+  } finally {
+    clearTimeout(timer);
+    if (!stalled) await iterator.return?.().catch(() => {});
   }
+  throw new Error("Model stream ended without a terminal event");
 }
 
 /**
- * 给模型请求补上可中断的 provider 瞬时错误重试和空闲终止边界。
+ * 给模型请求补上可中断的空闲终止边界。
  *
  * Runtime Turn 和 SubAgent 在把 `Models.streamSimple` 交给 Pi 前调用；显式传入的重试次数优先。
  *
- * Pi 0.83 默认 `maxRetries` 为 0，且流无事件时会无限等待。这里补 2 次默认重试，
- * 并在连续 120 秒没有模型事件时中止 provider、返回明确失败终态。
+ * 调用方可以覆盖默认的 2 次 Provider 重试；主 Turn 传 0，由 Submission
+ * 统一持有恢复预算。连续 60 秒没有可展示进展时中止 provider。
  */
-export function withProviderRetry(streamFn: StreamFn): StreamFn {
+export function withProviderRetry(
+  streamFn: StreamFn,
+  defaultMaxRetries = PROVIDER_MAX_RETRIES,
+  defaultSessionId?: string,
+): StreamFn {
   return (model, context, options) =>
     lazyStream(model, async () => {
       const watchdog = new AbortController();
@@ -98,7 +276,13 @@ export function withProviderRetry(streamFn: StreamFn): StreamFn {
         signal: options?.signal
           ? AbortSignal.any([options.signal, watchdog.signal])
           : watchdog.signal,
-        maxRetries: options?.maxRetries ?? PROVIDER_MAX_RETRIES,
+        maxRetries: options?.maxRetries ?? defaultMaxRetries,
+        sessionId: options?.sessionId ?? defaultSessionId,
+        onPayload: async (payload, activeModel) =>
+          pdfPayload(
+            await options?.onPayload?.(payload, activeModel) ?? payload,
+            activeModel.api,
+          ),
       });
       return stopStalledModelStream(source, watchdog);
     });
@@ -188,8 +372,14 @@ function configuredModel(
     api: apiFor(endpoint.protocol),
     provider: providerId(endpoint, index),
     baseUrl: endpoint.baseURL,
-    ...(endpoint.protocol === "openrouter-chat" && compat
-      ? { compat }
+    ...(endpoint.protocol === "openrouter-chat"
+      ? {
+          compat: {
+            ...compat,
+            sendSessionAffinityHeaders: true,
+            sessionAffinityFormat: "openrouter" as const,
+          },
+        }
       : {}),
     ...(Object.keys(headers).length > 0 ? { headers } : {}),
   };
@@ -265,7 +455,9 @@ export function configurePiModels(
       models: endpoint.models.map((modelId) =>
         configuredModel(endpoint, index, modelId),
       ),
-      api: piApiFor(endpoint.protocol),
+      // cloudflareStreams 在运行时把 baseURL 里的 {CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}
+      // 占位符替换成真实值；如果 baseURL 不含占位符则直接透传，不影响现有端点。
+      api: cloudflareStreams(piApiFor(endpoint.protocol)),
     })
   );
   models.clearProviders();

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,7 +2,10 @@ 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 { webSearchPiToolCandidate } from "./web-search";
@@ -42,13 +45,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 }],
@@ -97,6 +150,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 +162,59 @@ 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",
+    authorized: true,
+    requiredExecutionLevel: "safe",
+    source: "action",
+    tool,
+  };
+}