@pikiloom/kernel 0.1.4 → 0.2.1

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

package/dist/workspace/native.js

@@ -0,0 +1,340 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+export const NATIVE_SESSION_RUNNING_THRESHOLD_MS = 10_000;
+function homeOf(opts) {
+    return opts?.home || os.homedir();
+}
+function cleanTitle(raw, max = 120) {
+    if (!raw)
+        return null;
+    const s = raw.replace(/\s+/g, ' ').trim();
+    if (!s)
+        return null;
+    return s.length <= max ? s : `${s.slice(0, max - 3).trimEnd()}...`;
+}
+function statSafe(p) {
+    try {
+        return fs.statSync(p);
+    }
+    catch {
+        return null;
+    }
+}
+// ---- Claude: ~/.claude/projects/<encoded-workdir>/<sessionId>.jsonl ----
+/** Claude encodes a workdir into a project dir name by replacing non-alphanumerics with '-'. */
+export function encodeClaudeProjectDir(workdir) {
+    return path.resolve(workdir).replace(/[^a-zA-Z0-9]/g, '-');
+}
+/** Extract plain text from a Claude `message.content` (string or block array). */
+function claudeText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    const parts = [];
+    for (const block of content) {
+        if (block && typeof block === 'object' && block.type === 'text' && typeof block.text === 'string') {
+            parts.push(block.text);
+        }
+    }
+    return parts.join(' ');
+}
+function readClaudeHead(filePath, size) {
+    let title = null;
+    let model = null;
+    let lastUser = null;
+    let lastAssistant = null;
+    let turns = 0;
+    let head = '';
+    try {
+        const fd = fs.openSync(filePath, 'r');
+        const buf = Buffer.alloc(Math.min(256 * 1024, Math.max(65536, size)));
+        const n = fs.readSync(fd, buf, 0, buf.length, 0);
+        fs.closeSync(fd);
+        head = buf.toString('utf8', 0, n);
+    }
+    catch {
+        return { title: null, model: null, preview: null, turns: 0 };
+    }
+    for (const line of head.split('\n')) {
+        if (!line || line[0] !== '{')
+            continue;
+        let ev;
+        try {
+            ev = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (ev.type === 'user' && ev.isMeta !== true) {
+            const text = claudeText(ev.message?.content).trim();
+            if (text && !text.startsWith('<') && !text.startsWith('[Image:')) {
+                if (!title)
+                    title = cleanTitle(text);
+                lastUser = text;
+                turns++;
+            }
+        }
+        else if (ev.type === 'assistant') {
+            if (!model && ev.message?.model && ev.message.model !== '<synthetic>')
+                model = ev.message.model;
+            const text = claudeText(ev.message?.content).trim();
+            if (text)
+                lastAssistant = text;
+        }
+    }
+    const preview = cleanTitle(lastAssistant || lastUser, 200);
+    return { title, model, preview, turns };
+}
+export function discoverClaudeNativeSessions(workdir, opts = {}) {
+    const home = homeOf(opts);
+    const projectDir = path.join(home, '.claude', 'projects', encodeClaudeProjectDir(workdir));
+    let entries;
+    try {
+        entries = fs.readdirSync(projectDir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const threshold = opts.runningThresholdMs ?? NATIVE_SESSION_RUNNING_THRESHOLD_MS;
+    const files = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.jsonl'))
+            continue;
+        const filePath = path.join(projectDir, entry.name);
+        const stat = statSafe(filePath);
+        if (stat)
+            files.push({ sessionId: entry.name.slice(0, -6), filePath, stat });
+    }
+    files.sort((a, b) => b.stat.mtimeMs - a.stat.mtimeMs);
+    const selected = typeof opts.limit === 'number' ? files.slice(0, Math.max(0, opts.limit)) : files;
+    const now = Date.now();
+    return selected.map(({ sessionId, filePath, stat }) => {
+        const { title, model, preview, turns } = readClaudeHead(filePath, stat.size);
+        return {
+            sessionId,
+            title,
+            preview,
+            cwd: path.resolve(workdir),
+            model,
+            createdAt: stat.birthtime.toISOString(),
+            updatedAt: stat.mtime.toISOString(),
+            running: now - stat.mtimeMs < threshold,
+            messageCount: turns || null,
+        };
+    });
+}
+// ---- Codex: ~/.codex/sessions/**/rollout-*.jsonl (filtered by cwd) ----
+function loadCodexTitleIndex(home) {
+    const indexPath = path.join(home, '.codex', 'session_index.jsonl');
+    const map = new Map();
+    let data;
+    try {
+        data = fs.readFileSync(indexPath, 'utf8');
+    }
+    catch {
+        return map;
+    }
+    for (const line of data.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const entry = JSON.parse(line);
+            if (entry.id)
+                map.set(entry.id, { threadName: entry.thread_name || '', updatedAt: entry.updated_at || '' });
+        }
+        catch { /* skip */ }
+    }
+    return map;
+}
+function readCodexHead(filePath) {
+    try {
+        const fd = fs.openSync(filePath, 'r');
+        const buf = Buffer.alloc(8 * 1024);
+        const n = fs.readSync(fd, buf, 0, buf.length, 0);
+        fs.closeSync(fd);
+        const head = buf.toString('utf8', 0, n);
+        if (!head.includes('"session_meta"'))
+            return null;
+        const id = head.match(/"id"\s*:\s*"([^"]+)"/);
+        const cwd = head.match(/"cwd"\s*:\s*"([^"]+)"/);
+        const ts = head.match(/"timestamp"\s*:\s*"([^"]+)"/);
+        if (!id || !cwd)
+            return null;
+        return {
+            sessionId: id[1],
+            cwd: cwd[1],
+            timestamp: ts?.[1] || null,
+            isSubagent: /"source"\s*:\s*\{\s*"subagent"\s*:/.test(head) || /"thread_spawn"\s*:/.test(head),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function discoverCodexNativeSessions(workdir, opts = {}) {
+    const home = homeOf(opts);
+    const sessionsDir = path.join(home, '.codex', 'sessions');
+    const resolvedWorkdir = path.resolve(workdir);
+    const titleIndex = loadCodexTitleIndex(home);
+    const threshold = opts.runningThresholdMs ?? NATIVE_SESSION_RUNNING_THRESHOLD_MS;
+    const files = [];
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+                continue;
+            }
+            if (!entry.name.startsWith('rollout-') || !entry.name.endsWith('.jsonl'))
+                continue;
+            const stat = statSafe(full);
+            if (stat)
+                files.push({ filePath: full, stat });
+        }
+    };
+    walk(sessionsDir);
+    files.sort((a, b) => b.stat.mtimeMs - a.stat.mtimeMs);
+    const out = [];
+    const seen = new Set();
+    for (const { filePath, stat } of files) {
+        const meta = readCodexHead(filePath);
+        if (!meta || meta.isSubagent || path.resolve(meta.cwd) !== resolvedWorkdir)
+            continue;
+        if (seen.has(meta.sessionId))
+            continue;
+        seen.add(meta.sessionId);
+        const idx = titleIndex.get(meta.sessionId);
+        const updatedAt = idx?.updatedAt || stat.mtime.toISOString();
+        out.push({
+            sessionId: meta.sessionId,
+            title: cleanTitle(idx?.threadName || null),
+            preview: null,
+            cwd: meta.cwd,
+            model: null,
+            createdAt: meta.timestamp || stat.birthtime.toISOString(),
+            updatedAt,
+            running: Date.now() - Date.parse(updatedAt) < threshold,
+            messageCount: null,
+        });
+        if (typeof opts.limit === 'number' && out.length >= opts.limit)
+            break;
+    }
+    return out;
+}
+// ---- Gemini: ~/.gemini/projects.json -> tmp/<projectName>/chats/session-*.json[l] ----
+function geminiProjectName(home, workdir) {
+    const projectsPath = path.join(home, '.gemini', 'projects.json');
+    try {
+        const data = JSON.parse(fs.readFileSync(projectsPath, 'utf8'));
+        const projects = data?.projects;
+        if (!projects || typeof projects !== 'object')
+            return null;
+        const resolved = path.resolve(workdir);
+        if (projects[resolved])
+            return projects[resolved];
+        for (const [dir, name] of Object.entries(projects)) {
+            if (path.resolve(dir) === resolved)
+                return name;
+        }
+    }
+    catch { /* none */ }
+    return null;
+}
+function geminiText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content)) {
+        const parts = [];
+        for (const block of content) {
+            if (typeof block === 'string')
+                parts.push(block);
+            else if (block && typeof block === 'object' && typeof block.text === 'string')
+                parts.push(block.text);
+        }
+        return parts.join(' ');
+    }
+    return '';
+}
+export function discoverGeminiNativeSessions(workdir, opts = {}) {
+    const home = homeOf(opts);
+    const projectName = geminiProjectName(home, workdir);
+    if (!projectName)
+        return [];
+    const chatsDir = path.join(home, '.gemini', 'tmp', projectName, 'chats');
+    let entries;
+    try {
+        entries = fs.readdirSync(chatsDir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const threshold = opts.runningThresholdMs ?? NATIVE_SESSION_RUNNING_THRESHOLD_MS;
+    const byId = new Map();
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.startsWith('session-'))
+            continue;
+        if (!entry.name.endsWith('.json') && !entry.name.endsWith('.jsonl'))
+            continue;
+        const filePath = path.join(chatsDir, entry.name);
+        const stat = statSafe(filePath);
+        if (!stat)
+            continue;
+        let data;
+        try {
+            data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        }
+        catch {
+            continue;
+        }
+        const sessionId = data?.sessionId ? String(data.sessionId) : null;
+        if (!sessionId)
+            continue;
+        const messages = Array.isArray(data.messages) ? data.messages : [];
+        let title = null;
+        let lastUser = null;
+        let lastAssistant = null;
+        let turns = 0;
+        for (const msg of messages) {
+            if (msg?.type === 'user') {
+                const t = geminiText(msg.content).trim();
+                if (t) {
+                    if (!title)
+                        title = cleanTitle(t);
+                    lastUser = t;
+                    turns++;
+                }
+            }
+            else if (msg?.type === 'model' || msg?.type === 'assistant' || msg?.type === 'gemini') {
+                const t = geminiText(msg.content).trim();
+                if (t)
+                    lastAssistant = t;
+            }
+        }
+        const updatedAt = data.lastUpdated || data.startTime || data.createdAt || stat.mtime.toISOString();
+        const existing = byId.get(sessionId);
+        if (existing && existing.updatedAt && updatedAt && Date.parse(updatedAt) <= Date.parse(existing.updatedAt))
+            continue;
+        byId.set(sessionId, {
+            sessionId,
+            title,
+            preview: cleanTitle(lastAssistant || lastUser, 200),
+            cwd: path.resolve(workdir),
+            model: null,
+            createdAt: data.startTime || data.createdAt || null,
+            updatedAt,
+            running: data.lastUpdated ? Date.now() - Date.parse(data.lastUpdated) < threshold : false,
+            messageCount: turns || null,
+        });
+    }
+    const out = [...byId.values()].sort((a, b) => Date.parse(b.updatedAt || '') - Date.parse(a.updatedAt || ''));
+    return typeof opts.limit === 'number' ? out.slice(0, Math.max(0, opts.limit)) : out;
+}

