pikiloom 0.4.61 → 0.4.63

package/packages/kernel/dist/index.js

@@ -8,6 +8,10 @@
 //   await loom.start()
 //
 // pikiloom itself is just a consumer of this package.
+//
+// This barrel IS the public API (pinned by test/api-surface.test.ts). Driver-internal
+// parser/settle helpers are exported by their modules for white-box tests but are
+// deliberately NOT re-exported here.
 export { createLoom } from './runtime/loom.js';
 export { Hub } from './runtime/hub.js';
 export { SessionRunner } from './runtime/session-runner.js';
@@ -19,16 +23,20 @@ export { attachTui } from './runtime/tui.js';
 export { FsSessionStore, NullModelResolver, NoopToolProvider, PassthroughSystemPromptBuilder, AutoCancelInteractionHandler, DeferToTerminalInteractionHandler, NoopCatalog, defaultBaseDir, } from './ports/defaults.js';
 // Drivers & surfaces (also available via subpath exports)
 export { EchoDriver } from './drivers/echo.js';
-export { ClaudeDriver, isTerminalTaskStatus, trackClaudeBackgroundTask, pendingClaudeBackgroundTasks, markClaudeTaskNotificationTerminal, decideClaudeResultSettle, claudeBgHoldCapMs, claudeBgAgentHoldCapMs, claudeTurnHasAgentBackground, claudeBgHoldRecheckMs, claudeBgSettleQuietMs, claudeModelStallMs, claudeUserEventHasToolResult, handleClaudeEvent, claudeTurnEndedDangling, claudeTruncatedRecoveryEnabled, CLAUDE_TRUNCATED_RECOVERY_PROMPT, isClaudeSyntheticResumeNoise, claudeProducedRealOutput, claudeResumeNoopRetryLimit, } from './drivers/claude.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';
+// Native-session discovery: pure readers of each agent CLI's own transcript store
+// (driver-axis knowledge; drivers implement listNativeSessions with these).
+export { discoverClaudeNativeSessions, discoverCodexNativeSessions, discoverGeminiNativeSessions, encodeClaudeProjectDir, } from './drivers/native.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)
+// Multi-account: which env var carries an agent's auth token, so an app can inject a
+// selected account's token per spawn (see accounts.ts for the design notes).
 export * from './accounts.js';
 // Protocol (the wire vocabulary; shared with transports)
 export * from './protocol/index.js';

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

@@ -101,6 +101,11 @@ export interface SessionMeta {
     phase?: SessionPhase;
     updatedAt?: number;
 }
