@compilr-dev/sdk 0.9.6 → 0.9.8

package/dist/guide/guide-tool.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Guide Tool Factory — creates an environment-aware compilr_guide tool.
+ *
+ * The tool definition lives in the SDK. Each host app (CLI, Desktop)
+ * registers environment-specific content via additionalEntries.
+ */
+import type { GuideToolConfig } from './types.js';
+interface GuideInput {
+    query?: string;
+    list_topics?: boolean;
+}
+/**
+ * Create the compilr_guide tool for the given environment.
+ *
+ * @example
+ * ```typescript
+ * // In CLI
+ * const guideTool = createGuideTool({
+ *   environment: 'cli',
+ *   additionalEntries: CLI_GUIDE_ENTRIES,
+ * });
+ *
+ * // In Desktop
+ * const guideTool = createGuideTool({
+ *   environment: 'desktop',
+ *   additionalEntries: DESKTOP_GUIDE_ENTRIES,
+ * });
+ * ```
+ */
+export declare function createGuideTool(config: GuideToolConfig): import("@compilr-dev/agents").Tool<GuideInput>;
+export {};

package/dist/guide/guide-tool.js

@@ -0,0 +1,90 @@
+/**
+ * Guide Tool Factory — creates an environment-aware compilr_guide tool.
+ *
+ * The tool definition lives in the SDK. Each host app (CLI, Desktop)
+ * registers environment-specific content via additionalEntries.
+ */
+import { defineTool } from '@compilr-dev/agents';
+import { SHARED_GUIDE_ENTRIES } from './shared-content.js';
+import { searchGuideEntries } from './search.js';
+/**
+ * Create the compilr_guide tool for the given environment.
+ *
+ * @example
+ * ```typescript
+ * // In CLI
+ * const guideTool = createGuideTool({
+ *   environment: 'cli',
+ *   additionalEntries: CLI_GUIDE_ENTRIES,
+ * });
+ *
+ * // In Desktop
+ * const guideTool = createGuideTool({
+ *   environment: 'desktop',
+ *   additionalEntries: DESKTOP_GUIDE_ENTRIES,
+ * });
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+export function createGuideTool(config) {
+    // Merge shared + environment-specific content
+    const allEntries = [...SHARED_GUIDE_ENTRIES, ...(config.additionalEntries ?? [])];
+    const envLabel = config.environment === 'desktop' ? 'Desktop' : 'CLI';
+    return defineTool({
+        name: 'compilr_guide',
+        description: `Get documentation about Compilr Dev ${envLabel} features and capabilities. ` +
+            `Use this to answer user questions about how to use the ${envLabel.toLowerCase()}. ` +
+            'Query by topic (e.g., "creating-project", "team-agents", "image-support") or ' +
+            'set list_topics=true to see all available topics.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Topic or keyword to look up. Examples: "creating-project", "team-agents", "permissions", "image-support"',
+                },
+                list_topics: {
+                    type: 'boolean',
+                    description: 'Set to true to list all available guide topics',
+                },
+            },
+        },
+        execute: (input) => {
+            if (input.list_topics) {
+                const topics = allEntries.map((e) => `- ${e.id} — ${e.title}`).join('\n');
+                return Promise.resolve({
+                    success: true,
+                    result: {
+                        output: `Available guide topics (${envLabel}):\n\n${topics}`,
+                    },
+                });
+            }
+            if (!input.query) {
+                return Promise.resolve({
+                    success: true,
+                    result: {
+                        output: 'Provide a query (topic or keyword) or set list_topics=true to see all topics.',
+                    },
+                });
+            }
+            const results = searchGuideEntries(allEntries, input.query);
+            if (results.length === 0) {
+                const topics = allEntries.map((e) => e.id).join(', ');
+                return Promise.resolve({
+                    success: true,
+                    result: {
+                        output: `No guide found for "${input.query}".\n\nAvailable topics: ${topics}`,
+                    },
+                });
+            }
+            const formatted = results
+                .map((entry) => `## ${entry.title}\n\n${entry.content}`)
+                .join('\n\n---\n\n');
+            return Promise.resolve({
+                success: true,
+                result: { output: formatted },
+            });
+        },
+        silent: true,
+    });
+}

package/dist/guide/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Guide module — environment-aware documentation tool.
+ */
+export { createGuideTool } from './guide-tool.js';
+export { SHARED_GUIDE_ENTRIES } from './shared-content.js';
+export { searchGuideEntries, topicToGuideEntry } from './search.js';
+export type { GuideEntry, ContentTopic, ContentSection, GuideToolConfig } from './types.js';

