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

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

@@ -0,0 +1,277 @@
+import type { Sandbox } from "@cloudflare/sandbox";
+import type {
+  ChatCapableAgentClass,
+  RunAgentToolOptions,
+} from "agents";
+import type {
+  RuntimeBrowserPort,
+  RuntimeMemoryPort,
+  RuntimePlatformPort,
+  RuntimeSubagentPort,
+  WorkspacePort,
+} from "../../../kernel/bindings";
+import type { RuntimeDegradation } from "../../../kernel/degradation";
+import type { RuntimeMemoryProfile } from "../../../kernel/profile";
+import { AGENT_TYPES } from "../../../layers/orchestration/subagents/agent-types/registry";
+import type { RuntimeAgentConfigContext } from "../../../runtime-agent-context";
+import { createWorkspaceCodeExecutionPort } from "../../../pi/tool/core-host";
+import {
+  createCloudflareSandboxAdapter,
+  type SandboxAdmission,
+  type SandboxObserver,
+} from "../sandbox/adapter";
+import { sandboxIdForSession } from "../sandbox/id";
+import type { WorkspacePublishPort } from "../workspace/publisher";
+
+export type WorkspaceLoader = () => Promise<{
+  value: WorkspacePort | undefined;
+  degradations: readonly RuntimeDegradation[];
+}>;
+
+export type PlatformLoader = () => Promise<RuntimePlatformPort>;
+
+export interface CloudflarePlatformBindings {
+  LOADER: WorkerLoader;
+  BROWSER?: RuntimeBrowserPort;
+  TELEMETRY_CONSOLE?: string;
+}
+
+export interface WorkspaceRequirement {
+  memoryEnabled?: boolean;
+  sandboxEnabled?: boolean;
+  deniedToolNames?: readonly string[];
+  skillWorkspaceModes?: readonly ("none" | "read" | "read-write")[];
+  extensionWorkspaceModes?: readonly ("none" | "read" | "read-write")[];
+}
+
+const DEFAULT_MEMORY: RuntimeMemoryProfile = Object.freeze({
+  enabled: true,
+  memoryTokens: 2_000,
+  preferencesTokens: 500,
+});
+
+const WORKSPACE_TOOL_NAMES = [
+  "read",
+  "write",
+  "edit",
+  "list",
+  "find",
+  "grep",
+  "delete",
+  "bash",
+  "execute",
+] as const;
+
+export function workspaceRequired(input: WorkspaceRequirement): boolean {
+  const denied = new Set(input.deniedToolNames ?? []);
+  return input.memoryEnabled !== false ||
+    input.sandboxEnabled === true ||
+    input.skillWorkspaceModes?.some((mode) => mode !== "none") === true ||
+    input.extensionWorkspaceModes?.some((mode) => mode !== "none") === true ||
+    WORKSPACE_TOOL_NAMES.some((name) => !denied.has(name));
+}
+
+export function createWorkspaceLoader(
+  load: () => WorkspacePort,
+): WorkspaceLoader {
+  let cached: ReturnType<WorkspaceLoader> | undefined;
+  return () => cached ??= Promise.resolve().then(() => {
+    try {
+      const workspace = load();
+      return {
+        value: workspace,
+        degradations: [],
+      };
+    } catch (error) {
+      return {
+        value: undefined,
+        degradations: [{
+          capability: "workspace" as const,
+          reason: "unavailable" as const,
+          detail: error instanceof Error ? error.message : String(error),
+        }],
+      };
+    }
+  });
+}
+
+export function createPlatformLoader<
+  Env extends Cloudflare.Env & CloudflarePlatformBindings,
+>(context: RuntimeAgentConfigContext<Env>): PlatformLoader {
+  let cached: ReturnType<PlatformLoader> | undefined;
+  return () => cached ??= Promise.resolve().then(() => {
+    const exports = (context.ctx as unknown as {
+      exports: {
+        HttpGateway(options: Record<string, never>): Fetcher;
+      };
+    }).exports;
+    return {
+      loader: context.env.LOADER,
+      ...(context.env.BROWSER ? { browser: context.env.BROWSER } : {}),
+      outbound: () => exports.HttpGateway({}),
+      telemetryConsole: context.env.TELEMETRY_CONSOLE === "1",
+    };
+  });
+}
+
+export async function prepareWorkspace<Env extends Cloudflare.Env>(
+  context: RuntimeAgentConfigContext<Env>,
+  workspaceLoader: WorkspaceLoader,
+  platformLoader: PlatformLoader,
+) {
+  const [workspace, platform] = await Promise.all([
+    workspaceLoader(),
+    platformLoader(),
+  ]);
+  if (!workspace.value) return { degradations: workspace.degradations };
+  return {
+    workspace: workspace.value,
+    codeExecution: createWorkspaceCodeExecutionPort({
+      ctx: context.ctx,
+      loader: platform.loader,
+      outbound: platform.outbound(),
+      workspace: workspace.value,
+    }),
+    degradations: workspace.degradations,
+  };
+}
+
+export async function prepareMemory(
+  configured: Partial<RuntimeMemoryProfile> | null | undefined,
+  workspaceLoader: WorkspaceLoader,
+  port: RuntimeMemoryPort,
+): Promise<{
+  memoryProfile: RuntimeMemoryProfile;
+  memory?: RuntimeMemoryPort;
+  degradations: RuntimeDegradation[];
+}> {
+  const memoryConfig = configured ?? {};
+  if (memoryConfig.enabled === false) {
+    return {
+      memoryProfile: { ...DEFAULT_MEMORY, ...memoryConfig },
+      degradations: [{
+        capability: "memory" as const,
+        reason: "not_configured" as const,
+      }],
+    };
+  }
+  const workspace = (await workspaceLoader()).value;
+  const memoryProfile = {
+    ...DEFAULT_MEMORY,
+    ...memoryConfig,
+    enabled: workspace !== undefined,
+  };
+  return {
+    memoryProfile,
+    ...(memoryProfile.enabled ? { memory: port } : {}),
+    degradations: memoryProfile.enabled
+      ? []
+      : [{
+          capability: "memory" as const,
+          reason: "unavailable" as const,
+        }],
+  };
+}
+
+export async function prepareSubagents<Env extends Cloudflare.Env>(
+  context: RuntimeAgentConfigContext<Env>,
+  requested: readonly string[],
+  agentClass: ChatCapableAgentClass,
+) {
+  const enabledSubagents: string[] = [];
+  const degradations: RuntimeDegradation[] = [];
+
+  for (const name of new Set(requested.filter(Boolean))) {
+    if (name in AGENT_TYPES.byName) enabledSubagents.push(name);
+    else {
+      degradations.push({
+        capability: "subagent",
+        reason: "not_deployed",
+        detail: name,
+      });
+    }
+  }
+
+  const subagents: RuntimeSubagentPort = {
+    run: async (agentType, input, options) => {
+      const runOptions: RunAgentToolOptions<unknown> = {
+        input: { agentType, ...input },
+      };
+      if (options?.detached) {
+        runOptions.detached = { maxBudgetMs: options.maxBudgetMs };
+        if (options.notifySource) {
+          runOptions.detached.notify = { source: options.notifySource };
+        }
+      }
+      const result = await context.runAgentTool(agentClass, runOptions);
+      return {
+        status: result.status,
+        runId: result.runId,
+        output: result.output,
+        error: result.error,
+      };
+    },
+  };
+
+  return {
+    enabledSubagents,
+    ...(enabledSubagents.length > 0 ? { subagents } : {}),
+    degradations,
+  };
+}
+
+export async function prepareSandbox(options: {
+  enabled: boolean;
+  deploymentEnabled: boolean;
+  namespace?: DurableObjectNamespace<Sandbox>;
+  userId: string;
+  sessionId: string;
+  workspaceLoader: WorkspaceLoader;
+  publisher: WorkspacePublishPort;
+  onPublishComplete?: () => Promise<void>;
+  admission?: SandboxAdmission;
+  observer?: SandboxObserver;
+}) {
+  if (!options.enabled) return { degradations: [] };
+  if (!options.deploymentEnabled) {
+    return {
+      degradations: [{
+        capability: "sandbox" as const,
+        reason: "disabled_by_deployment" as const,
+      }],
+    };
+  }
+  if (!options.namespace) {
+    return {
+      degradations: [{
+        capability: "sandbox" as const,
+        reason: "unavailable" as const,
+        detail: "sandbox_binding_missing",
+      }],
+    };
+  }
+  const workspace = (await options.workspaceLoader()).value;
+  if (!workspace) {
+    return {
+      degradations: [{
+        capability: "sandbox" as const,
+        reason: "unavailable" as const,
+        detail: "persistent_workspace_unavailable",
+      }],
+    };
+  }
+  return {
+    sandbox: createCloudflareSandboxAdapter({
+      sandboxNamespace: options.namespace,
+      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 } : {}),
+    }),
+    degradations: [],
+  };
+}

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

