@compilr-dev/sdk 0.1.7 → 0.1.8

package/README.md

@@ -15,6 +15,9 @@
 [![npm version](https://img.shields.io/npm/v/@compilr-dev/sdk.svg)](https://www.npmjs.com/package/@compilr-dev/sdk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+> [!WARNING]
+> This package is in beta. APIs may change between minor versions.
+
 ## Overview
 
 The SDK sits on top of [@compilr-dev/agents](https://www.npmjs.com/package/@compilr-dev/agents) and [@compilr-dev/agents-coding](https://www.npmjs.com/package/@compilr-dev/agents-coding), providing a high-level API for agent creation, tool assembly, and multi-agent teams. It's the runtime that powers [@compilr-dev/cli](https://www.npmjs.com/package/@compilr-dev/cli).

package/dist/index.d.ts

@@ -47,6 +47,9 @@ export { MetaToolsRegistry, createMetaTools, META_TOOLS_SYSTEM_PROMPT_PREFIX, }
 export type { MetaToolStats, MetaTools } from './meta-tools/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_META_MODULE, DELEGATION_MODULE, GIT_SAFETY_MODULE, SUGGEST_MODULE, IMPORTANT_RULES_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, PlatformContext, PlatformToolsConfig, PlatformHooks, StepCriteria, } from './platform/index.js';
+export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, } from './platform/index.js';
+export { STEP_ORDER, GUIDED_STEP_CRITERIA, getNextStep, isValidTransition, getStepCriteria, formatStepDisplay, getStepNumber, } from './platform/index.js';
 export { defineTool, createSuccessResult, createErrorResult, mergeHooks, createLoggingHooks, createClaudeProvider, createOpenAIProvider, createGeminiNativeProvider, createOllamaProvider, createTogetherProvider, createGroqProvider, createFireworksProvider, createPerplexityProvider, createOpenRouterProvider, createMockProvider, MockProvider, Agent, ContextManager, DEFAULT_CONTEXT_CONFIG, createTaskTool, createSuggestTool, defaultAgentTypes, TOOL_SETS, BUILTIN_GUARDRAILS, TOOL_NAMES, getDefaultShellManager, builtinSkills, AnchorManager, MCPManager, AgentError, ProviderError, ToolError, ToolTimeoutError, MaxIterationsError, AbortError, } from '@compilr-dev/agents';
 export type { Tool, HooksConfig, AgentEvent, Message, LLMProvider, AnchorInput, ToolExecutionResult, AgentRunResult, PermissionHandler, ToolPermission, AgentTypeConfig, GuardrailTriggeredHandler, BeforeLLMHookResult, BeforeToolHook, BeforeToolHookResult, AfterToolHook, AgentState, AgentConfig, SessionInfo, Anchor, AnchorScope, AnchorClearOptions, AnchorPriority, AnchorQueryOptions, FileAccessType, FileAccess, GuardrailResult, GuardrailContext, MCPClient, MCPToolDefinition, } from '@compilr-dev/agents';
 export { readFileTool, writeFileTool, createBashTool, bashTool, bashOutputTool, killShellTool, grepTool, globTool, editTool, todoWriteTool, todoReadTool, createTodoTools, TodoStore, webFetchTool, suggestTool, } from '@compilr-dev/agents';

package/dist/index.js

@@ -75,6 +75,14 @@ ALL_MODULES, IDENTITY_MODULE, STYLE_MODULE, TASK_EXECUTION_MODULE, TODO_MANAGEME
 // Module utilities
 shouldIncludeModule, getEstimatedTokensForConditions, getTotalEstimatedTokens, } from './system-prompt/index.js';
 // =============================================================================
+// Platform Tools (runtime — createPlatformTools factory + individual factories)
+// =============================================================================
+export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, } from './platform/index.js';
+// =============================================================================
+// Platform Workflow (pure step-criteria logic)
+// =============================================================================
+export { STEP_ORDER, GUIDED_STEP_CRITERIA, getNextStep, isValidTransition, getStepCriteria, formatStepDisplay, getStepNumber, } from './platform/index.js';
+// =============================================================================
 // Re-exports from @compilr-dev/agents (convenience — no need to install separately)
 // =============================================================================
 export { 

package/dist/platform/context.d.ts

@@ -0,0 +1,44 @@
+/**
+ * PlatformContext — Unified access to all platform repositories.
+ *
+ * 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';
+export interface PlatformContext {
+    readonly projects: IProjectRepository;
+    readonly workItems: IWorkItemRepository;
+    readonly documents: IDocumentRepository;
+    readonly plans: IPlanRepository;
+    currentProjectId?: number;
+}
+export interface PlatformHooks {
+    /** Called when a project is resolved/selected as the current project */
+    onProjectResolved?: (project: {
+        id: number;
+        name: string;
+        displayName: string;
+        path: string;
+    }) => void;
+    /** Called when a work item is completed */
+    onWorkItemCompleted?: (item: {
+        id: number;
+        itemId: string;
+        title: string;
+    }) => void;
+    /** Called when the first project is created (for gamification) */
+    onFirstProject?: (project: {
+        id: number;
+        name: string;
+    }) => void;
+    /** Resolve owner aliases (e.g., 'self' → active agent ID) */
+    resolveOwner?: (alias: 'self') => string | undefined;
+}
+export interface PlatformToolsConfig {
+    /** Data access layer */
+    context: PlatformContext;
+    /** Working directory override (defaults to process.cwd()) */
+    cwd?: string;
+    /** Optional hooks for CLI-specific side effects */
+    hooks?: PlatformHooks;
+}

