@springbrand/agent-runtime 0.2.0-alpha.71 → 0.3.0-alpha.1

package/src/{pi/tool → tools}/gateway.ts

@@ -1,4 +1,4 @@
-import type { RuntimeGatewaySession } from "../../kernel/bindings";
+import type { RuntimeGatewaySession } from "../config/ports";
 import type { PiToolCandidate } from "./compiler";
 import { createPiMcpToolCandidate } from "./mcp";
 

package/src/tools/human-decisions.ts

@@ -0,0 +1,127 @@
+import type { ApprovalDecision } from "../submission/contracts";
+import type { RuntimeTelemetryCoordinator } from "../telemetry/coordinator";
+import type { ApprovalRepository } from "./approval/repository";
+import type { PiToolInteractionSpec } from "./compiler";
+import type { StoredToolInteraction, ToolInteractionRepository } from "./interaction/repository";
+
+/** Human decisions own validation and durable facts; the caller resumes Pi. */
+export class HarnessHumanDecisions {
+  constructor(private readonly options: {
+    readonly approvals: ApprovalRepository;
+    readonly interactions: ToolInteractionRepository;
+    readonly transaction: <T>(run: () => T) => T;
+    readonly isSubmissionActive: (submissionId: string) => boolean;
+    readonly telemetry: Pick<RuntimeTelemetryCoordinator, "capture">;
+  }) {}
+
+  isWaitingForApproval(submissionId: string): boolean {
+    return this.options.approvals.listPendingForSubmission(submissionId).length > 0;
+  }
+
+  isWaitingForInteraction(submissionId: string): boolean {
+    return this.options.interactions.listPendingForSubmission(submissionId).length > 0;
+  }
+
+  async respond(
+    pending: StoredToolInteraction,
+    spec: PiToolInteractionSpec,
+    response: unknown,
+    prepareResponse: (input: {
+      toolCallId: string;
+      toolName: string;
+      toolInput: unknown;
+      response: unknown;
+    }) => Promise<unknown | null>,
+  ): Promise<boolean> {
+    if (!this.options.isSubmissionActive(pending.submissionId) ||
+      this.options.interactions.find(pending.interactionId)?.status !== "pending") return false;
+    let input: unknown;
+    try { input = JSON.parse(pending.inputJson); } catch { return false; }
+    if (!spec.validateResponse(input, response)) return false;
+    const prepared = await prepareResponse({
+      toolCallId: pending.toolCallId,
+      toolName: pending.toolName,
+      toolInput: input,
+      response,
+    });
+    if (prepared === null || !spec.validateResponse(input, prepared)) return false;
+    return this.options.transaction(() => {
+      // Preparation may await a Host operation while stop, steer, or another answer wins.
+      const current = this.options.interactions.find(pending.interactionId);
+      if (current?.status !== "pending" ||
+        !this.options.isSubmissionActive(current.submissionId)) return false;
+      const occurredAt = Date.now();
+      this.options.interactions.settle(pending.interactionId, "responded", occurredAt, JSON.stringify(prepared));
+      this.options.telemetry.capture("interactionResponded", {
+        submissionId: current.submissionId,
+        toolCallId: current.toolCallId,
+        interactionId: current.interactionId,
+        response: prepared,
+        occurredAt,
+      });
+      return true;
+    });
+  }
+
+  approve(executionId: string, decision: ApprovalDecision): { ok: boolean; submissionId?: string } {
+    if (decision.decision === "allow_level") {
+      throw new Error("allow_level must be applied by the User Agent Host before resuming the Tool");
+    }
+    return this.options.transaction(() => {
+      const pending = this.options.approvals.find(executionId);
+      if (!pending) return { ok: true };
+      if (pending.status !== "pending" || !this.options.isSubmissionActive(pending.submissionId)) {
+        return { ok: false };
+      }
+      const status = decision.decision === "allow_once" ? "approved" : "rejected";
+      const reason = decision.decision === "deny" ? decision.reason : undefined;
+      const occurredAt = Date.now();
+      this.options.approvals.decide(executionId, status, occurredAt, reason);
+      this.options.telemetry.capture("approvalDecided", {
+        submissionId: pending.submissionId,
+        toolCallId: pending.toolCallId,
+        executionId,
+        decision: status,
+        ...(reason ? { reason } : {}),
+        occurredAt,
+      });
+      return { ok: true, submissionId: pending.submissionId };
+    });
+  }
+
+  cancelInteractions(submissionId: string, reason: string): void {
+    this.options.transaction(() => {
+      for (const id of this.options.interactions.listPendingForSubmission(submissionId)) {
+        const pending = this.options.interactions.find(id)!;
+        const occurredAt = Date.now();
+        this.options.interactions.settle(id, "cancelled", occurredAt);
+        this.options.telemetry.capture("interactionCancelled", {
+          submissionId,
+          toolCallId: pending.toolCallId,
+          interactionId: id,
+          reason,
+          occurredAt,
+        });
+      }
+    });
+  }
+
+  cancelForSubmission(submissionId: string, reason: string): void {
+    this.options.transaction(() => {
+      for (const id of this.options.approvals.listPendingForSubmission(submissionId)) {
+        const pending = this.options.approvals.find(id)!;
+        const occurredAt = Date.now();
+        this.options.approvals.decide(id, "rejected", occurredAt, reason);
+        this.options.telemetry.capture("approvalDecided", {
+          submissionId,
+          toolCallId: pending.toolCallId,
+          executionId: id,
+          decision: "cancelled",
+          reason,
+          occurredAt,
+        });
+      }
+      this.cancelInteractions(submissionId, reason);
+    });
+  }
+}