package/dist/guide/index.js

@@ -0,0 +1,6 @@
+/**
+ * Guide module — environment-aware documentation tool.
+ */
+export { createGuideTool } from './guide-tool.js';
+export { SHARED_GUIDE_ENTRIES } from './shared-content.js';
+export { searchGuideEntries, topicToGuideEntry } from './search.js';

package/dist/guide/search.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Guide search — finds relevant entries by query.
+ */
+import type { GuideEntry } from './types.js';
+/**
+ * Search guide entries by keyword, topic ID, or free text.
+ * Returns up to maxResults matches, ranked by relevance.
+ */
+export declare function searchGuideEntries(entries: GuideEntry[], query: string, maxResults?: number): GuideEntry[];
+/**
+ * Convert a ContentTopic to a GuideEntry (plain text).
+ */
+export declare function topicToGuideEntry(topic: {
+    id: string;
+    title: string;
+    keywords: string[];
+    sections: Array<{
+        title?: string;
+        items: string[];
+    }>;
+}): GuideEntry;

package/dist/guide/search.js

@@ -0,0 +1,62 @@
+/**
+ * Guide search — finds relevant entries by query.
+ */
+/**
+ * Search guide entries by keyword, topic ID, or free text.
+ * Returns up to maxResults matches, ranked by relevance.
+ */
+export function searchGuideEntries(entries, query, maxResults = 3) {
+    const q = query.toLowerCase().trim();
+    if (!q)
+        return [];
+    // 1. Exact ID match
+    const exactMatch = entries.find((e) => e.id === q);
+    if (exactMatch)
+        return [exactMatch];
+    // 2. Command match (e.g., "/design" → "skill-design", or "design")
+    const cmdQuery = q.startsWith('/') ? q : `/${q}`;
+    const cmdMatch = entries.find((e) => e.keywords.includes(cmdQuery) || e.keywords.includes(q));
+    if (cmdMatch)
+        return [cmdMatch];
+    // 3. Keyword + title + content search with scoring
+    const scored = entries
+        .map((e) => {
+        let score = 0;
+        // Keyword match (strongest signal)
+        if (e.keywords.some((k) => k === q))
+            score += 10;
+        if (e.keywords.some((k) => k.includes(q)))
+            score += 5;
+        if (e.keywords.some((k) => q.includes(k) && k.length > 2))
+            score += 3;
+        // Title match
+        if (e.title.toLowerCase().includes(q))
+            score += 4;
+        // Content match (weakest signal)
+        if (e.content.toLowerCase().includes(q))
+            score += 1;
+        return { entry: e, score };
+    })
+        .filter((s) => s.score > 0)
+        .sort((a, b) => b.score - a.score);
+    return scored.slice(0, maxResults).map((s) => s.entry);
+}
+/**
+ * Convert a ContentTopic to a GuideEntry (plain text).
+ */
+export function topicToGuideEntry(topic) {
+    const parts = [];
+    for (const section of topic.sections) {
+        if (section.title)
+            parts.push(section.title);
+        for (const item of section.items) {
+            parts.push(`  ${item}`);
+        }
+    }
+    return {
+        id: topic.id,
+        title: topic.title,
+        keywords: topic.keywords,
+        content: parts.join('\n'),
+    };
+}

package/dist/guide/shared-content.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Shared Guide Content — environment-agnostic topics.
+ *
+ * These apply to both CLI and Desktop. Each entry describes a feature
+ * that works the same way regardless of the host application.
+ */
+import type { GuideEntry } from './types.js';
+export declare const SHARED_GUIDE_ENTRIES: GuideEntry[];

package/dist/guide/shared-content.js

