@decibelsystems/tools 2.0.0

package/dist/tools/shared/project.d.ts

@@ -0,0 +1,17 @@
+import { ResolvedProjectPaths } from '../../projectRegistry.js';
+import { ToolResult } from '../types.js';
+/**
+ * Wrap a tool handler with automatic project resolution.
+ * Handles PROJECT_NOT_FOUND errors with helpful hints.
+ */
+export declare function withProject<T>(args: {
+    projectId?: string;
+}, fn: (resolved: ResolvedProjectPaths) => Promise<T>): Promise<T>;
+/**
+ * Wrap a tool handler that requires a project, returning ToolResult on error.
+ * Use this for top-level tool handlers.
+ */
+export declare function withProjectResult(args: {
+    projectId?: string;
+}, fn: (resolved: ResolvedProjectPaths) => Promise<ToolResult>): Promise<ToolResult>;
+//# sourceMappingURL=project.d.ts.map

package/dist/tools/shared/project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../../../src/tools/shared/project.ts"],"names":[],"mappings":"AAMA,OAAO,EAEL,oBAAoB,EACrB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC;;;GAGG;AACH,wBAAsB,WAAW,CAAC,CAAC,EACjC,IAAI,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,EAC5B,EAAE,EAAE,CAAC,QAAQ,EAAE,oBAAoB,KAAK,OAAO,CAAC,CAAC,CAAC,GACjD,OAAO,CAAC,CAAC,CAAC,CAQZ;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,EAC5B,EAAE,EAAE,CAAC,QAAQ,EAAE,oBAAoB,KAAK,OAAO,CAAC,UAAU,CAAC,GAC1D,OAAO,CAAC,UAAU,CAAC,CAQrB"}

package/dist/tools/shared/project.js

@@ -0,0 +1,36 @@
+// ============================================================================
+// Project Resolution Helper
+// ============================================================================
+// Wraps tool handlers with automatic project resolution.
+// ============================================================================
+import { resolveProjectPaths, } from '../../projectRegistry.js';
+import { toolError } from './response.js';
+/**
+ * Wrap a tool handler with automatic project resolution.
+ * Handles PROJECT_NOT_FOUND errors with helpful hints.
+ */
+export async function withProject(args, fn) {
+    try {
+        const resolved = resolveProjectPaths(args.projectId);
+        return await fn(resolved);
+    }
+    catch (err) {
+        // Re-throw with the error message (which now includes helpful hints)
+        throw err;
+    }
+}
+/**
+ * Wrap a tool handler that requires a project, returning ToolResult on error.
+ * Use this for top-level tool handlers.
+ */
+export async function withProjectResult(args, fn) {
+    try {
+        const resolved = resolveProjectPaths(args.projectId);
+        return await fn(resolved);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return toolError(message);
+    }
+}
+//# sourceMappingURL=project.js.map

package/dist/tools/shared/project.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.js","sourceRoot":"","sources":["../../../src/tools/shared/project.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,4BAA4B;AAC5B,+EAA+E;AAC/E,yDAAyD;AACzD,+EAA+E;AAE/E,OAAO,EACL,mBAAmB,GAEpB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE1C;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,IAA4B,EAC5B,EAAkD;IAElD,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,mBAAmB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACrD,OAAO,MAAM,EAAE,CAAC,QAAQ,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,qEAAqE;QACrE,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,IAA4B,EAC5B,EAA2D;IAE3D,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,mBAAmB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACrD,OAAO,MAAM,EAAE,CAAC,QAAQ,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,OAAO,SAAS,CAAC,OAAO,CAAC,CAAC;IAC5B,CAAC;AACH,CAAC"}

package/dist/tools/shared/response.d.ts

@@ -0,0 +1,15 @@
+import { ToolResult } from '../types.js';
+/**
+ * Track the last tool name for feedback prompts.
+ * Call this at the start of each tool handler.
+ */
+export declare function trackToolUse(toolName: string): void;
+/**
+ * Create a successful tool response
+ */
+export declare function toolSuccess(data: unknown): ToolResult;
+/**
+ * Create an error tool response
+ */
+export declare function toolError(error: string, hint?: string): ToolResult;
+//# sourceMappingURL=response.d.ts.map

package/dist/tools/shared/response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../../../src/tools/shared/response.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAkCzC;;;GAGG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAEnD;AAMD;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,UAAU,CAcrD;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,CAelE"}

package/dist/tools/shared/response.js

