@springbrand/agent-runtime 0.2.0-alpha.72 → 0.3.0-alpha.10

package/src/{pi → conversation}/message/conversion.ts

@@ -1,5 +1,80 @@
 import type { UserMessage } from "@earendil-works/pi-ai";
 import type { UIMessage } from "ai";
+import type { RequestedCapability } from "./contract";
+
+export function requestedCapabilitiesOf(metadata: unknown): RequestedCapability[] {
+  if (metadata === null || typeof metadata !== "object" || Array.isArray(metadata)) {
+    return [];
+  }
+  const record = metadata as Record<string, unknown>;
+  if (!("requestedCapabilities" in record)) return [];
+  if (!Array.isArray(record.requestedCapabilities)) {
+    throw new Error("requestedCapabilities must be an array");
+  }
+  const result: RequestedCapability[] = [];
+  const seen = new Set<string>();
+  for (const value of record.requestedCapabilities) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+      throw new Error("requestedCapabilities contains an invalid capability");
+    }
+    const capability = value as Record<string, unknown>;
+    if (
+      (capability.kind !== "skill" && capability.kind !== "tool" && capability.kind !== "plan") ||
+      typeof capability.name !== "string" ||
+      !capability.name.trim() ||
+      typeof capability.label !== "string" ||
+      !capability.label.trim()
+    ) {
+      throw new Error("requestedCapabilities contains an invalid capability");
+    }
+    const key = `${capability.kind}:${capability.name}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push({ kind: capability.kind, name: capability.name, label: capability.label });
+  }
+  return result;
+}
+
+/** Resolve user-selected capabilities against the loaded Runtime before model input conversion. */
+export function normalizeUIUserInput(
+  message: UIMessage & { role: "user" },
+  installed: {
+    readonly hasSkill: (name: string) => boolean;
+    readonly hasTool: (name: string) => boolean;
+  },
+): UserMessage {
+  const context: string[] = [];
+  for (const capability of requestedCapabilitiesOf(message.metadata)) {
+    if (capability.kind === "skill") {
+      if (!installed.hasSkill(capability.name)) {
+        throw new Error(`Requested Skill is not installed: ${capability.name}`);
+      }
+      context.push(
+        `requested capability: skill/${capability.name}`,
+        `required action: call activate_skill for "${capability.name}" before handling the task`,
+      );
+      continue;
+    }
+    if (capability.kind === "tool") {
+      if (!installed.hasTool(capability.name)) {
+        throw new Error(`Requested Tool is not installed: ${capability.name}`);
+      }
+      context.push(
+        `requested capability: tool/${capability.name}`,
+        `required action: call tool "${capability.name}" when handling the task`,
+      );
+      continue;
+    }
+    if (capability.name !== "plan") {
+      throw new Error(`Unknown plan capability: ${capability.name}`);
+    }
+    context.push(
+      "requested capability: plan/plan",
+      "required action: call update_plan with the complete plan before other work, then wait for user confirmation before execution",
+    );
+  }
+  return uiUserMessageToPi(message, context.join("\n"));
+}
 
 export interface UIUserSidecar {
   readonly metadata?: unknown;

package/src/{pi → conversation}/message/index.ts

@@ -1,3 +1,4 @@
 export * from "./contract";
 export * from "./conversion";
 export * from "./projection";
+export * from "./model-input";

package/src/{pi → conversation}/message/model-input.ts

@@ -1,5 +1,5 @@
 import type { Message, UserMessage } from "@earendil-works/pi-ai";
-import type { RuntimeModelInputModality } from "../../kernel/bindings";
+import type { RuntimeModelInputModality } from "../../config/profile";
 
 const UNSUPPORTED_FILE_PLACEHOLDER =
   "(file omitted: model API does not support this file type)";

package/src/{pi → conversation}/message/projection.ts

@@ -11,7 +11,7 @@ import type {
   UIMessage,
   UIMessageChunk,
 } from "ai";
-import { USER_STOP_REASON } from "../../kernel/receipts";
+import { USER_STOP_REASON } from "../../submission/contracts";
 
 const MAX_OUTPUT_BYTES = 256 * 1024;
 const MAX_OUTPUT_PREVIEW = 16 * 1024;
@@ -75,6 +75,35 @@ function safeInput(value: unknown): Record<string, unknown> {
   return isRecord(safe) ? safe : {};
 }
 
+export type ToolInputPreparer = (
+  toolName: string,
+  input: unknown,
+) => unknown;
+
+function safeToolInput(
+  toolName: string,
+  value: unknown,
+  prepare?: ToolInputPreparer,
+): Record<string, unknown> {
+  if (prepare) {
+    try {
+      value = prepare(toolName, value);
+    } catch {
+      // Preserve invalid provider output for the normal Tool validation path.
+    }
+  }
+  const input = safeInput(value);
+  if (toolName === "ask_user" && typeof input.questions === "string") {
+    try {
+      const questions: unknown = JSON.parse(input.questions);
+      if (Array.isArray(questions)) input.questions = questions;
+    } catch {
+      // Preserve malformed provider output for the normal unavailable state.
+    }
+  }
+  return input;
+}
+
 function contentText(result: unknown): string | undefined {
   if (!isRecord(result) || !Array.isArray(result.content)) return undefined;
   const text = result.content.flatMap((part) =>
@@ -174,6 +203,8 @@ export class PiChunkEncoder {
   private readonly messageId: string;
   private readonly startedAt?: number;
   private readonly turnId?: string;
+  private readonly userMessageId?: string;
+  private readonly prepareToolInput?: ToolInputPreparer;
   private started = false;
   private finished = false;
   private firstTurnStarted = false;
@@ -192,10 +223,14 @@ export class PiChunkEncoder {
     messageId: string;
     startedAt?: number;
     turnId?: string;
+    userMessageId?: string | null;
+    prepareToolInput?: ToolInputPreparer;
   }) {
     this.messageId = options.messageId;
     this.startedAt = options.startedAt;
     this.turnId = options.turnId;
+    this.userMessageId = options.userMessageId ?? undefined;
+    this.prepareToolInput = options.prepareToolInput;
   }
 
   start(): UIMessageChunk[] {
@@ -213,6 +248,7 @@ export class PiChunkEncoder {
                 createdAt: this.startedAt,
                 turnStatus: "running",
                 ...(this.turnId ? { turnId: this.turnId } : {}),
+                ...(this.userMessageId ? { userMessageId: this.userMessageId } : {}),
               },
             }),
       },
@@ -220,12 +256,60 @@ export class PiChunkEncoder {
     ];
   }
 
+  /** Seed this encoder and its open part IDs from one Pi-backed UI snapshot. */
+  restore(message: UIMessage, streaming: boolean): UIMessageChunk[] {
+    if (this.started) throw new Error("Cannot restore an already-started stream encoder");
+    this.started = true;
+    this.firstTurnStarted = message.parts.length === 0;
+    const chunks: UIMessageChunk[] = [{ type: "start", messageId: this.messageId,
+      ...(message.metadata === undefined ? {} : { messageMetadata: message.metadata }) }];
+    let contentIndex = 0;
+    let hasStep = false;
+    let lastContentIndex = message.parts.length - 1;
+    while (lastContentIndex >= 0 && message.parts[lastContentIndex]?.type === "step-start") lastContentIndex -= 1;
+    for (const [partIndex, part] of message.parts.entries()) {
+      if (part.type === "step-start") {
+        if (hasStep) { chunks.push({ type: "finish-step" }); this.stepIndex += 1; }
+        chunks.push({ type: "start-step" });
+        hasStep = true;
+        contentIndex = 0;
+        continue;
+      }
+      if (!hasStep) { chunks.push({ type: "start-step" }); hasStep = true; }
+      if (part.type === "text" || part.type === "reasoning") {
+        const kind = part.type;
+        const id = this.partId(kind, contentIndex);
+        chunks.push({ type: `${kind}-start`, id });
+        if (part.text) chunks.push({ type: `${kind}-delta`, id, delta: part.text });
+        if (streaming && partIndex === lastContentIndex) {
+          (kind === "text" ? this.activeText : this.activeReasoning).add(contentIndex);
+        } else chunks.push({ type: `${kind}-end`, id });
+      } else if (part.type === "dynamic-tool") {
+        if (part.state === "input-streaming") {
+          chunks.push({ type: "tool-input-start", toolCallId: part.toolCallId, toolName: part.toolName, dynamic: true });
+          this.toolCallIdByIndex.set(contentIndex, part.toolCallId);
+          this.streamingToolById.set(part.toolCallId, { toolName: part.toolName, started: true, deltas: [] });
+        } else {
+          chunks.push(...this.toolInput(part.toolCallId, part.toolName, part.input));
+          if (part.state === "approval-requested") chunks.push(...this.approvalRequested(part.toolCallId, part.approval.id));
+          else if (part.state === "output-available") chunks.push({ type: "tool-output-available", toolCallId: part.toolCallId, output: part.output, preliminary: part.preliminary, dynamic: true });
+          else if (part.state === "output-error") chunks.push({ type: "tool-output-error", toolCallId: part.toolCallId, errorText: part.errorText, dynamic: true });
+          else if (part.state === "output-denied") chunks.push({ type: "tool-output-denied", toolCallId: part.toolCallId });
+        }
+      }
+      contentIndex += 1;
+    }
+    if (!hasStep) chunks.push({ type: "start-step" });
+    else if (!streaming) chunks.push({ type: "finish-step" });
+    return chunks;
+  }
+
   toolInput(
     toolCallId: string,
     toolName: string,
     input: unknown,
   ): UIMessageChunk[] {
-    const safe = safeInput(input);
+    const safe = safeToolInput(toolName, input, this.prepareToolInput);
     this.toolInputs.set(toolCallId, { toolName, input: safe });
     return [{
       type: "tool-input-available",
@@ -262,7 +346,10 @@ export class PiChunkEncoder {
     ];
   }
 
-  encode(event: AgentEvent): UIMessageChunk[] {
+  encode(
+    event: AgentEvent,
+    options: { readonly terminal?: boolean } = {},
+  ): UIMessageChunk[] {
     if (this.finished) return [];
     switch (event.type) {
       case "agent_start":
@@ -318,7 +405,7 @@ export class PiChunkEncoder {
       case "message_end":
         this.firstTurnStarted = false;
         return event.message.role === "assistant"
-          ? this.endAssistant(event.message)
+          ? this.endAssistant(event.message, options.terminal !== false)
           : [];
       case "agent_end":
       case "turn_end":
@@ -450,33 +537,36 @@ export class PiChunkEncoder {
       streaming.deltas.length = 0;
     }
     if (update.type === "toolcall_end") {
-      const input = safeInput(update.toolCall.arguments);
-      this.toolInputs.set(toolCallId, {
-        toolName: update.toolCall.name,
-        input,
-      });
-      chunks.push({
-        type: "tool-input-available",
+      chunks.push(...this.toolInput(
         toolCallId,
-        toolName: update.toolCall.name,
-        input,
-        dynamic: true,
-      });
+        update.toolCall.name,
+        update.toolCall.arguments,
+      ));
       this.pendingToolByIndex.delete(index);
       this.toolCallIdByIndex.delete(index);
     }
     return chunks;
   }
 
-  private endAssistant(message: AssistantMessage): UIMessageChunk[] {
+  private endAssistant(message: AssistantMessage, terminal = true): UIMessageChunk[] {
     this.pendingToolByIndex.clear();
     this.toolCallIdByIndex.clear();
     const chunks = this.closeOpenParts();
-    if (message.stopReason === "toolUse") {
+    if (message.stopReason === "toolUse" || !terminal) {
       chunks.push({ type: "finish-step" });
       return chunks;
     }
+    const outcome = classifyPiTerminalStopReason(message.stopReason);
+    if (outcome.outcome === "succeeded") chunks.push({ type: "finish-step" });
+    chunks.push(...this.finish(message));
+    return chunks;
+  }
+
+  /** Finalize the UI operation after its last model step has already closed. */
+  finish(message: Pick<AssistantMessage, "stopReason" | "timestamp" | "errorMessage">): UIMessageChunk[] {
+    if (this.finished) return [];
     this.finished = true;
+    const chunks: UIMessageChunk[] = [];
     const publicError = publicAssistantError(message.errorMessage);
     const terminal = classifyPiTerminalStopReason(message.stopReason);
     if (this.startedAt !== undefined) {
@@ -507,7 +597,6 @@ export class PiChunkEncoder {
       });
       return chunks;
     }
-    chunks.push({ type: "finish-step" });
     chunks.push({
       type: "finish",
       finishReason: terminal.finishReason ?? "other",
@@ -549,15 +638,7 @@ function projectedTool(
   call: ToolCall,
   approval?: PiToolApprovalView,
 ): DynamicToolUIPart {
-  const input = safeInput(call.arguments);
-  if (call.name === "ask_user" && typeof input.questions === "string") {
-    try {
-      const questions: unknown = JSON.parse(input.questions);
-      if (Array.isArray(questions)) input.questions = questions;
-    } catch {
-      // Preserve malformed legacy input for the normal unavailable state.
-    }
-  }
+  const input = safeToolInput(call.name, call.arguments);
   const base = {
     type: "dynamic-tool" as const,
     toolCallId: call.id,
@@ -601,15 +682,16 @@ export function piAssistantToUIMessage(
     readonly id: string;
     readonly metadata?: unknown;
     readonly approvals?: Readonly<Record<string, PiToolApprovalView | undefined>>;
+    readonly state?: "streaming" | "done";
   },
 ): UIMessage {
   const parts = message.content.flatMap(
     (content): Array<UIMessage["parts"][number]> => {
     if (content.type === "text") {
-      return [{ type: "text", text: content.text, state: "done" }];
+      return [{ type: "text", text: content.text, state: options.state ?? "done" }];
     }
     if (content.type === "thinking") {
-      return [{ type: "reasoning", text: content.thinking, state: "done" }];
+      return [{ type: "reasoning", text: content.thinking, state: options.state ?? "done" }];
     }
     if (content.type === "toolCall") {
       return [projectedTool(content, options.approvals?.[content.id])];
@@ -629,6 +711,7 @@ export function piAssistantToUIMessage(
 export function applyPiToolResult(
   message: UIMessage,
   result: ToolResultMessage,
+  options: { readonly preliminary?: boolean } = {},
 ): UIMessage {
   return {
     ...message,
@@ -658,7 +741,7 @@ export function applyPiToolResult(
             state: "output-available",
             input: part.input,
             output: toolOutput({ content: result.content, details: result.details }),
-            preliminary: false,
+            preliminary: options.preliminary ?? false,
             ...(approval ? { approval } : {}),
           };
     }),

package/src/{db/message-ui.repo.ts → conversation/repository.ts}

@@ -30,6 +30,10 @@ export class MessageUiRepository {
     `;
   }
 
