@compilr-dev/sdk 0.9.5 → 0.9.7

package/dist/compressors/bash.js

@@ -19,23 +19,19 @@ export function compressBashOutput(command, stdout) {
         return compressGitLog(stdout);
     if (cmd.match(/^git\s+diff/))
         return compressGitDiff(stdout);
-    if (cmd.match(/^git\s+(add|commit|push|pull|fetch|merge|rebase|checkout|switch|branch)/))
-        return compressGitAction(stdout);
+    // git write commands (add, commit, push, pull, merge, rebase, checkout, switch, branch)
+    // — leave uncompressed. These are side-effect commands that cannot be re-run,
+    // and the agent needs to see the full result to confirm what happened.
     // npm/yarn/pnpm
-    if (cmd.match(/^(npm|yarn|pnpm)\s+install/))
-        return compressNpmInstall(stdout);
+    // npm install — side-effect command, leave uncompressed
     if (cmd.match(/^(npm|yarn|pnpm)\s+(test|run\s+test)/))
         return compressTestOutput(stdout);
-    if (cmd.match(/^(npm|yarn|pnpm)\s+run\s+(lint|eslint)/))
-        return compressLintOutput(stdout);
-    if (cmd.match(/^(npm|yarn|pnpm)\s+run\s+(build|tsc)/))
-        return compressBuildOutput(stdout);
+    // lint output — leave uncompressed. Agent needs every error location to fix code.
+    // npm build — side-effect command, leave uncompressed
     // Direct test runners
     if (cmd.match(/^(jest|vitest|mocha|pytest|cargo\s+test|go\s+test)/))
         return compressTestOutput(stdout);
-    // Direct linters
-    if (cmd.match(/^(eslint|tsc|ruff|cargo\s+clippy|golangci-lint)/))
-        return compressLintOutput(stdout);
+    // Direct linters — leave uncompressed. Agent needs every error to fix code.
     // ls (strip metadata, keep filenames)
     if (cmd.match(/^ls\b/))
         return compressLsOutput(stdout);
@@ -48,130 +44,181 @@ export function compressBashOutput(command, stdout) {
 }
 // ─── Git Status ─────────────────────────────────────────────────────────────
 function compressGitStatus(output) {
-    const lines = output.split('\n').filter((l) => l.trim());
-    if (lines.length <= 20)
-        return output;
-    const sections = [];
-    let current = null;
-    for (const line of lines) {
-        if (line.startsWith('On branch') ||
-            line.startsWith('Your branch') ||
-            line.startsWith('HEAD detached')) {
-            sections.push({ header: line, files: [] });
-        }
-        else if (line.match(/^(Changes|Untracked|Unmerged)/)) {
-            current = { header: line, files: [] };
-            sections.push(current);
-        }
-        else if (current &&
-            (line.startsWith('\t') || line.match(/^\s+(modified|new file|deleted|renamed)/))) {
-            current.files.push(line.trim());
-        }
-    }
-    // Rebuild with capped file lists
-    const maxFilesPerSection = 15;
     const result = [];
-    for (const section of sections) {
-        result.push(section.header);
-        const shown = section.files.slice(0, maxFilesPerSection);
-        for (const f of shown)
-            result.push(`  ${f}`);
-        if (section.files.length > maxFilesPerSection) {
-            result.push(`  ... +${String(section.files.length - maxFilesPerSection)} more files`);
+    for (const line of output.split('\n')) {
+        const trimmed = line.trim();
+        // Skip empty lines
+        if (!trimmed)
+            continue;
+        // Skip git hints (noise — agent doesn't need instructions on how to use git)
+        if (trimmed.startsWith('(use "git') ||
+            trimmed.startsWith('(create/copy files') ||
+            trimmed.includes('(use "git add') ||
+            trimmed.includes('(use "git restore') ||
+            trimmed.includes('(use "git checkout') ||
+            trimmed.includes('(use "git reset') ||
+            trimmed.includes('(use "git pull') ||
+            trimmed.includes('(use "git push')) {
+            continue;
+        }
+        // "nothing to commit, working tree clean" — keep and stop
+        if (trimmed.includes('nothing to commit') && trimmed.includes('working tree clean')) {
+            result.push(trimmed);
+            break;
         }
+        result.push(line);
     }
-    return result.join('\n');
+    return result.length > 0 ? result.join('\n') : output;
 }
 // ─── Git Log ────────────────────────────────────────────────────────────────
 function compressGitLog(output) {
     const lines = output.split('\n');
-    if (lines.length <= 30)
+    if (lines.length <= 10)
         return output;
-    // Keep first 25 lines (recent commits), summarize the rest
-    const kept = lines.slice(0, 25);
-    const remaining = lines.slice(25).filter((l) => l.match(/^commit\s/));
-    if (remaining.length > 0) {
-        kept.push(`\n... +${String(remaining.length)} older commits omitted`);
+    // Condense each commit to one line: hash message (date) <author>
+    // Strips verbose Author/Date/body lines, keeps all commits visible.
+    // Inspired by RTK's --pretty=format:%h %s (%ar) <%an> approach.
+    const result = [];
+    let currentHash = '';
+    let currentAuthor = '';
+    let currentDate = '';
+    let currentMessage = '';
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (line.startsWith('commit ')) {
+            // Flush previous commit
+            if (currentHash) {
+                result.push(formatCommitLine(currentHash, currentMessage, currentDate, currentAuthor));
+            }
+            currentHash = trimmed.replace('commit ', '').slice(0, 8);
+            currentAuthor = '';
+            currentDate = '';
+            currentMessage = '';
+        }
+        else if (trimmed.startsWith('Author:')) {
+            // Extract just the name (drop email)
+            const match = trimmed.match(/Author:\s*(.+?)(?:\s*<.*>)?$/);
+            currentAuthor = match ? match[1].trim() : trimmed.replace('Author:', '').trim();
+        }
+        else if (trimmed.startsWith('Date:')) {
+            currentDate = trimmed.replace('Date:', '').trim();
+        }
+        else if (trimmed &&
+            !trimmed.startsWith('Merge:') &&
+            !trimmed.startsWith('Signed-off-by:') &&
+            !trimmed.startsWith('Co-authored-by:') &&
+            !trimmed.startsWith('Co-Authored-By:')) {
+            // First non-empty body line = commit message
+            if (!currentMessage) {
+                currentMessage = trimmed;
+            }
+        }
     }
-    return kept.join('\n');
+    // Flush last commit
+    if (currentHash) {
+        result.push(formatCommitLine(currentHash, currentMessage, currentDate, currentAuthor));
+    }
+    return result.join('\n');
+}
+function formatCommitLine(hash, message, date, author) {
+    // Truncate message to 72 chars
+    const msg = message.length > 72 ? message.slice(0, 69) + '...' : message;
+    // Shorten date: "Mon Apr 20 12:00:00 2026 +0200" → "Apr 20"
+    const shortDate = shortenDate(date);
+    return `${hash} ${msg} (${shortDate}) <${author}>`;
+}
+function shortenDate(date) {
+    // Try to extract "Mon Day" from various git date formats
+    const match = date.match(/(\w{3})\s+(\d{1,2})/);
+    if (match)
+        return `${match[1]} ${match[2]}`;
+    // Fallback: return first 10 chars
+    return date.slice(0, 10).trim();
 }
 // ─── Git Diff ───────────────────────────────────────────────────────────────
 function compressGitDiff(output) {
     const lines = output.split('\n');
-    if (lines.length <= 50)
+    if (lines.length <= 20)
         return output;
-    // Keep diff headers and first N lines of each file, collapse large hunks
+    // Compact diff inspired by RTK: show file names, hunk headers, +/- lines
+    // with per-hunk truncation and per-file +N -N summaries.
     const result = [];
     let currentFile = '';
-    let hunkLines = 0;
-    const maxHunkLines = 30;
+    let added = 0;
+    let removed = 0;
+    let inHunk = false;
+    let hunkShown = 0;
+    let hunkSkipped = 0;
+    const maxHunkLines = 50;
+    const maxTotalLines = 300;
     for (const line of lines) {
         if (line.startsWith('diff --git')) {
-            currentFile = line;
-            hunkLines = 0;
-            result.push(line);
+            // Flush previous hunk/file
+            if (hunkSkipped > 0) {
+                result.push(`  ... (${String(hunkSkipped)} lines truncated)`);
+                hunkSkipped = 0;
+            }
+            if (currentFile && (added > 0 || removed > 0)) {
+                result.push(`  +${String(added)} -${String(removed)}`);
+            }
+            // Start new file — extract filename
+            currentFile = line.split(' b/')[1] ?? 'unknown';
+            result.push(`\n${currentFile}`);
+            added = 0;
+            removed = 0;
+            inHunk = false;
+            hunkShown = 0;
         }
-        else if (line.startsWith('---') || line.startsWith('+++') || line.startsWith('@@')) {
-            hunkLines = 0;
-            result.push(line);
+        else if (line.startsWith('@@')) {
+            if (hunkSkipped > 0) {
+                result.push(`  ... (${String(hunkSkipped)} lines truncated)`);
+                hunkSkipped = 0;
+            }
+            inHunk = true;
+            hunkShown = 0;
+            result.push(`  ${line}`);
         }
-        else if (line.startsWith('+') || line.startsWith('-') || line.startsWith(' ')) {
-            hunkLines++;
-            if (hunkLines <= maxHunkLines) {
-                result.push(line);
+        else if (inHunk) {
+            if (line.startsWith('+') && !line.startsWith('+++')) {
+                added++;
+                if (hunkShown < maxHunkLines) {
+                    result.push(`  ${line}`);
+                    hunkShown++;
+                }
+                else
+                    hunkSkipped++;
             }
-            else if (hunkLines === maxHunkLines + 1) {
-                result.push(`... (hunk truncated, ${currentFile.split(' b/')[1] ?? 'file'} continues)`);
+            else if (line.startsWith('-') && !line.startsWith('---')) {
+                removed++;
+                if (hunkShown < maxHunkLines) {
+                    result.push(`  ${line}`);
+                    hunkShown++;
+                }
+                else
+                    hunkSkipped++;
+            }
+            else if (hunkShown < maxHunkLines && !line.startsWith('\\')) {
+                if (hunkShown > 0) {
+                    result.push(`  ${line}`);
+                    hunkShown++;
+                }
             }
         }
-        else {
-            result.push(line);
+        if (result.length >= maxTotalLines) {
+            result.push('\n... (more changes truncated)');
+            break;
         }
     }
-    return result.join('\n');
-}
-// ─── Git Action (add, commit, push, pull, etc.) ─────────────────────────────
-function compressGitAction(output) {
-    const lines = output.split('\n').filter((l) => l.trim());
-    if (lines.length <= 15)
-        return output;
-    // Keep summary lines, strip verbose file lists
-    const important = lines.filter((l) => l.match(/^(\[|To |From |Already|Everything|Branch|Updating|Fast-forward|CONFLICT|error:|fatal:|warning:|\s*\d+ file|create mode|delete mode)/) ||
-        l.includes('->') ||
-        l.includes('insertions') ||
-        l.includes('deletions'));
-    if (important.length > 0 && important.length < lines.length) {
-        const omitted = lines.length - important.length;
-        important.push(`(${String(omitted)} lines of detail omitted)`);
-        return important.join('\n');
+    // Flush last file
+    if (hunkSkipped > 0) {
+        result.push(`  ... (${String(hunkSkipped)} lines truncated)`);
     }
-    return output;
+    if (currentFile && (added > 0 || removed > 0)) {
+        result.push(`  +${String(added)} -${String(removed)}`);
+    }
+    return result.join('\n');
 }
 // ─── npm install ────────────────────────────────────────────────────────────
-function compressNpmInstall(output) {
-    const lines = output.split('\n');
-    if (lines.length <= 10)
-        return output;
-    // Keep: added/removed/changed summary, warnings, errors
-    // Strip: progress bars, individual package resolutions, timing
-    const kept = lines.filter((l) => {
-        const t = l.trim();
-        if (!t)
-            return false;
-        if (t.startsWith('npm warn') || t.startsWith('npm error') || t.startsWith('npm ERR'))
-            return true;
-        if (t.match(/^added \d|^removed \d|^changed \d|^up to date/))
-            return true;
-        if (t.includes('vulnerabilit'))
-            return true;
-        if (t.startsWith('found '))
-            return true;
-        return false;
-    });
-    if (kept.length === 0)
-        return output; // Couldn't parse — return original
-    return kept.join('\n');
-}
 // ─── Test Output ────────────────────────────────────────────────────────────
 function compressTestOutput(output) {
     const lines = output.split('\n');
@@ -217,83 +264,7 @@ function compressTestOutput(output) {
     return result.join('\n');
 }
 // ─── Lint Output ────────────────────────────────────────────────────────────
-function compressLintOutput(output) {
-    const lines = output.split('\n');
-    if (lines.length <= 15)
-        return output;
-    // Group errors by rule, cap per rule
-    const errors = [];
-    const warnings = [];
-    const summaryLines = [];
-    const ruleCount = new Map();
-    const maxPerRule = 5;
-    for (const line of lines) {
-        const t = line.trim();
-        // Summary lines
-        if (t.match(/^✖|^\d+ problem|^\d+ error|^\d+ warning|^error:|^warning:/i)) {
-            summaryLines.push(line);
-            continue;
-        }
-        // ESLint-style: "file:line:col  error  message  rule"
-        const ruleMatch = t.match(/\s+(error|warning)\s+.+\s+(\S+)$/);
-        if (ruleMatch) {
-            const rule = ruleMatch[2];
-            const count = (ruleCount.get(rule) ?? 0) + 1;
-            ruleCount.set(rule, count);
-            if (count <= maxPerRule) {
-                if (ruleMatch[1] === 'error')
-                    errors.push(line);
-                else
-                    warnings.push(line);
-            }
-            continue;
-        }
-        // TypeScript-style: "file(line,col): error TS..."
-        if (t.match(/error TS\d+/)) {
-            errors.push(line);
-            continue;
-        }
-    }
-    const result = [...errors, ...warnings.slice(0, 20)];
-    // Show rules that were capped
-    for (const [rule, count] of ruleCount) {
-        if (count > maxPerRule) {
-            result.push(`  ... +${String(count - maxPerRule)} more ${rule}`);
-        }
-    }
-    result.push(...summaryLines);
-    if (result.length < lines.length) {
-        return result.join('\n');
-    }
-    return output;
-}
 // ─── Build Output ───────────────────────────────────────────────────────────
-function compressBuildOutput(output) {
-    const lines = output.split('\n');
-    if (lines.length <= 20)
-        return output;
-    // Keep errors and summary, strip progress/compilation messages
-    const kept = lines.filter((l) => {
-        const t = l.trim();
-        if (!t)
-            return false;
-        if (t.match(/^(error|Error|ERROR|warning|Warning|WARN)/))
-            return true;
-        if (t.match(/^(✓|✗|✘|Done|Built|Compiled|Successfully|Failed|FAIL)/))
-            return true;
-        if (t.match(/error TS\d+/))
-            return true;
-        if (t.includes('bundle') && t.includes('kB'))
-            return true; // Bundle size info
-        return false;
-    });
-    if (kept.length > 0 && kept.length < lines.length * 0.7) {
-        const omitted = lines.length - kept.length;
-        kept.push(`(${String(omitted)} lines of build output omitted)`);
-        return kept.join('\n');
-    }
-    return output;
-}
 // ─── ls Output (strip metadata, keep filenames) ────────────────────────────
 function compressLsOutput(output) {
     const lines = output.split('\n');
@@ -328,16 +299,19 @@ function compressLsOutput(output) {
 // ─── curl / wget ────────────────────────────────────────────────────────────
 function compressCurlOutput(output) {
     const lines = output.split('\n');
-    if (lines.length <= 10)
-        return output;
-    // Strip progress bars (curl -# output), keep headers and body
+    // Strip progress bars and transfer stats, keep headers and body
     const kept = lines.filter((l) => {
         const t = l.trim();
-        // Strip progress indicators
-        if (t.match(/^[#\s]*\d+(\.\d+)?%/) || t.match(/^\s*\d+\s+\d+\s+\d+\s+\d+/))
+        if (!t)
+            return true; // Keep blank lines (may separate headers from body)
+        // Strip curl progress table header: "  % Total    % Received ..."
+        if (t.startsWith('% Total') || t.startsWith('Dload'))
+            return false;
+        // Strip progress rows: "  0     0    0     0    0     0..." or " 50  1200   50   600..."
+        if (t.match(/^\d+\s+\d+\s+\d+\s+\d+/))
             return false;
-        // Strip curl stats
-        if (t.match(/^\s*(Dload|Upload|Total|Spent|Left|Speed)/))
+        // Strip progress percentage lines
+        if (t.match(/^[#\s]*\d+(\.\d+)?%/))
             return false;
         return true;
     });

package/dist/index.d.ts

@@ -58,8 +58,8 @@ export { createSQLiteRepositories, SQLiteProjectRepository, SQLiteWorkItemReposi
 export type { SQLiteRepositories, CreateSQLiteRepositoriesOptions, ProjectDeleteHooks, ProjectRecord, WorkItemRecord, ProjectDocumentRecord, WorkItemCommentRecord, } from './platform/index.js';
 export { createAskUserTool, createAskUserSimpleTool } from './tools/index.js';
 export type { AskUserQuestion, AskUserInput, AskUserResult, AskUserHandler, AskUserSimpleInput, AskUserSimpleResult, AskUserSimpleHandler, } from './tools/index.js';
-export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, ProjectAnchorStore, } from './platform/index.js';
-export type { ProjectAnchorStoreConfig } from './platform/index.js';
+export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, createImageTools, ProjectAnchorStore, } from './platform/index.js';
+export type { ProjectAnchorStoreConfig, ImageToolsConfig, ImageResizer } from './platform/index.js';
 export { STEP_ORDER, GUIDED_STEP_CRITERIA, getNextStep, isValidTransition, getStepCriteria, formatStepDisplay, getStepNumber, } from './platform/index.js';
 export { platformSkills, designSkill, sketchSkill, prdSkill, refineSkill, refineItemSkill, architectureSkill, sessionNotesSkill, buildSkill, scaffoldSkill, outlineSkill, literatureReviewSkill, draftSectionSkill, peerReviewSkill, researchScaffoldSkill, businessVisionSkill, marketAnalysisSkill, competitorAnalysisSkill, financialModelSkill, pitchOutlineSkill, businessReviewSkill, brandSetupSkill, contentStrategySkill, contentCalendarSkill, createContentSkill, contentReviewSkill, curriculumDesignSkill, lessonPlanSkill, assessmentDesignSkill, courseReviewSkill, bookOutlineSkill, characterDesignSkill, plotThreadsSkill, sceneBreakdownSkill, bookReviewSkill, } from './skills/index.js';
 export { ACTION_REGISTRY, getActionsForContext, getActionById, resolveActionPrompt, buildContextSummary, getSuggestedRole, } from './actions/index.js';

package/dist/index.js

@@ -131,7 +131,7 @@ export { createAskUserTool, createAskUserSimpleTool } from './tools/index.js';
 // =============================================================================
 // Platform Tools (runtime — createPlatformTools factory + individual factories)
 // =============================================================================
-export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, ProjectAnchorStore, } from './platform/index.js';
+export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, createImageTools, ProjectAnchorStore, } from './platform/index.js';
 // =============================================================================
 // Platform Workflow (pure step-criteria logic)
 // =============================================================================

package/dist/platform/index.d.ts

@@ -5,7 +5,8 @@ export type { ProjectType, ProjectStatus, RepoPattern, WorkflowMode, LifecycleSt
 export type { IProjectRepository, IWorkItemRepository, IDocumentRepository, IPlanRepository, ICommentRepository, } from './repositories.js';
 export type { IAnchorService, IArtifactService, IEpisodeService, AnchorData, ArtifactType, ArtifactData, ArtifactSummaryData, WorkEpisode, ProjectWorkSummary, } from './services.js';
 export type { PlatformContext, PlatformToolsConfig, PlatformHooks } from './context.js';
-export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, } from './tools/index.js';
+export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, createImageTools, } from './tools/index.js';
+export type { ImageToolsConfig, ImageResizer } from './tools/index.js';
 export { createSQLiteRepositories, SQLiteProjectRepository, SQLiteWorkItemRepository, SQLiteDocumentRepository, SQLitePlanRepository, SQLiteCommentRepository, getDatabase, closeDatabase, closeAllDatabases, databaseExists, SCHEMA_VERSION, SCHEMA_SQL, } from './sqlite/index.js';
 export type { SQLiteRepositories, CreateSQLiteRepositoriesOptions, ProjectDeleteHooks, ProjectRecord, WorkItemRecord, ProjectDocumentRecord, WorkItemCommentRecord, } from './sqlite/index.js';
 export { ProjectAnchorStore } from './file-anchor-service.js';

package/dist/platform/index.js

@@ -2,7 +2,7 @@
  * Platform — Repository interfaces, data models, tools, and workflow.
  */
 // Platform tools (runtime)
-export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, } from './tools/index.js';
+export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, createImageTools, } from './tools/index.js';
 // SQLite implementations (concrete repositories)
 export { createSQLiteRepositories, SQLiteProjectRepository, SQLiteWorkItemRepository, SQLiteDocumentRepository, SQLitePlanRepository, SQLiteCommentRepository, getDatabase, closeDatabase, closeAllDatabases, databaseExists, SCHEMA_VERSION, SCHEMA_SQL, } from './sqlite/index.js';
 // File-based anchor service (shared by CLI and Desktop)

package/dist/platform/tools/image-tools.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Image Tools — View image files for visual analysis.
+ *
+ * 1 tool: view_image
+ *
+ * Returns image data as imageBlocks on ToolExecutionResult, which the agent
+ * injects as sibling content blocks alongside the tool_result message.
+ * This lets vision-capable LLMs see the image.
+ */
+/**
+ * Max dimension for resizing. Claude recommends 1568px max.
+ * Resizing is optional — only applied if a resizer function is provided.
+ */
+export declare const DEFAULT_MAX_DIMENSION = 1568;
+/**
+ * Optional image resizer function. Provided by the host environment
+ * (e.g., Electron's nativeImage, sharp, etc.)
+ */
+export interface ImageResizer {
+    resize(data: Uint8Array, maxDimension: number): Promise<{
+        data: Uint8Array;
+        width: number;
+        height: number;
+        mediaType: string;
+    }>;
+}
+export interface ImageToolsConfig {
+    /** Working directory for resolving relative paths */
+    cwd?: string;
+    /** Optional image resizer (e.g., nativeImage in Electron) */
+    resizer?: ImageResizer;
+    /** Max dimension for resize (default: 1568) */
+    maxDimension?: number;
+}
+export declare function createImageTools(config?: ImageToolsConfig): readonly [import("@compilr-dev/agents").Tool<{
+    path: string;
+}>];

package/dist/platform/tools/image-tools.js

@@ -0,0 +1,102 @@
+/**
+ * Image Tools — View image files for visual analysis.
+ *
+ * 1 tool: view_image
+ *
+ * Returns image data as imageBlocks on ToolExecutionResult, which the agent
+ * injects as sibling content blocks alongside the tool_result message.
+ * This lets vision-capable LLMs see the image.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { defineTool, createErrorResult } from '@compilr-dev/agents';
+/** Supported image MIME types */
+const IMAGE_EXTENSIONS = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+};
+/** Max file size: 10MB (base64 will be ~13MB, well within API limits) */
+const MAX_FILE_SIZE = 10 * 1024 * 1024;
+/**
+ * Max dimension for resizing. Claude recommends 1568px max.
+ * Resizing is optional — only applied if a resizer function is provided.
+ */
+export const DEFAULT_MAX_DIMENSION = 1568;
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+export function createImageTools(config = {}) {
+    const cwd = config.cwd ?? process.cwd();
+    const maxDimension = config.maxDimension ?? DEFAULT_MAX_DIMENSION;
+    const viewImageTool = defineTool({
+        name: 'view_image',
+        description: 'View an image file for visual analysis. Returns the image so you can see it. ' +
+            'Supports PNG, JPEG, GIF, and WebP formats.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Path to the image file (absolute or relative to working directory)',
+                },
+            },
+            required: ['path'],
+        },
+        execute: async (input) => {
+            // Resolve path
+            const filePath = path.isAbsolute(input.path) ? input.path : path.resolve(cwd, input.path);
+            // Validate file exists
+            if (!fs.existsSync(filePath)) {
+                return createErrorResult(`File not found: ${input.path}`);
+            }
+            // Validate extension
+            const ext = path.extname(filePath).toLowerCase();
+            const mediaType = IMAGE_EXTENSIONS[ext];
+            if (!mediaType) {
+                const supported = Object.keys(IMAGE_EXTENSIONS).join(', ');
+                return createErrorResult(`Unsupported image format: ${ext}. Supported formats: ${supported}`);
+            }
+            // Check file size
+            const stat = fs.statSync(filePath);
+            if (stat.size > MAX_FILE_SIZE) {
+                const sizeMB = (stat.size / (1024 * 1024)).toFixed(1);
+                return createErrorResult(`Image too large: ${sizeMB}MB (max 10MB)`);
+            }
+            // Read file
+            let imageData = fs.readFileSync(filePath);
+            let finalMediaType = mediaType;
+            let width;
+            let height;
+            // Optional resize
+            if (config.resizer) {
+                try {
+                    const resized = await config.resizer.resize(imageData, maxDimension);
+                    imageData = resized.data;
+                    width = resized.width;
+                    height = resized.height;
+                    finalMediaType = resized.mediaType;
+                }
+                catch {
+                    // Resize failed — use original data
+                }
+            }
+            const base64 = Buffer.from(imageData).toString('base64');
+            const filename = path.basename(filePath);
+            return {
+                success: true,
+                result: `Image loaded: ${filename} (${finalMediaType})`,
+                imageBlocks: [
+                    {
+                        data: base64,
+                        mediaType: finalMediaType,
+                        filename,
+                        width,
+                        height,
+                    },
+                ],
+            };
+        },
+    });
+    return [viewImageTool];
+}

package/dist/platform/tools/index.d.ts

@@ -1,20 +1,22 @@
 /**
  * Platform Tools — Factory function for all platform tools.
  *
- * Returns up to 33 tool definitions operating against async PlatformContext.
+ * Returns up to 34 tool definitions operating against async PlatformContext.
  * - 25 DB tools (always): project, workitem (incl. comment), document, plan, backlog
+ * - 1 image tool (always): view_image
  * - 3 anchor tools (if ctx.anchors provided)
  * - 4 artifact tools (if ctx.artifacts provided)
  * - 1 episode tool (if ctx.episodes provided)
  */
 import type { Tool } from '@compilr-dev/agents';
 import type { PlatformToolsConfig } from '../context.js';
+import type { ImageToolsConfig } from './image-tools.js';
 /**
  * Create all platform tools operating against the given context.
- * Returns 24 DB tools unconditionally, plus up to 8 service-based tools
- * if the optional anchors/artifacts/episodes services are provided.
+ * Returns 25 DB tools + 1 image tool unconditionally, plus up to 8 service-based
+ * tools if the optional anchors/artifacts/episodes services are provided.
  */
-export declare function createPlatformTools(config: PlatformToolsConfig): Tool<never>[];
+export declare function createPlatformTools(config: PlatformToolsConfig, imageConfig?: ImageToolsConfig): Tool<never>[];
 export { createProjectTools } from './project-tools.js';
 export { createWorkItemTools } from './workitem-tools.js';
 export { createDocumentTools } from './document-tools.js';
@@ -23,3 +25,5 @@ export { createBacklogTools } from './backlog-tools.js';
 export { createAnchorTools } from './anchor-tools.js';
 export { createArtifactTools } from './artifact-tools.js';
 export { createEpisodeTools } from './episode-tools.js';
+export { createImageTools } from './image-tools.js';
+export type { ImageToolsConfig, ImageResizer } from './image-tools.js';

package/dist/platform/tools/index.js

@@ -1,8 +1,9 @@
 /**
  * Platform Tools — Factory function for all platform tools.
  *
- * Returns up to 33 tool definitions operating against async PlatformContext.
+ * Returns up to 34 tool definitions operating against async PlatformContext.
  * - 25 DB tools (always): project, workitem (incl. comment), document, plan, backlog
+ * - 1 image tool (always): view_image
  * - 3 anchor tools (if ctx.anchors provided)
  * - 4 artifact tools (if ctx.artifacts provided)
  * - 1 episode tool (if ctx.episodes provided)
@@ -15,13 +16,14 @@ import { createBacklogTools } from './backlog-tools.js';
 import { createAnchorTools } from './anchor-tools.js';
 import { createArtifactTools } from './artifact-tools.js';
 import { createEpisodeTools } from './episode-tools.js';
+import { createImageTools } from './image-tools.js';
 /**
  * Create all platform tools operating against the given context.
- * Returns 24 DB tools unconditionally, plus up to 8 service-based tools
- * if the optional anchors/artifacts/episodes services are provided.
+ * Returns 25 DB tools + 1 image tool unconditionally, plus up to 8 service-based
+ * tools if the optional anchors/artifacts/episodes services are provided.
  */
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
-export function createPlatformTools(config) {
+export function createPlatformTools(config, imageConfig) {
     // Use Tool<never>[] to accept any Tool<T> — the generic parameter is only
     // relevant to execute() callers, not to the registry that stores them.
     const tools = [
@@ -30,6 +32,7 @@ export function createPlatformTools(config) {
         ...createDocumentTools(config),
         ...createPlanTools(config),
         ...createBacklogTools(config),
+        ...createImageTools({ cwd: config.cwd, ...imageConfig }),
     ];
     if (config.context.anchors) {
         tools.push(...createAnchorTools(config));
@@ -51,3 +54,4 @@ export { createBacklogTools } from './backlog-tools.js';
 export { createAnchorTools } from './anchor-tools.js';
 export { createArtifactTools } from './artifact-tools.js';
 export { createEpisodeTools } from './episode-tools.js';
+export { createImageTools } from './image-tools.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.9.5",
+  "version": "0.9.7",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",