@compilr-dev/sdk 0.2.13 → 0.2.14

package/dist/index.d.ts

@@ -51,12 +51,12 @@ export { MetaToolsRegistry, createMetaTools, META_TOOLS_SYSTEM_PROMPT_PREFIX, }
 export type { MetaToolStats, MetaTools, FallbackOptions } from './meta-tools/index.js';
 export { CapabilityManager, CAPABILITY_PACKS, FORBIDDEN_PACK_SUGGESTIONS, getPackCount, getAllPackIds, createLoadCapabilityTool, generateCapabilityCatalog, } from './capabilities/index.js';
 export type { CapabilityPack, CapabilityTier, LoadedCapability, CapabilityCatalogEntry, CapabilityLoadResult, CapabilityManagerConfig, } from './capabilities/index.js';
-export { SystemPromptBuilder, buildSystemPrompt, detectGitRepository, getModuleStats, ALL_MODULES, IDENTITY_MODULE, STYLE_MODULE, TASK_EXECUTION_MODULE, TODO_MANAGEMENT_MODULE, TOOL_USAGE_DIRECT_MODULE, TOOL_USAGE_HINTS_MODULE, PLATFORM_TOOL_HINTS_MODULE, FACTORY_TOOL_HINTS_MODULE, TOOL_USAGE_META_MODULE, DELEGATION_MODULE, GIT_SAFETY_MODULE, SUGGEST_MODULE, IMPORTANT_RULES_MODULE, ENVIRONMENT_MODULE, shouldIncludeModule, getEstimatedTokensForConditions, getTotalEstimatedTokens, } from './system-prompt/index.js';
+export { SystemPromptBuilder, buildSystemPrompt, detectGitRepository, getModuleStats, ALL_MODULES, IDENTITY_MODULE, STYLE_MODULE, TASK_EXECUTION_MODULE, TODO_MANAGEMENT_MODULE, TOOL_USAGE_DIRECT_MODULE, TOOL_USAGE_HINTS_MODULE, PLATFORM_TOOL_HINTS_MODULE, FACTORY_TOOL_HINTS_MODULE, TOOL_USAGE_META_MODULE, DELEGATION_MODULE, GIT_SAFETY_MODULE, SUGGEST_MODULE, IMPORTANT_RULES_MODULE, VISUAL_OUTPUT_MODULE, ENVIRONMENT_MODULE, shouldIncludeModule, getEstimatedTokensForConditions, getTotalEstimatedTokens, } from './system-prompt/index.js';
 export type { SystemPromptContext, BuildResult, SystemPromptModule, ModuleConditions, } from './system-prompt/index.js';
-export type { ProjectType, ProjectStatus, RepoPattern, WorkflowMode, LifecycleState, WorkItemType, WorkItemStatus, WorkItemPriority, GuidedStep, DocumentType, PlanStatus, Project, WorkItem, ProjectDocument, Plan, PlanSummary, PlanWithWorkItem, HistoryEntry, CreateProjectInput, UpdateProjectInput, ProjectListOptions, CreateWorkItemInput, UpdateWorkItemInput, QueryWorkItemsInput, CreateDocumentInput, UpdateDocumentInput, CreatePlanInput, UpdatePlanInput, ListPlansOptions, WorkItemQueryResult, ProjectListResult, BulkCreateItem, IProjectRepository, IWorkItemRepository, IDocumentRepository, IPlanRepository, IAnchorService, IArtifactService, IEpisodeService, AnchorData, ArtifactType, ArtifactData, ArtifactSummaryData, WorkEpisode, ProjectWorkSummary, PlatformContext, PlatformToolsConfig, PlatformHooks, StepCriteria, } from './platform/index.js';
-export { createSQLiteRepositories, SQLiteProjectRepository, SQLiteWorkItemRepository, SQLiteDocumentRepository, SQLitePlanRepository, getDatabase, closeDatabase, closeAllDatabases, databaseExists, SCHEMA_VERSION, SCHEMA_SQL, } from './platform/index.js';
-export type { SQLiteRepositories, CreateSQLiteRepositoriesOptions, ProjectDeleteHooks, ProjectRecord, WorkItemRecord, ProjectDocumentRecord, } from './platform/index.js';
-export { createAskUserTool, createAskUserSimpleTool, } from './tools/index.js';
+export type { ProjectType, ProjectStatus, RepoPattern, WorkflowMode, LifecycleState, WorkItemType, WorkItemStatus, WorkItemPriority, GuidedStep, DocumentType, PlanStatus, Project, WorkItem, ProjectDocument, Plan, PlanSummary, PlanWithWorkItem, HistoryEntry, CreateProjectInput, UpdateProjectInput, ProjectListOptions, CreateWorkItemInput, UpdateWorkItemInput, QueryWorkItemsInput, CreateDocumentInput, UpdateDocumentInput, CreatePlanInput, UpdatePlanInput, ListPlansOptions, WorkItemQueryResult, ProjectListResult, BulkCreateItem, WorkItemComment, CreateCommentInput, UpdateCommentInput, IProjectRepository, IWorkItemRepository, IDocumentRepository, IPlanRepository, ICommentRepository, IAnchorService, IArtifactService, IEpisodeService, AnchorData, ArtifactType, ArtifactData, ArtifactSummaryData, WorkEpisode, ProjectWorkSummary, PlatformContext, PlatformToolsConfig, PlatformHooks, StepCriteria, } from './platform/index.js';
+export { createSQLiteRepositories, SQLiteProjectRepository, SQLiteWorkItemRepository, SQLiteDocumentRepository, SQLitePlanRepository, SQLiteCommentRepository, getDatabase, closeDatabase, closeAllDatabases, databaseExists, SCHEMA_VERSION, SCHEMA_SQL, } from './platform/index.js';
+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';

package/dist/index.js

@@ -109,17 +109,17 @@ export {
 // Builder
 SystemPromptBuilder, buildSystemPrompt, detectGitRepository, getModuleStats, 
 // Module constants
-ALL_MODULES, IDENTITY_MODULE, STYLE_MODULE, TASK_EXECUTION_MODULE, TODO_MANAGEMENT_MODULE, TOOL_USAGE_DIRECT_MODULE, TOOL_USAGE_HINTS_MODULE, PLATFORM_TOOL_HINTS_MODULE, FACTORY_TOOL_HINTS_MODULE, TOOL_USAGE_META_MODULE, DELEGATION_MODULE, GIT_SAFETY_MODULE, SUGGEST_MODULE, IMPORTANT_RULES_MODULE, ENVIRONMENT_MODULE, 
+ALL_MODULES, IDENTITY_MODULE, STYLE_MODULE, TASK_EXECUTION_MODULE, TODO_MANAGEMENT_MODULE, TOOL_USAGE_DIRECT_MODULE, TOOL_USAGE_HINTS_MODULE, PLATFORM_TOOL_HINTS_MODULE, FACTORY_TOOL_HINTS_MODULE, TOOL_USAGE_META_MODULE, DELEGATION_MODULE, GIT_SAFETY_MODULE, SUGGEST_MODULE, IMPORTANT_RULES_MODULE, VISUAL_OUTPUT_MODULE, ENVIRONMENT_MODULE, 
 // Module utilities
 shouldIncludeModule, getEstimatedTokensForConditions, getTotalEstimatedTokens, } from './system-prompt/index.js';
 // =============================================================================
 // Platform SQLite Repositories (concrete implementations)
 // =============================================================================
