@compilr-dev/sdk 0.1.9 → 0.1.11

package/dist/index.d.ts

@@ -47,8 +47,8 @@ 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 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 { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, } from './platform/index.js';
 export { STEP_ORDER, GUIDED_STEP_CRITERIA, getNextStep, isValidTransition, getStepCriteria, formatStepDisplay, getStepNumber, } from './platform/index.js';
 export { platformSkills, designSkill, sketchSkill, prdSkill, refineSkill, refineItemSkill, architectureSkill, sessionNotesSkill, buildSkill, scaffoldSkill, } from './skills/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';

package/dist/index.js

@@ -77,7 +77,7 @@ shouldIncludeModule, getEstimatedTokensForConditions, getTotalEstimatedTokens, }
 // =============================================================================
 // Platform Tools (runtime — createPlatformTools factory + individual factories)
 // =============================================================================
-export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, } from './platform/index.js';
+export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, } from './platform/index.js';
 // =============================================================================
 // Platform Workflow (pure step-criteria logic)
 // =============================================================================

package/dist/platform/context.d.ts

@@ -5,12 +5,16 @@
  * underlying storage backend (SQLite in CLI, PostgreSQL in web/API).
  */
 import type { IProjectRepository, IWorkItemRepository, IDocumentRepository, IPlanRepository } from './repositories.js';
+import type { IAnchorService, IArtifactService, IEpisodeService } from './services.js';
 export interface PlatformContext {
     readonly projects: IProjectRepository;
     readonly workItems: IWorkItemRepository;
     readonly documents: IDocumentRepository;
     readonly plans: IPlanRepository;
     currentProjectId?: number;
+    readonly anchors?: IAnchorService;
+    readonly artifacts?: IArtifactService;
+    readonly episodes?: IEpisodeService;
 }
 export interface PlatformHooks {
     /** Called when a project is resolved/selected as the current project */

package/dist/platform/index.d.ts

@@ -3,7 +3,8 @@
  */
 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 { 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, } from './tools/index.js';
+export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, } 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

@@ -2,6 +2,6 @@
  * Platform — Repository interfaces, data models, tools, and workflow.
  */
 // Platform tools (runtime)
