@agentstep/agent-sdk 0.1.0

package/package.json

@@ -0,0 +1,45 @@
+{
+  "license": "Apache-2.0",
+  "name": "@agentstep/agent-sdk",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./queue": "./src/queue/index.ts",
+    "./config": "./src/config/index.ts",
+    "./backends/claude": "./src/backends/claude/index.ts",
+    "./backends/codex": "./src/backends/codex/index.ts",
+    "./backends/opencode": "./src/backends/opencode/index.ts",
+    "./handlers": "./src/handlers/index.ts",
+    "./*": "./src/*.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentstep/gateway.git",
+    "directory": "packages/agent-sdk"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@asteasolutions/zod-to-openapi": "^7.3.4",
+    "libsql": "^0.5.29",
+    "ulid": "^2.3.0",
+    "ws": "^8.18.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@types/ws": "^8.5.13",
+    "typescript": "^5.9.3",
+    "vitest": "^2.1.0"
+  }
+}

package/src/auth/middleware.ts

@@ -0,0 +1,38 @@
+/**
+ * Authentication middleware.
+ *
+ * Extracts an API key from `x-api-key` (preferred per Managed Agents spec)
+ * or `Authorization: Bearer <token>`. Hashes with sha256 and looks it up in
+ * the `api_keys` table. Returns an AuthContext on success.
+ *
+ * Simplified rewrite of
+ *  —
+ * no WorkOS, no grace cache, no admin bypass key.
+ */
+import { findByRawKey } from "../db/api_keys";
+import type { AuthContext } from "../types";
+import { unauthorized } from "../errors";
+
+export function extractKey(request: Request): string | null {
+  const xKey = request.headers.get("x-api-key");
+  if (xKey && xKey.length > 0) return xKey;
+
+  const auth = request.headers.get("authorization") || request.headers.get("Authorization");
+  if (!auth) return null;
+  const m = /^Bearer\s+(.+)$/i.exec(auth);
+  return m ? m[1] : null;
+}
+
+export async function authenticate(request: Request): Promise<AuthContext> {
+  const key = extractKey(request);
+  if (!key) throw unauthorized();
+
+  const row = findByRawKey(key);
+  if (!row) throw unauthorized();
+
+  return {
+    keyId: row.id,
+    name: row.name,
+    permissions: JSON.parse(row.permissions_json) as string[],
+  };
+}

package/src/backends/claude/args.ts

@@ -0,0 +1,88 @@
+/**
+ * Build the `claude -p` argv for one turn.
+ *
+ * Collapses multi-CLI
+ * 
+ * down to the claude-only shape this service needs.
+ *
+ * Always emits:
+ *   -p --output-format stream-json --verbose
+ *   --permission-mode bypassPermissions --max-turns <N>
+ *
+ * Adds `--resume <claude_session_id>` on every turn ≥ 2 using the most
+ * recently observed id from the previous turn's `system.init`.
+ */
+import { getConfig } from "../../config";
+import type { Agent, McpServerConfig } from "../../types";
+import { resolveToolset } from "../../sessions/tools";
+
+export interface BuildArgsInput {
+  agent: Agent;
+  claudeSessionId?: string | null;
+  maxTurns?: number;
+  confirmationMode?: boolean;
+}
+
+export function buildClaudeArgs(input: BuildArgsInput): string[] {
+  const cfg = getConfig();
+  const permissionMode = input.confirmationMode ? "default" : "bypassPermissions";
+  const argv: string[] = [
+    "-p",
+    "--output-format",
+    "stream-json",
+    "--verbose",
+    "--permission-mode",
+    permissionMode,
+    "--max-turns",
+    String(input.maxTurns ?? cfg.agentMaxTurns),
+  ];
+
+  if (input.claudeSessionId) {
+    argv.push("--resume", input.claudeSessionId);
+  }
+
+  if (input.agent.system) {
+    argv.push("--system-prompt", input.agent.system);
+  }
+
+  if (input.agent.model) {
+    argv.push("--model", input.agent.model);
+  }
+
+  const tools = resolveToolset(input.agent.tools);
+  if (tools.allowedTools.length) {
+    argv.push("--allowed-tools", tools.allowedTools.join(","));
+  }
+  if (tools.disallowedTools.length) {
+    argv.push("--disallowed-tools", tools.disallowedTools.join(","));
+  }
+
+  if (input.agent.mcp_servers && Object.keys(input.agent.mcp_servers).length > 0) {
+    argv.push(
+      "--mcp-config",
+      JSON.stringify({ mcpServers: input.agent.mcp_servers satisfies Record<string, McpServerConfig> }),
+    );
+  }
+
+  return argv;
+}
+
+/**
+ * Return the auth env vars for claude as a key-value map. The driver
+ * composes these into the wrapper stdin as `KEY=value` lines.
+ */
+export function buildClaudeAuthEnv(): Record<string, string> {
+  const cfg = getConfig();
+  const env: Record<string, string> = {};
+
+  const token = cfg.anthropicApiKey || cfg.claudeToken;
+  if (token) {
+    if (token.startsWith("sk-ant-oat")) {
+      env.CLAUDE_CODE_OAUTH_TOKEN = token;
+    } else {
+      env.ANTHROPIC_API_KEY = token;
+    }
+  }
+
+  return env;
+}

