@aquex/cmos-mcp 1.0.0

package/dist/tools/cmos/cmos-resolve-references.d.ts

@@ -0,0 +1,145 @@
+/**
+ * cmos_resolve_references Tool
+ *
+ * MCP tool for parsing mission reference_docs and categorizing references
+ * by type (TraceLab URIs, local docs, web URLs).
+ *
+ * This tool does NOT fetch TraceLab content - it only parses and categorizes.
+ * Agents use TraceLab MCP tools directly for fetching.
+ *
+ * @module tools/cmos/cmos-resolve-references
+ */
+import { z } from 'zod';
+import type { CmosToolResult } from './types';
+/**
+ * TraceLab URI types supported.
+ */
+export declare const TRACELAB_URI_TYPES: readonly ["project", "collection", "report", "document", "chunk", "search"];
+export type TracelabUriType = (typeof TRACELAB_URI_TYPES)[number];
+/**
+ * Parsed TraceLab reference.
+ */
+export interface TracelabRef {
+    /** Original URI string */
+    uri: string;
+    /** Type of TraceLab resource */
+    type: TracelabUriType | 'unknown';
+    /** Resource ID extracted from URI */
+    resourceId: string | null;
+    /** Any additional path segments */
+    path: string | null;
+}
+/**
+ * Local document reference.
+ */
+export interface LocalDocRef {
+    /** Original reference string */
+    ref: string;
+    /** Path to the document */
+    path: string;
+}
+/**
+ * Web URL reference.
+ */
+export interface WebUrlRef {
+    /** Original URL string */
+    url: string;
+    /** URL hostname */
+    hostname: string | null;
+}
+/**
+ * Result of reference resolution.
+ */
+export interface CmosResolveReferencesResult {
+    /** Mission ID */
+    missionId: string;
+    /** TraceLab references (tracelab:// URIs) */
+    tracelabRefs: TracelabRef[];
+    /** Local document references (relative paths) */
+    localDocs: LocalDocRef[];
+    /** Web URL references (http:// or https://) */
+    webUrls: WebUrlRef[];
+    /** Total reference count */
+    totalRefs: number;
+    /** Message describing the result */
+    message: string;
+}
+/**
+ * Input parameters schema for cmos_resolve_references tool.
+ */
+export declare const cmosResolveReferencesSchema: z.ZodObject<{
+    /** Mission ID to resolve references for */
+    missionId: z.ZodString;
+    /** Optional project root */
+    projectRoot: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    missionId: string;
+    projectRoot?: string | undefined;
+}, {
+    missionId: string;
+    projectRoot?: string | undefined;
+}>;
+export type CmosResolveReferencesParams = z.infer<typeof cmosResolveReferencesSchema>;
+/**
+ * MCP Tool Definition for cmos_resolve_references.
+ */
+export declare const cmosResolveReferencesToolDefinition: {
+    readonly name: "cmos_resolve_references";
+    readonly description: "Parse mission reference_docs field and categorize references by type. Returns TraceLab URIs, local docs, and web URLs. Does NOT fetch content - use TraceLab tools for that.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly missionId: {
+                readonly type: "string";
+                readonly description: "The mission ID to resolve references for (e.g., \"s18-m01\")";
+            };
+            readonly projectRoot: {
+                readonly type: "string";
+                readonly description: "Project root directory to search for CMOS database (defaults to cwd)";
+            };
+        };
+        readonly required: readonly ["missionId"];
+        readonly additionalProperties: false;
+    };
+};
+/**
+ * Parse a TraceLab URI into its components.
+ *
+ * URI format: tracelab://<type>/<resource-id>[/<path>]
+ * Examples:
+ *   tracelab://project/abc123
+ *   tracelab://collection/abc123
+ *   tracelab://report/abc123
+ *   tracelab://document/abc123
+ *   tracelab://chunk/abc123
+ *   tracelab://search?q=query
+ */
+export declare function parseTracelabUri(uri: string): TracelabRef;
+/**
+ * Determine if a reference is a TraceLab URI.
+ */
+export declare function isTracelabUri(ref: string): boolean;
+/**
+ * Determine if a reference is a web URL.
+ */
+export declare function isWebUrl(ref: string): boolean;
+/**
+ * Parse a web URL to extract hostname.
+ */
+export declare function parseWebUrl(url: string): WebUrlRef;
+/**
+ * Parse a local document reference.
+ */
+export declare function parseLocalDoc(ref: string): LocalDocRef;
+/**
+ * Execute the cmos_resolve_references tool.
+ *
+ * @param params - Tool parameters
+ * @returns CmosToolResult with categorized references
+ */
+export declare function cmosResolveReferences(params: CmosResolveReferencesParams): Promise<CmosToolResult<CmosResolveReferencesResult>>;
+/**
+ * Format resolve references result for LLM readability.
+ */
+export declare function formatResolveReferencesForLLM(result: CmosToolResult<CmosResolveReferencesResult>): string;
+//# sourceMappingURL=cmos-resolve-references.d.ts.map

