@compilr-dev/sdk 0.9.6 → 0.9.7

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.6",
+  "version": "0.9.7",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",