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

package/src/runtime.ts

@@ -49,8 +49,11 @@ import { RuntimeLoadTracker } 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 +65,7 @@ import {
   type PiCanonicalTranscriptSnapshot,
   type PiChatRecoveryData,
   type UIChatRequestBody,
+  type RequestedCapability,
   type PiDurableMutation,
   type PiRecoveryCommand,
   type PiRecoveryDecision,
@@ -221,6 +225,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 +299,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 +506,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,
@@ -601,7 +655,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 +781,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 +916,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 需要读取真实装配结果，而不是上层配置声明。
@@ -2246,7 +2335,7 @@ export abstract class AgentRuntimeKernel<
         messages,
       }),
     );
-    const events = this.assembly().bindings.turnEvents;
+    const events = this.turnEventsPort();
     if (events) {
       try {
         await events.onResponse(
@@ -2395,7 +2484,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 +2569,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 +2802,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 +3304,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 +3434,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();
+}