@oka-core/reason 0.2.15 → 0.2.17

package/dist/tools/write.d.ts

@@ -1,8 +1,9 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { OkaClient } from "../client.js";
+import { type ToolDef } from "../tool-contract.js";
+export declare function buildWriteTools(client: OkaClient): ToolDef[];
 /**
- * Register the 4 write tools on the MCP server.
- * Each tool validates input, creates a reasoning event, and fires it to the API.
+ * Register write tools on the MCP server.
  */
 export declare function registerWriteTools(server: McpServer, client: OkaClient): void;
 //# sourceMappingURL=write.d.ts.map

package/dist/tools/write.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../src/tools/write.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CAqN7E"}
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../src/tools/write.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAM9C,OAAO,EAA+B,KAAK,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAehF,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,EAAE,CA2T5D;AAID;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CAE7E"}

package/dist/tools/write.js

@@ -1,182 +1,334 @@
 import { z } from "zod";
+import { toUserMessage, toSafeTelemetryMessage } from "../errors.js";
+import { SecretDetectedError } from "../errors.js";
+import { scanForSecrets, containsSecrets } from "../secrets.js";
+import { validateInput } from "../validation.js";
+import { analytics } from "../analytics.js";
+import { buildTool, registerToolPool } from "../tool-contract.js";
+// ─── Helpers ──────────────────────────────────────────────────────────
+function assertNoSecrets(...values) {
+    for (const v of values) {
+        if (v && containsSecrets(v)) {
+            const matches = scanForSecrets(v);
+            throw new SecretDetectedError(matches[0].patternName);
+        }
+    }
+}
+// ─── Tool definitions ─────────────────────────────────────────────────
+export function buildWriteTools(client) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- variance between ToolDef<SpecificShape> and ToolDef<ZodRawShape>
+    return [
+        buildTool({
+            name: "decision",
+            description: "Record an agent decision with rationale and alternatives considered",
+            inputSchema: {
+                description: z.string().describe("What was decided"),
+                rationale: z.string().describe("Why this choice was made"),
+                alternatives_considered: z
+                    .array(z.string())
+                    .default([])
+                    .describe("Other options that were evaluated"),
+                confidence: z
+                    .number()
+                    .min(0)
+                    .max(1)
+                    .describe("Confidence in the decision (0-1)"),
+            },
+            isReadOnly: false,
+            call: async (params) => {
+                analytics.track("tool.invoked", { tool: "decision" });
+                try {
+                    validateInput(params.description, 10_000);
+                    validateInput(params.rationale, 50_000);
+                    assertNoSecrets(params.description, params.rationale);
+                    await client.ingest({ event_type: "decision", payload: params });
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Decision recorded: ${params.description} (confidence: ${params.confidence})`,
+                            },
+                        ],
+                    };
+                }
+                catch (error) {
+                    analytics.track("tool.error", {
+                        tool: "decision",
+                        error: toSafeTelemetryMessage(error),
+                    });
+                    return {
+                        content: [{ type: "text", text: toUserMessage(error) }],
+                        isError: true,
+                    };
+                }
+            },
+        }),
+        buildTool({
+            name: "explore",
+            description: "Record an area the agent explored and what was found",
+            inputSchema: {
+                area: z.string().describe("The area or module explored"),
+                findings: z.string().describe("What was discovered"),
+                relevance_score: z
+                    .number()
+                    .min(0)
+                    .max(1)
+                    .describe("How relevant to the current task (0-1)"),
+            },
+            isReadOnly: false,
+            call: async (params) => {
+                analytics.track("tool.invoked", { tool: "explore" });
+                try {
+                    validateInput(params.area, 1_000);
+                    validateInput(params.findings, 50_000);
+                    assertNoSecrets(params.area, params.findings);
+                    await client.ingest({ event_type: "exploration", payload: params });
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Exploration recorded: ${params.area} (relevance: ${params.relevance_score})`,
+                            },
+                        ],
+                    };
+                }
+                catch (error) {
+                    analytics.track("tool.error", {
+                        tool: "explore",
+                        error: toSafeTelemetryMessage(error),
+                    });
+                    return {
+                        content: [{ type: "text", text: toUserMessage(error) }],
+                        isError: true,
+                    };
+                }
+            },
+        }),
+        buildTool({
+            name: "deviation",
+            description: "Record when the agent deviated from the original plan",
+            inputSchema: {
+                planned_action: z.string().describe("What was originally planned"),
+                actual_action: z.string().describe("What was actually done"),
+                reason: z.string().describe("Why the deviation occurred"),
+            },
+            isReadOnly: false,
+            call: async (params) => {
+                analytics.track("tool.invoked", { tool: "deviation" });
+                try {
+                    validateInput(params.planned_action, 10_000);
+                    validateInput(params.actual_action, 10_000);
+                    validateInput(params.reason, 50_000);
+                    assertNoSecrets(params.planned_action, params.actual_action, params.reason);
+                    await client.ingest({ event_type: "deviation", payload: params });
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Deviation recorded: planned "${params.planned_action}" → actual "${params.actual_action}"`,
+                            },
+                        ],
+                    };
+                }
+                catch (error) {
+                    analytics.track("tool.error", {
+                        tool: "deviation",
+                        error: toSafeTelemetryMessage(error),
+                    });
+                    return {
+                        content: [{ type: "text", text: toUserMessage(error) }],
+                        isError: true,
+                    };
+                }
+            },
+        }),
+        buildTool({
+            name: "done",
+            description: "Record task completion with outcome and quality signals. " +
+                "If you used Oka learnings during the task, include their IDs in used_learning_ids.",
+            inputSchema: {
+                task_id: z.string().describe("Identifier for the completed task"),
+                outcome: z
+                    .enum(["success", "partial", "failed"])
+                    .describe("Task outcome"),
+                artifacts: z
+                    .array(z.string())
+                    .default([])
+                    .describe("Files or PRs produced"),
+                quality_signals: z
+                    .record(z.string(), z.number())
+                    .default({})
+                    .describe("Quality metrics (e.g., test_coverage: 0.92)"),
+                used_learning_ids: z
+                    .array(z.string())
+                    .optional()
+                    .describe("IDs of Oka learnings used during the task"),
+            },
+            isReadOnly: false,
+            call: async (params) => {
+                analytics.track("tool.invoked", { tool: "done" });
+                try {
+                    validateInput(params.task_id, 1_000);
+                    const { used_learning_ids, ...completionPayload } = params;
+                    await client.ingest({
+                        event_type: "completion",
+                        payload: completionPayload,
+                    });
+                    if (used_learning_ids?.length) {
+                        client.reportUsedLearnings(used_learning_ids);
+                    }
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Completion recorded: ${params.task_id} → ${params.outcome}`,
+                            },
+                        ],
+                    };
+                }
+                catch (error) {
+                    analytics.track("tool.error", {
+                        tool: "done",
+                        error: toSafeTelemetryMessage(error),
+                    });
+                    return {
+                        content: [{ type: "text", text: toUserMessage(error) }],
+                        isError: true,
+                    };
+                }
+            },
+        }),
+        buildTool({
+            name: "observe",
+            description: "Record a general observation that doesn't fit decision/explore/deviation/done. " +
+                "Use this for architectural insights, code quality notes, dependency observations, " +
+                "performance findings, or any other knowledge worth preserving.",
+            inputSchema: {
+                category: z
+                    .enum([
+                    "architecture",
+                    "bug_pattern",
+                    "convention",
+                    "performance",
+                    "security",
+                    "workflow",
+                    "dependency",
+                    "code_quality",
+                    "other",
+                ])
+                    .describe("Category of the observation"),
+                summary: z.string().describe("Brief summary of the observation"),
+                details: z.string().optional().describe("Detailed description"),
+                confidence: z
+                    .number()
+                    .min(0)
+                    .max(1)
+                    .default(0.7)
+                    .describe("Confidence in this observation (0-1)"),
+                file_patterns: z
+                    .array(z.string())
+                    .default([])
+                    .describe("Related file patterns (e.g., 'src/auth/**')"),
+                tags: z
+                    .array(z.string())
+                    .default([])
+                    .describe("Tags for categorization"),
+            },
+            isReadOnly: false,
+            call: async (params) => {
+                analytics.track("tool.invoked", { tool: "observe" });
+                try {
+                    validateInput(params.summary, 10_000);
+                    if (params.details)
+                        validateInput(params.details, 50_000);
+                    assertNoSecrets(params.summary, params.details);
+                    await client.ingest({
+                        event_type: "exploration",
+                        payload: {
+                            area: params.category,
+                            findings: params.summary,
+                            details: params.details,
+                            relevance_score: params.confidence,
+                            observation_category: params.category,
+                            file_patterns: params.file_patterns,
+                            tags: params.tags,
+                        },
+                    });
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Observation recorded: [${params.category}] ${params.summary}`,
+                            },
+                        ],
+                    };
+                }
+                catch (error) {
+                    analytics.track("tool.error", {
+                        tool: "observe",
+                        error: toSafeTelemetryMessage(error),
+                    });
+                    return {
+                        content: [{ type: "text", text: toUserMessage(error) }],
+                        isError: true,
+                    };
+                }
+            },
+        }),
+        buildTool({
+            name: "feedback",
+            description: "Report whether a learning from Oka was useful or not. " +
+                "Improves future search quality. Call after using context or semantic_search.",
+            inputSchema: {
+                learning_id: z.string().describe("Learning ID from search results"),
+                useful: z.boolean().describe("Was this learning useful?"),
+                query_feedback_id: z
+                    .string()
+                    .optional()
+                    .describe("The ref ID from the search that returned this learning"),
+                reason: z
+                    .enum(["helpful", "outdated", "wrong", "irrelevant"])
+                    .optional()
+                    .describe("Why the learning was or wasn't useful"),
+            },
+            isReadOnly: false,
+            call: async (params) => {
+                analytics.track("tool.invoked", { tool: "feedback" });
+                try {
+                    validateInput(params.learning_id, 200);
+                    await client.submitFeedback({
+                        learning_id: params.learning_id,
+                        useful: params.useful,
+                        query_feedback_id: params.query_feedback_id,
+                        reason: params.reason,
+                    });
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Feedback recorded: ${params.learning_id.slice(0, 8)} → ${params.useful ? "useful" : "not useful"}`,
+                            },
+                        ],
+                    };
+                }
+                catch (error) {
+                    analytics.track("tool.error", {
+                        tool: "feedback",
+                        error: toSafeTelemetryMessage(error),
+                    });
+                    return {
+                        content: [{ type: "text", text: toUserMessage(error) }],
+                        isError: true,
+                    };
+                }
+            },
+        }),
+    ];
+}
+// ─── Registration ─────────────────────────────────────────────────────
 /**
- * Register the 4 write tools on the MCP server.
- * Each tool validates input, creates a reasoning event, and fires it to the API.
+ * Register write tools on the MCP server.
  */
 export function registerWriteTools(server, client) {
-    server.tool("decision", "Record an agent decision with rationale and alternatives considered", {
-        description: z.string().describe("What was decided"),
-        rationale: z.string().describe("Why this choice was made"),
-        alternatives_considered: z
-            .array(z.string())
-            .default([])
-            .describe("Other options that were evaluated"),
-        confidence: z
-            .number()
-            .min(0)
-            .max(1)
-            .describe("Confidence in the decision (0-1)"),
-    }, async (params) => {
-        await client.ingest({ event_type: "decision", payload: params });
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `Decision recorded: ${params.description} (confidence: ${params.confidence})`,
-                },
-            ],
-        };
-    });
-    server.tool("explore", "Record an area the agent explored and what was found", {
-        area: z.string().describe("The area or module explored"),
-        findings: z.string().describe("What was discovered"),
-        relevance_score: z
-            .number()
-            .min(0)
-            .max(1)
-            .describe("How relevant to the current task (0-1)"),
-    }, async (params) => {
-        await client.ingest({ event_type: "exploration", payload: params });
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `Exploration recorded: ${params.area} (relevance: ${params.relevance_score})`,
-                },
-            ],
-        };
-    });
-    server.tool("deviation", "Record when the agent deviated from the original plan", {
-        planned_action: z.string().describe("What was originally planned"),
-        actual_action: z.string().describe("What was actually done"),
-        reason: z.string().describe("Why the deviation occurred"),
-    }, async (params) => {
-        await client.ingest({ event_type: "deviation", payload: params });
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `Deviation recorded: planned "${params.planned_action}" → actual "${params.actual_action}"`,
-                },
-            ],
-        };
-    });
-    server.tool("done", "Record task completion with outcome and quality signals. " +
-        "If you used Oka learnings during the task, include their IDs in used_learning_ids.", {
-        task_id: z.string().describe("Identifier for the completed task"),
-        outcome: z
-            .enum(["success", "partial", "failed"])
-            .describe("Task outcome"),
-        artifacts: z
-            .array(z.string())
-            .default([])
-            .describe("Files or PRs produced"),
-        quality_signals: z
-            .record(z.string(), z.number())
-            .default({})
-            .describe("Quality metrics (e.g., test_coverage: 0.92)"),
-        used_learning_ids: z
-            .array(z.string())
-            .optional()
-            .describe("IDs of Oka learnings used during the task"),
-    }, async (params) => {
-        const { used_learning_ids, ...completionPayload } = params;
-        await client.ingest({
-            event_type: "completion",
-            payload: completionPayload,
-        });
-        // Report implicit feedback for LTR training
-        if (used_learning_ids?.length) {
-            client.reportUsedLearnings(used_learning_ids);
-        }
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `Completion recorded: ${params.task_id} → ${params.outcome}`,
-                },
-            ],
-        };
-    });
-    // ─── observe (general-purpose) ─────────────────────────────────
-    server.tool("observe", "Record a general observation that doesn't fit decision/explore/deviation/done. " +
-        "Use this for architectural insights, code quality notes, dependency observations, " +
-        "performance findings, or any other knowledge worth preserving.", {
-        category: z
-            .enum([
-            "architecture",
-            "bug_pattern",
-            "convention",
-            "performance",
-            "security",
-            "workflow",
-            "dependency",
-            "code_quality",
-            "other",
-        ])
-            .describe("Category of the observation"),
-        summary: z.string().describe("Brief summary of the observation"),
-        details: z.string().optional().describe("Detailed description"),
-        confidence: z
-            .number()
-            .min(0)
-            .max(1)
-            .default(0.7)
-            .describe("Confidence in this observation (0-1)"),
-        file_patterns: z
-            .array(z.string())
-            .default([])
-            .describe("Related file patterns (e.g., 'src/auth/**')"),
-        tags: z.array(z.string()).default([]).describe("Tags for categorization"),
-    }, async (params) => {
-        await client.ingest({
-            event_type: "exploration",
-            payload: {
-                area: params.category,
-                findings: params.summary,
-                details: params.details,
-                relevance_score: params.confidence,
-                observation_category: params.category,
-                file_patterns: params.file_patterns,
-                tags: params.tags,
-            },
-        });
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `Observation recorded: [${params.category}] ${params.summary}`,
-                },
-            ],
-        };
-    });
-    // ─── feedback (LTR training signal) ──────────────────────────────
-    server.tool("feedback", "Report whether a learning from Oka was useful or not. " +
-        "Improves future search quality. Call after using context or semantic_search.", {
-        learning_id: z.string().describe("Learning ID from search results"),
-        useful: z.boolean().describe("Was this learning useful?"),
-        query_feedback_id: z
-            .string()
-            .optional()
-            .describe("The ref ID from the search that returned this learning"),
-        reason: z
-            .enum(["helpful", "outdated", "wrong", "irrelevant"])
-            .optional()
-            .describe("Why the learning was or wasn't useful"),
-    }, async (params) => {
-        await client.submitFeedback({
-            learning_id: params.learning_id,
-            useful: params.useful,
-            query_feedback_id: params.query_feedback_id,
-            reason: params.reason,
-        });
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `Feedback recorded: ${params.learning_id.slice(0, 8)} → ${params.useful ? "useful" : "not useful"}`,
-                },
-            ],
-        };
-    });
+    registerToolPool(buildWriteTools(client), server);
 }