package/dist/platform/context.js

@@ -0,0 +1,7 @@
+/**
+ * PlatformContext — Unified access to all platform repositories.
+ *
+ * Provides a single entry point for data access, abstracting over the
+ * underlying storage backend (SQLite in CLI, PostgreSQL in web/API).
+ */
+export {};

package/dist/platform/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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 { PlatformContext, PlatformToolsConfig, PlatformHooks } from './context.js';
+export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, } from './tools/index.js';
+export { STEP_ORDER, GUIDED_STEP_CRITERIA, getNextStep, isValidTransition, getStepCriteria, formatStepDisplay, getStepNumber, } from './workflow.js';
+export type { StepCriteria } from './workflow.js';

package/dist/platform/index.js

@@ -0,0 +1,7 @@
+/**
+ * Platform — Repository interfaces, data models, tools, and workflow.
+ */
+// Platform tools (runtime)
+export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, } from './tools/index.js';
+// Workflow (pure step-criteria logic)
+export { STEP_ORDER, GUIDED_STEP_CRITERIA, getNextStep, isValidTransition, getStepCriteria, formatStepDisplay, getStepNumber, } from './workflow.js';

package/dist/platform/repositories.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Repository Interfaces — Storage-agnostic data access contracts.
+ *
+ * All methods return Promise<T> even though the current CLI implementation
+ * 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';
+export interface IProjectRepository {
+    create(input: CreateProjectInput): Promise<Project>;
+    getById(id: number): Promise<Project | null>;
+    getByName(name: string): Promise<Project | null>;
+    getByPath(path: string): Promise<Project | null>;
+    getByDocsPath(docsPath: string): Promise<Project | null>;
+    findByPath(searchPath: string): Promise<Project | null>;
+    list(options?: ProjectListOptions): Promise<ProjectListResult>;
+    update(id: number, input: UpdateProjectInput): Promise<Project | null>;
+    touch(id: number): Promise<void>;
+    delete(id: number): Promise<boolean>;
+    archive(id: number): Promise<Project | null>;
+    isNameAvailable(name: string, excludeId?: number): Promise<boolean>;
+    getStatusCounts(): Promise<Record<ProjectStatus, number>>;
+}
+export interface IWorkItemRepository {
+    create(input: CreateWorkItemInput): Promise<WorkItem>;
+    getById(id: number): Promise<WorkItem | null>;
+    getByItemId(projectId: number, itemId: string): Promise<WorkItem | null>;
+    query(input: QueryWorkItemsInput): Promise<WorkItemQueryResult>;
+    getNext(projectId: number, type?: WorkItemType): Promise<WorkItem | null>;
+    update(id: number, input: UpdateWorkItemInput): Promise<WorkItem | null>;
+    delete(id: number): Promise<boolean>;
+    getByOwner(projectId: number, owner: string, status?: WorkItemStatus): Promise<WorkItem[]>;
+    getOwnerCounts(projectId: number): Promise<Record<string, number>>;
+    getStatusCounts(projectId: number): Promise<Record<WorkItemStatus, number>>;
+    getHistory(workItemId: number): Promise<HistoryEntry[]>;
+    bulkCreate(projectId: number, items: BulkCreateItem[]): Promise<WorkItem[]>;
+}
+export interface IDocumentRepository {
+    upsert(input: CreateDocumentInput): Promise<ProjectDocument>;
+    create(input: CreateDocumentInput): Promise<ProjectDocument>;
+    getById(id: number): Promise<ProjectDocument | null>;
+    getByType(projectId: number, docType: DocumentType): Promise<ProjectDocument | null>;
+    listByProject(projectId: number): Promise<ProjectDocument[]>;
+    update(id: number, input: UpdateDocumentInput): Promise<ProjectDocument | null>;
+    delete(id: number): Promise<boolean>;
+    deleteByType(projectId: number, docType: DocumentType): Promise<boolean>;
+    getTypeCounts(projectId: number): Promise<Record<DocumentType, number>>;
+}
+export interface IPlanRepository {
+    create(input: CreatePlanInput): Promise<Plan>;
+    getById(id: number): Promise<Plan | null>;
+    getByName(projectId: number, name: string): Promise<Plan | null>;
+    getWithWorkItem(id: number): Promise<PlanWithWorkItem | null>;
+    update(id: number, input: UpdatePlanInput): Promise<Plan | null>;
+    delete(id: number): Promise<boolean>;
+    list(projectId: number, options?: ListPlansOptions): Promise<PlanSummary[]>;
+    countByStatus(projectId: number): Promise<Record<PlanStatus, number>>;
+    getInProgress(projectId: number): Promise<PlanSummary[]>;
+    hasInProgress(projectId: number): Promise<boolean>;
+    linkWorkItem(planId: number, workItemId: number): Promise<Plan | null>;
+    unlinkWorkItem(planId: number): Promise<Plan | null>;
+}