package/src/backends/claude/index.ts

@@ -0,0 +1,193 @@
+/**
+ * Claude backend: drives `claude -p` on sprites.dev containers.
+ *
+ * Implements the Backend interface over the existing claude-specific
+ * args/translator/wrapper modules. `buildTurn` owns the stream-json
+ * tool_result re-entry path — if `toolResults` is non-empty, it builds a
+ * `{type: "user", message: {role, content: [tool_result, ...]}}` frame and
+ * flips the argv to include `--input-format stream-json`.
+ */
+import { ApiError } from "../../errors";
+import { getConfig } from "../../config";
+import type { CustomTool } from "../../types";
+import type { ContainerProvider } from "../../providers/types";
+import type { Backend, BuildTurnInput, BuildTurnResult } from "../types";
+import type { TranslatorOptions } from "../shared/translator-types";
+import { buildClaudeArgs, buildClaudeAuthEnv } from "./args";
+import { createClaudeTranslator } from "./translator";
+import { CLAUDE_WRAPPER_PATH, installClaudeWrapper } from "./wrapper-script";
+import {
+  generateBridgeScript,
+  buildBridgeMcpConfig,
+  toolsToJson,
+  TOOL_BRIDGE_DIR,
+  TOOL_BRIDGE_SCRIPT_PATH,
+  TOOL_BRIDGE_TOOLS_PATH,
+} from "./tool-bridge";
+import {
+  generatePermissionHookScript,
+  buildPermissionHooksConfig,
+  PERMISSION_BRIDGE_DIR,
+  PERMISSION_HOOK_SCRIPT_PATH,
+} from "./permission-hook";
+
+function buildTurn(input: BuildTurnInput): BuildTurnResult {
+  const { agent, backendSessionId, promptText, toolResults } = input;
+
+  const argsBase = buildClaudeArgs({
+    agent,
+    claudeSessionId: backendSessionId,
+    confirmationMode: agent.confirmation_mode,
+  });
+  const env = buildClaudeAuthEnv();
+
+  // If the agent has custom tools or threads_enabled (which adds spawn_agent
+  // as a bridge tool), inject the tool bridge MCP server into --mcp-config.
+  // The bridge script + tools.json are installed on the sprite by prepareOnSprite.
+  // This overrides any existing --mcp-config in argsBase — we find it and merge.
+  const customTools = agent.tools.filter((t): t is CustomTool => t.type === "custom");
+  const hasBridgeTools = customTools.length > 0 || agent.threads_enabled;
+  if (hasBridgeTools) {
+    const mcpIdx = argsBase.indexOf("--mcp-config");
+    let existingServers: Record<string, unknown> = {};
+    if (mcpIdx >= 0 && mcpIdx + 1 < argsBase.length) {
+      try {
+        const existing = JSON.parse(argsBase[mcpIdx + 1]) as { mcpServers?: Record<string, unknown> };
+        existingServers = existing.mcpServers ?? {};
+      } catch {}
+      // Remove the old --mcp-config pair
+      argsBase.splice(mcpIdx, 2);
+    }
+    const merged = buildBridgeMcpConfig(existingServers);
+    argsBase.push("--mcp-config", JSON.stringify({ mcpServers: merged }));
+  }
+
+  if (toolResults.length > 0) {
+    // Stream-json re-entry: claude accepts a user frame on stdin that mixes
+    // text and tool_result content blocks. Spike S5 verified this works with
+    // --resume + --input-format stream-json.
+    const args = [...argsBase, "--input-format", "stream-json"];
+    const content: Array<Record<string, unknown>> = [];
+    if (promptText) {
+      content.push({ type: "text", text: promptText });
+    }
+    for (const r of toolResults) {
+      content.push({
+        type: "tool_result",
+        tool_use_id: r.custom_tool_use_id,
+        content: r.content,
+      });
+    }
+    const userFrame = JSON.stringify({
+      type: "user",
+      message: { role: "user", content },
+    });
+    return { argv: args, env, stdin: userFrame };
+  }
+
+  return { argv: argsBase, env, stdin: promptText };
+}
+
+function validateRuntime(): string | null {
+  const cfg = getConfig();
+  if (!cfg.anthropicApiKey && !cfg.claudeToken) {
+    return "claude backend requires ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN to be set";
+  }
+  return null;
+}
+
+/**
+ * Install the bridge script and tools.json on the sprite if the agent has
+ * custom tools. Called from the lifecycle after the base prepareOnSprite.
+ */
+async function installToolBridge(
+  spriteName: string,
+  customTools: CustomTool[],
+  provider: ContainerProvider,
+): Promise<void> {
+  if (customTools.length === 0) return;
+
+  await provider.exec(spriteName, ["mkdir", "-p", TOOL_BRIDGE_DIR]);
+  await provider.exec(
+    spriteName,
+    ["bash", "-c", `cat > ${TOOL_BRIDGE_SCRIPT_PATH}`],
+    { stdin: generateBridgeScript() },
+  );
+  await provider.exec(
+    spriteName,
+    ["bash", "-c", `cat > ${TOOL_BRIDGE_TOOLS_PATH}`],
+    { stdin: toolsToJson(customTools) },
+  );
+  await provider.exec(spriteName, ["chmod", "+x", TOOL_BRIDGE_SCRIPT_PATH]);
+}
+
+/**
+ * Install the permission hook script and configure Claude Code's settings
+ * to use it. Called from the lifecycle after prepareOnSprite when the agent
+ * has confirmation_mode enabled.
+ */
+async function installPermissionHook(
+  spriteName: string,
+  provider: ContainerProvider,
+): Promise<void> {
+  // Create the bridge directory
+  await provider.exec(spriteName, ["mkdir", "-p", PERMISSION_BRIDGE_DIR]);
+
+  // Write the hook script
+  await provider.exec(
+    spriteName,
+    ["bash", "-c", `cat > ${PERMISSION_HOOK_SCRIPT_PATH}`],
+    { stdin: generatePermissionHookScript() },
+  );
+  await provider.exec(spriteName, ["chmod", "+x", PERMISSION_HOOK_SCRIPT_PATH]);
+
+  // Write the hooks config to $HOME/.claude/settings.json.
+  // Claude Code reads hooks from the user's settings file at startup.
+  // We need to merge with any existing settings (e.g. from prior setup).
+  const hooksConfig = buildPermissionHooksConfig();
+  const settingsPath = "/home/sprite/.claude/settings.json";
+
+  // Read existing settings if any, merge hooks config
+  let existingSettings: Record<string, unknown> = {};
+  try {
+    const result = await provider.exec(
+      spriteName,
+      ["cat", settingsPath],
+    );
+    if (result.stdout.trim()) {
+      existingSettings = JSON.parse(result.stdout) as Record<string, unknown>;
+    }
+  } catch {
+    // No existing settings — that's fine
+  }
+
+  const merged = { ...existingSettings, ...hooksConfig };
+  await provider.exec(
+    spriteName,
+    ["bash", "-c", `mkdir -p /home/sprite/.claude && cat > ${settingsPath}`],
+    { stdin: JSON.stringify(merged, null, 2) },
+  );
+}
+
+export const claudeBackend: Backend = {
+  name: "claude",
+  wrapperPath: CLAUDE_WRAPPER_PATH,
+  buildTurn,
+  createTranslator: (opts: TranslatorOptions) => createClaudeTranslator(opts),
+  prepareOnSprite: (name: string, provider: ContainerProvider) => installClaudeWrapper(name, provider),
+  validateRuntime,
+};
+
+// Re-export utilities needed by tests or other modules that historically
+// imported them from lib/claude/*.
+export {
+  buildClaudeArgs,
+  buildClaudeAuthEnv,
+  createClaudeTranslator,
+  installClaudeWrapper,
+  installToolBridge,
+  installPermissionHook,
+  CLAUDE_WRAPPER_PATH,
+};
+// Re-export ApiError so the driver doesn't need to handle this indirection
+export { ApiError };

