@compilr-dev/sdk 0.14.0 → 0.16.0

package/dist/actions/registry.js

@@ -14,7 +14,11 @@ export const ACTION_REGISTRY = [
         icon: 'Wand2',
         applicableTo: ['project'],
         category: 'design',
-        suggestedRole: 'architect',
+        // BA owns requirements: the 'ba' role (analyst profile) has both
+        // backlog_write and documents, so it can complete the full /design action
+        // (create work items + write the PRD). The architect profile lacks
+        // backlog_write and cannot create the backlog.
+        suggestedRole: 'ba',
         needsInput: true,
         inputPrompt: 'What would you like to design?',
     },
@@ -34,8 +38,13 @@ export const ACTION_REGISTRY = [
         description: 'Create a product requirements document',
         icon: 'FileText',
         applicableTo: ['project'],
-        category: 'planning',
-        suggestedRole: 'pm',
+        // PRD is artifact-authoring (requirements), grouped with design/architecture
+        // rather than backlog-breakdown 'planning' (refine/refine-item).
+        category: 'design',
+        // Requirements work → Business Analyst, not PM. The 'ba' role (analyst
+        // profile) is purpose-built for requirements gathering and has the
+        // documents tools needed to author the PRD.
+        suggestedRole: 'ba',
     },
     {
         id: 'architecture',

package/dist/canvas/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Canvas contract barrel — exposed at `@compilr-dev/sdk/canvas` (renderer-safe:
+ * pure types + validation, no node deps). Tools live in the platform module.
+ */
+export * from './types.js';
+export * from './validate.js';

package/dist/canvas/index.js

@@ -0,0 +1,6 @@
+/**
+ * Canvas contract barrel — exposed at `@compilr-dev/sdk/canvas` (renderer-safe:
+ * pure types + validation, no node deps). Tools live in the platform module.
+ */
+export * from './types.js';
+export * from './validate.js';

package/dist/canvas/types.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Canvas — shared contract types.
+ *
+ * A Canvas is a persisted visual artifact the agent authors as HTML/SVG, with an
+ * optional controls manifest that surfaces live parameters ("Tweaks"). These
+ * types are the host-agnostic contract: the SDK owns them + the tools; hosts
+ * (Desktop) own the renderer.
+ *
+ * Intentionally dependency-free so this module can be exposed at the renderer-safe
+ * subpath `@compilr-dev/sdk/canvas` (the Desktop renderer needs the control types
+ * + validation without pulling node-only deps — same pattern as `.../errors`).
+ */
+export type CanvasType = 'infographic' | 'carousel' | 'board';
+/** A control's runtime value. */
+export type ParamValue = string | number | boolean;
+export interface SliderControl {
+    type: 'slider';
+    param: string;
+    label: string;
+    default: number;
+    min: number;
+    max: number;
+    step?: number;
+    unit?: string;
+    group?: string;
+}
+export interface NumberControl {
+    type: 'number';
+    param: string;
+    label: string;
+    default: number;
+    min?: number;
+    max?: number;
+    step?: number;
+    group?: string;
+}
+export interface ToggleControl {
+    type: 'toggle';
+    param: string;
+    label: string;
+    default: boolean;
+    group?: string;
+}
+export interface SelectControl {
+    type: 'select';
+    param: string;
+    label: string;
+    default: string;
+    options: string[];
+    group?: string;
+}
+export interface ColorControl {
+    type: 'color';
+    param: string;
+    label: string;
+    default: string;
+    group?: string;
+}
+export interface TextControl {
+    type: 'text';
+    param: string;
+    label: string;
+    default: string;
+    placeholder?: string;
+    group?: string;
+}
+export type Control = SliderControl | NumberControl | ToggleControl | SelectControl | ColorControl | TextControl;
+export interface ControlManifest {
+    controls: Control[];
+}
+/** Full persisted canvas. `content` is the agent's raw HTML/SVG only — the CSP + bridge are injected by the host renderer, never stored. */
+export interface CanvasRecord {
+    id: string;
+    projectId: string;
+    type: CanvasType;
+    title: string;
+    content: string;
+    controls: ControlManifest;
+    /** Current tweak state; seeded from control defaults on create. */
+    values: Record<string, ParamValue>;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/** Lightweight list entry (no content). */
+export interface CanvasSummary {
+    id: string;
+    projectId: string;
+    type: CanvasType;
+    title: string;
+    updatedAt: Date;
+}
+/**
+ * Host-implemented persistence for canvases (DB-backed). Optional field on
+ * PlatformContext — the canvas tools are absent when a host doesn't provide it.
+ */
+export interface ICanvasService {
+    create(input: {
+        type: CanvasType;
+        title: string;
+        content: string;
+        controls?: ControlManifest;
+        values?: Record<string, ParamValue>;
+        /** Defaults to the current project when omitted. */
+        projectId?: string;
+    }): Promise<CanvasRecord>;
+    update(id: string, patch: Partial<Pick<CanvasRecord, 'title' | 'content' | 'controls' | 'values'>>): Promise<CanvasRecord>;
+    get(id: string): Promise<CanvasRecord | null>;
+    /** Metadata only; scoped to the current project when projectId omitted. */
+    list(projectId?: string): Promise<CanvasSummary[]>;
+    delete(id: string): Promise<CanvasRecord | null>;
+}
+/** Seed a values map from a manifest's control defaults. */
+export declare function seedValues(manifest: ControlManifest | undefined): Record<string, ParamValue>;

package/dist/canvas/types.js

@@ -0,0 +1,21 @@
+/**
+ * Canvas — shared contract types.
+ *
+ * A Canvas is a persisted visual artifact the agent authors as HTML/SVG, with an
+ * optional controls manifest that surfaces live parameters ("Tweaks"). These
+ * types are the host-agnostic contract: the SDK owns them + the tools; hosts
+ * (Desktop) own the renderer.
+ *
+ * Intentionally dependency-free so this module can be exposed at the renderer-safe
+ * subpath `@compilr-dev/sdk/canvas` (the Desktop renderer needs the control types
+ * + validation without pulling node-only deps — same pattern as `.../errors`).
+ */
+/** Seed a values map from a manifest's control defaults. */
+export function seedValues(manifest) {
+    const values = {};
+    if (!manifest)
+        return values;
+    for (const c of manifest.controls)
+        values[c.param] = c.default;
+    return values;
+}

package/dist/canvas/validate.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Canvas controls-manifest validation. Dependency-free (renderer-safe subpath).
+ */
+import type { ControlManifest } from './types.js';
+export interface ManifestValidationResult {
+    ok: boolean;
+    errors: string[];
+}
+/**
+ * Validate a controls manifest: array shape, unique + well-formed param names,
+ * and per-type default sanity (in range / in options / correct primitive).
+ */
+export declare function validateControlManifest(manifest: ControlManifest): ManifestValidationResult;

package/dist/canvas/validate.js

@@ -0,0 +1,89 @@
+/**
+ * Canvas controls-manifest validation. Dependency-free (renderer-safe subpath).
+ */
+/** Param names must be usable as a CSS custom property suffix and a JS key. */
+const PARAM_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+const HEX_RE = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
+/**
+ * Validate a controls manifest: array shape, unique + well-formed param names,
+ * and per-type default sanity (in range / in options / correct primitive).
+ */
+export function validateControlManifest(manifest) {
+    const errors = [];
+    // Treat the manifest as untrusted (agent JSON), not the static type.
+    const rawControls = manifest.controls;
+    if (!Array.isArray(rawControls)) {
+        return { ok: false, errors: ['manifest.controls must be an array'] };
+    }
+    const seen = new Set();
+    for (const raw of rawControls) {
+        const param = raw.param;
+        if (typeof param !== 'string' || !PARAM_RE.test(param)) {
+            errors.push(`invalid param name "${String(param)}" (must match ${PARAM_RE.source})`);
+        }
+        else if (seen.has(param)) {
+            errors.push(`duplicate param "${param}"`);
+        }
+        if (typeof param === 'string')
+            seen.add(param);
+        validateDefault(raw, errors);
+    }
+    return { ok: errors.length === 0, errors };
+}
+function validateDefault(control, errors) {
+    const c = control;
+    const p = c.param;
+    switch (c.type) {
+        case 'slider': {
+            const { min, max, default: d } = c;
+            if (typeof min === 'number' && typeof max === 'number' && min > max) {
+                errors.push(`${p}: min ${String(min)} > max ${String(max)}`);
+            }
+            if (typeof d !== 'number') {
+                errors.push(`${p}: slider default must be a number`);
+            }
+            else if (typeof min === 'number' && typeof max === 'number' && (d < min || d > max)) {
+                errors.push(`${p}: default ${String(d)} out of range [${String(min)}, ${String(max)}]`);
+            }
+            break;
+        }
+        case 'number': {
+            const { min, max, default: d } = c;
+            if (typeof d !== 'number') {
+                errors.push(`${p}: number default must be a number`);
+            }
+            else {
+                if (typeof min === 'number' && d < min)
+                    errors.push(`${p}: default < min`);
+                if (typeof max === 'number' && d > max)
+                    errors.push(`${p}: default > max`);
+            }
+            break;
+        }
+        case 'toggle':
+            if (typeof c.default !== 'boolean')
+                errors.push(`${p}: toggle default must be boolean`);
+            break;
+        case 'select': {
+            const opts = c.options;
+            if (!Array.isArray(opts) || opts.length === 0) {
+                errors.push(`${p}: select needs a non-empty options array`);
+            }
+            else if (!opts.includes(c.default)) {
+                errors.push(`${p}: default "${String(c.default)}" is not in options`);
+            }
+            break;
+        }
+        case 'color':
+            if (typeof c.default !== 'string' || !HEX_RE.test(c.default)) {
+                errors.push(`${p}: color default must be a hex color (e.g. #FF5722)`);
+            }
+            break;
+        case 'text':
+            if (typeof c.default !== 'string')
+                errors.push(`${p}: text default must be a string`);
+            break;
+        default:
+            errors.push(`${p}: unknown control type "${c.type}"`);
+    }
+}

package/dist/errors/classify.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Agent-error classification.
+ *
+ * Provider/agent failures surface to hosts in two shapes:
+ *  - as a thrown `ProviderError` instance (in-process — e.g. the CLI), or
+ *  - as a stringified message after crossing an IPC/serialization boundary
+ *    (e.g. the Desktop app's `agent.chat` IPC returns `error: string`).
+ *
+ * Hosts were string-matching the message independently to detect the common
+ * first-run failure (a missing/invalid API key → 401), which is duplicated and
+ * fragile. This centralizes the classification so every host shares one
+ * implementation; the *remediation copy* stays host-specific (the CLI tells the
+ * user to run /config or set an env var; Desktop points to Settings).
+ */
+export type AgentErrorCategory = 'auth' | 'rate_limit' | 'overloaded' | 'server' | 'connection' | 'unknown';
+export interface AgentErrorInfo {
+    category: AgentErrorCategory;
+    /** HTTP status code if one could be determined. */
+    statusCode?: number;
+    /** The original message text (for logging / fallback display). */
+    raw: string;
+}
+/**
+ * Classify an agent/provider error into a stable category. Accepts a thrown
+ * `ProviderError` instance (read by duck-typing its `statusCode`), any `Error`,
+ * or a stringified message (post-IPC).
+ */
+export declare function classifyAgentError(err: unknown): AgentErrorInfo;
+/** Convenience: true when the failure is a missing/invalid API key. */
+export declare function isApiKeyError(err: unknown): boolean;

package/dist/errors/classify.js

@@ -0,0 +1,80 @@
+/**
+ * Agent-error classification.
+ *
+ * Provider/agent failures surface to hosts in two shapes:
+ *  - as a thrown `ProviderError` instance (in-process — e.g. the CLI), or
+ *  - as a stringified message after crossing an IPC/serialization boundary
+ *    (e.g. the Desktop app's `agent.chat` IPC returns `error: string`).
+ *
+ * Hosts were string-matching the message independently to detect the common
+ * first-run failure (a missing/invalid API key → 401), which is duplicated and
+ * fragile. This centralizes the classification so every host shares one
+ * implementation; the *remediation copy* stays host-specific (the CLI tells the
+ * user to run /config or set an env var; Desktop points to Settings).
+ */
+/** Pull a usable message string out of any thrown value. */
+function messageOf(err) {
+    if (typeof err === 'string')
+        return err;
+    if (err instanceof Error)
+        return err.message;
+    if (err && typeof err === 'object' && 'message' in err) {
+        return String(err.message);
+    }
+    return String(err);
+}
+/**
+ * First HTTP status code in the text, if any (e.g. "ProviderError: 401 ...").
+ * Uses a curated set of codes providers actually return, so a port number or IP
+ * octet isn't misread as a status (e.g. `ECONNREFUSED 127.0.0.1:443` must not
+ * read as 443 — that would mask a connection error as an HTTP one).
+ */
+function statusFromText(text) {
+    const m = text.match(/\b(400|401|403|404|408|409|413|422|429|500|502|503|504|529)\b/);
+    return m ? Number(m[1]) : undefined;
+}
+function categorize(statusCode, text) {
+    const lower = text.toLowerCase();
+    // Auth: key issues. Match on status OR the provider's textual markers, since a
+    // stringified error may not preserve the numeric code.
+    if (statusCode === 401 ||
+        statusCode === 403 ||
+        /authentication_error|invalid x-api-key|invalid api key|no api key|x-api-key|permission_error|unauthorized/.test(lower)) {
+        return 'auth';
+    }
+    if (statusCode === 429 || /rate.?limit|too many requests/.test(lower))
+        return 'rate_limit';
+    if (statusCode === 529 || /overloaded/.test(lower))
+        return 'overloaded';
+    if ((statusCode !== undefined && statusCode >= 500 && statusCode < 600) ||
+        /internal server error/.test(lower)) {
+        return 'server';
+    }
+    if (statusCode === undefined &&
+        /econnrefused|econnreset|etimedout|enotfound|network|socket|dns|connection/.test(lower)) {
+        return 'connection';
+    }
+    return 'unknown';
+}
+/**
+ * Classify an agent/provider error into a stable category. Accepts a thrown
+ * `ProviderError` instance (read by duck-typing its `statusCode`), any `Error`,
+ * or a stringified message (post-IPC).
+ */
+export function classifyAgentError(err) {
+    const raw = messageOf(err);
+    // A thrown ProviderError carries a numeric `statusCode`; prefer it. Fall back
+    // to parsing a status out of the message text (the stringified/IPC case).
+    let statusCode;
+    if (err && typeof err === 'object' && 'statusCode' in err && typeof err.statusCode === 'number') {
+        statusCode = err.statusCode;
+    }
+    else {
+        statusCode = statusFromText(raw);
+    }
+    return { category: categorize(statusCode, raw), statusCode, raw };
+}
+/** Convenience: true when the failure is a missing/invalid API key. */
+export function isApiKeyError(err) {
+    return classifyAgentError(err).category === 'auth';
+}

package/dist/index.d.ts

@@ -64,7 +64,7 @@ export { detectProject, suggestProjectType, detectCommon } from './detection/ind
 export type { DetectProjectOptions, DetectionResult, ContentSummary } from './detection/index.js';
 export { createGuideTool, SHARED_GUIDE_ENTRIES, searchGuideEntries, topicToGuideEntry, } from './guide/index.js';
 export type { GuideEntry, ContentTopic, ContentSection, GuideToolConfig } from './guide/index.js';
-export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, createImageTools, ProjectAnchorStore, FileArtifactService, } from './platform/index.js';
+export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, createCanvasTools, createImageTools, ProjectAnchorStore, FileArtifactService, } from './platform/index.js';
 export type { ProjectAnchorStoreConfig, FileArtifactServiceConfig, ImageToolsConfig, ImageResizer, } from './platform/index.js';
 export { STEP_ORDER, GUIDED_STEP_CRITERIA, getNextStep, isValidTransition, getStepCriteria, formatStepDisplay, getStepNumber, } from './platform/index.js';
 export type { CustomSkill, CompilrSkillExtension, ForkedFromMarker, SkillEligibilityContext, SkillCollision, SkillDiffLine, SkillValidationIssue, ScopeConfig, SkillResolution, } from './skills/index.js';
@@ -78,6 +78,10 @@ export { PROJECT_TYPES, getProjectTypeConfig, getEnrichedProjectTypeConfig, getP
 export type { ActionMeta, SkillMeta } from './project-types/index.js';
 export type { ProjectTypeConfig, ProjectPhase, SuggestedAgent, DocumentTemplate, } from './project-types/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 { classifyAgentError, isApiKeyError } from './errors/classify.js';
+export type { AgentErrorCategory, AgentErrorInfo } from './errors/classify.js';
+export { validateControlManifest, seedValues } from './canvas/index.js';
+export type { CanvasType, ParamValue, Control, ControlManifest, CanvasRecord, CanvasSummary, ICanvasService, SliderControl, NumberControl, ToggleControl, SelectControl, ColorControl, TextControl, ManifestValidationResult, } from './canvas/index.js';
 export type { Tool, HooksConfig, AgentEvent, Message, LLMProvider, AnchorInput, ToolExecutionResult, AgentRunResult, PermissionHandler, PermissionHandlerResponse, 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 { DEFAULT_PERMISSION_RULES, WRITE_TOOLS, findMatchingRule, permissionModeLabel, permissionLevelLabel, } from './permissions.js';
 export type { PermissionRule, PermissionMode, PermissionLevel } from './permissions.js';

package/dist/index.js

@@ -147,7 +147,7 @@ export { createGuideTool, SHARED_GUIDE_ENTRIES, searchGuideEntries, topicToGuide
 // =============================================================================
 // Platform Tools (runtime — createPlatformTools factory + individual factories)
 // =============================================================================
-export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, createImageTools, ProjectAnchorStore, FileArtifactService, } from './platform/index.js';
+export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, createCanvasTools, createImageTools, ProjectAnchorStore, FileArtifactService, } from './platform/index.js';
 // =============================================================================
 // Platform Workflow (pure step-criteria logic)
 // =============================================================================
@@ -193,6 +193,12 @@ AnchorManager,
 MCPManager, 
 // Error types
 AgentError, ProviderError, ToolError, ToolTimeoutError, MaxIterationsError, AbortError, } from '@compilr-dev/agents';
+// Error classification — shared by hosts to map provider/agent failures
+// (esp. missing/invalid API key) into stable categories + host-specific copy.
+export { classifyAgentError, isApiKeyError } from './errors/classify.js';
+// Canvas contract — shared visual-canvas types + controls-manifest validation.
+// Also exposed at the renderer-safe subpath `@compilr-dev/sdk/canvas`.
+export { validateControlManifest, seedValues } from './canvas/index.js';
 // =============================================================================
 // Shared Permission Defaults & Utilities
 // =============================================================================

package/dist/platform/context.d.ts

@@ -6,6 +6,7 @@
  */
 import type { IProjectRepository, IWorkItemRepository, IDocumentRepository, IPlanRepository, ICommentRepository } from './repositories.js';
 import type { IAnchorService, IArtifactService, IEpisodeService } from './services.js';
+import type { ICanvasService } from '../canvas/types.js';
 export interface PlatformContext {
     readonly projects: IProjectRepository;
     readonly workItems: IWorkItemRepository;
@@ -15,6 +16,7 @@ export interface PlatformContext {
     readonly anchors?: IAnchorService;
     readonly artifacts?: IArtifactService;
     readonly episodes?: IEpisodeService;
+    readonly canvas?: ICanvasService;
     readonly comments?: ICommentRepository;
 }
 export interface PlatformHooks {

package/dist/platform/index.d.ts

@@ -5,7 +5,7 @@ export type { ProjectType, ProjectStatus, RepoPattern, WorkflowMode, LifecycleSt
 export type { IProjectRepository, IWorkItemRepository, IDocumentRepository, IPlanRepository, ICommentRepository, } from './repositories.js';
 export type { IAnchorService, IArtifactService, IEpisodeService, AnchorData, ArtifactType, ArtifactData, ArtifactSummaryData, WorkEpisode, ProjectWorkSummary, } from './services.js';
 export type { PlatformContext, PlatformToolsConfig, PlatformHooks } from './context.js';
-export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, createImageTools, } from './tools/index.js';
+export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, createCanvasTools, createImageTools, } from './tools/index.js';
 export type { ImageToolsConfig, ImageResizer } from './tools/index.js';
 export { createSQLiteRepositories, SQLiteProjectRepository, SQLiteWorkItemRepository, SQLiteDocumentRepository, SQLitePlanRepository, SQLiteCommentRepository, getDatabase, closeDatabase, closeAllDatabases, databaseExists, SCHEMA_VERSION, SCHEMA_SQL, } from './sqlite/index.js';
 export type { SQLiteRepositories, CreateSQLiteRepositoriesOptions, ProjectDeleteHooks, ProjectRecord, WorkItemRecord, ProjectDocumentRecord, WorkItemCommentRecord, } from './sqlite/index.js';

package/dist/platform/index.js

@@ -2,7 +2,7 @@
  * Platform — Repository interfaces, data models, tools, and workflow.
  */
 // Platform tools (runtime)
-export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, createImageTools, } from './tools/index.js';
+export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, createCanvasTools, createImageTools, } from './tools/index.js';
 // SQLite implementations (concrete repositories)
 export { createSQLiteRepositories, SQLiteProjectRepository, SQLiteWorkItemRepository, SQLiteDocumentRepository, SQLitePlanRepository, SQLiteCommentRepository, getDatabase, closeDatabase, closeAllDatabases, databaseExists, SCHEMA_VERSION, SCHEMA_SQL, } from './sqlite/index.js';
 // File-based anchor service (shared by CLI and Desktop)

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