@@ -0,0 +1,77 @@
+// ============================================================================
+// Response Helpers
+// ============================================================================
+// Standardized response formatting for tool handlers.
+// ============================================================================
+// ============================================================================
+// Feedback Prompt Tracking
+// ============================================================================
+let toolCallCount = 0;
+let lastFeedbackPromptTime = Date.now();
+let lastToolName = '';
+const FEEDBACK_PROMPT_INTERVAL_CALLS = 15; // Every N tool calls
+const FEEDBACK_PROMPT_INTERVAL_MS = 30 * 60 * 1000; // Or every 30 minutes
+function shouldShowFeedbackPrompt() {
+    toolCallCount++;
+    const now = Date.now();
+    const timeSinceLastPrompt = now - lastFeedbackPromptTime;
+    if (toolCallCount >= FEEDBACK_PROMPT_INTERVAL_CALLS ||
+        timeSinceLastPrompt >= FEEDBACK_PROMPT_INTERVAL_MS) {
+        toolCallCount = 0;
+        lastFeedbackPromptTime = now;
+        return true;
+    }
+    return false;
+}
+function getFeedbackPrompt() {
+    if (lastToolName) {
+        return `Was this helpful? /feedback + ${lastToolName} or /feedback - ${lastToolName}`;
+    }
+    return 'Quick feedback? /feedback + or /feedback -';
+}
+/**
+ * Track the last tool name for feedback prompts.
+ * Call this at the start of each tool handler.
+ */
+export function trackToolUse(toolName) {
+    lastToolName = toolName;
+}
+// ============================================================================
+// Response Functions
+// ============================================================================
+/**
+ * Create a successful tool response
+ */
+export function toolSuccess(data) {
+    let text = JSON.stringify(data, null, 2);
+    // Periodically append feedback prompt
+    if (shouldShowFeedbackPrompt()) {
+        text += '\n\n---\n' + getFeedbackPrompt();
+    }
+    return {
+        content: [{
+                type: 'text',
+                text,
+            }],
+    };
+}
+/**
+ * Create an error tool response
+ */
+export function toolError(error, hint) {
+    const payload = {
+        success: false,
+        error,
+    };
+    if (hint) {
+        payload.hint = hint;
+    }
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify(payload, null, 2),
+            }],
+        isError: true,
+    };
+}
+//# sourceMappingURL=response.js.map

package/dist/tools/shared/response.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.js","sourceRoot":"","sources":["../../../src/tools/shared/response.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,mBAAmB;AACnB,+EAA+E;AAC/E,sDAAsD;AACtD,+EAA+E;AAI/E,+EAA+E;AAC/E,2BAA2B;AAC3B,+EAA+E;AAE/E,IAAI,aAAa,GAAG,CAAC,CAAC;AACtB,IAAI,sBAAsB,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;AACxC,IAAI,YAAY,GAAG,EAAE,CAAC;AAEtB,MAAM,8BAA8B,GAAG,EAAE,CAAC,CAAE,qBAAqB;AACjE,MAAM,2BAA2B,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAE,sBAAsB;AAE3E,SAAS,wBAAwB;IAC/B,aAAa,EAAE,CAAC;IAChB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,MAAM,mBAAmB,GAAG,GAAG,GAAG,sBAAsB,CAAC;IAEzD,IAAI,aAAa,IAAI,8BAA8B;QAC/C,mBAAmB,IAAI,2BAA2B,EAAE,CAAC;QACvD,aAAa,GAAG,CAAC,CAAC;QAClB,sBAAsB,GAAG,GAAG,CAAC;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,iBAAiB;IACxB,IAAI,YAAY,EAAE,CAAC;QACjB,OAAO,iCAAiC,YAAY,mBAAmB,YAAY,EAAE,CAAC;IACxF,CAAC;IACD,OAAO,4CAA4C,CAAC;AACtD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,QAAgB;IAC3C,YAAY,GAAG,QAAQ,CAAC;AAC1B,CAAC;AAED,+EAA+E;AAC/E,qBAAqB;AACrB,+EAA+E;AAE/E;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,IAAa;IACvC,IAAI,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAEzC,sCAAsC;IACtC,IAAI,wBAAwB,EAAE,EAAE,CAAC;QAC/B,IAAI,IAAI,WAAW,GAAG,iBAAiB,EAAE,CAAC;IAC5C,CAAC;IAED,OAAO;QACL,OAAO,EAAE,CAAC;gBACR,IAAI,EAAE,MAAM;gBACZ,IAAI;aACL,CAAC;KACH,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,KAAa,EAAE,IAAa;IACpD,MAAM,OAAO,GAA4B;QACvC,OAAO,EAAE,KAAK;QACd,KAAK;KACN,CAAC;IACF,IAAI,IAAI,EAAE,CAAC;QACT,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IACtB,CAAC;IACD,OAAO;QACL,OAAO,EAAE,CAAC;gBACR,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;aACvC,CAAC;QACF,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC"}