@@ -0,0 +1,80 @@
+import type {
+  RuntimeCodeExecutionPort,
+  RuntimeMemoryPort,
+  RuntimeSandboxPort,
+  RuntimeSchedulePort,
+  RuntimeSubagentPort,
+  WorkspacePort,
+} 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,
+} from "../../../pi/tool/workspace-sandbox";
+import {
+  mergeToolRegistries,
+  type ToolAssemblyResult,
+  type ToolRegistry,
+} from "../../../tool-registry";
+
+export function selectTools(
+  tools: ToolRegistry,
+  names: Iterable<string>,
+): ToolRegistry {
+  const selected = new Set(names);
+  return Object.fromEntries(
+    Object.entries(tools).filter(([name]) => selected.has(name)),
+  );
+}
+
+export function assembleUniversalAgentTools(options: {
+  hostTools?: ToolRegistry;
+  workspace?: WorkspacePort;
+  workspaceRevisions?: WorkspaceRevisionRestorePort;
+  codeExecution?: RuntimeCodeExecutionPort;
+  sandbox?: RuntimeSandboxPort;
+  schedule?: RuntimeSchedulePort;
+  subagents?: RuntimeSubagentPort;
+  enabledSubagents?: readonly string[];
+  memory?: RuntimeMemoryPort;
+  memoryProfile: RuntimeMemoryProfile;
+  degradations?: readonly RuntimeDegradation[];
+  dispose?: () => Promise<void>;
+}): ToolAssemblyResult {
+  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 {
+    tools,
+    bindings: {
+      ...(options.workspace ? { workspace: options.workspace } : {}),
+      ...(options.memory ? { memory: options.memory } : {}),
+    },
+    enabledSubagents: options.enabledSubagents ?? [],
+    memoryProfile: options.memoryProfile,
+    degradations: options.degradations ?? [],
+    ...(options.dispose ? { dispose: options.dispose } : {}),
+  };
+}

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

package/src/adapter/cloudflare/workspace/publisher.ts

@@ -0,0 +1,31 @@
+export interface WorkspaceFileVersion {
+  updatedAt: number;
+  size: number;
+}
+
+export type WorkspaceConditionalWriteResult =
+  | {
+      written: true;
+      version: WorkspaceFileVersion;
+    }
+  | {
+      written: false;
+      reason: "conflict";
+      current: WorkspaceFileVersion | null;
+    };
+
+/**
+ * Host-only compare-and-write capability used by Sandbox publishing.
+ *
+ * Runtime and the model never receive this port. The expected version comes
+ * from the automatic hydration snapshot, so a later Workspace edit cannot be
+ * overwritten silently.
+ */
+export interface WorkspacePublishPort {
+  writeFileBytesIfUnchanged(
+    path: string,
+    data: Uint8Array,
+    mimeType: string,
+    expected: WorkspaceFileVersion | null,
+  ): Promise<WorkspaceConditionalWriteResult>;
+}