@springbrand/agent-runtime 0.1.3-alpha.4 → 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/index.ts

@@ -22,9 +22,10 @@
  * - `SubAgent` 是由父 Agent 发起、但拥有独立执行上下文的子任务执行者。
  * - `canonical transcript` 是 Pi 持久化和恢复 Turn 时使用的权威消息历史。
  * - `admission` 是提示进入 Turn 前的接纳、去重和状态登记流程。
- * - `RuntimeAssemblyInput` 是 Host Planner 交给 Runtime 的一次性扁平装配输入。
- * - `Runtime Planner` 读取有效配置并准备本轮实际需要的 Port 与贡献。
- * - `Port` 是 Runtime 调用外部能力时依赖的最小接口。
+ * - `defineRuntimeAgent.load` 返回 config 和已加载 Resource。
+ * - `defineRuntimeAgent.tools` 是 Host 第一层 Tool 注册表声明。
+ * - `assembleRuntimeSnapshot` 消费该输入与 hooks，产出候选 Snapshot。
+ * - `Port` 是 Runtime 调用外部能力时依赖的最小接口（Definition 作者不直接装配）。
  * - `RuntimeBindings` 是本次装配选中的 Port 和可执行对象集合。
  * - `RuntimeBuilder` 是包内实现，用来校验贡献并生成候选结果。
  * - `RuntimeCandidate` 是尚未生效的候选结果和提交前检查。
@@ -36,7 +37,7 @@
  *
  * Snapshot 不允许替换已选集合，但不承诺把每个 Port 的内部对象深冻结。
  *
- * 正常调用顺序是 `plan → validate → freeze → guard → commit`。
+ * 正常调用顺序是 `assemble → validate → freeze → guard → commit`。
  * Runtime 独占跨能力校验和原子提交。
  *
  * @packageDocumentation
@@ -46,6 +47,7 @@ export * from "./kernel/extensions";
 export * from "./kernel/profile";
 export * from "./kernel/receipts";
 export * from "./kernel/runtime-config";
+export type { RuntimeAssemblyView } from "./kernel/runtime-assembly-view";
 export * from "./runtime-agent";
 export * from "./kernel/state";
 export * from "./lib/execution-level";
@@ -57,6 +59,31 @@ export type {
   RuntimeSkillContribution,
   RuntimeToolSurfacePolicy,
 } from "./runtime-assembler";
+export { assembleRuntimeSnapshot, toolRegistryPiToolCandidates } from "./runtime-assembler";
+export type {
+  PlatformToolContext,
+  PlatformToolRegistry,
+  PlatformToolSpec,
+  ProfileOverrides,
+  ResolvedConnectors,
+  ResolvedResources,
+  RuntimeAgentContext,
+  RuntimeAgentHooks,
+  RuntimeSettings,
+  RuntimeToolBindings,
+  ToolAssemblyResult,
+  ToolContext,
+  ToolRegistry,
+  ToolSpec,
+} from "./runtime-definition";
+export {
+  emptyPlatformToolRegistry,
+  emptyToolRegistry,
+  mergeToolRegistries,
+  normalizeToolAssembly,
+  piCandidateToToolSpec,
+  toolRegistryFromPiCandidates,
+} from "./tool-registry";
 export type { ModelOption } from "./lib/model-catalog";
 export {
   assembleSubagentPrompt,
@@ -82,16 +109,30 @@ export type {
   SettledPiToolCall,
 } from "./pi/tool";
 export { basePiToolCandidates } from "./pi/tool";
-export { schedulePiToolCandidates } from "./pi/tool";
 export {
+  createMemoryTools,
+  memoryPiToolCandidate,
+} from "./pi/tool";
+export {
+  createScheduleTools,
+  schedulePiToolCandidates,
+} from "./pi/tool";
+export {
+  createSandboxTools,
+  createWorkspaceTools,
   sandboxPiToolCandidates,
   workspacePiToolCandidates,
 } from "./pi/tool";
-export { subagentPiToolCandidates } from "./pi/tool";
+export {
+  createSubagentTools,
+  subagentPiToolCandidates,
+} from "./pi/tool";
 export { skillPiToolCandidates } from "./pi/tool";
 export type { PiSkillBinding } from "./pi/tool";
 export {
   browserQuickActionPiToolCandidates,
+  createCodeExecutionTool,
+  codeExecutionPiToolCandidate,
 } from "./pi/tool";
 export {
   createWorkspaceCodeExecutionPort,
@@ -103,10 +144,11 @@ export {
 export type {
   TemporaryAgentApprovalDecision,
   TemporaryAgentApprovalRequest,
-  TemporaryAgentExecutor,
+  TemporaryAgentLaunch,
   TemporaryAgentRequest,
   TemporaryAgentRunContext,
 } from "./layers/orchestration/temporary-agent/core";
+export { TEMPORARY_AGENT_LAUNCH_KEY } from "./layers/orchestration/temporary-agent/core";
 export {
   temporaryAgentExtensionIsSafe,
   temporaryAgentToolAllowed,

package/src/layers/orchestration/temporary-agent/core.ts

@@ -1,9 +1,21 @@
+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;
@@ -149,4 +161,3 @@ export class TemporaryAgentCoordinator {
     });
   }
 }
-import type { ExecutionLevel } from "../../../lib/execution-level";

package/src/layers/orchestration/temporary-agent/runner.ts

@@ -10,7 +10,6 @@ const BLOCKED_TOOLS = new Set([
   "resume_schedule",
   "change_schedule_agent",
   "cancel_schedule",
-  "execute",
   "set_context",
   "load_context",
   "search_context",
@@ -25,7 +24,7 @@ const BLOCKED_TOOLS = new Set([
  * @remarks
  * 宿主在装配临时 Agent 的平台、Workspace、Sandbox 和其他 Tool 时调用；调用方可再加名字或前缀黑名单。
  *
- * 固定黑名单排除再次委派、调度、主 Session 上下文和绕过隔离边界的 execute，以保持单层临时 Agent 和已确认的继承范围。
+ * 固定黑名单排除再次委派、调度和主 Session 上下文，以保持单层临时 Agent 和已确认的继承范围。
  *
  * Agent、Session、Workspace 和 Tool 的术语见 `src/index.ts`。
  */

package/src/pi/message/contract.ts

@@ -2,6 +2,13 @@ import type { UIMessage } from "ai";
 
 export type UIChatTrigger = "submit-message" | "regenerate-message";
 
+/** A user-selected Runtime capability persisted with the visible UIMessage. */
+export interface RequestedCapability {
+  readonly kind: "skill" | "plan";
+  readonly name: string;
+  readonly label: string;
+}
+
 export interface UIChatRequestBody {
   readonly messages: readonly UIMessage[];
   readonly trigger: UIChatTrigger;