-export { createSQLiteRepositories, SQLiteProjectRepository, SQLiteWorkItemRepository, SQLiteDocumentRepository, SQLitePlanRepository, getDatabase, closeDatabase, closeAllDatabases, databaseExists, SCHEMA_VERSION, SCHEMA_SQL, } from './platform/index.js';
+export { createSQLiteRepositories, SQLiteProjectRepository, SQLiteWorkItemRepository, SQLiteDocumentRepository, SQLitePlanRepository, SQLiteCommentRepository, getDatabase, closeDatabase, closeAllDatabases, databaseExists, SCHEMA_VERSION, SCHEMA_SQL, } from './platform/index.js';
 // =============================================================================
 // User Interaction Tools (ask_user, ask_user_simple)
 // =============================================================================
-export { createAskUserTool, createAskUserSimpleTool, } from './tools/index.js';
+export { createAskUserTool, createAskUserSimpleTool } from './tools/index.js';
 // =============================================================================
 // Platform Tools (runtime — createPlatformTools factory + individual factories)
 // =============================================================================

package/dist/platform/context.d.ts

@@ -4,7 +4,7 @@
  * Provides a single entry point for data access, abstracting over the
  * underlying storage backend (SQLite in CLI, PostgreSQL in web/API).
  */
-import type { IProjectRepository, IWorkItemRepository, IDocumentRepository, IPlanRepository } from './repositories.js';
+import type { IProjectRepository, IWorkItemRepository, IDocumentRepository, IPlanRepository, ICommentRepository } from './repositories.js';
 import type { IAnchorService, IArtifactService, IEpisodeService } from './services.js';
 export interface PlatformContext {
     readonly projects: IProjectRepository;
@@ -15,6 +15,7 @@ export interface PlatformContext {
     readonly anchors?: IAnchorService;
     readonly artifacts?: IArtifactService;
     readonly episodes?: IEpisodeService;
+    readonly comments?: ICommentRepository;
 }
 export interface PlatformHooks {
     /** Called when a project is resolved/selected as the current project */

package/dist/platform/index.d.ts

@@ -1,13 +1,13 @@
 /**
  * Platform — Repository interfaces, data models, tools, and workflow.
  */
-export type { ProjectType, ProjectStatus, RepoPattern, WorkflowMode, LifecycleState, WorkItemType, WorkItemStatus, WorkItemPriority, GuidedStep, DocumentType, PlanStatus, Project, WorkItem, ProjectDocument, Plan, PlanSummary, PlanWithWorkItem, HistoryEntry, CreateProjectInput, UpdateProjectInput, ProjectListOptions, CreateWorkItemInput, UpdateWorkItemInput, QueryWorkItemsInput, CreateDocumentInput, UpdateDocumentInput, CreatePlanInput, UpdatePlanInput, ListPlansOptions, WorkItemQueryResult, ProjectListResult, BulkCreateItem, } from './types.js';
-export type { IProjectRepository, IWorkItemRepository, IDocumentRepository, IPlanRepository, } from './repositories.js';
+export type { ProjectType, ProjectStatus, RepoPattern, WorkflowMode, LifecycleState, WorkItemType, WorkItemStatus, WorkItemPriority, GuidedStep, DocumentType, PlanStatus, Project, WorkItem, ProjectDocument, Plan, PlanSummary, PlanWithWorkItem, HistoryEntry, CreateProjectInput, UpdateProjectInput, ProjectListOptions, CreateWorkItemInput, UpdateWorkItemInput, QueryWorkItemsInput, CreateDocumentInput, UpdateDocumentInput, CreatePlanInput, UpdatePlanInput, ListPlansOptions, WorkItemQueryResult, ProjectListResult, BulkCreateItem, WorkItemComment, CreateCommentInput, UpdateCommentInput, } from './types.js';
+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 { createSQLiteRepositories, SQLiteProjectRepository, SQLiteWorkItemRepository, SQLiteDocumentRepository, SQLitePlanRepository, getDatabase, closeDatabase, closeAllDatabases, databaseExists, SCHEMA_VERSION, SCHEMA_SQL, } from './sqlite/index.js';
-export type { SQLiteRepositories, CreateSQLiteRepositoriesOptions, ProjectDeleteHooks, ProjectRecord, WorkItemRecord, ProjectDocumentRecord, } from './sqlite/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';
 export type { ProjectAnchorStoreConfig } from './file-anchor-service.js';
 export { STEP_ORDER, GUIDED_STEP_CRITERIA, getNextStep, isValidTransition, getStepCriteria, formatStepDisplay, getStepNumber, } from './workflow.js';

package/dist/platform/index.js

@@ -4,7 +4,7 @@
 // Platform tools (runtime)
 export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, } from './tools/index.js';
 // SQLite implementations (concrete repositories)
-export { createSQLiteRepositories, SQLiteProjectRepository, SQLiteWorkItemRepository, SQLiteDocumentRepository, SQLitePlanRepository, getDatabase, closeDatabase, closeAllDatabases, databaseExists, SCHEMA_VERSION, SCHEMA_SQL, } from './sqlite/index.js';
+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)
 export { ProjectAnchorStore } from './file-anchor-service.js';
 // Workflow (pure step-criteria logic)

package/dist/platform/repositories.d.ts

@@ -5,7 +5,7 @@
  * uses synchronous SQLite. This ensures compatibility with future async
  * backends (PostgreSQL, HTTP APIs).
  */
