@springbrand/agent-runtime 0.1.3-alpha.1 → 0.1.3-alpha.10

package/src/adapter/cloudflare/workspace/version-control.ts

@@ -0,0 +1,374 @@
+import * as git from "isomorphic-git";
+import type { WorkspacePort } from "../../../kernel/bindings";
+import {
+  WorkspaceRevisionNotFoundError,
+  type WorkspaceRevision,
+  type WorkspaceRevisionManifest,
+  type WorkspaceVersionPort,
+} from "../../../workspace-versioning";
+import { createWorkspaceGitFs } from "./git-fs";
+
+const PAGE_SIZE = 256;
+const MAX_LIST_LIMIT = 100;
+const REVISION_PATTERN = /^[0-9a-f]{40}$/u;
+const AUTHOR = Object.freeze({
+  name: "Workspace",
+  email: "workspace@springbrand.local",
+});
+
+type VersionControlOptions = {
+  workspace: WorkspacePort;
+  dir: string;
+  gitdir: string;
+};
+
+type TreeFile = {
+  path: string;
+  oid: string;
+  bytes: Uint8Array;
+};
+
+function coordinate(value: string): string {
+  if (!value.startsWith("/") || value.includes("\\")) {
+    throw new Error("Workspace revision coordinates must be absolute POSIX paths");
+  }
+  const parts = value.split("/").filter(Boolean);
+  if (parts.some((part) => part === "." || part === "..")) {
+    throw new Error("Workspace revision coordinates cannot traverse");
+  }
+  return `/${parts.join("/")}`;
+}
+
+function relativePath(value: string): string {
+  if (!value || value.startsWith("/") || value.includes("\\")) {
+    throw new WorkspaceRevisionNotFoundError();
+  }
+  const parts = value.split("/");
+  if (parts.some((part) => !part || part === "." || part === ".." || part === ".git")) {
+    throw new WorkspaceRevisionNotFoundError();
+  }
+  return parts.join("/");
+}
+
+function pathIn(root: string, relative: string): string {
+  return `${root}/${relative}`;
+}
+
+function isMissing(error: unknown) {
+  return error instanceof Error && (
+    "code" in error && String((error as { code: unknown }).code).includes("NotFound") ||
+    error.message.includes("Could not find") ||
+    error.message.includes("ENOENT")
+  );
+}
+
+/** A linear Git history for one Host-selected Workspace subtree. */
+export class WorkspaceVersionControl implements WorkspaceVersionPort {
+  private readonly workspace: WorkspacePort;
+  private readonly dir: string;
+  private readonly gitdir: string;
+  private readonly fs: git.FsClient;
+
+  constructor(options: VersionControlOptions) {
+    this.workspace = options.workspace;
+    this.dir = coordinate(options.dir);
+    this.gitdir = coordinate(options.gitdir);
+    if (
+      this.dir === this.gitdir ||
+      this.dir.startsWith(`${this.gitdir}/`) ||
+      this.gitdir.startsWith(`${this.dir}/`)
+    ) throw new Error("Workspace revision gitdir must be separate from its worktree");
+    this.fs = createWorkspaceGitFs(this.workspace);
+  }
+
+  async current(): Promise<WorkspaceRevision | null> {
+    await this.ensure();
+    try {
+      const entries = await git.log({
+        fs: this.fs,
+        dir: this.dir,
+        gitdir: this.gitdir,
+        depth: 1,
+      });
+      return entries[0] ? this.revision(entries[0]) : null;
+    } catch (error) {
+      if (isMissing(error)) return null;
+      throw error;
+    }
+  }
+
+  async checkpoint(input: { reason: string }) {
+    await this.ensure();
+    const reason = input.reason.trim();
+    if (!reason) throw new Error("Workspace revision reason is required");
+    const currentFiles = await this.worktreeFiles();
+    const before = await this.current();
+    if (currentFiles.size === 0 && !before) {
+      return { revision: null, treeHash: null, changed: false };
+    }
+    if (
+      before &&
+      sameFiles(currentFiles, (await this.readRevision(before.revision)).files)
+    ) {
+      return {
+        revision: before.revision,
+        treeHash: before.treeHash,
+        changed: false,
+      };
+    }
+
+    await this.stageWorktree(currentFiles);
+    const revision = await git.commit({
+      fs: this.fs,
+      dir: this.dir,
+      gitdir: this.gitdir,
+      message: reason,
+      author: AUTHOR,
+      committer: AUTHOR,
+    });
+    const treeHash = (await git.readTree({
+      fs: this.fs,
+      dir: this.dir,
+      gitdir: this.gitdir,
+      oid: revision,
+    })).oid;
+    return { revision, treeHash, changed: true };
+  }
+
+  async list(input?: { limit?: number }) {
+    await this.ensure();
+    const limit = Math.min(Math.max(input?.limit ?? 20, 1), MAX_LIST_LIMIT);
+    try {
+      return Promise.all((await git.log({
+        fs: this.fs,
+        dir: this.dir,
+        gitdir: this.gitdir,
+        depth: limit,
+      })).map((entry) => this.revision(entry)));
+    } catch (error) {
+      if (isMissing(error)) return [];
+      throw error;
+    }
+  }
+
+  async manifest(revision: string): Promise<WorkspaceRevisionManifest> {
+    const { treeHash, files } = await this.readRevision(revision);
+    return {
+      revision,
+      treeHash,
+      files: files.map(({ path, bytes }) => ({ path, size: bytes.byteLength })),
+    };
+  }
+
+  async readFile(revision: string, path: string): Promise<Uint8Array> {
+    const normalized = relativePath(path);
+    const { files } = await this.readRevision(revision);
+    const file = files.find((candidate) => candidate.path === normalized);
+    if (!file) throw new WorkspaceRevisionNotFoundError();
+    return file.bytes.slice();
+  }
+
+  async restore(input: { revision: string; reason: string }) {
+    const target = await this.readRevision(input.revision);
+    const preserved = await this.checkpoint({ reason: "Before restore" });
+    if (preserved.treeHash === target.treeHash) {
+      return {
+        revision: preserved.revision!,
+        treeHash: preserved.treeHash!,
+      };
+    }
+    const before = preserved.revision
+      ? await this.readRevision(preserved.revision)
+      : { treeHash: "", files: [] };
+    try {
+      await this.replaceWorktree(target.files);
+      const restored = await this.checkpoint({ reason: input.reason });
+      return { revision: restored.revision!, treeHash: restored.treeHash! };
+    } catch (error) {
+      try {
+        await this.replaceWorktree(before.files);
+        await this.stageWorktree();
+      } catch (compensationError) {
+        throw new AggregateError(
+          [error, compensationError],
+          "workspace_revision_restore_compensation_failed",
+        );
+      }
+      throw error;
+    }
+  }
+
+  private async ensure() {
+    await this.workspace.mkdir(this.dir, { recursive: true });
+    await this.workspace.mkdir(this.gitdir, { recursive: true });
+    await git.init({
+      fs: this.fs,
+      dir: this.dir,
+      gitdir: this.gitdir,
+      defaultBranch: "main",
+    });
+  }
+
+  private async revision(entry: Awaited<ReturnType<typeof git.log>>[number]) {
+    const treeHash = (await git.readTree({
+      fs: this.fs,
+      dir: this.dir,
+      gitdir: this.gitdir,
+      oid: entry.oid,
+    })).oid;
+    return {
+      revision: entry.oid,
+      treeHash,
+      reason: entry.commit.message.trim(),
+      createdAt: entry.commit.author.timestamp * 1_000,
+    } satisfies WorkspaceRevision;
+  }
+
+  private async readRevision(revision: string): Promise<{
+    treeHash: string;
+    files: TreeFile[];
+  }> {
+    await this.ensure();
+    if (!REVISION_PATTERN.test(revision)) throw new WorkspaceRevisionNotFoundError();
+    try {
+      await git.readCommit({
+        fs: this.fs,
+        dir: this.dir,
+        gitdir: this.gitdir,
+        oid: revision,
+      });
+      const root = await git.readTree({
+        fs: this.fs,
+        dir: this.dir,
+        gitdir: this.gitdir,
+        oid: revision,
+      });
+      const files: TreeFile[] = [];
+      await this.readTreeFiles(root.oid, "", files);
+      files.sort((left, right) => left.path.localeCompare(right.path));
+      return { treeHash: root.oid, files };
+    } catch (error) {
+      if (error instanceof WorkspaceRevisionNotFoundError || isMissing(error)) {
+        throw new WorkspaceRevisionNotFoundError();
+      }
+      throw error;
+    }
+  }
+
+  private async readTreeFiles(oid: string, prefix: string, files: TreeFile[]) {
+    const { tree } = await git.readTree({
+      fs: this.fs,
+      dir: this.dir,
+      gitdir: this.gitdir,
+      oid,
+    });
+    for (const entry of tree) {
+      const path = prefix ? `${prefix}/${entry.path}` : entry.path;
+      relativePath(path);
+      if (entry.type === "tree") {
+        await this.readTreeFiles(entry.oid, path, files);
+      } else if (entry.type === "blob" && entry.mode !== "120000") {
+        files.push({
+          path,
+          oid: entry.oid,
+          bytes: (await git.readBlob({
+            fs: this.fs,
+            dir: this.dir,
+            gitdir: this.gitdir,
+            oid: entry.oid,
+          })).blob,
+        });
+      } else {
+        throw new WorkspaceRevisionNotFoundError();
+      }
+    }
+  }
+
+  private async worktreeFiles() {
+    const files = new Map<string, Uint8Array>();
+    const pending = [this.dir];
+    while (pending.length > 0) {
+      const directory = pending.pop()!;
+      for (const entry of await this.readDir(directory)) {
+        const path = entry.path.slice(this.dir.length + 1);
+        relativePath(path);
+        if (entry.type === "directory") pending.push(entry.path);
+        else if (entry.type === "file") {
+          const bytes = await this.workspace.readFileBytes(entry.path);
+          if (!bytes) throw new Error("Workspace file disappeared during checkpoint");
+          files.set(path, bytes);
+        } else {
+          throw new Error("Workspace revisions do not support symbolic links");
+        }
+      }
+    }
+    return files;
+  }
+
+  private async readDir(path: string) {
+    const entries = [];
+    let offset = 0;
+    while (true) {
+      const page = await this.workspace.readDir(path, {
+        limit: PAGE_SIZE,
+        offset,
+      });
+      if (page.length === 0) return entries;
+      entries.push(...page);
+      offset += page.length;
+    }
+  }
+
+  private async replaceWorktree(files: readonly TreeFile[]) {
+    const target = new Set(files.map(({ path }) => path));
+    const current = await this.worktreeFiles();
+    for (const path of current.keys()) {
+      if (!target.has(path)) {
+        await this.workspace.rm(pathIn(this.dir, path), { force: true });
+      }
+    }
+    for (const file of files) {
+      await this.workspace.writeFileBytes(pathIn(this.dir, file.path), file.bytes);
+    }
+  }
+
+  private async stageWorktree(files?: ReadonlyMap<string, Uint8Array>) {
+    files ??= await this.worktreeFiles();
+    const tracked = new Set(await git.listFiles({
+      fs: this.fs,
+      dir: this.dir,
+      gitdir: this.gitdir,
+    }));
+    for (const path of files.keys()) {
+      await git.add({
+        fs: this.fs,
+        dir: this.dir,
+        gitdir: this.gitdir,
+        filepath: path,
+        force: true,
+      });
+      tracked.delete(path);
+    }
+    for (const path of tracked) {
+      await git.remove({
+        fs: this.fs,
+        dir: this.dir,
+        gitdir: this.gitdir,
+        filepath: path,
+      });
+    }
+  }
+
+}
+
+function sameFiles(
+  current: ReadonlyMap<string, Uint8Array>,
+  revision: readonly TreeFile[],
+) {
+  if (current.size !== revision.length) return false;
+  return revision.every(({ path, bytes }) => {
+    const candidate = current.get(path);
+    return candidate?.byteLength === bytes.byteLength &&
+      candidate.every((byte, index) => byte === bytes[index]);
+  });
+}

