@aion0/forge 0.4.15 → 0.5.0

package/docs/LOCAL-DEPLOY.md

@@ -8,13 +8,13 @@
 
 ### 方案对比
 
-| 方案 | 原理 | 优点 | 缺点 |
-|------|------|------|------|
-| **同一 WiFi 局域网** | Mac 开 Web 服务，手机直接访问 `192.168.x.x:3000` | 零配置、零成本 | 只能在家用 |
-| **Tailscale** | 虚拟局域网，任何网络下设备互通 | 免费、安全、无需公网 IP | 需要装客户端 |
-| **Cloudflare Tunnel** | 免费内网穿透，给你一个公网域名 | 免费、HTTPS、不开端口 | 依赖 Cloudflare |
-| **ngrok** | 临时隧道 | 一行命令搞定 | 免费版地址每次变 |
-| **frp** | 自建内网穿透 | 完全自控 | 需要一台有公网 IP 的服务器 |
+| 方案 | 原理                                     | 优点 | 缺点 |
+|------|----------------------------------------|------|------|
+| **同一 WiFi 局域网** | Mac 开 Web 服务，手机直接访问 `192.168.x.x:8403` | 零配置、零成本 | 只能在家用 |
+| **Tailscale** | 虚拟局域网，任何网络下设备互通                        | 免费、安全、无需公网 IP | 需要装客户端 |
+| **Cloudflare Tunnel** | 免费内网穿透，给你一个公网域名                        | 免费、HTTPS、不开端口 | 依赖 Cloudflare |
+| **ngrok** | 临时隧道                                   | 一行命令搞定 | 免费版地址每次变 |
+| **frp** | 自建内网穿透                                 | 完全自控 | 需要一台有公网 IP 的服务器 |
 
 ### 推荐组合：Tailscale（推荐） + 局域网（备选）
 
@@ -23,9 +23,9 @@
 │         你的 Mac                 │
 │                                 │
 │  my-workflow server             │
-│  ├── REST API    :3000          │
-│  ├── WebSocket   :3000/ws       │
-│  └── Dashboard   :3000          │
+│  ├── REST API    :8403          │
+│  ├── WebSocket   :8403/ws       │
+│  └── Dashboard   :8403          │
 │                                 │
 │  Tailscale IP: 100.x.x.x       │
 │  局域网 IP:    192.168.x.x      │
@@ -36,8 +36,8 @@
 ┌──────────┴──────────────────────┐
 │         你的手机                 │
 │                                 │
-│  浏览器 → 100.x.x.x:3000       │  ← 任何网络下都能访问
-│  或 Safari → 192.168.x.x:3000  │  ← 同一 WiFi 下
+│  浏览器 → 100.x.x.x:8403       │  ← 任何网络下都能访问
+│  或 Safari → 192.168.x.x:8403  │  ← 同一 WiFi 下
 │                                 │
 └─────────────────────────────────┘
 ```
@@ -67,7 +67,7 @@ tailscale ip -4
 
 # 5. 启动 my-workflow
 mw server start
-# → Dashboard: http://100.64.x.x:3000
+# → Dashboard: http://100.64.x.x:8403
 
 # 手机浏览器打开这个地址即可
 ```
@@ -133,10 +133,10 @@ launchctl list | grep my-workflow
 
 ```
 本地开发阶段:
-  手机 → Tailscale → Mac:3000
+  手机 → Tailscale → Mac:8403
 
 迁移到云端:
-  手机 → Tailscale → VPS:3000   (只是 IP 变了)
+  手机 → Tailscale → VPS:8403   (只是 IP 变了)
   或
   手机 → https://workflow.yourdomain.com  (Cloudflare Tunnel)
 ```

package/install.sh

@@ -12,7 +12,7 @@ if [ "$1" = "local" ] || [ "$1" = "--local" ]; then
   npm uninstall -g @aion0/forge 2>/dev/null || true
   npm link
   echo "[forge] Building..."
-  pnpm build
+  pnpm build || echo "[forge] Build completed with warnings (non-critical)"
 else
   echo "[forge] Installing from npm..."
   rm -rf "$(npm root -g)/@aion0/forge" 2>/dev/null || true
