kimaki 0.4.82 → 0.4.84

package/dist/hrana-server.js

@@ -2,38 +2,19 @@
 // Backed by the `libsql` npm package (better-sqlite3 API).
 // Binds to the fixed lock port for single-instance enforcement.
 //
-// Serves POST /v2/pipeline (Hrana v2 JSON), GET /v2, and GET /health.
-// The @libsql/client HTTP driver and @prisma/adapter-libsql connect here.
+// Protocol logic is implemented in the `libsqlproxy` package.
+// This file handles: server lifecycle, single-instance enforcement,
+// auth, and kimaki-specific endpoints (/kimaki/wake, /health).
 //
 // Hrana v2 protocol spec ("Hrana over HTTP"):
 //   https://github.com/tursodatabase/libsql/blob/main/docs/HTTP_V2_SPEC.md
-//
-// The protocol exposes stateful streams over HTTP. Each stream corresponds
-// to a SQLite connection. Requests on the same stream are tied together
-// via a "baton" — the server returns a baton in every response, and the
-// client includes it in the next request. Stream-scoped state includes
-// SQL text cached via store_sql (referenced by sql_id in later stmts).
-//
-// Request types implemented:
-//   execute     — run a single SQL statement, return cols/rows/changes
-//   batch       — run multiple steps with conditional execution (ok/not/and/or)
-//   sequence    — split raw SQL by semicolons, execute each (no results)
-//   store_sql   — cache SQL text under a numeric sql_id for the stream
-//   close_sql   — remove a cached sql_id
-//   close       — close the stream (baton becomes null)
-//
-// Value encoding (SQLite → Hrana JSON):
-//   INTEGER → {"type":"integer","value":"42"}  (string, not number)
-//   REAL    → {"type":"float","value":3.14}
-//   TEXT    → {"type":"text","value":"hello"}
-//   BLOB    → {"type":"blob","base64":"..."}
-//   NULL    → {"type":"null"}
 import fs from 'node:fs';
 import http from 'node:http';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import Database from 'libsql';
 import * as errore from 'errore';
+import { createLibsqlHandler, createLibsqlNodeHandler, libsqlExecutor, } from 'libsqlproxy';
 import { createLogger, LogPrefix } from './logger.js';
 import { ServerStartError, FetchError } from './errors.js';
 import { getLockPort } from './config.js';