package/src/agent-tool-runtime.ts

@@ -0,0 +1,152 @@
+import type {
+  AgentToolChildAdapter,
+  AgentToolRunInspection,
+  AgentToolStoredChunk,
+} from "agents";
+import { AgentRuntimeKernel } from "./runtime";
+
+const AGENT_TOOL_RUN_PREFIX = "universal-agent:temporary-agent-run:";
+
+interface AgentToolRunRecord {
+  runId: string;
+  submissionId: string;
+  startedAt: number;
+  completedAt?: number;
+  summary?: string;
+}
+
+function agentToolRunKey(runId: string): string {
+  return `${AGENT_TOOL_RUN_PREFIX}${runId}`;
+}
+
+/**
+ * 把 Cloudflare Agent Tool 子运行协议适配到 Runtime Submission 生命周期。
+ *
+ * 具体 Runtime 只负责准备输入与清理资源；启动、查询、取消和结果读取统一留在这里。
+ */
+export abstract class AgentToolRuntimeKernel<
+  Env extends Cloudflare.Env = Cloudflare.Env,
+> extends AgentRuntimeKernel<Env>
+  implements AgentToolChildAdapter<unknown, string> {
+  protected abstract prepareAgentToolRun(input: unknown): Promise<string>;
+  protected abstract cleanupAgentToolRun(): Promise<void>;
+
+  async startAgentToolRun(
+    input: unknown,
+    options: { runId: string; signal?: AbortSignal },
+  ): Promise<AgentToolRunInspection<string>> {
+    options.signal?.throwIfAborted();
+    try {
+      const prompt = await this.prepareAgentToolRun(input);
+      const receipt = await this.submitPrompt(prompt, {
+        idempotencyKey: options.runId,
+      });
+      const record: AgentToolRunRecord = {
+        runId: options.runId,
+        submissionId: receipt.submissionId,
+        startedAt: receipt.createdAt,
+      };
+      await this.ctx.storage.put(agentToolRunKey(options.runId), record);
+      const cancel = () => {
+        void this.cancelAgentToolRun(options.runId, options.signal?.reason);
+      };
+      if (options.signal?.aborted) cancel();
+      else options.signal?.addEventListener("abort", cancel, { once: true });
+      return {
+        runId: options.runId,
+        status: "running",
+        startedAt: record.startedAt,
+      };
+    } catch (error) {
+      await this.cleanupAgentToolRun();
+      throw error;
+    }
+  }
+
+  async inspectAgentToolRun(
+    runId: string,
+  ): Promise<AgentToolRunInspection<string> | null> {
+    const key = agentToolRunKey(runId);
+    const record = await this.ctx.storage.get<AgentToolRunRecord>(key);
+    if (!record) return null;
+    const receipt = await this.getSubmission(record.submissionId);
+    if (!receipt) return null;
+    if (receipt.status === "pending" || receipt.status === "running") {
+      return { runId, status: "running", startedAt: record.startedAt };
+    }
+
+    const completedAt = receipt.completedAt ?? Date.now();
+    if (receipt.status === "completed") {
+      const summary = record.summary ?? await this.latestAssistantText();
+      if (!summary) {
+        await this.cleanupAgentToolRun();
+        return {
+          runId,
+          status: "error",
+          error: "Temporary Agent completed without final text",
+          startedAt: record.startedAt,
+          completedAt,
+        };
+      }
+      await this.ctx.storage.put(key, {
+        ...record,
+        summary,
+        completedAt,
+      } satisfies AgentToolRunRecord);
+      await this.cleanupAgentToolRun();
+      return {
+        runId,
+        status: "completed",
+        output: summary,
+        summary,
+        startedAt: record.startedAt,
+        completedAt,
+      };
+    }
+
+    await this.cleanupAgentToolRun();
+    return receipt.status === "aborted"
+      ? {
+          runId,
+          status: "aborted",
+          error: receipt.error ?? "Temporary Agent was cancelled",
+          startedAt: record.startedAt,
+          completedAt,
+        }
+      : {
+          runId,
+          status: "error",
+          error: receipt.error ??
+            (receipt.status === "skipped"
+              ? "Temporary Agent submission was skipped"
+              : "Temporary Agent failed"),
+          startedAt: record.startedAt,
+          completedAt,
+        };
+  }
+
+  async getAgentToolChunks(
+    _runId: string,
+    _options?: { afterSequence?: number },
+  ): Promise<AgentToolStoredChunk[]> {
+    return [];
+  }
+
+  async cancelAgentToolRun(runId: string, reason?: unknown): Promise<void> {
+    const record = await this.ctx.storage.get<AgentToolRunRecord>(
+      agentToolRunKey(runId),
+    );
+    try {
+      if (record) {
+        await this.cancelSubmissionById(
+          record.submissionId,
+          reason instanceof Error
+            ? reason.message
+            : String(reason ?? "Temporary Agent cancelled"),
+        );
+      }
+    } finally {
+      await this.cleanupAgentToolRun();
+    }
+  }
+}

