pikiloom 0.4.71 → 0.4.73

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pikiloom",
-  "version": "0.4.71",
+  "version": "0.4.73",
   "description": "Put the world's smartest AI agents in your pocket. Command local Claude & Gemini via IM. | 让最好用的 IM 变成你电脑上的顶级 Agent 控制台",
   "type": "module",
   "bin": {

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

@@ -0,0 +1,36 @@
+/** Mime type when the file is an inlineable image, else null. */
+export declare function imageMimeForFile(filePath: string): string | null;
+/** The text note substituted for a non-image attachment. */
+export declare function attachedFileNote(filePath: string): string;
+/**
+ * Anthropic scales any image whose long edge exceeds 1568px before the model sees it, and —
+ * once a single request carries MORE THAN 20 images — outright REJECTS any image over 2000px
+ * on a side ("dimensions exceed max allowed size for many-image requests"). A long session
+ * full of screenshots easily crosses 20 images, at which point one freshly attached (or
+ * mid-turn steered) full-resolution screenshot gets the whole image stripped from the turn.
+ * Capping the long edge at Anthropic's own downscale threshold loses no detail the model
+ * would have kept and makes the many-image rejection unreachable. Other providers only gain
+ * from smaller uploads.
+ */
+export declare const MAX_IMAGE_EDGE = 1568;
+/**
+ * Pixel dimensions parsed from an image buffer's header (PNG / JPEG / GIF / WebP),
+ * or null when the bytes aren't one of those formats. Header-only: never decodes.
+ */
+export declare function imageDimensions(buf: Buffer): {
+    width: number;
+    height: number;
+} | null;
+type Resizer = 'sips' | 'magick' | 'convert' | 'none';
+/** Test seam: force re-probing (and optionally stub) the resize engine. */
+export declare function resetResizerForTest(value?: Resizer | null): void;
+/**
+ * Swap oversized raster images (long edge > {@link MAX_IMAGE_EDGE}) for downscaled temp
+ * copies, leaving everything else — small images, non-images, unreadable paths, animated
+ * gifs — untouched. Best-effort by design: any probe/resize failure keeps the original, so
+ * an attachment is never dropped; the worst case is the pre-existing behaviour. Called once
+ * per dispatch at the Hub chokepoints (turn start + mid-turn steer), so every driver —
+ * built-in or host-plugged — sends model-safe images.
+ */
+export declare function normalizeImageAttachments(attachments: string[] | undefined, log?: (msg: string) => void): Promise<string[] | undefined>;
+export {};

package/packages/kernel/dist/attachments.js

@@ -0,0 +1,162 @@
+import { execFile } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path, { extname } from 'node:path';
+// Attachment vocabulary + normalization, shared by the runtime (Hub) and every driver.
+// NOT part of the public API — nothing here is re-exported by any barrel.
+// Every driver inlines the same image formats (the Anthropic vision set, which the
+// others accept too) and notes non-image files the same way.
+const IMAGE_MIME_BY_EXT = {
+    '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif', '.webp': 'image/webp',
+};
+/** Mime type when the file is an inlineable image, else null. */
+export function imageMimeForFile(filePath) {
+    return IMAGE_MIME_BY_EXT[extname(filePath).toLowerCase()] ?? null;
+}
+/** The text note substituted for a non-image attachment. */
+export function attachedFileNote(filePath) {
+    return `[Attached file: ${filePath}]`;
+}
+/**
+ * Anthropic scales any image whose long edge exceeds 1568px before the model sees it, and —
+ * once a single request carries MORE THAN 20 images — outright REJECTS any image over 2000px
+ * on a side ("dimensions exceed max allowed size for many-image requests"). A long session
+ * full of screenshots easily crosses 20 images, at which point one freshly attached (or
+ * mid-turn steered) full-resolution screenshot gets the whole image stripped from the turn.
+ * Capping the long edge at Anthropic's own downscale threshold loses no detail the model
+ * would have kept and makes the many-image rejection unreachable. Other providers only gain
+ * from smaller uploads.
+ */
+export const MAX_IMAGE_EDGE = 1568;
+/**
+ * Pixel dimensions parsed from an image buffer's header (PNG / JPEG / GIF / WebP),
+ * or null when the bytes aren't one of those formats. Header-only: never decodes.
+ */
+export function imageDimensions(buf) {
+    if (buf.length >= 24 && buf.subarray(0, 8).equals(Buffer.from('89504e470d0a1a0a', 'hex'))) {
+        return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
+    }
+    if (buf.length >= 10 && (buf.subarray(0, 6).toString('latin1') === 'GIF87a' || buf.subarray(0, 6).toString('latin1') === 'GIF89a')) {
+        return { width: buf.readUInt16LE(6), height: buf.readUInt16LE(8) };
+    }
+    if (buf.length >= 4 && buf[0] === 0xff && buf[1] === 0xd8) {
+        // JPEG: walk segments to the first SOF (skips arbitrarily large EXIF/APPn blocks).
+        let i = 2;
+        while (i + 9 < buf.length) {
+            if (buf[i] !== 0xff) {
+                i++;
+                continue;
+            }
+            const marker = buf[i + 1];
+            if (marker === 0xff) {
+                i++;
+                continue;
+            } // fill byte
+            if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+                return { width: buf.readUInt16BE(i + 7), height: buf.readUInt16BE(i + 5) };
+            }
+            if (marker === 0xd8 || (marker >= 0xd0 && marker <= 0xd9)) {
+                i += 2;
+                continue;
+            } // standalone
+            i += 2 + buf.readUInt16BE(i + 2);
+        }
+        return null;
+    }
+    if (buf.length >= 30 && buf.subarray(0, 4).toString('latin1') === 'RIFF' && buf.subarray(8, 12).toString('latin1') === 'WEBP') {
+        const chunk = buf.subarray(12, 16).toString('latin1');
+        if (chunk === 'VP8X')
+            return { width: 1 + buf.readUIntLE(24, 3), height: 1 + buf.readUIntLE(27, 3) };
+        if (chunk === 'VP8L')
+            return { width: 1 + (buf.readUInt32LE(21) & 0x3fff), height: 1 + ((buf.readUInt32LE(21) >> 14) & 0x3fff) };
+        if (chunk === 'VP8 ')
+            return { width: buf.readUInt16LE(26) & 0x3fff, height: buf.readUInt16LE(28) & 0x3fff };
+    }
+    return null;
+}
+let resizerCache = null;
+function run(cmd, args) {
+    return new Promise((resolve, reject) => {
+        execFile(cmd, args, { timeout: 10_000 }, (err) => (err ? reject(err) : resolve()));
+    });
+}
+function detectResizer() {
+    if (resizerCache)
+        return resizerCache;
+    if (process.platform === 'darwin')
+        return (resizerCache = 'sips');
+    resizerCache = (async () => {
+        for (const cmd of ['magick', 'convert']) {
+            try {
+                await run(cmd, ['-version']);
+                return (resizerCache = cmd);
+            }
+            catch { /* try next */ }
+        }
+        return (resizerCache = 'none');
+    })();
+    return resizerCache;
+}
+/** Test seam: force re-probing (and optionally stub) the resize engine. */
+export function resetResizerForTest(value = null) {
+    resizerCache = value;
+}
+// Downscale `src` so its long edge is `maxEdge`, into a fresh temp file; null = keep the
+// original (no engine, or the engine failed/produced nothing). WebP output support varies
+// by sips version, so webp is re-encoded as PNG — the extension switch keeps the drivers'
+// mime mapping truthful.
+async function resizeToTemp(src, maxEdge) {
+    const resizer = await detectResizer();
+    if (resizer === 'none')
+        return null;
+    const srcExt = extname(src).toLowerCase();
+    const outExt = srcExt === '.webp' ? '.png' : srcExt;
+    const out = path.join(os.tmpdir(), `pikiloom-att-${randomUUID().slice(0, 8)}${outExt}`);
+    try {
+        if (resizer === 'sips') {
+            const format = srcExt === '.webp' ? ['-s', 'format', 'png'] : [];
+            await run('sips', [...format, '-Z', String(maxEdge), src, '--out', out]);
+        }
+        else {
+            await run(resizer, [src, '-resize', `${maxEdge}x${maxEdge}>`, out]);
+        }
+        return fs.statSync(out).size > 0 ? out : null;
+    }
+    catch {
+        fs.rmSync(out, { force: true });
+        return null;
+    }
+}
+/**
+ * Swap oversized raster images (long edge > {@link MAX_IMAGE_EDGE}) for downscaled temp
+ * copies, leaving everything else — small images, non-images, unreadable paths, animated
+ * gifs — untouched. Best-effort by design: any probe/resize failure keeps the original, so
+ * an attachment is never dropped; the worst case is the pre-existing behaviour. Called once
+ * per dispatch at the Hub chokepoints (turn start + mid-turn steer), so every driver —
+ * built-in or host-plugged — sends model-safe images.
+ */
+export async function normalizeImageAttachments(attachments, log) {
+    if (!attachments?.length)
+        return attachments;
+    const out = [...attachments];
+    for (let i = 0; i < out.length; i++) {
+        const file = out[i];
+        const mime = imageMimeForFile(file);
+        if (!mime || mime === 'image/gif')
+            continue; // gif: resizing would mangle animation
+        try {
+            const dims = imageDimensions(fs.readFileSync(file));
+            if (!dims || Math.max(dims.width, dims.height) <= MAX_IMAGE_EDGE)
+                continue;
+            const resized = await resizeToTemp(file, MAX_IMAGE_EDGE);
+            if (resized) {
+                out[i] = resized;
+                log?.(`[attachments] downscaled ${path.basename(file)} ${dims.width}x${dims.height} -> long edge ${MAX_IMAGE_EDGE}`);
+            }
+        }
+        catch { /* unreadable — the drivers' own fallback (file note) handles it */ }
+    }
+    return out;
+}