-export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, } from './tools/index.js';
+export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, } 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/services.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Platform Service Interfaces — Non-DB services for anchors, artifacts, and episodes.
+ *
+ * These interfaces abstract CLI-specific implementations (AnchorManager, ArtifactStore,
+ * FileEpisodeStore) so tool definitions can live in the SDK.
+ */
+import type { AnchorPriority, WorkEpisode, ProjectWorkSummary } from '@compilr-dev/agents';
+export interface AnchorData {
+    id: string;
+    content: string;
+    priority: string;
+    scope: 'global' | 'project';
+    tags?: string[];
+}
+export interface IAnchorService {
+    add(input: {
+        content: string;
+        priority?: AnchorPriority;
+        scope?: 'global' | 'project';
+        tags?: string[];
+    }): Promise<AnchorData>;
+    remove(id: string): Promise<{
+        removed: boolean;
+        scope?: string;
+    }>;
+    list(options?: {
+        scope?: 'global' | 'project' | 'all';
+        priority?: AnchorPriority;
+    }): Promise<{
+        count: number;
+        activeProjectName: string | null;
+        anchors: AnchorData[];
+    }>;
+}
+export type ArtifactType = 'design' | 'plan' | 'review' | 'decision' | 'note';
+export interface ArtifactData {
+    id: string;
+    name: string;
+    agent: string;
+    type: ArtifactType;
+    content: string;
+    summary: string;
+    version: number;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface ArtifactSummaryData {
+    id: string;
+    name: string;
+    agent: string;
+    type: ArtifactType;
+    summary: string;
+    version: number;
+    updatedAt: Date;
+}
+export interface IArtifactService {
+    save(input: {
+        name: string;
+        type: ArtifactType;
+        content: string;
+        summary?: string;
+        agent?: string;
+    }): Promise<{
+        artifact: ArtifactData;
+        isUpdate: boolean;
+    }>;
+    getByName(name: string): Promise<ArtifactData | null>;
+    list(options?: {
+        type?: ArtifactType;
+        agent?: string;
+        search?: string;
+    }): Promise<ArtifactSummaryData[]>;
+    delete(name: string): Promise<ArtifactData | null>;
+}
+export type { WorkEpisode, ProjectWorkSummary } from '@compilr-dev/agents';
+export interface IEpisodeService {
+    getByFiles(files: string[]): Promise<WorkEpisode[]>;
+    getByAgent(agentId: string): Promise<WorkEpisode[]>;
+    getBySession(sessionId: string): Promise<WorkEpisode[]>;
+    getRecent(count: number): Promise<WorkEpisode[]>;
+    getWorkSummary(): Promise<ProjectWorkSummary>;
+}

package/dist/platform/services.js

@@ -0,0 +1,7 @@
+/**
+ * Platform Service Interfaces — Non-DB services for anchors, artifacts, and episodes.
+ *
+ * These interfaces abstract CLI-specific implementations (AnchorManager, ArtifactStore,
+ * FileEpisodeStore) so tool definitions can live in the SDK.
+ */
+export {};

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

@@ -0,0 +1,18 @@
+/**
+ * Anchor Tools — Agent tools for managing persistent context anchors.
+ *
+ * 3 tools: anchor_add, anchor_remove, anchor_list
+ *
+ * Ported from CLI's src/tools/anchor-tools.ts. Key adaptation:
+ * - getGlobalAnchorManager()/getAnchorManager()/getActiveProject() → anchors.*
+ */
+import type { AnchorPriority } from '@compilr-dev/agents';
+import type { PlatformToolsConfig } from '../context.js';
+export declare function createAnchorTools(config: PlatformToolsConfig): (import("@compilr-dev/agents").Tool<{
+    content: string;
+    priority?: AnchorPriority;
+    scope?: "global" | "project";
+    tags?: string[];
+}> | import("@compilr-dev/agents").Tool<{
+    id: string;
+}>)[];

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

@@ -0,0 +1,172 @@
+/**
+ * Anchor Tools — Agent tools for managing persistent context anchors.
+ *
+ * 3 tools: anchor_add, anchor_remove, anchor_list
+ *
+ * Ported from CLI's src/tools/anchor-tools.ts. Key adaptation:
+ * - getGlobalAnchorManager()/getAnchorManager()/getActiveProject() → anchors.*
+ */
+import { defineTool } from '@compilr-dev/agents';
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+export function createAnchorTools(config) {
+    // Safe: callers guard with `if (config.context.anchors)` before calling
+    const anchors = config.context.anchors;
+    if (!anchors)
+        throw new Error('anchors service required');
+    // ---------------------------------------------------------------------------
+    // anchor_add
+    // ---------------------------------------------------------------------------
+    const anchorAddTool = defineTool({
+        name: 'anchor_add',
+        description: 'Add critical information that must survive context compaction. ' +
+            'Use this for: project context, important decisions, user preferences, ' +
+            'architectural constraints, or any information that should persist across the entire conversation. ' +
+            'Anchors are always included at the top of the context window.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                content: {
+                    type: 'string',
+                    description: 'The critical information to preserve. Keep it concise but complete.',
+                },
+                priority: {
+                    type: 'string',
+                    enum: ['critical', 'safety', 'info'],
+                    description: 'Priority level. "critical" for must-never-forget info (user preferences, key constraints), ' +
+                        '"safety" for safety-related context, "info" for general helpful context.',
+                },
+                scope: {
+                    type: 'string',
+                    enum: ['global', 'project'],
+                    description: 'Scope for the anchor. "global" persists across all projects, ' +
+                        '"project" is specific to the current project (requires active project).',
+                },
+                tags: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Optional tags for categorization (e.g., ["architecture", "decision"])',
+                },
+            },
+            required: ['content'],
+        },
+        execute: async (input) => {
+            try {
+                if (!input.content || input.content.trim().length === 0) {
+                    return { success: false, error: 'Anchor content is required and cannot be empty' };
+                }
+                const result = await anchors.add({
+                    content: input.content.trim(),
+                    priority: input.priority,
+                    scope: input.scope,
+                    tags: input.tags,
+                });
+                return {
+                    success: true,
+                    result: {
+                        id: result.id,
+                        content: result.content,
+                        priority: result.priority,
+                        scope: result.scope,
+                        tags: result.tags,
+                        message: `Anchor added successfully (${result.scope} scope, ${result.priority} priority)`,
+                    },
+                };
+            }
+            catch (err) {
+                return {
+                    success: false,
+                    error: `Failed to add anchor: ${err instanceof Error ? err.message : String(err)}`,
+                };
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
+    // anchor_remove
+    // ---------------------------------------------------------------------------
+    const anchorRemoveTool = defineTool({
+        name: 'anchor_remove',
+        description: 'Remove an anchor by its ID. Use this to clean up outdated or no longer relevant anchors. ' +
+            'Use anchor_list first to see available anchors and their IDs.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'string',
+                    description: 'The ID of the anchor to remove',
+                },
+            },
+            required: ['id'],
+        },
+        execute: async (input) => {
+            try {
+                if (!input.id || input.id.trim().length === 0) {
+                    return { success: false, error: 'Anchor ID is required' };
+                }
+                const result = await anchors.remove(input.id.trim());
+                if (!result.removed) {
+                    return { success: false, error: `Anchor with ID "${input.id.trim()}" not found` };
+                }
+                return {
+                    success: true,
+                    result: {
+                        id: input.id.trim(),
+                        scope: result.scope,
+                        message: `Anchor removed successfully (was ${result.scope ?? 'unknown'} scope)`,
+                    },
+                };
+            }
+            catch (err) {
+                return {
+                    success: false,
+                    error: `Failed to remove anchor: ${err instanceof Error ? err.message : String(err)}`,
+                };
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
+    // anchor_list
+    // ---------------------------------------------------------------------------
+    const anchorListTool = defineTool({
+        name: 'anchor_list',
+        description: 'List all anchors. Returns anchor IDs, content, priority, and scope. ' +
+            'Use this to see what persistent context is available before adding or removing anchors.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                scope: {
+                    type: 'string',
+                    enum: ['global', 'project', 'all'],
+                    description: 'Filter by scope: "global", "project", or "all" (default: "all")',
+                },
+                priority: {
+                    type: 'string',
+                    enum: ['critical', 'safety', 'info'],
+                    description: 'Filter by priority level',
+                },
+            },
+        },
+        execute: async (input) => {
+            try {
+                const result = await anchors.list({
+                    scope: input.scope,
+                    priority: input.priority,
+                });
+                return {
+                    success: true,
+                    result: {
+                        count: result.count,
+                        activeProject: result.activeProjectName,
+                        anchors: result.anchors,
+                    },
+                };
+            }
+            catch (err) {
+                return {
+                    success: false,
+                    error: `Failed to list anchors: ${err instanceof Error ? err.message : String(err)}`,
+                };
+            }
+        },
+    });
+    return [anchorAddTool, anchorRemoveTool, anchorListTool];
+}

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