package/dist/platform/repositories.js

@@ -0,0 +1,8 @@
+/**
+ * Repository Interfaces — Storage-agnostic data access contracts.
+ *
+ * All methods return Promise<T> even though the current CLI implementation
+ * uses synchronous SQLite. This ensures compatibility with future async
+ * backends (PostgreSQL, HTTP APIs).
+ */
+export {};

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

@@ -0,0 +1,41 @@
+/**
+ * Backlog Wrapper Tools — Library-compatible backlog interface over work items.
+ *
+ * 2 tools: backlog_read, backlog_write
+ *
+ * These wrappers provide `backlog_read` and `backlog_write` tools that skills expect,
+ * but internally delegate to the work item repository. This allows library skills
+ * (which reference backlog_*) to work seamlessly with the database-backed work items.
+ *
+ * Ported from CLI's src/tools/backlog-wrappers.ts.
+ */
+import type { PlatformToolsConfig } from '../context.js';
+export declare function createBacklogTools(config: PlatformToolsConfig): (import("@compilr-dev/agents").Tool<{
+    id?: string;
+    status?: string;
+    type?: string;
+    search?: string;
+    priority?: string;
+    limit?: number;
+}> | import("@compilr-dev/agents").Tool<{
+    action: string;
+    item?: {
+        id?: string;
+        type?: string;
+        title?: string;
+        description?: string;
+        status?: string;
+        priority?: string;
+        owner?: string;
+        commit_hash?: string;
+    };
+    deleteId?: string;
+    items?: Array<{
+        id?: string;
+        type: string;
+        title: string;
+        description?: string;
+        status?: string;
+        priority?: string;
+    }>;
+}>)[];

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

