@springbrand/agent-runtime 0.1.3-alpha.3 → 0.1.3-alpha.5

package/src/adapter/cloudflare/workspace/scoped-workspace.ts

@@ -0,0 +1,376 @@
+import type {
+  WorkspaceAdminPort,
+  WorkspaceFileInfo,
+  WorkspacePort,
+  WorkspaceQuota,
+  WorkspaceUsage,
+} from "../../../kernel/bindings";
+import type {
+  WorkspaceConditionalWriteResult,
+  WorkspaceFileVersion,
+} from "./publisher";
+
+const USAGE_PAGE_SIZE = 256;
+const UNCONFIGURED_QUOTA: WorkspaceQuota = Object.freeze({
+  maxFiles: null,
+  maxTotalBytes: null,
+  maxFileBytes: null,
+});
+
+function normalizePath(path: string): string {
+  const value = path.trim().replaceAll("\\", "/");
+  const absolute = value.startsWith("/") ? value : `/${value}`;
+  const parts = absolute.split("/").filter(Boolean);
+  if (parts.some((part) => part === ".." || part === ".")) {
+    throw new Error("workspace path traversal is not allowed");
+  }
+  return `/${parts.join("/")}`;
+}
+
+function isReservedMemoryPath(path: string): boolean {
+  return path === "/shared/memories" || path.startsWith("/shared/memories/");
+}
+
+/**
+ * A Session sees the user's shared mount plus its own directory. All other
+ * paths are interpreted relative to the current Session directory; another
+ * Session can never be named through this port. The Inbox Host also uses this
+ * object to create and remove the Session tree, so callers never need to build
+ * the physical `/sessions/<id>` path themselves.
+ */
+export class ScopedWorkspace implements WorkspacePort, WorkspaceAdminPort {
+  readonly sessionRoot: string;
+
+  constructor(
+    private readonly parent: WorkspacePort,
+    readonly sessionId: string,
+    private readonly quota: WorkspaceQuota = UNCONFIGURED_QUOTA,
+  ) {
+    if (!sessionId || sessionId.includes("/") || sessionId === "." || sessionId === "..") {
+      throw new Error("invalid session id");
+    }
+    this.sessionRoot = `/sessions/${sessionId}`;
+  }
+
+  async ensure(): Promise<void> {
+    await this.parent.mkdir("/shared", { recursive: true });
+    await this.parent.mkdir(this.sessionRoot, { recursive: true });
+  }
+
+  /**
+   * Count only this Session's private tree. User-level `/shared` belongs to the
+   * Inbox and must not be charged once per Chat.
+   */
+  async getUsage(): Promise<WorkspaceUsage> {
+    if (!(await this.parent.exists(this.sessionRoot))) {
+      return { fileCount: 0, directoryCount: 0, totalBytes: 0 };
+    }
+
+    let fileCount = 0;
+    let directoryCount = 0;
+    let totalBytes = 0;
+    const pending = [this.sessionRoot];
+
+    while (pending.length > 0) {
+      const directory = pending.pop()!;
+      let offset = 0;
+      while (true) {
+        const entries = await this.parent.readDir(directory, {
+          limit: USAGE_PAGE_SIZE,
+          offset,
+        });
+        for (const entry of entries) {
+          if (entry.type === "directory") {
+            directoryCount += 1;
+            pending.push(entry.path);
+          } else {
+            fileCount += 1;
+            totalBytes += entry.size;
+          }
+        }
+        if (entries.length < USAGE_PAGE_SIZE) break;
+        offset += entries.length;
+      }
+    }
+
+    return { fileCount, directoryCount, totalBytes };
+  }
+
+  async getQuota(): Promise<WorkspaceQuota> {
+    return { ...this.quota };
+  }
+
+  /** Host-only lifecycle operation. It never removes the user-level `/shared` tree. */
+  async removeAll(): Promise<void> {
+    await this.parent.rm(this.sessionRoot, {
+      recursive: true,
+      force: true,
+    });
+  }
+
+  private physical(path: string): string {
+    const normalized = normalizePath(path);
+    if (normalized === "/shared" || normalized.startsWith("/shared/")) {
+      return normalized;
+    }
+    if (normalized === this.sessionRoot || normalized.startsWith(`${this.sessionRoot}/`)) {
+      return normalized;
+    }
+    if (normalized === "/sessions" || normalized.startsWith("/sessions/")) {
+      throw new Error("another Session workspace is not accessible");
+    }
+    return normalized === "/"
+      ? this.sessionRoot
+      : `${this.sessionRoot}${normalized}`;
+  }
+
+  private writablePhysical(path: string): string {
+    const physical = this.physical(path);
+    if (isReservedMemoryPath(physical)) {
+      throw new Error("/shared/memories is read-only in Session workspaces");
+    }
+    return physical;
+  }
+
+  private async assertNoSymlinkComponents(path: string): Promise<void> {
+    let root: string;
+    if (path === "/shared" || path.startsWith("/shared/")) {
+      root = "/shared";
+    } else if (
+      path === this.sessionRoot ||
+      path.startsWith(`${this.sessionRoot}/`)
+    ) {
+      root = this.sessionRoot;
+    } else {
+      throw new Error("another Session workspace is not accessible");
+    }
+    const relative = path.slice(root.length);
+    const parts = relative.split("/").filter(Boolean);
+    let current = root;
+
+    for (const part of ["", ...parts]) {
+      if (part) current = `${current}/${part}`;
+      const info = await this.parent.lstat(current);
+      if (!info) return;
+      if (info.type === "symlink") {
+        throw new Error(
+          "symbolic links are not accessible in scoped workspaces",
+        );
+      }
+    }
+  }
+
+  private async guardedPhysical(
+    path: string,
+    writable = false,
+  ): Promise<string> {
+    const physical = writable
+      ? this.writablePhysical(path)
+      : this.physical(path);
+    await this.assertNoSymlinkComponents(physical);
+    return physical;
+  }
+
+  private virtual(path: string): string {
+    if (path === this.sessionRoot) return "/";
+    if (path.startsWith(`${this.sessionRoot}/`)) {
+      return path.slice(this.sessionRoot.length);
+    }
+    return path;
+  }
+
+  private project(info: WorkspaceFileInfo | null): WorkspaceFileInfo | null {
+    return info ? { ...info, path: this.virtual(info.path) } : null;
+  }
+
+  async readFile(path: string) {
+    return this.parent.readFile(await this.guardedPhysical(path));
+  }
+
+  async readFileBytes(path: string) {
+    return this.parent.readFileBytes(await this.guardedPhysical(path));
+  }
+
+  async writeFile(path: string, content: string, mimeType?: string) {
+    return this.parent.writeFile(
+      await this.guardedPhysical(path, true),
+      content,
+      mimeType,
+    );
+  }
+
+  async writeFileBytes(
+    path: string,
+    data: Uint8Array | ArrayBuffer,
+    mimeType?: string,
+  ) {
+    return this.parent.writeFileBytes(
+      await this.guardedPhysical(path, true),
+      data,
+      mimeType,
+    );
+  }
+
+  async writeFileBytesIfUnchanged(
+    path: string,
+    data: Uint8Array,
+    mimeType: string,
+    expected: WorkspaceFileVersion | null,
+  ): Promise<WorkspaceConditionalWriteResult> {
+    const physical = await this.guardedPhysical(path, true);
+    if (physical === "/shared" || physical.startsWith("/shared/")) {
+      throw new Error("/shared is read-only for Sandbox publishing");
+    }
+    const current = await this.parent.stat(physical);
+    const currentVersion =
+      current?.type === "file"
+        ? { updatedAt: current.updatedAt, size: current.size }
+        : null;
+    const matches =
+      expected === null
+        ? current === null
+        : current?.type === "file" &&
+          current.updatedAt === expected.updatedAt &&
+          current.size === expected.size;
+    if (!matches) {
+      return {
+        written: false,
+        reason: "conflict",
+        current: currentVersion,
+      };
+    }
+    await this.parent.writeFileBytes(physical, data, mimeType);
+    const written = await this.parent.stat(physical);
+    if (!written || written.type !== "file") {
+      throw new Error("published Workspace file could not be verified");
+    }
+    return {
+      written: true,
+      version: {
+        updatedAt: written.updatedAt,
+        size: written.size,
+      },
+    };
+  }
+
+  async appendFile(path: string, content: string, mimeType?: string) {
+    return this.parent.appendFile(
+      await this.guardedPhysical(path, true),
+      content,
+      mimeType,
+    );
+  }
+
+  async exists(path: string) {
+    return this.parent.exists(await this.guardedPhysical(path));
+  }
+
+  async stat(path: string) {
+    return this.project(
+      await this.parent.stat(await this.guardedPhysical(path)),
+    );
+  }
+
+  async lstat(path: string) {
+    return this.project(
+      await this.parent.lstat(await this.guardedPhysical(path)),
+    );
+  }
+
+  async mkdir(path: string, opts?: { recursive?: boolean }) {
+    return this.parent.mkdir(await this.guardedPhysical(path, true), opts);
+  }
+
+  async readDir(dir = "/", opts?: { limit?: number; offset?: number }) {
+    const files = await this.parent.readDir(
+      await this.guardedPhysical(dir),
+      opts,
+    );
+    return files.map((file) => this.project(file)!);
+  }
+
+  async rm(path: string, opts?: { recursive?: boolean; force?: boolean }) {
+    const physical = await this.guardedPhysical(path, true);
+    if (physical === "/shared" || physical === this.sessionRoot) {
+      throw new Error("workspace mount roots cannot be removed");
+    }
+    return this.parent.rm(physical, opts);
+  }
+
+  async cp(src: string, dest: string, opts?: { recursive?: boolean }) {
+    return this.parent.cp(
+      await this.guardedPhysical(src),
+      await this.guardedPhysical(dest, true),
+      opts,
+    );
+  }
+
+  async mv(src: string, dest: string, opts?: { recursive?: boolean }) {
+    return this.parent.mv(
+      await this.guardedPhysical(src, true),
+      await this.guardedPhysical(dest, true),
+      opts,
+    );
+  }
+
+  async symlink(target: string, linkPath: string) {
+    /*
+     * A symlink stored under `/shared` could target this Session's physical
+     * directory and then be followed by another Session. Path normalization
+     * cannot guard a later filesystem dereference, so scoped runtimes do not
+     * create symlinks at all.
+     */
+    void target;
+    void linkPath;
+    throw new Error("symbolic links are disabled in scoped workspaces");
+  }
+
+  async readlink(path: string) {
+    return this.virtual(
+      await this.parent.readlink(await this.guardedPhysical(path)),
+    );
+  }
+
+  async glob(pattern: string) {
+    const files = await this.parent.glob(this.physical(pattern));
+    for (const file of files) {
+      await this.assertNoSymlinkComponents(file.path);
+    }
+    return files.map((file) => this.project(file)!);
+  }
+}
+
+/**
+ * Build a runtime capability object that contains data-plane methods only.
+ *
+ * A TypeScript annotation does not remove extra methods at runtime. Returning
+ * this explicit facade prevents Agent Runtime and Sandbox adapters from
+ * reaching ScopedWorkspace lifecycle/accounting methods through the same
+ * object reference.
+ */
+export function createWorkspacePortFacade(
+  workspace: WorkspacePort,
+): WorkspacePort {
+  const facade: WorkspacePort = {
+    readFile: (path) => workspace.readFile(path),
+    readFileBytes: (path) => workspace.readFileBytes(path),
+    writeFile: (path, content, mimeType) =>
+      workspace.writeFile(path, content, mimeType),
+    writeFileBytes: (path, data, mimeType) =>
+      workspace.writeFileBytes(path, data, mimeType),
+    appendFile: (path, content, mimeType) =>
+      workspace.appendFile(path, content, mimeType),
+    exists: (path) => workspace.exists(path),
+    stat: (path) => workspace.stat(path),
+    lstat: (path) => workspace.lstat(path),
+    mkdir: (path, opts) => workspace.mkdir(path, opts),
+    readDir: (dir, opts) => workspace.readDir(dir, opts),
+    rm: (path, opts) => workspace.rm(path, opts),
+    cp: (src, dest, opts) => workspace.cp(src, dest, opts),
+    mv: (src, dest, opts) => workspace.mv(src, dest, opts),
+    symlink: (target, linkPath) => workspace.symlink(target, linkPath),
+    readlink: (path) => workspace.readlink(path),
+    glob: (pattern) => workspace.glob(pattern),
+  };
+  return Object.freeze(facade);
+}

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`;
   }