package/src/db/agent-tool.repo.ts

@@ -0,0 +1,27 @@
+import type { SqlTaggedTemplate } from "agents/chat";
+
+// Agent Tool Run 的统一定义见 ./index.ts。
+export class AgentToolRepository {
+  // 保存当前 Agent SQLite 的查询入口。
+  // RuntimeDatabase 构造时调用，活动投影随后通过这个 Repository 读取子运行。
+  // 把存储绑定留在构造阶段，避免每次读取都传入可能属于其他 Agent 的 sql。
+  constructor(private readonly sql: SqlTaggedTemplate) {}
+
+  // 是否仍有 Agent Tool 子运行在执行。
+  // 活动投影在重算 activity 时调用，判定只在这里做一次。
+  // `interrupted` 单独判 `child_still_running`：父级不再等待并不代表子级已经停下。
+  hasRunning(): boolean {
+    try {
+      return (
+        this.sql<{ count: number }>`
+          SELECT COUNT(*) AS count FROM cf_agent_tool_runs
+          WHERE status IN ('starting', 'running')
+             OR (status = 'interrupted' AND child_still_running = 1)
+        `[0]?.count ?? 0
+      ) > 0;
+    } catch {
+      // 一个子运行都没派发过时，Agents SDK 还没有把该表建出来。
+      return false;
+    }
+  }
+}