-import type { Project, WorkItem, ProjectDocument, Plan, PlanSummary, PlanWithWorkItem, HistoryEntry, CreateProjectInput, UpdateProjectInput, ProjectListOptions, CreateWorkItemInput, UpdateWorkItemInput, QueryWorkItemsInput, CreateDocumentInput, UpdateDocumentInput, CreatePlanInput, UpdatePlanInput, ListPlansOptions, WorkItemQueryResult, ProjectListResult, BulkCreateItem, ProjectStatus, WorkItemType, WorkItemStatus, DocumentType, PlanStatus } from './types.js';
+import type { Project, WorkItem, WorkItemComment, ProjectDocument, Plan, PlanSummary, PlanWithWorkItem, HistoryEntry, CreateProjectInput, UpdateProjectInput, ProjectListOptions, CreateWorkItemInput, UpdateWorkItemInput, QueryWorkItemsInput, CreateCommentInput, UpdateCommentInput, CreateDocumentInput, UpdateDocumentInput, CreatePlanInput, UpdatePlanInput, ListPlansOptions, WorkItemQueryResult, ProjectListResult, BulkCreateItem, ProjectStatus, WorkItemType, WorkItemStatus, DocumentType, PlanStatus } from './types.js';
 export interface IProjectRepository {
     create(input: CreateProjectInput): Promise<Project>;
     getById(id: number): Promise<Project | null>;
@@ -60,3 +60,11 @@ export interface IPlanRepository {
     linkWorkItem(planId: number, workItemId: number): Promise<Plan | null>;
     unlinkWorkItem(planId: number): Promise<Plan | null>;
 }
+export interface ICommentRepository {
+    create(input: CreateCommentInput): Promise<WorkItemComment>;
+    getById(id: number): Promise<WorkItemComment | null>;
+    listByWorkItem(workItemId: number): Promise<WorkItemComment[]>;
+    update(id: number, input: UpdateCommentInput): Promise<WorkItemComment | null>;
+    delete(id: number): Promise<boolean>;
+    countByWorkItem(workItemId: number): Promise<number>;
+}

package/dist/platform/sqlite/comment-repository.d.ts

@@ -0,0 +1,16 @@
+/**
+ * SQLite Comment Repository — Concrete implementation of ICommentRepository.
+ */
+import type Database from 'better-sqlite3';
+import type { ICommentRepository } from '../repositories.js';
+import type { WorkItemComment, CreateCommentInput, UpdateCommentInput } from '../types.js';
+export declare class SQLiteCommentRepository implements ICommentRepository {
+    private readonly db;
+    constructor(db: Database.Database);
+    create(input: CreateCommentInput): Promise<WorkItemComment>;
+    getById(id: number): Promise<WorkItemComment | null>;
+    listByWorkItem(workItemId: number): Promise<WorkItemComment[]>;
+    update(id: number, input: UpdateCommentInput): Promise<WorkItemComment | null>;
+    delete(id: number): Promise<boolean>;
+    countByWorkItem(workItemId: number): Promise<number>;
+}

package/dist/platform/sqlite/comment-repository.js

@@ -0,0 +1,62 @@
+/**
+ * SQLite Comment Repository — Concrete implementation of ICommentRepository.
+ */
+function recordToComment(record) {
+    return {
+        id: record.id,
+        workItemId: record.work_item_id,
+        projectId: record.project_id,
+        author: record.author,
+        content: record.content,
+        createdAt: new Date(record.created_at),
+        updatedAt: new Date(record.updated_at),
+    };
+}
+export class SQLiteCommentRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async create(input) {
+        const result = this.db
+            .prepare(`INSERT INTO work_item_comments (work_item_id, project_id, author, content)
+         VALUES (@work_item_id, @project_id, @author, @content)`)
+            .run({
+            work_item_id: input.work_item_id,
+            project_id: input.project_id,
+            author: input.author,
+            content: input.content,
+        });
+        const record = this.db
+            .prepare('SELECT * FROM work_item_comments WHERE id = ?')
+            .get(Number(result.lastInsertRowid));
+        return Promise.resolve(recordToComment(record));
+    }
+    async getById(id) {
+        const record = this.db.prepare('SELECT * FROM work_item_comments WHERE id = ?').get(id);
+        return Promise.resolve(record ? recordToComment(record) : null);
+    }
+    async listByWorkItem(workItemId) {
+        const records = this.db
+            .prepare('SELECT * FROM work_item_comments WHERE work_item_id = ? ORDER BY created_at ASC')
+            .all(workItemId);
+        return Promise.resolve(records.map(recordToComment));
+    }
+    async update(id, input) {
+        this.db
+            .prepare(`UPDATE work_item_comments SET content = @content, updated_at = CURRENT_TIMESTAMP WHERE id = @id`)
+            .run({ id, content: input.content });
+        const record = this.db.prepare('SELECT * FROM work_item_comments WHERE id = ?').get(id);
+        return Promise.resolve(record ? recordToComment(record) : null);
+    }
+    async delete(id) {
+        const result = this.db.prepare('DELETE FROM work_item_comments WHERE id = ?').run(id);
+        return Promise.resolve(result.changes > 0);
+    }
+    async countByWorkItem(workItemId) {
+        const result = this.db
+            .prepare('SELECT COUNT(*) as count FROM work_item_comments WHERE work_item_id = ?')
+            .get(workItemId);
+        return Promise.resolve(result.count);
+    }
+}

package/dist/platform/sqlite/db.js

@@ -139,4 +139,22 @@ function runMigrations(db, fromVersion, toVersion) {
     `);
         db.prepare('INSERT INTO schema_version (version) VALUES (?)').run(6);
     }
+    if (fromVersion < 7 && toVersion >= 7) {
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS work_item_comments (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        work_item_id INTEGER NOT NULL,
+        project_id INTEGER NOT NULL,
+        author TEXT NOT NULL,
+        content TEXT NOT NULL,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        FOREIGN KEY (work_item_id) REFERENCES work_items(id) ON DELETE CASCADE,
+        FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE
+      );
+      CREATE INDEX IF NOT EXISTS idx_work_item_comments_work_item ON work_item_comments(work_item_id);
+      CREATE INDEX IF NOT EXISTS idx_work_item_comments_project ON work_item_comments(project_id);
+    `);
+        db.prepare('INSERT INTO schema_version (version) VALUES (?)').run(7);
+    }
 }

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

@@ -17,12 +17,13 @@
  */
 import type Database from 'better-sqlite3';
 import { type ProjectDeleteHooks } from './project-repository.js';