package/packages/kernel/dist/contracts/driver.d.ts

@@ -6,6 +6,9 @@ export interface AgentTurnInput {
     fork?: {
         anchor?: string | null;
     } | null;
+    rewind?: {
+        anchor?: string | null;
+    } | null;
     workdir: string;
     model?: string | null;
     effort?: string | null;
@@ -55,6 +58,10 @@ export type DriverEvent = {
 } | {
     type: 'activity';
     line: string;
+} | {
+    type: 'compaction';
+    trigger: 'auto' | 'manual';
+    atTokens?: number | null;
 };
 export type SteerFn = (prompt: string, attachments?: string[]) => Promise<boolean>;
 export interface DriverContext {
@@ -72,6 +79,7 @@ export interface DriverResult {
     sessionId?: string | null;
     usage?: UniversalUsage | null;
     anchor?: string | null;
+    transport?: 'cold' | 'warm' | null;
 }
 export interface TuiInput {
     workdir: string;
@@ -106,6 +114,7 @@ export interface AgentDriver {
         resume?: boolean;
         tui?: boolean;
         fork?: boolean;
+        rewind?: boolean;
     };
     run(input: AgentTurnInput, ctx: DriverContext): Promise<DriverResult>;
     tui?(input: TuiInput): TuiSpec;

package/packages/kernel/dist/contracts/ports.d.ts

@@ -25,6 +25,9 @@ export interface CoreSessionRecord {
         anchor: string | null;
         mode: 'native' | 'seed';
     } | null;
+    pendingRewind?: {
+        anchor: string | null;
+    } | null;
 }
 export interface SessionStore {
     ensure(agent: string, opts: {
@@ -48,6 +51,7 @@ export interface SessionStore {
     reconcileRunning?(isAlive: (pid: number) => boolean): Promise<number>;
     appendTurn?(agent: string, sessionId: string, turn: UniversalSnapshot): Promise<void>;
     history?(agent: string, sessionId: string): Promise<UniversalSnapshot[]>;
+    truncateTurns?(agent: string, sessionId: string, throughTaskId: string | null): Promise<void>;
 }
 export interface ModelInjection {
     model?: string | null;

package/packages/kernel/dist/contracts/surface.d.ts

@@ -23,6 +23,13 @@ export interface LoomIO {
     forkSession(input: ForkSessionInput): Promise<{
         sessionKey: string;
     }>;
+    rewindSession(input: {
+        sessionKey: string;
+        atTaskId: string;
+        anchor?: string | null;
+    }): Promise<{
+        sessionKey: string;
+    }>;
     stop(sessionKey: string): boolean;
     steer(taskId: string, prompt: string, attachments?: string[]): Promise<boolean>;
     interact(promptId: string, action: 'select' | 'text' | 'skip' | 'cancel', value?: string): boolean;

package/packages/kernel/dist/drivers/claude-pool.d.ts

@@ -0,0 +1,20 @@
+import type { ChildProcess } from 'node:child_process';
+export declare function claudeWarmIdleTtlMs(): number;
+export declare function claudeWarmMaxProcesses(): number;
+export declare class ClaudeWarmPool {
+    private readonly parked;
+    size(): number;
+    /**
+     * Reclaim the parked process for `sessionId`, or null when there is none, it died while
+     * parked, or its spawn fingerprint no longer matches (that entry is destroyed — the turn
+     * must go cold so the new model/effort/config actually applies).
+     */
+    take(sessionId: string, fingerprint: string): ChildProcess | null;
+    /** Park a process after a clean settle. The caller has already detached its turn listeners. */
+    put(sessionId: string, fingerprint: string, child: ChildProcess): void;
+    /** Destroy the parked process for a session (rewind made its in-memory context stale, TTL, cap). */
+    evictSession(sessionId: string): void;
+    dispose(): void;
+    /** Remove bookkeeping without deciding the child's fate. */
+    private unpark;
+}

package/packages/kernel/dist/drivers/claude-pool.js

@@ -0,0 +1,125 @@
+import { sigterm } from './shared.js';
+// ── Warm Claude process pool ─────────────────────────────────────────────────────────
+// A `claude -p --input-format stream-json` process stays alive after `result` for as long
+// as its stdin is open, and a user message written to that stdin runs a NEW turn in the
+// same conversation (the steer path has always relied on this). Every cold spawn costs
+// ~4s of CLI init before the first model request — the single largest local overhead of a
+// Claude turn — so after a clean settle the driver parks the process here instead of
+// killing it, and the session's next continuation turn skips the spawn entirely.
+//
+// Discipline (mirrors mirasim's Codex warm pool):
+//  - keyed by native session id; one process per session, serial turns only.
+//  - a process is reused only when its spawn-time fingerprint (model/effort/workdir/…)
+//    still matches what a cold spawn would use; any drift destroys it and goes cold.
+//  - idle processes are destroyed after a TTL; the pool is size-capped (oldest-idle out).
+//  - only CLEAN settles pool (no error / abort / timeout / background hold); everything
+//    else keeps today's kill semantics, so pooling can never leak a wedged process.
+// Idle TTL before a parked process is destroyed. Override with PIKILOOM_CLAUDE_WARM_IDLE_MS.
+const CLAUDE_WARM_IDLE_TTL_DEFAULT_MS = 10 * 60_000;
+export function claudeWarmIdleTtlMs() {
+    const raw = Number(process.env.PIKILOOM_CLAUDE_WARM_IDLE_MS);
+    return Number.isFinite(raw) && raw > 0 ? raw : CLAUDE_WARM_IDLE_TTL_DEFAULT_MS;
+}
+// Max parked processes (each holds a full CLI + its MCP servers — roughly 0.5–1 GB).
+// Override with PIKILOOM_CLAUDE_WARM_MAX.
+const CLAUDE_WARM_MAX_DEFAULT = 4;
+export function claudeWarmMaxProcesses() {
+    const raw = Number(process.env.PIKILOOM_CLAUDE_WARM_MAX);
+    return Number.isFinite(raw) && raw >= 0 ? Math.floor(raw) : CLAUDE_WARM_MAX_DEFAULT;
+}
+// After ending a parked process's stdin, force-kill only if it hasn't exited on its own
+// within this window — same leak-guard shape as a graceful turn settle.
+const CLAUDE_WARM_DESTROY_GUARD_MS = 15_000;
+/** End a no-longer-poolable process the same way a graceful settle does. */
+function destroyClaudeChild(child) {
+    try {
+        child.stdin?.end();
+    }
+    catch { /* ignore */ }
+    if (child.exitCode != null || child.killed)
+        return;
+    const guard = setTimeout(() => sigterm(child), CLAUDE_WARM_DESTROY_GUARD_MS);
+    if (typeof guard.unref === 'function')
+        guard.unref();
+}
+export class ClaudeWarmPool {
+    parked = new Map();
+    size() {
+        return this.parked.size;
+    }
+    /**
+     * Reclaim the parked process for `sessionId`, or null when there is none, it died while
+     * parked, or its spawn fingerprint no longer matches (that entry is destroyed — the turn
+     * must go cold so the new model/effort/config actually applies).
+     */
+    take(sessionId, fingerprint) {
+        const entry = this.parked.get(sessionId);
+        if (!entry)
+            return null;
+        this.unpark(sessionId, entry);
+        if (entry.child.exitCode != null || entry.child.killed)
+            return null;
+        if (entry.fingerprint !== fingerprint) {
+            destroyClaudeChild(entry.child);
+            return null;
+        }
+        return entry.child;
+    }
+    /** Park a process after a clean settle. The caller has already detached its turn listeners. */
+    put(sessionId, fingerprint, child) {
+        if (child.exitCode != null || child.killed || !child.stdin || child.stdin.destroyed) {
+            destroyClaudeChild(child);
+            return;
+        }
+        this.evictSession(sessionId); // never two processes for one session
+        while (this.parked.size >= Math.max(claudeWarmMaxProcesses(), 0)) {
+            const oldest = [...this.parked.entries()].sort((a, b) => a[1].parkedAt - b[1].parkedAt)[0];
+            if (!oldest)
+                break;
+            this.evictSession(oldest[0]);
+        }
+        if (claudeWarmMaxProcesses() <= 0) {
+            destroyClaudeChild(child);
+            return;
+        }
+        const onClose = () => {
+            const cur = this.parked.get(sessionId);
+            if (cur?.child === child) {
+                this.unpark(sessionId, cur);
+            }
+        };
+        // Keep both pipes flowing while parked so the CLI can never block on a full pipe.
+        const drain = () => { };
+        child.stdout?.on('data', drain);
+        child.stderr?.on('data', drain);
+        child.on('close', onClose);
+        const idleTimer = setTimeout(() => {
+            const cur = this.parked.get(sessionId);
+            if (cur?.child === child)
+                this.evictSession(sessionId);
+        }, claudeWarmIdleTtlMs());
+        if (typeof idleTimer.unref === 'function')
+            idleTimer.unref();
+        this.parked.set(sessionId, { child, fingerprint, parkedAt: Date.now(), idleTimer, onClose, drain });
+    }
+    /** Destroy the parked process for a session (rewind made its in-memory context stale, TTL, cap). */
+    evictSession(sessionId) {
+        const entry = this.parked.get(sessionId);
+        if (!entry)
+            return;
+        this.unpark(sessionId, entry);
+        destroyClaudeChild(entry.child);
+    }
+    dispose() {
+        for (const sessionId of [...this.parked.keys()])
+            this.evictSession(sessionId);
+    }
+    /** Remove bookkeeping without deciding the child's fate. */
+    unpark(sessionId, entry) {
+        clearTimeout(entry.idleTimer);
+        entry.child.stdout?.off('data', entry.drain);
+        entry.child.stderr?.off('data', entry.drain);
+        entry.child.off('close', entry.onClose);
+        this.parked.delete(sessionId);
+    }
+}

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

@@ -1,5 +1,12 @@
 import type { AgentDriver, AgentTurnInput, DriverContext, DriverResult, DriverEvent, TuiInput, TuiSpec, NativeSessionInfo } from '../contracts/driver.js';
 import type { UniversalPlan } from '../protocol/index.js';
+export interface ClaudeDriverOptions {
+    /** Keep the CLI process alive after a clean turn and reuse it for the session's next
+     *  continuation turn (skips the ~4s spawn+init). Off by default: a parked process holds
+     *  real memory and keeps the event loop alive, which a one-shot embedder must not inherit
+     *  silently. Long-lived hosts opt in and call dispose() on shutdown. */
+    warmPool?: boolean;
+}
 export declare class ClaudeDriver implements AgentDriver {
     private readonly bin;
     readonly id = "claude";
@@ -9,8 +16,14 @@ export declare class ClaudeDriver implements AgentDriver {
         resume: boolean;
         tui: boolean;
         fork: boolean;
+        rewind: boolean;
     };
-    constructor(bin?: string);
+    private readonly pool;
+    constructor(bin?: string, opts?: ClaudeDriverOptions);
+    /** Destroy every parked warm process. Long-lived hosts call this on shutdown. */
+    dispose(): void;
+    /** Parked warm processes right now (tests + telemetry). */
+    warmPoolSize(): number;
     tui(input: TuiInput): TuiSpec;
     listNativeSessions(opts: {
         workdir: string;
@@ -23,8 +36,11 @@ export declare class ClaudeDriver implements AgentDriver {
         workdir: string;
     }): string | null;
 }
+export declare function claudeProcessFingerprint(bin: string, input: AgentTurnInput): string;
 export declare function claudeResumeArgs(sessionId: string, fork?: {
     anchor?: string | null;
+} | null, rewind?: {
+    anchor?: string | null;
 } | null): string[];
 export declare function handleClaudeEvent(ev: any, s: any, emit: (e: DriverEvent) => void): void;
 export declare function claudeBgHoldCapMs(): number;