package/dist/tools/cmos/cmos-resolve-references.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cmos-resolve-references.d.ts","sourceRoot":"","sources":["../../../src/tools/cmos/cmos-resolve-references.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,cAAc,EAAW,MAAM,SAAS,CAAC;AAGvD;;GAEG;AACH,eAAO,MAAM,kBAAkB,6EAOrB,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,0BAA0B;IAC1B,GAAG,EAAE,MAAM,CAAC;IAEZ,gCAAgC;IAChC,IAAI,EAAE,eAAe,GAAG,SAAS,CAAC;IAElC,qCAAqC;IACrC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAE1B,mCAAmC;IACnC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,gCAAgC;IAChC,GAAG,EAAE,MAAM,CAAC;IAEZ,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,0BAA0B;IAC1B,GAAG,EAAE,MAAM,CAAC;IAEZ,mBAAmB;IACnB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,iBAAiB;IACjB,SAAS,EAAE,MAAM,CAAC;IAElB,6CAA6C;IAC7C,YAAY,EAAE,WAAW,EAAE,CAAC;IAE5B,iDAAiD;IACjD,SAAS,EAAE,WAAW,EAAE,CAAC;IAEzB,+CAA+C;IAC/C,OAAO,EAAE,SAAS,EAAE,CAAC;IAErB,4BAA4B;IAC5B,SAAS,EAAE,MAAM,CAAC;IAElB,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,eAAO,MAAM,2BAA2B;IACtC,2CAA2C;;IAM3C,4BAA4B;;;;;;;;EAK5B,CAAC;AAEH,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEtF;;GAEG;AACH,eAAO,MAAM,mCAAmC;;;;;;;;;;;;;;;;;;CAmBtC,CAAC;AAEX;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CA6BzD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE7C;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAalD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAKtD;AAED;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,2BAA2B,GAClC,OAAO,CAAC,cAAc,CAAC,2BAA2B,CAAC,CAAC,CAwFtD;AAED;;GAEG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,cAAc,CAAC,2BAA2B,CAAC,GAClD,MAAM,CAoDR"}

package/dist/tools/cmos/cmos-resolve-references.js