+export declare function makeSessionKey(agent: string, sessionId: string): string;
+export declare function splitSessionKey(sessionKey: string): {
+    agent: string;
+    sessionId: string;
+};
 export interface SnapshotPatch {
     full?: UniversalSnapshot;
     appendText?: string;

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

@@ -2,6 +2,16 @@
 // This is the SSOT shape: a driver-agnostic, accumulating snapshot of one session,
 // plus a small set of control verbs. Ported from pikiloom's pikichannel protocol.
 export const PROTOCOL_VERSION = 1;
+// ---- Session keys ----
+// A sessionKey is `${agent}:${sessionId}` — the composite id shared by the runtime, every
+// store, and every terminal. These two helpers ARE that contract; nothing else parses it.
+export function makeSessionKey(agent, sessionId) {
+    return `${agent}:${sessionId}`;
+}
+export function splitSessionKey(sessionKey) {
+    const i = sessionKey.indexOf(':');
+    return i < 0 ? { agent: '', sessionId: sessionKey } : { agent: sessionKey.slice(0, i), sessionId: sessionKey.slice(i + 1) };
+}
 export function emptySnapshot() {
     return { phase: 'idle', updatedAt: 0 };
 }

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

@@ -1,10 +1,6 @@
 import { randomUUID } from 'node:crypto';
-import { diffSnapshot, emptySnapshot, } from '../protocol/index.js';
+import { diffSnapshot, emptySnapshot, makeSessionKey, splitSessionKey, } from '../protocol/index.js';
 import { SessionRunner } from './session-runner.js';
-function splitKey(sessionKey) {
-    const i = sessionKey.indexOf(':');
-    return i < 0 ? { agent: '', sessionId: sessionKey } : { agent: sessionKey.slice(0, i), sessionId: sessionKey.slice(i + 1) };
-}
 export class Hub {
     deps;
     sessions = new Map();
@@ -57,12 +53,12 @@ export class Hub {
         if (!driver)
             throw new Error(`No driver registered for agent "${agent}"`);
         const workdir = input.workdir || this.deps.workdir;
-        const resumeId = input.sessionKey ? splitKey(input.sessionKey).sessionId : null;
+        const resumeId = input.sessionKey ? splitSessionKey(input.sessionKey).sessionId : null;
         const preExisted = resumeId ? !!(await this.deps.sessionStore.get(agent, resumeId)) : false;
         const { sessionId, workspacePath } = await this.deps.sessionStore.ensure(agent, {
             sessionId: resumeId, workdir, title: input.prompt.slice(0, 80),
         });
-        const sessionKey = `${agent}:${sessionId}`;
+        const sessionKey = makeSessionKey(agent, sessionId);
         const taskId = randomUUID();
         const runner = new SessionRunner(sessionKey, agent, taskId, (snap, seq) => this.onRunnerUpdate(sessionKey, snap, seq), this.deps.interactionHandler);
         this.runnersByTask.set(taskId, runner);
@@ -124,6 +120,12 @@ export class Hub {
             extraArgs: spawn.extraArgs,
             configOverrides: spawn.configOverrides,
             extraMcpServers: tools.servers,
+            // The managed path's control verb `LoomIO.steer()` can only reach a driver that was
+            // launched steer-enabled, so honor the driver's declared capability here — otherwise
+            // steer is a silent no-op for steer-capable agents (claude gates registerSteer +
+            // --replay-user-messages on this flag). Drivers that don't support steer stay
+            // un-steerable; those that steer over their own channel regardless (codex RPC) ignore it.
+            steerable: !!driver.capabilities?.steer,
         };
         runner.run(driver, turnInput, input.prompt, model, effort)
             .then(async (result) => {
@@ -320,7 +322,7 @@ export class Hub {
         return e ? { snapshot: e.snapshot, seq: e.seq } : null;
     }
     async getHistory(sessionKey) {
-        const { agent, sessionId } = splitKey(sessionKey);
+        const { agent, sessionId } = splitSessionKey(sessionKey);
         if (!agent || !this.deps.sessionStore.history)
             return [];
         try {

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

@@ -1,5 +1,4 @@
 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 { SkillsManager, ensureDirSymlink, parseSkillMeta, type SkillInfo, type SkillMeta, 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

@@ -1,7 +1,8 @@
 // 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).
+// (Native-session discovery lives with the drivers — drivers/native.ts — because knowing each
+// agent CLI's on-disk transcript format is driver-axis knowledge.)
 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 { SkillsManager, ensureDirSymlink, parseSkillMeta, } from './skills.js';
 export { McpRegistry, } from './mcp.js';

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

@@ -1,3 +1,4 @@
+import { searchNpmPackages } from './npm-search.js';
 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' },
@@ -57,22 +58,11 @@ export class McpRegistry {
         }
         // 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);
+            const hits = await searchNpmPackages(`mcp server ${q}`.trim(), n, fetchImpl);
+            return hits.map(h => ({
+                name: h.name, description: h.description, source: 'npm',
+                npmPackage: h.name, homepage: h.homepage,
+            })).slice(0, n);
         }
         catch (e) {
             this.log?.(`[mcp] npm search failed: ${e?.message || e}`);

package/packages/kernel/dist/workspace/npm-search.d.ts

@@ -0,0 +1,9 @@
+export interface NpmPackageHit {
+    name: string;
+    description: string | null;
+    homepage: string | null;
+    author: string | null;
+    version: string | null;
+}
+/** Query registry.npmjs.org's search endpoint. [] on non-OK; throws on network failure. */
+export declare function searchNpmPackages(text: string, size: number, fetchImpl: typeof fetch): Promise<NpmPackageHit[]>;

package/packages/kernel/dist/workspace/npm-search.js

@@ -0,0 +1,21 @@
+// Shared npm-registry search used by SkillsManager.search and McpRegistry's npm fallback.
+// Workspace-internal — not exported by any barrel.
+/** Query registry.npmjs.org's search endpoint. [] on non-OK; throws on network failure. */
+export async function searchNpmPackages(text, size, fetchImpl) {
+    const url = `https://registry.npmjs.org/-/v1/search?text=${encodeURIComponent(text)}&size=${size}`;
+    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,
+            homepage: pkg.links?.homepage ?? pkg.links?.npm ?? null,
+            author: pkg.publisher?.username ?? pkg.author?.name ?? null,
+            version: pkg.version ?? null,
+        };
+    }).filter(h => h.name);
+}

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

@@ -16,6 +16,7 @@ export interface ManagedSessionInfo {
     source: SessionSource;
     createdAt: string | null;
     updatedAt: string | null;
+    messageCount?: number | null;
 }
 export interface ListSessionsOptions {
     /**
@@ -28,6 +29,8 @@ export interface ListSessionsOptions {
     agent?: string;
     includeNative?: boolean;
     limit?: number;
+    /** Skip this many of the most-recent rows before taking `limit` — for paginated "load more". */
+    offset?: number;
 }
 export interface SearchSessionsOptions extends ListSessionsOptions {
     query: string;

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

@@ -1,8 +1,5 @@
 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) };
-}
+import { makeSessionKey, splitSessionKey } from '../protocol/index.js';
 function ts(iso) {
     if (!iso)
         return 0;
@@ -14,7 +11,7 @@ function newer(a, b) {
 }
 function managedToInfo(agent, rec) {
     return {
-        sessionKey: `${agent}:${rec.sessionId}`,
+        sessionKey: makeSessionKey(agent, rec.sessionId),
         agent,
         sessionId: rec.sessionId,
         title: rec.title ?? null,
@@ -27,23 +24,25 @@ function managedToInfo(agent, rec) {
         source: 'managed',
         createdAt: rec.createdAt ?? null,
         updatedAt: rec.updatedAt ?? null,
+        messageCount: null, // managed records don't track a turn count; native rows carry the head-approx one
     };
 }
 function nativeToInfo(agent, n) {
     return {
-        sessionKey: `${agent}:${n.sessionId}`,
+        sessionKey: makeSessionKey(agent, n.sessionId),
         agent,
         sessionId: n.sessionId,
         title: n.title,
         preview: n.preview,
         workdir: n.cwd,
         model: n.model,
-        effort: null,
+        effort: n.effort ?? null,
         runState: n.running ? 'running' : 'completed',
         running: n.running,
         source: 'native',
         createdAt: n.createdAt,
         updatedAt: n.updatedAt,
+        messageCount: n.messageCount ?? null,
     };
 }
 export class SessionsManager {
@@ -58,6 +57,15 @@ export class SessionsManager {
         const drivers = this.deps.drivers();
         const agentIds = opts.agent ? [opts.agent] : [...drivers.keys()];
         const byKey = new Map();
+        // Native discovery must surface enough of the newest rows to satisfy offset+limit paging, since
+        // the final page is sliced AFTER merging managed + native. `undefined` limit = discover all.
+        const offset = Math.max(0, opts.offset ?? 0);
+        const nativeLimit = typeof opts.limit === 'number' ? offset + opts.limit : undefined;
+        // Native session keys a managed record already represents because the agent minted a DIVERGENT
+        // transcript id (rec.sessionId ≠ rec.nativeSessionId — the new-chat case). Those native rows are
+        // dropped below so they don't double up with their managed row. Deduping HERE (before paging) keeps
+        // page sizes and "has more" correct — doing it in a host wrapper after slicing shrinks pages.
+        const coveredNativeKeys = new Set();
         // Managed sessions (the kernel's own store).
         for (const agent of agentIds) {
             let records = [];
@@ -68,11 +76,14 @@ export class SessionsManager {
                 this.deps.log?.(`[sessions] store.list(${agent}) failed: ${e?.message || e}`);
             }
             for (const rec of records) {
+                if (rec.nativeSessionId && rec.nativeSessionId !== rec.sessionId) {
+                    coveredNativeKeys.add(makeSessionKey(agent, rec.nativeSessionId));
+                }
                 if (scope === 'workspace') {
                     if (!rec.workdir || path.resolve(rec.workdir) !== workdir)
                         continue;
                 }
-                byKey.set(`${agent}:${rec.sessionId}`, managedToInfo(agent, rec));
+                byKey.set(makeSessionKey(agent, rec.sessionId), managedToInfo(agent, rec));
             }
         }
         // Native sessions (the agents' own stores) — inherently per-workdir.
@@ -83,13 +94,15 @@ export class SessionsManager {
                     continue;
                 let natives = [];
                 try {
-                    natives = await driver.listNativeSessions({ workdir, limit: opts.limit });
+                    natives = await driver.listNativeSessions({ workdir, limit: nativeLimit });
                 }
                 catch (e) {
                     this.deps.log?.(`[sessions] ${agent}.listNativeSessions failed: ${e?.message || e}`);
                 }
                 for (const n of natives) {
-                    const key = `${agent}:${n.sessionId}`;
+                    const key = makeSessionKey(agent, n.sessionId);
+                    if (coveredNativeKeys.has(key))
+                        continue; // a managed record already represents this transcript
                     const existing = byKey.get(key);
                     if (existing) {
                         // Same identity discovered both ways: managed record wins, but adopt the newer
@@ -107,18 +120,19 @@ export class SessionsManager {
             }
         }
         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;
+        return typeof opts.limit === 'number' ? out.slice(offset, offset + opts.limit) : offset ? out.slice(offset) : out;
     }
     async search(opts) {
         const q = (opts.query || '').trim().toLowerCase();
-        const all = await this.list({ ...opts, limit: undefined });
+        const all = await this.list({ ...opts, limit: undefined, offset: 0 });
         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;
+        const offset = Math.max(0, opts.offset ?? 0);
+        return typeof opts.limit === 'number' ? matched.slice(offset, offset + opts.limit) : offset ? matched.slice(offset) : matched;
     }
     async get(sessionKey, opts = {}) {
-        const { agent, sessionId } = splitKey(sessionKey);
+        const { agent, sessionId } = splitSessionKey(sessionKey);
         if (!agent)
             return null;
         const rec = await this.deps.store.get(agent, sessionId).catch(() => null);

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

@@ -21,6 +21,17 @@ export interface SkillsManagerOptions {
     agentSkillDirs?: string[];
     log?: (msg: string) => void;
 }
+export interface SkillMeta {
+    label: string | null;
+    description: string | null;
+    mcpRequires?: string[];
+}
+/**
+ * Parse a SKILL.md's frontmatter (label/name + description + mcp_requires), falling back
+ * to the first `# heading` for the label. Exported so an app scanning additional skill
+ * stores (e.g. an agent's own ~/.claude/skills) reads them with the same rules.
+ */
+export declare function parseSkillMeta(content: string): SkillMeta;
 /** 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 {

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

@@ -1,13 +1,20 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { searchNpmPackages } from './npm-search.js';
 const DEFAULT_AGENT_SKILL_DIRS = ['.claude/skills', '.agents/skills'];
-function parseSkillMeta(content) {
+/**
+ * Parse a SKILL.md's frontmatter (label/name + description + mcp_requires), falling back
+ * to the first `# heading` for the label. Exported so an app scanning additional skill
+ * stores (e.g. an agent's own ~/.claude/skills) reads them with the same rules.
+ */
+export 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);
+        // Both frontmatter dialects: pikiloom's `label:` and the agent-native `name:`.
+        const lm = fm[1].match(/^label:\s*(.+)/m) || fm[1].match(/^name:\s*(.+)/m);
         if (lm)
             label = lm[1].trim();
         const dm = fm[1].match(/^description:\s*(.+)/m);
@@ -145,25 +152,12 @@ export class SkillsManager {
     /** 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);
+            const hits = await searchNpmPackages(`agent skill ${q}`.trim(), Math.max(1, Math.min(50, limit)), fetch);
+            return hits.map(h => ({
+                name: h.name, description: h.description, source: 'npm',
+                author: h.author, homepage: h.homepage, version: h.version,
+            }));
         }
         catch (e) {
             this.log?.(`[skills] search failed: ${e?.message || e}`);