@springbrand/agent-runtime 0.1.3-alpha.4 → 0.1.3-alpha.6

package/src/runtime.ts

@@ -45,12 +45,18 @@ import type {
   RuntimeState,
   RuntimeTurnState,
 } from "./kernel/state";
-import { RuntimeLoadTracker } from "./kernel/runtime-load";
+import {
+  RuntimeLoadTracker,
+  withRuntimeLoadTimeout,
+} from "./kernel/runtime-load";
 import {
   prepareRuntimeCandidate,
   type RuntimeAssemblyInput,
+  type RuntimeCandidate,
   type RuntimeSnapshot,
 } from "./runtime-assembler";
+import type { RuntimeAgentHooks } from "./runtime-definition";
+import type { RuntimeTurnEventsPort } from "./kernel/bindings";
 import { connectConfiguredMcpServers } from "./lib/mcp";
 import { installConsoleSink } from "./lib/telemetry-dev";
 import {
@@ -62,6 +68,7 @@ import {
   type PiCanonicalTranscriptSnapshot,
   type PiChatRecoveryData,
   type UIChatRequestBody,
+  type RequestedCapability,
   type PiDurableMutation,
   type PiRecoveryCommand,
   type PiRecoveryDecision,
@@ -171,6 +178,16 @@ function json(value: unknown): string {
   return JSON.stringify(value);
 }
 
+async function closeRuntimeGatewaySession(
+  session: RuntimeGatewaySession | undefined,
+  step: string,
+): Promise<void> {
+  if (!session) return;
+  await withRuntimeLoadTimeout(step, () => session.close()).catch(
+    () => undefined,
+  );
+}
+
 function assistantUsageEvent(
   eventId: string,
   submissionId: string,
@@ -221,6 +238,44 @@ function userContentKey(message: PiCanonicalUserInput): string {
   );
 }
 
+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 !== "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;
+}
+
 interface PendingTemporaryAgentApproval {
   receipt: ApprovalReceipt;
   resolve(decision: TemporaryAgentApprovalDecision): void;
@@ -257,6 +312,8 @@ export abstract class AgentRuntimeKernel<
   private runtimeRevision?: string;
   private runtimePi?: PreparedPiRuntime;
   private runtimeGatewaySession?: RuntimeGatewaySession;
+  private runtimeTurnEvents?: RuntimeTurnEventsPort;
+  private runtimeHooks?: RuntimeAgentHooks;
   private piAdapter?: PiRuntimeAdapter;
   private readonly transcript: PiRuntimeTranscript;
   private readonly submissions: SubmissionLifecycle<
@@ -462,11 +519,21 @@ export abstract class AgentRuntimeKernel<
   // 调用：生成 Agent 在首次启动或显式重载 Runtime key 时调用。
   // 原因：先完整 prepare 再替换 Snapshot，且活跃 Turn 期间禁止换 revision，可避免半装配和恢复时能力漂移。
   protected async initConfig(input: RuntimeAssemblyInput): Promise<void> {
-    const previous = this.runtimeSnapshot;
-    this.runtimeLoad.advance("assembly");
     const candidate = await prepareRuntimeCandidate(input);
-    const candidateSnapshot = candidate.snapshot;
+    await this.initCandidate(candidate);
+  }
+
+  private turnEventsPort(): RuntimeTurnEventsPort | undefined {
+    return this.runtimeTurnEvents ?? this.runtimeSnapshot?.bindings.turnEvents;
+  }
 
+  protected async initCandidate(candidate: RuntimeCandidate): Promise<void> {
+    this.runtimeTurnEvents =
+      candidate.turnEvents ?? candidate.snapshot.bindings.turnEvents;
+    this.runtimeHooks = candidate.hooks;
+    const previous = this.runtimeSnapshot;
+    const candidateSnapshot = candidate.snapshot;
+    this.runtimeLoad.advance("assembly");
     this.runtimeLoad.advance("mcp");
     await connectConfiguredMcpServers(
       this,
@@ -476,8 +543,15 @@ export abstract class AgentRuntimeKernel<
     let gatewaySession: RuntimeGatewaySession | undefined;
     if (candidateSnapshot.bindings.gateway) {
       try {
-        gatewaySession = await candidateSnapshot.bindings.gateway.open(
-          `${this.ctx.id.toString()}:${crypto.randomUUID()}`,
+        gatewaySession = await withRuntimeLoadTimeout(
+          "gateway.open",
+          () => candidateSnapshot.bindings.gateway!.open(
+            `${this.ctx.id.toString()}:${crypto.randomUUID()}`,
+          ),
+          {
+            onLateResult: (session) =>
+              closeRuntimeGatewaySession(session, "gateway.close.late"),
+          },
         );
       } catch {
         gatewayDegradations.push({
@@ -503,7 +577,7 @@ export abstract class AgentRuntimeKernel<
           ),
       });
     } catch (error) {
-      await gatewaySession?.close().catch(() => undefined);
+      await closeRuntimeGatewaySession(gatewaySession, "gateway.close.failed");
       throw error;
     }
     const revision = await this.hash(prepared.revisionDescriptor);
@@ -515,18 +589,23 @@ export abstract class AgentRuntimeKernel<
       this.submissions.isBusy();
     const parked = contested && this.db.everyUnfinishedSubmissionParked();
     if (contested && !parked) {
-      await gatewaySession?.close().catch(() => undefined);
+      await closeRuntimeGatewaySession(gatewaySession, "gateway.close.contested");
       throw new Error(
         "Cannot reload Runtime while a revision-pinned Pi Turn is active",
       );
     }
     const repin = parked
-      ? await this.prepareParkedSubmissionRepin(prepared, revision)
+      ? await withRuntimeLoadTimeout(
+          "parked-submission.repin",
+          () => this.prepareParkedSubmissionRepin(prepared, revision),
+        )
       : undefined;
     let activated = false;
     const previousGatewaySession = this.runtimeGatewaySession;
     try {
-      for (const guard of candidate.commitGuards) await guard();
+      for (const [index, guard] of candidate.commitGuards.entries()) {
+        await withRuntimeLoadTimeout(`commit-guard:${index}`, guard);
+      }
       if (candidateSnapshot.bindings.platform.telemetryConsole) {
         installConsoleSink();
       }
@@ -540,13 +619,19 @@ export abstract class AgentRuntimeKernel<
     } catch (error) {
       repin?.abort();
       if (activated && previous) this.pi.activate(previous);
-      await gatewaySession?.close().catch(() => undefined);
+      await closeRuntimeGatewaySession(gatewaySession, "gateway.close.aborted");
       throw error;
     }
-    await repin?.interrupt().catch((error) => {
-      console.error("[runtime-repin:interrupt-failed]", error);
-    });
-    await previousGatewaySession?.close().catch(() => undefined);
+    if (repin) {
+      await withRuntimeLoadTimeout(
+        "parked-submission.interrupt",
+        () => repin.interrupt(),
+      ).catch(() => undefined);
+    }
+    await closeRuntimeGatewaySession(
+      previousGatewaySession,
+      "gateway.close.previous",
+    );
 
     const degradations = prepared.degradations;
     if (degradations.length > 0) {
@@ -601,7 +686,7 @@ export abstract class AgentRuntimeKernel<
             async (created) => {
               await onCreated?.();
               try {
-                await this.assembly().bindings.turnEvents?.onApproval?.({
+                await this.turnEventsPort()?.onApproval?.({
                   submissionId: submission.submissionId,
                   approvalExecutionId: created.executionId,
                 });
@@ -727,7 +812,7 @@ export abstract class AgentRuntimeKernel<
   }
 
   private async drainRuntimeEvents(idempotentRetry = true): Promise<void> {
-    const turnEvents = this.runtimeSnapshot?.bindings.turnEvents;
+    const turnEvents = this.turnEventsPort();
     if (!turnEvents) return;
 
     let failed = false;
@@ -862,6 +947,41 @@ export abstract class AgentRuntimeKernel<
     return this.runtimeSnapshot;
   }
 
+  private async normalizeUIUserInput(
+    message: UIMessage & { role: "user" },
+  ): Promise<PiCanonicalUserInput> {
+    const capabilities = requestedCapabilitiesOf(message.metadata);
+    if (capabilities.length === 0) return this.pi.normalizeUserInput(message);
+
+    await this.ensureRuntimeReady();
+    const installedSkills = new Set(
+      this.assembly().bindings.skills.sources.map(({ name }) => name),
+    );
+    const context: string[] = [];
+    for (const capability of capabilities) {
+      if (capability.kind === "skill") {
+        if (!installedSkills.has(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.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 this.pi.normalizeUserInput(message, context.join("\n"));
+  }
+
   // 作用：把当前已安装的 Runtime Snapshot 投影成可序列化的调试视图。
   // 调用：Session facet 的 `getRuntimeAssembly` RPC。
   // 原因：UI 需要读取真实装配结果，而不是上层配置声明。
@@ -2010,7 +2130,9 @@ export abstract class AgentRuntimeKernel<
       continuation: recovery,
       assistantOrdinal,
       onRecord: (record) =>
-        this.persistAndBroadcastRecord(turn, record),
+        this.migratedSubmissions.has(submissionId)
+          ? undefined
+          : this.persistAndBroadcastRecord(turn, record),
       onTerminal: (intent) => {
         terminalIntent = intent;
         this.appendTerminalIntent(
@@ -2246,7 +2368,7 @@ export abstract class AgentRuntimeKernel<
         messages,
       }),
     );
-    const events = this.assembly().bindings.turnEvents;
+    const events = this.turnEventsPort();
     if (events) {
       try {
         await events.onResponse(
@@ -2395,7 +2517,7 @@ export abstract class AgentRuntimeKernel<
         ReturnType<AgentRuntimeKernel["submitMessage"]>
       >;
       try {
-        const normalized = this.pi.normalizeUserInput(latest);
+        const normalized = await this.normalizeUIUserInput(latest);
         submitted = await this.submitMessage(normalized, {
           requestId: event.id,
           idempotencyKey: event.id,
@@ -2480,6 +2602,18 @@ export abstract class AgentRuntimeKernel<
     return this.transcript.browserMessages();
   }
 
+  /** 读取当前 canonical transcript 中最后一条助手文本。 */
+  protected async latestAssistantText(): Promise<string | undefined> {
+    const message = [...await this.transcript.canonicalMessages()]
+      .reverse()
+      .find((entry): entry is AssistantMessage => entry.role === "assistant");
+    const text = message?.content
+      .flatMap((part) => part.type === "text" ? [part.text] : [])
+      .join("")
+      .trim();
+    return text || undefined;
+  }
+
   // #endregion
 
   // #region Runtime Extension Host 回环端口
@@ -2701,9 +2835,18 @@ export abstract class AgentRuntimeKernel<
       };
     }
 
-    const userMessage = this.pi.normalizeUserInput(
-      message as UIMessage & { role: "user" },
-    );
+    let userMessage: PiCanonicalUserInput;
+    try {
+      userMessage = await this.normalizeUIUserInput(
+        message as UIMessage & { role: "user" },
+      );
+    } catch (error) {
+      return {
+        kind: "rejected",
+        code: "invalid_message",
+        message: errorText(error),
+      };
+    }
     // 停在 interaction park 上的 Turn 一律按 steer 处理，哪怕客户端发的是 enqueue：
     // enqueue 要等本 Turn 结束，而本 Turn 正在等一个永远不会来的答案 —— 死锁。
     const parked = this.findInteractionParkedSubmission();
@@ -3194,6 +3337,24 @@ export abstract class AgentRuntimeKernel<
     await this.broadcastApprovals();
   }
 
+  async _cfDetachedNotifyFinish(
+    run: AgentToolRunInfo,
+    result: AgentToolLifecycleResult,
+  ): Promise<void> {
+    const outcome = result.status === "completed"
+      ? result.summary ?? "Completed without a result."
+      : result.error ?? `Background run ${result.status}.`;
+    await this.submitPrompt(
+      [
+        "A background sub-agent run has finished.",
+        `runId: ${run.runId}`,
+        `status: ${result.status}`,
+        `result: ${outcome}`,
+      ].join("\n"),
+      { idempotencyKey: `detached-agent-tool:${run.runId}:${result.status}` },
+    );
+  }
+
   // 作用：把审批、队列和 Session 活动投影到 Agent 可广播状态。
   // 调用：启动、准入、审批变化、interaction 变化、子运行变化和 Turn 完成时调用。
   // 原因：这些都是可重建的 UI 投影，相同内容不重复 `setState`，投影失败也不能阻断执行。
@@ -3306,8 +3467,7 @@ export abstract class AgentRuntimeKernel<
           turn,
         });
       }
-      const projection = this.runtimeSnapshot?.bindings.turnEvents
-        ?.onActivityChanged?.(nextActivity);
+      const projection = this.turnEventsPort()?.onActivityChanged?.(nextActivity);
       if (projection) {
         this.ctx.waitUntil(
           projection.catch(() => undefined),

package/src/tool-registry.ts

@@ -0,0 +1,143 @@
+import type { ExecutionLevel } from "./lib/execution-level";
+import type {
+  RuntimeMemoryPort,
+  WorkspacePort,
+} from "./kernel/bindings";
+import type { RuntimeExtensionConfig } from "./kernel/extensions";
+import type { RuntimeDegradation } from "./kernel/degradation";
+import type { PiToolCandidate } from "./pi/tool/compiler";
+
+/** Tool Surface 筛选策略（不含 Manifest deny 列表）。 */
+export interface ToolSurfaceSelectionPolicy {
+  readonly allowsTool?: (name: string) => boolean;
+  readonly allowsExtension?: (extension: RuntimeExtensionConfig) => boolean;
+}
+
+/** 模型调用 Tool 时传给 `execute` 的上下文。 */
+export interface ToolContext {
+  readonly toolCallId: string;
+  readonly signal: AbortSignal;
+}
+
+/** Definition 作者声明的一个 Tool。 */
+export interface ToolSpec {
+  readonly label: string;
+  readonly description: string;
+  readonly parameters: unknown;
+  readonly requiredExecutionLevel: ExecutionLevel;
+  /** Require a fresh human decision for every call, regardless of execution level. */
+  readonly alwaysRequiresApproval?: boolean;
+  readonly execute: (
+    input: unknown,
+    ctx: ToolContext,
+  ) => Promise<unknown>;
+}
+
+/** 一次装配声明的全部 Tool，键即模型可见的工具名。 */
+export type ToolRegistry = Record<string, ToolSpec>;
+
+export function emptyToolRegistry(): ToolRegistry {
+  return {};
+}
+
+export function mergeToolRegistries(...registries: ToolRegistry[]): ToolRegistry {
+  const merged: ToolRegistry = {};
+  for (const registry of registries) {
+    for (const [name, spec] of Object.entries(registry)) {
+      if (name in merged) {
+        throw new Error(`Duplicate Runtime Tool: ${name}`);
+      }
+      merged[name] = spec;
+    }
+  }
+  return merged;
+}
+
+export function toolRegistryFromPiCandidates(
+  candidates:
+    | readonly PiToolCandidate[]
+    | Record<string, PiToolCandidate>,
+): ToolRegistry {
+  const list = Array.isArray(candidates)
+    ? candidates
+    : Object.values(candidates);
+  const registry: ToolRegistry = {};
+  for (const candidate of list) {
+    const name = candidate.tool.name;
+    if (!name.trim()) {
+      throw new Error("Pi Tool name must not be empty");
+    }
+    registry[name] = piCandidateToToolSpec(candidate);
+  }
+  return registry;
+}
+
+export function piCandidateToToolSpec(candidate: PiToolCandidate): ToolSpec {
+  const name = candidate.tool.name;
+  return {
+    label: candidate.tool.label ?? name,
+    description: candidate.tool.description,
+    parameters: candidate.tool.parameters,
+    requiredExecutionLevel: candidate.requiredExecutionLevel,
+    ...(candidate.alwaysRequiresApproval
+      ? { alwaysRequiresApproval: true }
+      : {}),
+    execute: async (input, ctx) => {
+      const execute = candidate.tool.execute;
+      if (typeof execute !== "function") {
+        throw new Error(`Tool "${name}" is not executable`);
+      }
+      const result = await execute(
+        ctx.toolCallId,
+        input,
+        ctx.signal,
+        undefined,
+      );
+      return result.details ?? result;
+    },
+  };
+}
+
+/** Kernel 绑定仍需要的执行后端；不出现在 Definition 公开类型里。 */
+export interface RuntimeToolBindings {
+  readonly workspace?: WorkspacePort;
+  readonly memory?: RuntimeMemoryPort;
+}
+
+/**
+ * Worker `tools()` 可返回纯注册表，或附带 Kernel 绑定与降级信息。
+ */
+export interface ToolAssemblyResult {
+  readonly tools: ToolRegistry;
+  readonly bindings?: RuntimeToolBindings;
+  readonly memoryProfile?: import("./kernel/profile").RuntimeMemoryProfile;
+  readonly enabledSubagents?: readonly string[];
+  readonly degradations?: readonly RuntimeDegradation[];
+  readonly surfacePolicy?: ToolSurfaceSelectionPolicy;
+  readonly commitGuard?: () => Promise<void>;
+  /** 释放本次装配创建的外部资源；临时 Agent 终止后由 Runtime 调用。 */
+  readonly dispose?: () => Promise<void>;
+}
+
+export function normalizeToolAssembly(
+  input: ToolRegistry | ToolAssemblyResult,
+): ToolAssemblyResult {
+  if ("tools" in input && typeof input.tools === "object" && input.tools !== null) {
+    return input as ToolAssemblyResult;
+  }
+  return { tools: input as ToolRegistry };
+}
+
+/** @deprecated 使用 `ToolSpec`。 */
+export type PlatformToolSpec = ToolSpec;
+
+/** @deprecated 使用 `ToolContext`。 */
+export type PlatformToolContext = ToolContext;
+
+/** @deprecated 使用 `ToolRegistry`。 */
+export type PlatformToolRegistry = ToolRegistry;
+
+/** @deprecated 使用 `emptyToolRegistry`。 */
+export function emptyPlatformToolRegistry(): ToolRegistry {
+  return emptyToolRegistry();
+}