package/dist/tools/shared/runTracker.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Get or create an active run for a project.
+ * Returns the run ID for use in event logging.
+ *
+ * @param projectId - The project identifier
+ * @returns The active run ID, or null if creation failed
+ */
+export declare function getOrCreateActiveRun(projectId: string): Promise<string | null>;
+/**
+ * Log a tool event to the active run for a project.
+ * Fails silently if no active run or if logging fails.
+ *
+ * @param projectId - The project identifier
+ * @param toolName - Name of the tool that was called
+ * @param result - 'success' or 'error'
+ * @param summary - Brief summary of what happened
+ */
+export declare function logToolEvent(projectId: string, toolName: string, result: 'success' | 'error', summary: string): Promise<void>;
+/** Configuration for a tracked tool */
+export interface TrackedToolConfig {
+    /** Tool name for logging */
+    toolName: string;
+    /** Function to extract projectId from args (default: args.projectId || args.project_id) */
+    getProjectId?: (args: Record<string, unknown>) => string | undefined;
+    /** Function to generate summary from result (default: JSON.stringify) */
+    getSummary?: (args: Record<string, unknown>, result: unknown) => string;
+}
+/**
+ * Wrap a tool handler to automatically log successful calls.
+ * Tracking failures are silently ignored to avoid blocking tool execution.
+ *
+ * @param handler - The original tool handler
+ * @param config - Configuration for tracking
+ * @returns Wrapped handler that logs events after successful execution
+ */
+export declare function withRunTracking<T extends Record<string, unknown>>(handler: (args: T) => Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+}>, config: TrackedToolConfig): (args: T) => Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+}>;
+/** Common summary generators for different tool types */
+export declare const summaryGenerators: {
+    /** Summary for issue creation */
+    issue: (args: Record<string, unknown>, result: unknown) => string;
+    /** Summary for epic creation */
+    epic: (args: Record<string, unknown>, result: unknown) => string;
+    /** Summary for issue closure */
+    closeIssue: (args: Record<string, unknown>, result: unknown) => string;
+    /** Summary for proposal creation */
+    proposal: (args: Record<string, unknown>, result: unknown) => string;
+    /** Summary for wish creation */
+    wish: (args: Record<string, unknown>, result: unknown) => string;
+    /** Summary for experiment scaffold */
+    scaffold: (args: Record<string, unknown>, result: unknown) => string;
+    /** Summary for learning append */
+    learning: (args: Record<string, unknown>) => string;
+    /** Summary for friction log */
+    friction: (args: Record<string, unknown>, result: unknown) => string;
+    /** Summary for ADR creation */
+    adr: (args: Record<string, unknown>, result: unknown) => string;
+    /** Summary for design decision */
+    designDecision: (args: Record<string, unknown>) => string;
+    /** Summary for lateral thinking session */
+    lateralSession: (args: Record<string, unknown>, result: unknown) => string;
+};
+/**
+ * Get the current active run for a project (if any).
+ * Useful for debugging or external inspection.
+ */
+export declare function getActiveRunId(projectId: string): string | null;
+/**
+ * Clear all active runs (useful for testing).
+ */
+export declare function clearActiveRuns(): void;
+/**
+ * Get count of active runs (useful for debugging).
+ */
+export declare function getActiveRunCount(): number;
+//# sourceMappingURL=runTracker.d.ts.map