package/src/backends/claude/permission-hook.ts

@@ -0,0 +1,152 @@
+/**
+ * Permission hook bridge: generates a Node.js hook script that bridges
+ * Claude Code's PermissionRequest hook to the Managed Agents API's
+ * `user.tool_confirmation` flow.
+ *
+ * Architecture:
+ *   - A Node.js script installed at /tmp/permission-bridge/hook.mjs
+ *   - Claude Code fires PermissionRequest hooks when running in
+ *     `--permission-mode default` and a tool needs approval
+ *   - The hook receives the permission request JSON on stdin
+ *   - It writes /tmp/permission-bridge/request.json with tool details
+ *   - Creates /tmp/permission-bridge/pending sentinel
+ *   - Blocks polling for /tmp/permission-bridge/response.json via fs.watchFile
+ *   - On response: outputs the hook result JSON to stdout and cleans up
+ *
+ * The driver detects the pending sentinel via a background poller during
+ * the stream loop. When found, it emits `agent.tool_confirmation_request`
+ * on the event bus and waits for the client to POST `user.tool_confirmation`.
+ * The events route writes response.json into the container, unblocking the hook.
+ */
+
+export const PERMISSION_BRIDGE_DIR = "/tmp/permission-bridge";
+export const PERMISSION_HOOK_SCRIPT_PATH = `${PERMISSION_BRIDGE_DIR}/hook.mjs`;
+export const PERMISSION_BRIDGE_REQUEST_PATH = `${PERMISSION_BRIDGE_DIR}/request.json`;
+export const PERMISSION_BRIDGE_RESPONSE_PATH = `${PERMISSION_BRIDGE_DIR}/response.json`;
+export const PERMISSION_BRIDGE_PENDING_PATH = `${PERMISSION_BRIDGE_DIR}/pending`;
+
+/**
+ * Generate the PermissionRequest hook script as a string.
+ * This script is written to the container and referenced from
+ * $HOME/.claude/settings.json hooks config.
+ */
+export function generatePermissionHookScript(): string {
+  return `#!/usr/bin/env node
+// Auto-generated PermissionRequest hook for tool confirmation bridge.
+// Reads hook JSON from stdin, writes request.json + pending sentinel,
+// polls for response.json, then outputs the hook response to stdout.
+import { readFileSync, writeFileSync, unlinkSync, existsSync, watchFile, unwatchFile } from 'node:fs';
+
+const REQUEST_PATH = ${JSON.stringify(PERMISSION_BRIDGE_REQUEST_PATH)};
+const RESPONSE_PATH = ${JSON.stringify(PERMISSION_BRIDGE_RESPONSE_PATH)};
+const PENDING_PATH = ${JSON.stringify(PERMISSION_BRIDGE_PENDING_PATH)};
+const TIMEOUT_MS = 120000; // 2 minutes
+
+// Read hook input from stdin
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { input += chunk; });
+process.stdin.on('end', () => {
+  let hookInput;
+  try {
+    hookInput = JSON.parse(input);
+  } catch (e) {
+    // If we can't parse the input, allow by default to avoid blocking
+    console.error('[permission-hook] failed to parse stdin:', e.message);
+    outputResult({ behavior: 'allow' });
+    return;
+  }
+
+  // Extract tool details from the PermissionRequest hook payload.
+  // Claude Code sends: { tool_name, tool_input, tool_use_id, ... }
+  const toolName = hookInput.tool_name || hookInput.toolName || 'unknown';
+  const toolInput = hookInput.tool_input || hookInput.toolInput || {};
+  const toolUseId = hookInput.tool_use_id || hookInput.toolUseId || '';
+
+  // Write request.json with tool details
+  writeFileSync(REQUEST_PATH, JSON.stringify({
+    tool_name: toolName,
+    tool_input: toolInput,
+    tool_use_id: toolUseId,
+  }));
+
+  // Create pending sentinel
+  writeFileSync(PENDING_PATH, '');
+
+  // Poll for response.json
+  const startTime = Date.now();
+  let resolved = false;
+
+  const checkResponse = () => {
+    if (resolved) return;
+    if (!existsSync(RESPONSE_PATH)) return;
+    resolved = true;
+    try { unwatchFile(RESPONSE_PATH, pollFn); } catch {}
+    if (timeoutTimer) clearTimeout(timeoutTimer);
+
+    try {
+      const resp = JSON.parse(readFileSync(RESPONSE_PATH, 'utf8'));
+      try { unlinkSync(RESPONSE_PATH); } catch {}
+      try { unlinkSync(PENDING_PATH); } catch {}
+
+      if (resp.result === 'allow') {
+        outputResult({ behavior: 'allow' });
+      } else {
+        outputResult({ behavior: 'deny', message: resp.deny_message || 'User denied tool use' });
+      }
+    } catch (e) {
+      console.error('[permission-hook] failed to read response:', e.message);
+      // On error, deny to be safe
+      try { unlinkSync(PENDING_PATH); } catch {}
+      outputResult({ behavior: 'deny', message: 'Permission hook error: ' + e.message });
+    }
+  };
+
+  const pollFn = () => checkResponse();
+
+  // Check immediately in case response was pre-written
+  checkResponse();
+  if (resolved) return;
+
+  // Use fs.watchFile for reliable polling
+  watchFile(RESPONSE_PATH, { interval: 200 }, pollFn);
+
+  // Timeout: deny after TIMEOUT_MS
+  const timeoutTimer = setTimeout(() => {
+    if (resolved) return;
+    resolved = true;
+    try { unwatchFile(RESPONSE_PATH, pollFn); } catch {}
+    try { unlinkSync(PENDING_PATH); } catch {}
+    outputResult({ behavior: 'deny', message: 'Permission request timed out after ' + (TIMEOUT_MS / 1000) + 's' });
+  }, TIMEOUT_MS);
+});
+
+function outputResult(decision) {
+  const output = JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PermissionRequest',
+      decision: decision,
+    },
+  });
+  process.stdout.write(output);
+  process.exit(0);
+}
+`;
+}
+
+/**
+ * Build the settings.json hooks configuration for the permission hook.
+ * Returns the JSON object to merge into $HOME/.claude/settings.json.
+ */
+export function buildPermissionHooksConfig(): Record<string, unknown> {
+  return {
+    hooks: {
+      PermissionRequest: [
+        {
+          type: "command",
+          command: `node ${PERMISSION_HOOK_SCRIPT_PATH}`,
+        },
+      ],
+    },
+  };
+}