@@ -0,0 +1,273 @@
+"use strict";
+/**
+ * cmos_resolve_references Tool
+ *
+ * MCP tool for parsing mission reference_docs and categorizing references
+ * by type (TraceLab URIs, local docs, web URLs).
+ *
+ * This tool does NOT fetch TraceLab content - it only parses and categorizes.
+ * Agents use TraceLab MCP tools directly for fetching.
+ *
+ * @module tools/cmos/cmos-resolve-references
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cmosResolveReferencesToolDefinition = exports.cmosResolveReferencesSchema = exports.TRACELAB_URI_TYPES = void 0;
+exports.parseTracelabUri = parseTracelabUri;
+exports.isTracelabUri = isTracelabUri;
+exports.isWebUrl = isWebUrl;
+exports.parseWebUrl = parseWebUrl;
+exports.parseLocalDoc = parseLocalDoc;
+exports.cmosResolveReferences = cmosResolveReferences;
+exports.formatResolveReferencesForLLM = formatResolveReferencesForLLM;
+const zod_1 = require("zod");
+const client_1 = require("./client");
+const errors_1 = require("./errors");
+/**
+ * TraceLab URI types supported.
+ */
+exports.TRACELAB_URI_TYPES = [
+    'project',
+    'collection',
+    'report',
+    'document',
+    'chunk',
+    'search',
+];
+/**
+ * Input parameters schema for cmos_resolve_references tool.
+ */
+exports.cmosResolveReferencesSchema = zod_1.z.object({
+    /** Mission ID to resolve references for */
+    missionId: zod_1.z
+        .string()
+        .min(1)
+        .describe('The mission ID to resolve references for (e.g., "s18-m01")'),
+    /** Optional project root */
+    projectRoot: zod_1.z
+        .string()
+        .optional()
+        .describe('Project root directory to search for CMOS database (defaults to cwd)'),
+});
+/**
+ * MCP Tool Definition for cmos_resolve_references.
+ */
+exports.cmosResolveReferencesToolDefinition = {
+    name: 'cmos_resolve_references',
+    description: 'Parse mission reference_docs field and categorize references by type. Returns TraceLab URIs, local docs, and web URLs. Does NOT fetch content - use TraceLab tools for that.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            missionId: {
+                type: 'string',
+                description: 'The mission ID to resolve references for (e.g., "s18-m01")',
+            },
+            projectRoot: {
+                type: 'string',
+                description: 'Project root directory to search for CMOS database (defaults to cwd)',
+            },
+        },
+        required: ['missionId'],
+        additionalProperties: false,
+    },
+};
+/**
+ * Parse a TraceLab URI into its components.
+ *
+ * URI format: tracelab://<type>/<resource-id>[/<path>]
+ * Examples:
+ *   tracelab://project/abc123
+ *   tracelab://collection/abc123
+ *   tracelab://report/abc123
+ *   tracelab://document/abc123
+ *   tracelab://chunk/abc123
+ *   tracelab://search?q=query
+ */
+function parseTracelabUri(uri) {
+    const tracelabPrefix = 'tracelab://';
+    if (!uri.startsWith(tracelabPrefix)) {
+        return {
+            uri,
+            type: 'unknown',
+            resourceId: null,
+            path: null,
+        };
+    }
+    const remainder = uri.slice(tracelabPrefix.length);
+    const parts = remainder.split('/');
+    const typeStr = parts[0] || '';
+    const type = exports.TRACELAB_URI_TYPES.includes(typeStr)
+        ? typeStr
+        : 'unknown';
+    const resourceId = parts[1] || null;
+    const path = parts.length > 2 ? parts.slice(2).join('/') : null;
+    return {
+        uri,
+        type,
+        resourceId,
+        path,
+    };
+}
+/**
+ * Determine if a reference is a TraceLab URI.
+ */
+function isTracelabUri(ref) {
+    return ref.startsWith('tracelab://');
+}
+/**
+ * Determine if a reference is a web URL.
+ */
+function isWebUrl(ref) {
+    return ref.startsWith('http://') || ref.startsWith('https://');
+}
+/**
+ * Parse a web URL to extract hostname.
+ */
+function parseWebUrl(url) {
+    try {
+        const parsed = new URL(url);
+        return {
+            url,
+            hostname: parsed.hostname,
+        };
+    }
+    catch {
+        return {
+            url,
+            hostname: null,
+        };
+    }
+}
+/**
+ * Parse a local document reference.
+ */
+function parseLocalDoc(ref) {
+    return {
+        ref,
+        path: ref,
+    };
+}
+/**
+ * Execute the cmos_resolve_references tool.
+ *
+ * @param params - Tool parameters
+ * @returns CmosToolResult with categorized references
+ */
+async function cmosResolveReferences(params) {
+    const { missionId } = params;
+    if (!missionId || missionId.trim() === '') {
+        return (0, errors_1.createError)(errors_1.CmosErrors.missingParameter('missionId'));
+    }
+    return (0, client_1.withClientValidated)((client) => {
+        // Fetch the mission
+        const missionResult = client.getOne('SELECT id, reference_docs FROM missions WHERE id = ?', [missionId]);
+        if (!missionResult.success) {
+            return (0, errors_1.createError)(missionResult.error ?? { code: 'DB_QUERY_FAILED', message: 'Failed to query mission' });
+        }
+        if (!missionResult.data) {
+            return (0, errors_1.createError)(errors_1.CmosErrors.missionNotFound(missionId));
+        }
+        const mission = missionResult.data;
+        // Parse reference_docs JSON
+        let refs = [];
+        if (mission.reference_docs) {
+            try {
+                const parsed = JSON.parse(mission.reference_docs);
+                if (Array.isArray(parsed)) {
+                    refs = parsed.filter((r) => typeof r === 'string');
+                }
+            }
+            catch {
+                // Invalid JSON, treat as empty
+                refs = [];
+            }
+        }
+        // Categorize references
+        const tracelabRefs = [];
+        const localDocs = [];
+        const webUrls = [];
+        for (const ref of refs) {
+            const trimmedRef = ref.trim();
+            if (!trimmedRef)
+                continue;
+            if (isTracelabUri(trimmedRef)) {
+                tracelabRefs.push(parseTracelabUri(trimmedRef));
+            }
+            else if (isWebUrl(trimmedRef)) {
+                webUrls.push(parseWebUrl(trimmedRef));
+            }
+            else {
+                localDocs.push(parseLocalDoc(trimmedRef));
+            }
+        }
+        const totalRefs = tracelabRefs.length + localDocs.length + webUrls.length;
+        const messageParts = [];
+        if (tracelabRefs.length > 0) {
+            messageParts.push(`${tracelabRefs.length} TraceLab`);
+        }
+        if (localDocs.length > 0) {
+            messageParts.push(`${localDocs.length} local`);
+        }
+        if (webUrls.length > 0) {
+            messageParts.push(`${webUrls.length} web`);
+        }
+        const message = totalRefs === 0
+            ? `Mission '${missionId}' has no reference docs`
+            : `Mission '${missionId}' has ${totalRefs} refs: ${messageParts.join(', ')}`;
+        return (0, errors_1.createSuccess)({
+            missionId,
+            tracelabRefs,
+            localDocs,
+            webUrls,
+            totalRefs,
+            message,
+        });
+    }, { projectRoot: params.projectRoot });
+}
+/**
+ * Format resolve references result for LLM readability.
+ */
+function formatResolveReferencesForLLM(result) {
+    if (!result.success || !result.data) {
+        const error = result.error;
+        const lines = [
+            'Failed to resolve references',
+            '',
+            `Error: ${error?.message ?? 'Unknown error'}`,
+        ];
+        if (error?.suggestion) {
+            lines.push('');
+            lines.push(`Suggestion: ${error.suggestion}`);
+        }
+        return lines.join('\n');
+    }
+    const data = result.data;
+    const lines = [`**References for ${data.missionId}**`, ''];
+    if (data.totalRefs === 0) {
+        lines.push('No reference docs found.');
+        return lines.join('\n');
+    }
+    if (data.tracelabRefs.length > 0) {
+        lines.push(`**TraceLab References** (${data.tracelabRefs.length})`);
+        for (const ref of data.tracelabRefs) {
+            lines.push(`  - [${ref.type}] ${ref.uri}`);
+        }
+        lines.push('');
+    }
+    if (data.localDocs.length > 0) {
+        lines.push(`**Local Docs** (${data.localDocs.length})`);
+        for (const doc of data.localDocs) {
+            lines.push(`  - ${doc.path}`);
+        }
+        lines.push('');
+    }
+    if (data.webUrls.length > 0) {
+        lines.push(`**Web URLs** (${data.webUrls.length})`);
+        for (const url of data.webUrls) {
+            lines.push(`  - ${url.url}`);
+        }
+        lines.push('');
+    }
+    lines.push(`**Total**: ${data.totalRefs} references`);
+    return lines.join('\n');
+}
+//# sourceMappingURL=cmos-resolve-references.js.map

