@compilr-dev/sdk 0.9.7 → 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,6 +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 { 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';

package/dist/index.js

@@ -129,6 +129,10 @@ 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, createImageTools, ProjectAnchorStore, } from './platform/index.js';

package/package.json

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