pikiclaw 0.2.35

package/dist/code-agent.js

@@ -0,0 +1,1080 @@
+/**
+ * code-agent.ts — Shared agent layer: types, session management, artifact helpers,
+ * CLI spawn framework, and unified entry points that delegate to per-agent drivers.
+ *
+ * Agent-specific logic lives in driver-claude.ts, driver-codex.ts, driver-gemini.ts.
+ */
+import crypto from 'node:crypto';
+import { execSync, spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import fs from 'node:fs';
+import path from 'node:path';
+import { getDriver, allDrivers } from './agent-driver.js';
+import { terminateProcessTree } from './process-control.js';
+export { registerDriver, getDriver, allDrivers, allDriverIds, hasDriver, shutdownAllDrivers } from './agent-driver.js';
+// Load all drivers (side-effect: each calls registerDriver)
+import './driver-claude.js';
+import './driver-codex.js';
+import './driver-gemini.js';
+// Re-export driver-specific functions that external code imports directly
+export { doClaudeStream } from './driver-claude.js';
+export { doCodexStream, buildCodexTurnInput, shutdownCodexServer, getCodexUsageLive } from './driver-codex.js';
+export { doGeminiStream } from './driver-gemini.js';
+// ---------------------------------------------------------------------------
+// Shared utilities (exported for drivers)
+// ---------------------------------------------------------------------------
+export const Q = (a) => /[^a-zA-Z0-9_./:=@-]/.test(a) ? `'${a.replace(/'/g, "'\\''")}'` : a;
+const AGENT_DETECT_TTL_MS = 1_000;
+const AGENT_VERSION_TTL_MS = 5 * 60_000;
+const AGENT_VERSION_TIMEOUT_MS = 900;
+const agentDetectCache = new Map();
+export function agentLog(msg) {
+    const ts = new Date().toTimeString().slice(0, 8);
+    process.stdout.write(`[agent ${ts}] ${msg}\n`);
+}
+export function dedupeStrings(values) {
+    const seen = new Set();
+    const deduped = [];
+    for (const value of values) {
+        const item = String(value || '').trim();
+        if (!item || seen.has(item))
+            continue;
+        seen.add(item);
+        deduped.push(item);
+    }
+    return deduped;
+}
+function ensureDir(dirPath) { fs.mkdirSync(dirPath, { recursive: true }); }
+function readJsonFile(filePath, fallback) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    }
+    catch {
+        return fallback;
+    }
+}
+function writeJsonFile(filePath, value) {
+    ensureDir(path.dirname(filePath));
+    const tmpPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    fs.writeFileSync(tmpPath, JSON.stringify(value, null, 2));
+    fs.renameSync(tmpPath, filePath);
+}
+function removeFileIfExists(filePath) { try {
+    fs.rmSync(filePath, { force: true });
+}
+catch { } }
+export function numberOrNull(...values) {
+    for (const value of values) {
+        if (typeof value === 'number' && Number.isFinite(value))
+            return value;
+    }
+    return null;
+}
+export function normalizeActivityLine(text) { return text.replace(/\s+/g, ' ').trim(); }
+export function pushRecentActivity(lines, line, maxLines = 12) {
+    const cleaned = normalizeActivityLine(line);
+    if (!cleaned)
+        return;
+    if (lines[lines.length - 1] === cleaned)
+        return;
+    lines.push(cleaned);
+    if (lines.length > maxLines)
+        lines.splice(0, lines.length - maxLines);
+}
+export function firstNonEmptyLine(text) {
+    for (const line of String(text || '').split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed)
+            return trimmed;
+    }
+    return '';
+}
+export function shortValue(value, max = 90) {
+    const text = typeof value === 'string' ? value.trim() : value == null ? '' : String(value).trim();
+    if (!text)
+        return '';
+    if (text.length <= max)
+        return text;
+    return `${text.slice(0, Math.max(0, max - 3)).trimEnd()}...`;
+}
+export function appendSystemPrompt(base, extra) {
+    const lhs = String(base || '').trim();
+    const rhs = String(extra || '').trim();
+    if (!lhs)
+        return rhs;
+    if (!rhs)
+        return lhs;
+    return `${lhs}\n\n${rhs}`;
+}
+export const IMAGE_EXTS = new Set(['.jpg', '.jpeg', '.png', '.gif', '.webp']);
+export function mimeForExt(ext) {
+    switch (ext) {
+        case '.jpg':
+        case '.jpeg': return 'image/jpeg';
+        case '.png': return 'image/png';
+        case '.gif': return 'image/gif';
+        case '.webp': return 'image/webp';
+        default: return 'application/octet-stream';
+    }
+}
+export function computeContext(s) {
+    const total = (s.inputTokens ?? 0) + (s.cachedInputTokens ?? 0) + (s.cacheCreationInputTokens ?? 0);
+    const used = total > 0 ? total : null;
+    const pct = used != null && s.contextWindow
+        ? Math.min(99.9, Math.round(used / s.contextWindow * 1000) / 10)
+        : null;
+    return { contextUsedTokens: used, contextPercent: pct };
+}
+export function buildStreamPreviewMeta(s) {
+    return {
+        inputTokens: s.inputTokens, outputTokens: s.outputTokens,
+        cachedInputTokens: s.cachedInputTokens, contextPercent: computeContext(s).contextPercent,
+    };
+}
+// Claude tool use helpers (used by driver-claude.ts)
+export function summarizeClaudeToolUse(name, input) {
+    const tool = String(name || '').trim() || 'Tool';
+    const description = shortValue(input?.description, 120);
+    switch (tool) {
+        case 'Read': {
+            const t = shortValue(input?.file_path || input?.path, 140);
+            return t ? `Read ${t}` : 'Read file';
+        }
+        case 'Edit': {
+            const t = shortValue(input?.file_path || input?.path, 140);
+            return t ? `Edit ${t}` : 'Edit file';
+        }
+        case 'Write': {
+            const t = shortValue(input?.file_path || input?.path, 140);
+            return t ? `Write ${t}` : 'Write file';
+        }
+        case 'Glob': {
+            const p = shortValue(input?.pattern || input?.glob, 120);
+            return p ? `List files: ${p}` : 'List files';
+        }
+        case 'Grep': {
+            const p = shortValue(input?.pattern || input?.query, 120);
+            return p ? `Search text: ${p}` : 'Search text';
+        }
+        case 'WebFetch': {
+            const u = shortValue(input?.url, 120);
+            return u ? `Fetch ${u}` : 'Fetch web page';
+        }
+        case 'WebSearch': {
+            const q = shortValue(input?.query, 120);
+            return q ? `Search web: ${q}` : 'Search web';
+        }
+        case 'TodoWrite': return 'Update plan';
+        case 'Task': {
+            const p = shortValue(input?.description || input?.prompt, 120);
+            return p ? `Run task: ${p}` : 'Run task';
+        }
+        case 'Bash': {
+            if (description)
+                return `Run shell: ${description}`;
+            const c = shortValue(input?.command, 120);
+            return c ? `Run shell: ${c}` : 'Run shell command';
+        }
+        default: {
+            if (description)
+                return `${tool}: ${description}`;
+            const d = shortValue(input?.file_path || input?.path || input?.command || input?.query || input?.pattern || input?.url, 120);
+            return d ? `${tool}: ${d}` : tool;
+        }
+    }
+}
+export function summarizeClaudeToolResult(tool, block, toolUseResult) {
+    const summary = tool?.summary || shortValue(tool?.name || 'Tool', 120) || 'Tool';
+    const isError = !!block?.is_error;
+    if (isError) {
+        const detail = firstNonEmptyLine(toolUseResult?.stderr || toolUseResult?.stdout || block?.content || '');
+        return detail ? `${summary} failed: ${shortValue(detail, 120)}` : `${summary} failed`;
+    }
+    const toolName = tool?.name || '';
+    if (toolName === 'Read' || toolName === 'Edit' || toolName === 'Write' || toolName === 'TodoWrite')
+        return `${summary} done`;
+    const detail = firstNonEmptyLine(toolUseResult?.stdout || block?.content || toolUseResult?.stderr || '');
+    if (!detail)
+        return `${summary} done`;
+    return `${summary} -> ${shortValue(detail, 120)}`;
+}
+// Usage helpers (used by drivers)
+export function roundPercent(value) {
+    const n = Number(value);
+    if (!Number.isFinite(n))
+        return null;
+    return Math.max(0, Math.min(100, Math.round(n * 10) / 10));
+}
+export function toIsoFromEpochSeconds(value) {
+    const n = Number(value);
+    if (!Number.isFinite(n) || n <= 0)
+        return null;
+    return new Date(n * 1000).toISOString();
+}
+export function normalizeUsageStatus(value) {
+    const raw = typeof value === 'string' ? value.trim().toLowerCase() : '';
+    if (!raw)
+        return null;
+    const normalized = raw.replace(/[\s-]+/g, '_');
+    if (normalized === 'limit_reached' || normalized === 'warning' || normalized === 'allowed')
+        return normalized;
+    if (normalized.includes('limit') || normalized.includes('exceeded') || normalized.includes('denied'))
+        return 'limit_reached';
+    if (normalized.includes('warning') || normalized.includes('warn'))
+        return 'warning';
+    if (normalized.includes('allowed') || normalized === 'ok' || normalized === 'healthy' || normalized === 'ready')
+        return 'allowed';
+    return normalized;
+}
+export function labelFromWindowMinutes(value, fallback) {
+    const minutes = Number(value);
+    if (!Number.isFinite(minutes) || minutes <= 0)
+        return fallback;
+    const roundedMinutes = Math.round(minutes);
+    if (Math.abs(roundedMinutes - 300) <= 2)
+        return '5h';
+    if (Math.abs(roundedMinutes - 10080) <= 5)
+        return '7d';
+    const roundedDays = Math.round(roundedMinutes / 1440);
+    if (roundedDays >= 1 && Math.abs(roundedMinutes - roundedDays * 1440) <= 5)
+        return `${roundedDays}d`;
+    const roundedHours = Math.round(roundedMinutes / 60);
+    if (roundedHours >= 1 && Math.abs(roundedMinutes - roundedHours * 60) <= 2)
+        return `${roundedHours}h`;
+    return `${roundedMinutes}m`;
+}
+export function usageWindowFromRateLimit(fallback, limit) {
+    if (!limit || typeof limit !== 'object')
+        return null;
+    const usedPercent = roundPercent(limit.used_percent);
+    const remainingPercent = usedPercent == null ? null : Math.max(0, Math.round((100 - usedPercent) * 10) / 10);
+    const resetAt = toIsoFromEpochSeconds(limit.reset_at ?? limit.resets_at);
+    let resetAfterSeconds = null;
+    const directResetAfter = Number(limit.reset_after_seconds);
+    if (Number.isFinite(directResetAfter) && directResetAfter >= 0)
+        resetAfterSeconds = Math.round(directResetAfter);
+    else if (resetAt) {
+        const resetAtMs = Date.parse(resetAt);
+        if (Number.isFinite(resetAtMs))
+            resetAfterSeconds = Math.max(0, Math.round((resetAtMs - Date.now()) / 1000));
+    }
+    return {
+        label: labelFromWindowMinutes(limit.window_minutes, fallback),
+        usedPercent, remainingPercent, resetAt, resetAfterSeconds,
+        status: normalizeUsageStatus(limit.status),
+    };
+}
+export function parseJsonTail(raw) {
+    const start = raw.indexOf('{');
+    if (start < 0)
+        return null;
+    try {
+        return JSON.parse(raw.slice(start));
+    }
+    catch {
+        return null;
+    }
+}
+export function modelFamily(model) {
+    const lower = model?.toLowerCase() || '';
+    if (!lower)
+        return null;
+    if (lower.includes('opus'))
+        return 'opus';
+    if (lower.includes('sonnet'))
+        return 'sonnet';
+    return null;
+}
+export function emptyUsage(agent, error) {
+    return { ok: false, agent, source: null, capturedAt: null, status: null, windows: [], error };
+}
+function isExecutableFile(filePath) {
+    try {
+        const stat = fs.statSync(filePath);
+        if (!stat.isFile())
+            return false;
+        if (process.platform === 'win32')
+            return true;
+        fs.accessSync(filePath, fs.constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function executableCandidates(cmd) {
+    if (process.platform !== 'win32')
+        return [cmd];
+    const ext = path.extname(cmd).toLowerCase();
+    if (ext)
+        return [cmd];
+    const pathExt = (process.env.PATHEXT || '.COM;.EXE;.BAT;.CMD')
+        .split(';')
+        .map(value => value.trim())
+        .filter(Boolean);
+    return [cmd, ...pathExt.map(value => `${cmd}${value.toLowerCase()}`)];
+}
+function resolveAgentBinPath(cmd) {
+    const raw = String(cmd || '').trim();
+    if (!raw)
+        return null;
+    const hasPathSeparator = raw.includes('/') || raw.includes('\\');
+    if (hasPathSeparator) {
+        const absolutePath = path.resolve(raw);
+        for (const candidate of executableCandidates(absolutePath)) {
+            if (isExecutableFile(candidate))
+                return candidate;
+        }
+        return null;
+    }
+    const searchPaths = String(process.env.PATH || '')
+        .split(path.delimiter)
+        .map(entry => entry.trim())
+        .filter(Boolean);
+    for (const dir of searchPaths) {
+        for (const candidate of executableCandidates(path.join(dir, raw))) {
+            if (isExecutableFile(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+function readAgentVersion(binPath, timeoutMs) {
+    try {
+        return execSync(`${Q(binPath)} --version 2>/dev/null`, {
+            encoding: 'utf-8',
+            timeout: Math.max(250, timeoutMs),
+        }).trim().split('\n')[0] || null;
+    }
+    catch {
+        return null;
+    }
+}
+// Agent detection (used by all drivers)
+export function detectAgentBin(cmd, agent, options = {}) {
+    const cacheKey = `${agent}:${cmd}`;
+    const now = Date.now();
+    const includeVersion = !!options.includeVersion;
+    const refresh = !!options.refresh;
+    const versionTimeoutMs = options.versionTimeoutMs ?? AGENT_VERSION_TIMEOUT_MS;
+    let entry = agentDetectCache.get(cacheKey) || null;
+    const shouldRefreshBase = refresh || !entry || now - entry.detectedAt > AGENT_DETECT_TTL_MS;
+    if (shouldRefreshBase) {
+        const binPath = resolveAgentBinPath(cmd);
+        const previousVersion = entry?.info.path === binPath ? entry.info.version ?? null : null;
+        const previousVersionAt = entry?.info.path === binPath ? entry.versionAt : 0;
+        entry = {
+            detectedAt: now,
+            versionAt: previousVersionAt,
+            info: {
+                agent,
+                installed: !!binPath,
+                path: binPath,
+                version: previousVersion,
+            },
+        };
+        agentDetectCache.set(cacheKey, entry);
+    }
+    if (!entry) {
+        return { agent, installed: false, path: null, version: null };
+    }
+    if (includeVersion
+        && entry.info.installed
+        && entry.info.path
+        && (refresh || !entry.versionAt || now - entry.versionAt > AGENT_VERSION_TTL_MS)) {
+        entry.info.version = readAgentVersion(entry.info.path, versionTimeoutMs);
+        entry.versionAt = now;
+        agentDetectCache.set(cacheKey, entry);
+    }
+    return { ...entry.info };
+}
+// Session tail helpers (used by drivers)
+export function readTailLines(filePath, maxBytes = 256 * 1024) {
+    try {
+        const stat = fs.statSync(filePath);
+        const readSize = Math.min(maxBytes, stat.size);
+        const fd = fs.openSync(filePath, 'r');
+        const buf = Buffer.alloc(readSize);
+        fs.readSync(fd, buf, 0, readSize, stat.size - readSize);
+        fs.closeSync(fd);
+        return buf.toString('utf-8').split('\n').filter(l => l.trim());
+    }
+    catch {
+        return [];
+    }
+}
+export function stripInjectedPrompts(text) {
+    const markers = ['\n[Session Workspace]'];
+    for (const m of markers) {
+        const idx = text.indexOf(m);
+        if (idx >= 0)
+            return text.slice(0, idx).trim();
+    }
+    return text;
+}
+const PIKICLAW_DIR = '.pikiclaw';
+const PIKICLAW_SESSIONS_DIR = path.join(PIKICLAW_DIR, 'sessions');
+const PIKICLAW_SESSION_INDEX = path.join(PIKICLAW_SESSIONS_DIR, 'index.json');
+const PIKICLAW_LEGACY_WORKSPACES_DIR = path.join(PIKICLAW_DIR, 'workspaces');
+const SESSION_WORKSPACE_DIR = 'workspace';
+const SESSION_META_FILE = 'session.json';
+// return.json and artifact constants removed — file return is now handled by MCP bridge
+function sessionIndexPath(workdir) { return path.join(workdir, PIKICLAW_SESSION_INDEX); }
+function sessionDirPath(workdir, agent, sessionId) { return path.join(workdir, PIKICLAW_SESSIONS_DIR, agent, sessionId); }
+function legacySessionWorkspacePath(workdir, agent, sessionId) { return path.join(workdir, PIKICLAW_LEGACY_WORKSPACES_DIR, agent, sessionId); }
+function sessionWorkspacePath(workdir, agent, sessionId) { return path.join(sessionDirPath(workdir, agent, sessionId), SESSION_WORKSPACE_DIR); }
+function sessionRootFromWorkspacePath(workspacePath) {
+    const resolved = path.resolve(workspacePath);
+    return path.basename(resolved) === SESSION_WORKSPACE_DIR ? path.dirname(resolved) : resolved;
+}
+function sessionMetaPath(workspacePath) { return path.join(sessionRootFromWorkspacePath(workspacePath), SESSION_META_FILE); }
+function legacySessionMetaPath(workspacePath) { return path.join(workspacePath, PIKICLAW_DIR, SESSION_META_FILE); }
+/** Generate a temporary session ID for new sessions before the agent assigns one. */
+function nextPendingSessionId() { return `pending_${crypto.randomBytes(6).toString('hex')}`; }
+export function isPendingSessionId(sessionId) {
+    return typeof sessionId === 'string' && sessionId.startsWith('pending_');
+}
+function normalizeSessionRecord(raw, workdir) {
+    // Support both new format (sessionId) and legacy format (localSessionId + engineSessionId)
+    const sessionId = typeof raw?.sessionId === 'string' ? raw.sessionId.trim()
+        : typeof raw?.engineSessionId === 'string' && raw.engineSessionId.trim() ? raw.engineSessionId.trim()
+            : typeof raw?.localSessionId === 'string' ? raw.localSessionId.trim()
+                : '';
+    const agent = typeof raw?.agent === 'string' ? raw.agent.trim() : null;
+    if (!sessionId || !agent)
+        return null;
+    const workspacePath = typeof raw?.workspacePath === 'string' && raw.workspacePath.trim()
+        ? path.resolve(raw.workspacePath)
+        : sessionWorkspacePath(workdir, agent, sessionId);
+    return {
+        sessionId, agent, workdir,
+        workspacePath,
+        createdAt: typeof raw?.createdAt === 'string' && raw.createdAt.trim() ? raw.createdAt : new Date().toISOString(),
+        updatedAt: typeof raw?.updatedAt === 'string' && raw.updatedAt.trim() ? raw.updatedAt : new Date().toISOString(),
+        title: typeof raw?.title === 'string' && raw.title.trim() ? raw.title.trim() : null,
+        model: typeof raw?.model === 'string' && raw.model.trim() ? raw.model.trim() : null,
+        stagedFiles: Array.isArray(raw?.stagedFiles) ? dedupeStrings(raw.stagedFiles.filter((v) => typeof v === 'string')) : [],
+    };
+}
+function loadSessionIndex(workdir) {
+    const parsed = readJsonFile(sessionIndexPath(workdir), { version: 1, sessions: [] });
+    const sessions = Array.isArray(parsed?.sessions) ? parsed.sessions : [];
+    return {
+        version: 1,
+        sessions: sessions
+            .map((entry) => normalizeSessionRecord(entry, workdir))
+            .filter((entry) => !!entry),
+    };
+}
+function writeSessionMeta(record) {
+    writeJsonFile(sessionMetaPath(record.workspacePath), {
+        sessionId: record.sessionId, agent: record.agent, workdir: record.workdir,
+        workspacePath: record.workspacePath,
+        createdAt: record.createdAt, updatedAt: record.updatedAt,
+        title: record.title, model: record.model, stagedFiles: record.stagedFiles,
+    });
+}
+function copyPath(sourcePath, targetPath) {
+    const stat = fs.statSync(sourcePath);
+    if (stat.isDirectory()) {
+        fs.cpSync(sourcePath, targetPath, { recursive: true, force: true });
+        return;
+    }
+    ensureDir(path.dirname(targetPath));
+    fs.copyFileSync(sourcePath, targetPath);
+}
+function migrateSessionLayout(workdir, record) {
+    const targetSessionDir = sessionDirPath(workdir, record.agent, record.sessionId);
+    const targetWorkspacePath = sessionWorkspacePath(workdir, record.agent, record.sessionId);
+    const currentWorkspacePath = path.resolve(record.workspacePath || targetWorkspacePath);
+    const legacyWp = path.resolve(legacySessionWorkspacePath(workdir, record.agent, record.sessionId));
+    ensureDir(targetSessionDir);
+    ensureDir(targetWorkspacePath);
+    for (const sourceWorkspacePath of dedupeStrings([currentWorkspacePath, legacyWp])) {
+        if (sourceWorkspacePath === targetWorkspacePath || !fs.existsSync(sourceWorkspacePath))
+            continue;
+        if (!fs.statSync(sourceWorkspacePath).isDirectory())
+            continue;
+        for (const entry of fs.readdirSync(sourceWorkspacePath)) {
+            if (entry === PIKICLAW_DIR)
+                continue;
+            copyPath(path.join(sourceWorkspacePath, entry), path.join(targetWorkspacePath, entry));
+        }
+        if (sourceWorkspacePath === legacyWp)
+            fs.rmSync(sourceWorkspacePath, { recursive: true, force: true });
+    }
+    record.workspacePath = path.resolve(targetWorkspacePath);
+    return record;
+}
+function saveSessionRecord(workdir, record) {
+    record = migrateSessionLayout(workdir, record);
+    ensureDir(sessionDirPath(workdir, record.agent, record.sessionId));
+    ensureDir(record.workspacePath);
+    const index = loadSessionIndex(workdir);
+    record.updatedAt = new Date().toISOString();
+    const pos = index.sessions.findIndex(entry => entry.sessionId === record.sessionId);
+    if (pos >= 0)
+        index.sessions[pos] = record;
+    else
+        index.sessions.unshift(record);
+    index.sessions.sort((a, b) => Date.parse(b.updatedAt) - Date.parse(a.updatedAt));
+    writeJsonFile(sessionIndexPath(workdir), { version: 1, sessions: index.sessions });
+    writeSessionMeta(record);
+    return record;
+}
+/**
+ * Promote a pending session to a real session ID. Renames the workspace directory
+ * and updates the index. Called after the first stream returns the agent's native ID.
+ */
+export function promoteSessionId(workdir, agent, pendingId, nativeId) {
+    if (!isPendingSessionId(pendingId) || !nativeId.trim())
+        return;
+    const resolvedWorkdir = path.resolve(workdir);
+    const index = loadSessionIndex(resolvedWorkdir);
+    const record = index.sessions.find(entry => entry.sessionId === pendingId && entry.agent === agent);
+    if (!record)
+        return;
+    const oldDir = sessionDirPath(resolvedWorkdir, agent, pendingId);
+    const newDir = sessionDirPath(resolvedWorkdir, agent, nativeId);
+    // Move workspace directory if it exists
+    if (fs.existsSync(oldDir) && !fs.existsSync(newDir)) {
+        try {
+            fs.renameSync(oldDir, newDir);
+        }
+        catch { /* cross-device: copy+delete */
+            try {
+                fs.cpSync(oldDir, newDir, { recursive: true });
+                fs.rmSync(oldDir, { recursive: true, force: true });
+            }
+            catch { }
+        }
+    }
+    record.sessionId = nativeId;
+    record.workspacePath = sessionWorkspacePath(resolvedWorkdir, agent, nativeId);
+    saveSessionRecord(resolvedWorkdir, record);
+}
+function summarizePromptTitle(prompt) {
+    const text = String(prompt || '').replace(/\s+/g, ' ').trim();
+    if (!text)
+        return null;
+    return text.length <= 120 ? text : `${text.slice(0, 117).trimEnd()}...`;
+}
+function safeWorkspaceFilename(filename) {
+    const base = path.basename(filename || 'file');
+    const sanitized = base.replace(/[^\w.\- ]+/g, '_').replace(/^\.+/, '').trim();
+    return sanitized || `file-${Date.now()}`;
+}
+function uniqueWorkspaceFilename(workspacePath, desiredName) {
+    const ext = path.extname(desiredName);
+    const stem = ext ? desiredName.slice(0, -ext.length) : desiredName;
+    let candidate = desiredName;
+    let index = 2;
+    while (fs.existsSync(path.join(workspacePath, candidate))) {
+        candidate = `${stem}-${index}${ext}`;
+        index++;
+    }
+    return candidate;
+}
+function importFilesIntoWorkspace(workspacePath, files) {
+    const imported = [];
+    const realWorkspace = fs.realpathSync(workspacePath);
+    for (const filePath of files) {
+        const sourcePath = path.resolve(filePath);
+        if (!fs.existsSync(sourcePath) || !fs.statSync(sourcePath).isFile())
+            continue;
+        let relPath = path.relative(realWorkspace, sourcePath);
+        if (relPath && !relPath.startsWith('..') && !path.isAbsolute(relPath)) {
+            imported.push(relPath.split(path.sep).join(path.posix.sep));
+            continue;
+        }
+        const targetName = uniqueWorkspaceFilename(workspacePath, safeWorkspaceFilename(path.basename(sourcePath)));
+        fs.copyFileSync(sourcePath, path.join(workspacePath, targetName));
+        imported.push(targetName);
+    }
+    return dedupeStrings(imported);
+}
+function ensureSessionWorkspace(opts) {
+    const workdir = path.resolve(opts.workdir);
+    const index = loadSessionIndex(workdir);
+    let record = index.sessions.find(entry => entry.agent === opts.agent && opts.sessionId && entry.sessionId === opts.sessionId)
+        || null;
+    if (!record) {
+        const sessionId = opts.sessionId?.trim() || nextPendingSessionId();
+        record = {
+            sessionId, agent: opts.agent, workdir,
+            workspacePath: sessionWorkspacePath(workdir, opts.agent, sessionId),
+            createdAt: new Date().toISOString(), updatedAt: new Date().toISOString(),
+            title: summarizePromptTitle(opts.title) || null, model: null, stagedFiles: [],
+        };
+    }
+    if (!record.title && opts.title)
+        record.title = summarizePromptTitle(opts.title);
+    record.workspacePath = path.resolve(record.workspacePath);
+    saveSessionRecord(workdir, record);
+    return { sessionId: record.sessionId, workspacePath: record.workspacePath, record };
+}
+// Exported for drivers
+export function listPikiclawSessions(workdir, agent, limit) {
+    const records = loadSessionIndex(path.resolve(workdir)).sessions
+        .filter(entry => entry.agent === agent)
+        .sort((a, b) => Date.parse(b.updatedAt) - Date.parse(a.updatedAt));
+    return typeof limit === 'number' ? records.slice(0, limit) : records;
+}
+export function findPikiclawSession(workdir, agent, sessionId) {
+    return listPikiclawSessions(workdir, agent).find(entry => entry.sessionId === sessionId) || null;
+}
+export function stageSessionFiles(opts) {
+    const session = ensureSessionWorkspace({ agent: opts.agent, workdir: opts.workdir, sessionId: opts.sessionId, title: opts.title });
+    const importedFiles = importFilesIntoWorkspace(session.workspacePath, opts.files);
+    if (importedFiles.length) {
+        session.record.stagedFiles = dedupeStrings([...session.record.stagedFiles, ...importedFiles]);
+        if (!session.record.title)
+            session.record.title = importedFiles[0];
+        saveSessionRecord(opts.workdir, session.record);
+    }
+    return { sessionId: session.sessionId, workspacePath: session.workspacePath, importedFiles };
+}
+// ---------------------------------------------------------------------------
+// Shared CLI spawn framework (used by driver-claude.ts, driver-gemini.ts)
+// ---------------------------------------------------------------------------
+export async function run(cmd, opts, parseLine) {
+    const start = Date.now();
+    const deadline = start + opts.timeout * 1000;
+    let stderr = '';
+    let lineCount = 0;
+    let timedOut = false;
+    const s = {
+        sessionId: opts.sessionId, text: '', thinking: '', msgs: [], thinkParts: [],
+        model: opts.model, thinkingEffort: opts.thinkingEffort, errors: null,
+        inputTokens: null, outputTokens: null, cachedInputTokens: null,
+        cacheCreationInputTokens: null, contextWindow: null,
+        codexCumulative: null,
+        stopReason: null, activity: '',
+        recentActivity: [],
+        claudeToolsById: new Map(),
+        seenClaudeToolIds: new Set(),
+    };
+    const shellCmd = cmd.map(Q).join(' ');
+    agentLog(`[spawn] full command: cd ${Q(opts.workdir)} && ${shellCmd}`);
+    agentLog(`[spawn] timeout: ${opts.timeout}s session: ${opts.sessionId || '(new)'}`);
+    agentLog(`[spawn] prompt (stdin): "${opts.prompt.slice(0, 300)}${opts.prompt.length > 300 ? '…' : ''}"`);
+    const proc = spawn(shellCmd, {
+        cwd: opts.workdir,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        shell: true,
+        detached: process.platform !== 'win32',
+    });
+    agentLog(`[spawn] pid=${proc.pid}`);
+    try {
+        proc.stdin.write(opts._stdinOverride ?? opts.prompt);
+        proc.stdin.end();
+    }
+    catch { }
+    proc.stderr?.on('data', (c) => { const chunk = c.toString(); stderr += chunk; agentLog(`[stderr] ${chunk.trim().slice(0, 200)}`); });
+    const rl = createInterface({ input: proc.stdout, crlfDelay: Infinity });
+    rl.on('line', raw => {
+        if (Date.now() > deadline) {
+            timedOut = true;
+            s.stopReason = 'timeout';
+            agentLog(`[timeout] deadline exceeded, killing process tree`);
+            terminateProcessTree(proc, { signal: 'SIGKILL' });
+            return;
+        }
+        const line = raw.trim();
+        if (!line || line[0] !== '{')
+            return;
+        lineCount++;
+        try {
+            const ev = JSON.parse(line);
+            const evType = ev.type || '?';
+            if (evType === 'system' || evType === 'result' || evType === 'assistant' || evType === 'thread.started' || evType === 'turn.completed' || evType === 'item.completed') {
+                agentLog(`[event] type=${evType} session=${ev.session_id || s.sessionId || '?'} model=${ev.model || s.model || '?'}`);
+            }
+            if (evType === 'stream_event') {
+                const inner = ev.event || {};
+                if (inner.type === 'message_start' || inner.type === 'message_delta')
+                    agentLog(`[event] stream_event/${inner.type} session=${ev.session_id || '?'}`);
+            }
+            parseLine(ev, s);
+            opts.onText(s.text, s.thinking, s.activity, buildStreamPreviewMeta(s), null);
+        }
+        catch { }
+    });
+    const hardTimer = setTimeout(() => {
+        timedOut = true;
+        s.stopReason = 'timeout';
+        agentLog(`[timeout] hard deadline reached (${opts.timeout}s), killing process tree pid=${proc.pid}`);
+        terminateProcessTree(proc, { signal: 'SIGTERM', forceSignal: 'SIGKILL', forceAfterMs: 5000 });
+    }, opts.timeout * 1000 + 10_000);
+    const [procOk, code] = await new Promise(resolve => {
+        proc.on('close', code => { clearTimeout(hardTimer); agentLog(`[exit] code=${code} lines_parsed=${lineCount}`); resolve([code === 0, code]); });
+        proc.on('error', e => { clearTimeout(hardTimer); agentLog(`[error] ${e.message}`); stderr += e.message; resolve([false, -1]); });
+    });
+    if (!s.text.trim() && s.msgs.length)
+        s.text = s.msgs.join('\n\n');
+    if (!s.thinking.trim() && s.thinkParts.length)
+        s.thinking = s.thinkParts.join('\n\n');
+    const ok = procOk && !s.errors && !timedOut;
+    const error = s.errors?.map(e => e.trim()).filter(Boolean).join('; ').trim()
+        || (timedOut ? `Timed out after ${opts.timeout}s before the agent reported completion.` : null)
+        || (!procOk ? (stderr.trim() || `Failed (exit=${code}).`) : null);
+    const incomplete = !ok || s.stopReason === 'max_tokens' || s.stopReason === 'timeout';
+    const elapsed = ((Date.now() - start) / 1000).toFixed(1);
+    agentLog(`[result] ok=${ok && !s.errors} elapsed=${elapsed}s text=${s.text.length}chars thinking=${s.thinking.length}chars session=${s.sessionId || '?'}`);
+    if (s.errors)
+        agentLog(`[result] errors: ${s.errors.join('; ')}`);
+    if (s.stopReason)
+        agentLog(`[result] stop_reason=${s.stopReason}`);
+    if (stderr.trim() && !procOk)
+        agentLog(`[result] stderr: ${stderr.trim().slice(0, 300)}`);
+    return {
+        ok, sessionId: s.sessionId, workspacePath: null,
+        model: s.model, thinkingEffort: s.thinkingEffort,
+        message: s.text.trim() || s.errors?.join('; ') || (procOk ? '(no textual response)' : `Failed (exit=${code}).\n\n${stderr.trim() || '(no output)'}`),
+        thinking: s.thinking.trim() || null,
+        elapsedS: (Date.now() - start) / 1000,
+        inputTokens: s.inputTokens, outputTokens: s.outputTokens, cachedInputTokens: s.cachedInputTokens,
+        cacheCreationInputTokens: s.cacheCreationInputTokens, contextWindow: s.contextWindow,
+        ...computeContext(s), codexCumulative: s.codexCumulative, error, stopReason: s.stopReason,
+        incomplete, activity: s.activity.trim() || null,
+    };
+}
+// ---------------------------------------------------------------------------
+// Unified entry points (delegate to drivers via registry)
+// ---------------------------------------------------------------------------
+function prepareStreamOpts(opts) {
+    const session = ensureSessionWorkspace({ agent: opts.agent, workdir: opts.workdir, sessionId: opts.sessionId, title: opts.prompt });
+    const importedFiles = importFilesIntoWorkspace(session.workspacePath, opts.attachments || []);
+    const attachmentRelPaths = dedupeStrings([...session.record.stagedFiles, ...importedFiles]);
+    // Capture staged files for MCP bridge before clearing
+    const stagedFiles = [...session.record.stagedFiles];
+    session.record.stagedFiles = [];
+    if (!session.record.title)
+        session.record.title = summarizePromptTitle(opts.prompt) || importedFiles[0] || null;
+    saveSessionRecord(opts.workdir, session.record);
+    const attachmentPaths = attachmentRelPaths.map(relPath => path.join(session.workspacePath, relPath));
+    // For pending sessions, pass null sessionId to the CLI so it creates a new session
+    const effectiveSessionId = isPendingSessionId(session.sessionId) ? null : session.sessionId;
+    return {
+        session,
+        attachments: attachmentPaths,
+        stagedFiles,
+        prepared: {
+            ...opts,
+            sessionId: effectiveSessionId,
+            attachments: attachmentPaths.length ? attachmentPaths : undefined,
+        },
+    };
+}
+function finalizeStreamResult(result, workdir, prompt, session) {
+    // If the agent returned a native session ID and our session was pending, promote it
+    const pendingId = session.sessionId;
+    if (result.sessionId && isPendingSessionId(pendingId)) {
+        promoteSessionId(workdir, session.record.agent, pendingId, result.sessionId);
+        session.sessionId = result.sessionId;
+    }
+    session.record.sessionId = result.sessionId || session.record.sessionId;
+    session.record.model = result.model || session.record.model;
+    if (!session.record.title)
+        session.record.title = summarizePromptTitle(prompt);
+    saveSessionRecord(workdir, session.record);
+    return { ...result, sessionId: session.sessionId, workspacePath: session.workspacePath };
+}
+export async function doStream(opts) {
+    let session;
+    let prepared;
+    let stagedFiles;
+    try {
+        const prep = prepareStreamOpts(opts);
+        session = prep.session;
+        prepared = prep.prepared;
+        stagedFiles = prep.stagedFiles;
+    }
+    catch (e) {
+        const message = e?.message || String(e);
+        return {
+            ok: false, message, thinking: null,
+            sessionId: opts.sessionId, workspacePath: null, model: opts.model, thinkingEffort: opts.thinkingEffort,
+            elapsedS: 0, inputTokens: null, outputTokens: null, cachedInputTokens: null,
+            cacheCreationInputTokens: null, contextWindow: null, contextUsedTokens: null, contextPercent: null,
+            codexCumulative: null, error: message, stopReason: null, incomplete: true, activity: null,
+        };
+    }
+    // Start MCP bridge if sendFile callback is provided
+    let bridge = null;
+    if (opts.mcpSendFile) {
+        try {
+            const { startMcpBridge } = await import('./mcp-bridge.js');
+            const sessionDir = path.dirname(session.workspacePath);
+            bridge = await startMcpBridge({
+                sessionDir,
+                workspacePath: session.workspacePath,
+                workdir: opts.workdir,
+                stagedFiles,
+                sendFile: opts.mcpSendFile,
+                agent: opts.agent,
+            });
+            prepared.mcpConfigPath = bridge.configPath;
+            agentLog(`[mcp] bridge started on ${bridge.configPath}`);
+        }
+        catch (e) {
+            agentLog(`[mcp] bridge start failed: ${e.message} — proceeding without MCP`);
+        }
+    }
+    try {
+        const driver = getDriver(prepared.agent);
+        const result = await driver.doStream(prepared);
+        return finalizeStreamResult(result, opts.workdir, opts.prompt, session);
+    }
+    finally {
+        if (bridge) {
+            await bridge.stop().catch(() => { });
+            agentLog('[mcp] bridge stopped');
+        }
+    }
+}
+export function getSessions(opts) {
+    const workdir = path.resolve(opts.workdir);
+    agentLog(`[sessions] request agent=${opts.agent} workdir=${workdir} limit=${opts.limit ?? 'all'}`);
+    return getDriver(opts.agent).getSessions(workdir, opts.limit).then(result => {
+        agentLog(`[sessions] result agent=${opts.agent} ok=${result.ok} count=${result.sessions.length} error=${result.error || '(none)'}`);
+        return result;
+    });
+}
+export function getSessionTail(opts) {
+    return getDriver(opts.agent).getSessionTail(opts);
+}
+export function listAgents(options = {}) {
+    return { agents: allDrivers().map(d => detectAgentBin(d.cmd, d.id, options)) };
+}
+function parseSkillMeta(content) {
+    let label = null;
+    let description = null;
+    const fm = content.match(/^---\s*\n([\s\S]*?)\n---/);
+    if (fm) {
+        const lm = fm[1].match(/^label:\s*(.+)/m);
+        if (lm)
+            label = lm[1].trim();
+        const dm = fm[1].match(/^description:\s*(.+)/m);
+        if (dm)
+            description = dm[1].trim();
+    }
+    if (!label) {
+        const hm = content.match(/^#\s+(.+)$/m);
+        if (hm)
+            label = hm[1].trim();
+    }
+    return { label, description };
+}
+function hasFile(filePath) {
+    try {
+        return fs.statSync(filePath).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function hasDir(dirPath) {
+    try {
+        return fs.statSync(dirPath).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function readSortedDir(dirPath) {
+    try {
+        return fs.readdirSync(dirPath).sort((a, b) => a.localeCompare(b, 'en', { sensitivity: 'base' }));
+    }
+    catch {
+        return [];
+    }
+}
+function listRelativeFiles(dirPath, prefix = '') {
+    const files = [];
+    for (const entry of readSortedDir(dirPath)) {
+        const abs = path.join(dirPath, entry);
+        const rel = prefix ? path.join(prefix, entry) : entry;
+        let stat;
+        try {
+            stat = fs.statSync(abs);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isDirectory())
+            files.push(...listRelativeFiles(abs, rel));
+        else if (stat.isFile())
+            files.push(rel);
+    }
+    return files;
+}
+function listProjectSkillCandidates(rootDir, source) {
+    const entries = new Map();
+    for (const name of readSortedDir(rootDir)) {
+        const dirPath = path.join(rootDir, name);
+        const skillFile = path.join(dirPath, 'SKILL.md');
+        if (!hasDir(dirPath) || !hasFile(skillFile))
+            continue;
+        let mtimeMs = 0;
+        try {
+            mtimeMs = fs.statSync(skillFile).mtimeMs;
+        }
+        catch { }
+        entries.set(name, { source, dirPath, skillFile, mtimeMs });
+    }
+    return entries;
+}
+function realPathOrNull(filePath) {
+    try {
+        return fs.realpathSync(filePath);
+    }
+    catch {
+        return null;
+    }
+}
+function chooseProjectSkillCandidate(candidates) {
+    if (!candidates.length)
+        return null;
+    const priority = {
+        canonical: 0,
+        agents: 1,
+        claude: 2,
+    };
+    return [...candidates].sort((a, b) => {
+        const byPriority = priority[a.source] - priority[b.source];
+        if (byPriority !== 0)
+            return byPriority;
+        if (b.mtimeMs !== a.mtimeMs)
+            return b.mtimeMs - a.mtimeMs;
+        return a.dirPath.localeCompare(b.dirPath);
+    })[0] || null;
+}
+function replaceDir(srcDir, destDir) {
+    try {
+        fs.rmSync(destDir, { recursive: true, force: true });
+    }
+    catch { }
+    fs.mkdirSync(path.dirname(destDir), { recursive: true });
+    fs.cpSync(srcDir, destDir, { recursive: true });
+}
+function ensureDirSymlink(linkPath, targetDir) {
+    const desiredTarget = path.relative(path.dirname(linkPath), targetDir) || '.';
+    try {
+        const stat = fs.lstatSync(linkPath);
+        if (stat.isSymbolicLink()) {
+            const currentTarget = fs.readlinkSync(linkPath);
+            const currentReal = realPathOrNull(path.resolve(path.dirname(linkPath), currentTarget));
+            const desiredReal = realPathOrNull(targetDir);
+            if (currentTarget === desiredTarget || (currentReal && desiredReal && currentReal === desiredReal))
+                return;
+        }
+        fs.rmSync(linkPath, { recursive: true, force: true });
+    }
+    catch { }
+    fs.mkdirSync(path.dirname(linkPath), { recursive: true });
+    fs.symlinkSync(desiredTarget, linkPath, 'dir');
+}
+export function initializeProjectSkills(workdir, opts = {}) {
+    const canonicalRoot = path.join(workdir, '.pikiclaw', 'skills');
+    const agentsRoot = path.join(workdir, '.agents', 'skills');
+    const claudeRoot = path.join(workdir, '.claude', 'skills');
+    const candidatesByName = new Map();
+    const canonicalReal = realPathOrNull(canonicalRoot);
+    const roots = [
+        { rootDir: canonicalRoot, source: 'canonical' },
+        { rootDir: agentsRoot, source: 'agents' },
+        { rootDir: claudeRoot, source: 'claude' },
+    ];
+    for (const { rootDir, source } of roots) {
+        if (source !== 'canonical') {
+            const rootReal = realPathOrNull(rootDir);
+            if (rootReal && canonicalReal && rootReal === canonicalReal)
+                continue;
+        }
+        for (const [name, candidate] of listProjectSkillCandidates(rootDir, source)) {
+            candidatesByName.set(name, [...(candidatesByName.get(name) || []), candidate]);
+        }
+    }
+    fs.mkdirSync(canonicalRoot, { recursive: true });
+    let merged = 0;
+    for (const [name, candidates] of candidatesByName) {
+        const canonicalDir = path.join(canonicalRoot, name);
+        if (hasDir(canonicalDir))
+            continue;
+        const chosen = chooseProjectSkillCandidate(candidates);
+        if (!chosen || chosen.source === 'canonical')
+            continue;
+        replaceDir(chosen.dirPath, canonicalDir);
+        merged += 1;
+    }
+    ensureDirSymlink(agentsRoot, canonicalRoot);
+    ensureDirSymlink(claudeRoot, canonicalRoot);
+    if (merged)
+        opts.log?.(`skills initialized: merged=${merged} linked=2 workdir=${workdir}`);
+}
+export function getProjectSkillPaths(workdir, skillName) {
+    const sharedSkillFile = path.join(workdir, '.pikiclaw', 'skills', skillName, 'SKILL.md');
+    const agentsSkillFile = path.join(workdir, '.agents', 'skills', skillName, 'SKILL.md');
+    const claudeSkillFile = path.join(workdir, '.claude', 'skills', skillName, 'SKILL.md');
+    const claudeCommandFile = path.join(workdir, '.claude', 'commands', `${skillName}.md`);
+    return {
+        sharedSkillFile: hasFile(sharedSkillFile) ? sharedSkillFile : null,
+        agentsSkillFile: hasFile(agentsSkillFile) ? agentsSkillFile : null,
+        claudeSkillFile: hasFile(claudeSkillFile) ? claudeSkillFile : null,
+        claudeCommandFile: hasFile(claudeCommandFile) ? claudeCommandFile : null,
+    };
+}
+export function listSkills(workdir) {
+    const skills = [];
+    const seen = new Set();
+    const commandsDir = path.join(workdir, '.claude', 'commands');
+    for (const entry of readSortedDir(commandsDir)) {
+        if (!entry.endsWith('.md'))
+            continue;
+        const name = entry.replace(/\.md$/, '');
+        if (!name || seen.has(name))
+            continue;
+        let meta = { label: null, description: null };
+        try {
+            meta = parseSkillMeta(fs.readFileSync(path.join(commandsDir, entry), 'utf-8'));
+        }
+        catch { }
+        skills.push({ name, label: meta.label, description: meta.description, source: 'commands' });
+        seen.add(name);
+    }
+    const skillRoots = [
+        path.join(workdir, '.pikiclaw', 'skills'),
+    ];
+    for (const skillsDir of skillRoots) {
+        for (const entry of readSortedDir(skillsDir)) {
+            if (!entry || seen.has(entry))
+                continue;
+            const skillDir = path.join(skillsDir, entry);
+            const skillFile = path.join(skillDir, 'SKILL.md');
+            try {
+                if (!fs.statSync(skillDir).isDirectory())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            if (!hasFile(skillFile))
+                continue;
+            let meta = { label: null, description: null };
+            try {
+                meta = parseSkillMeta(fs.readFileSync(skillFile, 'utf-8'));
+            }
+            catch { }
+            skills.push({ name: entry, label: meta.label, description: meta.description, source: 'skills' });
+            seen.add(entry);
+        }
+    }
+    return { skills, workdir };
+}
+export function listModels(agent, opts = {}) {
+    return getDriver(agent).listModels(opts);
+}
+export function getUsage(opts) {
+    return getDriver(opts.agent).getUsage(opts);
+}