package/dist/tools/cmos/cmos-resolve-references.js.map

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

package/dist/tools/cmos/cmos-session-capture.d.ts

@@ -0,0 +1,228 @@
+/**
+ * cmos_session_capture Tool
+ *
+ * MCP tool for capturing insights during an active session.
+ * Supports categories: decision, learning, constraint, context, next-step.
+ *
+ * @module tools/cmos/cmos-session-capture
+ */
+import { z } from 'zod';
+import type { CmosToolResult } from './types';
+import { type SupersessionCandidate } from './supersession-detection';
+/**
+ * Valid capture categories matching the Python session_runtime.
+ */
+export declare const VALID_CAPTURE_CATEGORIES: readonly ["decision", "learning", "constraint", "context", "next-step"];
+export type CaptureCategory = (typeof VALID_CAPTURE_CATEGORIES)[number];
+/**
+ * Result of session capture operation.
+ */
+export interface CmosSessionCaptureResult {
+    /** Session ID the capture was added to */
+    sessionId: string;
+    /** Category of the capture */
+    category: CaptureCategory;
+    /** Content of the capture */
+    content: string;
+    /** When the capture was recorded */
+    timestamp: string;
+    /** Total captures in the session after this one */
+    captureCount: number;
+    /** Message describing the result */
+    message: string;
+    /** Associated mission ID (when missionId was provided) */
+    missionId?: string;
+    /** Number of decisions extracted (present for decision category captures) */
+    decisionExtractionCount?: number;
+    /** Whether the decision was already extracted (present for decision category captures) */
+    decisionAlreadyExtracted?: boolean;
+    /** Source chunk IDs for decision provenance tracking */
+    sourceChunkIds?: string[];
+    /** Evidence references stored with the decision */
+    evidenceStored?: Array<{
+        type: string;
+        id: string;
+    }>;
+    /** Whether a learning was extracted to the learnings table */
+    learningExtracted?: boolean;
+    /** Whether a constraint was extracted to the constraints table */
+    constraintExtracted?: boolean;
+    /** Supersession candidates detected for this decision */
+    supersessionCandidates?: SupersessionCandidate[];
+    /** Human-readable supersession suggestion */
+    supersessionMessage?: string;
+    /**
+     * Learning IDs whose `last_reviewed_at` was bumped because the caller
+     * passed them in `citesLearningIds[]`. Sprint 61 m01.
+     */
+    explicitlyReaffirmedLearningIds?: number[];
+    /**
+     * Learning IDs whose `last_reviewed_at` was bumped because the new capture's
+     * content overlapped them by at least IMPLICIT_REAFFIRM_KEYWORD_FLOOR keywords.
+     * Sprint 61 m01.
+     */
+    implicitlyReaffirmedLearningIds?: number[];
+    /**
+     * Learning IDs the caller passed in `citesLearningIds[]` that did not
+     * resolve to existing rows. Sprint 61 m01.
+     */
+    missingCitedLearningIds?: number[];
+}
+/**
+ * Input parameters schema for cmos_session_capture tool.
+ */
+export declare const cmosSessionCaptureSchema: z.ZodObject<{
+    /** Session ID to capture to (optional - uses active session if not provided) */
+    sessionId: z.ZodOptional<z.ZodString>;
+    /** Capture category */
+    category: z.ZodEnum<["decision", "learning", "constraint", "context", "next-step"]>;
+    /** Content to capture */
+    content: z.ZodString;
+    /** Optional context/reason for the capture */
+    context: z.ZodOptional<z.ZodString>;
+    /** Optional mission ID to associate this capture with */
+    missionId: z.ZodOptional<z.ZodString>;
+    /** Optional evidence references for decision captures */
+    evidence: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        id: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: string;
+        id: string;
+    }, {
+        type: string;
+        id: string;
+    }>, "many">>;
+    /** Optional expiry date for constraint captures (ISO 8601) */
+    expiresAt: z.ZodOptional<z.ZodString>;
+    /** Optional agent name */
+    agent: z.ZodOptional<z.ZodDefault<z.ZodString>>;
+    /**
+     * Optional explicit list of learning IDs this capture cites. When set, those
+     * learnings get their `last_reviewed_at` bumped to now — keeping still-true
+     * institutional rules out of the staleness pile (Sprint 61 m01).
+     */
+    citesLearningIds: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+    /** Optional project root */
+    projectRoot: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    category: "context" | "constraint" | "decision" | "learning" | "next-step";
+    content: string;
+    projectRoot?: string | undefined;
+    evidence?: {
+        type: string;
+        id: string;
+    }[] | undefined;
+    agent?: string | undefined;
+    missionId?: string | undefined;
+    context?: string | undefined;
+    sessionId?: string | undefined;
+    expiresAt?: string | undefined;
+    citesLearningIds?: number[] | undefined;
+}, {
+    category: "context" | "constraint" | "decision" | "learning" | "next-step";
+    content: string;
+    projectRoot?: string | undefined;
+    evidence?: {
+        type: string;
+        id: string;
+    }[] | undefined;
+    agent?: string | undefined;
+    missionId?: string | undefined;
+    context?: string | undefined;
+    sessionId?: string | undefined;
+    expiresAt?: string | undefined;
+    citesLearningIds?: number[] | undefined;
+}>;
+export type CmosSessionCaptureParams = z.infer<typeof cmosSessionCaptureSchema>;
+/**
+ * MCP Tool Definition for cmos_session_capture.
+ */
+export declare const cmosSessionCaptureToolDefinition: {
+    readonly name: "cmos_session_capture";
+    readonly description: "Capture an insight during an active session. Categories: decision (choices made), learning (what was learned), constraint (limitations discovered), context (background info), next-step (action items). Captures are aggregated into master context when the session completes.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly sessionId: {
+                readonly type: "string";
+                readonly description: "Session ID to add capture to (uses active session if not provided)";
+            };
+            readonly category: {
+                readonly type: "string";
+                readonly enum: readonly ["decision", "learning", "constraint", "context", "next-step"];
+                readonly description: "Category: decision, learning, constraint, context, or next-step";
+            };
+            readonly content: {
+                readonly type: "string";
+                readonly description: "The insight to capture (1-1000 characters)";
+                readonly minLength: 1;
+                readonly maxLength: 1000;
+            };
+            readonly context: {
+                readonly type: "string";
+                readonly description: "Optional context or reason for this capture";
+                readonly maxLength: 500;
+            };
+            readonly missionId: {
+                readonly type: "string";
+                readonly description: "Associate this capture with a specific mission (creates strategic_decisions when category=decision)";
+            };
+            readonly evidence: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly type: {
+                            readonly type: "string";
+                            readonly description: "Evidence type (e.g. \"collection\", \"document\", \"chunk\")";
+                        };
+                        readonly id: {
+                            readonly type: "string";
+                            readonly description: "Evidence identifier (e.g. TraceLab collection/document ID)";
+                        };
+                    };
+                    readonly required: readonly ["type", "id"];
+                };
+                readonly description: "Array of TraceLab evidence references [{type, id}] to link with a decision capture";
+            };
+            readonly expiresAt: {
+                readonly type: "string";
+                readonly description: "Optional expiry date for constraint captures (ISO 8601, e.g. \"2026-03-20T00:00:00Z\")";
+            };
+            readonly agent: {
+                readonly type: "string";
+                readonly description: "Agent making the capture (default: \"assistant\")";
+            };
+            readonly citesLearningIds: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                };
+                readonly description: "Learning IDs this capture cites. Bumps last_reviewed_at on each — applies to category=decision|learning.";
+            };
+            readonly projectRoot: {
+                readonly type: "string";
+                readonly description: "Project root directory to search for CMOS database (defaults to cwd)";
+            };
+        };
+        readonly required: readonly ["category", "content"];
+        readonly additionalProperties: false;
+    };
+};
+/**
+ * Execute the cmos_session_capture tool.
+ *
+ * Adds a capture to an active session. If sessionId is not provided,
+ * uses the currently active session.
+ *
+ * @param params - Tool parameters
+ * @returns CmosToolResult with capture info or actionable error
+ */
+export declare function cmosSessionCapture(params: CmosSessionCaptureParams): Promise<CmosToolResult<CmosSessionCaptureResult>>;
+/**
+ * Format session capture result for LLM readability.
+ */
+export declare function formatSessionCaptureForLLM(result: CmosToolResult<CmosSessionCaptureResult>): string;
+//# sourceMappingURL=cmos-session-capture.d.ts.map