+  delete(messageId: string): void {
+    this.sql`DELETE FROM pi_message_ui WHERE message_id = ${messageId}`;
+  }
+
   // 删除全部 Message UI 补充数据。
   // Transcript.clear 在清空标准会话时调用，并由上层事务把两类数据一起提交。
   // 该责任曾属于 RuntimeDatabase.clearAll，现在归 Transcript 所有；不能两处分别维护清理规则。

package/src/conversation/state.ts

@@ -0,0 +1,196 @@
+import type { ApprovalReceipt } from "../submission/contracts";
+import type { StoredSubmission } from "../submission/repository";
+import type { PendingApprovalSummary } from "../tools/runtime/approval/repository";
+import type { PiCanonicalUserInput } from "./message/contract";
+
+export type RuntimeLoadPhase = "config" | "assembly" | "mcp" | "pi";
+
+export type RuntimeActivity = "idle" | "working" | "needs-input";
+
+export interface RuntimeActivityProjection {
+  activity: RuntimeActivity;
+  /**
+   * 是否仍有 Agent Tool 子运行在执行。
+   *
+   * `activity` 三态互斥，表达不了「等人回应的同时后台还在跑」。Host 的列表需要
+   * 这两件事各自成立，所以它是一个独立维度，而不是第四种活动值。
+   */
+  backgroundWork: boolean;
+  revision: number;
+}
+
+/**
+ * Runtime 最近一次装载尝试的公开状态。
+ *
+ * `available` 与本次尝试分开表达：强制重载失败时，旧 Runtime 仍可能继续服务。
+ * 该状态由 Agents SDK 的 Agent state 同步给浏览器，不包含底层异常文本。
+ */
+export type RuntimeLoadState =
+  | {
+      status: "idle";
+      available: false;
+    }
+  | {
+      status: "loading";
+      phase: RuntimeLoadPhase;
+      available: boolean;
+      startedAt: number;
+      updatedAt: number;
+    }
+  | {
+      status: "ready";
+      available: true;
+      startedAt: number;
+      completedAt: number;
+    }
+  | {
+      status: "error";
+      phase: RuntimeLoadPhase;
+      available: boolean;
+      startedAt: number;
+      failedAt: number;
+    };
+
+export interface RuntimeQueuedSubmission {
+  submissionId: string;
+  messageId: string;
+  preview: string;
+  position: number;
+  createdAt: number;
+}
+
+export interface RuntimeTurnState {
+  activeSubmissionId?: string;
+  activeRequestId?: string;
+  activeMessageId?: string;
+  steerable: boolean;
+  hasPendingSteer: boolean;
+  queued: RuntimeQueuedSubmission[];
+}
+
+/**
+ * 本 Session 当前是否拒绝普通用户输入。
+ *
+ * 定时 Run 未结束时它独占输入:宿主据此禁用输入框并显示原因。
+ * 服务端准入用同一事实拒绝消息,所以客户端状态与后端判定不会漂移。
+ */
+export interface RuntimeInputLock {
+  /** 稳定原因码,由宿主/UI 决定文案。 */
+  reason: string;
+}
+
+/**
+ * 保存 Kernel 在当前会话里自己维护的审批状态。
+ *
+ * @remarks
+ * `RuntimeAgent` 把它作为 Agent state 的形状，并在审批记录变化时读写。
+ *
+ * 它故意不保存用户、Agent 或 Session 等业务身份，避免 Runtime 越过 Host 的归属边界。
+ *
+ * `Runtime`、`Kernel` 与 `Host` 等核心术语见 `../index.ts`。
+ */
+export interface RuntimeState {
+  /** 当前实例的 Runtime 装载状态；旧状态记录没有该字段时等同 `idle`。 */
+  runtimeLoad?: RuntimeLoadState;
+  /** 供 Host 列表持久化的粗粒度活动状态；Submission 与 Approval 仍是执行真相。 */
+  activity?: RuntimeActivityProjection;
+  approvals?: ApprovalReceipt[];
+  turn?: RuntimeTurnState;
+  /** 有值时普通输入被锁定,直到锁定的 Submission 进入终态。 */
+  inputLock?: RuntimeInputLock;
+}
+
+type SubmissionProjection = Pick<
+  StoredSubmission,
+  "submissionId" | "requestId" | "assistantMessageId" | "userMessageId" |
+  "queuedInputJson" | "createdAt"
+>;
+
+/** Rebuild client-visible activity from current facts without retaining lifecycle state. */
+export function projectRuntimeState(input: {
+  readonly approvals: readonly PendingApprovalSummary[];
+  readonly temporaryApprovals: readonly ApprovalReceipt[];
+  readonly running: SubmissionProjection | null | undefined;
+  readonly pending: readonly SubmissionProjection[];
+  readonly hasPendingApproval: (submissionId: string) => boolean;
+  readonly hasPendingInteraction: (submissionId: string) => boolean;
+  readonly hasPendingSteer: (submissionId: string) => boolean;
+  readonly hasRunningAgentTools: boolean;
+  /** A non-terminal scheduled Submission owns ordinary input until it ends. */
+  readonly hasUnfinishedScheduled?: boolean;
+  readonly previousState: RuntimeState;
+}): { state: RuntimeState; changed: boolean } {
+  const approvals: ApprovalReceipt[] = [
+    ...input.approvals.map((approval) => ({
+      executionId: approval.executionId,
+      source: approval.source as ApprovalReceipt["source"],
+      action: approval.toolName,
+      summary: approval.summary,
+      executionLevel: approval.executionLevel,
+      requiredExecutionLevel: approval.requiredExecutionLevel,
+      inputJson: approval.inputJson,
+      requestId: approval.requestId,
+    })),
+    ...input.temporaryApprovals,
+  ];
+  const current = input.running ?? input.pending[0];
+  const queued = (input.running ? input.pending : input.pending.slice(1)).map(
+    (submission, index): RuntimeQueuedSubmission => {
+      let preview = "Queued message";
+      if (submission.queuedInputJson) {
+        try {
+          const message = JSON.parse(submission.queuedInputJson) as PiCanonicalUserInput;
+          preview = (typeof message.content === "string" ? message.content :
+            message.content.flatMap((part) => part.type === "text" ? [part.text] : []).join(" "))
+            .trim().slice(0, 160) || preview;
+        } catch {
+          // The queue pump reports corrupt payloads when it activates the Submission.
+        }
+      }
+      return {
+        submissionId: submission.submissionId,
+        messageId: submission.userMessageId ?? submission.submissionId,
+        preview,
+        position: index + 1,
+        createdAt: submission.createdAt,
+      };
+    },
+  );
+  const turn: RuntimeTurnState = {
+    ...(current ? {
+      activeSubmissionId: current.submissionId,
+      activeMessageId: current.assistantMessageId,
+      ...(current.requestId ? { activeRequestId: current.requestId } : {}),
+    } : {}),
+    steerable: Boolean(current && !input.hasPendingApproval(current.submissionId)),
+    hasPendingSteer: Boolean(current && input.hasPendingSteer(current.submissionId)),
+    queued,
+  };
+  const activity: RuntimeActivity = approvals.length > 0 ||
+      (current && input.hasPendingInteraction(current.submissionId))
+    ? "needs-input"
+    : current || queued.length > 0 ? "working" : "idle";
+  const previousActivity = input.previousState.activity;
+  const nextActivity: RuntimeActivityProjection = previousActivity?.activity === activity &&
+      previousActivity.backgroundWork === input.hasRunningAgentTools
+    ? previousActivity
+    : {
+      activity,
+      backgroundWork: input.hasRunningAgentTools,
+      revision: (previousActivity?.revision ?? 0) + 1,
+    };
+  const inputLock: RuntimeInputLock | undefined = input.hasUnfinishedScheduled
+    ? { reason: "scheduled-run" }
+    : undefined;
+  const changed = input.previousState.approvals === undefined ||
+    JSON.stringify(input.previousState.approvals) !== JSON.stringify(approvals) ||
+    JSON.stringify(input.previousState.turn) !== JSON.stringify(turn) ||
+    JSON.stringify(input.previousState.inputLock) !== JSON.stringify(inputLock) ||
+    nextActivity !== previousActivity;
+  return {
+    state: changed
+      ? { ...input.previousState, activity: nextActivity, approvals, turn, inputLock }
+      : input.previousState,
+    changed,
+  };
+}

package/src/harness/index.ts

@@ -0,0 +1,7 @@
+export { openSessionHarness, SessionHarness } from "./session-harness";
+export type {
+  SessionHarnessLimits,
+  SessionHarnessOptions,
+  SessionHarnessRunResult,
+} from "./session-harness";
+export { prepareSubmissionOperation } from "./submission-operation";