package/dist/tools/shared/runTracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runTracker.d.ts","sourceRoot":"","sources":["../../../src/tools/shared/runTracker.ts"],"names":[],"mappings":"AAuCA;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiCpF;AAED;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAChC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,SAAS,GAAG,OAAO,EAC3B,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAwBf;AAMD,uCAAuC;AACvC,MAAM,WAAW,iBAAiB;IAChC,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,2FAA2F;IAC3F,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,GAAG,SAAS,CAAC;IACrE,yEAAyE;IACzE,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,OAAO,KAAK,MAAM,CAAC;CACzE;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/D,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC;IAAE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC,EACpG,MAAM,EAAE,iBAAiB,GACxB,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC;IAAE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC,CAiC7F;AAMD,yDAAyD;AACzD,eAAO,MAAM,iBAAiB;IAC5B,iCAAiC;kBACnB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,OAAO,KAAG,MAAM;IAK/D,gCAAgC;iBACnB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,OAAO,KAAG,MAAM;IAK9D,gCAAgC;uBACb,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,OAAO,KAAG,MAAM;IAKpE,oCAAoC;qBACnB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,OAAO,KAAG,MAAM;IAKlE,gCAAgC;iBACnB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,OAAO,KAAG,MAAM;IAK9D,sCAAsC;qBACrB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,OAAO,KAAG,MAAM;IAKlE,kCAAkC;qBACjB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,MAAM;IAIjD,+BAA+B;qBACd,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,OAAO,KAAG,MAAM;IAKlE,+BAA+B;gBACnB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,OAAO,KAAG,MAAM;IAK7D,kCAAkC;2BACX,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,MAAM;IAIvD,2CAA2C;2BACpB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,OAAO,KAAG,MAAM;CAIzE,CAAC;AAMF;;;GAGG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAY/D;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAEtC;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C"}

package/dist/tools/shared/runTracker.js

