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

package/src/pi/message/conversion.ts

@@ -26,6 +26,7 @@ function attachmentText(
 
 function userContent(
   parts: ReadonlyArray<UIMessage["parts"][number]>,
+  privateContext?: string,
 ): UserMessage["content"] {
   const content: Exclude<UserMessage["content"], string> = [];
   for (const part of parts) {
@@ -46,16 +47,23 @@ function userContent(
     }
   }
   if (content.length === 0) throw new Error("User message content is required");
+  if (privateContext) {
+    content.unshift({
+      type: "text",
+      text: `[Agent private context]\n${privateContext}\n[/Agent private context]`,
+    });
+  }
   return content;
 }
 
 /** Convert an official user UIMessage into canonical Pi model input. */
 export function uiUserMessageToPi(
   message: UIMessage & { readonly role: "user" },
+  privateContext?: string,
 ): UserMessage {
   return {
     role: "user",
-    content: userContent(message.parts),
+    content: userContent(message.parts, privateContext),
     timestamp: timestampOf(message),
   };
 }

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

@@ -248,10 +248,12 @@ function describeTools(candidates: readonly PiToolCandidate[]) {
       name: candidate.tool.name,
       owner: candidate.owner,
       label: candidate.tool.label,
-      description:
-        candidate.tool.description ?? candidate.tool.label,
+      description: candidate.tool.description ?? candidate.tool.label,
       parameters: candidate.tool.parameters,
       requiredExecutionLevel: candidate.requiredExecutionLevel,
+      ...(candidate.alwaysRequiresApproval
+        ? { alwaysRequiresApproval: true }
+        : {}),
       ...(candidate.source ? { source: candidate.source } : {}),
       retry: piToolRetryPolicy(candidate),
     }))

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