-import type { IProjectRepository, IWorkItemRepository, IDocumentRepository, IPlanRepository } from '../repositories.js';
+import type { IProjectRepository, IWorkItemRepository, IDocumentRepository, IPlanRepository, ICommentRepository } from '../repositories.js';
 export interface SQLiteRepositories {
     projects: IProjectRepository;
     workItems: IWorkItemRepository;
     documents: IDocumentRepository;
     plans: IPlanRepository;
+    comments: ICommentRepository;
 }
 export interface CreateSQLiteRepositoriesOptions {
     projectDeleteHooks?: ProjectDeleteHooks;
@@ -35,6 +36,7 @@ export { SQLiteProjectRepository, type ProjectDeleteHooks } from './project-repo
 export { SQLiteWorkItemRepository } from './work-item-repository.js';
 export { SQLiteDocumentRepository } from './document-repository.js';
 export { SQLitePlanRepository } from './plan-repository.js';
+export { SQLiteCommentRepository } from './comment-repository.js';
 export { getDatabase, closeDatabase, closeAllDatabases, databaseExists } from './db.js';
 export { SCHEMA_VERSION, SCHEMA_SQL } from './schema.js';
-export type { ProjectRecord, WorkItemRecord, ProjectDocumentRecord } from './schema.js';
+export type { ProjectRecord, WorkItemRecord, ProjectDocumentRecord, WorkItemCommentRecord, } from './schema.js';

package/dist/platform/sqlite/index.js

@@ -19,6 +19,7 @@ import { SQLiteProjectRepository } from './project-repository.js';
 import { SQLiteWorkItemRepository } from './work-item-repository.js';
 import { SQLiteDocumentRepository } from './document-repository.js';
 import { SQLitePlanRepository } from './plan-repository.js';
+import { SQLiteCommentRepository } from './comment-repository.js';
 /**
  * Create all 4 platform repositories backed by a single SQLite database.
  */
@@ -28,6 +29,7 @@ export function createSQLiteRepositories(db, options) {
         workItems: new SQLiteWorkItemRepository(db),
         documents: new SQLiteDocumentRepository(db),
         plans: new SQLitePlanRepository(db),
+        comments: new SQLiteCommentRepository(db),
     };
 }
 // Re-export classes for advanced usage
@@ -35,6 +37,7 @@ export { SQLiteProjectRepository } from './project-repository.js';
 export { SQLiteWorkItemRepository } from './work-item-repository.js';
 export { SQLiteDocumentRepository } from './document-repository.js';
 export { SQLitePlanRepository } from './plan-repository.js';
+export { SQLiteCommentRepository } from './comment-repository.js';
 // Re-export database utilities
 export { getDatabase, closeDatabase, closeAllDatabases, databaseExists } from './db.js';
 // Re-export schema (for consumers that need direct access)

package/dist/platform/sqlite/schema.d.ts

@@ -4,8 +4,8 @@
  * Shared between CLI and Desktop — both access ~/.compilr-dev/projects.db
  * Schema version must be kept in sync across all consumers.
  */