@@ -0,0 +1,21 @@
+/**
+ * Canvas Tools — agent authoring + management of visual canvases.
+ *
+ * 4 tools: canvas_write (create/update), canvas_list, canvas_get, canvas_delete.
+ *
+ * `content` is the agent's raw HTML/SVG; the host renderer injects the CSP +
+ * bridge and renders it in a sandboxed iframe. `controls` is the optional Tweaks
+ * manifest (validated here). Persistence is delegated to ICanvasService.
+ */
+import type { PlatformToolsConfig } from '../context.js';
+import type { ControlManifest } from '../../canvas/types.js';
+export declare function createCanvasTools(config: PlatformToolsConfig): (import("@compilr-dev/agents").Tool<{
+    type: string;
+    title: string;
+    html: string;
+    controls?: ControlManifest;
+    canvasId?: string;
+    projectId?: string;
+}> | import("@compilr-dev/agents").Tool<{
+    canvasId: string;
+}>)[];

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

@@ -0,0 +1,183 @@
+/**
+ * Canvas Tools — agent authoring + management of visual canvases.
+ *
+ * 4 tools: canvas_write (create/update), canvas_list, canvas_get, canvas_delete.
+ *
+ * `content` is the agent's raw HTML/SVG; the host renderer injects the CSP +
+ * bridge and renders it in a sandboxed iframe. `controls` is the optional Tweaks
+ * manifest (validated here). Persistence is delegated to ICanvasService.
+ */
+import { defineTool, createSuccessResult, createErrorResult } from '@compilr-dev/agents';
+import { truncateContent } from './truncate.js';
+import { seedValues } from '../../canvas/types.js';
+import { validateControlManifest } from '../../canvas/validate.js';
+const CANVAS_TYPES = ['infographic', 'carousel', 'board'];
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+export function createCanvasTools(config) {
+    const canvas = config.context.canvas;
+    if (!canvas)
+        throw new Error('canvas service required');
+    // ---------------------------------------------------------------------------
+    // canvas_write — create (no canvasId) or update (canvasId given)
+    // ---------------------------------------------------------------------------
+    const canvasWriteTool = defineTool({
+        name: 'canvas_write',
+        description: 'Create or update a visual canvas (infographic, carousel, or board) rendered from HTML/SVG. ' +
+            'Optionally declare a controls manifest ("Tweaks") of live parameters the user can adjust: ' +
+            'each control is { type: slider|number|toggle|select|color|text, param, label, default, ...type config }. ' +
+            'Bind params in your HTML via CSS custom properties var(--param), [data-bind="param"] text, and ' +
+            '[data-show="param"] visibility; for computed updates define window.applyParams(values) in a <script>. ' +
+            'Pass canvasId to update an existing canvas; omit it to create a new one.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                type: {
+                    type: 'string',
+                    enum: CANVAS_TYPES,
+                    description: 'Canvas kind: infographic (single composition), carousel (slide sheets), board (infinite 2D).',
+                },
+                title: { type: 'string', description: 'Canvas title (shown in the library and tab).' },
+                html: {
+                    type: 'string',
+                    description: 'The canvas content as HTML/SVG. Raw content only — the app injects the sandbox/CSP. ' +
+                        'May include a <script> defining window.applyParams(values) for live recompute.',
+                },
+                controls: {
+                    type: 'object',
+                    description: 'Optional Tweaks manifest: { "controls": [ { "type": "slider", "param": "headline", "label": "Headline", "default": 40, "min": 24, "max": 72 }, ... ] }.',
+                    properties: {
+                        controls: { type: 'array', items: { type: 'object' } },
+                    },
+                },
+                canvasId: {
+                    type: 'string',
+                    description: 'Existing canvas id to update. Omit to create a new canvas.',
+                },
+                projectId: {
+                    type: 'string',
+                    description: 'Optional project id. Defaults to the current project.',
+                },
+            },
+            required: ['type', 'title', 'html'],
+        },
+        execute: async (input) => {
+            try {
+                if (input.controls) {
+                    const check = validateControlManifest(input.controls);
+                    if (!check.ok) {
+                        return createErrorResult(`Invalid controls manifest:\n- ${check.errors.join('\n- ')}`);
+                    }
+                }
+                if (input.canvasId) {
+                    const updated = await canvas.update(input.canvasId, {
+                        title: input.title,
+                        content: input.html,
+                        // Re-seed values from the new manifest when controls are (re)declared.
+                        // Phase 1 keeps this simple; a later phase can preserve prior tweaks
+                        // for surviving params.
+                        ...(input.controls
+                            ? { controls: input.controls, values: seedValues(input.controls) }
+                            : {}),
+                    });
+                    return createSuccessResult(`Updated canvas "${updated.title}" (${updated.type})\nID: ${updated.id}`);
+                }
+                const controls = input.controls ?? { controls: [] };
+                const created = await canvas.create({
+                    type: input.type,
+                    title: input.title,
+                    content: input.html,
+                    controls,
+                    values: seedValues(controls),
+                    projectId: input.projectId,
+                });
+                return createSuccessResult(`Created canvas "${created.title}" (${created.type})\nID: ${created.id}`);
+            }
+            catch (error) {
+                return createErrorResult(`Failed to write canvas: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
+    // canvas_list
+    // ---------------------------------------------------------------------------
+    const canvasListTool = defineTool({
+        name: 'canvas_list',
+        description: 'List the canvases in the current (or given) project.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                projectId: { type: 'string', description: 'Optional project id. Defaults to current.' },
+            },
+            required: [],
+        },
+        execute: async (input) => {
+            try {
+                const items = await canvas.list(input.projectId);
+                if (items.length === 0)
+                    return createSuccessResult('No canvases yet.');
+                const lines = items.map((c) => `- [${c.type}] ${c.title}  (id: ${c.id})`);
+                return createSuccessResult([`${String(items.length)} canvas(es):`, ...lines].join('\n'));
+            }
+            catch (error) {
+                return createErrorResult(`Failed to list canvases: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
+    // canvas_get
+    // ---------------------------------------------------------------------------
+    const canvasGetTool = defineTool({
+        name: 'canvas_get',
+        description: 'Get a canvas by id, including its content, controls manifest, and current values.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                canvasId: { type: 'string', description: 'Canvas id.' },
+            },
+            required: ['canvasId'],
+        },
+        execute: async (input) => {
+            try {
+                const c = await canvas.get(input.canvasId);
+                if (!c)
+                    return createErrorResult(`Canvas "${input.canvasId}" not found.`);
+                const tc = truncateContent(c.content);
+                const output = `Canvas "${c.title}" (${c.type})\n` +
+                    `ID: ${c.id}\n` +
+                    `Controls: ${String(c.controls.controls.length)}\n\n` +
+                    `--- content ---\n` +
+                    tc.content;
+                return createSuccessResult(output);
+            }
+            catch (error) {
+                return createErrorResult(`Failed to get canvas: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
+    // canvas_delete
+    // ---------------------------------------------------------------------------
+    const canvasDeleteTool = defineTool({
+        name: 'canvas_delete',
+        description: 'Delete a canvas by id.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                canvasId: { type: 'string', description: 'Canvas id.' },
+            },
+            required: ['canvasId'],
+        },
+        execute: async (input) => {
+            try {
+                const deleted = await canvas.delete(input.canvasId);
+                if (!deleted)
+                    return createErrorResult(`Canvas "${input.canvasId}" not found.`);
+                return createSuccessResult(`Deleted canvas "${deleted.title}"`);
+            }
+            catch (error) {
+                return createErrorResult(`Failed to delete canvas: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+    });
+    return [canvasWriteTool, canvasListTool, canvasGetTool, canvasDeleteTool];
+}

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

@@ -31,5 +31,6 @@ export { createBacklogTools } from './backlog-tools.js';
 export { createAnchorTools } from './anchor-tools.js';
 export { createArtifactTools } from './artifact-tools.js';
 export { createEpisodeTools } from './episode-tools.js';
+export { createCanvasTools } from './canvas-tools.js';
 export { createImageTools } from './image-tools.js';
 export type { ImageToolsConfig, ImageResizer } from './image-tools.js';

package/dist/platform/tools/index.js

@@ -16,6 +16,7 @@ import { createBacklogTools } from './backlog-tools.js';
 import { createAnchorTools } from './anchor-tools.js';
 import { createArtifactTools } from './artifact-tools.js';
 import { createEpisodeTools } from './episode-tools.js';
+import { createCanvasTools } from './canvas-tools.js';
 import { createImageTools } from './image-tools.js';
 /**
  * Create all platform tools operating against the given context.
@@ -54,6 +55,9 @@ export function createPlatformTools(config, options) {
     if (config.context.episodes) {
         tools.push(...createEpisodeTools(config));
     }
+    if (config.context.canvas) {
+        tools.push(...createCanvasTools(config));
+    }
     return tools;
 }
 // Re-export individual factory functions for selective use
@@ -65,4 +69,5 @@ export { createBacklogTools } from './backlog-tools.js';
 export { createAnchorTools } from './anchor-tools.js';
 export { createArtifactTools } from './artifact-tools.js';
 export { createEpisodeTools } from './episode-tools.js';
+export { createCanvasTools } from './canvas-tools.js';
 export { createImageTools } from './image-tools.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",
@@ -17,6 +17,14 @@
     "./flow-runner": {
       "types": "./dist/flow-runner/index.d.ts",
       "import": "./dist/flow-runner/index.js"
+    },
+    "./errors": {
+      "types": "./dist/errors/classify.d.ts",
+      "import": "./dist/errors/classify.js"
+    },
+    "./canvas": {
+      "types": "./dist/canvas/index.d.ts",
+      "import": "./dist/canvas/index.js"
     }
   },
   "files": [