pikiloom 0.4.40 → 0.4.42

package/packages/kernel/dist/drivers/hermes.js

@@ -1,194 +1,11 @@
-import { spawn } from 'node:child_process';
-// Minimal ACP (Agent Client Protocol) ndjson JSON-RPC client — same wire as codex
-// app-server. Used by the Hermes driver to drive any-model agents over ACP.
-class AcpClient {
-    bin;
-    args;
-    env;
-    proc = null;
-    buf = '';
-    nextId = 1;
-    pending = new Map();
-    notify;
-    constructor(bin, args, env) {
-        this.bin = bin;
-        this.args = args;
-        this.env = env;
-    }
-    onNotification(cb) { this.notify = cb; }
-    start() {
-        try {
-            this.proc = spawn(this.bin, this.args, { stdio: ['pipe', 'pipe', 'pipe'], env: this.env ? { ...process.env, ...this.env } : process.env });
-        }
-        catch {
-            return false;
-        }
-        this.proc.stdout.on('data', (chunk) => this.onData(chunk));
-        this.proc.on('close', () => { for (const cb of this.pending.values())
-            cb({ error: { message: 'acp exited' } }); this.pending.clear(); });
-        this.proc.on('error', () => { });
-        return true;
-    }
-    onData(chunk) {
-        this.buf += chunk.toString('utf8');
-        const lines = this.buf.split('\n');
-        this.buf = lines.pop() || '';
-        for (const line of lines) {
-            if (!line.trim())
-                continue;
-            let m;
-            try {
-                m = JSON.parse(line);
-            }
-            catch {
-                continue;
-            }
-            if (m.method && m.id != null) {
-                this.respond(m.id, {});
-            } // agent->client request: ack
-            else if (m.id != null) {
-                const cb = this.pending.get(m.id);
-                if (cb) {
-                    this.pending.delete(m.id);
-                    cb(m);
-                }
-            }
-            else if (m.method)
-                this.notify?.(m.method, m.params ?? {});
-        }
-    }
-    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); });
-            try {
-                this.proc.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n');
-            }
-            catch {
-                clearTimeout(timer);
-                this.pending.delete(id);
-                resolve({ error: { message: 'write failed' } });
-            }
-        });
-    }
-    respond(id, result) { try {
-        this.proc?.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, result }) + '\n');
-    }
-    catch { /* closed */ } }
-    kill() { try {
-        this.proc?.kill('SIGTERM');
-    }
-    catch { /* ignore */ } this.proc = null; }
-}
-export class HermesDriver {
-    bin;
-    id = 'hermes';
-    capabilities = { steer: false, interact: false, resume: true, tui: false };
+import { AcpDriver, applyAcpUpdate } from './acp.js';
+// Hermes = the reference ACP agent, shipped as a thin preset over the generic AcpDriver.
+// Any other ACP CLI (OpenCode, Gemini-ACP, …) is just `new AcpDriver({ id, command, args })`.
+export class HermesDriver extends AcpDriver {
     constructor(bin = 'hermes') {
-        this.bin = bin;
-    }
-    async run(input, ctx) {
-        const client = new AcpClient(this.bin, ['acp'], input.env);
-        const s = { text: '', reasoning: '', sessionId: input.sessionId ?? null, contextWindow: null, contextUsed: null, error: null };
-        const tools = new Set();
-        if (!client.start())
-            return { ok: false, text: '', error: 'failed to start hermes acp', stopReason: 'error' };
-        const onAbort = () => { try {
-            client.request('session/cancel', { sessionId: s.sessionId });
-        }
-        catch { /* ignore */ } client.kill(); };
-        if (ctx.signal.aborted)
-            onAbort();
-        else
-            ctx.signal.addEventListener('abort', onAbort, { once: true });
-        client.onNotification((method, params) => {
-            if (method !== 'session/update')
-                return;
-            applyHermesUpdate(params?.update ?? params, s, tools, ctx.emit);
-        });
-        try {
-            const init = await client.request('initialize', { protocolVersion: 1, clientCapabilities: { fs: { readTextFile: false, writeTextFile: false } } });
-            if (init.error)
-                return { ok: false, text: '', error: init.error.message || 'initialize failed', stopReason: 'error' };
-            if (!s.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' };
-                s.sessionId = ns.result?.sessionId || ns.result?.session_id || null;
-                if (s.sessionId)
-                    ctx.emit({ type: 'session', sessionId: s.sessionId });
-            }
-            else {
-                await client.request('session/load', { sessionId: s.sessionId, cwd: input.workdir, mcpServers: [] }, 30_000).catch(() => ({}));
-            }
-            if (!s.sessionId)
-                return { ok: false, text: '', error: 'hermes returned no session id', stopReason: 'error' };
-            if (input.model)
-                await client.request('session/set_model', { sessionId: s.sessionId, modelId: input.model }, 15_000).catch(() => ({}));
-            const promptResp = await client.request('session/prompt', {
-                sessionId: s.sessionId,
-                prompt: [{ type: 'text', text: input.prompt }],
-            }, 7_200_000);
-            const usage = { inputTokens: null, outputTokens: null, cachedInputTokens: null, contextUsedTokens: s.contextUsed, contextPercent: null };
-            if (ctx.signal.aborted)
-                return { ok: false, text: s.text, error: 'Interrupted by user.', stopReason: 'interrupted', sessionId: s.sessionId, usage };
-            if (promptResp.error)
-                return { ok: false, text: s.text, error: promptResp.error.message || 'session/prompt failed', stopReason: 'error', sessionId: s.sessionId, usage };
-            const stopReason = promptResp.result?.stopReason ?? 'end_turn';
-            return { ok: !s.error, text: s.text, reasoning: s.reasoning || undefined, error: s.error, stopReason, sessionId: s.sessionId, usage };
-        }
-        finally {
-            client.kill();
-        }
-    }
-}
-export function applyHermesUpdate(u, s, tools, emit) {
-    if (!u)
-        return;
-    switch (u.sessionUpdate) {
-        case 'agent_message_chunk': {
-            const t = u.content?.text;
-            if (typeof t === 'string' && t) {
-                s.text += t;
-                emit({ type: 'text', delta: t });
-            }
-            return;
-        }
-        case 'agent_thought_chunk': {
-            const t = u.content?.text;
-            if (typeof t === 'string' && t) {
-                s.reasoning += t;
-                emit({ type: 'reasoning', delta: t });
-            }
-            return;
-        }
-        case 'tool_call': {
-            const id = typeof u.toolCallId === 'string' ? u.toolCallId : '';
-            const title = (typeof u.title === 'string' && u.title.trim()) || 'tool';
-            if (id && !tools.has(id)) {
-                tools.add(id);
-                emit({ type: 'tool', call: { id, name: title, summary: title, status: 'running' } });
-            }
-            return;
-        }
-        case 'tool_call_update': {
-            const id = typeof u.toolCallId === 'string' ? u.toolCallId : '';
-            const title = (typeof u.title === 'string' && u.title.trim()) || 'tool';
-            if (id && (u.status === 'completed' || u.status === 'failed'))
-                emit({ type: 'tool', call: { id, name: title, summary: title, status: u.status === 'failed' ? 'failed' : 'done' } });
-            return;
-        }
-        case 'usage_update': {
-            if (typeof u.used === 'number') {
-                s.contextUsed = u.used;
-                emit({ type: 'usage', usage: { inputTokens: null, outputTokens: null, cachedInputTokens: null, contextUsedTokens: u.used, contextPercent: null } });
-            }
-            return;
-        }
+        super({ id: 'hermes', command: bin, args: ['acp'] });
     }
 }
+// Back-compat alias: the generic ACP session/update parser handles the identical wire that
+// the original hermes-specific parser did. Kept so existing imports/tests resolve.
+export const applyHermesUpdate = applyAcpUpdate;

package/packages/kernel/dist/drivers/index.d.ts

@@ -2,4 +2,5 @@ export { EchoDriver } from './echo.js';
 export { ClaudeDriver, handleClaudeEvent, todoWriteToPlan } from './claude.js';
 export { CodexDriver } from './codex.js';
 export { GeminiDriver, parseGeminiEvent } from './gemini.js';
+export { AcpDriver, applyAcpUpdate, toAcpMcpServers, buildAcpPromptBlocks, type AcpDriverConfig } from './acp.js';
 export { HermesDriver, applyHermesUpdate } from './hermes.js';

package/packages/kernel/dist/drivers/index.js

@@ -2,4 +2,5 @@ export { EchoDriver } from './echo.js';
 export { ClaudeDriver, handleClaudeEvent, todoWriteToPlan } from './claude.js';
 export { CodexDriver } from './codex.js';
 export { GeminiDriver, parseGeminiEvent } from './gemini.js';
+export { AcpDriver, applyAcpUpdate, toAcpMcpServers, buildAcpPromptBlocks } from './acp.js';
 export { HermesDriver, applyHermesUpdate } from './hermes.js';

package/packages/kernel/dist/index.d.ts

@@ -4,7 +4,7 @@ export { SessionRunner } from './runtime/session-runner.js';
 export { runTurn, type RunTurnOptions, type TurnOutcome } from './runtime/turn.js';
 export { PtyBridge, ptyAvailable, type PtyExit, type PtyOpenOpts } from './runtime/pty.js';
 export { attachTui, type AttachTuiOptions } from './runtime/tui.js';
-export type { AgentDriver, AgentTurnInput, DriverContext, DriverEvent, DriverResult, SteerFn, McpServerSpec, TuiInput, TuiSpec, } from './contracts/driver.js';
+export type { AgentDriver, AgentTurnInput, DriverContext, DriverEvent, DriverResult, SteerFn, McpServerSpec, TuiInput, TuiSpec, NativeSessionInfo, } from './contracts/driver.js';
 export type { SessionStore, CoreSessionRecord, ModelResolver, ModelInjection, ToolProvider, SystemPromptBuilder, InteractionHandler, Catalog, } from './contracts/ports.js';
 export type { LoomIO, PromptInput, Surface, SurfaceCapabilities, Plugin, SpawnContribution, } from './contracts/surface.js';
 export { FsSessionStore, NullModelResolver, NoopToolProvider, PassthroughSystemPromptBuilder, AutoCancelInteractionHandler, DeferToTerminalInteractionHandler, NoopCatalog, defaultBaseDir, } from './ports/defaults.js';
@@ -12,7 +12,10 @@ export { EchoDriver } from './drivers/echo.js';
 export { ClaudeDriver } from './drivers/claude.js';
 export { CodexDriver } from './drivers/codex.js';
 export { GeminiDriver } from './drivers/gemini.js';
+export { AcpDriver, type AcpDriverConfig } from './drivers/acp.js';
 export { HermesDriver } from './drivers/hermes.js';
 export { WebSurface, type WebSurfaceOptions } from './surfaces/web.js';
 export { CliSurface } from './surfaces/cli.js';
+export * from './workspace/index.js';
+export * from './accounts.js';
 export * from './protocol/index.js';

package/packages/kernel/dist/index.js

@@ -22,8 +22,13 @@ export { EchoDriver } from './drivers/echo.js';
 export { ClaudeDriver } from './drivers/claude.js';
 export { CodexDriver } from './drivers/codex.js';
 export { GeminiDriver } from './drivers/gemini.js';
+export { AcpDriver } from './drivers/acp.js';
 export { HermesDriver } from './drivers/hermes.js';
 export { WebSurface } from './surfaces/web.js';
 export { CliSurface } from './surfaces/cli.js';
+// Workspace: unified top-level directory + session/skill/mcp management (loom.paths/sessions/skills/mcp)
+export * from './workspace/index.js';
+// Multi-account: per-account isolated config dirs (CLAUDE_CONFIG_DIR / CODEX_HOME)
+export * from './accounts.js';
 // Protocol (the wire vocabulary; shared with transports)
 export * from './protocol/index.js';

package/packages/kernel/dist/ports/defaults.js

@@ -25,11 +25,15 @@ export class FsSessionStore {
         if (!existing) {
             const now = new Date().toISOString();
             await this.save({
-                agent, sessionId, workspacePath,
+                agent, sessionId, workspacePath, workdir: path.resolve(opts.workdir),
                 createdAt: now, updatedAt: now,
                 title: opts.title ?? null, runState: 'running', runDetail: null,
             });
         }
+        else if (!existing.workdir) {
+            existing.workdir = path.resolve(opts.workdir);
+            await this.save(existing);
+        }
         return { sessionId, workspacePath };
     }
     async get(agent, sessionId) {
@@ -74,6 +78,8 @@ export class FsSessionStore {
             rec.nativeSessionId = result.sessionId;
         if (result.text && !rec.title)
             rec.title = result.text.slice(0, 80);
+        if (result.text)
+            rec.preview = result.text.replace(/\s+/g, ' ').trim().slice(0, 200) || rec.preview || null;
         await this.save(rec);
     }
     async appendTurn(agent, sessionId, turn) {

package/packages/kernel/dist/runtime/loom.d.ts

@@ -2,6 +2,10 @@ import type { AgentDriver, TuiSpec } from '../contracts/driver.js';
 import type { SessionStore, ModelResolver, ToolProvider, SystemPromptBuilder, Catalog, InteractionHandler } from '../contracts/ports.js';
 import type { LoomIO, Surface, Plugin } from '../contracts/surface.js';
 import { PtyBridge, type PtyOpenOpts, type PtyExit } from './pty.js';
+import { type LoomPaths } from '../workspace/paths.js';
+import { SessionsManager } from '../workspace/sessions.js';
+import { SkillsManager } from '../workspace/skills.js';
+import { McpRegistry } from '../workspace/mcp.js';
 export interface TuiLaunchOptions {
     agent?: string;
     workdir?: string;
@@ -9,9 +13,11 @@ export interface TuiLaunchOptions {
     sessionId?: string | null;
 }
 export interface LoomConfig {
+    stateDirName?: string;
     appNamespace?: string;
     workdir?: string;
     defaultAgent?: string;
+    agentSkillDirs?: string[];
     drivers?: AgentDriver[];
     surfaces?: Surface[];
     plugins?: Plugin[];
@@ -27,6 +33,10 @@ export interface LoomConfig {
 }
 export interface Loom {
     readonly io: LoomIO;
+    readonly paths: LoomPaths;
+    readonly sessions: SessionsManager;
+    readonly skills: SkillsManager;
+    readonly mcp: McpRegistry;
     registerDriver(driver: AgentDriver): void;
     registerPlugin(plugin: Plugin): void;
     start(): Promise<void>;

package/packages/kernel/dist/runtime/loom.js

@@ -2,8 +2,15 @@ import { FsSessionStore, NullModelResolver, NoopToolProvider, PassthroughSystemP
 import { Hub } from './hub.js';
 import { PtyBridge } from './pty.js';
 import { attachTui } from './tui.js';
+import { resolveLoomPaths } from '../workspace/paths.js';
+import { SessionsManager } from '../workspace/sessions.js';
+import { SkillsManager } from '../workspace/skills.js';
+import { McpRegistry } from '../workspace/mcp.js';
 export function createLoom(config = {}) {
-    const appNamespace = config.appNamespace || 'loom';
+    // The top-level dir defaults to 'pikiloom'; appNamespace (the default session-store base)
+    // falls back to it so a single knob configures everything for a fresh consumer.
+    const stateDirName = config.stateDirName || config.appNamespace || 'pikiloom';
+    const appNamespace = config.appNamespace || stateDirName;
     const workdir = config.workdir || process.cwd();
     const log = config.log || (() => { });
     const drivers = new Map();
@@ -12,11 +19,16 @@ export function createLoom(config = {}) {
     const defaultAgent = config.defaultAgent || config.drivers?.[0]?.id || 'echo';
     // Held as a live reference so registerPlugin() mutates the same array the Hub iterates.
     const plugins = [...(config.plugins || [])];
+    const sessionStore = config.sessionStore || new FsSessionStore(defaultBaseDir(appNamespace));
+    const paths = resolveLoomPaths({ stateDirName });
+    const sessions = new SessionsManager({ store: sessionStore, drivers: () => drivers, defaultWorkdir: workdir, log });
+    const skills = new SkillsManager({ paths, agentSkillDirs: config.agentSkillDirs, log });
+    const mcp = new McpRegistry({ log });
     const hub = new Hub({
         drivers,
         defaultAgent,
         workdir,
-        sessionStore: config.sessionStore || new FsSessionStore(defaultBaseDir(appNamespace)),
+        sessionStore,
         modelResolver: config.modelResolver || new NullModelResolver(),
         toolProvider: config.toolProvider || new NoopToolProvider(),
         systemPromptBuilder: config.systemPromptBuilder || new PassthroughSystemPromptBuilder(),
@@ -37,6 +49,10 @@ export function createLoom(config = {}) {
     };
     return {
         io: hub,
+        paths,
+        sessions,
+        skills,
+        mcp,
         registerDriver(driver) { drivers.set(driver.id, driver); },
         registerPlugin(plugin) { plugins.push(plugin); },
         async start() {

package/packages/kernel/dist/workspace/index.d.ts

@@ -0,0 +1,5 @@
+export { resolveLoomPaths, normalizeStateDirName, type LoomPaths, type LoomScope } from './paths.js';
+export { discoverClaudeNativeSessions, discoverCodexNativeSessions, discoverGeminiNativeSessions, encodeClaudeProjectDir, NATIVE_SESSION_RUNNING_THRESHOLD_MS, type DiscoverOptions, type NativeSessionInfo, } from './native.js';
+export { SessionsManager, type ManagedSessionInfo, type SessionSource, type ListSessionsOptions, type SearchSessionsOptions, type SessionsManagerDeps, } from './sessions.js';
+export { SkillsManager, ensureDirSymlink, type SkillInfo, type SkillSearchResult, type SkillsManagerOptions, } from './skills.js';
+export { McpRegistry, type McpCatalogEntry, type McpSearchResult, type McpRegistryOptions, } from './mcp.js';

package/packages/kernel/dist/workspace/index.js

@@ -0,0 +1,7 @@
+// Workspace subsystem: the unified top-level directory + session/skill/mcp management that
+// a consuming app gets "for free" off createLoom() (exposed as loom.paths/sessions/skills/mcp).
+export { resolveLoomPaths, normalizeStateDirName } from './paths.js';
+export { discoverClaudeNativeSessions, discoverCodexNativeSessions, discoverGeminiNativeSessions, encodeClaudeProjectDir, NATIVE_SESSION_RUNNING_THRESHOLD_MS, } from './native.js';
+export { SessionsManager, } from './sessions.js';
+export { SkillsManager, ensureDirSymlink, } from './skills.js';
+export { McpRegistry, } from './mcp.js';

package/packages/kernel/dist/workspace/mcp.d.ts

@@ -0,0 +1,44 @@
+import type { McpServerSpec } from '../contracts/driver.js';
+export interface McpCatalogEntry {
+    id: string;
+    name: string;
+    description?: string;
+    category?: string;
+    brand?: string;
+    transport: {
+        type: 'stdio';
+        command: string;
+        args?: string[];
+    } | {
+        type: 'http';
+        url: string;
+    };
+    /** Required credential env var names (so a UI can prompt for them). */
+    envKeys?: string[];
+    homepage?: string;
+}
+export interface McpSearchResult {
+    name: string;
+    description: string | null;
+    source: 'registry' | 'npm';
+    npmPackage?: string | null;
+    homepage?: string | null;
+}
+export interface McpRegistryOptions {
+    /** Replace/extend the built-in recommended catalog. */
+    recommended?: McpCatalogEntry[];
+    fetchImpl?: typeof fetch;
+    log?: (msg: string) => void;
+}
+export declare class McpRegistry {
+    private readonly _recommended;
+    private readonly fetchImpl;
+    private readonly log?;
+    constructor(opts?: McpRegistryOptions);
+    /** The curated catalog of well-known servers. */
+    recommended(): McpCatalogEntry[];
+    /** Turn a catalog entry into a kernel McpServerSpec ready to hand to a driver/plugin. */
+    toServerSpec(entry: McpCatalogEntry, env?: Record<string, string>): McpServerSpec;
+    /** Search the public MCP registry, falling back to npm. Best-effort; [] on failure. */
+    search(query: string, limit?: number): Promise<McpSearchResult[]>;
+}

package/packages/kernel/dist/workspace/mcp.js

@@ -0,0 +1,82 @@
+const BUILTIN_RECOMMENDED = [
+    { id: 'filesystem', name: 'Filesystem', description: 'Read/write files under allowed directories.', category: 'core', transport: { type: 'stdio', command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem'] }, homepage: 'https://github.com/modelcontextprotocol/servers' },
+    { id: 'github', name: 'GitHub', description: 'GitHub repos, issues, and PRs.', category: 'dev', brand: 'github', transport: { type: 'stdio', command: 'npx', args: ['-y', '@modelcontextprotocol/server-github'] }, envKeys: ['GITHUB_PERSONAL_ACCESS_TOKEN'], homepage: 'https://github.com/modelcontextprotocol/servers' },
+    { id: 'fetch', name: 'Fetch', description: 'Fetch and convert web pages to markdown.', category: 'web', transport: { type: 'stdio', command: 'npx', args: ['-y', '@modelcontextprotocol/server-fetch'] }, homepage: 'https://github.com/modelcontextprotocol/servers' },
+    { id: 'git', name: 'Git', description: 'Local git repository operations.', category: 'dev', transport: { type: 'stdio', command: 'npx', args: ['-y', '@modelcontextprotocol/server-git'] }, homepage: 'https://github.com/modelcontextprotocol/servers' },
+    { id: 'memory', name: 'Memory', description: 'A knowledge-graph memory store.', category: 'core', transport: { type: 'stdio', command: 'npx', args: ['-y', '@modelcontextprotocol/server-memory'] }, homepage: 'https://github.com/modelcontextprotocol/servers' },
+    { id: 'playwright', name: 'Playwright', description: 'Drive a real browser for automation.', category: 'web', brand: 'playwright', transport: { type: 'stdio', command: 'npx', args: ['-y', '@playwright/mcp@latest'] }, homepage: 'https://github.com/microsoft/playwright-mcp' },
+    { id: 'context7', name: 'Context7', description: 'Up-to-date library docs & code examples.', category: 'docs', transport: { type: 'http', url: 'https://mcp.context7.com/mcp' }, homepage: 'https://context7.com' },
+];
+export class McpRegistry {
+    _recommended;
+    fetchImpl;
+    log;
+    constructor(opts = {}) {
+        this._recommended = opts.recommended?.length ? opts.recommended : BUILTIN_RECOMMENDED;
+        this.fetchImpl = opts.fetchImpl ?? (typeof fetch === 'function' ? fetch : undefined);
+        this.log = opts.log;
+    }
+    /** The curated catalog of well-known servers. */
+    recommended() {
+        return this._recommended.map(e => ({ ...e }));
+    }
+    /** Turn a catalog entry into a kernel McpServerSpec ready to hand to a driver/plugin. */
+    toServerSpec(entry, env) {
+        if (entry.transport.type === 'http') {
+            return { name: entry.id, type: 'http', url: entry.transport.url };
+        }
+        return { name: entry.id, type: 'stdio', command: entry.transport.command, args: entry.transport.args, env };
+    }
+    /** Search the public MCP registry, falling back to npm. Best-effort; [] on failure. */
+    async search(query, limit = 20) {
+        const q = (query || '').trim();
+        const n = Math.max(1, Math.min(50, limit));
+        const fetchImpl = this.fetchImpl;
+        if (!fetchImpl)
+            return [];
+        // 1) Official MCP registry.
+        try {
+            const url = `https://registry.modelcontextprotocol.io/v0/servers?search=${encodeURIComponent(q)}&limit=${n}`;
+            const res = await fetchImpl(url, { headers: { accept: 'application/json' } });
+            if (res.ok) {
+                const data = await res.json();
+                const servers = Array.isArray(data?.servers) ? data.servers : Array.isArray(data?.data) ? data.data : [];
+                const mapped = servers.map((s) => ({
+                    name: String(s?.name ?? s?.id ?? ''),
+                    description: s?.description ?? null,
+                    source: 'registry',
+                    npmPackage: s?.packages?.[0]?.identifier ?? s?.npm ?? null,
+                    homepage: s?.repository?.url ?? s?.homepage ?? null,
+                })).filter(s => s.name);
+                if (mapped.length)
+                    return mapped.slice(0, n);
+            }
+        }
+        catch (e) {
+            this.log?.(`[mcp] registry search failed: ${e?.message || e}`);
+        }
+        // 2) npm fallback.
+        try {
+            const url = `https://registry.npmjs.org/-/v1/search?text=${encodeURIComponent(`mcp server ${q}`.trim())}&size=${n}`;
+            const res = await fetchImpl(url, { headers: { accept: 'application/json' } });
+            if (!res.ok)
+                return [];
+            const data = await res.json();
+            const objects = Array.isArray(data?.objects) ? data.objects : [];
+            return objects.map((o) => {
+                const pkg = o?.package ?? {};
+                return {
+                    name: String(pkg.name ?? ''),
+                    description: pkg.description ?? null,
+                    source: 'npm',
+                    npmPackage: pkg.name ?? null,
+                    homepage: pkg.links?.homepage ?? pkg.links?.npm ?? null,
+                };
+            }).filter(s => s.name).slice(0, n);
+        }
+        catch (e) {
+            this.log?.(`[mcp] npm search failed: ${e?.message || e}`);
+            return [];
+        }
+    }
+}

package/packages/kernel/dist/workspace/native.d.ts

@@ -0,0 +1,14 @@
+import type { NativeSessionInfo } from '../contracts/driver.js';
+export type { NativeSessionInfo } from '../contracts/driver.js';
+export interface DiscoverOptions {
+    home?: string;
+    limit?: number;
+    /** A session whose file changed within this window is treated as "running". */
+    runningThresholdMs?: number;
+}
+export declare const NATIVE_SESSION_RUNNING_THRESHOLD_MS = 10000;
+/** Claude encodes a workdir into a project dir name by replacing non-alphanumerics with '-'. */
+export declare function encodeClaudeProjectDir(workdir: string): string;
+export declare function discoverClaudeNativeSessions(workdir: string, opts?: DiscoverOptions): NativeSessionInfo[];
+export declare function discoverCodexNativeSessions(workdir: string, opts?: DiscoverOptions): NativeSessionInfo[];
+export declare function discoverGeminiNativeSessions(workdir: string, opts?: DiscoverOptions): NativeSessionInfo[];