package/dist/workspace/paths.d.ts

@@ -0,0 +1,33 @@
+export type LoomScope = 'global' | 'workspace';
+export interface LoomPaths {
+    /** The bare name (no leading dot), e.g. 'pikiloom'. */
+    readonly stateDirName: string;
+    /** The dotted directory name, e.g. '.pikiloom'. */
+    readonly dirName: string;
+    readonly home: string;
+    /** ~/.<stateDirName> */
+    readonly globalRoot: string;
+    /** <workdir>/.<stateDirName> */
+    workspaceRoot(workdir: string): string;
+    /** The root for a scope (workspace requires a workdir). */
+    root(scope: LoomScope, workdir?: string): string;
+    /** <root>/sessions */
+    sessionsDir(scope: LoomScope, workdir?: string): string;
+    /** <root>/skills — the canonical skills registry that agent dirs symlink to. */
+    skillsDir(scope: LoomScope, workdir?: string): string;
+    /** <root>/mcp.json — the unified MCP server config for a scope. */
+    mcpConfigPath(scope: LoomScope, workdir?: string): string;
+    /**
+     * The base under which an agent keeps its own dotfiles for a scope:
+     *   global    -> ~        (so ~/.claude, ~/.agents)
+     *   workspace -> <workdir> (so <workdir>/.claude, <workdir>/.agents)
+     * Used to resolve symlink targets for native agents.
+     */
+    agentHome(scope: LoomScope, workdir?: string): string;
+}
+/** Normalize a state dir name to its bare form: strip a leading dot, trim. */
+export declare function normalizeStateDirName(name: string | null | undefined): string;
+export declare function resolveLoomPaths(opts?: {
+    stateDirName?: string | null;
+    home?: string;
+}): LoomPaths;