@@ -0,0 +1,267 @@
+/**
+ * Shared Guide Content — environment-agnostic topics.
+ *
+ * These apply to both CLI and Desktop. Each entry describes a feature
+ * that works the same way regardless of the host application.
+ */
+export const SHARED_GUIDE_ENTRIES = [
+    // ── Projects ────────────────────────────────────────────────────────────
+    {
+        id: 'creating-project',
+        title: 'Creating a New Project',
+        keywords: ['create', 'new', 'project', 'start'],
+        content: `To create a new project, use the project creation flow.
+
+You'll specify:
+- Project name and display name
+- Project type (software, research, book, business-plan, etc.)
+- Project path (where files live on disk)
+
+After creation, the project is set as active and agents can start working in it.
+
+7 project types are available:
+- software — Full-stack web apps, APIs, libraries
+- research — Academic papers, literature reviews
+- book — Books, chapters, outlines
+- course — Courses, curricula, lessons
+- business-plan — Business plans, pitch decks, financials
+- content-marketing — Content calendars, articles
+- tech-docs — Documentation, API references, tutorials`,
+    },
+    {
+        id: 'project-types',
+        title: 'Project Types',
+        keywords: [
+            'project type',
+            'software',
+            'research',
+            'book',
+            'business',
+            'course',
+            'content',
+            'tech-docs',
+        ],
+        content: `Each project type determines which agent roles, skills, and tools are most relevant:
+
+**software** — Agent roles: dev, pm, qa, arch. Skills: /design, /prd, /architecture, /scaffold, /build
+**research** — Agent roles: researcher, reviewer, writer. Skills: /outline, /literature-review, /methodology, /abstract
+**book** — Agent roles: editor, writer, reviewer. Skills: /outline, /chapter
+**course** — Agent roles: instructor, writer, reviewer. Skills: /outline, /lesson
+**business-plan** — Agent roles: analyst, strategist, writer. Skills: /business-vision, /market-analysis, /financial-model, /pitch
+**content-marketing** — Agent roles: writer, editor, strategist. Skills: /editorial-calendar, /article
+**tech-docs** — Agent roles: writer, dev, reviewer. Skills: /getting-started, /api-reference, /tutorial
+
+All project types support: teams, backlog, documents, knowledge base, file references, anchors.`,
+    },
+    {
+        id: 'importing-project',
+        title: 'Importing an Existing Project',
+        keywords: ['import', 'existing', 'project', 'folder'],
+        content: `You can import an existing project directory. The system will:
+1. Detect the project type from its contents
+2. Create a project entry in the database
+3. Read COMPILR.md if present (project context for the agent)
+4. Set it as the active project
+
+The agent then has context about your project and can help immediately.`,
+    },
+    {
+        id: 'switching-projects',
+        title: 'Switching Projects',
+        keywords: ['switch', 'change', 'project', 'select'],
+        content: `You can switch between projects at any time. When you switch:
+- The active project changes
+- Agents get the new project's context (COMPILR.md, anchors, KB)
+- Existing conversations are preserved (per-project)`,
+    },
+    // ── Teams & Agents ──────────────────────────────────────────────────────
+    {
+        id: 'team-agents',
+        title: 'Team Agents',
+        keywords: ['team', 'agents', '$agent', 'mention', 'role', 'specialist'],
+        content: `Team agents are specialized AI assistants with different roles and expertise.
+
+Use $agent to mention an agent (e.g., "$arch review this design", "$qa write tests").
+
+Available roles:
+- $dev — Software developer (coding, debugging)
+- $pm — Product manager (requirements, priorities)
+- $qa — QA engineer (testing, quality)
+- $arch — Architect (design, patterns, decisions)
+- $writer — Technical writer (docs, README)
+- $researcher — Research assistant (literature, analysis)
+- $reviewer — Code/content reviewer
+- $editor — Content editor (prose, structure)
+- $analyst — Data/business analyst
+- $strategist — Strategy and planning
+- $instructor — Teaching and course design
+
+Each role has a tailored system prompt and tool set.`,
+    },
+    {
+        id: 'coordinator-mode',
+        title: 'Coordinator Mode',
+        keywords: ['coordinator', 'delegation', 'delegate', 'background', 'multi-agent'],
+        content: `Coordinator mode allows one agent to delegate tasks to others.
+
+The coordinator can:
+- delegate_background: Send a task to another agent to run in background
+- delegation_status: Check on running delegations
+- Receive results when delegated tasks complete
+
+Useful for: code review ($qa), documentation ($writer), architecture analysis ($arch).
+
+The delegated agent runs independently and returns results to the coordinator.`,
+    },
+    // ── Skills ──────────────────────────────────────────────────────────────
+    {
+        id: 'skills-overview',
+        title: 'Skills Overview',
+        keywords: ['skills', 'slash', 'command', '/'],
+        content: `Skills are pre-built prompts that guide the agent through specific workflows.
+
+Use them by typing / followed by the skill name (e.g., /design, /build).
+
+Skills vary by project type. Software projects have: /design, /prd, /architecture, /scaffold, /build, /backlog, /session-notes.
+
+Research projects have: /outline, /literature-review, /methodology, /abstract.
+
+Business projects have: /business-vision, /market-analysis, /financial-model, /pitch.
+
+Skills can be combined with your own instructions: type /design then add context.`,
+    },
+    // ── Models & Providers ──────────────────────────────────────────────────
+    {
+        id: 'models',
+        title: 'Models and Providers',
+        keywords: ['model', 'provider', 'claude', 'openai', 'gemini', 'ollama', 'llm'],
+        content: `Compilr Dev supports multiple LLM providers:
+
+- Claude (Anthropic) — Claude Opus, Sonnet, Haiku
+- OpenAI — GPT-4o, GPT-4o-mini
+- Gemini (Google) — Gemini 2.5 Pro, Flash
+- Ollama — Local models (llama, codellama, etc.)
+- Together, Groq, Fireworks, Perplexity, OpenRouter
+
+Each provider requires an API key (except Ollama which runs locally).
+Models are organized by tier: premium, balanced, fast.`,
+    },
+    // ── Context & Memory ────────────────────────────────────────────────────
+    {
+        id: 'file-references',
+        title: 'File References (@file)',
+        keywords: ['file', 'reference', '@', 'attach', 'mention'],
+        content: `Reference files in your messages with @filename.
+
+Examples:
+  @src/index.ts — Agent reads this file for context
+  @package.json — Agent checks dependencies
+
+The agent will use its tools to read the referenced files.`,
+    },
+    {
+        id: 'compilr-md',
+        title: 'COMPILR.md — Project Context',
+        keywords: ['compilr.md', 'context', 'project', 'instructions'],
+        content: `COMPILR.md is a markdown file in your project root that gives the agent context.
+
+It can include:
+- Project description and goals
+- Tech stack and dependencies
+- Coding conventions
+- Build/test commands
+- Important file locations
+
+The agent reads this on every conversation to understand your project.
+Create one manually or let the agent generate it.`,
+    },
+    {
+        id: 'knowledge-base',
+        title: 'Knowledge Base',
+        keywords: ['knowledge', 'kb', 'reference', 'docs', 'upload', 'pin'],
+        content: `The knowledge base stores reference documents for your project.
+
+You can add:
+- Files (code, markdown, text, PDF, images)
+- Pasted text snippets
+- URLs (web page content imported)
+
+Pin important files to include them in every agent conversation.
+Unpinned files are available on-demand (agent uses view tools).
+
+Images in the KB can be viewed by the agent using the view_image tool.`,
+    },
+    {
+        id: 'context-management',
+        title: 'Context Management',
+        keywords: ['context', 'tokens', 'compaction', 'observation', 'masking', 'window'],
+        content: `The agent manages its context window automatically:
+
+- Observation masking: Old tool results replaced with compact summaries after a few turns
+- Image masking: Old images replaced with text placeholders (saves 1000+ tokens per image)
+- Tool output compression: Large outputs compressed by 60-90% (git, npm, file listings)
+- Smart windowing: Oldest messages compacted when context fills up
+
+You can see context utilization in the status bar or via /context.`,
+    },
+    // ── Permissions ─────────────────────────────────────────────────────────
+    {
+        id: 'permissions',
+        title: 'Permissions',
+        keywords: ['permission', 'approve', 'deny', 'auto-accept', 'security'],
+        content: `Agents ask permission before running potentially dangerous tools.
+
+Permission modes:
+- Normal — Agent asks before bash, edit, write operations
+- Auto-accept — Automatically approve all tool calls (faster, less safe)
+
+You can set per-tool rules (always allow, always deny, always ask).
+
+In restricted mode (untrusted workspace), bash/edit/write are blocked entirely.`,
+    },
+    // ── Images ──────────────────────────────────────────────────────────────
+    {
+        id: 'image-support',
+        title: 'Image Support',
+        keywords: ['image', 'screenshot', 'picture', 'paste', 'vision', 'multimodal'],
+        content: `You can send images to agents for visual analysis.
+
+Supported formats: PNG, JPEG, GIF, WebP.
+
+Images are automatically resized to max 1568px (Claude's recommended max) to save tokens.
+After a few turns, images are replaced with text placeholders to further reduce token cost.
+
+The agent can also view image files from disk using the view_image tool.
+
+All major providers support images: Claude, OpenAI GPT-4o, Gemini.`,
+    },
+    // ── Workspace Trust ─────────────────────────────────────────────────────
+    {
+        id: 'workspace-trust',
+        title: 'Workspace Trust',
+        keywords: ['trust', 'restricted', 'security', 'untrusted', 'safe'],
+        content: `When you open a project for the first time, you're asked to trust it.
+
+Trusted projects: Full agent capabilities — bash, file editing, terminal.
+Restricted projects: Read-only — agents can read files and answer questions but cannot run commands or modify files.
+
+You can change trust status by clicking the "Restricted" badge in the status bar.
+
+Trust is inherited: if you trust /projects/myapp, all subdirectories are also trusted.`,
+    },
+    // ── Anchors ─────────────────────────────────────────────────────────────
+    {
+        id: 'anchors',
+        title: 'Anchors — Persistent Context',
+        keywords: ['anchor', 'pin', 'persistent', 'important', 'remember'],
+        content: `Anchors are persistent notes that stay in the agent's context across conversations.
+
+Use them for:
+- Architecture decisions ("We chose PostgreSQL because...")
+- Important conventions ("All API routes use camelCase")
+- Work-in-progress notes ("Auth module is half-done, don't touch")
+
+Anchors survive session restarts and project switches.
+The agent sees them in every conversation.`,
+    },
+];

