Worker

{
  runtimeId: "claude-code" | "codex-cli" | "opencode",
  runtimeModel: string,
  runtimeParams: Record<string, string>
}

/tmp/second-workspaces/          ← base (configurable via WORKSPACES_DIR)
├── {appId-1}/                   ← app 1's workspace
│   ├── package.json             ← Vite project manifest
│   ├── src/                     ← source files (React + TS)
│   ├── dist/                    ← compiled artifact (created by done_building)
│   └── ...
├── {appId-2}/                   ← app 2's workspace (completely separate)
│   └── ...

const DEFAULT_ALLOWED_TOOLS = [
  "Read",       // Read files
  "Write",      // Create/overwrite files
  "Edit",       // Patch files (search & replace)
  "Bash",       // Run shell commands
  "Glob",       // Find files by pattern
  "Grep",       // Search file contents
  "WebSearch",  // Search the web
  "WebFetch",   // Fetch a URL
  "mcp__second__present_plan",    // Custom: present a build plan for approval
  "mcp__second__list_app_integration_keys", // Custom: list current app integration keys
  "mcp__second__present_agents",  // Custom: present agents.json for governed approval
  "mcp__second__present_integration_setup", // Custom: present setup instructions
  "mcp__second__done_building",   // Custom: run build & trigger live preview
];

import { tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const presentPlan = tool(
  "present_plan",
  "Present a structured build plan to the user for approval before writing any code.",
  {
    overview: z.string().describe("High-level summary of what will be built"),
    features: z.array(z.object({
      name: z.string(),
      description: z.string(),
    })).describe("Main features / capabilities"),
    dataFlow: z.string().describe("How data moves through the app"),
    agents: z.string().nullable().describe("Agent definitions, null if not available"),
    backend: z.string().nullable().describe("Custom backend, null if not available"),
  },
  async (args) => ({
    content: [{ type: "text", text: `Plan presented to user.\n\n${args.overview}` }],
  }),
);

function createSecondToolsMcpServer(config: SessionConfig) {
  return createSdkMcpServer({
    name: "second",
    version: "1.0.0",
    tools: [
      createListAppIntegrationKeysTool(config),
      presentPlan,
      createPresentAgentsTool(config),
      createPresentIntegrationSetupTool(config),
      createDoneBuildingTool(config.workingDirectory),
    ],
  });
}

const allowedTools = [
  ...agent.allowedTools,
  ...agent.tools
    .filter((tool) => tool.type === "custom" && tool.enabled)
    .map((tool) => `mcp__app_tools__${tool.name}`),
  "mcp__app_tools__report_tool_call_failed",
  ...(agent.dataCollections?.length
    ? ["mcp__app_data__update_app_data", "mcp__app_data__read_app_data"]
    : []),
];

{
  "prompt": "Build me a React dashboard",
  "systemPrompt": "You are Second, an AI agent...",
  "runtimeId": "codex-cli",
  "runtimeModel": "gpt-5.4",
  "runtimeParams": {
    "reasoningEffort": "high",
    "sandbox": "workspace-write"
  },
  "workingDirectory": "/tmp/second-workspaces/abc123",
  "allowedTools": ["Read", "Write", "Edit", "Bash"],
  "maxTurns": 50,
  "sessionState": {
    "runtimeId": "codex-cli",
    "sessionId": "abc-123"
  },
  "sourceFiles": { "src/main.tsx": "...", "dist/index.html": "...", "dist/assets/index-abc123.js": "..." }
}

data: {"type":"system","subtype":"init","session_id":"..."}
data: {"type":"stream_event","event":{"type":"content_block_delta","delta":{"type":"text_delta","text":"Hello"}}}
data: {"type":"stream_event","event":{"type":"content_block_start","content_block":{"type":"tool_use","name":"Bash","id":"tc_1"}}}
data: {"type":"assistant","message":{"content":[...]}}
data: {"type":"result","result":"Done.","total_cost_usd":0.05}
data: [DONE]

{
  "exists": true,
  "status": "idle",
  "sessionId": "abc-123",
  "ttlRemainingMs": 840000,
  "workspaceExists": true,
  "workspaceHasFiles": true,
  "restoreNeeded": false,
  "createdAt": "2026-03-24T12:00:00Z",
  "lastActiveAt": "2026-03-24T12:05:00Z"
}

{
  "sessionState": {
    "runtimeId": "claude-code",
    "sessionId": "abc-123",
    "data": {
      "jsonl": "..."
    }
  }
}

{
  "files": {
    "src/main.tsx": "import React from \"react\";\n...",
    "dist/index.html": "<!doctype html>...",
    "dist/assets/index-abc123.js": "import { ... } from \"react\";\n..."
  }
}

{
  "runId": "abc-123",
  "prompt": "Enrich lead Sarah Chen",
  "systemPrompt": "You are a lead enrichment specialist...",
  "agentConfig": { "id": "lead-enricher", "tools": [...], "dataCollections": ["leads"] },
  "allowedTools": ["WebSearch", "mcp__app_data__update_app_data"],
  "runtimeId": "codex-cli",
  "runtimeModel": "gpt-5.4",
  "runtimeParams": { "reasoningEffort": "high", "sandbox": "workspace-write" },
  "workspaceId": "ws-1",
  "appId": "app-1",
  "callbackUrl": "http://web:3000/api/internal/agent-run-complete",
  "sourceFiles": { "src/App.tsx": "..." }
}

import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";

const q = query({
  prompt: "Build a dashboard",
  options: {
    model: "claude-opus-4-8",             // per-message model selection
    effort: "xhigh",                       // "low" | "medium" | "high" | "xhigh" | "max"
    thinking: { type: "adaptive", display: "summarized" },
    systemPrompt: "You are Second...",
    cwd: "/tmp/second-workspaces/abc123",
    allowedTools: ["Read", "Write", "Edit", "Bash", "mcp__second__present_plan"],
    maxTurns: 50,
    includePartialMessages: true,          // enables stream_event messages
    mcpServers: { second: createSecondToolsMcpServer(config) },
    // resume: sessionId,  // for continuing a session
  },
});

for await (const message of q) {
  // message.type: "system" | "stream_event" | "assistant" | "user" | "result"
}

apps/worker/
├── package.json
├── Dockerfile
├── tsconfig.json
└── src/
    ├── index.ts              # Hono HTTP server + route handlers + session file I/O
    ├── session-manager.ts    # TTL-based session lifecycle
    ├── runner.ts             # Provider-neutral Second tool handlers + Claude tool wrappers
    ├── tool-broker.ts        # Scoped MCP broker for command-backed runtimes
    ├── runtimes/             # Claude, Codex CLI, and OpenCode adapters
    ├── builder-skills.ts     # Local Claude skills injected into app workspaces
    ├── agent-run-manager.ts  # Background agent execution with event buffering
    ├── event-stream.ts       # SSE encoding helpers
    ├── dep-warmup.ts         # Background npm install at scaffold time
    └── workspace-template.ts # Vite + TS + Shadcn scaffold + SDK (useAgent, useCollection, etc.)