@pikiloom/kernel 0.1.4 → 0.2.1

package/dist/workspace/sessions.js

@@ -0,0 +1,130 @@
+import path from 'node:path';
+function splitKey(sessionKey) {
+    const i = sessionKey.indexOf(':');
+    return i < 0 ? { agent: '', sessionId: sessionKey } : { agent: sessionKey.slice(0, i), sessionId: sessionKey.slice(i + 1) };
+}
+function ts(iso) {
+    if (!iso)
+        return 0;
+    const n = Date.parse(iso);
+    return Number.isNaN(n) ? 0 : n;
+}
+function newer(a, b) {
+    return ts(b) > ts(a) ? b : a;
+}
+function managedToInfo(agent, rec) {
+    return {
+        sessionKey: `${agent}:${rec.sessionId}`,
+        agent,
+        sessionId: rec.sessionId,
+        title: rec.title ?? null,
+        preview: rec.preview ?? null,
+        workdir: rec.workdir ?? null,
+        model: rec.model ?? null,
+        effort: rec.effort ?? null,
+        runState: rec.runState ?? null,
+        running: rec.runState === 'running',
+        source: 'managed',
+        createdAt: rec.createdAt ?? null,
+        updatedAt: rec.updatedAt ?? null,
+    };
+}
+function nativeToInfo(agent, n) {
+    return {
+        sessionKey: `${agent}:${n.sessionId}`,
+        agent,
+        sessionId: n.sessionId,
+        title: n.title,
+        preview: n.preview,
+        workdir: n.cwd,
+        model: n.model,
+        effort: null,
+        runState: n.running ? 'running' : 'completed',
+        running: n.running,
+        source: 'native',
+        createdAt: n.createdAt,
+        updatedAt: n.updatedAt,
+    };
+}
+export class SessionsManager {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async list(opts = {}) {
+        const scope = opts.scope ?? 'all';
+        const workdir = path.resolve(opts.workdir || this.deps.defaultWorkdir);
+        const includeNative = opts.includeNative !== false;
+        const drivers = this.deps.drivers();
+        const agentIds = opts.agent ? [opts.agent] : [...drivers.keys()];
+        const byKey = new Map();
+        // Managed sessions (the kernel's own store).
+        for (const agent of agentIds) {
+            let records = [];
+            try {
+                records = await this.deps.store.list(agent);
+            }
+            catch (e) {
+                this.deps.log?.(`[sessions] store.list(${agent}) failed: ${e?.message || e}`);
+            }
+            for (const rec of records) {
+                if (scope === 'workspace') {
+                    if (!rec.workdir || path.resolve(rec.workdir) !== workdir)
+                        continue;
+                }
+                byKey.set(`${agent}:${rec.sessionId}`, managedToInfo(agent, rec));
+            }
+        }
+        // Native sessions (the agents' own stores) — inherently per-workdir.
+        if (includeNative) {
+            for (const agent of agentIds) {
+                const driver = drivers.get(agent);
+                if (!driver?.listNativeSessions)
+                    continue;
+                let natives = [];
+                try {
+                    natives = await driver.listNativeSessions({ workdir, limit: opts.limit });
+                }
+                catch (e) {
+                    this.deps.log?.(`[sessions] ${agent}.listNativeSessions failed: ${e?.message || e}`);
+                }
+                for (const n of natives) {
+                    const key = `${agent}:${n.sessionId}`;
+                    const existing = byKey.get(key);
+                    if (existing) {
+                        // Same identity discovered both ways: managed record wins, but adopt the newer
+                        // timestamp and backfill any fields the managed record never captured.
+                        existing.updatedAt = newer(existing.updatedAt, n.updatedAt);
+                        existing.preview = existing.preview ?? n.preview;
+                        existing.title = existing.title ?? n.title;
+                        existing.model = existing.model ?? n.model;
+                        existing.running = existing.running || n.running;
+                    }
+                    else {
+                        byKey.set(key, nativeToInfo(agent, n));
+                    }
+                }
+            }
+        }
+        const out = [...byKey.values()].sort((a, b) => ts(b.updatedAt) - ts(a.updatedAt));
+        return typeof opts.limit === 'number' ? out.slice(0, Math.max(0, opts.limit)) : out;
+    }
+    async search(opts) {
+        const q = (opts.query || '').trim().toLowerCase();
+        const all = await this.list({ ...opts, limit: undefined });
+        const matched = q
+            ? all.filter(s => [s.title, s.preview, s.sessionId, s.model, s.agent].some(v => v != null && v.toLowerCase().includes(q)))
+            : all;
+        return typeof opts.limit === 'number' ? matched.slice(0, Math.max(0, opts.limit)) : matched;
+    }
+    async get(sessionKey, opts = {}) {
+        const { agent, sessionId } = splitKey(sessionKey);
+        if (!agent)
+            return null;
+        const rec = await this.deps.store.get(agent, sessionId).catch(() => null);
+        if (rec)
+            return managedToInfo(agent, rec);
+        const list = await this.list({ agent, workdir: opts.workdir });
+        return list.find(s => s.sessionKey === sessionKey) ?? null;
+    }
+}

