@pikiloom/kernel 0.1.5 → 0.2.2

package/README.md

@@ -275,6 +275,40 @@ plugins are the composable per-capability layer on top.)
 
 ---
 
+## Workspace: unified directory + session / skill / mcp management
+
+One explicitly-configurable **top-level directory** (`createLoom({ stateDirName })`, default
+`'pikiloom'` → `.pikiloom`) gives a consuming app the same "everything under one folder" model
+pikiloom uses, resolved in two scopes — global (`~/.pikiloom`) and per-workspace
+(`<workdir>/.pikiloom`). It's exposed off the `Loom`:
+
+```ts
+const loom = createLoom({ drivers: [new ClaudeDriver(), new CodexDriver()], stateDirName: 'pikiloom' });
+
+// Unified, searchable session list — the kernel's MANAGED sessions (scoped per workspace by the
+// cwd they ran in) MERGED with each agent's OWN native sessions (claude/codex read their on-disk
+// transcripts). Global view, per-workspace view, and search — all kernel-owned:
+await loom.sessions.list({ scope: 'workspace', workdir });   // this folder (managed + native)
+await loom.sessions.list({ scope: 'global' });               // every workspace's managed sessions
+await loom.sessions.search({ query: 'deploy', workdir });
+
+// Skills registry: one canonical dir, symlinked into every agent's skills dir.
+loom.skills.ensureLinks('workspace', workdir);   // <wd>/.claude/skills + .agents/skills → <wd>/.pikiloom/skills
+loom.skills.list({ workdir });                   // installed skills (workspace + global)
+await loom.skills.search('pdf');                 // installable skills (npm)
+
+// MCP catalog + discovery (enabling a server stays on the Plugin.tools()/ToolProvider seam):
+loom.mcp.recommended();                           // curated catalog
+await loom.mcp.search('postgres');                // MCP registry → npm
+
+loom.paths.skillsDir('global');                   // ~/.pikiloom/skills, etc.
+```
+
+A driver opts into native discovery by implementing
+`listNativeSessions?({ workdir, limit }): NativeSessionInfo[]` (Claude/Codex/Gemini do; the pure
+readers are also exported as `discover{Claude,Codex,Gemini}NativeSessions`). All of this is
+node-builtins-only and additive — every existing port/default is unchanged.
+
 ## Exports
 
 Main entry `@pikiloom/kernel` re-exports everything. Subpaths: `@pikiloom/kernel/drivers`,