package/src/tools/index.ts

@@ -0,0 +1,30 @@
+export * from "./ai-adapter";
+export * from "./approval";
+export * from "./base";
+export * from "./compiler";
+export * from "./core";
+export * from "./core-host";
+export * from "./declared";
+export * from "./decision-gate";
+export * from "./human-decisions";
+export * from "./gateway";
+export * from "./mcp";
+export * from "./interaction";
+export * from "./schedule";
+export * from "./skill";
+export * from "./subagent";
+export * from "./subagent-authority";
+export * from "./subagent-run-repository";
+export * from "./subagent-runtime";
+export * from "./subagent-types/contract";
+export * from "./subagent-types/registry";
+export * from "./temporary-agent/approvals";
+export * from "./temporary-agent/core";
+export * from "./temporary-agent/coordinator";
+export * from "./temporary-agent/runner";
+export * from "./temporary-agent/workspace";
+export * from "./time";
+export * from "./workspace-sandbox";
+export * from "./workspace-revision";
+export * from "./workspace-versioning";
+export * from "./web-search";

package/src/tools/interaction/index.ts

@@ -0,0 +1 @@
+export * from "./repository";

package/src/{pi/tool → tools}/mcp.ts

@@ -1,4 +1,4 @@
-import type { RuntimeMcpServer } from "../../kernel/profile";
+import type { RuntimeMcpServer } from "../config/profile";
 import type { PiToolCandidate } from "./compiler";
 import { createPiDeclaredToolCandidate } from "./declared";
 

package/src/{pi/tool → tools}/schedule.ts

