@pikiloom/kernel 0.1.5 → 0.2.1

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/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/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'];

package/dist/drivers/codex.d.ts

@@ -1,4 +1,4 @@
-import type { AgentDriver, AgentTurnInput, DriverContext, DriverEvent, DriverResult, TuiInput, TuiSpec } from '../contracts/driver.js';
+import type { AgentDriver, AgentTurnInput, DriverContext, DriverEvent, DriverResult, TuiInput, TuiSpec, NativeSessionInfo } from '../contracts/driver.js';
 import type { UniversalUsage } from '../protocol/index.js';
 export declare function codexToolSummary(item: any): {
     id: string;
@@ -29,6 +29,10 @@ export declare class CodexDriver implements AgentDriver {
     constructor(bin?: string);
     run(input: AgentTurnInput, ctx: DriverContext): Promise<DriverResult>;
     tui(input: TuiInput): TuiSpec;
+    listNativeSessions(opts: {
+        workdir: string;
+        limit?: number;
+    }): NativeSessionInfo[];
 }
 export interface CodexUsageState {
     input: number | null;

package/dist/drivers/codex.js

@@ -1,4 +1,5 @@
 import { spawn } from 'node:child_process';
+import { discoverCodexNativeSessions } from '../workspace/native.js';
 // Minimal newline-delimited JSON-RPC client for `codex app-server` (ported faithfully
 // from pikiloom's CodexAppServer; trimmed to what the kernel needs).
 class AppServer {
@@ -405,6 +406,9 @@ export class CodexDriver {
             args.push(...input.extraArgs);
         return { command: this.bin, args, cwd: input.workdir, env: input.env };
     }
+    listNativeSessions(opts) {
+        return discoverCodexNativeSessions(opts.workdir, { limit: opts.limit });
+    }
 }
 const IMAGE_EXTS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp']);
 function buildTurnInput(prompt, attachments) {

package/dist/drivers/gemini.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';
 export declare class GeminiDriver implements AgentDriver {
     private readonly bin;
     readonly id = "gemini";
@@ -11,6 +11,10 @@ export declare class GeminiDriver implements AgentDriver {
     constructor(bin?: string);
     run(input: AgentTurnInput, ctx: DriverContext): Promise<DriverResult>;
     tui(input: TuiInput): TuiSpec;
+    listNativeSessions(opts: {
+        workdir: string;
+        limit?: number;
+    }): NativeSessionInfo[];
 }
 export declare function parseGeminiEvent(ev: any, s: any, tools: Map<string, {
     name: string;

package/dist/drivers/gemini.js

@@ -1,4 +1,5 @@
 import { spawn } from 'node:child_process';
+import { discoverGeminiNativeSessions } from '../workspace/native.js';
 // Native kernel Gemini driver: `gemini --output-format stream-json ... -p <prompt>` and
 // parse its stream-json events into kernel DriverEvents. Faithful to pikiloom's geminiParse.
 export class GeminiDriver {
@@ -80,6 +81,9 @@ export class GeminiDriver {
             args.push(...input.extraArgs);
         return { command: this.bin, args, cwd: input.workdir, env: input.env };
     }
+    listNativeSessions(opts) {
+        return discoverGeminiNativeSessions(opts.workdir, { limit: opts.limit });
+    }
 }
 export function parseGeminiEvent(ev, s, tools, emit) {
     const t = ev.type || '';

package/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';
@@ -15,4 +15,5 @@ export { GeminiDriver } from './drivers/gemini.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 './protocol/index.js';

package/dist/index.js

@@ -25,5 +25,7 @@ export { GeminiDriver } from './drivers/gemini.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';
 // Protocol (the wire vocabulary; shared with transports)
 export * from './protocol/index.js';

package/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/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/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/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/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/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/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/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[];