@ctrl-spc/cs 0.3.1 → 0.5.0

package/dist/mcp.js

@@ -1,4 +1,4 @@
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { createServer as createHttpServer } from 'node:http';
@@ -9,6 +9,7 @@ import { z } from 'zod';
 import { TOOLS_SERVER_PORT, SESSION_TTL_MS } from './env.js';
 import { agentPath } from './agents.js';
 import { mcpToken, readSession } from './config.js';
+import { readPngScreenshot, } from './screenshots.js';
 export function attributionFromClientName(name) {
     if (!name)
         return null;
@@ -279,6 +280,297 @@ async function createArtifactHandler(client, userId, currentSession, args) {
         return errorResult(`create_artifact failed: ${err.message}`);
     }
 }
+const SCREENSHOT_PLATFORM_LABEL = {
+    web: 'Web',
+    ios: 'iOS',
+    android: 'Android',
+};
+function attachScreenshotFailure(title, reason) {
+    return errorResult(`Couldn’t attach "${title}": ${reason}. No artifact was created.`);
+}
+function screenshotArtifactId(taskId, title, platform, target, bytes) {
+    const digest = createHash('sha256')
+        .update('ctrl-spc:screenshot:v1\0')
+        .update(taskId)
+        .update('\0')
+        .update(title)
+        .update('\0')
+        .update(platform)
+        .update('\0')
+        .update(target)
+        .update('\0')
+        .update(bytes)
+        .digest()
+        .subarray(0, 16);
+    // RFC 9562-shaped, deterministic UUID. The content-addressed identity makes
+    // a retry after Storage succeeded but Postgres failed converge on the same
+    // object instead of leaking one new object per retry.
+    digest[6] = (digest[6] & 0x0f) | 0x50;
+    digest[8] = (digest[8] & 0x3f) | 0x80;
+    const hex = digest.toString('hex');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+function isDuplicateStorageObject(error) {
+    return /duplicate|already exists|resource exists/i.test(`${error.message} ${error.error ?? ''} ${error.name ?? ''}`);
+}
+function screenshotArtifactMatches(row, expected) {
+    return (row.id === expected.id &&
+        row.task_id === expected.taskId &&
+        row.type === 'image' &&
+        row.format === 'png' &&
+        row.title === expected.title &&
+        row.content === expected.content &&
+        row.storage_path === expected.storagePath &&
+        row.created_by === expected.userId &&
+        row.deleted_at === null);
+}
+async function fetchScreenshotArtifact(client, artifactId) {
+    return must(client
+        .from('artifacts')
+        .select('id,task_id,type,format,title,content,storage_path,created_by,deleted_at')
+        .eq('id', artifactId)
+        .maybeSingle());
+}
+async function downloadScreenshotObject(client, storagePath) {
+    const { data, error } = await client.storage.from('artifacts').download(storagePath);
+    if (error)
+        throw new Error(error.message);
+    if (!data)
+        throw new Error('Storage returned no file data');
+    const arrayBuffer = await data.arrayBuffer();
+    return Buffer.from(arrayBuffer);
+}
+async function ensureScreenshotAttribution(client, userId, sessionId, artifactId) {
+    try {
+        await must(client.from('cliv2_agent_outputs').insert({
+            user_id: userId,
+            session_id: sessionId,
+            kind: 'artifact',
+            product_id: artifactId,
+        }));
+        return undefined;
+    }
+    catch (err) {
+        // A completed call whose response was lost already has this unique
+        // attribution row. Treat it as converged rather than warning or duplicating.
+        try {
+            const existing = await must(client
+                .from('cliv2_agent_outputs')
+                .select('user_id,session_id,product_id')
+                .eq('kind', 'artifact')
+                .eq('product_id', artifactId)
+                .maybeSingle());
+            if (existing?.user_id === userId && existing.product_id === artifactId)
+                return undefined;
+        }
+        catch {
+            // Preserve the original attribution failure below.
+        }
+        return `Screenshot attached, but recording session attribution failed: ${err.message}`;
+    }
+}
+function attachedScreenshotResult(title, platform, target, artifactId, attributionWarning) {
+    const success = `✓ Attached "${title}" to this work item.\n` +
+        `  ${SCREENSHOT_PLATFORM_LABEL[platform]} · ${target} · image artifact ${artifactId}`;
+    return attributionWarning
+        ? { content: [{ type: 'text', text: `${success}\n  Warning: ${attributionWarning}` }] }
+        : { content: [{ type: 'text', text: success }] };
+}
+/**
+ * Attach one already-captured PNG to this connection's open work session.
+ *
+ * The local file is fully validated before the first hosted request. The
+ * Storage upload intentionally precedes the artifact INSERT: the private bucket
+ * has no DELETE policy (objects follow the artifact soft-delete posture), so an
+ * upload failure must never leave a live broken card. There is no transaction
+ * across Supabase Storage and Postgres; if the upload succeeds but the row
+ * insert fails, the stable object key is reported for maintenance cleanup.
+ */
+export async function attachScreenshotHandler(client, userId, currentSession, args, deps = {}) {
+    const title = args.title?.trim() ?? '';
+    if (!currentSession) {
+        return errorResult('attach_screenshot needs an open work session — call begin_work first. No artifact was created.');
+    }
+    if (!title) {
+        return attachScreenshotFailure('Untitled screenshot', 'title must be non-empty');
+    }
+    const target = args.target?.trim() ?? '';
+    if (!target) {
+        return attachScreenshotFailure(title, 'target must be non-empty');
+    }
+    if (!['web', 'ios', 'android'].includes(args.platform)) {
+        return attachScreenshotFailure(title, "platform must be 'web', 'ios', or 'android'");
+    }
+    let screenshot;
+    try {
+        screenshot = await (deps.readScreenshot ?? readPngScreenshot)(args.path);
+    }
+    catch (err) {
+        return attachScreenshotFailure(title, err.message);
+    }
+    try {
+        // Resolve only the open session's task. There is deliberately no task_id
+        // argument, so one MCP connection cannot attach a screenshot to some other
+        // work item while it is working this one.
+        const task = await must(client
+            .from('tasks')
+            .select('id,project_id')
+            .eq('id', currentSession.taskId)
+            .is('archived_at', null)
+            .maybeSingle());
+        if (!task) {
+            return attachScreenshotFailure(title, 'the open work item was not found or is archived');
+        }
+        const project = await must(client
+            .from('projects')
+            .select('id,org_id')
+            .eq('id', task.project_id)
+            .is('archived_at', null)
+            .maybeSingle());
+        if (!project) {
+            return attachScreenshotFailure(title, 'the work item project was not found or is not accessible');
+        }
+        const artifactId = deps.artifactId?.() ??
+            screenshotArtifactId(task.id, title, args.platform, target, screenshot.bytes);
+        const storagePath = `${project.org_id}/${task.project_id}/${task.id}/${artifactId}.png`;
+        const metadata = {
+            platform: args.platform,
+            target,
+            width: screenshot.width,
+            height: screenshot.height,
+            size_bytes: screenshot.sizeBytes,
+        };
+        const content = JSON.stringify(metadata);
+        const expectedArtifact = {
+            id: artifactId,
+            taskId: task.id,
+            title,
+            content,
+            storagePath,
+            userId,
+        };
+        // Supabase Storage documents that upload needs INSERT RLS. upsert:false is
+        // intentional: this call never replaces an existing screenshot and
+        // therefore does not require SELECT + UPDATE permissions.
+        const { error: uploadError } = await client.storage
+            .from('artifacts')
+            .upload(storagePath, screenshot.bytes, {
+            contentType: 'image/png',
+            upsert: false,
+        });
+        if (uploadError && !isDuplicateStorageObject(uploadError)) {
+            return attachScreenshotFailure(title, `the PNG could not be uploaded: ${uploadError.message}`);
+        }
+        if (uploadError) {
+            let existing;
+            try {
+                existing = await fetchScreenshotArtifact(client, artifactId);
+            }
+            catch (err) {
+                return errorResult(`Couldn’t attach "${title}": the screenshot object already exists, but CTRL+SPC could not confirm ` +
+                    `whether artifact ${artifactId} is complete: ${err.message}. The existing object and any ` +
+                    'artifact record were left unchanged; do not retry until the artifact can be checked.');
+            }
+            if (existing) {
+                if (!screenshotArtifactMatches(existing, expectedArtifact)) {
+                    return errorResult(`Couldn’t attach "${title}": the retry key is already linked to a different artifact record. ` +
+                        `Existing artifact ${artifactId} was left unchanged; no new artifact was created.`);
+                }
+                const warning = await ensureScreenshotAttribution(client, userId, currentSession.sessionId, artifactId);
+                return attachedScreenshotResult(title, args.platform, target, artifactId, warning);
+            }
+            // No artifact row means this may be an orphan from an interrupted call.
+            // Verify the private object's exact bytes before linking it; a key
+            // collision must never turn someone else's object into this evidence.
+            let existingBytes;
+            try {
+                existingBytes = await downloadScreenshotObject(client, storagePath);
+            }
+            catch (err) {
+                return errorResult(`Couldn’t attach "${title}": the screenshot object already exists, but CTRL+SPC could not verify ` +
+                    `its bytes: ${err.message}. The existing object was left unchanged; no artifact was created.`);
+            }
+            if (!existingBytes.equals(screenshot.bytes)) {
+                return errorResult(`Couldn’t attach "${title}": the retry key points to an existing screenshot with different bytes. ` +
+                    `The existing object was left unchanged; no artifact was created.`);
+            }
+            // The exact object is an orphan from a previous call that failed at
+            // Postgres. Continue with the same deterministic id/path to finish it.
+        }
+        let row;
+        try {
+            row = await must(client
+                .from('artifacts')
+                .insert({
+                id: artifactId,
+                task_id: task.id,
+                type: 'image',
+                format: 'png',
+                title,
+                content,
+                storage_path: storagePath,
+                created_by: userId,
+                from_agent: null,
+                agent_run_id: null,
+            })
+                .select(ARTIFACT_COLUMNS)
+                .single());
+        }
+        catch (err) {
+            // The insert response may have been lost after Postgres committed, or a
+            // concurrent retry may have won. Re-read before describing an orphan.
+            let existing;
+            try {
+                existing = await fetchScreenshotArtifact(client, artifactId);
+            }
+            catch (readErr) {
+                return errorResult(`Couldn’t confirm whether "${title}" finished attaching after the PNG upload: ` +
+                    `${readErr.message}. Artifact ${artifactId} may already exist; the private object at ` +
+                    `"${storagePath}" was left unchanged. Do not retry until the artifact can be checked.`);
+            }
+            if (existing) {
+                if (!screenshotArtifactMatches(existing, expectedArtifact)) {
+                    return errorResult(`Couldn’t attach "${title}": artifact id ${artifactId} is already used by a different record. ` +
+                        'The existing artifact was left unchanged; no new artifact was created.');
+                }
+                const warning = await ensureScreenshotAttribution(client, userId, currentSession.sessionId, artifactId);
+                return attachedScreenshotResult(title, args.platform, target, artifactId, warning);
+            }
+            // The bucket intentionally has no DELETE policy. Removing an object by
+            // writing storage.objects directly is unsupported by Supabase, so do not
+            // pretend this cross-service boundary is atomic.
+            return errorResult(`Couldn’t attach "${title}": the PNG uploaded, but the artifact record could not be created: ` +
+                `${err.message}. No artifact was created. The unlinked private object at ` +
+                `"${storagePath}" may require maintenance cleanup.`);
+        }
+        if (!row) {
+            let existing;
+            try {
+                existing = await fetchScreenshotArtifact(client, artifactId);
+            }
+            catch (readErr) {
+                return errorResult(`Couldn’t confirm whether "${title}" finished attaching after the PNG upload: ` +
+                    `${readErr.message}. Artifact ${artifactId} may already exist; the private object at ` +
+                    `"${storagePath}" was left unchanged. Do not retry until the artifact can be checked.`);
+            }
+            if (existing) {
+                if (!screenshotArtifactMatches(existing, expectedArtifact)) {
+                    return errorResult(`Couldn’t attach "${title}": artifact id ${artifactId} is already used by a different record. ` +
+                        'The existing artifact was left unchanged; no new artifact was created.');
+                }
+                const warning = await ensureScreenshotAttribution(client, userId, currentSession.sessionId, artifactId);
+                return attachedScreenshotResult(title, args.platform, target, artifactId, warning);
+            }
+            return errorResult(`Couldn’t attach "${title}": the PNG uploaded, but the artifact record returned no row. ` +
+                `No artifact was created. The unlinked private object at "${storagePath}" may require maintenance cleanup.`);
+        }
+        const attributionWarning = await ensureScreenshotAttribution(client, userId, currentSession.sessionId, artifactId);
+        return attachedScreenshotResult(title, args.platform, target, artifactId, attributionWarning);
+    }
+    catch (err) {
+        return attachScreenshotFailure(title, err.message);
+    }
+}
 /** Re-fetch one task with the SAME select get_task uses (`*` + the tag join),
  *  returning the parsed task object ({ ...row, tags }, task_tags dropped) or null.
  *  Shared by update_task and create_task so their result shape matches get_task's
@@ -1414,12 +1706,13 @@ async function getCredentialHandler(client, args) {
     }
 }
 // ---------------------------------------------------------------------------
-// The twenty-two tools this server exposes. Exported for the self-check.
+// The twenty-three tools this server exposes. Exported for the self-check.
 // ---------------------------------------------------------------------------
 export const TOOL_NAMES = [
     'list_tasks',
     'get_task',
     'create_artifact',
+    'attach_screenshot',
     'update_task',
     'update_artifact',
     'set_task_role_slugs',
@@ -1440,7 +1733,7 @@ export const TOOL_NAMES = [
     'list_credentials',
     'get_credential',
 ];
-/** Build a per-session McpServer with the twenty-two tools. A fresh instance per
+/** Build a per-session McpServer with the twenty-three tools. A fresh instance per
  *  session is what makes `server.server.getClientVersion()` (populated during
  *  that session's `initialize`) the right source for attribution — mirroring
  *  v1's per-session `buildServer`. `connectionId` is this connection's key into
@@ -1496,6 +1789,21 @@ export function buildToolsServer(client, userId, machineId, connectionId) {
         touchSession(connectionId);
         return createArtifactHandler(client, userId, openSessions.get(connectionId) ?? null, args);
     });
+    server.registerTool('attach_screenshot', {
+        description: 'Attach one real Web, iOS, or Android PNG screenshot to the work item in your open session. ' +
+            'Playwright or Maestro captures the file first; pass its absolute local path, a clear title, the ' +
+            'platform, and the exact browser/simulator/emulator target. The local path is never uploaded or stored. ' +
+            'Requires an open session (begin_work).',
+        inputSchema: {
+            path: z.string().describe('Absolute local path to one existing PNG'),
+            title: z.string().describe('Non-empty title shown on the work item'),
+            platform: z.enum(['web', 'ios', 'android']),
+            target: z.string().describe('Non-empty exact browser, simulator, or emulator name'),
+        },
+    }, async (args) => {
+        touchSession(connectionId);
+        return attachScreenshotHandler(client, userId, openSessions.get(connectionId) ?? null, args);
+    });
     server.registerTool('update_task', {
         description: 'Update a task you own — its status (backlog / in_progress / done), name, description, or due_date. ' +
             'Pass expected_revision from the most recent get_task for optimistic concurrency; on a conflict, ' +

package/dist/screenshots.js

@@ -0,0 +1,196 @@
+import { lstat, readFile } from 'node:fs/promises';
+import { isAbsolute } from 'node:path';
+import { inflateSync } from 'node:zlib';
+export const MAX_SCREENSHOT_BYTES = 20 * 1024 * 1024;
+const MAX_DECODED_SCREENSHOT_BYTES = 256 * 1024 * 1024;
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const CRC32_TABLE = Uint32Array.from({ length: 256 }, (_, value) => {
+    let crc = value;
+    for (let bit = 0; bit < 8; bit += 1) {
+        crc = (crc >>> 1) ^ (0xedb88320 & -(crc & 1));
+    }
+    return crc >>> 0;
+});
+function crc32(bytes) {
+    let crc = 0xffffffff;
+    for (const byte of bytes) {
+        crc = CRC32_TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8);
+    }
+    return (crc ^ 0xffffffff) >>> 0;
+}
+/**
+ * Read and validate the local screenshot before any hosted request is made.
+ *
+ * This validates the PNG framing and decoded scanline envelope without
+ * rewriting the user's original bytes. Interlaced images are rejected because
+ * browser and mobile screenshot tools produce standard non-interlaced PNGs,
+ * and validating Adam7 safely would add complexity without helping Phase 1.
+ */
+export async function readPngScreenshot(localPath) {
+    if (!localPath || !isAbsolute(localPath)) {
+        throw new Error('path must be an absolute local path');
+    }
+    let stat;
+    try {
+        stat = await lstat(localPath);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT')
+            throw new Error(`the PNG was not found at ${localPath}`);
+        throw new Error(`the PNG could not be inspected at ${localPath}: ${err.message}`);
+    }
+    if (!stat.isFile()) {
+        throw new Error(`the path is not a regular file: ${localPath}`);
+    }
+    if (stat.size === 0) {
+        throw new Error('the PNG is empty');
+    }
+    if (stat.size > MAX_SCREENSHOT_BYTES) {
+        throw new Error(`the PNG is larger than the ${MAX_SCREENSHOT_BYTES / (1024 * 1024)} MB limit`);
+    }
+    let bytes;
+    try {
+        bytes = await readFile(localPath);
+    }
+    catch (err) {
+        throw new Error(`the PNG could not be read at ${localPath}: ${err.message}`);
+    }
+    if (bytes.length !== stat.size) {
+        throw new Error('the PNG changed while it was being read; capture it again and retry');
+    }
+    if (bytes.length < PNG_SIGNATURE.length || !bytes.subarray(0, 8).equals(PNG_SIGNATURE)) {
+        throw new Error('the file is not a readable PNG (invalid PNG signature)');
+    }
+    let offset = 8;
+    let width = 0;
+    let height = 0;
+    let sawHeader = false;
+    let sawImageData = false;
+    let sawEnd = false;
+    let sawPalette = false;
+    let endedImageData = false;
+    let bitDepth = 0;
+    let colorType = 0;
+    const imageDataChunks = [];
+    while (offset < bytes.length) {
+        if (bytes.length - offset < 12) {
+            throw new Error('the file is not a readable PNG (truncated chunk header)');
+        }
+        const length = bytes.readUInt32BE(offset);
+        const chunkEnd = offset + 12 + length;
+        if (chunkEnd > bytes.length || chunkEnd < offset) {
+            throw new Error('the file is not a readable PNG (truncated chunk data)');
+        }
+        const typeBytes = bytes.subarray(offset + 4, offset + 8);
+        const type = typeBytes.toString('ascii');
+        if (!/^[A-Za-z]{4}$/.test(type)) {
+            throw new Error('the file is not a readable PNG (invalid chunk type)');
+        }
+        const expectedCrc = bytes.readUInt32BE(offset + 8 + length);
+        const actualCrc = crc32(bytes.subarray(offset + 4, offset + 8 + length));
+        if (actualCrc !== expectedCrc) {
+            throw new Error(`the file is not a readable PNG (${type} chunk CRC mismatch)`);
+        }
+        if (!sawHeader) {
+            if (type !== 'IHDR' || length !== 13) {
+                throw new Error('the file is not a readable PNG (missing the required IHDR header)');
+            }
+            width = bytes.readUInt32BE(offset + 8);
+            height = bytes.readUInt32BE(offset + 12);
+            bitDepth = bytes[offset + 16];
+            colorType = bytes[offset + 17];
+            const compression = bytes[offset + 18];
+            const filter = bytes[offset + 19];
+            const interlace = bytes[offset + 20];
+            const legalDepths = {
+                0: [1, 2, 4, 8, 16],
+                2: [8, 16],
+                3: [1, 2, 4, 8],
+                4: [8, 16],
+                6: [8, 16],
+            };
+            if (!legalDepths[colorType]?.includes(bitDepth)) {
+                throw new Error('the file is not a readable PNG (unsupported IHDR color type or bit depth)');
+            }
+            if (compression !== 0 || filter !== 0) {
+                throw new Error('the file is not a readable PNG (unsupported compression or filter method)');
+            }
+            if (interlace !== 0) {
+                throw new Error('the file is not a readable PNG (interlaced PNGs are not supported)');
+            }
+            sawHeader = true;
+        }
+        else if (type === 'IHDR') {
+            throw new Error('the file is not a readable PNG (duplicate IHDR header)');
+        }
+        if (type === 'PLTE') {
+            if (sawImageData || length === 0 || length % 3 !== 0 || length > 768) {
+                throw new Error('the file is not a readable PNG (invalid PLTE chunk)');
+            }
+            sawPalette = true;
+        }
+        if (type === 'IDAT') {
+            if (endedImageData) {
+                throw new Error('the file is not a readable PNG (IDAT chunks must be consecutive)');
+            }
+            sawImageData = true;
+            imageDataChunks.push(bytes.subarray(offset + 8, offset + 8 + length));
+        }
+        else if (type === 'IEND') {
+            if (length !== 0) {
+                throw new Error('the file is not a readable PNG (invalid IEND chunk)');
+            }
+            sawEnd = true;
+            offset = chunkEnd;
+            break;
+        }
+        else if (sawImageData) {
+            endedImageData = true;
+        }
+        if (/^[A-Z]/.test(type) && !['IHDR', 'PLTE', 'IDAT', 'IEND'].includes(type)) {
+            throw new Error(`the file is not a readable PNG (unsupported critical chunk ${type})`);
+        }
+        offset = chunkEnd;
+    }
+    if (!sawImageData) {
+        throw new Error('the file is not a readable PNG (missing image data)');
+    }
+    if (!sawEnd) {
+        throw new Error('the file is not a readable PNG (missing IEND chunk)');
+    }
+    if (offset !== bytes.length) {
+        throw new Error('the file is not a readable PNG (trailing data after IEND)');
+    }
+    if (width < 1 || height < 1) {
+        throw new Error('the file is not a readable PNG (width and height must be positive)');
+    }
+    if (colorType === 3 && !sawPalette) {
+        throw new Error('the file is not a readable PNG (indexed color requires a PLTE chunk)');
+    }
+    const channels = colorType === 0 || colorType === 3 ? 1 : colorType === 2 ? 3 : colorType === 4 ? 2 : 4;
+    const rowBytes = Math.ceil((width * channels * bitDepth) / 8);
+    const scanlineBytes = rowBytes + 1;
+    const expectedDecodedBytes = scanlineBytes * height;
+    if (!Number.isSafeInteger(expectedDecodedBytes) || expectedDecodedBytes > MAX_DECODED_SCREENSHOT_BYTES) {
+        throw new Error('the PNG expands beyond the 256 MB decoded screenshot limit');
+    }
+    let decoded;
+    try {
+        decoded = inflateSync(Buffer.concat(imageDataChunks), {
+            maxOutputLength: expectedDecodedBytes + 1,
+        });
+    }
+    catch (err) {
+        throw new Error(`the file is not a readable PNG (invalid compressed image data: ${err.message})`);
+    }
+    if (decoded.length !== expectedDecodedBytes) {
+        throw new Error(`the file is not a readable PNG (decoded scanline size is ${decoded.length}, expected ${expectedDecodedBytes})`);
+    }
+    for (let row = 0; row < height; row += 1) {
+        if (decoded[row * scanlineBytes] > 4) {
+            throw new Error(`the file is not a readable PNG (invalid filter byte on scanline ${row + 1})`);
+        }
+    }
+    return { bytes, width, height, sizeBytes: bytes.length };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctrl-spc/cs",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "CTRL+SPC — minimal, reliable per-machine agent presence. Sign-in, auto-start, agent detection, heartbeat presence, and ping acknowledgement.",
   "engines": {
     "node": ">=22"