@@ -0,0 +1,225 @@
+// ============================================================================
+// Run Tracker
+// ============================================================================
+// Automatic Vector run tracking for significant tool calls.
+// Tracks tool invocations as events within agent sessions.
+// ============================================================================
+import { log } from '../../config.js';
+import { createRun, logEvent } from '../vector.js';
+// ============================================================================
+// Constants
+// ============================================================================
+/** Active run timeout in milliseconds (30 minutes) */
+const ACTIVE_RUN_TIMEOUT_MS = 30 * 60 * 1000;
+/** Default agent info for auto-tracked runs */
+const DEFAULT_AGENT = {
+    type: 'claude-code',
+    version: 'auto-tracked',
+};
+/** Map of projectId -> active run state */
+const activeRuns = new Map();
+// ============================================================================
+// Core Functions
+// ============================================================================
+/**
+ * Get or create an active run for a project.
+ * Returns the run ID for use in event logging.
+ *
+ * @param projectId - The project identifier
+ * @returns The active run ID, or null if creation failed
+ */
+export async function getOrCreateActiveRun(projectId) {
+    const now = Date.now();
+    const existing = activeRuns.get(projectId);
+    // Check if we have an active run within timeout
+    if (existing && (now - existing.timestamp) < ACTIVE_RUN_TIMEOUT_MS) {
+        // Update timestamp to extend the session
+        existing.timestamp = now;
+        return existing.runId;
+    }
+    // Create a new run
+    try {
+        const result = await createRun({
+            projectId,
+            agent: DEFAULT_AGENT,
+            raw_prompt: '[Auto-tracked session via MCP tool calls]',
+            intent: {
+                goal: 'Tool usage session tracked automatically',
+            },
+        });
+        activeRuns.set(projectId, {
+            runId: result.run_id,
+            timestamp: now,
+        });
+        log(`RunTracker: Created new run ${result.run_id} for project ${projectId}`);
+        return result.run_id;
+    }
+    catch (err) {
+        log(`RunTracker: Failed to create run for project ${projectId}: ${err}`);
+        return null;
+    }
+}
+/**
+ * Log a tool event to the active run for a project.
+ * Fails silently if no active run or if logging fails.
+ *
+ * @param projectId - The project identifier
+ * @param toolName - Name of the tool that was called
+ * @param result - 'success' or 'error'
+ * @param summary - Brief summary of what happened
+ */
+export async function logToolEvent(projectId, toolName, result, summary) {
+    try {
+        const runId = await getOrCreateActiveRun(projectId);
+        if (!runId) {
+            log(`RunTracker: No active run for project ${projectId}, skipping event`);
+            return;
+        }
+        await logEvent({
+            projectId,
+            run_id: runId,
+            type: 'command_ran',
+            payload: {
+                tool: toolName,
+                result,
+                summary,
+            },
+        });
+        log(`RunTracker: Logged ${toolName} event (${result}) to run ${runId}`);
+    }
+    catch (err) {
+        // Fail silently - don't block tool execution
+        log(`RunTracker: Failed to log event for ${toolName}: ${err}`);
+    }
+}
+/**
+ * Wrap a tool handler to automatically log successful calls.
+ * Tracking failures are silently ignored to avoid blocking tool execution.
+ *
+ * @param handler - The original tool handler
+ * @param config - Configuration for tracking
+ * @returns Wrapped handler that logs events after successful execution
+ */
+export function withRunTracking(handler, config) {
+    return async (args) => {
+        const result = await handler(args);
+        // Only track successful calls
+        if (!result.isError) {
+            const projectId = config.getProjectId
+                ? config.getProjectId(args)
+                : args.projectId || args.project_id;
+            if (projectId) {
+                // Parse the result to generate summary
+                let summary;
+                try {
+                    if (config.getSummary) {
+                        const parsedResult = JSON.parse(result.content[0]?.text || '{}');
+                        summary = config.getSummary(args, parsedResult);
+                    }
+                    else {
+                        summary = `${config.toolName} completed`;
+                    }
+                }
+                catch {
+                    summary = `${config.toolName} completed`;
+                }
+                // Fire and forget - don't await to avoid blocking
+                logToolEvent(projectId, config.toolName, 'success', summary).catch(() => {
+                    // Silently ignore tracking errors
+                });
+            }
+        }
+        return result;
+    };
+}
+// ============================================================================
+// Summary Generators
+// ============================================================================
+/** Common summary generators for different tool types */
+export const summaryGenerators = {
+    /** Summary for issue creation */
+    issue: (args, result) => {
+        const r = result;
+        return `Created issue ${r.id || ''}: ${args.title || 'untitled'}`;
+    },
+    /** Summary for epic creation */
+    epic: (args, result) => {
+        const r = result;
+        return `Created epic ${r.epic_id || ''}: ${args.title || 'untitled'}`;
+    },
+    /** Summary for issue closure */
+    closeIssue: (args, result) => {
+        const r = result;
+        return `Closed issue ${r.id || args.issue_id}: ${r.status || 'closed'}`;
+    },
+    /** Summary for proposal creation */
+    proposal: (args, result) => {
+        const r = result;
+        return `Created proposal ${r.proposal_id || ''}: ${args.title || 'untitled'}`;
+    },
+    /** Summary for wish creation */
+    wish: (args, result) => {
+        const r = result;
+        return `Added wish ${r.wish_id || ''}: ${args.capability || 'unnamed'}`;
+    },
+    /** Summary for experiment scaffold */
+    scaffold: (args, result) => {
+        const r = result;
+        return `Scaffolded experiment ${r.experiment_id || ''} from ${args.proposal_id || 'unknown'}`;
+    },
+    /** Summary for learning append */
+    learning: (args) => {
+        return `Appended learning: ${args.title || 'untitled'}`;
+    },
+    /** Summary for friction log */
+    friction: (args, result) => {
+        const r = result;
+        return `Logged friction ${r.id || ''}: ${args.context || 'unknown context'}`;
+    },
+    /** Summary for ADR creation */
+    adr: (args, result) => {
+        const r = result;
+        return `Created ADR ${r.adr_id || ''}: ${args.title || args.change || 'untitled'}`;
+    },
+    /** Summary for design decision */
+    designDecision: (args) => {
+        return `Recorded design decision (${args.area || 'general'}): ${args.summary || 'untitled'}`;
+    },
+    /** Summary for lateral thinking session */
+    lateralSession: (args, result) => {
+        const r = result;
+        return `Lateral session ${r.session_id || args.session_id || ''}: ${r.problem || args.problem || 'session action'}`;
+    },
+};
+// ============================================================================
+// Utility Functions
+// ============================================================================
+/**
+ * Get the current active run for a project (if any).
+ * Useful for debugging or external inspection.
+ */
+export function getActiveRunId(projectId) {
+    const state = activeRuns.get(projectId);
+    if (!state)
+        return null;
+    const now = Date.now();
+    if ((now - state.timestamp) >= ACTIVE_RUN_TIMEOUT_MS) {
+        // Run has expired
+        activeRuns.delete(projectId);
+        return null;
+    }
+    return state.runId;
+}
+/**
+ * Clear all active runs (useful for testing).
+ */
+export function clearActiveRuns() {
+    activeRuns.clear();
+}
+/**
+ * Get count of active runs (useful for debugging).
+ */
+export function getActiveRunCount() {
+    return activeRuns.size;
+}
+//# sourceMappingURL=runTracker.js.map

package/dist/tools/shared/runTracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runTracker.js","sourceRoot":"","sources":["../../../src/tools/shared/runTracker.ts"],"names":[],"mappings":"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"}