package/dist/workspace/paths.js

@@ -0,0 +1,40 @@
+import os from 'node:os';
+import path from 'node:path';
+/** Normalize a state dir name to its bare form: strip a leading dot, trim. */
+export function normalizeStateDirName(name) {
+    const trimmed = (name ?? '').trim().replace(/^\.+/, '');
+    return trimmed || 'pikiloom';
+}
+export function resolveLoomPaths(opts = {}) {
+    const stateDirName = normalizeStateDirName(opts.stateDirName);
+    const dirName = `.${stateDirName}`;
+    const home = opts.home || os.homedir();
+    const globalRoot = path.join(home, dirName);
+    const workspaceRoot = (workdir) => path.join(path.resolve(workdir), dirName);
+    const root = (scope, workdir) => {
+        if (scope === 'global')
+            return globalRoot;
+        if (!workdir)
+            throw new Error('workspace scope requires a workdir');
+        return workspaceRoot(workdir);
+    };
+    const agentHome = (scope, workdir) => {
+        if (scope === 'global')
+            return home;
+        if (!workdir)
+            throw new Error('workspace scope requires a workdir');
+        return path.resolve(workdir);
+    };
+    return {
+        stateDirName,
+        dirName,
+        home,
+        globalRoot,
+        workspaceRoot,
+        root,
+        agentHome,
+        sessionsDir: (scope, workdir) => path.join(root(scope, workdir), 'sessions'),
+        skillsDir: (scope, workdir) => path.join(root(scope, workdir), 'skills'),
+        mcpConfigPath: (scope, workdir) => path.join(root(scope, workdir), 'mcp.json'),
+    };
+}