package/dist/uuid.d.ts

@@ -0,0 +1,20 @@
+/**
+ * UUID validation and labeled ID generation — zero external dependencies.
+ *
+ * Inspired by Claude Code's `src/utils/uuid.ts`.
+ */
+/**
+ * Validate that a value is a well-formed UUID string.
+ * Returns the string if valid, null otherwise.
+ */
+export declare function validateUuid(maybeUuid: unknown): string | null;
+/**
+ * Generate a random hex ID with an optional label prefix.
+ *
+ * Format: `{label-}{16 hex chars}` or just `{16 hex chars}`.
+ *
+ * @example createId()          // "a3f2c1b4d5e6f7a8"
+ * @example createId("agent")   // "agent-a3f2c1b4d5e6f7a8"
+ */
+export declare function createId(label?: string): string;
+//# sourceMappingURL=uuid.d.ts.map

package/dist/uuid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid.d.ts","sourceRoot":"","sources":["../src/uuid.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH;;;GAGG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAG9D;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAG/C"}

package/dist/uuid.js

@@ -0,0 +1,28 @@
+/**
+ * UUID validation and labeled ID generation — zero external dependencies.
+ *
+ * Inspired by Claude Code's `src/utils/uuid.ts`.
+ */
+import { randomBytes } from "crypto";
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Validate that a value is a well-formed UUID string.
+ * Returns the string if valid, null otherwise.
+ */
+export function validateUuid(maybeUuid) {
+    if (typeof maybeUuid !== "string")
+        return null;
+    return UUID_REGEX.test(maybeUuid) ? maybeUuid : null;
+}
+/**
+ * Generate a random hex ID with an optional label prefix.
+ *
+ * Format: `{label-}{16 hex chars}` or just `{16 hex chars}`.
+ *
+ * @example createId()          // "a3f2c1b4d5e6f7a8"
+ * @example createId("agent")   // "agent-a3f2c1b4d5e6f7a8"
+ */
+export function createId(label) {
+    const suffix = randomBytes(8).toString("hex");
+    return label ? `${label}-${suffix}` : suffix;
+}