@@ -284,6 +318,7 @@ Main entry `@pikiloom/kernel` re-exports everything. Subpaths: `@pikiloom/kernel
 - Drivers: `EchoDriver`, `ClaudeDriver`, `CodexDriver`, `GeminiDriver`, `HermesDriver`
 - Surfaces: `WebSurface`, `CliSurface`
 - Ports/defaults: `FsSessionStore`, `NullModelResolver`, `NoopToolProvider`, `PassthroughSystemPromptBuilder`, `AutoCancelInteractionHandler`, `DeferToTerminalInteractionHandler`, `NoopCatalog`, `defaultBaseDir`
+- Workspace: `resolveLoomPaths`, `SessionsManager`, `SkillsManager`, `McpRegistry`, `ensureDirSymlink`, `discover{Claude,Codex,Gemini}NativeSessions` + types `LoomPaths`, `LoomScope`, `ManagedSessionInfo`, `NativeSessionInfo`, `SkillInfo`, `McpCatalogEntry`
 - Protocol: `UniversalSnapshot`, `diffSnapshot`, `applySnapshotPatch`, `emptySnapshot`, `PROTOCOL_VERSION`, all wire/`Client*`/`Server*` message types
 - Types: `AgentDriver`, `AgentTurnInput`, `DriverContext`, `DriverEvent`, `DriverResult`, `LoomIO`, `PromptInput`, `Surface`, `Plugin`, `SpawnContribution`, `SessionStore`, `ModelResolver`, `ToolProvider`, `SystemPromptBuilder`, `InteractionHandler`, `Catalog`, …
 

package/dist/accounts.d.ts

@@ -0,0 +1,6 @@
+/** Whether this agent's local accounts are switched by injecting a token. */
+export declare function accountTokenSupported(agent: string): boolean;
+/** The env-var name that overrides this agent's subscription identity, or null. */
+export declare function accountTokenEnvVar(agent: string): string | null;
+/** Env to merge at spawn so the agent runs under the given account token. */
+export declare function accountTokenEnv(agent: string, token: string): Record<string, string>;

package/dist/accounts.js

@@ -0,0 +1,29 @@
+// Multi-account capability (token form): switch between several local subscription accounts
+// of a coding-agent CLI by injecting a long-lived auth token at spawn time. The CLI keeps
+// using its normal single config home (~/.claude etc.) — only the *identity* changes.
+//
+//   claude / claude-tui -> CLAUDE_CODE_OAUTH_TOKEN=<token from `claude setup-token`>
+//
+// This replaces the earlier per-account config-directory approach: on macOS claude stores
+// its credential in one shared OS-keychain item (not per CLAUDE_CONFIG_DIR), so the token is
+// what actually isolates an account. codex has no equivalent token, so it is not supported
+// here yet (single account only).
+//
+// Dependency-free (no imports) so any @pikiloom/kernel consumer inherits account switching.
+const ACCOUNT_TOKEN_ENV = {
+    claude: 'CLAUDE_CODE_OAUTH_TOKEN',
+    'claude-tui': 'CLAUDE_CODE_OAUTH_TOKEN',
+};
+/** Whether this agent's local accounts are switched by injecting a token. */
+export function accountTokenSupported(agent) {
+    return Object.prototype.hasOwnProperty.call(ACCOUNT_TOKEN_ENV, agent);
+}
+/** The env-var name that overrides this agent's subscription identity, or null. */
+export function accountTokenEnvVar(agent) {
+    return ACCOUNT_TOKEN_ENV[agent] ?? null;
+}
+/** Env to merge at spawn so the agent runs under the given account token. */
+export function accountTokenEnv(agent, token) {
+    const key = accountTokenEnvVar(agent);
+    return key && token ? { [key]: token } : {};
+}

package/dist/contracts/driver.d.ts

@@ -82,6 +82,17 @@ export interface TuiSpec {
     cwd: string;
     env?: Record<string, string>;
 }
+export interface NativeSessionInfo {
+    sessionId: string;
+    title: string | null;
+    preview: string | null;
+    cwd: string | null;
+    model: string | null;
+    createdAt: string | null;
+    updatedAt: string | null;
+    running: boolean;
+    messageCount?: number | null;
+}
 export interface AgentDriver {
     readonly id: string;
     readonly capabilities?: {
@@ -92,4 +103,8 @@ export interface AgentDriver {
     };
     run(input: AgentTurnInput, ctx: DriverContext): Promise<DriverResult>;
     tui?(input: TuiInput): TuiSpec;
+    listNativeSessions?(opts: {
+        workdir: string;
+        limit?: number;
+    }): NativeSessionInfo[] | Promise<NativeSessionInfo[]>;
 }

package/dist/contracts/ports.d.ts

@@ -5,9 +5,11 @@ export interface CoreSessionRecord {
     sessionId: string;
     nativeSessionId?: string | null;
     workspacePath: string;
+    workdir?: string | null;
     createdAt: string;
     updatedAt: string;
     title?: string | null;
+    preview?: string | null;
     model?: string | null;
     effort?: string | null;
     runState?: 'running' | 'completed' | 'incomplete';

package/dist/drivers/acp.d.ts

@@ -0,0 +1,24 @@
+import type { AgentDriver, AgentTurnInput, DriverContext, DriverResult, DriverEvent, McpServerSpec } from '../contracts/driver.js';
+export interface AcpDriverConfig {
+    id: string;
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    fsAccess?: boolean;
+    permissionFallback?: 'allow' | 'reject' | 'cancel';
+    protocolVersion?: number;
+    promptTimeoutMs?: number;
+    capabilities?: AgentDriver['capabilities'];
+}
+export declare function toAcpMcpServers(servers?: McpServerSpec[]): any[];
+export declare function buildAcpPromptBlocks(prompt: string, attachments: string[]): any[];
+export declare function applyAcpUpdate(update: any, s: any, tools: Set<string>, emit: (e: DriverEvent) => void): void;
+export declare class AcpDriver implements AgentDriver {
+    readonly id: string;
+    readonly capabilities: NonNullable<AgentDriver['capabilities']>;
+    protected readonly cfg: Required<Omit<AcpDriverConfig, 'capabilities' | 'env'>> & Pick<AcpDriverConfig, 'env' | 'capabilities'>;
+    constructor(config: AcpDriverConfig);
+    run(input: AgentTurnInput, ctx: DriverContext): Promise<DriverResult>;
+    private resolvePermission;
+    private startupError;
+}

package/dist/drivers/acp.js

@@ -0,0 +1,477 @@
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, extname } from 'node:path';
+class AcpRpcError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+// ── ACP JSON-RPC client over a child process' stdio (ndjson framing) ───────────
+class AcpClient {
+    bin;
+    args;
+    env;
+    cwd;
+    proc = null;
+    nextId = 1;
+    pending = new Map();
+    notifyCb;
+    requestCb;
+    stderrTail = [];
+    constructor(bin, args, env, cwd) {
+        this.bin = bin;
+        this.args = args;
+        this.env = env;
+        this.cwd = cwd;
+    }
+    onNotification(cb) { this.notifyCb = cb; }
+    onRequest(cb) { this.requestCb = cb; }
+    stderrText() { return this.stderrTail.join('\n'); }
+    start() {
+        try {
+            this.proc = spawn(this.bin, this.args, {
+                cwd: this.cwd,
+                stdio: ['pipe', 'pipe', 'pipe'],
+                env: this.env ? { ...process.env, ...this.env } : process.env,
+            });
+        }
+        catch {
+            return false;
+        }
+        const rl = createInterface({ input: this.proc.stdout, crlfDelay: Infinity });
+        rl.on('line', (line) => this.onLine(line));
+        this.proc.stderr.on('data', (chunk) => {
+            for (const ln of chunk.toString('utf8').split('\n')) {
+                const t = ln.trim();
+                if (!t)
+                    continue;
+                this.stderrTail.push(t.slice(0, 240));
+                if (this.stderrTail.length > 20)
+                    this.stderrTail.shift();
+            }
+        });
+        this.proc.on('close', () => { for (const cb of this.pending.values())
+            cb({ error: { message: 'acp process exited' } }); this.pending.clear(); });
+        this.proc.on('error', () => { });
+        return true;
+    }
+    onLine(line) {
+        const t = line.trim();
+        if (!t)
+            return;
+        let m;
+        try {
+            m = JSON.parse(t);
+        }
+        catch {
+            return;
+        } // non-JSON stdout noise
+        if (m.method && m.id != null) {
+            void this.handleRequest(m);
+            return;
+        } // agent -> client request
+        if (m.id != null) { // response to one of our requests
+            const cb = this.pending.get(m.id);
+            if (cb) {
+                this.pending.delete(m.id);
+                cb(m);
+            }
+            return;
+        }
+        if (m.method)
+            this.notifyCb?.(m.method, m.params ?? {}); // notification (session/update)
+    }
+    async handleRequest(m) {
+        const id = m.id;
+        if (!this.requestCb) {
+            this.respondError(id, -32601, `Method not implemented: ${m.method}`);
+            return;
+        }
+        try {
+            const result = await this.requestCb(m.method, m.params ?? {});
+            this.respond(id, result ?? null);
+        }
+        catch (e) {
+            const code = e instanceof AcpRpcError ? e.code : -32603;
+            this.respondError(id, code, e?.message || 'handler error');
+        }
+    }
+    request(method, params, timeoutMs = 60_000) {
+        return new Promise((resolve) => {
+            if (!this.proc || this.proc.killed) {
+                resolve({ error: { message: 'not connected' } });
+                return;
+            }
+            const id = this.nextId++;
+            const timer = setTimeout(() => { this.pending.delete(id); resolve({ error: { message: `ACP '${method}' timed out` } }); }, timeoutMs);
+            this.pending.set(id, (m) => { clearTimeout(timer); resolve(m); });
+            this.write({ jsonrpc: '2.0', id, method, params });
+        });
+    }
+    notify(method, params) { this.write({ jsonrpc: '2.0', method, params }); }
+    respond(id, result) { this.write({ jsonrpc: '2.0', id, result }); }
+    respondError(id, code, message) { this.write({ jsonrpc: '2.0', id, error: { code, message } }); }
+    write(msg) {
+        if (!this.proc || this.proc.killed)
+            return;
+        try {
+            this.proc.stdin.write(JSON.stringify(msg) + '\n');
+        }
+        catch { /* stream closed */ }
+    }
+    kill() { try {
+        this.proc?.kill('SIGTERM');
+    }
+    catch { /* ignore */ } this.proc = null; }
+}
+// ── pikiloom McpServerSpec[] -> ACP mcpServers[] ───────────────────────────────
+export function toAcpMcpServers(servers) {
+    if (!servers || !servers.length)
+        return [];
+    const out = [];
+    for (const s of servers) {
+        if (!s || !s.name)
+            continue;
+        if (s.type === 'http' && s.url) {
+            out.push({ type: 'http', name: s.name, url: s.url, headers: Object.entries(s.headers || {}).map(([name, value]) => ({ name, value: String(value) })) });
+            continue;
+        }
+        if (s.command) {
+            out.push({ name: s.name, command: s.command, args: Array.isArray(s.args) ? s.args.map(String) : [], env: Object.entries(s.env || {}).map(([name, value]) => ({ name, value: String(value) })) });
+        }
+    }
+    return out;
+}
+const IMAGE_EXTS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp']);
+function mimeForExt(ext) {
+    if (ext === '.jpg' || ext === '.jpeg')
+        return 'image/jpeg';
+    if (ext === '.gif')
+        return 'image/gif';
+    if (ext === '.webp')
+        return 'image/webp';
+    return 'image/png';
+}
+// ACP prompt content blocks: text + inline base64 images; other attachments noted as text.
+export function buildAcpPromptBlocks(prompt, attachments) {
+    const blocks = [];
+    for (const f of attachments) {
+        const ext = extname(f).toLowerCase();
+        if (IMAGE_EXTS.has(ext)) {
+            try {
+                blocks.push({ type: 'image', mimeType: mimeForExt(ext), data: readFileSync(f).toString('base64') });
+                continue;
+            }
+            catch { /* fall through to a text note */ }
+        }
+        blocks.push({ type: 'text', text: `[Attached file: ${f}]` });
+    }
+    blocks.push({ type: 'text', text: prompt });
+    return blocks;
+}
+function acpContentText(content) {
+    if (content == null)
+        return '';
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content))
+        return content.map(acpContentText).filter(Boolean).join('\n');
+    if (typeof content === 'object') {
+        if (typeof content.text === 'string')
+            return content.text;
+        if (content.type === 'content' && content.content)
+            return acpContentText(content.content);
+        if (content.type === 'diff' && typeof content.path === 'string')
+            return `[diff ${content.path}]`;
+    }
+    return '';
+}
+function acpToolStatus(status, dflt) {
+    if (status === 'completed')
+        return 'done';
+    if (status === 'failed')
+        return 'failed';
+    if (status === 'pending' || status === 'in_progress')
+        return 'running';
+    return dflt;
+}
+function safeJson(v) {
+    try {
+        return typeof v === 'string' ? v : JSON.stringify(v);
+    }
+    catch {
+        return null;
+    }
+}
+function truncate(s, n) { return s.length > n ? s.slice(0, n) + '…' : s; }
+// session/update -> normalized DriverEvents. Exported (and aliased as applyHermesUpdate)
+// so it can be unit-tested against the raw ACP wire without spawning a process.
+export function applyAcpUpdate(update, s, tools, emit) {
+    if (!update)
+        return;
+    switch (update.sessionUpdate) {
+        case 'agent_message_chunk': {
+            const t = acpContentText(update.content);
+            if (t) {
+                s.text = (s.text || '') + t;
+                emit({ type: 'text', delta: t });
+            }
+            return;
+        }
+        case 'agent_thought_chunk': {
+            const t = acpContentText(update.content);
+            if (t) {
+                s.reasoning = (s.reasoning || '') + t;
+                emit({ type: 'reasoning', delta: t });
+            }
+            return;
+        }
+        case 'tool_call': {
+            const id = typeof update.toolCallId === 'string' ? update.toolCallId : '';
+            if (!id)
+                return;
+            const name = (typeof update.title === 'string' && update.title.trim()) || (typeof update.kind === 'string' && update.kind) || 'tool';
+            tools.add(id);
+            emit({ type: 'tool', call: { id, name, summary: name, input: update.rawInput != null ? truncate(safeJson(update.rawInput) || '', 2000) : null, status: acpToolStatus(update.status, 'running') } });
+            return;
+        }
+        case 'tool_call_update': {
+            const id = typeof update.toolCallId === 'string' ? update.toolCallId : '';
+            if (!id)
+                return;
+            const name = (typeof update.title === 'string' && update.title.trim()) || 'tool';
+            const status = acpToolStatus(update.status, 'running');
+            const result = update.content != null ? truncate(acpContentText(update.content), 2000) : null;
+            emit({ type: 'tool', call: { id, name, summary: name, result: result || null, status } });
+            return;
+        }
+        case 'plan': {
+            const entries = Array.isArray(update.entries) ? update.entries : [];
+            const steps = entries
+                .map((e) => ({ text: String(e?.content ?? '').trim(), status: e?.status === 'in_progress' ? 'inProgress' : e?.status === 'completed' ? 'completed' : 'pending' }))
+                .filter((st) => st.text);
+            if (steps.length)
+                emit({ type: 'plan', plan: { explanation: null, steps } });
+            return;
+        }
+        case 'usage_update': {
+            if (typeof update.size === 'number')
+                s.contextWindow = update.size;
+            if (typeof update.used === 'number')
+                s.contextUsed = update.used;
+            if (typeof update.used === 'number') {
+                const window = s.contextWindow;
+                const contextPercent = window && update.used > 0 ? Math.min(99.9, Math.round((update.used / window) * 1000) / 10) : null;
+                emit({ type: 'usage', usage: { inputTokens: null, outputTokens: null, cachedInputTokens: null, contextUsedTokens: update.used, contextPercent } });
+            }
+            return;
+        }
+    }
+}
+// session/request_permission params -> a normalized UniversalInteraction (kind 'permission').
+// Each choice's `value` IS the ACP optionId, so the answer maps straight back to an outcome.
+function permissionToInteraction(params, promptId) {
+    const options = Array.isArray(params?.options) ? params.options : [];
+    if (!options.length)
+        return null;
+    const tc = params?.toolCall || {};
+    const what = (typeof tc.title === 'string' && tc.title.trim()) || (typeof tc.kind === 'string' && tc.kind) || 'this action';
+    return {
+        promptId,
+        kind: 'permission',
+        title: 'Permission required',
+        hint: `The agent wants to: ${what}`,
+        questions: [{
+                id: 'choice',
+                header: 'Permission',
+                text: `Allow the agent to ${what}?`,
+                type: 'select',
+                choices: options.map((o) => ({ label: String(o?.name || o?.optionId || 'option'), value: String(o?.optionId || ''), description: String(o?.kind || '') })),
+                allowFreeform: false,
+                allowEmpty: true,
+            }],
+    };
+}
+function pickOptionId(answers, options) {
+    const vals = Object.values(answers || {}).flat().map(String);
+    for (const v of vals) {
+        const byId = options.find((o) => String(o?.optionId) === v);
+        if (byId)
+            return String(byId.optionId);
+        const byName = options.find((o) => String(o?.name) === v);
+        if (byName)
+            return String(byName.optionId);
+    }
+    return null;
+}
+function fallbackOptionId(options, fallback) {
+    if (fallback === 'cancel')
+        return null;
+    const order = fallback === 'allow' ? ['allow_once', 'allow_always', 'allow'] : ['reject_once', 'reject_always', 'reject'];
+    for (const k of order) {
+        const o = options.find((x) => String(x?.kind) === k);
+        if (o)
+            return String(o.optionId);
+    }
+    return fallback === 'allow' && options[0] ? String(options[0].optionId) : null;
+}
+function readAcpTextFile(params) {
+    const p = String(params?.path || '');
+    if (!p || !existsSync(p))
+        throw new AcpRpcError(-32602, `file not found: ${p}`);
+    let content = readFileSync(p, 'utf8');
+    const line = typeof params?.line === 'number' ? params.line : null;
+    const limit = typeof params?.limit === 'number' ? params.limit : null;
+    if (line != null || limit != null) {
+        const lines = content.split('\n');
+        const start = line != null ? Math.max(0, line - 1) : 0;
+        content = lines.slice(start, limit != null ? start + limit : undefined).join('\n');
+    }
+    return { content };
+}
+function writeAcpTextFile(params) {
+    const p = String(params?.path || '');
+    if (!p)
+        throw new AcpRpcError(-32602, 'path required');
+    try {
+        mkdirSync(dirname(p), { recursive: true });
+    }
+    catch { /* parent may exist */ }
+    writeFileSync(p, String(params?.content ?? ''), 'utf8');
+    return null;
+}
+function acpUsage(s, raw) {
+    let input = null, output = null, cached = null;
+    if (raw && typeof raw === 'object') {
+        const n = (v) => (typeof v === 'number' ? v : null);
+        input = n(raw.inputTokens ?? raw.input_tokens);
+        output = n(raw.outputTokens ?? raw.output_tokens);
+        cached = n(raw.cachedReadTokens ?? raw.cached_read_tokens ?? raw.cachedInputTokens);
+    }
+    const window = s.contextWindow, used = s.contextUsed;
+    const contextPercent = window && used ? Math.min(99.9, Math.round((used / window) * 1000) / 10) : null;
+    return { inputTokens: input, outputTokens: output, cachedInputTokens: cached, contextUsedTokens: used, contextPercent, turnOutputTokens: output };
+}
+export class AcpDriver {
+    id;
+    capabilities;
+    cfg;
+    constructor(config) {
+        this.id = config.id;
+        this.cfg = {
+            id: config.id,
+            command: config.command,
+            args: config.args ?? ['acp'],
+            env: config.env,
+            fsAccess: config.fsAccess ?? true,
+            permissionFallback: config.permissionFallback ?? 'allow',
+            protocolVersion: config.protocolVersion ?? 1,
+            promptTimeoutMs: config.promptTimeoutMs ?? 7_200_000,
+            capabilities: config.capabilities,
+        };
+        this.capabilities = config.capabilities ?? { steer: false, interact: true, resume: true, tui: false };
+    }
+    async run(input, ctx) {
+        const env = { ...(this.cfg.env || {}), ...(input.env || {}) };
+        const client = new AcpClient(this.cfg.command, this.cfg.args, env, input.workdir);
+        const state = { text: '', reasoning: '', contextWindow: null, contextUsed: null };
+        const tools = new Set();
+        let sessionId = input.sessionId ?? null;
+        let permSeq = 0;
+        if (!client.start())
+            return { ok: false, text: '', error: `failed to start ${this.cfg.command}`, stopReason: 'error' };
+        const onAbort = () => { if (sessionId)
+            client.notify('session/cancel', { sessionId }); client.kill(); };
+        if (ctx.signal.aborted)
+            onAbort();
+        else
+            ctx.signal.addEventListener('abort', onAbort, { once: true });
+        client.onNotification((method, params) => {
+            if (method === 'session/update')
+                applyAcpUpdate(params?.update ?? params, state, tools, ctx.emit);
+        });
+        client.onRequest(async (method, params) => {
+            switch (method) {
+                case 'session/request_permission': return this.resolvePermission(params, ctx, `${this.id}-perm-${++permSeq}`);
+                case 'fs/read_text_file':
+                    if (!this.cfg.fsAccess)
+                        throw new AcpRpcError(-32601, 'fs/read_text_file not supported');
+                    return readAcpTextFile(params);
+                case 'fs/write_text_file':
+                    if (!this.cfg.fsAccess)
+                        throw new AcpRpcError(-32601, 'fs/write_text_file not supported');
+                    return writeAcpTextFile(params);
+                default:
+                    throw new AcpRpcError(-32601, `Method not implemented: ${method}`);
+            }
+        });
+        try {
+            const init = await client.request('initialize', {
+                protocolVersion: this.cfg.protocolVersion,
+                clientCapabilities: { fs: { readTextFile: !!this.cfg.fsAccess, writeTextFile: !!this.cfg.fsAccess }, terminal: false },
+            });
+            if (init.error)
+                return { ok: false, text: '', error: this.startupError(client, init.error.message || 'initialize failed'), stopReason: 'error' };
+            const mcpServers = toAcpMcpServers(input.extraMcpServers);
+            if (!sessionId) {
+                const ns = await client.request('session/new', { cwd: input.workdir, mcpServers });
+                if (ns.error)
+                    return { ok: false, text: '', error: ns.error.message || 'session/new failed', stopReason: 'error' };
+                sessionId = ns.result?.sessionId ?? ns.result?.session_id ?? null;
+                if (sessionId)
+                    ctx.emit({ type: 'session', sessionId });
+            }
+            else {
+                await client.request('session/load', { sessionId, cwd: input.workdir, mcpServers }, 30_000).catch(() => ({}));
+                ctx.emit({ type: 'session', sessionId });
+            }
+            if (!sessionId)
+                return { ok: false, text: '', error: `${this.id} returned no session id`, stopReason: 'error' };
+            if (input.model)
+                await client.request('session/set_model', { sessionId, modelId: input.model }, 15_000).catch(() => ({}));
+            if (input.effort)
+                await client.request('session/set_mode', { sessionId, modeId: input.effort }, 15_000).catch(() => ({}));
+            const promptResp = await client.request('session/prompt', {
+                sessionId,
+                prompt: buildAcpPromptBlocks(input.prompt, input.attachments || []),
+            }, this.cfg.promptTimeoutMs);
+            const usage = acpUsage(state, promptResp.result?.usage);
+            if (ctx.signal.aborted)
+                return { ok: false, text: state.text, error: 'Interrupted by user.', stopReason: 'interrupted', sessionId, usage };
+            if (promptResp.error)
+                return { ok: false, text: state.text, error: promptResp.error.message || 'session/prompt failed', stopReason: 'error', sessionId, usage };
+            const stopReason = promptResp.result?.stopReason ?? 'end_turn';
+            return { ok: true, text: state.text, reasoning: state.reasoning || undefined, error: null, stopReason, sessionId, usage };
+        }
+        finally {
+            ctx.signal.removeEventListener('abort', onAbort);
+            client.kill();
+        }
+    }
+    async resolvePermission(params, ctx, promptId) {
+        const options = Array.isArray(params?.options) ? params.options : [];
+        if (!options.length)
+            return { outcome: { outcome: 'cancelled' } };
+        const interaction = permissionToInteraction(params, promptId);
+        let answers = {};
+        if (interaction) {
+            try {
+                answers = (await ctx.askUser(interaction)) || {};
+            }
+            catch {
+                answers = {};
+            }
+        }
+        if (ctx.signal.aborted)
+            return { outcome: { outcome: 'cancelled' } };
+        const picked = pickOptionId(answers, options) ?? fallbackOptionId(options, this.cfg.permissionFallback);
+        return picked ? { outcome: { outcome: 'selected', optionId: picked } } : { outcome: { outcome: 'cancelled' } };
+    }
+    startupError(client, base) {
+        const tail = client.stderrText().trim();
+        return tail ? `${base} — ${truncate(tail, 300)}` : base;
+    }
+}

package/dist/drivers/claude.d.ts

@@ -1,4 +1,4 @@
-import type { AgentDriver, AgentTurnInput, DriverContext, DriverResult, DriverEvent, TuiInput, TuiSpec } from '../contracts/driver.js';
+import type { AgentDriver, AgentTurnInput, DriverContext, DriverResult, DriverEvent, TuiInput, TuiSpec, NativeSessionInfo } from '../contracts/driver.js';
 import type { UniversalUsage, UniversalPlan } from '../protocol/index.js';
 export declare class ClaudeDriver implements AgentDriver {
     private readonly bin;
@@ -11,6 +11,10 @@ export declare class ClaudeDriver implements AgentDriver {
     };
     constructor(bin?: string);
     tui(input: TuiInput): TuiSpec;
+    listNativeSessions(opts: {
+        workdir: string;
+        limit?: number;
+    }): NativeSessionInfo[];
     run(input: AgentTurnInput, ctx: DriverContext): Promise<DriverResult>;
     private usage;
 }

package/dist/drivers/claude.js

@@ -1,4 +1,5 @@
 import { spawn } from 'node:child_process';
+import { discoverClaudeNativeSessions } from '../workspace/native.js';
 // Real driver: shells the local `claude` CLI in stream-json mode and normalizes its
 // events into kernel DriverEvents. Faithful to pikiloom's claude.ts event shapes
 // (system / stream_event{message_start,content_block_delta,message_delta} / assistant / result),
@@ -22,6 +23,9 @@ export class ClaudeDriver {
             args.push(...input.extraArgs);
         return { command: this.bin, args, cwd: input.workdir, env: input.env };
     }
+    listNativeSessions(opts) {
+        return discoverClaudeNativeSessions(opts.workdir, { limit: opts.limit });
+    }
     run(input, ctx) {
         const steerable = !!input.steerable;
         const args = ['-p', '--verbose', '--output-format', 'stream-json', '--include-partial-messages'];