package/dist/workspace/sessions.d.ts

@@ -0,0 +1,49 @@
+import type { AgentDriver } from '../contracts/driver.js';
+import type { SessionStore } from '../contracts/ports.js';
+import type { LoomScope } from './paths.js';
+export type SessionSource = 'managed' | 'native';
+export interface ManagedSessionInfo {
+    sessionKey: string;
+    agent: string;
+    sessionId: string;
+    title: string | null;
+    preview: string | null;
+    workdir: string | null;
+    model: string | null;
+    effort: string | null;
+    runState: 'running' | 'completed' | 'incomplete' | null;
+    running: boolean;
+    source: SessionSource;
+    createdAt: string | null;
+    updatedAt: string | null;
+}
+export interface ListSessionsOptions {
+    /**
+     * 'workspace' = only sessions for `workdir` (managed-with-matching-cwd + native for the cwd).
+     * 'global'    = all managed sessions across every workdir, plus native for `workdir`.
+     * 'all'       = global, the default.
+     */
+    scope?: LoomScope | 'all';
+    workdir?: string;
+    agent?: string;
+    includeNative?: boolean;
+    limit?: number;
+}
+export interface SearchSessionsOptions extends ListSessionsOptions {
+    query: string;
+}
+export interface SessionsManagerDeps {
+    store: SessionStore;
+    drivers: () => Map<string, AgentDriver>;
+    defaultWorkdir: string;
+    log?: (msg: string) => void;
+}
+export declare class SessionsManager {
+    private readonly deps;
+    constructor(deps: SessionsManagerDeps);
+    list(opts?: ListSessionsOptions): Promise<ManagedSessionInfo[]>;
+    search(opts: SearchSessionsOptions): Promise<ManagedSessionInfo[]>;
+    get(sessionKey: string, opts?: {
+        workdir?: string;
+    }): Promise<ManagedSessionInfo | null>;
+}