package/dist/validation.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Input validation and path security — pure domain layer.
+ *
+ * ZERO external dependencies. Inspired by Claude Code's hardened
+ * validation patterns for MCP tool inputs.
+ *
+ * @module validation
+ */
+/**
+ * Validate and sanitize a free-text input string.
+ *
+ * Rejects null bytes, control characters (except \t, \n, \r),
+ * and inputs exceeding `maxLength`. Returns the trimmed string.
+ *
+ * @param input - Raw input string
+ * @param maxLength - Maximum allowed length (after trim)
+ * @returns Trimmed, validated input
+ * @throws {ValidationError} On invalid input
+ */
+export declare function validateInput(input: string, maxLength: number): string;
+/**
+ * Validate a file path against security constraints and allowed prefixes.
+ *
+ * Checks for:
+ * - Null bytes
+ * - URL-encoded traversal sequences (`%2e%2e`, `%2f`, `%5c`)
+ * - NFKC normalization attacks (path changes after normalization)
+ * - `..` path components (directory traversal)
+ * - Prefix boundary enforcement (`/allowed` must not match `/allowed-evil`)
+ *
+ * @param path - The file path to validate
+ * @param allowedPrefixes - Array of allowed path prefixes
+ * @returns The validated, normalized path
+ * @throws {PathSecurityError} On any security violation
+ */
+export declare function validatePath(path: string, allowedPrefixes: string[]): string;
+/**
+ * Check whether a path refers to a blocked device or virtual filesystem.
+ *
+ * Blocks `/dev/*`, `/proc/self/fd/*`, `/sys/*` and specific device nodes.
+ *
+ * @param path - The path to check
+ * @returns `true` if the path is a blocked device path
+ */
+export declare function isBlockedDevicePath(path: string): boolean;
+/**
+ * Check whether a filename (or path) refers to a sensitive/dangerous file.
+ *
+ * Detects config files (`.gitconfig`, `.bashrc`, `.env`), credential files
+ * (`credentials.json`, SSH keys), and sensitive directories (`.ssh/`, `.aws/`).
+ *
+ * @param filename - Filename or path to check (basename is extracted)
+ * @returns `true` if the file is considered dangerous
+ */
+export declare function isDangerousFile(filename: string): boolean;
+/**
+ * Validate that a file size is within acceptable bounds.
+ *
+ * @param bytes - Actual size in bytes
+ * @param maxBytes - Maximum allowed size in bytes
+ * @throws {ContentTooLargeError} If size exceeds the limit
+ */
+export declare function validateFileSize(bytes: number, maxBytes: number): void;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAiFH;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CA4BtE;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,GAAG,MAAM,CAmD5E;AAID;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAYzD;AAID;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAwBzD;AAID;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAUtE"}