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

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

@@ -0,0 +1,273 @@
+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;
+  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.admission ? { admission: options.admission } : {}),
+      ...(options.observer ? { observer: options.observer } : {}),
+    }),
+    degradations: [],
+  };
+}

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

@@ -0,0 +1,74 @@
+import type {
+  RuntimeCodeExecutionPort,
+  RuntimeMemoryPort,
+  RuntimeSandboxPort,
+  RuntimeSchedulePort,
+  RuntimeSubagentPort,
+  WorkspacePort,
+} from "../../../kernel/bindings";
+import type { RuntimeDegradation } from "../../../kernel/degradation";
+import type { RuntimeMemoryProfile } from "../../../kernel/profile";
+import { createCodeExecutionTool } from "../../../pi/tool/core";
+import { createScheduleTools } from "../../../pi/tool/schedule";
+import { createSubagentTools } from "../../../pi/tool/subagent";
+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;
+  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.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/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>;
+}