package/dist/tools/shared/validation.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Validate that required fields are present in args.
+ * Throws an error listing any missing fields.
+ */
+export declare function requireFields(args: any, ...fields: string[]): void;
+/**
+ * Validate that a field matches one of the allowed values.
+ */
+export declare function requireOneOf<T>(value: T, fieldName: string, allowed: T[]): void;
+//# sourceMappingURL=validation.d.ts.map

package/dist/tools/shared/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/tools/shared/validation.ts"],"names":[],"mappings":"AAMA;;;GAGG;AACH,wBAAgB,aAAa,CAE3B,IAAI,EAAE,GAAG,EACT,GAAG,MAAM,EAAE,MAAM,EAAE,GAClB,IAAI,CAKN;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,KAAK,EAAE,CAAC,EACR,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,CAAC,EAAE,GACX,IAAI,CAIN"}

package/dist/tools/shared/validation.js

@@ -0,0 +1,26 @@
+// ============================================================================
+// Validation Helpers
+// ============================================================================
+// Common validation utilities for tool handlers.
+// ============================================================================
+/**
+ * Validate that required fields are present in args.
+ * Throws an error listing any missing fields.
+ */
+export function requireFields(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+args, ...fields) {
+    const missing = fields.filter(f => args[f] === undefined || args[f] === null);
+    if (missing.length > 0) {
+        throw new Error(`Missing required field${missing.length > 1 ? 's' : ''}: ${missing.join(', ')}`);
+    }
+}
+/**
+ * Validate that a field matches one of the allowed values.
+ */
+export function requireOneOf(value, fieldName, allowed) {
+    if (!allowed.includes(value)) {
+        throw new Error(`Invalid ${fieldName}: "${value}". Must be one of: ${allowed.join(', ')}`);
+    }
+}
+//# sourceMappingURL=validation.js.map

package/dist/tools/shared/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../../src/tools/shared/validation.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,qBAAqB;AACrB,+EAA+E;AAC/E,iDAAiD;AACjD,+EAA+E;AAE/E;;;GAGG;AACH,MAAM,UAAU,aAAa;AAC3B,8DAA8D;AAC9D,IAAS,EACT,GAAG,MAAgB;IAEnB,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,SAAS,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;IAC9E,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,yBAAyB,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACnG,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAC1B,KAAQ,EACR,SAAiB,EACjB,OAAY;IAEZ,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,WAAW,SAAS,MAAM,KAAK,sBAAsB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC7F,CAAC;AACH,CAAC"}

package/dist/tools/studio/cloud-spine.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Studio Cloud Spine Tools
+ *
+ * Supabase-backed tools for Decibel Studio cloud sync.
+ * Integrates with senken.pro Supabase for:
+ *   - Project management
+ *   - Artifact sync
+ *   - Event streaming
+ *   - Device registration
+ *
+ * EPIC-0002: Cloud Spine (Supabase Backend)
+ */
+import { ToolSpec } from '../types.js';
+export declare const studioListProjectsTool: ToolSpec;
+export declare const studioCreateProjectTool: ToolSpec;
+export declare const studioReadProjectTool: ToolSpec;
+export declare const studioListArtifactsTool: ToolSpec;
+export declare const studioCreateArtifactTool: ToolSpec;
+export declare const studioUpdateArtifactTool: ToolSpec;
+export declare const studioSyncEventsTool: ToolSpec;
+export declare const studioRegisterDeviceTool: ToolSpec;
+export declare const studioHeartbeatTool: ToolSpec;
+export declare const studioListJobsTool: ToolSpec;
+export declare const studioClaimJobTool: ToolSpec;
+export declare const studioUpdateJobTool: ToolSpec;
+export declare const studioCloudSpineTools: ToolSpec[];
+//# sourceMappingURL=cloud-spine.d.ts.map

package/dist/tools/studio/cloud-spine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-spine.d.ts","sourceRoot":"","sources":["../../../src/tools/studio/cloud-spine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAkBvC,eAAO,MAAM,sBAAsB,EAAE,QA4DpC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,QAmErC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,QA8CnC,CAAC;AAMF,eAAO,MAAM,uBAAuB,EAAE,QAoFrC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,QA+FtC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,QA2FtC,CAAC;AAMF,eAAO,MAAM,oBAAoB,EAAE,QAoElC,CAAC;AAMF,eAAO,MAAM,wBAAwB,EAAE,QAyEtC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,QA6CjC,CAAC;AAMF,eAAO,MAAM,kBAAkB,EAAE,QAmEhC,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,QAkEhC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,QA+EjC,CAAC;AAMF,eAAO,MAAM,qBAAqB,EAAE,QAAQ,EAkB3C,CAAC"}