package/dist/workspace/skills.d.ts

@@ -0,0 +1,44 @@
+import type { LoomPaths, LoomScope } from './paths.js';
+export interface SkillInfo {
+    name: string;
+    label: string | null;
+    description: string | null;
+    scope: LoomScope;
+    path: string;
+    mcpRequires?: string[];
+}
+export interface SkillSearchResult {
+    name: string;
+    description: string | null;
+    source: string;
+    author?: string | null;
+    homepage?: string | null;
+    version?: string | null;
+}
+export interface SkillsManagerOptions {
+    paths: LoomPaths;
+    /** Agent skills dirs (relative to the scope's agentHome) to symlink to the canonical dir. */
+    agentSkillDirs?: string[];
+    log?: (msg: string) => void;
+}
+/** Make `linkPath` a symlink to `targetDir` (idempotent; replaces a stale link/dir). */
+export declare function ensureDirSymlink(linkPath: string, targetDir: string): void;
+export declare class SkillsManager {
+    private readonly paths;
+    private readonly agentSkillDirs;
+    private readonly log?;
+    constructor(opts: SkillsManagerOptions);
+    /** The canonical skills dir for a scope, e.g. <workdir>/.pikiloom/skills or ~/.pikiloom/skills. */
+    canonicalDir(scope: LoomScope, workdir?: string): string;
+    /** Absolute paths of the per-agent skill dirs that link to the canonical dir for a scope. */
+    agentLinkPaths(scope: LoomScope, workdir?: string): string[];
+    /** Ensure the canonical dir exists and each agent skills dir symlinks to it. */
+    ensureLinks(scope: LoomScope, workdir?: string): void;
+    /** List skills. scope 'all' (default) = workspace (if workdir) then global, project wins on name clash. */
+    list(opts?: {
+        workdir?: string;
+        scope?: LoomScope | 'all';
+    }): SkillInfo[];
+    /** Search installable skills on the npm registry (best-effort; [] on failure). */
+    search(query: string, limit?: number): Promise<SkillSearchResult[]>;
+}

package/dist/workspace/skills.js