-export declare const SCHEMA_VERSION = 6;
-export declare const SCHEMA_SQL = "\n-- Schema version tracking\nCREATE TABLE IF NOT EXISTS schema_version (\n  version INTEGER PRIMARY KEY,\n  applied_at DATETIME DEFAULT CURRENT_TIMESTAMP\n);\n\n-- Projects table\nCREATE TABLE IF NOT EXISTS projects (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  name TEXT UNIQUE NOT NULL,\n  display_name TEXT NOT NULL,\n  description TEXT,\n  type TEXT DEFAULT 'general',\n  status TEXT DEFAULT 'active',\n  path TEXT NOT NULL,\n  docs_path TEXT,\n  repo_pattern TEXT DEFAULT 'single',\n  language TEXT,\n  framework TEXT,\n  package_manager TEXT,\n  runtime_version TEXT,\n  commands TEXT,\n  git_remote TEXT,\n  git_branch TEXT DEFAULT 'main',\n  workflow_mode TEXT DEFAULT 'flexible',\n  lifecycle_state TEXT DEFAULT 'setup',\n  current_item_id TEXT,\n  last_context TEXT,\n  metadata TEXT,\n  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  last_activity_at DATETIME\n);\n\n-- Work items (backlog items, tasks, bugs)\nCREATE TABLE IF NOT EXISTS work_items (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  project_id INTEGER NOT NULL,\n  item_number INTEGER NOT NULL,\n  item_id TEXT NOT NULL,\n  type TEXT NOT NULL,\n  status TEXT DEFAULT 'backlog',\n  priority TEXT DEFAULT 'medium',\n  guided_step TEXT,\n  owner TEXT,\n  title TEXT NOT NULL,\n  description TEXT,\n  estimated_effort TEXT,\n  actual_minutes INTEGER,\n  completed_at DATETIME,\n  completed_by TEXT,\n  commit_hash TEXT,\n  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE,\n  UNIQUE (project_id, item_id)\n);\n\n-- Project documents (PRD, architecture, plans, etc.)\nCREATE TABLE IF NOT EXISTS project_documents (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  project_id INTEGER NOT NULL,\n  doc_type TEXT NOT NULL,\n  title TEXT NOT NULL,\n  content TEXT NOT NULL,\n  status TEXT,\n  work_item_id INTEGER,\n  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE,\n  FOREIGN KEY (work_item_id) REFERENCES work_items(id) ON DELETE SET NULL\n);\n\n-- Work item history (audit trail)\nCREATE TABLE IF NOT EXISTS work_item_history (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  work_item_id INTEGER NOT NULL,\n  project_id INTEGER NOT NULL,\n  action TEXT NOT NULL,\n  old_value TEXT,\n  new_value TEXT,\n  notes TEXT,\n  changed_by TEXT,\n  changed_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  FOREIGN KEY (work_item_id) REFERENCES work_items(id) ON DELETE CASCADE,\n  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE\n);\n\n-- Indexes\nCREATE INDEX IF NOT EXISTS idx_projects_path ON projects(path);\nCREATE INDEX IF NOT EXISTS idx_projects_docs_path ON projects(docs_path);\nCREATE INDEX IF NOT EXISTS idx_projects_status ON projects(status);\nCREATE INDEX IF NOT EXISTS idx_work_items_project ON work_items(project_id);\nCREATE INDEX IF NOT EXISTS idx_work_items_status ON work_items(status);\nCREATE INDEX IF NOT EXISTS idx_work_items_priority ON work_items(priority);\nCREATE INDEX IF NOT EXISTS idx_work_items_owner ON work_items(owner);\nCREATE INDEX IF NOT EXISTS idx_project_documents_project ON project_documents(project_id);\nCREATE INDEX IF NOT EXISTS idx_project_documents_type ON project_documents(doc_type);\nCREATE INDEX IF NOT EXISTS idx_project_documents_status ON project_documents(status);\nCREATE INDEX IF NOT EXISTS idx_project_documents_work_item ON project_documents(work_item_id);\nCREATE INDEX IF NOT EXISTS idx_work_item_history_item ON work_item_history(work_item_id);\n\n-- Terminal sessions (multi-terminal awareness)\nCREATE TABLE IF NOT EXISTS terminal_sessions (\n  id TEXT PRIMARY KEY,\n  project_id INTEGER,\n  pid INTEGER NOT NULL,\n  tty_path TEXT,\n  label TEXT,\n  started_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  last_heartbeat DATETIME DEFAULT CURRENT_TIMESTAMP,\n  active_agent TEXT DEFAULT 'default',\n  agents_json TEXT DEFAULT '[]',\n  status TEXT DEFAULT 'active',\n  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE SET NULL\n);\nCREATE INDEX IF NOT EXISTS idx_terminal_sessions_project ON terminal_sessions(project_id);\nCREATE INDEX IF NOT EXISTS idx_terminal_sessions_status ON terminal_sessions(status);\n\n-- File locks (multi-terminal file lock awareness)\nCREATE TABLE IF NOT EXISTS file_locks (\n  path TEXT NOT NULL,\n  project_id INTEGER NOT NULL,\n  session_id TEXT NOT NULL,\n  agent_id TEXT NOT NULL,\n  locked_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  PRIMARY KEY (path, project_id),\n  FOREIGN KEY (session_id) REFERENCES terminal_sessions(id) ON DELETE CASCADE,\n  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE\n);\nCREATE INDEX IF NOT EXISTS idx_file_locks_session ON file_locks(session_id);\n\n-- Session notifications (cross-session notifications)\nCREATE TABLE IF NOT EXISTS session_notifications (\n  id TEXT PRIMARY KEY,\n  project_id INTEGER NOT NULL,\n  from_session_id TEXT NOT NULL,\n  to_session_id TEXT,\n  type TEXT NOT NULL,\n  title TEXT NOT NULL,\n  message TEXT,\n  payload_json TEXT,\n  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  read_at DATETIME,\n  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE,\n  FOREIGN KEY (from_session_id) REFERENCES terminal_sessions(id) ON DELETE CASCADE\n);\nCREATE INDEX IF NOT EXISTS idx_session_notifications_project ON session_notifications(project_id);\nCREATE INDEX IF NOT EXISTS idx_session_notifications_to_session ON session_notifications(to_session_id);\nCREATE INDEX IF NOT EXISTS idx_session_notifications_unread ON session_notifications(read_at);\n";
+export declare const SCHEMA_VERSION = 7;
+export declare const SCHEMA_SQL = "\n-- Schema version tracking\nCREATE TABLE IF NOT EXISTS schema_version (\n  version INTEGER PRIMARY KEY,\n  applied_at DATETIME DEFAULT CURRENT_TIMESTAMP\n);\n\n-- Projects table\nCREATE TABLE IF NOT EXISTS projects (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  name TEXT UNIQUE NOT NULL,\n  display_name TEXT NOT NULL,\n  description TEXT,\n  type TEXT DEFAULT 'general',\n  status TEXT DEFAULT 'active',\n  path TEXT NOT NULL,\n  docs_path TEXT,\n  repo_pattern TEXT DEFAULT 'single',\n  language TEXT,\n  framework TEXT,\n  package_manager TEXT,\n  runtime_version TEXT,\n  commands TEXT,\n  git_remote TEXT,\n  git_branch TEXT DEFAULT 'main',\n  workflow_mode TEXT DEFAULT 'flexible',\n  lifecycle_state TEXT DEFAULT 'setup',\n  current_item_id TEXT,\n  last_context TEXT,\n  metadata TEXT,\n  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  last_activity_at DATETIME\n);\n\n-- Work items (backlog items, tasks, bugs)\nCREATE TABLE IF NOT EXISTS work_items (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  project_id INTEGER NOT NULL,\n  item_number INTEGER NOT NULL,\n  item_id TEXT NOT NULL,\n  type TEXT NOT NULL,\n  status TEXT DEFAULT 'backlog',\n  priority TEXT DEFAULT 'medium',\n  guided_step TEXT,\n  owner TEXT,\n  title TEXT NOT NULL,\n  description TEXT,\n  estimated_effort TEXT,\n  actual_minutes INTEGER,\n  completed_at DATETIME,\n  completed_by TEXT,\n  commit_hash TEXT,\n  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE,\n  UNIQUE (project_id, item_id)\n);\n\n-- Project documents (PRD, architecture, plans, etc.)\nCREATE TABLE IF NOT EXISTS project_documents (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  project_id INTEGER NOT NULL,\n  doc_type TEXT NOT NULL,\n  title TEXT NOT NULL,\n  content TEXT NOT NULL,\n  status TEXT,\n  work_item_id INTEGER,\n  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE,\n  FOREIGN KEY (work_item_id) REFERENCES work_items(id) ON DELETE SET NULL\n);\n\n-- Work item history (audit trail)\nCREATE TABLE IF NOT EXISTS work_item_history (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  work_item_id INTEGER NOT NULL,\n  project_id INTEGER NOT NULL,\n  action TEXT NOT NULL,\n  old_value TEXT,\n  new_value TEXT,\n  notes TEXT,\n  changed_by TEXT,\n  changed_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  FOREIGN KEY (work_item_id) REFERENCES work_items(id) ON DELETE CASCADE,\n  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE\n);\n\n-- Indexes\nCREATE INDEX IF NOT EXISTS idx_projects_path ON projects(path);\nCREATE INDEX IF NOT EXISTS idx_projects_docs_path ON projects(docs_path);\nCREATE INDEX IF NOT EXISTS idx_projects_status ON projects(status);\nCREATE INDEX IF NOT EXISTS idx_work_items_project ON work_items(project_id);\nCREATE INDEX IF NOT EXISTS idx_work_items_status ON work_items(status);\nCREATE INDEX IF NOT EXISTS idx_work_items_priority ON work_items(priority);\nCREATE INDEX IF NOT EXISTS idx_work_items_owner ON work_items(owner);\nCREATE INDEX IF NOT EXISTS idx_project_documents_project ON project_documents(project_id);\nCREATE INDEX IF NOT EXISTS idx_project_documents_type ON project_documents(doc_type);\nCREATE INDEX IF NOT EXISTS idx_project_documents_status ON project_documents(status);\nCREATE INDEX IF NOT EXISTS idx_project_documents_work_item ON project_documents(work_item_id);\nCREATE INDEX IF NOT EXISTS idx_work_item_history_item ON work_item_history(work_item_id);\n\n-- Terminal sessions (multi-terminal awareness)\nCREATE TABLE IF NOT EXISTS terminal_sessions (\n  id TEXT PRIMARY KEY,\n  project_id INTEGER,\n  pid INTEGER NOT NULL,\n  tty_path TEXT,\n  label TEXT,\n  started_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  last_heartbeat DATETIME DEFAULT CURRENT_TIMESTAMP,\n  active_agent TEXT DEFAULT 'default',\n  agents_json TEXT DEFAULT '[]',\n  status TEXT DEFAULT 'active',\n  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE SET NULL\n);\nCREATE INDEX IF NOT EXISTS idx_terminal_sessions_project ON terminal_sessions(project_id);\nCREATE INDEX IF NOT EXISTS idx_terminal_sessions_status ON terminal_sessions(status);\n\n-- File locks (multi-terminal file lock awareness)\nCREATE TABLE IF NOT EXISTS file_locks (\n  path TEXT NOT NULL,\n  project_id INTEGER NOT NULL,\n  session_id TEXT NOT NULL,\n  agent_id TEXT NOT NULL,\n  locked_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  PRIMARY KEY (path, project_id),\n  FOREIGN KEY (session_id) REFERENCES terminal_sessions(id) ON DELETE CASCADE,\n  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE\n);\nCREATE INDEX IF NOT EXISTS idx_file_locks_session ON file_locks(session_id);\n\n-- Session notifications (cross-session notifications)\nCREATE TABLE IF NOT EXISTS session_notifications (\n  id TEXT PRIMARY KEY,\n  project_id INTEGER NOT NULL,\n  from_session_id TEXT NOT NULL,\n  to_session_id TEXT,\n  type TEXT NOT NULL,\n  title TEXT NOT NULL,\n  message TEXT,\n  payload_json TEXT,\n  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  read_at DATETIME,\n  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE,\n  FOREIGN KEY (from_session_id) REFERENCES terminal_sessions(id) ON DELETE CASCADE\n);\nCREATE INDEX IF NOT EXISTS idx_session_notifications_project ON session_notifications(project_id);\nCREATE INDEX IF NOT EXISTS idx_session_notifications_to_session ON session_notifications(to_session_id);\nCREATE INDEX IF NOT EXISTS idx_session_notifications_unread ON session_notifications(read_at);\n\n-- Work item comments\nCREATE TABLE IF NOT EXISTS work_item_comments (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  work_item_id INTEGER NOT NULL,\n  project_id INTEGER NOT NULL,\n  author TEXT NOT NULL,\n  content TEXT NOT NULL,\n  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  FOREIGN KEY (work_item_id) REFERENCES work_items(id) ON DELETE CASCADE,\n  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE\n);\nCREATE INDEX IF NOT EXISTS idx_work_item_comments_work_item ON work_item_comments(work_item_id);\nCREATE INDEX IF NOT EXISTS idx_work_item_comments_project ON work_item_comments(project_id);\n";
 export interface ProjectRecord {
     id: number;
     name: string;
@@ -63,3 +63,12 @@ export interface ProjectDocumentRecord {
     created_at: string;
     updated_at: string;
 }
+export interface WorkItemCommentRecord {
+    id: number;
+    work_item_id: number;
+    project_id: number;
+    author: string;
+    content: string;
+    created_at: string;
+    updated_at: string;
+}

package/dist/platform/sqlite/schema.js

@@ -4,7 +4,7 @@
  * Shared between CLI and Desktop — both access ~/.compilr-dev/projects.db
  * Schema version must be kept in sync across all consumers.
  */
-export const SCHEMA_VERSION = 6;
+export const SCHEMA_VERSION = 7;
 export const SCHEMA_SQL = `
 -- Schema version tracking
 CREATE TABLE IF NOT EXISTS schema_version (
@@ -156,4 +156,19 @@ CREATE TABLE IF NOT EXISTS session_notifications (
 CREATE INDEX IF NOT EXISTS idx_session_notifications_project ON session_notifications(project_id);
 CREATE INDEX IF NOT EXISTS idx_session_notifications_to_session ON session_notifications(to_session_id);
 CREATE INDEX IF NOT EXISTS idx_session_notifications_unread ON session_notifications(read_at);
+
+-- Work item comments
+CREATE TABLE IF NOT EXISTS work_item_comments (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  work_item_id INTEGER NOT NULL,
+  project_id INTEGER NOT NULL,
+  author TEXT NOT NULL,
+  content TEXT NOT NULL,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY (work_item_id) REFERENCES work_items(id) ON DELETE CASCADE,
+  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_work_item_comments_work_item ON work_item_comments(work_item_id);
+CREATE INDEX IF NOT EXISTS idx_work_item_comments_project ON work_item_comments(project_id);
 `;

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

@@ -1,8 +1,8 @@
 /**
  * Platform Tools — Factory function for all platform tools.
  *
- * Returns up to 32 tool definitions operating against async PlatformContext.
- * - 24 DB tools (always): project, workitem, document, plan, backlog
+ * Returns up to 33 tool definitions operating against async PlatformContext.
+ * - 25 DB tools (always): project, workitem (incl. comment), document, plan, backlog
  * - 3 anchor tools (if ctx.anchors provided)
  * - 4 artifact tools (if ctx.artifacts provided)
  * - 1 episode tool (if ctx.episodes provided)

package/dist/platform/tools/index.js

@@ -1,8 +1,8 @@
 /**
  * Platform Tools — Factory function for all platform tools.
  *
- * Returns up to 32 tool definitions operating against async PlatformContext.
- * - 24 DB tools (always): project, workitem, document, plan, backlog
+ * Returns up to 33 tool definitions operating against async PlatformContext.
+ * - 25 DB tools (always): project, workitem (incl. comment), document, plan, backlog
  * - 3 anchor tools (if ctx.anchors provided)
  * - 4 artifact tools (if ctx.artifacts provided)
  * - 1 episode tool (if ctx.episodes provided)

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

@@ -1,9 +1,9 @@
 /**
  * Work Item Tools — CRUD + workflow operations for work items.
  *
- * 9 tools: workitem_query, workitem_add, workitem_update, workitem_next,
- *          workitem_delete, workitem_status_counts, workitem_advance_step,
- *          workitem_claim, workitem_handoff
+ * 10 tools: workitem_query, workitem_add, workitem_update, workitem_next,
+ *           workitem_delete, workitem_status_counts, workitem_advance_step,
+ *           workitem_claim, workitem_handoff, workitem_comment
  *
  * Ported from CLI's src/tools/workitem-db.ts. Key adaptations:
  * - getActiveProject()?.id → ctx.currentProjectId
@@ -53,4 +53,8 @@ export declare function createWorkItemTools(config: PlatformToolsConfig): (impor
     to_agent_id: string;
     notes?: string;
     project_id?: number;
+}> | import("@compilr-dev/agents").Tool<{
+    item_id: string;
+    content: string;
+    project_id?: number;
 }>)[];

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

@@ -1,9 +1,9 @@
 /**
  * Work Item Tools — CRUD + workflow operations for work items.
  *
- * 9 tools: workitem_query, workitem_add, workitem_update, workitem_next,
- *          workitem_delete, workitem_status_counts, workitem_advance_step,
- *          workitem_claim, workitem_handoff
+ * 10 tools: workitem_query, workitem_add, workitem_update, workitem_next,
+ *           workitem_delete, workitem_status_counts, workitem_advance_step,
+ *           workitem_claim, workitem_handoff, workitem_comment
  *
  * Ported from CLI's src/tools/workitem-db.ts. Key adaptations:
  * - getActiveProject()?.id → ctx.currentProjectId
@@ -696,6 +696,69 @@ export function createWorkItemTools(config) {
             }
         },
     });
+    // ---------------------------------------------------------------------------
+    // workitem_comment
+    // ---------------------------------------------------------------------------
+    const workitemCommentTool = defineTool({
+        name: 'workitem_comment',
+        description: 'Add a comment to a work item. Comments support markdown and are visible in the work item timeline.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                item_id: {
+                    type: 'string',
+                    description: 'Work item ID (e.g., "REQ-001", "BUG-002")',
+                },
+                content: {
+                    type: 'string',
+                    description: 'Comment content (supports markdown)',
+                },
+                project_id: {
+                    type: 'number',
+                    description: 'Override active project.',
+                },
+            },
+            required: ['item_id', 'content'],
+        },
+        execute: async (input) => {
+            try {
+                const comments = ctx.comments;
+                if (!comments) {
+                    return createErrorResult('Comment service not configured.');
+                }
+                const projectId = input.project_id ?? ctx.currentProjectId;
+                if (!projectId) {
+                    return createErrorResult('No project specified and no active project. Use project_get or /projects to select a project first.');
+                }
+                const existingItem = await ctx.workItems.getByItemId(projectId, input.item_id);
+                if (!existingItem) {
+                    return createErrorResult(`Work item "${input.item_id}" not found in current project`);
+                }
+                // Resolve author: use agent identity from hook, or fallback to 'agent'
+                const author = hooks?.resolveOwner?.('self') ?? 'agent';
+                const comment = await comments.create({
+                    work_item_id: existingItem.id,
+                    project_id: projectId,
+                    author,
+                    content: input.content,
+                });
+                return createSuccessResult({
+                    success: true,
+                    message: `Comment added to ${input.item_id} by ${author}`,
+                    comment: {
+                        id: comment.id,
+                        workItemId: comment.workItemId,
+                        author: comment.author,
+                        content: comment.content,
+                        createdAt: comment.createdAt.toISOString(),
+                    },
+                });
+            }
+            catch (error) {
+                return createErrorResult(`Failed to add comment: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+    });
     return [
         workitemQueryTool,
         workitemAddTool,
@@ -706,5 +769,6 @@ export function createWorkItemTools(config) {
         workitemAdvanceStepTool,
         workitemClaimTool,
         workitemHandoffTool,
+        workitemCommentTool,
     ];
 }

package/dist/platform/types.d.ts

@@ -231,3 +231,21 @@ export interface BulkCreateItem {
     priority?: WorkItemPriority;
     owner?: string;
 }
+export interface WorkItemComment {
+    id: number;
+    workItemId: number;
+    projectId: number;
+    author: string;
+    content: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface CreateCommentInput {
+    work_item_id: number;
+    project_id: number;
+    author: string;
+    content: string;
+}
+export interface UpdateCommentInput {
+    content: string;
+}

package/dist/system-prompt/builder.d.ts

@@ -22,6 +22,8 @@ export interface SystemPromptContext {
     enableMetaTools?: boolean;
     /** Does the agent have a role-specific identity? (team agents) */
     hasRoleIdentity?: boolean;
+    /** Does the client support inline visual output (HTML/SVG preview)? Desktop only. */
+    hasVisualOutput?: boolean;
     /** Active project display name (human-readable, e.g. "Hr Manager") */
     projectName?: string;
     /** Active project slug (unique identifier, e.g. "hr-manager") */

package/dist/system-prompt/index.d.ts

@@ -31,4 +31,4 @@
  * ```
  */
 export { SystemPromptBuilder, buildSystemPrompt, detectGitRepository, getModuleStats, type SystemPromptContext, type BuildResult, } from './builder.js';
-export { ALL_MODULES, IDENTITY_MODULE, STYLE_MODULE, TASK_EXECUTION_MODULE, TODO_MANAGEMENT_MODULE, TOOL_USAGE_DIRECT_MODULE, TOOL_USAGE_HINTS_MODULE, PLATFORM_TOOL_HINTS_MODULE, FACTORY_TOOL_HINTS_MODULE, TOOL_USAGE_META_MODULE, DELEGATION_MODULE, GIT_SAFETY_MODULE, SUGGEST_MODULE, IMPORTANT_RULES_MODULE, ENVIRONMENT_MODULE, shouldIncludeModule, getEstimatedTokensForConditions, getTotalEstimatedTokens, type SystemPromptModule, type ModuleConditions, } from './modules.js';
+export { ALL_MODULES, IDENTITY_MODULE, STYLE_MODULE, TASK_EXECUTION_MODULE, TODO_MANAGEMENT_MODULE, TOOL_USAGE_DIRECT_MODULE, TOOL_USAGE_HINTS_MODULE, PLATFORM_TOOL_HINTS_MODULE, FACTORY_TOOL_HINTS_MODULE, TOOL_USAGE_META_MODULE, DELEGATION_MODULE, GIT_SAFETY_MODULE, SUGGEST_MODULE, IMPORTANT_RULES_MODULE, VISUAL_OUTPUT_MODULE, ENVIRONMENT_MODULE, shouldIncludeModule, getEstimatedTokensForConditions, getTotalEstimatedTokens, type SystemPromptModule, type ModuleConditions, } from './modules.js';

package/dist/system-prompt/index.js

@@ -31,4 +31,4 @@
  * ```
  */
 export { SystemPromptBuilder, buildSystemPrompt, detectGitRepository, getModuleStats, } from './builder.js';
-export { ALL_MODULES, IDENTITY_MODULE, STYLE_MODULE, TASK_EXECUTION_MODULE, TODO_MANAGEMENT_MODULE, TOOL_USAGE_DIRECT_MODULE, TOOL_USAGE_HINTS_MODULE, PLATFORM_TOOL_HINTS_MODULE, FACTORY_TOOL_HINTS_MODULE, TOOL_USAGE_META_MODULE, DELEGATION_MODULE, GIT_SAFETY_MODULE, SUGGEST_MODULE, IMPORTANT_RULES_MODULE, ENVIRONMENT_MODULE, shouldIncludeModule, getEstimatedTokensForConditions, getTotalEstimatedTokens, } from './modules.js';
+export { ALL_MODULES, IDENTITY_MODULE, STYLE_MODULE, TASK_EXECUTION_MODULE, TODO_MANAGEMENT_MODULE, TOOL_USAGE_DIRECT_MODULE, TOOL_USAGE_HINTS_MODULE, PLATFORM_TOOL_HINTS_MODULE, FACTORY_TOOL_HINTS_MODULE, TOOL_USAGE_META_MODULE, DELEGATION_MODULE, GIT_SAFETY_MODULE, SUGGEST_MODULE, IMPORTANT_RULES_MODULE, VISUAL_OUTPUT_MODULE, ENVIRONMENT_MODULE, shouldIncludeModule, getEstimatedTokensForConditions, getTotalEstimatedTokens, } from './modules.js';

package/dist/system-prompt/modules.d.ts

@@ -20,6 +20,8 @@ export interface ModuleConditions {
     enableMetaTools?: boolean;
     /** Include only if NO role identity is specified (for default identity module) */
     noRoleIdentity?: boolean;
+    /** Include only if visual output is supported (desktop app with inline preview) */
+    hasVisualOutput?: boolean;
 }
 /**
  * A system prompt module
@@ -109,6 +111,11 @@ export declare const IMPORTANT_RULES_MODULE: SystemPromptModule;
  * Current working directory and git config
  * Note: {{PLACEHOLDERS}} are replaced at runtime
  */
+/**
+ * Visual output module — only included when the client supports inline preview
+ * (desktop app with HTML/SVG/Mermaid rendering in iframes)
+ */
+export declare const VISUAL_OUTPUT_MODULE: SystemPromptModule;
 export declare const ENVIRONMENT_MODULE: SystemPromptModule;
 /**
  * All modules in the order they should appear in the prompt.
@@ -128,6 +135,7 @@ export declare function getEstimatedTokensForConditions(conditions: {
     mode?: 'flexible' | 'guided' | 'plan';
     hasProject?: boolean;
     hasRoleIdentity?: boolean;
+    hasVisualOutput?: boolean;
 }): number;
 /**
  * Check if a module should be included based on conditions
@@ -138,4 +146,5 @@ export declare function shouldIncludeModule(module: SystemPromptModule, context:
     mode?: 'flexible' | 'guided' | 'plan';
     hasProject?: boolean;
     hasRoleIdentity?: boolean;
+    hasVisualOutput?: boolean;
 }): boolean;

package/dist/system-prompt/modules.js

@@ -328,6 +328,58 @@ export const IMPORTANT_RULES_MODULE = {
  * Current working directory and git config
  * Note: {{PLACEHOLDERS}} are replaced at runtime
  */
+/**
+ * Visual output module — only included when the client supports inline preview
+ * (desktop app with HTML/SVG/Mermaid rendering in iframes)
+ */
+export const VISUAL_OUTPUT_MODULE = {
+    id: 'visual-output',
+    name: 'Visual Output',
+    estimatedTokens: 300,
+    conditions: {
+        hasVisualOutput: true,
+    },
+    content: `## Visual Output
+
+You can render live, interactive previews inline by using fenced code blocks with these languages:
+- \`html\` — Full HTML documents with CSS and JavaScript (interactive canvas, games, animations, data visualizations)
+- \`svg\` — Vector graphics (diagrams, illustrations, charts)
+- \`mermaid\` — Diagrams (flowcharts, sequence diagrams, class diagrams, ERDs)
+- \`csv\` — Data tables
+- \`latex\` — Mathematical formulas
+
+These code blocks render as live previews by default. The user can toggle between preview and source code.
+
+### When to Use Visuals (Proactively)
+
+Use visual output when it communicates more effectively than text alone. Don't wait to be asked — reach for visuals naturally when the concept has spatial, sequential, or interactive qualities.
+
+**Triggers — use visuals for:**
+- Explaining architecture, data flows, state machines, or processes → mermaid or HTML/SVG diagram
+- Comparing options or trade-offs → HTML table or side-by-side visual
+- Demonstrating algorithms or data structures → animated HTML canvas
+- Showing UI concepts, layouts, or mockups → HTML with CSS
+- Presenting data or metrics → HTML chart or CSV table
+- Mathematical concepts → LaTeX formulas
+- Any request containing "show me", "visualize", "diagram", or "compare X vs Y"
+
+**Do NOT generate visuals for:**
+- Pure text tasks (drafting, writing, summarizing)
+- Simple code explanations that don't have a structural component
+- Quick answers that are better as a sentence
+- When the user explicitly asks for text/code only
+
+### Rendering Constraints
+
+Previews run in a sandboxed iframe with no network access. Follow these rules:
+- **No external resources** — no CDN links, no fetch/XHR, no external images or fonts. Everything must be inline.
+- **Use inline styles** — no external CSS files.
+- **Keep it self-contained** — a single HTML file with embedded \`<style>\` and \`<script>\`.
+- **Dark theme default** — use dark backgrounds (#0a0a0a or similar), light text (#fafafa), accent colors.
+- **Reasonable height** — content should fit within ~500px height. Avoid \`height: 100vh\`.
+- **Keyboard interactivity works** — the user can click into the preview and use keyboard controls (games, form inputs, etc.).
+- For simple structures, prefer \`mermaid\` (less tokens) over hand-drawn SVG/HTML.`,
+};
 export const ENVIRONMENT_MODULE = {
     id: 'environment',
     name: 'Environment Info',
@@ -358,6 +410,7 @@ export const ALL_MODULES = [
     GIT_SAFETY_MODULE, // Conditional: hasGit
     SUGGEST_MODULE,
     IMPORTANT_RULES_MODULE,
+    VISUAL_OUTPUT_MODULE, // Conditional: hasVisualOutput (desktop only)
     ENVIRONMENT_MODULE,
 ];
 /**
@@ -411,5 +464,10 @@ export function shouldIncludeModule(module, context) {
     if (conditions.hasProject !== undefined && conditions.hasProject !== context.hasProject) {
         return false;
     }
+    // Check hasVisualOutput condition
+    if (conditions.hasVisualOutput !== undefined &&
+        conditions.hasVisualOutput !== context.hasVisualOutput) {
+        return false;
+    }
     return true;
 }

package/dist/tools/index.d.ts

@@ -4,5 +4,5 @@
  * These tools require a UI handler callback from the consumer.
  * The SDK defines schemas and types; consumers provide the UI.
  */
-export { createAskUserTool, createAskUserSimpleTool, } from './ask-user-tools.js';
+export { createAskUserTool, createAskUserSimpleTool } from './ask-user-tools.js';
 export type { AskUserQuestion, AskUserInput, AskUserResult, AskUserHandler, AskUserSimpleInput, AskUserSimpleResult, AskUserSimpleHandler, } from './ask-user-tools.js';

package/dist/tools/index.js

@@ -4,4 +4,4 @@
  * These tools require a UI handler callback from the consumer.
  * The SDK defines schemas and types; consumers provide the UI.
  */
-export { createAskUserTool, createAskUserSimpleTool, } from './ask-user-tools.js';
+export { createAskUserTool, createAskUserSimpleTool } from './ask-user-tools.js';

package/package.json

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