package/dist/guide/types.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Guide types — shared across SDK, CLI, and Desktop.
+ */
+/**
+ * A single guide entry the agent can return to the user.
+ */
+export interface GuideEntry {
+    id: string;
+    title: string;
+    keywords: string[];
+    content: string;
+}
+/**
+ * Structured content topic (used for tutorials in CLI, converted to GuideEntry for the tool).
+ */
+export interface ContentSection {
+    title?: string;
+    items: string[];
+}
+export interface ContentTopic {
+    id: string;
+    title: string;
+    keywords: string[];
+    sections: ContentSection[];
+}
+/**
+ * Configuration for the guide tool factory.
+ */
+export interface GuideToolConfig {
+    /** Which environment the tool is running in */
+    environment: 'cli' | 'desktop';
+    /** Additional environment-specific content to merge with shared content */
+    additionalEntries?: GuideEntry[];
+}

package/dist/guide/types.js

@@ -0,0 +1,4 @@
+/**
+ * Guide types — shared across SDK, CLI, and Desktop.
+ */
+export {};

package/dist/index.d.ts

@@ -58,8 +58,10 @@ 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 { createGuideTool, SHARED_GUIDE_ENTRIES, searchGuideEntries, topicToGuideEntry, } from './guide/index.js';
+export type { GuideEntry, ContentTopic, ContentSection, GuideToolConfig } from './guide/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

@@ -129,9 +129,13 @@ export { createSQLiteRepositories, SQLiteProjectRepository, SQLiteWorkItemReposi
 // =============================================================================
 export { createAskUserTool, createAskUserSimpleTool } from './tools/index.js';
 // =============================================================================
+// Guide Tool (environment-aware documentation)
+// =============================================================================
+export { createGuideTool, SHARED_GUIDE_ENTRIES, searchGuideEntries, topicToGuideEntry, } from './guide/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.8",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",