@@ -6,9 +6,9 @@ import { Type, type TSchema } from "@earendil-works/pi-ai";
 import type {
   RuntimeSchedulePort,
   RuntimeScheduleUpdate,
-} from "../../kernel/bindings";
-import type { ScheduleSpec } from "../../kernel/receipts";
-import { serializeOutput } from "../../lib/artifacts";
+} from "../config/ports";
+import type { ScheduleSpec } from "../submission/contracts";
+import { serializeOutput } from "../lib/artifacts";
 import type { PiToolCandidate } from "./compiler";
 
 const scheduleTriggerParameters = Type.Union([

package/src/{pi/tool → tools}/skill.ts

@@ -12,10 +12,10 @@ import { z } from "zod";
 import type {
   RuntimeSkillScriptPolicy,
   WorkspacePort,
-} from "../../kernel/bindings";
-import type { RuntimeSkillBodyTransform } from "../../runtime-definition";
-import { STORAGE_LEAF_MAX_CHARS } from "../../layers/context/budget/gate";
-import { serializeOutput } from "../../lib/artifacts";
+} from "../config/ports";
+import type { RuntimeSkillBodyTransform } from "../config/definition";
+import { STORAGE_LEAF_MAX_CHARS } from "../context/memory/budget/gate";
+import { serializeOutput } from "../lib/artifacts";
 import { aiToolToPi } from "./ai-adapter";
 import type { PiToolCandidate } from "./compiler";
 import { piCandidatesToAiTools } from "./nested-tools";

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

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

package/src/{pi/tool → tools}/subagent.ts

@@ -5,13 +5,13 @@ import type {
   RuntimeSubagentPort,
   RuntimeSubagentRunResult,
   RuntimeSubagentUsageEvent,
-} from "../../kernel/bindings";
-import { AGENT_TYPES } from "../../layers/orchestration/subagents/agent-types/registry";
-import { serializeOutput } from "../../lib/artifacts";
+} from "../config/ports";
+import { AGENT_TYPES } from "./subagent-types/registry";
+import { serializeOutput } from "../lib/artifacts";
 import {
   isZeroSubagentUsage,
   subagentTerminalStatus,
-} from "../../kernel/subagent-runtime";
+} from "./subagent-runtime";
 import type { PiToolCandidate } from "./compiler";
 
 const BACKGROUND_MAX_BUDGET_MS = 10 * 60 * 1_000;

package/src/tools/temporary-agent/approvals.ts

@@ -0,0 +1,126 @@
+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/temporary-agent/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/temporary-agent/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 → tools}/temporary-agent/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 → tools}/temporary-agent/workspace.ts

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

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

@@ -5,7 +5,7 @@
  * https://github.com/ttttmr/pi-web-search
  */
 
-import type { RuntimeModelEndpoint } from "../../../kernel/bindings";
+import type { RuntimeModelEndpoint } from "../../config/ports";
 
 export interface WebSearchSource {
     title: string;

package/src/{pi/tool → tools}/workspace-revision.ts

@@ -1,7 +1,7 @@
 import type { AgentTool, AgentToolResult } from "@earendil-works/pi-agent-core";
 import { Type } from "@earendil-works/pi-ai";
-import type { WorkspaceRevisionRestorePort } from "../../workspace-versioning";
-import { serializeOutput } from "../../lib/artifacts";
+import type { WorkspaceRevisionRestorePort } from "./workspace-versioning";
+import { serializeOutput } from "../lib/artifacts";
 import type { PiToolCandidate } from "./compiler";
 
 const parameters = Type.Object({

package/src/{pi/tool → tools}/workspace-sandbox.ts

@@ -16,8 +16,8 @@ import { Type } from "@earendil-works/pi-ai";
 import type {
   RuntimeSandboxPort,
   WorkspacePort,
-} from "../../kernel/bindings";
-import { serializeOutput } from "../../lib/artifacts";
+} from "../config/ports";
+import { serializeOutput } from "../lib/artifacts";
 import { aiToolToPi } from "./ai-adapter";
 import type { PiToolCandidate } from "./compiler";
 

package/src/{pi/tool → tools}/workspace-state-connector.ts

@@ -2,7 +2,7 @@ import { STATE_TYPES } from "@cloudflare/shell";
 import type { StateBackend } from "@cloudflare/shell/workers";
 import { StateConnector } from "@cloudflare/shell/workers";
 import type { ConnectorTools } from "@cloudflare/codemode";
-import type { WorkspacePort } from "../../kernel/bindings";
+import type { WorkspacePort } from "../config/ports";
 
 export const WORKSPACE_DIRECT_TEXT_READ_MAX_BYTES = 1024 * 1024;