package/src/db/index.ts

@@ -3,41 +3,52 @@ import type { SqlTaggedTemplate } from "agents/chat";
 import { initializeSchema } from "./schema";
 import { SubmissionRepository } from "./submission.repo";
 import { ApprovalRepository } from "./approval.repo";
+import { ToolInteractionRepository } from "./interaction.repo";
 import { ToolSettlementRepository } from "./settlement.repo";
 import { RecoveryMilestoneRepository } from "./milestone.repo";
 import { ExtContextRepository } from "./ext-context.repo";
 import { MessageUiRepository } from "./message-ui.repo";
 import { SteerRepository } from "./steer.repo";
 import { RuntimeEventOutboxRepository } from "./runtime-event-outbox.repo";
+import { AgentToolRepository } from "./agent-tool.repo";
 
 // 数据库术语以这里为准。
 // Submission 是一次可持久化的用户提交，从排队到终态都用同一个 submissionId 跟踪。
 // Approval 是某次工具调用的持久化审批记录，executionId 是对外决策时的主键。
+// Tool Interaction 是「结果由客户端提供」的工具调用的 park 记录，interactionId 是主键；
+// 它只回答还等不等得到响应，答案的权威副本仍是 Settlement。
 // Settlement 是工具调用的最终结果，同一 Submission 内用 toolCallId 防止重复落盘。
 // Recovery Milestone 是按 seq 重放的恢复事实，milestoneKey 用来去重。
 // Extension Context 是扩展按 label 保存的文本，不随清空聊天记录删除。
 // Message UI 是会话消息的用户界面补充数据，它由 Transcript 而不是 Turn 生命周期管理。