@@ -0,0 +1,173 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const DEFAULT_AGENT_SKILL_DIRS = ['.claude/skills', '.agents/skills'];
+function parseSkillMeta(content) {
+    let label = null;
+    let description = null;
+    let mcpRequires;
+    const fm = content.match(/^---\s*\n([\s\S]*?)\n---/);
+    if (fm) {
+        const lm = fm[1].match(/^label:\s*(.+)/m);
+        if (lm)
+            label = lm[1].trim();
+        const dm = fm[1].match(/^description:\s*(.+)/m);
+        if (dm)
+            description = dm[1].trim();
+        const mr = fm[1].match(/^mcp_requires:\s*\n((?:\s+-\s+.+\n?)+)/m);
+        if (mr) {
+            mcpRequires = mr[1].split('\n').map(l => l.replace(/^\s*-\s*/, '').replace(/["']/g, '').trim()).filter(Boolean);
+        }
+    }
+    if (!label) {
+        const hm = content.match(/^#\s+(.+)$/m);
+        if (hm)
+            label = hm[1].trim();
+    }
+    return { label, description, mcpRequires };
+}
+function realPathOrNull(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return null;
+    }
+}
+/** Make `linkPath` a symlink to `targetDir` (idempotent; replaces a stale link/dir). */
+export function ensureDirSymlink(linkPath, targetDir) {
+    const desiredTarget = path.relative(path.dirname(linkPath), targetDir) || '.';
+    try {
+        const stat = fs.lstatSync(linkPath);
+        if (stat.isSymbolicLink()) {
+            const currentTarget = fs.readlinkSync(linkPath);
+            const currentReal = realPathOrNull(path.resolve(path.dirname(linkPath), currentTarget));
+            const desiredReal = realPathOrNull(targetDir);
+            if (currentTarget === desiredTarget || (currentReal && desiredReal && currentReal === desiredReal))
+                return;
+            fs.unlinkSync(linkPath);
+        }
+        else {
+            fs.rmSync(linkPath, { recursive: true, force: true });
+        }
+    }
+    catch { /* nothing there yet */ }
+    fs.mkdirSync(path.dirname(linkPath), { recursive: true });
+    try {
+        fs.symlinkSync(desiredTarget, linkPath, process.platform === 'win32' ? 'junction' : 'dir');
+    }
+    catch (err) {
+        if (err?.code !== 'EEXIST' || fs.readlinkSync(linkPath) !== desiredTarget)
+            throw err;
+    }
+}
+function discoverSkillsFromDir(dir, scope, seen) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir).sort((a, b) => a.localeCompare(b, 'en', { sensitivity: 'base' }));
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of entries) {
+        if (!name || seen.has(name))
+            continue;
+        const skillDir = path.join(dir, name);
+        const skillFile = path.join(skillDir, 'SKILL.md');
+        try {
+            if (!fs.statSync(skillDir).isDirectory())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        try {
+            if (!fs.statSync(skillFile).isFile())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        let meta = { label: null, description: null };
+        try {
+            meta = parseSkillMeta(fs.readFileSync(skillFile, 'utf8'));
+        }
+        catch { /* keep defaults */ }
+        out.push({ name, label: meta.label, description: meta.description, scope, path: skillDir, mcpRequires: meta.mcpRequires });
+        seen.add(name);
+    }
+    return out;
+}
+export class SkillsManager {
+    paths;
+    agentSkillDirs;
+    log;
+    constructor(opts) {
+        this.paths = opts.paths;
+        this.agentSkillDirs = opts.agentSkillDirs?.length ? opts.agentSkillDirs : DEFAULT_AGENT_SKILL_DIRS;
+        this.log = opts.log;
+    }
+    /** The canonical skills dir for a scope, e.g. <workdir>/.pikiloom/skills or ~/.pikiloom/skills. */
+    canonicalDir(scope, workdir) {
+        return this.paths.skillsDir(scope, workdir);
+    }
+    /** Absolute paths of the per-agent skill dirs that link to the canonical dir for a scope. */
+    agentLinkPaths(scope, workdir) {
+        const base = this.paths.agentHome(scope, workdir);
+        return this.agentSkillDirs.map(rel => path.join(base, rel));
+    }
+    /** Ensure the canonical dir exists and each agent skills dir symlinks to it. */
+    ensureLinks(scope, workdir) {
+        const canonical = this.canonicalDir(scope, workdir);
+        fs.mkdirSync(canonical, { recursive: true });
+        for (const link of this.agentLinkPaths(scope, workdir)) {
+            try {
+                ensureDirSymlink(link, canonical);
+            }
+            catch (e) {
+                this.log?.(`[skills] link ${link} -> ${canonical} failed: ${e?.message || e}`);
+            }
+        }
+    }
+    /** List skills. scope 'all' (default) = workspace (if workdir) then global, project wins on name clash. */
+    list(opts = {}) {
+        const scope = opts.scope ?? 'all';
+        const seen = new Set();
+        const out = [];
+        if ((scope === 'workspace' || scope === 'all') && opts.workdir) {
+            out.push(...discoverSkillsFromDir(this.paths.skillsDir('workspace', opts.workdir), 'workspace', seen));
+        }
+        if (scope === 'global' || scope === 'all') {
+            out.push(...discoverSkillsFromDir(this.paths.skillsDir('global'), 'global', seen));
+        }
+        return out;
+    }
+    /** Search installable skills on the npm registry (best-effort; [] on failure). */
+    async search(query, limit = 20) {
+        const q = (query || '').trim();
+        const text = encodeURIComponent(`agent skill ${q}`.trim());
+        const url = `https://registry.npmjs.org/-/v1/search?text=${text}&size=${Math.max(1, Math.min(50, limit))}`;
+        try {
+            const res = await fetch(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',
+                    author: pkg.publisher?.username ?? pkg.author?.name ?? null,
+                    homepage: pkg.links?.homepage ?? pkg.links?.npm ?? null,
+                    version: pkg.version ?? null,
+                };
+            }).filter(s => s.name);
+        }
+        catch (e) {
+            this.log?.(`[skills] search failed: ${e?.message || e}`);
+            return [];
+        }
+    }
+}

