pikiloop 0.4.0

package/dist/agent/images.js

@@ -0,0 +1,355 @@
+/**
+ * images.ts — unified image pipeline for the agent layer.
+ *
+ * Every driver produces image blocks through `attachAgentImage`, every IM
+ * channel consumes them through `materializeImage`, and every dashboard
+ * response routes large images through the attachment HTTP endpoint via
+ * `rewriteImageBlocksForTransport`. The shape isolates *where the bytes live*
+ * from *how a renderer wants to consume them*, so adding a new driver source
+ * (Codex `image_generation_call`, Claude MCP `tool_result` image, Gemini Imagen,
+ * future) or a new transport (a fourth IM channel, a CLI exporter, an OG-image
+ * preview) doesn't require touching every other site.
+ *
+ * Storage model
+ * -------------
+ *  - Agent-native sources (`~/.codex/generated_images/...`, `~/.claude/...`)
+ *    keep their files in place. The block's `imagePath` is the authoritative
+ *    pointer; the dashboard and channels read directly from there.
+ *  - MCP-bridge-buffered sources (image content embedded in MCP tool results)
+ *    are persisted under the per-session attachments directory (see
+ *    `sessionAttachmentsDir`) so they survive the originating CLI process and
+ *    are reachable by an absolute path.
+ *
+ * Transport model
+ * ---------------
+ *  - `content` always carries a directly-renderable reference: a `data:` URL
+ *    for inline bytes, or an attachment HTTP URL for files on disk.
+ *  - Below `INLINE_THRESHOLD_BYTES`, drivers may inline as `data:`. Above the
+ *    threshold, `rewriteImageBlocksForTransport` substitutes a relative
+ *    `/api/sessions/:agent/:id/attachment?...` URL — keeps RichMessage
+ *    payloads small even when a session has many large images.
+ *  - IM channels prefer `imagePath` over decoding `content`, avoiding wasted
+ *    base64 round-trips.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { getHome } from '../core/platform.js';
+import { agentLog, agentWarn } from './utils.js';
+import { mimeForExt } from './utils.js';
+// ---------------------------------------------------------------------------
+// Constants & policy
+// ---------------------------------------------------------------------------
+/**
+ * Maximum on-disk size we'll read into memory when materializing image bytes.
+ * Larger files are skipped (transport surfaces the `imagePath` reference but
+ * doesn't blast a multi-megabyte buffer through the channel send path).
+ */
+const MAX_IMAGE_BYTES = 16 * 1024 * 1024;
+/**
+ * Below this size we inline the image as a `data:` URL inside the block's
+ * `content`. Larger images travel as on-disk references; the dashboard fetches
+ * them lazily through the attachment HTTP endpoint and IM channels read from
+ * disk via `imagePath`.
+ */
+const INLINE_THRESHOLD_BYTES = 256 * 1024;
+const IMAGE_MIME_PREFIX = 'image/';
+const IMAGE_EXT_BY_MIME = {
+    'image/png': '.png',
+    'image/jpeg': '.jpg',
+    'image/jpg': '.jpg',
+    'image/gif': '.gif',
+    'image/webp': '.webp',
+    'image/svg+xml': '.svg',
+};
+// ---------------------------------------------------------------------------
+// Path helpers
+// ---------------------------------------------------------------------------
+/** `$CODEX_HOME` or fallback `~/.codex`. */
+export function codexHome() {
+    return process.env.CODEX_HOME || path.join(getHome(), '.codex');
+}
+/** Per-session attachments directory used by MCP bridge / tool buffering.
+ *  Lives next to the user's pikiloop config so it survives across workdirs. */
+export function sessionAttachmentsDir(agent, sessionId) {
+    return path.join(getHome(), '.pikiloop', 'attachments', agent, sessionId);
+}
+/**
+ * Path roots that the dashboard attachment endpoint is allowed to serve.
+ * Every entry is real-resolved at request time; a candidate file must live
+ * inside one of them (post-realpath) to be served.
+ *
+ *  - `~/.codex/generated_images` — Codex built-in `image_gen` outputs.
+ *  - `~/.codex/sessions`         — rollout-adjacent assets (rare but legal).
+ *  - `~/.claude/projects`        — Claude attached images written to JSONL.
+ *  - `~/.gemini`                 — Gemini CLI managed dirs.
+ *  - `~/.pikiloop/attachments`   — MCP-bridge-buffered tool result images.
+ *  - workspace tree(s)           — files generated under the project workdir.
+ *  - OS tmpdir                   — short-lived staging by drivers / skills.
+ *
+ * `workdir` accepts a list because a multi-workspace setup serves sessions
+ * from several project trees through one endpoint — every entry must come
+ * from server-side config (registered workspaces / managed session records),
+ * never from request input.
+ */
+export function allowedAttachmentRoots(workdir) {
+    const home = getHome();
+    const roots = [
+        path.join(codexHome(), 'generated_images'),
+        path.join(codexHome(), 'sessions'),
+        path.join(home, '.claude', 'projects'),
+        path.join(home, '.gemini'),
+        path.join(home, '.pikiloop', 'attachments'),
+        os.tmpdir(),
+    ];
+    const workdirs = typeof workdir === 'string' ? [workdir] : (workdir ?? []);
+    for (const wd of workdirs) {
+        if (wd && wd.trim())
+            roots.push(path.resolve(wd));
+    }
+    return roots;
+}
+/**
+ * Verify a resolved file path lives under one of the allowed roots, defending
+ * against `..` traversal AND symlinks that escape the allowlist. Returns the
+ * realpath when the file is allowed, or null when not.
+ */
+export function resolveAllowedAttachmentPath(requested, workdir) {
+    if (!requested)
+        return null;
+    let real;
+    try {
+        real = fs.realpathSync(requested);
+    }
+    catch {
+        return null;
+    }
+    for (const root of allowedAttachmentRoots(workdir)) {
+        let realRoot;
+        try {
+            realRoot = fs.realpathSync(root);
+        }
+        catch {
+            continue;
+        }
+        const rel = path.relative(realRoot, real);
+        if (rel && !rel.startsWith('..') && !path.isAbsolute(rel))
+            return real;
+        if (rel === '')
+            return real;
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// MIME helpers
+// ---------------------------------------------------------------------------
+function mimeFromPath(filePath) {
+    return mimeForExt(path.extname(filePath).toLowerCase());
+}
+function extFromMime(mime) {
+    return IMAGE_EXT_BY_MIME[mime.toLowerCase()] || '.bin';
+}
+function isImageMime(mime) {
+    return mime.toLowerCase().startsWith(IMAGE_MIME_PREFIX);
+}
+/**
+ * Build a `MessageBlock` of type `image` from an on-disk file produced by an
+ * agent (Codex built-in `image_gen`, MCP tool buffered to attachments dir, …).
+ * Returns null when the file is missing or unreadable — drivers should treat
+ * that as a soft failure and continue without the block.
+ */
+export function attachAgentImage(opts) {
+    const abs = path.resolve(opts.imagePath);
+    let stat;
+    try {
+        stat = fs.statSync(abs);
+    }
+    catch (err) {
+        agentLog(`[images] attachAgentImage: stat failed for ${abs}: ${err?.message || err}`);
+        return null;
+    }
+    if (!stat.isFile())
+        return null;
+    if (stat.size > MAX_IMAGE_BYTES) {
+        agentWarn(`[images] attachAgentImage: ${abs} too large (${stat.size} bytes > ${MAX_IMAGE_BYTES})`);
+        return null;
+    }
+    const mime = (opts.mime || mimeFromPath(abs)).toLowerCase();
+    if (!isImageMime(mime))
+        return null;
+    const threshold = opts.inlineThresholdBytes ?? INLINE_THRESHOLD_BYTES;
+    let content;
+    if (stat.size <= threshold) {
+        let bytes;
+        try {
+            bytes = fs.readFileSync(abs);
+        }
+        catch (err) {
+            agentLog(`[images] attachAgentImage: read failed for ${abs}: ${err?.message || err}`);
+            return null;
+        }
+        content = `data:${mime};base64,${bytes.toString('base64')}`;
+    }
+    else {
+        // Sentinel: the transport layer rewrites this into an HTTP URL with the
+        // right session context. Renderers that bypass `rewriteImageBlocksForTransport`
+        // see a `file://` URL and can still resolve it via `materializeImage` since
+        // `imagePath` is also populated.
+        content = `file://${abs}`;
+    }
+    const block = {
+        type: 'image',
+        content,
+        imagePath: abs,
+        imageMime: mime,
+    };
+    if (opts.caption?.trim())
+        block.imageCaption = opts.caption.trim();
+    if (opts.phase)
+        block.phase = opts.phase;
+    return block;
+}
+/**
+ * Build an image MessageBlock from an in-memory byte buffer. When `persist`
+ * is supplied, the bytes are also written to the session's attachments dir
+ * and the resulting path attached as `imagePath` — this is the path the MCP
+ * bridge uses when a tool returns an image (so downstream IM channels and the
+ * dashboard attachment endpoint can serve it without re-encoding).
+ */
+export function attachInlineImage(opts) {
+    if (!opts.bytes?.length)
+        return null;
+    const mime = opts.mime.toLowerCase();
+    if (!isImageMime(mime))
+        return null;
+    if (opts.bytes.length > MAX_IMAGE_BYTES) {
+        agentWarn(`[images] attachInlineImage: ${opts.bytes.length} bytes > ${MAX_IMAGE_BYTES}`);
+        return null;
+    }
+    let imagePath;
+    if (opts.persist) {
+        const dir = sessionAttachmentsDir(opts.persist.agent, opts.persist.sessionId);
+        try {
+            fs.mkdirSync(dir, { recursive: true });
+            const stamp = Date.now().toString(36) + Math.random().toString(36).slice(2, 8);
+            const hint = (opts.persist.hint || 'image').replace(/[^a-zA-Z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'image';
+            const candidate = path.join(dir, `${hint}-${stamp}${extFromMime(mime)}`);
+            fs.writeFileSync(candidate, opts.bytes);
+            imagePath = candidate;
+        }
+        catch (err) {
+            agentLog(`[images] attachInlineImage: persist failed: ${err?.message || err}`);
+        }
+    }
+    const threshold = opts.inlineThresholdBytes ?? INLINE_THRESHOLD_BYTES;
+    const content = opts.bytes.length <= threshold || !imagePath
+        ? `data:${mime};base64,${opts.bytes.toString('base64')}`
+        : `file://${imagePath}`;
+    const block = { type: 'image', content, imageMime: mime };
+    if (imagePath)
+        block.imagePath = imagePath;
+    if (opts.caption?.trim())
+        block.imageCaption = opts.caption.trim();
+    if (opts.phase)
+        block.phase = opts.phase;
+    return block;
+}
+/**
+ * Resolve an image block to raw bytes for transport (IM channel image send,
+ * export bundling, …). Preference order:
+ *   1. `imagePath` — read straight from disk, no base64 decode.
+ *   2. `content` is `data:image/...;base64,...` — decode the URL.
+ *   3. `content` is `file://...` — read that path from disk.
+ *   4. otherwise — return null.
+ */
+export function materializeImage(block) {
+    if (block.type !== 'image')
+        return null;
+    const caption = block.imageCaption?.trim() || undefined;
+    if (block.imagePath) {
+        try {
+            const stat = fs.statSync(block.imagePath);
+            if (stat.isFile() && stat.size <= MAX_IMAGE_BYTES) {
+                const bytes = fs.readFileSync(block.imagePath);
+                const mime = (block.imageMime || mimeFromPath(block.imagePath)).toLowerCase();
+                return { bytes, mime, caption };
+            }
+        }
+        catch { /* fall through to content */ }
+    }
+    const content = block.content || '';
+    if (content.startsWith('data:')) {
+        const m = /^data:([^;,]+);base64,(.+)$/i.exec(content);
+        if (!m)
+            return null;
+        const mime = m[1].toLowerCase();
+        try {
+            const bytes = Buffer.from(m[2], 'base64');
+            if (bytes.length > MAX_IMAGE_BYTES)
+                return null;
+            return { bytes, mime, caption };
+        }
+        catch {
+            return null;
+        }
+    }
+    if (content.startsWith('file://')) {
+        const filePath = content.slice('file://'.length);
+        try {
+            const stat = fs.statSync(filePath);
+            if (!stat.isFile() || stat.size > MAX_IMAGE_BYTES)
+                return null;
+            const bytes = fs.readFileSync(filePath);
+            const mime = (block.imageMime || mimeFromPath(filePath)).toLowerCase();
+            return { bytes, mime, caption };
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+function encodePathForUrl(value) {
+    // base64url makes the path opaque in URLs (no `?`, `#`, `/` collisions) and
+    // round-trips losslessly back to the original absolute path.
+    return Buffer.from(value, 'utf-8').toString('base64')
+        .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '');
+}
+export function decodeAttachmentPathParam(value) {
+    const padded = value + '='.repeat((4 - (value.length % 4)) % 4);
+    const normalized = padded.replace(/-/g, '+').replace(/_/g, '/');
+    return Buffer.from(normalized, 'base64').toString('utf-8');
+}
+/**
+ * Rewrite a block array for transport: any image block whose `content` is a
+ * `file://` sentinel becomes an attachment HTTP URL, and any inline `data:`
+ * URL above the threshold is also promoted to an HTTP URL (keeping the
+ * RichMessage payload compact even when a session has many large images).
+ *
+ * Pure: returns a new array; the input is not mutated.
+ */
+export function rewriteImageBlocksForTransport(blocks, ctx) {
+    const base = (ctx.apiBase || '/api/sessions').replace(/\/+$/, '');
+    return blocks.map(block => {
+        if (block.type !== 'image')
+            return block;
+        const sourcePath = block.imagePath
+            || (block.content?.startsWith('file://') ? block.content.slice('file://'.length) : '');
+        if (!sourcePath)
+            return block;
+        // Inline content under the threshold: leave the data URL alone — the
+        // dashboard renders it directly, no extra request.
+        if (block.content?.startsWith('data:'))
+            return block;
+        const encoded = encodePathForUrl(sourcePath);
+        const url = `${base}/${encodeURIComponent(ctx.agent)}/${encodeURIComponent(ctx.sessionId)}/attachment?p=${encoded}`;
+        return { ...block, content: url, imagePath: sourcePath };
+    });
+}
+// ---------------------------------------------------------------------------
+// Constants exported for tests
+// ---------------------------------------------------------------------------
+export const _IMAGE_PIPELINE_INTERNALS = {
+    MAX_IMAGE_BYTES,
+    INLINE_THRESHOLD_BYTES,
+};

package/dist/agent/index.js

@@ -0,0 +1,50 @@
+/**
+ * agent/index.ts — Barrel export for the agent layer.
+ *
+ * This module loads all agent drivers (side-effect) and re-exports the public
+ * API from focused sub-modules:
+ *
+ *   types.ts    — Shared type definitions (StreamOpts, StreamResult, SessionInfo, …)
+ *   utils.ts    — Pure utility functions (Q, agentLog, normalizeErrorMessage, …)
+ *   session.ts  — Session workspace management, metadata, classification, export/import
+ *   stream.ts   — CLI spawn framework, stream orchestration, agent detection, delegation
+ *   driver.ts   — AgentDriver interface and registry
+ *   skills.ts   — Project skill discovery
+ *   drivers/    — Per-agent driver implementations (claude, codex, gemini)
+ */
+// ── Load all drivers (side-effect: each calls registerDriver) ───────────────
+import './drivers/claude.js';
+import './drivers/codex.js';
+import './drivers/gemini.js';
+import './drivers/hermes.js';
+export { IMAGE_EXTS } from './types.js';
+// ── Re-export: image pipeline ──────────────────────────────────────────────
+export { attachAgentImage, attachInlineImage, materializeImage, rewriteImageBlocksForTransport, resolveAllowedAttachmentPath, allowedAttachmentRoots, decodeAttachmentPathParam, sessionAttachmentsDir, codexHome, } from './images.js';
+// ── Re-export: utilities ────────────────────────────────────────────────────
+export { Q, agentLog, agentWarn, agentError, dedupeStrings, numberOrNull, normalizeStreamPreviewPlan, parseTodoWriteAsPlan, normalizeActivityLine, pushRecentActivity, detectClaudeApiError, isRetryableClaudeApiError, detectClaudeModelError, claudeModelErrorMessage, firstNonEmptyLine, shortValue, normalizeErrorMessage, joinErrorMessages, appendSystemPrompt, mimeForExt, computeContext, buildStreamPreviewMeta, summarizeClaudeToolUse, summarizeClaudeToolResult, previewToolCallInput, previewToolCallResult, roundPercent, toIsoFromEpochSeconds, normalizeUsageStatus, labelFromWindowMinutes, usageWindowFromRateLimit, parseJsonTail, modelFamily, normalizeClaudeModelId, emptyUsage, readTailLines, stripInjectedPrompts, sanitizeSessionUserPreviewText, SESSION_PREVIEW_IMAGE_PLACEHOLDER_RE, CLAUDE_AT_MENTION_IMAGE_RE, extractClaudeAtMentionImagePaths, stripClaudeAtMentionImages, isPendingSessionId, emitSessionIdUpdate, sessionListDisplayTitle, } from './utils.js';
+// ── Re-export: session management ───────────────────────────────────────────
+export { updateSessionMeta, promoteSessionId, recordFork, listPikiloopSessions, findPikiloopSession, getSessionStoredConfig, ensureManagedSession, findManagedThreadSession, stageSessionFiles, mergeManagedAndNativeSessions, getSessions, getSessionTail, getSessionMessages, applyTurnWindow, applyTurnFilter, classifySession, deriveUserStatus, exportSession, importSession, deleteAgentSession, isProcessAlive, isRunningSessionStale, reconcileOrphanedRunningSessions, } from './session.js';
+// ── Re-export: stream & detection ───────────────────────────────────────────
+export { detectAgentBin, listAgents, resolveDefaultAgent, run, doStream, listModels, resolveAgentModels, getUsage, getAgentBoundModelId, setAgentBoundModelId, } from './stream.js';
+// ── Re-export: driver registry ──────────────────────────────────────────────
+export { registerDriver, getDriver, getDriverCapabilities, allDrivers, allDriverIds, hasDriver, shutdownAllDrivers, } from './driver.js';
+// ── Re-export: skills ───────────────────────────────────────────────────────
+export { getProjectSkillPaths, initializeProjectSkills, listSkills, getGlobalSkillsRoot, collapseSkillPrompt, } from './skills.js';
+// ── Re-export: goal (persistent thread objective) ────────────────────────────
+export { readGoal, writeGoal, clearGoal, setGoal, pauseGoal, resumeGoal, completeGoal, accountTurn, bumpContinuationCount, shouldContinueAfterTurn, renderContinuationPrompt, renderBudgetLimitPrompt, sessionGoalPath, DEFAULT_MAX_CONTINUATIONS, } from './goal.js';
+// ── Re-export: native codex goal bridge ──────────────────────────────────────
+export { setCodexGoal, getCodexGoal, clearCodexGoal, pauseCodexGoal, resumeCodexGoal, } from './drivers/codex.js';
+// ── Re-export: native claude goal bridge ─────────────────────────────────────
+export { getClaudeNativeGoal, buildClaudeSetGoalPrompt, buildClaudeClearGoalPrompt, } from './drivers/claude.js';
+// ── Re-export: MCP extensions ───────────────────────────────────────────────
+export { listAllMcpExtensions, addGlobalMcpExtension, removeGlobalMcpExtension, updateGlobalMcpExtension, addWorkspaceMcpExtension, removeWorkspaceMcpExtension, updateWorkspaceMcpExtension, loadGlobalMcpExtensions, loadWorkspaceMcpExtensions, getCatalogItems, getCatalogItem, buildInstalledConfigFromRecommended, checkMcpHealth, getCachedHealth, cacheHealth, } from './mcp/extensions.js';
+export { getRecommendedMcpServers, getRecommendedMcpServer, getRecommendedSkillRepos, searchMcpServers, searchSkills as searchSkillRepos, } from './mcp/registry.js';
+export { getMcpToken, saveMcpToken, deleteMcpToken, hasValidMcpToken, startAuthorization, completeAuthorization, refreshMcpToken, injectOAuthHeaders, } from './mcp/oauth.js';
+export { installSkill, removeSkill, checkSkillUpdates, getGlobalSkillsDir, } from './skill-installer.js';
+// ── Re-export: CLI extensions ───────────────────────────────────────────────
+export { getRecommendedClis, getRecommendedCli, detectCli, getCachedCliStatus, invalidateCliStatus, currentPlatform, getCliCatalog, refreshCliStatus, startCliAuthSession, getAuthSession, cancelAuthSession, applyCliToken, logoutCli, startCliInstallSession, } from './cli/index.js';
+// ── Re-export: driver-specific functions ────────────────────────────────────
+export { doClaudeStream } from './drivers/claude.js';
+export { doCodexStream, buildCodexTurnInput, shutdownCodexServer, getCodexUsageLive } from './drivers/codex.js';
+export { doGeminiStream } from './drivers/gemini.js';
+export { doHermesStream } from './drivers/hermes.js';