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

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;
 
@@ -87,7 +91,6 @@ export function subagentPiToolCandidates(
     };
     return {
       owner: `subagent:${type.name}`,
-      authorized: true,
       requiredExecutionLevel: "safe",
       tool,
     };
@@ -138,7 +141,6 @@ export function subagentPiToolCandidates(
   };
   candidates.push({
     owner: "subagent:background",
-    authorized: true,
     requiredExecutionLevel: "low",
     summary: "Dispatch a background sub-agent",
     source: "action",
@@ -146,3 +148,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/web-fetch.ts

@@ -272,7 +272,6 @@ export function webFetchPiToolCandidate(): PiToolCandidate {
 
   return {
     owner: "runtime-base",
-    authorized: true,
     requiredExecutionLevel: "safe",
     source: "action",
     tool,

package/src/pi/tool/web-search/web-search.ts

@@ -119,7 +119,6 @@ export function webSearchPiToolCandidate(
   };
   return {
     owner: "runtime-base",
-    authorized: true,
     requiredExecutionLevel: "safe",
     source: "action",
     tool,

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[] {
@@ -283,13 +288,11 @@ export function workspacePiToolCandidates(
   return [
     ...[read, write, edit, list, find, grep, remove].map((tool) => ({
       owner: "workspace",
-      authorized: true,
       requiredExecutionLevel: "safe" as const,
       tool,
     })),
     {
       owner: "workspace",
-      authorized: true,
       requiredExecutionLevel: "high" as const,
       summary: "Run a Bash script over Workspace files",
       source: "action" as const,
@@ -298,6 +301,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
@@ -464,35 +472,35 @@ export function sandboxPiToolCandidates(
   return [
     {
       owner: "sandbox",
-      authorized: true,
       requiredExecutionLevel: "high",
       tool: exec,
     },
     {
       owner: "sandbox",
-      authorized: true,
       requiredExecutionLevel: "high",
       tool: startProcess,
     },
     {
       owner: "sandbox",
-      authorized: true,
       requiredExecutionLevel: "safe",
       tool: processLogs,
     },
     {
       owner: "sandbox",
-      authorized: true,
       requiredExecutionLevel: "high",
       tool: stopProcess,
     },
     {
       owner: "sandbox",
-      authorized: true,
       requiredExecutionLevel: "high",
       tool: publishFiles,
     },
   ];
 }
 
+/** 从 {@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>;