@@ -0,0 +1,358 @@
+/**
+ * Backlog Wrapper Tools — Library-compatible backlog interface over work items.
+ *
+ * 2 tools: backlog_read, backlog_write
+ *
+ * These wrappers provide `backlog_read` and `backlog_write` tools that skills expect,
+ * but internally delegate to the work item repository. This allows library skills
+ * (which reference backlog_*) to work seamlessly with the database-backed work items.
+ *
+ * Ported from CLI's src/tools/backlog-wrappers.ts.
+ */
+import { defineTool, createSuccessResult, createErrorResult } from '@compilr-dev/agents';
+// =============================================================================
+// Type Mappings (Library ↔ CLI)
+// =============================================================================
+/** Library status → CLI status */
+const STATUS_TO_CLI = {
+    backlog: 'backlog',
+    'in-progress': 'in_progress',
+    done: 'completed',
+    blocked: 'skipped',
+};
+/** CLI status → Library status */
+const STATUS_TO_LIBRARY = {
+    backlog: 'backlog',
+    in_progress: 'in-progress',
+    completed: 'done',
+    skipped: 'blocked',
+};
+/** Library type → CLI type */
+const TYPE_TO_CLI = {
+    feature: 'feature',
+    bug: 'bug',
+    chore: 'chore',
+    spike: 'tech-debt',
+};
+/** CLI type → Library type */
+const TYPE_TO_LIBRARY = {
+    feature: 'feature',
+    bug: 'bug',
+    chore: 'chore',
+    'tech-debt': 'spike',
+};
+// =============================================================================
+// Tool factory
+// =============================================================================
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+export function createBacklogTools(config) {
+    const { context: ctx } = config;
+    // ---------------------------------------------------------------------------
+    // backlog_read
+    // ---------------------------------------------------------------------------
+    const backlogReadTool = defineTool({
+        name: 'backlog_read',
+        description: 'Read backlog items from the project. ' +
+            'Use filters to narrow results. Use id parameter to get a specific item. ' +
+            'Returns items sorted by priority (critical first) then by creation date.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'string',
+                    description: 'Get a specific item by ID (e.g., "FEAT-001")',
+                },
+                status: {
+                    type: 'string',
+                    enum: ['backlog', 'in-progress', 'done', 'blocked'],
+                    description: 'Filter by status',
+                },
+                type: {
+                    type: 'string',
+                    enum: ['feature', 'bug', 'chore', 'spike'],
+                    description: 'Filter by item type',
+                },
+                search: {
+                    type: 'string',
+                    description: 'Search in title and description',
+                },
+                priority: {
+                    type: 'string',
+                    enum: ['critical', 'high', 'medium', 'low'],
+                    description: 'Filter by priority',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Maximum items to return (default: 20)',
+                },
+            },
+            required: [],
+        },
+        execute: async (input) => {
+            try {
+                const projectId = ctx.currentProjectId;
+                if (!projectId) {
+                    return createSuccessResult({
+                        items: [],
+                        total: 0,
+                        filtered: 0,
+                        message: 'No active project. Use /projects to select a project first.',
+                    });
+                }
+                // If specific ID requested, look it up directly
+                if (input.id) {
+                    const item = await ctx.workItems.getByItemId(projectId, input.id);
+                    if (!item) {
+                        return createErrorResult(`Item not found: ${input.id}`);
+                    }
+                    return createSuccessResult({
+                        items: [
+                            {
+                                id: item.itemId,
+                                type: TYPE_TO_LIBRARY[item.type],
+                                title: item.title,
+                                description: item.description ?? '',
+                                status: STATUS_TO_LIBRARY[item.status],
+                                priority: item.priority,
+                            },
+                        ],
+                        total: 1,
+                        filtered: 1,
+                    });
+                }
+                // Build query
+                const queryInput = {
+                    project_id: projectId,
+                    status: input.status ? STATUS_TO_CLI[input.status] : 'all',
+                    type: input.type ? TYPE_TO_CLI[input.type] : 'all',
+                    priority: input.priority ? input.priority : 'all',
+                    search: input.search,
+                    limit: input.limit ?? 20,
+                    offset: 0,
+                };
+                const result = await ctx.workItems.query(queryInput);
+                const items = result.items.map((item) => ({
+                    id: item.itemId,
+                    type: TYPE_TO_LIBRARY[item.type],
+                    title: item.title,
+                    description: item.description ?? '',
+                    status: STATUS_TO_LIBRARY[item.status],
+                    priority: item.priority,
+                    createdAt: item.createdAt.toISOString(),
+                    updatedAt: item.createdAt.toISOString(),
+                }));
+                return createSuccessResult({
+                    items,
+                    total: result.total,
+                    filtered: items.length,
+                });
+            }
+            catch (error) {
+                return createErrorResult(error instanceof Error ? error.message : String(error));
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
+    // backlog_write
+    // ---------------------------------------------------------------------------
+    const backlogWriteTool = defineTool({
+        name: 'backlog_write',
+        description: 'Create, update, or delete backlog items. ' +
+            'Actions: add (new item), update (modify existing), delete (remove), replace (full list). ' +
+            'IDs are auto-generated for new items based on type (e.g., FEAT-001, BUG-002).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['add', 'update', 'delete', 'replace'],
+                    description: 'Action to perform',
+                },
+                item: {
+                    type: 'object',
+                    description: 'Item to add or update (for add/update actions)',
+                    properties: {
+                        id: { type: 'string', description: 'Item ID (required for update)' },
+                        type: {
+                            type: 'string',
+                            enum: ['feature', 'bug', 'chore', 'spike'],
+                            description: 'Item type (required for add)',
+                        },
+                        title: { type: 'string', description: 'Item title' },
+                        description: { type: 'string', description: 'Detailed description' },
+                        status: {
+                            type: 'string',
+                            enum: ['backlog', 'in-progress', 'done', 'blocked'],
+                            description: 'Item status',
+                        },
+                        priority: {
+                            type: 'string',
+                            enum: ['critical', 'high', 'medium', 'low'],
+                            description: 'Priority level',
+                        },
+                        owner: {
+                            type: 'string',
+                            description: 'Owner/assignee of the item',
+                        },
+                        commit_hash: {
+                            type: 'string',
+                            description: 'Git commit hash associated with the item (for update)',
+                        },
+                    },
+                },
+                deleteId: {
+                    type: 'string',
+                    description: 'Item ID to delete (for delete action)',
+                },
+                items: {
+                    type: 'array',
+                    description: 'Full list of items (for replace action)',
+                    items: {
+                        type: 'object',
+                    },
+                },
+            },
+            required: ['action'],
+        },
+        execute: async (input) => {
+            try {
+                const projectId = ctx.currentProjectId;
+                if (!projectId) {
+                    return createErrorResult('No active project. Use /projects to select a project first.');
+                }
+                switch (input.action) {
+                    case 'add': {
+                        if (!input.item) {
+                            return createErrorResult('Item is required for add action');
+                        }
+                        if (!input.item.type) {
+                            return createErrorResult('Item type is required for add action');
+                        }
+                        if (!input.item.title) {
+                            return createErrorResult('Item title is required for add action');
+                        }
+                        const createInput = {
+                            project_id: projectId,
+                            type: TYPE_TO_CLI[input.item.type],
+                            title: input.item.title,
+                            description: input.item.description,
+                            priority: input.item.priority,
+                            owner: input.item.owner,
+                        };
+                        const item = await ctx.workItems.create(createInput);
+                        return createSuccessResult({
+                            success: true,
+                            action: 'add',
+                            itemId: item.itemId,
+                            message: `Created ${item.itemId}: "${item.title}"`,
+                        });
+                    }
+                    case 'update': {
+                        if (!input.item?.id) {
+                            return createErrorResult('Item ID is required for update action');
+                        }
+                        const existingItem = await ctx.workItems.getByItemId(projectId, input.item.id);
+                        if (!existingItem) {
+                            return createErrorResult(`Item not found: ${input.item.id}`);
+                        }
+                        const updateInput = {};
+                        if (input.item.status) {
+                            updateInput.status = STATUS_TO_CLI[input.item.status];
+                        }
+                        if (input.item.priority) {
+                            updateInput.priority = input.item.priority;
+                        }
+                        if (input.item.title) {
+                            updateInput.title = input.item.title;
+                        }
+                        if (input.item.description !== undefined) {
+                            updateInput.description = input.item.description;
+                        }
+                        if (input.item.owner !== undefined) {
+                            updateInput.owner = input.item.owner;
+                        }
+                        if (input.item.commit_hash) {
+                            updateInput.commit_hash = input.item.commit_hash;
+                        }
+                        const updated = await ctx.workItems.update(existingItem.id, updateInput);
+                        if (!updated) {
+                            return createErrorResult(`Failed to update item: ${input.item.id}`);
+                        }
+                        return createSuccessResult({
+                            success: true,
+                            action: 'update',
+                            itemId: input.item.id,
+                            message: `Updated ${input.item.id}`,
+                        });
+                    }
+                    case 'delete': {
+                        const deleteId = input.deleteId ?? input.item?.id;
+                        if (!deleteId) {
+                            return createErrorResult('deleteId or item.id is required for delete action');
+                        }
+                        const existingItem = await ctx.workItems.getByItemId(projectId, deleteId);
+                        if (!existingItem) {
+                            return createErrorResult(`Item not found: ${deleteId}`);
+                        }
+                        const deleted = await ctx.workItems.delete(existingItem.id);
+                        if (!deleted) {
+                            return createErrorResult(`Failed to delete item: ${deleteId}`);
+                        }
+                        return createSuccessResult({
+                            success: true,
+                            action: 'delete',
+                            itemId: deleteId,
+                            message: `Deleted ${deleteId}`,
+                        });
+                    }
+                    case 'replace': {
+                        if (!input.items) {
+                            return createErrorResult('Items array is required for replace action');
+                        }
+                        // Delete all existing items
+                        const existing = await ctx.workItems.query({
+                            project_id: projectId,
+                            limit: 1000,
+                            offset: 0,
+                        });
+                        for (const item of existing.items) {
+                            await ctx.workItems.delete(item.id);
+                        }
+                        // Add all new items
+                        const newIds = [];
+                        for (const newItem of input.items) {
+                            const createInput = {
+                                project_id: projectId,
+                                type: TYPE_TO_CLI[newItem.type],
+                                title: newItem.title,
+                                description: newItem.description,
+                                priority: newItem.priority,
+                            };
+                            const created = await ctx.workItems.create(createInput);
+                            newIds.push(created.itemId);
+                            // Update status if not backlog
+                            if (newItem.status && newItem.status !== 'backlog') {
+                                await ctx.workItems.update(created.id, {
+                                    status: STATUS_TO_CLI[newItem.status],
+                                });
+                            }
+                        }
+                        return createSuccessResult({
+                            success: true,
+                            action: 'replace',
+                            itemCount: input.items.length,
+                            newIds,
+                            message: `Replaced backlog with ${String(input.items.length)} items`,
+                        });
+                    }
+                    default:
+                        return createErrorResult(`Unknown action: ${input.action}`);
+                }
+            }
+            catch (error) {
+                return createErrorResult(error instanceof Error ? error.message : String(error));
+            }
+        },
+    });
+    return [backlogReadTool, backlogWriteTool];
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Document Tools — CRUD operations for project documents.
+ *
+ * 4 tools: project_document_add, project_document_get,
+ *          project_document_list, project_document_delete
+ *
+ * Ported from CLI's src/tools/document-db.ts.
+ */
+import type { PlatformToolsConfig } from '../context.js';
+export declare function createDocumentTools(config: PlatformToolsConfig): import("@compilr-dev/agents").Tool<{
+    project_id?: number;
+    doc_type: string;
+    title: string;
+    content: string;
+}>[];