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

package/src/{db/agent-tool.repo.ts → tools/subagent/repository.ts}

@@ -5,7 +5,7 @@ export class AgentToolRepository {
   // 保存当前 Agent SQLite 的查询入口。
   // RuntimeDatabase 构造时调用，活动投影随后通过这个 Repository 读取子运行。
   // 把存储绑定留在构造阶段，避免每次读取都传入可能属于其他 Agent 的 sql。
-  constructor(private readonly sql: SqlTaggedTemplate) {}
+  constructor(private readonly sql: SqlTaggedTemplate) { }
 
   // 是否仍有 Agent Tool 子运行在执行。
   // 活动投影在重算 activity 时调用，判定只在这里做一次。

package/src/{kernel/subagent-runtime.ts → tools/subagent/runtime.ts}

@@ -1,4 +1,4 @@
-import type { RuntimeSubagentUsageMetrics } from "./submission-authority";
+import type { RuntimeSubagentUsageMetrics } from "./authority";
 
 export interface RuntimeSubagentRunMetadata {
   readonly submissionId: string;

package/src/tools/subagent/temporary/approvals.ts

@@ -0,0 +1,123 @@
+import type { ApprovalDecision, ApprovalReceipt } from "../../../submission/contracts";
+import type { RuntimeTelemetryCoordinator } from "../../../telemetry/coordinator";
+import type { TemporaryAgentApprovalDecision, TemporaryAgentApprovalRequest } from "./core";
+
+interface PendingApproval {
+  receipt: ApprovalReceipt;
+  submissionId?: string;
+  toolCallId: string;
+  resolve(decision: TemporaryAgentApprovalDecision): void;
+}
+
+/** Human decisions belong to the temporary execution and expire with it. */
+export class TemporaryAgentApprovals {
+  private readonly pending = new Map<string, PendingApproval>();
+
+  constructor(private readonly options: {
+    capture: RuntimeTelemetryCoordinator["capture"];
+    onChanged(): Promise<void>;
+  }) { }
+
+  find(executionId: string): ApprovalReceipt | null {
+    return this.pending.get(executionId)?.receipt ?? null;
+  }
+
+  list(): ApprovalReceipt[] {
+    return [...this.pending.values()].map(({ receipt }) => receipt);
+  }
+
+  request(
+    request: TemporaryAgentApprovalRequest,
+    submissionId?: string,
+  ): Promise<TemporaryAgentApprovalDecision> {
+    if (this.pending.has(request.executionId)) {
+      return Promise.reject(new Error(
+        `temporary agent approval already pending: ${request.executionId}`,
+      ));
+    }
+    const summary = `${request.subagentName} requests ${request.toolName}`;
+    return new Promise((resolve, reject) => {
+      const pending: PendingApproval = {
+        receipt: {
+          executionId: request.executionId,
+          source: "temporary-agent",
+          action: request.toolName,
+          summary,
+          executionLevel: request.executionLevel,
+          requiredExecutionLevel: request.requiredExecutionLevel,
+          inputJson: JSON.stringify(request.input ?? null),
+          requestId: request.requestId,
+        },
+        submissionId,
+        toolCallId: request.toolCallId,
+        resolve,
+      };
+      this.pending.set(request.executionId, pending);
+      if (submissionId) {
+        this.options.capture("approvalRequested", {
+          submissionId,
+          toolCallId: request.toolCallId,
+          executionId: request.executionId,
+          toolName: request.toolName,
+          summary,
+          input: request.input,
+        });
+      }
+      void this.options.onChanged().catch((error) => {
+        if (this.pending.get(request.executionId) === pending) {
+          this.pending.delete(request.executionId);
+        }
+        reject(error);
+      });
+    });
+  }
+
+  async cancel(
+    executionId: string,
+    reason = "temporary agent was cancelled",
+  ): Promise<{ ok: boolean }> {
+    return this.settle(executionId, { approved: false, reason }, "cancelled");
+  }
+
+  /** Undefined leaves ordinary durable Tool approvals to their fact owner. */
+  async decide(
+    executionId: string,
+    decision: ApprovalDecision,
+  ): Promise<{ ok: boolean } | undefined> {
+    if (!this.pending.has(executionId)) return undefined;
+    if (decision.decision === "allow_level") {
+      throw new Error(
+        "allow_level must be applied by the User Agent Host before resuming the Tool",
+      );
+    }
+    return this.settle(
+      executionId,
+      decision.decision === "allow_once"
+        ? { approved: true }
+        : { approved: false, reason: decision.reason },
+      decision.decision === "allow_once" ? "approved" : "rejected",
+    );
+  }
+
+  private async settle(
+    executionId: string,
+    result: TemporaryAgentApprovalDecision,
+    decision: "approved" | "rejected" | "cancelled",
+  ): Promise<{ ok: boolean }> {
+    const pending = this.pending.get(executionId);
+    if (!pending) return { ok: false };
+    this.pending.delete(executionId);
+    pending.resolve(result);
+    if (pending.submissionId) {
+      this.options.capture("approvalDecided", {
+        submissionId: pending.submissionId,
+        toolCallId: pending.toolCallId,
+        executionId,
+        decision,
+        ...(result.reason ? { reason: result.reason } : {}),
+      });
+    }
+    await this.options.onChanged();
+    return { ok: true };
+  }
+}

package/src/{layers/orchestration/temporary-agent/core.ts → tools/subagent/temporary/coordinator.ts}

@@ -1,55 +1,26 @@
-import type { ExecutionLevel } from "../../../lib/execution-level";
+import type { TemporaryAgentExecutor, TemporaryAgentRequest } from "./core";
 
-export const TEMPORARY_AGENT_LAUNCH_KEY =
-  "universal-agent:temporary-agent-launch";
-
-export interface TemporaryAgentRequest {
-  subagentName: string;
-  instructions: string;
-  task: string;
-}
-
-export interface TemporaryAgentLaunch<Config = unknown>
-  extends TemporaryAgentRequest {
-  runtimeKey: string;
-  config: Config;
-  executionLevel: ExecutionLevel;
-}
-
-export interface TemporaryAgentRunContext {
-  signal: AbortSignal;
-  requestId: string;
-  toolCallId: string;
-}
-
-/**
- * 启动一个临时 Agent，并在它完整收尾后返回最终文本。
- *
- * @remarks
- * `TemporaryAgentCoordinator.run` 在获得并发槽位后调用；实现方应把子运行和外部资源清理收口到同一个 Promise。
- *
- * 协调器只依赖这个函数而不依赖 Durable Object、UI 或具体 Agent SDK，避免把基础设施生命周期写进并发规则。
- *
- * Agent 和 Runtime 的术语见 `src/index.ts`。
- */
-export type TemporaryAgentExecutor = (
-  request: TemporaryAgentRequest,
-) => Promise<string>;
+export type TemporaryAgentLifecycleEvent = {
+  type: "started";
+  request: TemporaryAgentRequest;
+  occurredAt: number;
+} | {
+  type: "finished";
+  outcome: "completed" | "failed" | "cancelled";
+  durationMs: number;
+  occurredAt: number;
+  output?: string;
+  error?: unknown;
+};
 
-export interface TemporaryAgentApprovalRequest {
-  executionId: string;
-  subagentName: string;
-  requestId: string;
-  toolCallId: string;
-  toolName: string;
-  executionLevel: ExecutionLevel;
-  requiredExecutionLevel: ExecutionLevel;
-  input: unknown;
-}
+type TemporaryAgentObserver = (event: TemporaryAgentLifecycleEvent) => void;
 
-export interface TemporaryAgentApprovalDecision {
-  approved: boolean;
-  reason?: string;
+function observe(observer: TemporaryAgentObserver | undefined, event: TemporaryAgentLifecycleEvent): void {
+  try {
+    observer?.(event);
+  } catch {
+    // Observation must not fail a child or prevent releasing its execution slot.
+  }
 }
 
 // 作用：去掉临时 Agent 请求三个字段的首尾空白，并拒绝空值。
@@ -95,13 +66,34 @@ export class TemporaryAgentCoordinator {
     request: TemporaryAgentRequest,
     execute: TemporaryAgentExecutor,
     signal?: AbortSignal,
+    observer?: TemporaryAgentObserver,
   ): Promise<string> {
     const normalized = normalizeRequest(request);
     await this.acquire(signal);
+    const startedAt = Date.now();
+    observe(observer, { type: "started", request: normalized, occurredAt: startedAt });
     try {
       const text = (await execute(normalized)).trim();
       if (!text) throw new Error("temporary agent final text must not be blank");
+      const occurredAt = Date.now();
+      observe(observer, {
+        type: "finished",
+        outcome: "completed",
+        output: text,
+        durationMs: Math.max(0, occurredAt - startedAt),
+        occurredAt,
+      });
       return text;
+    } catch (error) {
+      const occurredAt = Date.now();
+      observe(observer, {
+        type: "finished",
+        outcome: signal?.aborted ? "cancelled" : "failed",
+        error,
+        durationMs: Math.max(0, occurredAt - startedAt),
+        occurredAt,
+      });
+      throw error;
     } finally {
       this.release();
     }

package/src/tools/subagent/temporary/core.ts

@@ -0,0 +1,53 @@
+import type { ExecutionLevel } from "../../../lib/execution-level";
+
+export const TEMPORARY_AGENT_LAUNCH_KEY =
+  "universal-agent:temporary-agent-launch";
+
+export interface TemporaryAgentRequest {
+  subagentName: string;
+  instructions: string;
+  task: string;
+}
+
+export interface TemporaryAgentLaunch<Config = unknown>
+  extends TemporaryAgentRequest {
+  runtimeKey: string;
+  config: Config;
+  executionLevel: ExecutionLevel;
+}
+
+export interface TemporaryAgentRunContext {
+  signal: AbortSignal;
+  requestId: string;
+  toolCallId: string;
+}
+
+/**
+ * 启动一个临时 Agent，并在它完整收尾后返回最终文本。
+ *
+ * @remarks
+ * `TemporaryAgentCoordinator.run` 在获得并发槽位后调用；实现方应把子运行和外部资源清理收口到同一个 Promise。
+ *
+ * 协调器只依赖这个函数而不依赖 Durable Object、UI 或具体 Agent SDK，避免把基础设施生命周期写进并发规则。
+ *
+ * Agent 和 Runtime 的术语见 `src/index.ts`。
+ */
+export type TemporaryAgentExecutor = (
+  request: TemporaryAgentRequest,
+) => Promise<string>;
+
+export interface TemporaryAgentApprovalRequest {
+  executionId: string;
+  subagentName: string;
+  requestId: string;
+  toolCallId: string;
+  toolName: string;
+  executionLevel: ExecutionLevel;
+  requiredExecutionLevel: ExecutionLevel;
+  input: unknown;
+}
+
+export interface TemporaryAgentApprovalDecision {
+  approved: boolean;
+  reason?: string;
+}

package/src/{layers/orchestration/temporary-agent → tools/subagent/temporary}/runner.ts

@@ -1,4 +1,4 @@
-import type { RuntimeExtensionConfig } from "../../../kernel/extensions";
+import type { RuntimeExtensionConfig } from "../../../context/extension/contracts";
 
 const BLOCKED_TOOLS = new Set([
   "dispatch_background",

package/src/{layers/orchestration/temporary-agent → tools/subagent/temporary}/workspace.ts

@@ -1,7 +1,4 @@
-import type {
-  WorkspaceFileInfo,
-  WorkspacePort,
-} from "../../../kernel/bindings";
+import type { WorkspaceFileInfo, WorkspacePort } from "../../../config/ports";
 
 const MEMORY_ROOT = "/userspace/memories";
 

package/src/{pi/tool/web-fetch.ts → tools/web/fetch.ts}

@@ -10,14 +10,13 @@
  *   - 不依赖 Workers AI `toMarkdown()`——base runtime 不持有 AI binding，调用方若需要
  *     Markdown 转换，应在宿主层叠加；此处返回原始 UTF-8 解码内容。
  *
- * 本文件未接入任何系统入口（index.ts / base.ts），可单独 import 使用。
+ * 本文件未注册到默认 Tool Surface，可单独 import 使用。
  */
 
 import type { AgentTool } from "@earendil-works/pi-agent-core";
 import { Type } from "@earendil-works/pi-ai";
-import type { PiToolCandidate } from "./compiler";
+import type { PiToolCandidate } from "../runtime/contracts";
 
-// #region 常量
 
 /** 服务端强制截断上限（字节）。调用方 maxBytes 在此之上再被夹断。 */
 const HARD_MAX_BYTES = 5 * 1024 * 1024; // 5 MiB
@@ -28,9 +27,7 @@ const FETCH_TIMEOUT_MS = 30_000;
 /** 发出请求时使用的 User-Agent 字符串。 */
 const USER_AGENT = "UniversalAgent/1.0";
 
-// #endregion
 
-// #region 公开类型
 
 export const webFetchParameters = Type.Object({
   url: Type.String({
@@ -62,9 +59,7 @@ export interface WebFetchDetails {
   bodyLength: number;
 }
 
-// #endregion
 
-// #region 内部工具函数
 
 /**
  * 校验 URL 字符串是否符合 webFetch 的安全约束。
@@ -83,7 +78,7 @@ export function validateWebFetchUrl(input: string): URL {
   if (parsed.protocol !== "https:") {
     throw new Error(
       `Only https:// URLs are allowed; got ${parsed.protocol}//. ` +
-        `Use the HTTPS version of this URL.`,
+      `Use the HTTPS version of this URL.`,
     );
   }
   if (parsed.username || parsed.password) {
@@ -170,9 +165,7 @@ export function formatWebFetchResult(
   ].join("\n");
 }
 
-// #endregion
 
-// #region Pi 工具候选项工厂
 
 /**
  * 创建独立的 `web_fetch` Pi 工具候选项。
@@ -247,7 +240,7 @@ export function webFetchPiToolCandidate(): PiToolCandidate {
         try { await response.body?.cancel(); } catch { /* ignore */ }
         throw new Error(
           `The site at ${finalUrl} sets Content-Signal: ai-input=no, ` +
-            `indicating that it does not permit its content to be used as AI input.`,
+          `indicating that it does not permit its content to be used as AI input.`,
         );
       }
 
@@ -277,5 +270,3 @@ export function webFetchPiToolCandidate(): PiToolCandidate {
     tool,
   };
 }
-
-// #endregion

package/src/tools/web/index.ts

@@ -0,0 +1,2 @@
+export * from "./fetch";
+export * from "./search";