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

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

@@ -0,0 +1,23 @@
+const encoder = new TextEncoder();
+
+function hex(bytes: ArrayBuffer): string {
+  return [...new Uint8Array(bytes)]
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+/** Stable, non-reversible Sandbox identifier for one owned Chat Session. */
+export async function sandboxIdForSession(
+  userId: string,
+  sessionId: string,
+): Promise<string> {
+  const digest = await crypto.subtle.digest(
+    "SHA-256",
+    // JSON string framing keeps the tuple unambiguous even when either ID
+    // contains the delimiter characters used by a human-readable format.
+    encoder.encode(
+      JSON.stringify(["universal-agent", userId, sessionId]),
+    ),
+  );
+  return `ua-${hex(digest).slice(0, 40)}`;
+}

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

@@ -0,0 +1,15 @@
+export const SANDBOX_HOST_POLICY = Object.freeze({
+  defaultExecTimeoutMs: 30_000,
+  maxExecTimeoutMs: 60_000,
+  maxOutputBytes: 64 * 1024,
+  maxBackgroundProcesses: 4,
+  maxBackgroundProcessAgeMs: 2 * 60 * 60_000,
+  maxPublishFiles: 100,
+  maxPublishEntries: 400,
+  maxPublishBytes: 25 * 1024 * 1024,
+  maxPublishFileBytes: 25 * 1024 * 1024,
+  maxHydrationFiles: 10_000,
+  maxHydrationEntries: 20_000,
+  maxHydrationBytes: 512 * 1024 * 1024,
+  maxHydrationManifestBytes: 1024 * 1024,
+} as const);

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

@@ -0,0 +1,574 @@
+import {
+  Agent,
+  type AgentContext,
+  type AgentToolProgressSnapshot,
+  type AgentToolRunInspection,
+  type AgentToolStoredChunk,
+  type FiberRecoveryContext,
+  type FiberRecoveryResult,
+} from "agents";
+import type { AgentEvent } from "@earendil-works/pi-agent-core";
+import {
+  AGENT_TYPES,
+} from "../../../layers/orchestration/subagents/agent-types/registry";
+import type { AgentType } from "../../../layers/orchestration/subagents/agent-types/contract";
+import type {
+  RuntimeProviderPort,
+  WorkspacePort,
+} from "../../../kernel/bindings";
+import { PiChunkEncoder } from "../../../pi/message";
+import {
+  createPiModels,
+  resolvePiApiKey,
+  resolvePiModel,
+  withProviderRetry,
+} from "../../../pi/runtime-adapter/models";
+import { runCloudflareSubAgent } from "./runner";
+import { createCloudflareSubAgentTools } from "./tools";
+
+type RunStatus =
+  | "starting"
+  | "running"
+  | "completed"
+  | "error"
+  | "aborted";
+
+interface RunRow {
+  run_id: string;
+  agent_type: string;
+  status: RunStatus;
+  input_json: string;
+  output_json: string | null;
+  summary: string | null;
+  error_message: string | null;
+  started_at: number;
+  completed_at: number | null;
+  progress_json: string | null;
+}
+
+interface ChunkRow {
+  sequence: number;
+  body: string;
+}
+
+interface TailSubscriber {
+  push(chunk: AgentToolStoredChunk): void;
+  close(): void;
+}
+
+const FIBER_NAME = "pi-subagent";
+const TERMINAL = new Set<RunStatus>([
+  "completed",
+  "error",
+  "aborted",
+]);
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function parseJson(value: string | null): unknown {
+  if (value === null) return undefined;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+
+function stringifyJson(value: unknown): string {
+  const json = JSON.stringify(value);
+  if (json === undefined) {
+    throw new Error("SubAgent input is not JSON serializable");
+  }
+  return json;
+}
+
+function progressFor(
+  event: AgentEvent,
+): Omit<AgentToolProgressSnapshot, "at"> | null {
+  if (event.type === "agent_start") {
+    return { phase: "running", message: "SubAgent started" };
+  }
+  if (event.type === "tool_execution_start") {
+    return {
+      phase: "tool",
+      message: `Running ${event.toolName}`,
+    };
+  }
+  if (event.type === "tool_execution_update") {
+    return {
+      phase: "tool",
+      message: `${event.toolName} is still running`,
+    };
+  }
+  if (event.type === "tool_execution_end") {
+    return {
+      phase: event.isError ? "tool-error" : "tool",
+      message: event.isError
+        ? `${event.toolName} failed`
+        : `${event.toolName} completed`,
+    };
+  }
+  return null;
+}
+
+/**
+ * Pi-native child Durable Object used by the Agents SDK Agent Tool protocol.
+ * The base Agent owns routing/facets; this class owns only bounded Pi
+ * inference plus its durable run/chunk adapter.
+ */
+export interface CloudflareSubAgentExecution {
+  provider: RuntimeProviderPort;
+  workspace: WorkspacePort;
+  loader: WorkerLoader;
+  outbound: Fetcher;
+}
+
+export abstract class CloudflareSubAgent<
+  Env extends Cloudflare.Env,
+> extends Agent<Env, Record<string, never>> {
+  initialState: Record<string, never> = {};
+
+  private readonly subscribers = new Map<
+    string,
+    Set<TailSubscriber>
+  >();
+
+  constructor(ctx: AgentContext, env: Env) {
+    super(ctx, env);
+    this.sql`
+      CREATE TABLE IF NOT EXISTS pi_subagent_runs (
+        run_id TEXT PRIMARY KEY,
+        agent_type TEXT NOT NULL,
+        status TEXT NOT NULL,
+        input_json TEXT NOT NULL,
+        output_json TEXT,
+        summary TEXT,
+        error_message TEXT,
+        started_at INTEGER NOT NULL,
+        completed_at INTEGER,
+        progress_json TEXT
+      )
+    `;
+    this.sql`
+      CREATE TABLE IF NOT EXISTS pi_subagent_chunks (
+        run_id TEXT NOT NULL,
+        sequence INTEGER NOT NULL,
+        body TEXT NOT NULL,
+        PRIMARY KEY (run_id, sequence)
+      )
+    `;
+  }
+
+  protected abstract prepareExecution(): Promise<CloudflareSubAgentExecution>;
+
+  private resolveType(name: string): AgentType {
+    const type = AGENT_TYPES.byName[name];
+    if (!type) throw new Error(`unknown SubAgent type: ${name}`);
+    return type;
+  }
+
+  private readRun(runId: string): RunRow | null {
+    return (
+      this.sql<RunRow>`
+        SELECT
+          run_id,
+          agent_type,
+          status,
+          input_json,
+          output_json,
+          summary,
+          error_message,
+          started_at,
+          completed_at,
+          progress_json
+        FROM pi_subagent_runs
+        WHERE run_id = ${runId}
+      `[0] ?? null
+    );
+  }
+
+  private readChunks(
+    runId: string,
+    afterSequence = -1,
+  ): AgentToolStoredChunk[] {
+    return this.sql<ChunkRow>`
+      SELECT sequence, body
+      FROM pi_subagent_chunks
+      WHERE run_id = ${runId} AND sequence > ${afterSequence}
+      ORDER BY sequence ASC
+    `;
+  }
+
+  private inspection(row: RunRow): AgentToolRunInspection {
+    const progress = parseJson(row.progress_json);
+    return {
+      runId: row.run_id,
+      status: row.status,
+      ...(row.output_json === null
+        ? {}
+        : { output: parseJson(row.output_json) }),
+      ...(row.summary === null ? {} : { summary: row.summary }),
+      ...(row.error_message === null
+        ? {}
+        : { error: row.error_message }),
+      startedAt: row.started_at,
+      ...(row.completed_at === null
+        ? {}
+        : { completedAt: row.completed_at }),
+      ...(typeof progress === "object" && progress !== null
+        ? { progress: progress as AgentToolProgressSnapshot }
+        : {}),
+    };
+  }
+
+  private appendChunk(runId: string, body: string): void {
+    const next =
+      this.sql<{ sequence: number }>`
+        SELECT COALESCE(MAX(sequence), -1) + 1 AS sequence
+        FROM pi_subagent_chunks
+        WHERE run_id = ${runId}
+      `[0]?.sequence ?? 0;
+    const chunk = { sequence: next, body };
+    this.sql`
+      INSERT INTO pi_subagent_chunks (run_id, sequence, body)
+      VALUES (${runId}, ${chunk.sequence}, ${chunk.body})
+    `;
+    for (const subscriber of this.subscribers.get(runId) ?? []) {
+      subscriber.push(chunk);
+    }
+  }
+
+  private persistProgress(
+    runId: string,
+    progress: Omit<AgentToolProgressSnapshot, "at">,
+  ): void {
+    const snapshot: AgentToolProgressSnapshot = {
+      ...progress,
+      at: Date.now(),
+    };
+    this.sql`
+      UPDATE pi_subagent_runs
+      SET progress_json = ${stringifyJson(snapshot)}
+      WHERE run_id = ${runId}
+    `;
+    this.appendChunk(
+      runId,
+      stringifyJson({
+        type: "data-agent-progress",
+        data: progress,
+      }),
+    );
+  }
+
+  private closeSubscribers(runId: string): void {
+    const subscribers = this.subscribers.get(runId);
+    if (!subscribers) return;
+    this.subscribers.delete(runId);
+    for (const subscriber of subscribers) subscriber.close();
+  }
+
+  private completeRun(runId: string, output: unknown): void {
+    const outputJson = stringifyJson(output);
+    this.sql`
+      UPDATE pi_subagent_runs
+      SET
+        status = 'completed',
+        output_json = ${outputJson},
+        summary = ${outputJson},
+        error_message = NULL,
+        completed_at = ${Date.now()}
+      WHERE run_id = ${runId}
+        AND status IN ('starting', 'running')
+    `;
+    this.closeSubscribers(runId);
+  }
+
+  private failRun(
+    runId: string,
+    status: "error" | "aborted",
+    error: string,
+  ): void {
+    this.sql`
+      UPDATE pi_subagent_runs
+      SET
+        status = ${status},
+        error_message = ${error},
+        completed_at = ${Date.now()}
+      WHERE run_id = ${runId}
+        AND status IN ('starting', 'running')
+    `;
+    this.closeSubscribers(runId);
+  }
+
+  private async executeRun(
+    runId: string,
+    type: AgentType,
+    input: unknown,
+    signal: AbortSignal,
+  ): Promise<void> {
+    if (TERMINAL.has(this.readRun(runId)?.status ?? "error")) return;
+    this.sql`
+      UPDATE pi_subagent_runs
+      SET status = 'running'
+      WHERE run_id = ${runId} AND status = 'starting'
+    `;
+
+    try {
+      const { provider, workspace, loader, outbound } =
+        await this.prepareExecution();
+      const models = createPiModels(provider);
+      const model = resolvePiModel(provider, provider.defaultModel);
+      const tools = createCloudflareSubAgentTools({
+        profile: type.tools,
+        workspace,
+        loader,
+        outbound,
+        settle: (call) => {
+          this.appendChunk(
+            runId,
+            stringifyJson({
+              type: "data-agent-progress",
+              data: {
+                phase: call.isError ? "tool-error" : "tool",
+                message: call.isError
+                  ? `${call.toolName} failed`
+                  : `${call.toolName} completed`,
+              },
+            }),
+          );
+        },
+      });
+      let streamSequence = 0;
+      const encoder = new PiChunkEncoder({
+        messageId: runId,
+        startedAt: this.readRun(runId)?.started_at ?? Date.now(),
+      });
+      const output = await runCloudflareSubAgent({
+        type,
+        input,
+        model,
+        streamFn: withProviderRetry(models.streamSimple.bind(models)),
+        getApiKey: () =>
+          resolvePiApiKey(provider, provider.defaultModel),
+        tools,
+        signal,
+        onEvent: (event) => {
+          for (const chunk of encoder.encode(event)) {
+            this.appendChunk(runId, stringifyJson({
+              v: 1,
+              messageId: runId,
+              sequence: streamSequence++,
+              chunk,
+            }));
+          }
+          const progress = progressFor(event);
+          if (progress) this.persistProgress(runId, progress);
+        },
+      });
+      this.completeRun(runId, output);
+    } catch (error) {
+      this.failRun(
+        runId,
+        signal.aborted ? "aborted" : "error",
+        signal.aborted ? "SubAgent run aborted" : errorMessage(error),
+      );
+    }
+  }
+
+  async startAgentToolRun(
+    input: unknown,
+    options: { runId: string; signal?: AbortSignal },
+  ): Promise<AgentToolRunInspection> {
+    const existing = this.readRun(options.runId);
+    if (existing) {
+      return (
+        (await this.inspectAgentToolRun(options.runId)) ??
+        this.inspection(existing)
+      );
+    }
+
+    const record =
+      typeof input === "object" && input !== null
+        ? (input as Record<string, unknown>)
+        : {};
+    const name = record.agentType;
+    if (typeof name !== "string") {
+      throw new Error(`unknown SubAgent type: ${String(name ?? "")}`);
+    }
+    const type = this.resolveType(name);
+    const { agentType: _agentType, ...rawInput } = record;
+    const parsed = type.inputSchema.safeParse(rawInput);
+    if (!parsed.success) {
+      throw new Error(
+        `SubAgent input failed schema validation: ${parsed.error.message}`,
+      );
+    }
+    const inputJson = stringifyJson(parsed.data);
+    const startedAt = Date.now();
+    this.sql`
+      INSERT INTO pi_subagent_runs (
+        run_id,
+        agent_type,
+        status,
+        input_json,
+        started_at
+      )
+      VALUES (
+        ${options.runId},
+        ${type.name},
+        'starting',
+        ${inputJson},
+        ${startedAt}
+      )
+    `;
+
+    const abort = () => {
+      void this.cancelAgentToolRun(options.runId).catch(() => {});
+    };
+    if (options.signal?.aborted) abort();
+    else options.signal?.addEventListener("abort", abort, { once: true });
+
+    try {
+      await this.startFiber(
+        FIBER_NAME,
+        (fiber) =>
+          this.executeRun(
+            options.runId,
+            type,
+            parsed.data,
+            fiber.signal,
+          ),
+        {
+          idempotencyKey: options.runId,
+          metadata: { runId: options.runId },
+          waitForCompletion: false,
+        },
+      );
+    } catch (error) {
+      this.failRun(options.runId, "error", errorMessage(error));
+    }
+
+    const row = this.readRun(options.runId);
+    if (!row) throw new Error("SubAgent run was not persisted");
+    return this.inspection(row);
+  }
+
+  async cancelAgentToolRun(
+    runId: string,
+    _reason?: unknown,
+  ): Promise<void> {
+    this.failRun(runId, "aborted", "SubAgent run aborted");
+    await this.cancelFiberByKey(runId, "SubAgent run aborted");
+  }
+
+  async inspectAgentToolRun(
+    runId: string,
+  ): Promise<AgentToolRunInspection | null> {
+    let row = this.readRun(runId);
+    if (!row) return null;
+    if (!TERMINAL.has(row.status)) {
+      const fiber = await this.inspectFiberByKey(runId);
+      if (
+        !fiber ||
+        fiber.status === "interrupted" ||
+        fiber.status === "error" ||
+        fiber.status === "completed"
+      ) {
+        this.failRun(
+          runId,
+          "error",
+          fiber?.error ?? "SubAgent run was interrupted before completion",
+        );
+      } else if (fiber.status === "aborted") {
+        this.failRun(runId, "aborted", "SubAgent run aborted");
+      }
+      row = this.readRun(runId);
+    }
+    return row ? this.inspection(row) : null;
+  }
+
+  async getAgentToolChunks(
+    runId: string,
+    options?: { afterSequence?: number },
+  ): Promise<AgentToolStoredChunk[]> {
+    return this.readChunks(runId, options?.afterSequence);
+  }
+
+  async tailAgentToolRun(
+    runId: string,
+    options?: { afterSequence?: number; signal?: AbortSignal },
+  ): Promise<ReadableStream<Uint8Array>> {
+    // Keep the replay read and live subscription in one synchronous section;
+    // otherwise a chunk emitted across an `await` could fall into the gap.
+    const chunks = this.readChunks(runId, options?.afterSequence);
+    const terminal = TERMINAL.has(
+      this.readRun(runId)?.status ?? "error",
+    );
+    let detach = () => {};
+
+    // Facet RPC only transports byte streams; runAgentTool decodes JSONL bytes.
+    const encode = (chunk: AgentToolStoredChunk) =>
+      new TextEncoder().encode(`${stringifyJson(chunk)}\n`);
+
+    return new ReadableStream({
+      type: "bytes",
+      start: (controller) => {
+        for (const chunk of chunks) controller.enqueue(encode(chunk));
+        if (terminal || options?.signal?.aborted) {
+          controller.close();
+          return;
+        }
+
+        const subscriber: TailSubscriber = {
+          push: (chunk) => controller.enqueue(encode(chunk)),
+          close: () => {
+            detach();
+            controller.close();
+          },
+        };
+        const set =
+          this.subscribers.get(runId) ?? new Set<TailSubscriber>();
+        set.add(subscriber);
+        this.subscribers.set(runId, set);
+
+        const abort = () => {
+          detach();
+          controller.close();
+        };
+        detach = () => {
+          options?.signal?.removeEventListener("abort", abort);
+          const current = this.subscribers.get(runId);
+          current?.delete(subscriber);
+          if (current?.size === 0) this.subscribers.delete(runId);
+        };
+        options?.signal?.addEventListener("abort", abort, {
+          once: true,
+        });
+      },
+      cancel: () => detach(),
+    });
+  }
+
+  override async onFiberRecovered(
+    context: FiberRecoveryContext,
+  ): Promise<void | FiberRecoveryResult> {
+    if (context.name !== FIBER_NAME) return;
+    const runId =
+      typeof context.metadata?.runId === "string"
+        ? context.metadata.runId
+        : context.idempotencyKey;
+    if (runId) {
+      this.failRun(
+        runId,
+        "error",
+        "SubAgent run was interrupted before completion",
+      );
+    }
+    return {
+      status: "interrupted",
+      reason: "SubAgent run was interrupted before completion",
+    };
+  }
+}