@@ -0,0 +1,20 @@
+/**
+ * Artifact Tools — Team artifact management.
+ *
+ * 4 tools: artifact_save, artifact_get, artifact_list, artifact_delete
+ *
+ * Ported from CLI's src/tools/artifact-tools.ts. Key adaptation:
+ * - getTeamCheckpointer()/recordTeamActivity()/getCurrentProject() → artifacts.*
+ */
+import type { PlatformToolsConfig } from '../context.js';
+export declare function createArtifactTools(config: PlatformToolsConfig): (import("@compilr-dev/agents").Tool<{
+    name: string;
+    type: string;
+    content: string;
+    summary?: string;
+    agent?: string;
+}> | import("@compilr-dev/agents").Tool<{
+    type?: string;
+    agent?: string;
+    search?: string;
+}>)[];

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

@@ -0,0 +1,254 @@
+/**
+ * Artifact Tools — Team artifact management.
+ *
+ * 4 tools: artifact_save, artifact_get, artifact_list, artifact_delete
+ *
+ * Ported from CLI's src/tools/artifact-tools.ts. Key adaptation:
+ * - getTeamCheckpointer()/recordTeamActivity()/getCurrentProject() → artifacts.*
+ */
+import { defineTool, createSuccessResult, createErrorResult } from '@compilr-dev/agents';
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+export function createArtifactTools(config) {
+    // Safe: callers guard with `if (config.context.artifacts)` before calling
+    const artifacts = config.context.artifacts;
+    if (!artifacts)
+        throw new Error('artifacts service required');
+    // ---------------------------------------------------------------------------
+    // artifact_save
+    // ---------------------------------------------------------------------------
+    const artifactSaveTool = defineTool({
+        name: 'artifact_save',
+        description: 'Save a new artifact or update an existing one. Artifacts are named pieces of work that can be referenced by other agents. ' +
+            'Types: design (architecture/API specs), plan (task breakdowns), review (code reviews), decision (architectural decisions), note (general notes).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: {
+                    type: 'string',
+                    description: 'Artifact name (human-readable, unique within team). Example: "API Design v2", "Sprint 5 Plan", "Auth Module Review"',
+                },
+                type: {
+                    type: 'string',
+                    enum: ['design', 'plan', 'review', 'decision', 'note'],
+                    description: 'Artifact type: design (architecture), plan (task breakdown), review (feedback), decision (trade-off analysis), note (general)',
+                },
+                content: {
+                    type: 'string',
+                    description: 'Full artifact content in markdown format. Should be complete and self-contained.',
+                },
+                summary: {
+                    type: 'string',
+                    description: 'Optional one-line summary (auto-generated if not provided). Max 200 characters.',
+                },
+                agent: {
+                    type: 'string',
+                    description: 'Optional agent ID who created this artifact. Defaults to current agent.',
+                },
+            },
+            required: ['name', 'type', 'content'],
+        },
+        execute: async (input) => {
+            try {
+                const result = await artifacts.save({
+                    name: input.name,
+                    type: input.type,
+                    content: input.content,
+                    summary: input.summary,
+                    agent: input.agent,
+                });
+                const { artifact, isUpdate } = result;
+                if (isUpdate) {
+                    const output = [
+                        `Updated artifact "${artifact.name}" (v${String(artifact.version)})`,
+                        ``,
+                        `Type:    ${artifact.type}`,
+                        `Agent:   ${artifact.agent}`,
+                        `Summary: ${artifact.summary}`,
+                        `Updated: ${artifact.updatedAt.toISOString()}`,
+                    ].join('\n');
+                    return createSuccessResult(output);
+                }
+                else {
+                    const output = [
+                        `Created artifact "${artifact.name}"`,
+                        ``,
+                        `Type:    ${artifact.type}`,
+                        `Agent:   ${artifact.agent}`,
+                        `Summary: ${artifact.summary}`,
+                        `Created: ${artifact.createdAt.toISOString()}`,
+                    ].join('\n');
+                    return createSuccessResult(output);
+                }
+            }
+            catch (error) {
+                return createErrorResult(`Failed to save artifact: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
+    // artifact_get
+    // ---------------------------------------------------------------------------
+    const artifactGetTool = defineTool({
+        name: 'artifact_get',
+        description: 'Retrieve an artifact by name. Returns the full content and metadata. ' +
+            'Use artifact_list first to see available artifacts.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: {
+                    type: 'string',
+                    description: 'Name of the artifact to retrieve (case-insensitive)',
+                },
+            },
+            required: ['name'],
+        },
+        execute: async (input) => {
+            try {
+                const artifact = await artifacts.getByName(input.name);
+                if (!artifact) {
+                    // List available artifacts for suggestions
+                    const all = await artifacts.list();
+                    const searchLower = input.name.toLowerCase();
+                    const suggestions = all
+                        .filter((a) => a.name.toLowerCase().includes(searchLower) ||
+                        searchLower.includes(a.name.toLowerCase()))
+                        .slice(0, 3)
+                        .map((a) => `"${a.name}"`);
+                    let message = `Artifact "${input.name}" not found.`;
+                    if (suggestions.length > 0) {
+                        message += ` Did you mean: ${suggestions.join(', ')}?`;
+                    }
+                    else if (all.length > 0) {
+                        message += ` Available artifacts: ${all
+                            .slice(0, 5)
+                            .map((a) => `"${a.name}"`)
+                            .join(', ')}`;
+                        if (all.length > 5) {
+                            message += ` (+${String(all.length - 5)} more)`;
+                        }
+                    }
+                    else {
+                        message += ' No artifacts exist yet. Use artifact_save to create one.';
+                    }
+                    return createErrorResult(message);
+                }
+                const output = [
+                    `Artifact: ${artifact.name}`,
+                    ``,
+                    `Type:    ${artifact.type}`,
+                    `Agent:   ${artifact.agent}`,
+                    `Version: ${String(artifact.version)}`,
+                    `Summary: ${artifact.summary}`,
+                    `Created: ${artifact.createdAt.toISOString()}`,
+                    `Updated: ${artifact.updatedAt.toISOString()}`,
+                    ``,
+                    `--- Content ---`,
+                    artifact.content,
+                ].join('\n');
+                return createSuccessResult(output);
+            }
+            catch (error) {
+                return createErrorResult(`Failed to get artifact: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
+    // artifact_list
+    // ---------------------------------------------------------------------------
+    const artifactListTool = defineTool({
+        name: 'artifact_list',
+        description: 'List all artifacts in the team. Can filter by type or agent. ' +
+            'Returns summaries only - use artifact_get for full content.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                type: {
+                    type: 'string',
+                    enum: ['design', 'plan', 'review', 'decision', 'note'],
+                    description: 'Optional: filter by artifact type',
+                },
+                agent: {
+                    type: 'string',
+                    description: 'Optional: filter by agent ID',
+                },
+                search: {
+                    type: 'string',
+                    description: 'Optional: search by name or content',
+                },
+            },
+            required: [],
+        },
+        execute: async (input) => {
+            try {
+                const items = await artifacts.list({
+                    type: input.type,
+                    agent: input.agent,
+                    search: input.search,
+                });
+                // Sort by most recently updated
+                items.sort((a, b) => b.updatedAt.getTime() - a.updatedAt.getTime());
+                if (items.length === 0) {
+                    let message = 'No artifacts found';
+                    if (input.type || input.agent || input.search) {
+                        message += ' matching the filter criteria';
+                    }
+                    message += '. Use artifact_save to create one.';
+                    return createSuccessResult(message);
+                }
+                const lines = [
+                    `Found ${String(items.length)} artifact${items.length === 1 ? '' : 's'}:`,
+                    ``,
+                ];
+                for (const a of items) {
+                    lines.push(`* ${a.name} [${a.type}]`);
+                    lines.push(`  Agent: ${a.agent} | v${String(a.version)} | Updated: ${a.updatedAt.toISOString().split('T')[0]}`);
+                    if (a.summary) {
+                        lines.push(`  ${a.summary}`);
+                    }
+                    lines.push(``);
+                }
+                lines.push(`Use artifact_get(name) to view full content.`);
+                return createSuccessResult(lines.join('\n'));
+            }
+            catch (error) {
+                return createErrorResult(`Failed to list artifacts: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
+    // artifact_delete
+    // ---------------------------------------------------------------------------
+    const artifactDeleteTool = defineTool({
+        name: 'artifact_delete',
+        description: 'Delete an artifact by name. This action cannot be undone.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: {
+                    type: 'string',
+                    description: 'Name of the artifact to delete (case-insensitive)',
+                },
+            },
+            required: ['name'],
+        },
+        execute: async (input) => {
+            try {
+                const deleted = await artifacts.delete(input.name);
+                if (!deleted) {
+                    return createErrorResult(`Artifact "${input.name}" not found.`);
+                }
+                const output = [
+                    `Deleted artifact "${deleted.name}"`,
+                    ``,
+                    `Type:  ${deleted.type}`,
+                    `Agent: ${deleted.agent}`,
+                ].join('\n');
+                return createSuccessResult(output);
+            }
+            catch (error) {
+                return createErrorResult(`Failed to delete artifact: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+    });
+    return [artifactSaveTool, artifactGetTool, artifactListTool, artifactDeleteTool];
+}

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

@@ -19,10 +19,6 @@ export function createDocumentTools(config) {
         inputSchema: {
             type: 'object',
             properties: {
-                project_id: {
-                    type: 'number',
-                    description: 'Project ID (uses active project if not provided)',
-                },
                 doc_type: {
                     type: 'string',
                     enum: ['prd', 'architecture', 'design', 'notes'],
@@ -36,6 +32,10 @@ export function createDocumentTools(config) {
                     type: 'string',
                     description: 'Document content (markdown)',
                 },
+                project_id: {
+                    type: 'number',
+                    description: 'Optional. Defaults to active project. Only needed to target a different project.',
+                },
             },
             required: ['doc_type', 'title', 'content'],
         },
@@ -78,15 +78,15 @@ export function createDocumentTools(config) {
         inputSchema: {
             type: 'object',
             properties: {
-                project_id: {
-                    type: 'number',
-                    description: 'Project ID (uses active project if not provided)',
-                },
                 doc_type: {
                     type: 'string',
                     enum: ['prd', 'architecture', 'design', 'notes'],
                     description: 'Document type to retrieve',
                 },
+                project_id: {
+                    type: 'number',
+                    description: 'Optional. Defaults to active project. Only needed to target a different project.',
+                },
             },
             required: ['doc_type'],
         },
@@ -132,7 +132,7 @@ export function createDocumentTools(config) {
             properties: {
                 project_id: {
                     type: 'number',
-                    description: 'Project ID (uses active project if not provided)',
+                    description: 'Optional. Defaults to active project. Only needed to target a different project.',
                 },
             },
             required: [],
@@ -172,15 +172,15 @@ export function createDocumentTools(config) {
         inputSchema: {
             type: 'object',
             properties: {
-                project_id: {
-                    type: 'number',
-                    description: 'Project ID (uses active project if not provided)',
-                },
                 doc_type: {
                     type: 'string',
                     enum: ['prd', 'architecture', 'design', 'notes'],
                     description: 'Document type to delete',
                 },
+                project_id: {
+                    type: 'number',
+                    description: 'Optional. Defaults to active project. Only needed to target a different project.',
+                },
             },
             required: ['doc_type'],
         },

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

@@ -0,0 +1,15 @@
+/**
+ * Episode Tools — Query work history.
+ *
+ * 1 tool: recall_work
+ *
+ * Ported from CLI's src/tools/recall-work-tool.ts. Key adaptation:
+ * - getGlobalEpisodeStore() → episodes.*
+ */
+import type { PlatformToolsConfig } from '../context.js';
+export declare function createEpisodeTools(config: PlatformToolsConfig): import("@compilr-dev/agents").Tool<{
+    files?: string[];
+    agentId?: string;
+    sessionId?: string;
+    recent?: number;
+}>[];

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

@@ -0,0 +1,92 @@
+/**
+ * Episode Tools — Query work history.
+ *
+ * 1 tool: recall_work
+ *
+ * Ported from CLI's src/tools/recall-work-tool.ts. Key adaptation:
+ * - getGlobalEpisodeStore() → episodes.*
+ */
+import { defineTool } from '@compilr-dev/agents';
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+export function createEpisodeTools(config) {
+    // Safe: callers guard with `if (config.context.episodes)` before calling
+    const episodes = config.context.episodes;
+    if (!episodes)
+        throw new Error('episodes service required');
+    // ---------------------------------------------------------------------------
+    // recall_work
+    // ---------------------------------------------------------------------------
+    const recallWorkTool = defineTool({
+        name: 'recall_work',
+        description: 'Query work history — episodes of what agents have done in this project. ' +
+            'Returns episodes with agent attribution, effort level, and affected files. ' +
+            'Use before destructive operations to check what work would be affected. ' +
+            'Use to understand what has been done in this session or by other agents.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                files: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Filter by file paths — returns episodes touching any of these files',
+                },
+                agentId: {
+                    type: 'string',
+                    description: 'Filter by agent ID (e.g., "default", "backend")',
+                },
+                sessionId: {
+                    type: 'string',
+                    description: 'Filter by session ID',
+                },
+                recent: {
+                    type: 'number',
+                    description: 'Return N most recent episodes (default: 20)',
+                },
+            },
+        },
+        execute: async (input) => {
+            try {
+                let results;
+                if (input.files && input.files.length > 0) {
+                    results = await episodes.getByFiles(input.files);
+                }
+                else if (input.agentId) {
+                    results = await episodes.getByAgent(input.agentId);
+                }
+                else if (input.sessionId) {
+                    results = await episodes.getBySession(input.sessionId);
+                }
+                else {
+                    results = await episodes.getRecent(input.recent ?? 20);
+                }
+                const summary = await episodes.getWorkSummary();
+                return {
+                    success: true,
+                    result: {
+                        episodes: results.map((ep) => ({
+                            id: ep.id,
+                            agentId: ep.agentId,
+                            terminalPrefix: ep.terminalPrefix,
+                            action: ep.action,
+                            summary: ep.summary,
+                            files: ep.files,
+                            effort: ep.effort,
+                            timestamp: ep.timestamp,
+                            toolCalls: ep.toolCalls,
+                        })),
+                        totalEpisodes: summary.episodeCount,
+                        totalEffort: summary.totalEffort,
+                        uncommittedCount: summary.uncommittedWork.length,
+                    },
+                };
+            }
+            catch (err) {
+                return {
+                    success: false,
+                    error: `Failed to recall work: ${err instanceof Error ? err.message : String(err)}`,
+                };
+            }
+        },
+    });
+    return [recallWorkTool];
+}

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

@@ -1,135 +1,25 @@
 /**
  * Platform Tools — Factory function for all platform tools.
  *
- * Returns 24 tool definitions operating against async PlatformContext repositories.
- * Decouples tool logic from SQLite storage, enabling mock-based testing and
- * future PostgreSQL/API backends.
+ * Returns up to 32 tool definitions operating against async PlatformContext.
+ * - 24 DB tools (always): project, workitem, document, plan, backlog
+ * - 3 anchor tools (if ctx.anchors provided)
+ * - 4 artifact tools (if ctx.artifacts provided)
+ * - 1 episode tool (if ctx.episodes provided)
  */
+import type { Tool } from '@compilr-dev/agents';
 import type { PlatformToolsConfig } from '../context.js';
 /**
- * Create all 24 platform tools operating against the given context.
+ * Create all platform tools operating against the given context.
+ * Returns 24 DB tools unconditionally, plus up to 8 service-based tools
+ * if the optional anchors/artifacts/episodes services are provided.
  */
-export declare function createPlatformTools(config: PlatformToolsConfig): (import("@compilr-dev/agents").Tool<{
-    project_id?: number;
-    name?: string;
-    path?: string;
-}> | import("@compilr-dev/agents").Tool<{
-    name: string;
-    display_name: string;
-    description?: string;
-    path?: string;
-    type?: string;
-    workflow_mode?: string;
-    language?: string;
-    framework?: string;
-    package_manager?: string;
-}> | import("@compilr-dev/agents").Tool<{
-    project_id?: number;
-    status?: string;
-    description?: string;
-    workflow_mode?: string;
-    lifecycle_state?: string;
-    current_item_id?: string;
-    git_remote?: string;
-    git_branch?: string;
-    last_context?: Record<string, unknown>;
-}> | import("@compilr-dev/agents").Tool<{
-    project_id?: number;
-    status?: string;
-    type?: string;
-    priority?: string;
-    owner?: string;
-    search?: string;
-    limit?: number;
-    offset?: number;
-}> | import("@compilr-dev/agents").Tool<{
-    project_id?: number;
-    type: string;
-    title: string;
-    description?: string;
-    priority?: string;
-    estimated_effort?: string;
-    owner?: string;
-}> | import("@compilr-dev/agents").Tool<{
-    item_id: string;
-    project_id?: number;
-    status?: string;
-    priority?: string;
-    owner?: string;
-    guided_step?: string;
-    title?: string;
-    description?: string;
-    commit_hash?: string;
-}> | import("@compilr-dev/agents").Tool<{
-    item_id: string;
-    reason: string;
-    force?: boolean;
-    project_id?: number;
-}> | import("@compilr-dev/agents").Tool<{
-    item_id: string;
-    agent_id: string;
-    project_id?: number;
-}> | import("@compilr-dev/agents").Tool<{
-    item_id: string;
-    to_agent_id: string;
-    notes?: string;
-    project_id?: number;
-}> | import("@compilr-dev/agents").Tool<{
-    project_id?: number;
-    doc_type: string;
-    title: string;
-    content: string;
-}> | import("@compilr-dev/agents").Tool<{
-    name: string;
-    content: string;
-    work_item_id?: number;
-    project_id?: number;
-}> | import("@compilr-dev/agents").Tool<{
-    plan_id: number;
-    content?: string;
-    status?: string;
-    work_item_id?: number | null;
-}> | import("@compilr-dev/agents").Tool<{
-    plan_id?: number;
-    name?: string;
-    project_id?: number;
-}> | import("@compilr-dev/agents").Tool<{
-    project_id?: number;
-    status?: string;
-    work_item_id?: number;
-    limit?: number;
-    order_by?: string;
-}> | 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;
-    }>;
-}>)[];
+export declare function createPlatformTools(config: PlatformToolsConfig): Tool<never>[];
 export { createProjectTools } from './project-tools.js';
 export { createWorkItemTools } from './workitem-tools.js';
 export { createDocumentTools } from './document-tools.js';
 export { createPlanTools } from './plan-tools.js';
 export { createBacklogTools } from './backlog-tools.js';
+export { createAnchorTools } from './anchor-tools.js';
+export { createArtifactTools } from './artifact-tools.js';
+export { createEpisodeTools } from './episode-tools.js';

package/dist/platform/tools/index.js

@@ -1,27 +1,46 @@
 /**
  * Platform Tools — Factory function for all platform tools.
  *
- * Returns 24 tool definitions operating against async PlatformContext repositories.
- * Decouples tool logic from SQLite storage, enabling mock-based testing and
- * future PostgreSQL/API backends.
+ * Returns up to 32 tool definitions operating against async PlatformContext.
+ * - 24 DB tools (always): project, workitem, document, plan, backlog
+ * - 3 anchor tools (if ctx.anchors provided)
+ * - 4 artifact tools (if ctx.artifacts provided)
+ * - 1 episode tool (if ctx.episodes provided)
  */
 import { createProjectTools } from './project-tools.js';
 import { createWorkItemTools } from './workitem-tools.js';
 import { createDocumentTools } from './document-tools.js';
 import { createPlanTools } from './plan-tools.js';
 import { createBacklogTools } from './backlog-tools.js';
+import { createAnchorTools } from './anchor-tools.js';
+import { createArtifactTools } from './artifact-tools.js';
+import { createEpisodeTools } from './episode-tools.js';
 /**
- * Create all 24 platform tools operating against the given context.
+ * Create all platform tools operating against the given context.
+ * Returns 24 DB tools unconditionally, plus up to 8 service-based tools
+ * if the optional anchors/artifacts/episodes services are provided.
  */
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 export function createPlatformTools(config) {
-    return [
+    // Use Tool<never>[] to accept any Tool<T> — the generic parameter is only
+    // relevant to execute() callers, not to the registry that stores them.
+    const tools = [
         ...createProjectTools(config),
         ...createWorkItemTools(config),
         ...createDocumentTools(config),
         ...createPlanTools(config),
         ...createBacklogTools(config),
     ];
+    if (config.context.anchors) {
+        tools.push(...createAnchorTools(config));
+    }
+    if (config.context.artifacts) {
+        tools.push(...createArtifactTools(config));
+    }
+    if (config.context.episodes) {
+        tools.push(...createEpisodeTools(config));
+    }
+    return tools;
 }
 // Re-export individual factory functions for selective use
 export { createProjectTools } from './project-tools.js';
@@ -29,3 +48,6 @@ export { createWorkItemTools } from './workitem-tools.js';
 export { createDocumentTools } from './document-tools.js';
 export { createPlanTools } from './plan-tools.js';
 export { createBacklogTools } from './backlog-tools.js';
+export { createAnchorTools } from './anchor-tools.js';
+export { createArtifactTools } from './artifact-tools.js';
+export { createEpisodeTools } from './episode-tools.js';

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

@@ -32,7 +32,7 @@ export function createPlanTools(config) {
                 },
                 project_id: {
                     type: 'number',
-                    description: 'Project ID (uses active project if not provided)',
+                    description: 'Optional. Defaults to active project. Only needed to target a different project.',
                 },
             },
             required: ['name', 'content'],
@@ -154,7 +154,7 @@ export function createPlanTools(config) {
                 },
                 project_id: {
                     type: 'number',
-                    description: 'Project ID (required if using name, uses active project if not provided)',
+                    description: 'Required when using name lookup. Defaults to active project.',
                 },
             },
             required: [],
@@ -220,10 +220,6 @@ export function createPlanTools(config) {
         inputSchema: {
             type: 'object',
             properties: {
-                project_id: {
-                    type: 'number',
-                    description: 'Project ID (uses active project if not provided)',
-                },
                 status: {
                     type: 'string',
                     enum: ['draft', 'approved', 'in_progress', 'completed', 'abandoned', 'all'],
@@ -242,6 +238,10 @@ export function createPlanTools(config) {
                     enum: ['updated_desc', 'updated_asc', 'created_desc', 'name_asc'],
                     description: 'Sort order (default: updated_desc)',
                 },
+                project_id: {
+                    type: 'number',
+                    description: 'Optional. Defaults to active project. Only needed to target a different project.',
+                },
             },
             required: [],
         },

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

@@ -225,7 +225,7 @@ export function createProjectTools(config) {
             properties: {
                 project_id: {
                     type: 'number',
-                    description: 'Project ID to update (uses active project if not provided)',
+                    description: 'Optional. Defaults to active project. Only needed to update a different project.',
                 },
                 status: {
                     type: 'string',

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

@@ -27,10 +27,6 @@ export function createWorkItemTools(config) {
         inputSchema: {
             type: 'object',
             properties: {
-                project_id: {
-                    type: 'number',
-                    description: 'Project ID (uses active project if not provided)',
-                },
                 status: {
                     type: 'string',
                     enum: ['backlog', 'in_progress', 'completed', 'skipped', 'all'],
@@ -62,6 +58,10 @@ export function createWorkItemTools(config) {
                     type: 'number',
                     description: 'Offset for pagination (default: 0)',
                 },
+                project_id: {
+                    type: 'number',
+                    description: 'Optional. Defaults to active project. Only needed to target a different project.',
+                },
             },
             required: [],
         },
@@ -125,10 +125,6 @@ export function createWorkItemTools(config) {
         inputSchema: {
             type: 'object',
             properties: {
-                project_id: {
-                    type: 'number',
-                    description: 'Project ID (uses active project if not provided)',
-                },
                 type: {
                     type: 'string',
                     enum: ['feature', 'bug', 'tech-debt', 'chore'],
@@ -156,6 +152,10 @@ export function createWorkItemTools(config) {
                     type: 'string',
                     description: 'Owner agent ID. Omit for unassigned.',
                 },
+                project_id: {
+                    type: 'number',
+                    description: 'Optional. Defaults to active project. Only needed to target a different project.',
+                },
             },
             required: ['type', 'title'],
         },
@@ -210,7 +210,7 @@ export function createWorkItemTools(config) {
                 },
                 project_id: {
                     type: 'number',
-                    description: 'Project ID (uses active project if not provided)',
+                    description: 'Optional. Defaults to active project. Only needed to target a different project.',
                 },
                 status: {
                     type: 'string',
@@ -315,15 +315,15 @@ export function createWorkItemTools(config) {
         inputSchema: {
             type: 'object',
             properties: {
-                project_id: {
-                    type: 'number',
-                    description: 'Project ID (uses active project if not provided)',
-                },
                 type: {
                     type: 'string',
                     enum: ['feature', 'bug', 'tech-debt', 'chore'],
                     description: 'Filter by type (optional)',
                 },
+                project_id: {
+                    type: 'number',
+                    description: 'Optional. Defaults to active project. Only needed to target a different project.',
+                },
             },
             required: [],
         },
@@ -376,7 +376,7 @@ export function createWorkItemTools(config) {
                 },
                 project_id: {
                     type: 'number',
-                    description: 'Project ID (uses active project if not provided)',
+                    description: 'Optional. Defaults to active project. Only needed to target a different project.',
                 },
             },
             required: ['item_id'],
@@ -416,7 +416,7 @@ export function createWorkItemTools(config) {
             properties: {
                 project_id: {
                     type: 'number',
-                    description: 'Project ID (uses active project if not provided)',
+                    description: 'Optional. Defaults to active project. Only needed to target a different project.',
                 },
             },
             required: [],
@@ -469,7 +469,7 @@ export function createWorkItemTools(config) {
                 },
                 project_id: {
                     type: 'number',
-                    description: 'Project ID (uses active project if not provided)',
+                    description: 'Optional. Defaults to active project. Only needed to target a different project.',
                 },
             },
             required: ['item_id', 'reason'],
@@ -591,7 +591,7 @@ export function createWorkItemTools(config) {
                 },
                 project_id: {
                     type: 'number',
-                    description: 'Project ID (uses active project if not provided)',
+                    description: 'Optional. Defaults to active project. Only needed to target a different project.',
                 },
             },
             required: ['item_id', 'agent_id'],
@@ -658,7 +658,7 @@ export function createWorkItemTools(config) {
                 },
                 project_id: {
                     type: 'number',
-                    description: 'Project ID (uses active project if not provided)',
+                    description: 'Optional. Defaults to active project. Only needed to target a different project.',
                 },
             },
             required: ['item_id', 'to_agent_id'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",
@@ -56,14 +56,15 @@
     "ajv": "^6.14.0"
   },
   "peerDependencies": {
-    "@compilr-dev/agents": "^0.3.14",
+    "@compilr-dev/agents": "^0.3.16",
     "@compilr-dev/agents-coding": "^1.0.2"
   },
   "devDependencies": {
     "@anthropic-ai/sdk": "^0.78.0",
-    "@compilr-dev/agents": "^0.3.14",
+    "@compilr-dev/agents": "^0.3.16",
     "@compilr-dev/agents-coding": "^1.0.2",
     "@eslint/js": "^9.39.1",
+    "@opentelemetry/api": "^1.9.0",
     "@types/node": "^25.2.3",
     "@vitest/coverage-v8": "^4.0.18",
     "eslint": "^9.39.1",