@@ -132,8 +113,10 @@ export async function startHranaServer({ dbPath, bindAll = false, }) {
     database.exec('PRAGMA journal_mode = WAL');
     database.exec('PRAGMA busy_timeout = 5000');
     db = database;
-    const hranaHandler = createHranaHandler(database);
-    // Combined handler: all control/data routes require the same service auth token.
+    // Create the Hrana handler using libsqlproxy
+    const hranaFetchHandler = createLibsqlHandler(libsqlExecutor(database));
+    const hranaNodeHandler = createLibsqlNodeHandler(hranaFetchHandler);
+    // Combined handler: kimaki-specific endpoints + hrana protocol
     const handler = async (req, res) => {
         const pathname = new URL(req.url || '/', 'http://localhost').pathname;
         if (pathname === '/kimaki/wake') {
@@ -157,18 +140,20 @@ export async function startHranaServer({ dbPath, bindAll = false, }) {
             res.end(JSON.stringify({ ready: true }));
             return;
         }
-        // Hrana routes: /health, /v2, /v2/pipeline
+        // Health check — no auth required
         if (pathname === '/health') {
-            hranaHandler(req, res);
+            res.writeHead(200, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ status: 'ok', pid: process.pid }));
             return;
         }
+        // Hrana routes: /v2, /v2/pipeline — require auth
         if (pathname === '/v2' || pathname === '/v2/pipeline') {
             if (!isAuthorizedRequest(req)) {
                 res.writeHead(401, { 'content-type': 'application/json' });
                 res.end(JSON.stringify({ error: 'unauthorized' }));
                 return;
             }
-            hranaHandler(req, res);
+            hranaNodeHandler(req, res);
             return;
         }
         res.writeHead(404);
@@ -220,263 +205,7 @@ export async function stopHranaServer() {
     readyWaiters = [];
     hranaLogger.log('Hrana server stopped');
 }
-// ── Value encoding/decoding ──────────────────────────────────────────────
-function encodeValue(val) {
-    if (val === null || val === undefined)
-        return { type: 'null' };
-    if (typeof val === 'bigint')
-        return { type: 'integer', value: val.toString() };
-    if (typeof val === 'number') {
-        if (Number.isInteger(val))
-            return { type: 'integer', value: val.toString() };
-        return { type: 'float', value: val };
-    }
-    if (typeof val === 'string')
-        return { type: 'text', value: val };
-    if (Buffer.isBuffer(val))
-        return { type: 'blob', base64: val.toString('base64') };
-    if (val instanceof Uint8Array)
-        return { type: 'blob', base64: Buffer.from(val).toString('base64') };
-    return { type: 'text', value: String(val) };
-}
-function decodeValue(val) {
-    if (val.type === 'null')
-        return null;
-    if (val.type === 'integer') {
-        const n = Number(val.value);
-        return Number.isSafeInteger(n) ? n : BigInt(val.value);
-    }
-    if (val.type === 'float')
-        return val.value;
-    if (val.type === 'text')
-        return val.value;
-    if (val.type === 'blob')
-        return Buffer.from(val.base64, 'base64');
-    return null;
-}
-// ── Statement execution ──────────────────────────────────────────────────
-// SqliteError from libsql has a `code` property but catch gives Error.
-function getSqliteErrorCode(err) {
-    return err.code ?? 'SQLITE_ERROR';
-}
-function resolveStmtSql(stmt, sqlStore) {
-    if (stmt.sql != null)
-        return stmt.sql;
-    if (stmt.sql_id != null)
-        return sqlStore.get(stmt.sql_id) ?? '';
-    return '';
-}
-function bindParams(stmt) {
-    if (stmt.named_args && stmt.named_args.length > 0) {
-        const named = {};
-        for (const na of stmt.named_args) {
-            named[na.name] = decodeValue(na.value);
-        }
-        return [named];
-    }
-    return (stmt.args ?? []).map(decodeValue);
-}
-function executeStmt(database, stmt, sqlStore) {
-    const sql = resolveStmtSql(stmt, sqlStore);
-    const prepared = database.prepare(sql);
-    const params = bindParams(stmt);
-    if (prepared.reader) {
-        const cols = prepared.columns();
-        const rows = prepared.all(...params);
-        return {
-            cols: cols.map((c) => ({ name: c.name, decltype: c.type })),
-            rows: rows.map((row) => cols.map((c) => encodeValue(row[c.name]))),
-            affected_row_count: 0,
-            last_insert_rowid: null,
-        };
-    }
-    const result = prepared.run(...params);
-    return {
-        cols: [],
-        rows: [],
-        affected_row_count: result.changes,
-        last_insert_rowid: result.lastInsertRowid != null ? result.lastInsertRowid.toString() : null,
-    };
-}
-// ── Batch condition evaluation ───────────────────────────────────────────
-function evaluateCondition(cond, stepResults, stepErrors) {
-    if (!cond)
-        return true;
-    if (cond.type === 'ok')
-        return stepErrors[cond.step] === null && stepResults[cond.step] !== null;
-    if (cond.type === 'not')
-        return !evaluateCondition(cond.cond, stepResults, stepErrors);
-    if (cond.type === 'and')
-        return (cond.conds ?? []).every((c) => evaluateCondition(c, stepResults, stepErrors));
-    if (cond.type === 'or')
-        return (cond.conds ?? []).some((c) => evaluateCondition(c, stepResults, stepErrors));
-    return true;
-}
-// ── Request handlers ─────────────────────────────────────────────────────
-function handleExecute(database, req, sqlStore) {
-    if (!req.stmt)
-        return {
-            type: 'error',
-            error: { message: 'Missing stmt', code: 'HRANA_PROTO_ERROR' },
-        };
-    const result = errore.try({
-        try: () => executeStmt(database, req.stmt, sqlStore),
-        catch: (e) => e,
-    });
-    if (result instanceof Error) {
-        return {
-            type: 'error',
-            error: { message: result.message, code: getSqliteErrorCode(result) },
-        };
-    }
-    return { type: 'ok', response: { type: 'execute', result } };
-}
-function handleBatch(database, req, sqlStore) {
-    const steps = req.batch?.steps ?? [];
-    const stepResults = [];
-    const stepErrors = [];
-    for (const step of steps) {
-        if (!evaluateCondition(step.condition, stepResults, stepErrors)) {
-            stepResults.push(null);
-            stepErrors.push(null);
-            continue;
-        }
-        const result = errore.try({
-            try: () => executeStmt(database, step.stmt, sqlStore),
-            catch: (e) => e,
-        });
-        if (result instanceof Error) {
-            stepResults.push(null);
-            stepErrors.push({
-                message: result.message,
-                code: getSqliteErrorCode(result),
-            });
-        }
-        else {
-            stepResults.push(result);
-            stepErrors.push(null);
-        }
-    }
-    return {
-        type: 'ok',
-        response: {
-            type: 'batch',
-            result: { step_results: stepResults, step_errors: stepErrors },
-        },
-    };
-}
-function handleSequence(database, req, sqlStore) {
-    const sql = req.sql ?? (req.sql_id != null ? sqlStore.get(req.sql_id) : null);
-    if (!sql)
-        return { type: 'ok', response: { type: 'sequence' } };
-    const result = errore.try({
-        try: () => {
-            database.exec(sql);
-        },
-        catch: (e) => e,
-    });
-    if (result instanceof Error) {
-        return {
-            type: 'error',
-            error: { message: result.message, code: getSqliteErrorCode(result) },
-        };
-    }
-    return { type: 'ok', response: { type: 'sequence' } };
-}
-function processRequest(database, req, sqlStore) {
-    if (req.type === 'execute')
-        return handleExecute(database, req, sqlStore);
-    if (req.type === 'batch')
-        return handleBatch(database, req, sqlStore);
-    if (req.type === 'sequence')
-        return handleSequence(database, req, sqlStore);
-    if (req.type === 'close')
-        return { type: 'ok', response: { type: 'close' } };
-    if (req.type === 'store_sql') {
-        if (req.sql_id != null && req.sql != null)
-            sqlStore.set(req.sql_id, req.sql);
-        return { type: 'ok', response: { type: 'store_sql' } };
-    }
-    if (req.type === 'close_sql') {
-        if (req.sql_id != null)
-            sqlStore.delete(req.sql_id);
-        return { type: 'ok', response: { type: 'close_sql' } };
-    }
-    return {
-        type: 'error',
-        error: {
-            message: `Unknown request type: ${req.type}`,
-            code: 'HRANA_PROTO_ERROR',
-        },
-    };
-}
-// ── HTTP handler ─────────────────────────────────────────────────────────
-// @libsql/client HTTP driver uses batons to keep streams alive across
-// pipeline requests (needed for interactive transactions). Each stream has
-// its own SQL store for store_sql/close_sql scoping.
-let batonCounter = 0;
-const streamStores = new Map();
-export function createHranaHandler(database) {
-    return (req, res) => {
-        const requestUrl = new URL(req.url || '/', 'http://127.0.0.1');
-        if (req.method === 'GET' && requestUrl.pathname === '/health') {
-            res.writeHead(200, { 'content-type': 'application/json' });
-            res.end(JSON.stringify({ status: 'ok', pid: process.pid }));
-            return;
-        }
-        if (req.method === 'GET' && requestUrl.pathname === '/v2') {
-            res.writeHead(200, { 'content-type': 'application/json' });
-            res.end('{"version":"hrana-v2"}');
-            return;
-        }
-        if (req.method === 'POST' && requestUrl.pathname === '/v2/pipeline') {
-            const chunks = [];
-            let aborted = false;
-            req.on('error', () => {
-                aborted = true;
-                res.destroy();
-            });
-            req.on('data', (chunk) => {
-                chunks.push(chunk);
-            });
-            req.on('end', () => {
-                if (aborted)
-                    return;
-                const parseResult = errore.try({
-                    try: () => JSON.parse(Buffer.concat(chunks).toString()),
-                    catch: (e) => e,
-                });
-                if (parseResult instanceof Error) {
-                    res.writeHead(400, { 'content-type': 'application/json' });
-                    res.end(JSON.stringify({
-                        error: {
-                            message: parseResult.message,
-                            code: 'HRANA_PROTO_ERROR',
-                        },
-                    }));
-                    return;
-                }
-                // Resolve or create per-stream SQL store keyed by baton
-                const incoming = parseResult.baton;
-                const sqlStore = (incoming ? streamStores.get(incoming) : undefined) ??
-                    new Map();
-                if (incoming)
-                    streamStores.delete(incoming);
-                const results = (parseResult.requests ?? []).map((r) => processRequest(database, r, sqlStore));
-                const hasClose = (parseResult.requests ?? []).some((r) => r.type === 'close');
-                const baton = hasClose ? null : `b${++batonCounter}`;
-                if (baton)
-                    streamStores.set(baton, sqlStore);
-                res.writeHead(200, { 'content-type': 'application/json' });
-                res.end(JSON.stringify({ baton, base_url: null, results }));
-            });
-            return;
-        }
-        res.writeHead(404);
-        res.end();
-    };
-}
-// ── Single-instance enforcement ──────────────────────────────────────────
+// ── Single-instance enforcement ──────────────────────────────────────
 /**
  * Evict a previous kimaki instance on the lock port.
  * Fetches /health to get the running process PID, then kills it directly.

package/dist/hrana-server.test.js

@@ -7,7 +7,7 @@ import { describe, test, expect, afterAll } from 'vitest';
 import Database from 'libsql';
 import { PrismaLibSql } from '@prisma/adapter-libsql';
 import { PrismaClient } from './generated/client.js';
-import { createHranaHandler } from './hrana-server.js';
+import { createLibsqlHandler, createLibsqlNodeHandler, libsqlExecutor, } from 'libsqlproxy';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 async function migrateSchema(prisma) {
@@ -72,7 +72,9 @@ describe('hrana-server', () => {
         testDb = database;
         const port = 10000 + Math.floor(Math.random() * 50000);
         await new Promise((resolve, reject) => {
-            const srv = http.createServer(createHranaHandler(database));
+            const hranaFetchHandler = createLibsqlHandler(libsqlExecutor(database));
+            const hranaNodeHandler = createLibsqlNodeHandler(hranaFetchHandler);
+            const srv = http.createServer(hranaNodeHandler);
             srv.on('error', reject);
             srv.listen(port, '127.0.0.1', () => {
                 testServer = srv;

package/dist/kimaki-opencode-plugin-loading.e2e.test.js

@@ -34,6 +34,7 @@ test('opencode server loads plugin without errors', async () => {
     const port = chooseLockPort({ key: 'opencode-plugin-loading-e2e' });
     const pluginPath = new URL('../src/kimaki-opencode-plugin.ts', import.meta.url).href;
     const stderrLines = [];
+    const isolatedOpencodeRoot = path.join(projectDir, 'opencode-test-home');
     const { command, args, windowsVerbatimArguments, } = getSpawnCommandAndArgs({
         resolvedCommand: resolveOpencodeCommand(),
         baseArgs: ['serve', '--port', port.toString(), '--print-logs', '--log-level', 'DEBUG'],
@@ -50,6 +51,12 @@ test('opencode server loads plugin without errors', async () => {
                 formatter: false,
                 plugin: [pluginPath],
             }),
+            OPENCODE_TEST_HOME: isolatedOpencodeRoot,
+            OPENCODE_CONFIG_DIR: path.join(isolatedOpencodeRoot, '.opencode-kimaki'),
+            XDG_CONFIG_HOME: path.join(isolatedOpencodeRoot, '.config'),
+            XDG_DATA_HOME: path.join(isolatedOpencodeRoot, '.local', 'share'),
+            XDG_CACHE_HOME: path.join(isolatedOpencodeRoot, '.cache'),
+            XDG_STATE_HOME: path.join(isolatedOpencodeRoot, '.local', 'state'),
         },
     });
     serverProcess.stderr?.on('data', (data) => {

package/dist/kimaki-opencode-plugin.js

@@ -7,7 +7,9 @@
 // - ipc-tools-plugin: file upload + action buttons (IPC-based Discord tools)
 // - context-awareness-plugin: branch, pwd, memory, time gap, onboarding tutorial
 // - opencode-interrupt-plugin: interrupt queued messages at step boundaries
+// - kitty-graphics-plugin: extract Kitty Graphics Protocol images from bash output
 export { ipcToolsPlugin } from './ipc-tools-plugin.js';
 export { contextAwarenessPlugin } from './context-awareness-plugin.js';
 export { interruptOpencodeSessionOnUserMessage } from './opencode-interrupt-plugin.js';
 export { anthropicAuthPlugin } from './anthropic-auth-plugin.js';
+export { kittyGraphicsPlugin } from 'kitty-graphics-agent';

package/dist/kitty-graphics-parser.js

@@ -0,0 +1,3 @@
+// Re-export from the kitty-graphics-agent package.
+// The implementation lives in its own package/repo for reuse as a spec.
+export { extractKittyGraphics } from 'kitty-graphics-agent/parser';

package/dist/kitty-graphics-parser.test.js

@@ -0,0 +1,276 @@
+import { describe, expect, test } from 'vitest';
+import { extractKittyGraphics } from './kitty-graphics-parser.js';
+// Helper to build a Kitty Graphics escape sequence
+function kittySeq(controlData, payload) {
+    return `\x1b_G${controlData};${payload}\x1b\\`;
+}
+// Small valid base64 PNG header (not a real PNG, just for testing)
+const FAKE_PNG_B64 = 'iVBORw0KGgoAAAANSUhEUg==';
+const FAKE_PNG_B64_CHUNK1 = 'iVBORw0KGg';
+const FAKE_PNG_B64_CHUNK2 = 'oAAAANSUhEUg==';
+describe('extractKittyGraphics', () => {
+    test('no escape sequences returns input unchanged', () => {
+        const result = extractKittyGraphics('hello world');
+        expect(result).toMatchInlineSnapshot(`
+      {
+        "cleanedOutput": "hello world",
+        "images": [],
+      }
+    `);
+    });
+    test('empty string', () => {
+        const result = extractKittyGraphics('');
+        expect(result).toMatchInlineSnapshot(`
+      {
+        "cleanedOutput": "",
+        "images": [],
+      }
+    `);
+    });
+    test('single PNG image (f=100, non-chunked)', () => {
+        const input = `before${kittySeq('f=100', FAKE_PNG_B64)}after`;
+        const result = extractKittyGraphics(input);
+        expect(result).toMatchInlineSnapshot(`
+      {
+        "cleanedOutput": "beforeafter",
+        "images": [
+          {
+            "data": "iVBORw0KGgoAAAANSUhEUg==",
+            "mime": "image/png",
+          },
+        ],
+      }
+    `);
+    });
+    test('PNG image with transmit+display action (a=T)', () => {
+        const input = kittySeq('a=T,f=100', FAKE_PNG_B64);
+        const result = extractKittyGraphics(input);
+        expect(result).toMatchInlineSnapshot(`
+      {
+        "cleanedOutput": "",
+        "images": [
+          {
+            "data": "iVBORw0KGgoAAAANSUhEUg==",
+            "mime": "image/png",
+          },
+        ],
+      }
+    `);
+    });
+    test('PNG image with width and height', () => {
+        const input = kittySeq('f=100,s=640,v=480', FAKE_PNG_B64);
+        const result = extractKittyGraphics(input);
+        expect(result).toMatchInlineSnapshot(`
+      {
+        "cleanedOutput": "",
+        "images": [
+          {
+            "data": "iVBORw0KGgoAAAANSUhEUg==",
+            "height": 480,
+            "mime": "image/png",
+            "width": 640,
+          },
+        ],
+      }
+    `);
+    });
+    test('chunked PNG image (m=1 then m=0)', () => {
+        const chunk1 = kittySeq('a=T,f=100,m=1', FAKE_PNG_B64_CHUNK1);
+        const chunk2 = kittySeq('m=0', FAKE_PNG_B64_CHUNK2);
+        const input = `start${chunk1}${chunk2}end`;
+        const result = extractKittyGraphics(input);
+        expect(result).toMatchInlineSnapshot(`
+      {
+        "cleanedOutput": "startend",
+        "images": [
+          {
+            "data": "iVBORw0KGgoAAAANSUhEUg==",
+            "mime": "image/png",
+          },
+        ],
+      }
+    `);
+    });
+    test('three-chunk PNG image', () => {
+        const chunk1 = kittySeq('a=T,f=100,s=100,v=50,m=1', 'AAAA');
+        const chunk2 = kittySeq('m=1', 'BBBB');
+        const chunk3 = kittySeq('m=0', 'CCCC');
+        const input = `${chunk1}${chunk2}${chunk3}`;
+        const result = extractKittyGraphics(input);
+        expect(result).toMatchInlineSnapshot(`
+      {
+        "cleanedOutput": "",
+        "images": [
+          {
+            "data": "AAAABBBBCCCC",
+            "height": 50,
+            "mime": "image/png",
+            "width": 100,
+          },
+        ],
+      }
+    `);
+    });
+    test('RGBA image (f=32) is stripped but not extracted', () => {
+        const input = `text${kittySeq('f=32,s=10,v=10', 'RGBA_DATA')}more`;
+        const result = extractKittyGraphics(input);
+        expect(result).toMatchInlineSnapshot(`
+      {
+        "cleanedOutput": "textmore",
+        "images": [],
+      }
+    `);
+    });
+    test('RGB image (f=24) is stripped but not extracted', () => {
+        const input = `x${kittySeq('f=24,s=5,v=5', 'RGB_DATA')}y`;
+        const result = extractKittyGraphics(input);
+        expect(result).toMatchInlineSnapshot(`
+      {
+        "cleanedOutput": "xy",
+        "images": [],
+      }
+    `);
+    });
+    test('default format (no f= key, defaults to 32) is stripped but not extracted', () => {
+        const input = `a${kittySeq('s=10,v=10', 'SOME_DATA')}b`;
+        const result = extractKittyGraphics(input);
+        expect(result).toMatchInlineSnapshot(`
+      {
+        "cleanedOutput": "ab",
+        "images": [],
+      }
+    `);
+    });
+    test('multiple images in one output', () => {
+        const img1 = kittySeq('f=100', 'IMAGE_ONE');
+        const img2 = kittySeq('f=100,s=200,v=100', 'IMAGE_TWO');
+        const input = `first${img1}middle${img2}last`;
+        const result = extractKittyGraphics(input);
+        expect(result).toMatchInlineSnapshot(`
+      {
+        "cleanedOutput": "firstmiddlelast",
+        "images": [
+          {
+            "data": "IMAGE_ONE",
+            "mime": "image/png",
+          },
+          {
+            "data": "IMAGE_TWO",
+            "height": 100,
+            "mime": "image/png",
+            "width": 200,
+          },
+        ],
+      }
+    `);
+    });
+    test('mixed PNG and non-PNG: only PNG extracted', () => {
+        const pngImg = kittySeq('f=100', 'PNG_DATA');
+        const rgbaImg = kittySeq('f=32,s=10,v=10', 'RGBA_DATA');
+        const input = `${pngImg}between${rgbaImg}`;
+        const result = extractKittyGraphics(input);
+        expect(result).toMatchInlineSnapshot(`
+      {
+        "cleanedOutput": "between",
+        "images": [
+          {
+            "data": "PNG_DATA",
+            "mime": "image/png",
+          },
+        ],
+      }
+    `);
+    });
+    test('file-based transmission (t=f) is stripped but not extracted', () => {
+        // t=f means the payload is a file path, not inline data
+        const input = `x${kittySeq('f=100,t=f', 'L3RtcC9pbWFnZS5wbmc=')}y`;
+        const result = extractKittyGraphics(input);
+        expect(result).toMatchInlineSnapshot(`
+      {
+        "cleanedOutput": "xy",
+        "images": [],
+      }
+    `);
+    });
+    test('image with suppress response (q=2)', () => {
+        const input = kittySeq('f=100,q=2', FAKE_PNG_B64);
+        const result = extractKittyGraphics(input);
+        expect(result).toMatchInlineSnapshot(`
+      {
+        "cleanedOutput": "",
+        "images": [
+          {
+            "data": "iVBORw0KGgoAAAANSUhEUg==",
+            "mime": "image/png",
+          },
+        ],
+      }
+    `);
+    });
+    test('incomplete escape sequence at end is left in output', () => {
+        // Missing ST terminator
+        const input = `hello\x1b_Gf=100;${FAKE_PNG_B64}`;
+        const result = extractKittyGraphics(input);
+        expect(result).toMatchInlineSnapshot(`
+      {
+        "cleanedOutput": "hello_Gf=100;iVBORw0KGgoAAAANSUhEUg==",
+        "images": [],
+      }
+    `);
+    });
+    test('text with ANSI color codes is not affected', () => {
+        const input = '\x1b[31mred text\x1b[0m normal';
+        const result = extractKittyGraphics(input);
+        expect(result).toMatchInlineSnapshot(`
+      {
+        "cleanedOutput": "red text normal",
+        "images": [],
+      }
+    `);
+    });
+    test('delete command (a=d) is stripped, no image extracted', () => {
+        const input = `before\x1b_Ga=d\x1b\\after`;
+        const result = extractKittyGraphics(input);
+        expect(result).toMatchInlineSnapshot(`
+      {
+        "cleanedOutput": "beforeafter",
+        "images": [],
+      }
+    `);
+    });
+    test('escape sequence with no payload', () => {
+        const input = `x\x1b_Ga=d,d=a;\x1b\\y`;
+        const result = extractKittyGraphics(input);
+        expect(result).toMatchInlineSnapshot(`
+      {
+        "cleanedOutput": "xy",
+        "images": [],
+      }
+    `);
+    });
+    test('real-world: text with command output mixed with kitty image', () => {
+        const lines = [
+            '$ kitten icat image.png',
+            kittySeq('a=T,f=100,q=2,m=1', FAKE_PNG_B64_CHUNK1),
+            kittySeq('m=0', FAKE_PNG_B64_CHUNK2),
+            '$ echo done',
+            'done',
+        ].join('\n');
+        const result = extractKittyGraphics(lines);
+        expect(result.cleanedOutput).toMatchInlineSnapshot(`
+      "$ kitten icat image.png
+
+
+      $ echo done
+      done"
+    `);
+        expect(result.images).toMatchInlineSnapshot(`
+      [
+        {
+          "data": "iVBORw0KGgoAAAANSUhEUg==",
+          "mime": "image/png",
+        },
+      ]
+    `);
+    });
+});

package/dist/kitty-graphics-plugin.js

@@ -0,0 +1,3 @@
+// Re-export from the kitty-graphics-agent package.
+// The implementation lives in its own package/repo for reuse as a spec.
+export { kittyGraphicsPlugin } from 'kitty-graphics-agent';