@@ -107,8 +107,11 @@ export class PiRuntimeAdapter {
    * 实现理由：转换只生成 Pi UserMessage 的 content 和 timestamp，原始浏览器视图由 transcript sidecar 另行保存。
    * 不要把 UI id、metadata 或原始 part 结构并入 canonical message。
    */
-  normalizeUserInput(input: UIMessage & { role: "user" }) {
-    return uiUserMessageToPi(input);
+  normalizeUserInput(
+    input: UIMessage & { role: "user" },
+    privateContext?: string,
+  ) {
+    return uiUserMessageToPi(input, privateContext);
   }
 
   resolveApiKey(
@@ -209,6 +212,7 @@ export class PiRuntimeAdapter {
 }
 
 export type {
+  RequestedCapability,
   UIChatRequestBody,
 } from "../message";
 export type { PiToolApproval } from "../turn";

package/src/pi/tool/base.ts

@@ -8,6 +8,10 @@ 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";
 
@@ -271,3 +275,16 @@ export function memoryPiToolCandidate(
     tool,
   };
 }
+
+/** 从 Memory Port 生成 `set_context` Tool。 */
+export function createMemoryTools(
+  memory: RuntimeMemoryPort,
+  profile: Pick<
+    RuntimeMemoryProfile,
+    "memoryTokens" | "preferencesTokens"
+  >,
+): ToolRegistry {
+  return toolRegistryFromPiCandidates([
+    memoryPiToolCandidate(memory, profile),
+  ]);
+}

package/src/pi/tool/core.ts

@@ -12,6 +12,10 @@ import { serializeOutput } from "../../lib/artifacts";
 import type { PiLoadedExtension } from "../assembly/extensions";
 import { aiToolToPi } from "./ai-adapter";
 import type { PiToolCandidate } from "./compiler";
+import {
+  toolRegistryFromPiCandidates,
+  type ToolRegistry,
+} from "../../tool-registry";
 
 // 本文件沿用 `../../index.ts` 入口定义的 Extension、Port 和 Tool Candidate 术语。
 
@@ -178,4 +182,13 @@ export function codeExecutionPiToolCandidate(
   };
 }
 
+/** 从 Codemode Runtime Port 生成 `execute` Tool。 */
+export function createCodeExecutionTool(
+  runtime: RuntimeCodeExecutionPort,
+): ToolRegistry {
+  return toolRegistryFromPiCandidates([
+    codeExecutionPiToolCandidate(runtime),
+  ]);
+}
+
 // #endregion

package/src/pi/tool/schedule.ts

@@ -10,6 +10,10 @@ import type {
 import type { ScheduleSpec } from "../../kernel/receipts";
 import { serializeOutput } from "../../lib/artifacts";
 import type { PiToolCandidate } from "./compiler";
+import {
+  toolRegistryFromPiCandidates,
+  type ToolRegistry,
+} from "../../tool-registry";
 
 const scheduleTriggerParameters = Type.Union([
   Type.Object({
@@ -240,3 +244,10 @@ export function schedulePiToolCandidates(
     ),
   ];
 }
+
+/** 从 {@link RuntimeSchedulePort} 生成定时任务 Tool 集。 */
+export function createScheduleTools(
+  schedule: RuntimeSchedulePort,
+): ToolRegistry {
+  return toolRegistryFromPiCandidates(schedulePiToolCandidates(schedule));
+}

package/src/pi/tool/subagent.ts

@@ -4,6 +4,10 @@ import type { RuntimeSubagentPort } from "../../kernel/bindings";
 import { AGENT_TYPES } from "../../layers/orchestration/subagents/agent-types/registry";
 import { serializeOutput } from "../../lib/artifacts";
 import type { PiToolCandidate } from "./compiler";
+import {
+  toolRegistryFromPiCandidates,
+  type ToolRegistry,
+} from "../../tool-registry";
 
 const BACKGROUND_MAX_BUDGET_MS = 10 * 60 * 1_000;
 
@@ -146,3 +150,13 @@ export function subagentPiToolCandidates(
   });
   return candidates;
 }
+
+/** 从 {@link RuntimeSubagentPort} 生成已启用 SubAgent Tool 集。 */
+export function createSubagentTools(
+  subagents: RuntimeSubagentPort | undefined,
+  enabledSubagents: readonly string[],
+): ToolRegistry {
+  return toolRegistryFromPiCandidates(
+    subagentPiToolCandidates(subagents, enabledSubagents),
+  );
+}

package/src/pi/tool/workspace-sandbox.ts

@@ -21,6 +21,10 @@ import type {
 import { serializeOutput } from "../../lib/artifacts";
 import { aiToolToPi } from "./ai-adapter";
 import type { PiToolCandidate } from "./compiler";
+import {
+  toolRegistryFromPiCandidates,
+  type ToolRegistry,
+} from "../../tool-registry";
 
 // #region Shared Pi result helpers
 
@@ -145,6 +149,7 @@ function serializeByPath<T>(
  *
  * `Pi`、`Port` 与“候选工具”等项目核心术语见 `../../index.ts`。
  */
+/** Pi 编译路径：从 {@link WorkspacePort} 生成标准 workspace 文件 Tool 候选项。 */
 export function workspacePiToolCandidates(
   workspace: WorkspacePort,
 ): PiToolCandidate[] {
@@ -298,6 +303,11 @@ export function workspacePiToolCandidates(
   ];
 }
 
+/** 从 {@link WorkspacePort} 生成标准 workspace 文件 Tool 集（read / write / edit …）。 */
+export function createWorkspaceTools(workspace: WorkspacePort): ToolRegistry {
+  return toolRegistryFromPiCandidates(workspacePiToolCandidates(workspace));
+}
+
 // #endregion
 
 // #region Sandbox tools
@@ -495,4 +505,9 @@ export function sandboxPiToolCandidates(
   ];
 }
 
+/** 从 {@link RuntimeSandboxPort} 生成 Sandbox Tool 集。 */
+export function createSandboxTools(sandbox: RuntimeSandboxPort): ToolRegistry {
+  return toolRegistryFromPiCandidates(sandboxPiToolCandidates(sandbox));
+}
+
 // #endregion

package/src/runtime-agent-context.ts

@@ -0,0 +1,112 @@
+import type {
+  AgentToolRunStatus,
+  ChatCapableAgentClass,
+  RunAgentToolOptions,
+} from "agents";
+import type { ExecutionLevel } from "./lib/execution-level";
+import type { RuntimeConfigUpdateResult } from "./kernel/runtime-config";
+import type {
+  TemporaryAgentRequest,
+  TemporaryAgentRunContext,
+} from "./layers/orchestration/temporary-agent/core";
+
+/**
+ * 描述 Agent 寻址路径中的一级父子节点。
+ *
+ * @remarks
+ * Cloudflare Agents SDK 用 `parentPath` 暴露根节点到直接父节点的路径。
+ *
+ * 调用方通常只读取，不应自行构造后写回 SDK。
+ */
+export interface RuntimeAgentPathStep {
+  className: string;
+  name: string;
+}
+
+/**
+ * 表示一次 Agent Tool 执行返回给 Runtime 的稳定字段。
+ *
+ * @remarks
+ * Subagent 端口在调用 `RuntimeAgentConfigContext.runAgentTool` 后读取它。
+ *
+ * 这里只保留 Runtime 需要的结果，避免把 SDK 内部运行对象暴露给应用。
+ */
+export interface RuntimeAgentToolResult {
+  status: string;
+  runId: string;
+  output?: unknown;
+  summary?: string;
+  error?: string;
+}
+
+export type RuntimeAgentRole = "primary" | "temporary";
+
+/**
+ * 这是应用创建 Config 时唯一可以接触的 Agent 实例能力。
+ *
+ * 身份通过实时 getter 暴露。
+ */
+export interface RuntimeAgentConfigContext<
+  Env extends Cloudflare.Env = Cloudflare.Env,
+> {
+  /** 读取当前 Durable Object 的状态句柄。 */
+  readonly ctx: DurableObjectState;
+  /** 读取当前 Worker 的环境绑定。 */
+  readonly env: Env;
+  /** 读取当前 Agent 实例名称。 */
+  readonly name: string;
+  /** 读取从根节点到直接父节点的 Agent 路径。 */
+  readonly parentPath: readonly RuntimeAgentPathStep[];
+  /** Runtime 根据 Agent facet 父子关系自动判定，不是外部配置项。 */
+  readonly role: RuntimeAgentRole;
+  /**
+   * 通过当前 Agent 调用一个受 SDK 管理的子 Agent Tool。
+   *
+   * @remarks
+   * subagent 端口在父 Agent 需要保留子运行状态、事件和取消边界时调用。
+   */
+  runAgentTool(
+    agentClass: ChatCapableAgentClass,
+    options: RunAgentToolOptions<unknown>,
+  ): Promise<RuntimeAgentToolResult>;
+  /**
+   * 清理符合年龄和状态条件的 SDK 子运行记录。
+   */
+  clearAgentToolRuns(options: {
+    olderThan: number;
+    status: AgentToolRunStatus[];
+  }): Promise<void>;
+  /** 读取当前已装配 User Agent 的执行档位。 */
+  executionLevel(): ExecutionLevel;
+  /**
+   * 在当前 Session Runtime 中执行一个仅对本次调用存活的临时 Agent。
+   */
+  runTemporaryAgent(
+    request: TemporaryAgentRequest,
+    context: TemporaryAgentRunContext,
+  ): Promise<string>;
+}
+
+export interface RuntimeAgentPlanningContext<
+  Env extends Cloudflare.Env = Cloudflare.Env,
+  Command = never,
+  Change = never,
+> extends RuntimeAgentConfigContext<Env> {
+  /** 仅可变 Definition 提供；Host Tool 用它复用生成类的更新与重载编排。 */
+  readonly updateConfig?: (
+    command: Command,
+  ) => Promise<RuntimeConfigUpdateResult<Change>>;
+}
+
+/** 装配、Hook 与 Port 准备共用的 Agent 上下文。 */
+export type RuntimeAssemblyContext<
+  Env extends Cloudflare.Env = Cloudflare.Env,
+  Command = never,
+  Change = never,
+> = RuntimeAgentPlanningContext<Env, Command, Change>;
+
+export type RuntimeAgentContext<
+  Env extends Cloudflare.Env = Cloudflare.Env,
+  Command = never,
+  Change = never,
+> = RuntimeAgentPlanningContext<Env, Command, Change>;