package/dist/tools/cmos/cmos-session-capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cmos-session-capture.d.ts","sourceRoot":"","sources":["../../../src/tools/cmos/cmos-session-capture.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,cAAc,EAAW,MAAM,SAAS,CAAC;AAUvD,OAAO,EAAgC,KAAK,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAGpG;;GAEG;AACH,eAAO,MAAM,wBAAwB,yEAM3B,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAExE;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAElB,8BAA8B;IAC9B,QAAQ,EAAE,eAAe,CAAC;IAE1B,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAEhB,oCAAoC;IACpC,SAAS,EAAE,MAAM,CAAC;IAElB,mDAAmD;IACnD,YAAY,EAAE,MAAM,CAAC;IAErB,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAEhB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,6EAA6E;IAC7E,uBAAuB,CAAC,EAAE,MAAM,CAAC;IAEjC,0FAA0F;IAC1F,wBAAwB,CAAC,EAAE,OAAO,CAAC;IAEnC,wDAAwD;IACxD,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAE1B,mDAAmD;IACnD,cAAc,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAErD,8DAA8D;IAC9D,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAE5B,kEAAkE;IAClE,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAE9B,yDAAyD;IACzD,sBAAsB,CAAC,EAAE,qBAAqB,EAAE,CAAC;IAEjD,6CAA6C;IAC7C,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAE7B;;;OAGG;IACH,+BAA+B,CAAC,EAAE,MAAM,EAAE,CAAC;IAE3C;;;;OAIG;IACH,+BAA+B,CAAC,EAAE,MAAM,EAAE,CAAC;IAE3C;;;OAGG;IACH,uBAAuB,CAAC,EAAE,MAAM,EAAE,CAAC;CACpC;AAED;;GAEG;AACH,eAAO,MAAM,wBAAwB;IACnC,gFAAgF;;IAMhF,uBAAuB;;IAKvB,yBAAyB;;IAGzB,8CAA8C;;IAG9C,yDAAyD;;IAQzD,yDAAyD;;;;;;;;;;;IAczD,8DAA8D;;IAQ9D,0BAA0B;;IAO1B;;;;OAIG;;IAQH,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAK5B,CAAC;AAEH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEhF;;GAEG;AACH,eAAO,MAAM,gCAAgC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0EnC,CAAC;AAEX;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,wBAAwB,GAC/B,OAAO,CAAC,cAAc,CAAC,wBAAwB,CAAC,CAAC,CAkYnD;AA6CD;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,cAAc,CAAC,wBAAwB,CAAC,GAC/C,MAAM,CAiER"}