@springbrand/agent-runtime 0.1.3-alpha.7 → 0.2.0-alpha.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/agent-runtime",
-  "version": "0.1.3-alpha.7",
+  "version": "0.2.0-alpha.13",
   "type": "module",
   "files": [
     "src",
@@ -22,15 +22,16 @@
     "@cloudflare/think": "0.15.0",
     "@earendil-works/pi-agent-core": "0.83.0",
     "@earendil-works/pi-ai": "0.83.0",
+    "isomorphic-git": "1.38.6",
     "lodash-es": "^4.18.1",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "agents": "^0.19.0",
+    "agents": "^0.20.1",
     "ai": "^7.0.0"
   },
   "devDependencies": {
-    "agents": "0.19.0",
+    "agents": "0.20.1",
     "ai": "7.0.37"
   }
 }

package/src/adapter/cloudflare/index.ts

@@ -31,6 +31,7 @@ export {
   createWorkspacePortFacade,
   ScopedWorkspace,
 } from "./workspace/scoped-workspace";
+export { WorkspaceVersionControl } from "./workspace/version-control";
 export type {
   WorkspaceConditionalWriteResult,
   WorkspaceFileVersion,

package/src/adapter/cloudflare/sandbox/adapter.ts

@@ -155,6 +155,7 @@ export interface CloudflareSandboxAdapterOptions {
   sandboxId: string;
   workspace: WorkspacePort;
   publisher: WorkspacePublishPort;
+  onPublishComplete?: () => Promise<void>;
   admission?: SandboxAdmission;
   observer?: SandboxObserver;
   clientFactory?: SandboxClientFactory;
@@ -829,6 +830,9 @@ export class CloudflareSandboxAdapter implements RuntimeSandboxPort {
           await this.writeHydrationManifest(manifest);
         }
         const frozen = this.freezeSyncResult(result);
+        if (frozen.files.length > 0 && frozen.failed.length === 0) {
+          await this.options.onPublishComplete?.();
+        }
         this.emit("sandbox.workspace.published", {
           success: frozen.failed.length === 0,
           files: frozen.files.length,

package/src/adapter/cloudflare/subagent/definition.ts

@@ -24,6 +24,13 @@ import {
   withProviderRetry,
 } from "../../../pi/runtime-adapter/models";
 import { runCloudflareSubAgent } from "./runner";
+import {
+  addSubagentUsage,
+  decodeSubagentCompletion,
+  emptySubagentUsage,
+  encodeSubagentCompletion,
+} from "../../../kernel/subagent-runtime";
+import type { RuntimeSubagentUsageMetrics } from "../../../kernel/submission-authority";
 import { createCloudflareSubAgentTools } from "./tools";
 
 type RunStatus =
@@ -44,6 +51,7 @@ interface RunRow {
   started_at: number;
   completed_at: number | null;
   progress_json: string | null;
+  usage_json: string | null;
 }
 
 interface ChunkRow {
@@ -148,9 +156,17 @@ export abstract class CloudflareSubAgent<
         error_message TEXT,
         started_at INTEGER NOT NULL,
         completed_at INTEGER,
-        progress_json TEXT
+        progress_json TEXT,
+        usage_json TEXT
       )
     `;
+    const runColumns = new Set(
+      this.sql<{ name: string }>`PRAGMA table_info(pi_subagent_runs)`
+        .map((column) => column.name),
+    );
+    if (!runColumns.has("usage_json")) {
+      this.sql`ALTER TABLE pi_subagent_runs ADD COLUMN usage_json TEXT`;
+    }
     this.sql`
       CREATE TABLE IF NOT EXISTS pi_subagent_chunks (
         run_id TEXT NOT NULL,
@@ -182,7 +198,8 @@ export abstract class CloudflareSubAgent<
           error_message,
           started_at,
           completed_at,
-          progress_json
+          progress_json,
+          usage_json
         FROM pi_subagent_runs
         WHERE run_id = ${runId}
       `[0] ?? null
@@ -240,6 +257,26 @@ export abstract class CloudflareSubAgent<
     }
   }
 
+  private readUsage(runId: string): RuntimeSubagentUsageMetrics {
+    const value = this.readRun(runId)?.usage_json;
+    if (!value) return emptySubagentUsage();
+    const decoded = decodeSubagentCompletion(
+      stringifyJson({ usage: parseJson(value) }),
+    );
+    return decoded?.usage ?? emptySubagentUsage();
+  }
+
+  private persistUsage(
+    runId: string,
+    usage: RuntimeSubagentUsageMetrics,
+  ): void {
+    this.sql`
+      UPDATE pi_subagent_runs
+      SET usage_json = ${stringifyJson(usage)}
+      WHERE run_id = ${runId}
+    `;
+  }
+
   private persistProgress(
     runId: string,
     progress: Omit<AgentToolProgressSnapshot, "at">,
@@ -269,14 +306,20 @@ export abstract class CloudflareSubAgent<
     for (const subscriber of subscribers) subscriber.close();
   }
 
-  private completeRun(runId: string, output: unknown): void {
+  private completeRun(
+    runId: string,
+    output: unknown,
+    usage: RuntimeSubagentUsageMetrics,
+  ): void {
     const outputJson = stringifyJson(output);
+    const summary = encodeSubagentCompletion(output, usage);
     this.sql`
       UPDATE pi_subagent_runs
       SET
         status = 'completed',
         output_json = ${outputJson},
-        summary = ${outputJson},
+        summary = ${summary},
+        usage_json = ${stringifyJson(usage)},
         error_message = NULL,
         completed_at = ${Date.now()}
       WHERE run_id = ${runId}
@@ -289,11 +332,15 @@ export abstract class CloudflareSubAgent<
     runId: string,
     status: "error" | "aborted",
     error: string,
+    usage: RuntimeSubagentUsageMetrics = this.readUsage(runId),
   ): void {
+    const summary = encodeSubagentCompletion(undefined, usage);
     this.sql`
       UPDATE pi_subagent_runs
       SET
         status = ${status},
+        summary = ${summary},
+        usage_json = ${stringifyJson(usage)},
         error_message = ${error},
         completed_at = ${Date.now()}
       WHERE run_id = ${runId}
@@ -315,6 +362,7 @@ export abstract class CloudflareSubAgent<
       WHERE run_id = ${runId} AND status = 'starting'
     `;
 
+    const usage = this.readUsage(runId);
     try {
       const { provider, workspace, loader, outbound } =
         await this.prepareExecution();
@@ -355,6 +403,10 @@ export abstract class CloudflareSubAgent<
         tools,
         signal,
         onEvent: (event) => {
+          if (event.type === "message_end" && event.message.role === "assistant") {
+            addSubagentUsage(usage, event.message.usage);
+            this.persistUsage(runId, usage);
+          }
           for (const chunk of encoder.encode(event)) {
             this.appendChunk(runId, stringifyJson({
               v: 1,
@@ -367,12 +419,13 @@ export abstract class CloudflareSubAgent<
           if (progress) this.persistProgress(runId, progress);
         },
       });
-      this.completeRun(runId, output);
+      this.completeRun(runId, output, usage);
     } catch (error) {
       this.failRun(
         runId,
         signal.aborted ? "aborted" : "error",
         signal.aborted ? "SubAgent run aborted" : errorMessage(error),
+        usage,
       );
     }
   }
@@ -413,6 +466,7 @@ export abstract class CloudflareSubAgent<
         agent_type,
         status,
         input_json,
+        usage_json,
         started_at
       )
       VALUES (
@@ -420,6 +474,7 @@ export abstract class CloudflareSubAgent<
         ${type.name},
         'starting',
         ${inputJson},
+        ${stringifyJson(emptySubagentUsage())},
         ${startedAt}
       )
     `;

package/src/adapter/cloudflare/universal-agent/hooks.ts

@@ -1,4 +1,7 @@
-import type { RuntimeTurnEventsPort } from "../../../kernel/bindings";
+import type {
+  RuntimeSubmissionAdmissionHook,
+  RuntimeTurnEventsPort,
+} from "../../../kernel/bindings";
 import type { RuntimeAgentHooks } from "../../../runtime-definition";
 
 export function createUniversalAgentHooks<
@@ -9,6 +12,7 @@ export function createUniversalAgentHooks<
 >(adapter: {
   guard(config: Config): Promise<void>;
   turnEvents(): RuntimeTurnEventsPort | Promise<RuntimeTurnEventsPort>;
+  onSubmissionAdmission?: RuntimeSubmissionAdmissionHook;
 }): RuntimeAgentHooks<Env, Config, Command, Change> {
   const turnEvents = () => Promise.resolve(adapter.turnEvents());
   return {
@@ -19,6 +23,24 @@ export function createUniversalAgentHooks<
     onModelUsage: async (event) => {
       await (await turnEvents()).onModelUsage?.(event);
     },
+    ...(adapter.onSubmissionAdmission
+      ? { onSubmissionAdmission: adapter.onSubmissionAdmission }
+      : {}),
+    // 一个不订阅这两类事实的 Host 不能把 outbox 堵住：Runtime 只有拿到确认才
+    // 会标记投递，而 `undefined` 表示"没投出去"。因此没有 Host 实现时这里就地确认，
+    // 语义等同于旧版本"Host 不关心就丢弃"，而不是让整条队列在队头无限重试。
+    onSubagentUsage: async (event) => {
+      const port = await turnEvents();
+      return port.onSubagentUsage
+        ? port.onSubagentUsage(event)
+        : { confirmed: true };
+    },
+    onLifecycleFact: async (event) => {
+      const port = await turnEvents();
+      return port.onLifecycleFact
+        ? port.onLifecycleFact(event)
+        : { confirmed: true };
+    },
     onToolSettled: async (event) => {
       await (await turnEvents()).onToolSettled?.(event);
     },

package/src/adapter/cloudflare/universal-agent/preparation.ts

@@ -10,6 +10,7 @@ import type {
   RuntimeSubagentPort,
   WorkspacePort,
 } from "../../../kernel/bindings";
+import { decodeSubagentCompletion } from "../../../kernel/subagent-runtime";
 import type { RuntimeDegradation } from "../../../kernel/degradation";
 import type { RuntimeMemoryProfile } from "../../../kernel/profile";
 import { AGENT_TYPES } from "../../../layers/orchestration/subagents/agent-types/registry";
@@ -193,9 +194,33 @@ export async function prepareSubagents<Env extends Cloudflare.Env>(
   }
 
   const subagents: RuntimeSubagentPort = {
+    reserve: async (_agentType, _input, options) => {
+      if (!options?.submissionId || !options.toolCallId) {
+        throw new Error("Durable SubAgent reservation identity is required");
+      }
+      return {
+        runId: `${options.submissionId}:subagent:${options.toolCallId}`,
+      };
+    },
     run: async (agentType, input, options) => {
       const runOptions: RunAgentToolOptions<unknown> = {
         input: { agentType, ...input },
+        ...(options?.subagentRunId ? { runId: options.subagentRunId } : {}),
+        ...(options?.submissionId && options.parentRunId
+          ? {
+              inputPreview: {
+                submissionId: options.submissionId,
+                parentRunId: options.parentRunId,
+                ...(options.accountId ? { accountId: options.accountId } : {}),
+                ...(options.rateVersion !== undefined
+                  ? { rateVersion: options.rateVersion }
+                  : {}),
+                ...(options.slotIdentity
+                  ? { slotIdentity: options.slotIdentity }
+                  : {}),
+              },
+            }
+          : {}),
       };
       if (options?.detached) {
         runOptions.detached = { maxBudgetMs: options.maxBudgetMs };
@@ -204,11 +229,16 @@ export async function prepareSubagents<Env extends Cloudflare.Env>(
         }
       }
       const result = await context.runAgentTool(agentClass, runOptions);
+      const completion = decodeSubagentCompletion(result.summary);
       return {
         status: result.status,
         runId: result.runId,
         output: result.output,
         error: result.error,
+        ...(result.childStillRunning !== undefined
+          ? { childStillRunning: result.childStillRunning }
+          : {}),
+        ...(completion ? { usage: completion.usage } : {}),
       };
     },
   };
@@ -228,6 +258,7 @@ export async function prepareSandbox(options: {
   sessionId: string;
   workspaceLoader: WorkspaceLoader;
   publisher: WorkspacePublishPort;
+  onPublishComplete?: () => Promise<void>;
   admission?: SandboxAdmission;
   observer?: SandboxObserver;
 }) {
@@ -265,6 +296,9 @@ export async function prepareSandbox(options: {
       sandboxId: await sandboxIdForSession(options.userId, options.sessionId),
       workspace,
       publisher: options.publisher,
+      ...(options.onPublishComplete
+        ? { onPublishComplete: options.onPublishComplete }
+        : {}),
       ...(options.admission ? { admission: options.admission } : {}),
       ...(options.observer ? { observer: options.observer } : {}),
     }),

package/src/adapter/cloudflare/universal-agent/tools.ts

@@ -8,9 +8,10 @@ import type {
 } from "../../../kernel/bindings";
 import type { RuntimeDegradation } from "../../../kernel/degradation";
 import type { RuntimeMemoryProfile } from "../../../kernel/profile";
+import type { WorkspaceRevisionRestorePort } from "../../../workspace-versioning";
 import { createCodeExecutionTool } from "../../../pi/tool/core";
 import { createScheduleTools } from "../../../pi/tool/schedule";
-import { createSubagentTools } from "../../../pi/tool/subagent";
+import { createWorkspaceRevisionTools } from "../../../pi/tool/workspace-revision";
 import {
   createSandboxTools,
   createWorkspaceTools,
@@ -34,6 +35,7 @@ export function selectTools(
 export function assembleUniversalAgentTools(options: {
   hostTools?: ToolRegistry;
   workspace?: WorkspacePort;
+  workspaceRevisions?: WorkspaceRevisionRestorePort;
   codeExecution?: RuntimeCodeExecutionPort;
   sandbox?: RuntimeSandboxPort;
   schedule?: RuntimeSchedulePort;
@@ -47,17 +49,14 @@ export function assembleUniversalAgentTools(options: {
   const tools = mergeToolRegistries(
     options.hostTools ?? {},
     options.workspace ? createWorkspaceTools(options.workspace) : {},
+    options.workspaceRevisions
+      ? createWorkspaceRevisionTools(options.workspaceRevisions)
+      : {},
     options.codeExecution
       ? createCodeExecutionTool(options.codeExecution)
       : {},
     options.sandbox ? createSandboxTools(options.sandbox) : {},
     options.schedule ? createScheduleTools(options.schedule) : {},
-    options.subagents
-      ? createSubagentTools(
-          options.subagents,
-          options.enabledSubagents ?? [],
-        )
-      : {},
   );
 
   return {
@@ -65,6 +64,7 @@ export function assembleUniversalAgentTools(options: {
     bindings: {
       ...(options.workspace ? { workspace: options.workspace } : {}),
       ...(options.memory ? { memory: options.memory } : {}),
+      ...(options.subagents ? { subagents: options.subagents } : {}),
     },
     enabledSubagents: options.enabledSubagents ?? [],
     memoryProfile: options.memoryProfile,

package/src/adapter/cloudflare/workspace/git-fs.ts

@@ -0,0 +1,178 @@
+/*
+ * Adapted from @cloudflare/shell.
+ * MIT License Copyright (c) 2025 Cloudflare, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+import type {
+  FsClient,
+  PromiseFsClient,
+} from "isomorphic-git";
+import type {
+  WorkspaceFileInfo,
+  WorkspacePort,
+} from "../../../kernel/bindings";
+
+const PAGE_SIZE = 256;
+
+class GitStat {
+  readonly size: number;
+  readonly mtime: Date;
+  readonly mtimeMs: number;
+  readonly ctimeMs: number;
+  readonly mode: number;
+  readonly ino = 0;
+  readonly uid = 0;
+  readonly gid = 0;
+  readonly dev = 0;
+
+  constructor(private readonly info: WorkspaceFileInfo) {
+    this.size = info.size;
+    this.mtime = new Date(info.updatedAt);
+    this.mtimeMs = info.updatedAt;
+    this.ctimeMs = info.createdAt;
+    this.mode = info.type === "directory"
+      ? 0o40755
+      : info.type === "symlink"
+        ? 0o120000
+        : 0o100644;
+  }
+
+  isFile() {
+    return this.info.type === "file";
+  }
+
+  isDirectory() {
+    return this.info.type === "directory";
+  }
+
+  isSymbolicLink() {
+    return this.info.type === "symlink";
+  }
+}
+
+function fsError(path: string, cause?: unknown): Error & { code: string } {
+  if (
+    cause instanceof Error &&
+    "code" in cause &&
+    typeof (cause as { code: unknown }).code === "string"
+  ) return cause as Error & { code: string };
+
+  const error = new Error(
+    cause instanceof Error ? cause.message : `ENOENT: ${path}`,
+  ) as Error & { code: string };
+  error.code = cause === undefined ? "ENOENT" : "EIO";
+  return error;
+}
+
+async function readAll(workspace: WorkspacePort, path: string) {
+  const entries: WorkspaceFileInfo[] = [];
+  let offset = 0;
+  while (true) {
+    const page = await workspace.readDir(path, { limit: PAGE_SIZE, offset });
+    if (page.length === 0) return entries;
+    entries.push(...page);
+    offset += page.length;
+  }
+}
+
+export function createWorkspaceGitFs(workspace: WorkspacePort): FsClient {
+  const promises: PromiseFsClient["promises"] = {
+    async readFile(
+      path: string,
+      options?: { encoding?: string } | string,
+    ): Promise<Uint8Array | string> {
+      const encoding = typeof options === "string" ? options : options?.encoding;
+      try {
+        const value = encoding === "utf8" || encoding === "utf-8"
+          ? await workspace.readFile(path)
+          : await workspace.readFileBytes(path);
+        if (value === null) throw fsError(path);
+        return value;
+      } catch (error) {
+        throw fsError(path, error);
+      }
+    },
+    async writeFile(path: string, data: string | Uint8Array): Promise<void> {
+      const parent = path.replace(/\/[^/]+$/u, "");
+      if (parent && parent !== "/" && parent !== path) {
+        await workspace.mkdir(parent, { recursive: true });
+      }
+      if (typeof data === "string") await workspace.writeFile(path, data);
+      else await workspace.writeFileBytes(path, data);
+    },
+    async unlink(path: string): Promise<void> {
+      try {
+        await workspace.rm(path);
+      } catch (error) {
+        throw fsError(path, error);
+      }
+    },
+    async readdir(path: string): Promise<string[]> {
+      try {
+        const info = await workspace.stat(path);
+        if (!info || info.type !== "directory") throw fsError(path);
+        return (await readAll(workspace, path)).map(({ name }) => name);
+      } catch (error) {
+        throw fsError(path, error);
+      }
+    },
+    async mkdir(
+      path: string,
+      mode?: number | { recursive?: boolean },
+    ): Promise<void> {
+      await workspace.mkdir(path, {
+        recursive: typeof mode === "object" ? mode.recursive : false,
+      });
+    },
+    async rmdir(path: string): Promise<void> {
+      await workspace.rm(path);
+    },
+    async stat(path: string): Promise<GitStat> {
+      try {
+        const info = await workspace.stat(path);
+        if (!info) throw fsError(path);
+        return new GitStat(info);
+      } catch (error) {
+        throw fsError(path, error);
+      }
+    },
+    async lstat(path: string): Promise<GitStat> {
+      try {
+        const info = await workspace.lstat(path);
+        if (!info) throw fsError(path);
+        return new GitStat(info);
+      } catch (error) {
+        throw fsError(path, error);
+      }
+    },
+    async readlink(path: string): Promise<string> {
+      try {
+        return await workspace.readlink(path);
+      } catch (error) {
+        throw fsError(path, error);
+      }
+    },
+    async symlink(target: string, path: string): Promise<void> {
+      await workspace.symlink(target, path);
+    },
+    async chmod(): Promise<void> {},
+  };
+  return { promises };
+}