@@ -20,7 +20,7 @@ else
   # Install from /tmp to avoid pnpm node_modules conflict
   (cd /tmp && npm install -g @aion0/forge)
   echo "[forge] Building..."
-  cd "$(npm root -g)/@aion0/forge" && npx next build && cd -
+  cd "$(npm root -g)/@aion0/forge" && (npx next build || echo "[forge] Build completed with warnings") && cd -
 fi
 
 echo ""

package/lib/agents/claude-adapter.ts

@@ -0,0 +1,104 @@
+/**
+ * Claude Code adapter — handles Claude CLI specifics.
+ */
+
+import { execSync } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import type { AgentAdapter, AgentConfig, AgentSpawnOptions, AgentSpawnResult } from './types';
+
+const CAPABILITIES = {
+  supportsResume: true,
+  supportsStreamJson: true,
+  supportsModel: true,
+  supportsSkipPermissions: true,
+  hasSessionFiles: true,
+  requiresTTY: false,
+};
+
+/** Resolve claude binary path (symlink → real .js → node) */
+function resolveClaudePath(claudePath: string): { cmd: string; prefix: string[] } {
+  try {
+    let resolved = claudePath;
+    try {
+      const which = execSync(`which ${claudePath}`, { encoding: 'utf-8', timeout: 3000, stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+      resolved = realpathSync(which);
+    } catch {
+      resolved = realpathSync(claudePath);
+    }
+    if (resolved.endsWith('.js') || resolved.endsWith('.mjs')) {
+      return { cmd: process.execPath, prefix: [resolved] };
+    }
+    return { cmd: resolved, prefix: [] };
+  } catch {
+    return { cmd: process.execPath, prefix: [claudePath] };
+  }
+}
+
+export function createClaudeAdapter(config: AgentConfig): AgentAdapter {
+  return {
+    id: 'claude',
+    config: { ...config, capabilities: CAPABILITIES },
+
+    buildTaskSpawn(opts: AgentSpawnOptions): AgentSpawnResult {
+      const resolved = resolveClaudePath(config.path);
+      const args = [...resolved.prefix, '-p', '--verbose'];
+
+      if (opts.outputFormat === 'stream-json' || opts.outputFormat === undefined) {
+        args.push('--output-format', 'stream-json');
+      } else if (opts.outputFormat === 'json') {
+        args.push('--output-format', 'json');
+      }
+
+      if (opts.skipPermissions !== false) {
+        const flag = config.skipPermissionsFlag || '--dangerously-skip-permissions';
+        if (flag) args.push(...flag.split(/\s+/));
+      }
+
+      if (opts.model && opts.model !== 'default') {
+        args.push('--model', opts.model);
+      }
+
+      if (opts.conversationId) {
+        args.push('--resume', opts.conversationId);
+      }
+
+      if (opts.extraFlags) {
+        args.push(...opts.extraFlags);
+      }
+
+      args.push(opts.prompt);
+
+      return { cmd: resolved.cmd, args };
+    },
+
+    buildTerminalCommand(opts) {
+      const flag = config.skipPermissionsFlag || '--dangerously-skip-permissions';
+      const skipFlag = opts.skipPermissions && flag ? ` ${flag}` : '';
+      if (opts.sessionId) {
+        return `cd "${opts.projectPath}" && claude --resume ${opts.sessionId}${skipFlag}\n`;
+      }
+      const resumeFlag = opts.resume ? ' -c' : '';
+      return `cd "${opts.projectPath}" && claude${resumeFlag}${skipFlag}\n`;
+    },
+  };
+}
+
+/** Detect if claude is installed and return config */
+export function detectClaude(customPath?: string): AgentConfig | null {
+  const paths = customPath ? [customPath] : ['claude'];
+  for (const p of paths) {
+    try {
+      execSync(`which ${p}`, { encoding: 'utf-8', timeout: 3000, stdio: ['pipe', 'pipe', 'pipe'] });
+      return {
+        id: 'claude',
+        name: 'Claude Code',
+        path: p,
+        enabled: true,
+        type: 'claude-code',
+        capabilities: CAPABILITIES,
+        skipPermissionsFlag: '--dangerously-skip-permissions',
+      };
+    } catch {}
+  }
+  return null;
+}

package/lib/agents/generic-adapter.ts

@@ -0,0 +1,64 @@
+/**
+ * Generic agent adapter — works with any CLI agent that takes a prompt via args or stdin.
+ * Supports: codex, aider, or any custom agent binary.
+ */
+
+import { execSync } from 'node:child_process';
+import type { AgentAdapter, AgentConfig, AgentSpawnOptions, AgentSpawnResult } from './types';
+
+export function createGenericAdapter(config: AgentConfig): AgentAdapter {
+  return {
+    id: config.id,
+    config,
+
+    buildTaskSpawn(opts: AgentSpawnOptions): AgentSpawnResult {
+      const args: string[] = [];
+
+      // Add configured flags (e.g., ['--message'] for aider)
+      if (config.flags) {
+        args.push(...config.flags);
+      }
+
+      // Add skip permissions flag if configured
+      if (opts.skipPermissions !== false && config.skipPermissionsFlag) {
+        args.push(...config.skipPermissionsFlag.split(/\s+/));
+      }
+
+      // Add prompt
+      args.push(opts.prompt);
+
+      if (opts.extraFlags) {
+        args.push(...opts.extraFlags);
+      }
+
+      return { cmd: config.path, args };
+    },
+
+    buildTerminalCommand(opts) {
+      return `cd "${opts.projectPath}" && ${config.path}\n`;
+    },
+  };
+}
+
+/** Detect known agents */
+export function detectAgent(id: string, name: string, binaryName: string, flags?: string[]): AgentConfig | null {
+  try {
+    execSync(`which ${binaryName}`, { encoding: 'utf-8', timeout: 3000, stdio: ['pipe', 'pipe', 'pipe'] });
+    return {
+      id,
+      name,
+      path: binaryName,
+      enabled: true,
+      type: 'generic',
+      flags,
+      capabilities: {
+        supportsResume: false,
+        supportsStreamJson: false,
+        supportsModel: false,
+        supportsSkipPermissions: false,
+        hasSessionFiles: false,
+        requiresTTY: false,
+      },
+    };
+  } catch { return null; }
+}

package/lib/agents/index.ts

@@ -0,0 +1,242 @@
+/**
+ * Agent Registry — manages available agents and provides adapters.
+ * Agents coexist (not mutually exclusive). Each entry point can select any agent.
+ */
+
+import { loadSettings } from '../settings';
+import type { AgentAdapter, AgentConfig, AgentId } from './types';
+import { createClaudeAdapter, detectClaude } from './claude-adapter';
+import { createGenericAdapter, detectAgent } from './generic-adapter';
+
+export type { AgentAdapter, AgentConfig, AgentId } from './types';
+
+// Module-level cache
+const adapterCache = new Map<AgentId, AgentAdapter>();
+
+/** Get all configured agents */
+export function listAgents(): AgentConfig[] {
+  const settings = loadSettings();
+  const agents: AgentConfig[] = [];
+
+  // Claude (always check — primary agent)
+  const claudeConfig = settings.agents?.claude;
+  const claude = detectClaude(claudeConfig?.path || settings.claudePath);
+  if (claude) {
+    agents.push({ ...claude, enabled: claudeConfig?.enabled !== false, detected: true, skipPermissionsFlag: claudeConfig?.skipPermissionsFlag || '--dangerously-skip-permissions', cliType: 'claude-code' } as any);
+  }
+
+  // Codex
+  const codexConfig = settings.agents?.codex;
+  const codex = detectAgent('codex', 'OpenAI Codex', codexConfig?.path || 'codex');
+  if (codex) {
+    codex.capabilities.requiresTTY = true;
+    agents.push({ ...codex, enabled: codexConfig?.enabled !== false, detected: true, skipPermissionsFlag: codexConfig?.skipPermissionsFlag || '--full-auto', cliType: 'codex' } as any);
+  }
+
+  // Aider
+  const aiderConfig = settings.agents?.aider;
+  const aider = detectAgent('aider', 'Aider', aiderConfig?.path || 'aider', ['--message']);
+  if (aider) {
+    agents.push({ ...aider, enabled: aiderConfig?.enabled !== false, detected: true, skipPermissionsFlag: aiderConfig?.skipPermissionsFlag || '--yes', cliType: 'aider' } as any);
+  }
+
+  // Custom agents + profiles from settings
+  if (settings.agents) {
+    for (const [id, cfg] of Object.entries(settings.agents)) {
+      if (['claude', 'codex', 'aider'].includes(id)) continue;
+
+      // API profile — no CLI detection needed
+      if (cfg.type === 'api') {
+        agents.push({
+          id,
+          name: cfg.name || id,
+          path: '',
+          enabled: cfg.enabled !== false,
+          type: 'generic' as const,
+          capabilities: { supportsResume: false, supportsStreamJson: false, supportsModel: false, supportsSkipPermissions: false, hasSessionFiles: false, requiresTTY: false },
+          isProfile: true,
+          backendType: 'api',
+          provider: cfg.provider,
+          model: cfg.model,
+          apiKey: cfg.apiKey,
+        } as any);
+        continue;
+      }
+
+      // CLI profile (has base) — inherit from base agent
+      if (cfg.base) {
+        const baseAgent = agents.find(a => a.id === cfg.base);
+        agents.push({
+          ...(baseAgent || { type: 'generic' as const, capabilities: { supportsResume: false, supportsStreamJson: false, supportsModel: false, supportsSkipPermissions: false, hasSessionFiles: false, requiresTTY: false } }),
+          id,
+          name: cfg.name || id,
+          path: baseAgent?.path || '',
+          enabled: cfg.enabled !== false,
+          base: cfg.base,
+          isProfile: true,
+          backendType: 'cli',
+          model: cfg.model || cfg.models?.task,
+          skipPermissionsFlag: cfg.skipPermissionsFlag || baseAgent?.skipPermissionsFlag,
+          env: cfg.env,
+          cliType: cfg.cliType || (baseAgent as any)?.cliType || 'generic',
+        } as any);
+        continue;
+      }
+
+      // Custom agent (not a profile) — detect binary
+      if (!cfg.path) continue;
+      const flags = cfg.taskFlags ? cfg.taskFlags.split(/\s+/).filter(Boolean) : cfg.flags;
+      const detected = detectAgent(id, cfg.name || id, cfg.path, flags);
+      agents.push({
+        ...(detected || {
+          id, name: cfg.name || id, path: cfg.path, type: 'generic' as const, flags,
+          capabilities: { supportsResume: false, supportsStreamJson: false, supportsModel: false, supportsSkipPermissions: false, hasSessionFiles: false, requiresTTY: !!cfg.requiresTTY },
+        }),
+        flags,
+        enabled: cfg.enabled !== false,
+        detected: !!detected,
+      } as any);
+    }
+  }
+
+  return agents;
+}
+
+/** Get the default agent ID */
+export function getDefaultAgentId(): AgentId {
+  const settings = loadSettings();
+  return settings.defaultAgent || 'claude';
+}
+
+/** Get an agent adapter by ID (falls back to default). For profiles, returns base agent's adapter. */
+export function getAgent(id?: AgentId): AgentAdapter {
+  const agentId = id || getDefaultAgentId();
+
+  // Return cached adapter
+  if (adapterCache.has(agentId)) return adapterCache.get(agentId)!;
+
+  const agents = listAgents();
+  const config = agents.find(a => a.id === agentId && a.enabled);
+
+  // Profile with base → get base agent's adapter
+  if (config?.base) {
+    const baseAdapter = getAgent(config.base);
+    // Wrap adapter with profile's model override
+    const profileAdapter: AgentAdapter = {
+      ...baseAdapter,
+      id: agentId,
+      config: { ...baseAdapter.config, ...config, id: agentId },
+    };
+    adapterCache.set(agentId, profileAdapter);
+    return profileAdapter;
+  }
+
+  if (!config) {
+    // If specifically requested agent not found, only fallback for 'claude' (default)
+    if (agentId === 'claude' || agentId === getDefaultAgentId()) {
+      const fallback = detectClaude() || {
+        id: 'claude', name: 'Claude Code', path: 'claude', enabled: true,
+        type: 'claude-code' as const,
+        capabilities: { supportsResume: true, supportsStreamJson: true, supportsModel: true, supportsSkipPermissions: true, hasSessionFiles: true, requiresTTY: false },
+      };
+      const adapter = createClaudeAdapter(fallback);
+      adapterCache.set(agentId, adapter);
+      return adapter;
+    }
+    // Non-default agent not found — create generic with the ID as path (will fail if not installed)
+    const notFound: AgentConfig = {
+      id: agentId, name: agentId, path: agentId, enabled: true, type: 'generic',
+      capabilities: { supportsResume: false, supportsStreamJson: false, supportsModel: false, supportsSkipPermissions: false, hasSessionFiles: false, requiresTTY: false },
+    };
+    const adapter = createGenericAdapter(notFound);
+    adapterCache.set(agentId, adapter);
+    return adapter;
+  }
+
+  const adapter = config.type === 'claude-code'
+    ? createClaudeAdapter(config)
+    : createGenericAdapter(config);
+
+  adapterCache.set(agentId, adapter);
+  return adapter;
+}
+
+/** Clear adapter cache (call after settings change) */
+export function clearAgentCache(): void {
+  adapterCache.clear();
+}
+
+/** Auto-detect all available agents (called on startup) */
+export function autoDetectAgents(): AgentConfig[] {
+  const detected: AgentConfig[] = [];
+
+  const claude = detectClaude();
+  if (claude) detected.push(claude);
+
+  const codex = detectAgent('codex', 'OpenAI Codex', 'codex');
+  if (codex) detected.push(codex);
+
+  const aider = detectAgent('aider', 'Aider', 'aider', ['--message']);
+  if (aider) detected.push(aider);
+
+  if (detected.length > 0) {
+    console.log(`[agents] Detected: ${detected.map(a => a.name).join(', ')}`);
+  }
+
+  return detected;
+}
+
+/** Resolve terminal launch info for an agent — used by both VibeCoding and Workspace */
+export interface TerminalLaunchInfo {
+  cliCmd: string;              // actual binary: claude, codex, aider
+  cliType: string;             // claude-code, codex, aider, generic
+  supportsSession: boolean;    // has session files to resume
+  resumeFlag: string;          // -c, --resume, etc.
+  env?: Record<string, string>; // profile env vars to export
+  model?: string;              // profile model override (--model flag)
+}
+
+export function resolveTerminalLaunch(agentId?: string): TerminalLaunchInfo {
+  const settings = loadSettings();
+  const agentCfg = settings.agents?.[agentId || 'claude'] || {};
+  // Resolve cliType: own cliType → base agent's cliType → base agent name guessing → agentId name guessing
+  const baseId = agentCfg.base;
+  const baseCfg = baseId ? (settings.agents?.[baseId] || {}) : {};
+  const cliType = agentCfg.cliType || baseCfg.cliType
+    || (baseId === 'codex' ? 'codex' : baseId === 'aider' ? 'aider' : undefined)
+    || (agentId === 'codex' ? 'codex' : agentId === 'aider' ? 'aider' : 'claude-code');
+
+  // Determine CLI command and capabilities from cliType
+  const cliMap: Record<string, { cmd: string; session: boolean; resume: string }> = {
+    'claude-code': { cmd: 'claude', session: true, resume: '-c' },
+    'codex': { cmd: 'codex', session: false, resume: '' },
+    'aider': { cmd: 'aider', session: false, resume: '' },
+    'generic': { cmd: agentCfg.path || agentId || 'claude', session: false, resume: '' },
+  };
+  const cli = cliMap[cliType] || cliMap['claude-code'];
+
+  // Resolve env/model: either from this agent's own profile fields, or from linked profile
+  let env: Record<string, string> | undefined;
+  let model: string | undefined;
+  if (agentCfg.base || agentCfg.env || agentCfg.model) {
+    // This agent IS a profile — read env/model directly
+    if (agentCfg.env) env = { ...agentCfg.env };
+    if (agentCfg.model) model = agentCfg.model;
+  } else if (agentCfg.profile) {
+    // Agent links to a separate profile — read from that
+    const profileCfg = settings.agents?.[agentCfg.profile];
+    if (profileCfg) {
+      if (profileCfg.env) env = { ...profileCfg.env };
+      if (profileCfg.model) model = profileCfg.model;
+    }
+  }
+
+  return {
+    cliCmd: cli.cmd,
+    cliType,
+    supportsSession: cli.session,
+    resumeFlag: agentCfg.resumeFlag || cli.resume,
+    env,
+    model,
+  };
+}

package/lib/agents/types.ts

@@ -0,0 +1,70 @@
+/**
+ * Agent types — shared interfaces for multi-agent support.
+ */
+
+export type AgentId = string; // 'claude' | 'codex' | 'aider' | custom
+
+export interface AgentCapabilities {
+  supportsResume: boolean;          // -c / --resume (continue session)
+  supportsStreamJson: boolean;      // structured output parsing
+  supportsModel: boolean;           // --model flag
+  supportsSkipPermissions: boolean; // --dangerously-skip-permissions or equivalent
+  hasSessionFiles: boolean;         // on-disk session files (JSONL etc.)
+  requiresTTY: boolean;             // needs pseudo-terminal (e.g., codex)
+}
+
+export interface AgentConfig {
+  id: AgentId;
+  name: string;             // display name: "Claude Code", "OpenAI Codex", "Aider"
+  path: string;             // binary path
+  enabled: boolean;
+  type: 'claude-code' | 'generic'; // adapter type
+  flags?: string[];         // extra CLI flags
+  capabilities: AgentCapabilities;
+  version?: string;
+  skipPermissionsFlag?: string; // e.g., "--dangerously-skip-permissions", "--full-auto"
+  // Profile fields
+  base?: string;             // base agent ID — makes this a profile
+  isProfile?: boolean;       // true if this is a profile (not a base agent)
+  backendType?: 'cli' | 'api'; // 'api' for API profiles
+  provider?: string;         // API provider (anthropic, google, openai, grok)
+  model?: string;            // model override for profiles
+  apiKey?: string;           // per-profile API key
+  env?: Record<string, string>; // env vars injected on spawn
+  cliType?: 'claude-code' | 'codex' | 'aider' | 'generic'; // CLI tool type
+}
+
+export interface AgentSpawnOptions {
+  projectPath: string;
+  prompt: string;
+  model?: string;
+  conversationId?: string;  // for resume
+  skipPermissions?: boolean;
+  outputFormat?: 'stream-json' | 'json' | 'text';
+  extraFlags?: string[];
+}
+
+export interface AgentSpawnResult {
+  cmd: string;
+  args: string[];
+  env?: Record<string, string>;
+}
+
+export interface AgentAdapter {
+  id: AgentId;
+  config: AgentConfig;
+
+  /** Build spawn command + args for non-interactive task execution */
+  buildTaskSpawn(opts: AgentSpawnOptions): AgentSpawnResult;
+
+  /** Build the terminal command string (e.g., "cd /path && claude -c") */
+  buildTerminalCommand(opts: {
+    projectPath: string;
+    resume?: boolean;
+    sessionId?: string;
+    skipPermissions?: boolean;
+  }): string;
+
+  /** Parse a line of output into normalized events (for stream-json agents) */
+  parseOutputLine?(line: string): any[];
+}

package/lib/artifacts.ts

@@ -0,0 +1,106 @@
+/**
+ * Artifact system — structured data passing between delivery agents.
+ * Each artifact is a named document (requirements, architecture, test-plan, etc.)
+ * stored as a separate JSON file for lazy loading.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { getDataDir } from './dirs';
+
+export type ArtifactType = 'requirements' | 'architecture' | 'test-plan' | 'code-diff' | 'review-report' | 'custom';
+
+export interface Artifact {
+  id: string;
+  deliveryId: string;
+  type: ArtifactType;
+  name: string;          // e.g., "requirements.md"
+  content: string;
+  producedBy: string;    // phase name or 'user'
+  consumedBy: string[];  // phases that consumed this
+  createdAt: string;
+}
+
+function artifactsDir(deliveryId: string): string {
+  const dir = join(getDataDir(), 'deliveries', deliveryId, 'artifacts');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+export function createArtifact(deliveryId: string, opts: {
+  type: ArtifactType;
+  name: string;
+  content: string;
+  producedBy: string;
+}): Artifact {
+  const id = randomUUID().slice(0, 8);
+  const artifact: Artifact = {
+    id,
+    deliveryId,
+    type: opts.type,
+    name: opts.name,
+    content: opts.content,
+    producedBy: opts.producedBy,
+    consumedBy: [],
+    createdAt: new Date().toISOString(),
+  };
+  writeFileSync(join(artifactsDir(deliveryId), `${id}.json`), JSON.stringify(artifact, null, 2));
+  return artifact;
+}
+
+export function getArtifact(deliveryId: string, id: string): Artifact | null {
+  try {
+    return JSON.parse(readFileSync(join(artifactsDir(deliveryId), `${id}.json`), 'utf-8'));
+  } catch { return null; }
+}
+
+export function listArtifacts(deliveryId: string): Artifact[] {
+  const dir = artifactsDir(deliveryId);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter(f => f.endsWith('.json'))
+    .map(f => {
+      try { return JSON.parse(readFileSync(join(dir, f), 'utf-8')) as Artifact; } catch { return null; }
+    })
+    .filter(Boolean) as Artifact[];
+}
+
+export function deleteArtifact(deliveryId: string, id: string): void {
+  try { unlinkSync(join(artifactsDir(deliveryId), `${id}.json`)); } catch {}
+}
+
+/** Extract artifacts from agent output using ===ARTIFACT:name=== markers */
+export function extractArtifacts(output: string, deliveryId: string, producedBy: string): Artifact[] {
+  const artifacts: Artifact[] = [];
+  const regex = /===ARTIFACT:([\w.-]+)===\n([\s\S]*?)(?=\n===ARTIFACT:|$)/g;
+  let match;
+
+  while ((match = regex.exec(output)) !== null) {
+    const name = match[1];
+    const content = match[2].trim();
+    if (!content) continue;
+
+    // Infer type from name
+    let type: ArtifactType = 'custom';
+    if (name.includes('requirement')) type = 'requirements';
+    else if (name.includes('architect') || name.includes('design')) type = 'architecture';
+    else if (name.includes('test')) type = 'test-plan';
+    else if (name.includes('review')) type = 'review-report';
+    else if (name.includes('diff')) type = 'code-diff';
+
+    artifacts.push(createArtifact(deliveryId, { type, name, content, producedBy }));
+  }
+
+  // Fallback: if no markers found, don't create any artifact — let the engine decide
+  return artifacts;
+}
+
+/** Write artifact content to the project directory */
+export function writeArtifactToProject(artifact: Artifact, projectPath: string, subDir = '.forge-delivery'): string {
+  const dir = join(projectPath, subDir);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const filePath = join(dir, artifact.name);
+  writeFileSync(filePath, artifact.content, 'utf-8');
+  return filePath;
+}

package/lib/cloudflared.ts

@@ -169,7 +169,7 @@ function pushLog(line: string) {
   if (state.log.length > MAX_LOG_LINES) state.log.shift();
 }
 
-export async function startTunnel(localPort: number = parseInt(process.env.PORT || '3000')): Promise<{ url?: string; error?: string }> {
+export async function startTunnel(localPort: number = parseInt(process.env.PORT || '8403')): Promise<{ url?: string; error?: string }> {
   console.log(`[tunnel] Starting tunnel on port ${localPort}...`);
   // Prevent concurrent starts: state.process is already spawned, or another call is
   // mid-flight between the guard and spawn (the async download window).