package/llms.txt

@@ -35,7 +35,7 @@ await loom.start();
 const { sessionKey, taskId } = await loom.io.prompt({ prompt: 'hi', agent: 'claude' });
 const unsub = loom.io.subscribe((key, snapshot, patch, seq) => render(snapshot));
 ```
-Every port has a default (zero config). Override any: sessionStore, modelResolver, toolProvider, systemPromptBuilder, catalog, interactionHandler, plugins, serialPerSession, appNamespace, workdir, defaultAgent, log.
+Every port has a default (zero config). Override any: sessionStore, modelResolver, toolProvider, systemPromptBuilder, catalog, interactionHandler, plugins, serialPerSession, stateDirName, appNamespace, agentSkillDirs, workdir, defaultAgent, log.
 
 3) RAW TUI passthrough — `loom.runTui({ agent, workdir })` (full stdio passthrough) or `loom.openTui(...) => PtyBridge` (onData/write/resize/onExit). Needs optional `node-pty`; `ptyAvailable()` reports it.
 
@@ -71,6 +71,28 @@ Wire delta helpers: `diffSnapshot(prev,next) => SnapshotPatch` (prefix-append te
 - discovery: `listModels(agent)`, `listEffort(agent, model?)`, `listTools(agent, workdir?)`, `listSkills(agent, workdir?)`
 Concurrent prompts to one session queue by default (serialPerSession=true).
 
+## Workspace: unified top-level directory + session/skill/mcp management (loom.paths/sessions/skills/mcp)
+
+One explicitly-configurable top-level dir (`createLoom({ stateDirName })`, default `'pikiloom'` → `.pikiloom`)
+governs a session index, a skills registry and per-agent symlinks, resolved in two scopes: global
+(`~/.pikiloom`) and per-workspace (`<workdir>/.pikiloom`). Exposed off the Loom:
+
+- `loom.paths: LoomPaths` — `resolveLoomPaths({stateDirName})`. `globalRoot`, `workspaceRoot(wd)`,
+  `sessionsDir/skillsDir/mcpConfigPath(scope, wd?)`, `agentHome(scope, wd?)`. (`scope: 'global'|'workspace'`.)
+- `loom.sessions: SessionsManager` — the unified, searchable session read-model. Merges MANAGED sessions
+  (the SessionStore, scoped per workspace by the cwd they ran in) with each agent's NATIVE sessions
+  (driver.listNativeSessions — claude/codex/gemini read their own on-disk transcripts). `list({scope:'workspace'|'global'|'all', workdir?, agent?, includeNative?, limit?}) => ManagedSessionInfo[]`,
+  `search({query, ...}) `, `get(sessionKey)`. This is "全局 + 每个工作区的会话列表，含 claude/codex 自己的会话 + 搜索".
+- `loom.skills: SkillsManager` — the canonical skills registry. `canonicalDir(scope,wd?)` = `<root>/skills`;
+  `ensureLinks(scope, wd?)` symlinks it into each agent's dir (default `.claude/skills`, `.agents/skills`,
+  overridable via `agentSkillDirs`) so a skill registered once is visible to every agent. `list({workdir?,scope?})`,
+  `search(query) => npm results`.
+- `loom.mcp: McpRegistry` — `recommended(): McpCatalogEntry[]` (curated), `search(query)` (MCP registry → npm),
+  `toServerSpec(entry, env?) => McpServerSpec`. Enabling/injecting a server stays on the Plugin.tools()/ToolProvider seam.
+
+Drivers expose native discovery via the optional `AgentDriver.listNativeSessions?({workdir, limit}) => NativeSessionInfo[]`
+(implemented by Claude/Codex/Gemini; pure node-builtins, also exported as `discover{Claude,Codex,Gemini}NativeSessions`).
+
 ## Drivers (pass to createLoom({drivers}) or loom.registerDriver)
 
 - ClaudeDriver (id 'claude'): `claude` CLI stream-json, supports --effort; steer ✓, resume ✓, tui ✓

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikiloom/kernel",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "description": "Heterogeneous coding agents (Claude / Codex / Gemini / ACP) -> an interaction-friendly, accumulating session snapshot + control handle, over pluggable surfaces (IM, Web, tunnel, TUI). The reusable core pikiloom itself is built on.",
   "type": "module",
   "license": "MIT",