+// Agent Tool Run 是 Agents SDK 派发的子运行，唯一一张不归 Runtime 所有的表：SDK 建它、写它、清它，
+// 这里只读。它没有 `pi_` 前缀，也不进 initializeSchema 和 clearAll。之所以直读 SDK 的表而不另建账本，
+// 是因为 SDK 没有公开父级侧的「还有没有子运行在跑」读法，而复制一份必然产生第二个真相源。
 // Repository 只把 Runtime 语义翻译成参数化 SQL，所有表都位于当前 Agent 实例自己的 Durable Object SQLite 存储中。
 // Transaction 指 Cloudflare transactionSync 包住的同步操作，回调抛错时整体回滚。
 export * from "./schema";
 export * from "./submission.repo";
 export * from "./approval.repo";
+export * from "./interaction.repo";
 export * from "./settlement.repo";
 export * from "./milestone.repo";
 export * from "./ext-context.repo";
 export * from "./message-ui.repo";
 export * from "./steer.repo";
 export * from "./runtime-event-outbox.repo";
+export * from "./agent-tool.repo";
 
 export class RuntimeDatabase {
   readonly submissions: SubmissionRepository;
   readonly approvals: ApprovalRepository;
+  readonly interactions: ToolInteractionRepository;
   readonly settlements: ToolSettlementRepository;
   readonly milestones: RecoveryMilestoneRepository;
   readonly extContext: ExtContextRepository;
   readonly messageUi: MessageUiRepository;
   readonly steers: SteerRepository;
   readonly runtimeEvents: RuntimeEventOutboxRepository;
+  readonly agentTools: AgentToolRepository;
 
   // 给各个 Repository 分配同一个 Agent SQLite 入口和事务入口。
   // AgentRuntimeKernel 构造时只创建一次，业务代码随后通过对应属性访问仓储。
@@ -48,12 +59,33 @@ export class RuntimeDatabase {
   ) {
     this.submissions = new SubmissionRepository(sql);
     this.approvals = new ApprovalRepository(sql);
+    this.interactions = new ToolInteractionRepository(sql);
     this.settlements = new ToolSettlementRepository(sql);
     this.milestones = new RecoveryMilestoneRepository(sql);
     this.extContext = new ExtContextRepository(sql);
     this.messageUi = new MessageUiRepository(sql);
     this.steers = new SteerRepository(sql);
     this.runtimeEvents = new RuntimeEventOutboxRepository(sql);
+    this.agentTools = new AgentToolRepository(sql);
+  }
+
+  /**
+   * 有未完成 Submission，且每一条都停在人机等待上。
+   *
+   * 换装配的忙碌闸门调用它。「停在等人」有两种形态：待决审批，和等客户端
+   * 投递结果的 Tool Interaction —— 两者都意味着没有模型请求在飞、没有工具
+   * 在执行，因此换掉能力语义是安全的。
+   *
+   * 注意它不是「存在待处理的人机等待」：只要有一条 Submission 正在真的执行，
+   * 整个判断就必须为假，否则会把执行中的 Turn 切成两套能力语义。
+   */
+  everyUnfinishedSubmissionParked(): boolean {
+    const unfinished = this.submissions.listUnfinishedIds();
+    if (unfinished.length === 0) return false;
+    return unfinished.every((submissionId) =>
+      this.approvals.listPendingForSubmission(submissionId).length > 0 ||
+      this.interactions.listPendingForSubmission(submissionId).length > 0
+    );
   }
 
   // 在一个同步 SQLite 事务里运行一组读写。
@@ -77,6 +109,7 @@ export class RuntimeDatabase {
     this.sql`DELETE FROM pi_pending_steers`;
     this.sql`DELETE FROM pi_submissions`;
     this.sql`DELETE FROM pi_approvals`;
+    this.sql`DELETE FROM pi_tool_interactions`;
     this.sql`DELETE FROM pi_tool_settlements`;
     this.sql`DELETE FROM pi_recovery_milestones`;
   }