@oka-core/reason 0.2.14 → 0.2.16

package/dist/subprocess-env.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Secret-aware environment scrubbing for subprocess spawning.
+ *
+ * Strips sensitive variables (API keys, cloud credentials, OIDC tokens)
+ * from child process environments to prevent exfiltration via shell
+ * expansion in CI/CD and agent contexts.
+ *
+ * Inspired by Claude Code's `src/utils/subprocessEnv.ts`.
+ */
+export type SubprocessEnvOptions = {
+    /** Environment variable that gates scrubbing. Default: OKA_SUBPROCESS_ENV_SCRUB. */
+    enableEnvVar?: string;
+    /** Additional variables to scrub beyond defaults. */
+    extraScrubList?: readonly string[];
+    /** Completely replace the default scrub list. */
+    scrubList?: readonly string[];
+};
+/**
+ * Create a scrubbed copy of `process.env` for subprocess spawning.
+ *
+ * Scrubbing is only active when the gate env var is truthy.
+ * Also scrubs `INPUT_<NAME>` variants (GitHub Actions auto-creates these).
+ */
+export declare function createSubprocessEnv(opts?: SubprocessEnvOptions): NodeJS.ProcessEnv;
+//# sourceMappingURL=subprocess-env.d.ts.map

package/dist/subprocess-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subprocess-env.d.ts","sourceRoot":"","sources":["../src/subprocess-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA+BH,MAAM,MAAM,oBAAoB,GAAG;IACjC,oFAAoF;IACpF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,iDAAiD;IACjD,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/B,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,CAAC,EAAE,oBAAoB,GAC1B,MAAM,CAAC,UAAU,CAmBnB"}

package/dist/subprocess-env.js

@@ -0,0 +1,55 @@
+/**
+ * Secret-aware environment scrubbing for subprocess spawning.
+ *
+ * Strips sensitive variables (API keys, cloud credentials, OIDC tokens)
+ * from child process environments to prevent exfiltration via shell
+ * expansion in CI/CD and agent contexts.
+ *
+ * Inspired by Claude Code's `src/utils/subprocessEnv.ts`.
+ */
+import { isEnvTruthy } from "./env.js";
+/** Default variables to scrub from subprocess environments. */
+const DEFAULT_SCRUB_LIST = [
+    // API keys
+    "ANTHROPIC_API_KEY",
+    "OPENAI_API_KEY",
+    "OPENROUTER_API_KEY",
+    // Cloud provider credentials
+    "AWS_SECRET_ACCESS_KEY",
+    "AWS_SESSION_TOKEN",
+    "GOOGLE_APPLICATION_CREDENTIALS",
+    "AZURE_CLIENT_SECRET",
+    "AZURE_CLIENT_CERTIFICATE_PATH",
+    // OTEL exporter headers (may carry Bearer tokens)
+    "OTEL_EXPORTER_OTLP_HEADERS",
+    "OTEL_EXPORTER_OTLP_LOGS_HEADERS",
+    "OTEL_EXPORTER_OTLP_METRICS_HEADERS",
+    "OTEL_EXPORTER_OTLP_TRACES_HEADERS",
+    // GitHub Actions OIDC + runtime tokens
+    "ACTIONS_ID_TOKEN_REQUEST_TOKEN",
+    "ACTIONS_ID_TOKEN_REQUEST_URL",
+    "ACTIONS_RUNTIME_TOKEN",
+    "ACTIONS_RUNTIME_URL",
+];
+/**
+ * Create a scrubbed copy of `process.env` for subprocess spawning.
+ *
+ * Scrubbing is only active when the gate env var is truthy.
+ * Also scrubs `INPUT_<NAME>` variants (GitHub Actions auto-creates these).
+ */
+export function createSubprocessEnv(opts) {
+    const gateVar = opts?.enableEnvVar ?? "OKA_SUBPROCESS_ENV_SCRUB";
+    if (!isEnvTruthy(process.env[gateVar])) {
+        return process.env;
+    }
+    const env = { ...process.env };
+    const scrubList = opts?.scrubList ?? [
+        ...DEFAULT_SCRUB_LIST,
+        ...(opts?.extraScrubList ?? []),
+    ];
+    for (const k of scrubList) {
+        delete env[k];
+        delete env[`INPUT_${k}`];
+    }
+    return env;
+}

package/dist/temp-file.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Temporary file path generation — deterministic (content-hashed) or random.
+ *
+ * Inspired by Claude Code's `src/utils/tempfile.ts`.
+ */
+/**
+ * Generate a temporary file path.
+ *
+ * @param prefix  File name prefix (default: "oka-tmp")
+ * @param extension  File extension including dot (default: ".md")
+ * @param options.contentHash  When provided, the ID is a stable SHA-256
+ *   prefix of this string. Same content → same path across processes.
+ *   Use when the path is included in API payloads (avoids cache busting).
+ */
+export declare function generateTempFilePath(prefix?: string, extension?: string, options?: {
+    contentHash?: string;
+}): string;
+//# sourceMappingURL=temp-file.d.ts.map

package/dist/temp-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"temp-file.d.ts","sourceRoot":"","sources":["../src/temp-file.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,SAAY,EAClB,SAAS,SAAQ,EACjB,OAAO,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GACjC,MAAM,CAQR"}

package/dist/temp-file.js

@@ -0,0 +1,26 @@
+/**
+ * Temporary file path generation — deterministic (content-hashed) or random.
+ *
+ * Inspired by Claude Code's `src/utils/tempfile.ts`.
+ */
+import { createHash, randomUUID } from "crypto";
+import { tmpdir } from "os";
+import { join } from "path";
+/**
+ * Generate a temporary file path.
+ *
+ * @param prefix  File name prefix (default: "oka-tmp")
+ * @param extension  File extension including dot (default: ".md")
+ * @param options.contentHash  When provided, the ID is a stable SHA-256
+ *   prefix of this string. Same content → same path across processes.
+ *   Use when the path is included in API payloads (avoids cache busting).
+ */
+export function generateTempFilePath(prefix = "oka-tmp", extension = ".md", options) {
+    const id = options?.contentHash
+        ? createHash("sha256")
+            .update(options.contentHash)
+            .digest("hex")
+            .slice(0, 16)
+        : randomUUID();
+    return join(tmpdir(), `${prefix}-${id}${extension}`);
+}

package/dist/tool-contract.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Tool contract pattern — typed, composable MCP tool definitions.
+ *
+ * ZERO external dependencies beyond Zod (already required by MCP SDK).
+ *
+ * Inspired by Claude Code's Tool<Input,Output> pattern:
+ * - Separates tool definition from MCP registration
+ * - Permission pipeline (allow/deny/ask)
+ * - Input validation lifecycle
+ * - Lazy schema construction
+ * - Concurrency and read-only markers for pool assembly
+ */
+import type { z, ZodRawShape } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export type PermissionResult = {
+    decision: "allow";
+} | {
+    decision: "deny";
+    reason: string;
+} | {
+    decision: "ask";
+    prompt: string;
+};
+/** A typed, framework-agnostic tool definition. */
+export interface ToolDef<TShape extends ZodRawShape = ZodRawShape> {
+    /** Unique tool name (used as MCP tool ID). */
+    name: string;
+    /** Human-readable description for the agent. */
+    description: string;
+    /** Zod shape for input validation. */
+    inputSchema: TShape;
+    /** Whether this tool only reads data (no side effects). */
+    isReadOnly: boolean;
+    /** Whether concurrent invocations are safe. */
+    isConcurrencySafe: boolean;
+    /** Optional permission check before execution. */
+    checkPermissions?: (input: z.objectOutputType<TShape, z.ZodTypeAny>) => PermissionResult;
+    /** The tool handler. */
+    call: (input: z.objectOutputType<TShape, z.ZodTypeAny>) => Promise<{
+        content: Array<{
+            type: "text";
+            text: string;
+        }>;
+    }>;
+}
+interface BuildToolOpts<TShape extends ZodRawShape> {
+    name: string;
+    description: string;
+    inputSchema: TShape;
+    isReadOnly?: boolean;
+    isConcurrencySafe?: boolean;
+    checkPermissions?: ToolDef<TShape>["checkPermissions"];
+    call: ToolDef<TShape>["call"];
+}
+/** Build a typed tool definition with sensible defaults. */
+export declare function buildTool<TShape extends ZodRawShape>(opts: BuildToolOpts<TShape>): ToolDef<TShape>;
+/**
+ * Defer schema construction until first access.
+ * Useful when Zod shapes depend on runtime config.
+ */
+export declare function lazySchema<TShape extends ZodRawShape>(factory: () => TShape): TShape;
+/** A named deny rule that prevents certain tools from registering. */
+export interface DenyRule {
+    /** Tool names to deny. */
+    names: string[];
+    reason: string;
+}
+/**
+ * Assemble a tool pool from definitions, applying deny rules and deduplication.
+ * Returns only tools that pass all rules.
+ */
+export declare function assembleToolPool(tools: ToolDef[], denyRules?: DenyRule[]): ToolDef[];
+/**
+ * Register a ToolDef on an MCP server instance.
+ *
+ * This is the thin adapter that bridges our typed tool definitions
+ * to the MCP SDK's `server.tool()` registration.
+ */
+export declare function wrapForMcp(tool: ToolDef, server: McpServer): void;
+/**
+ * Register all tools from a pool onto an MCP server.
+ */
+export declare function registerToolPool(tools: ToolDef[], server: McpServer): void;
+export {};
+//# sourceMappingURL=tool-contract.d.ts.map

package/dist/tool-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-contract.d.ts","sourceRoot":"","sources":["../src/tool-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AAC1C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIzE,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,GACrB;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,QAAQ,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAIxC,mDAAmD;AACnD,MAAM,WAAW,OAAO,CAAC,MAAM,SAAS,WAAW,GAAG,WAAW;IAC/D,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,UAAU,EAAE,OAAO,CAAC;IACpB,+CAA+C;IAC/C,iBAAiB,EAAE,OAAO,CAAC;IAC3B,kDAAkD;IAClD,gBAAgB,CAAC,EAAE,CACjB,KAAK,EAAE,CAAC,CAAC,gBAAgB,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC,KAC5C,gBAAgB,CAAC;IACtB,wBAAwB;IACxB,IAAI,EAAE,CACJ,KAAK,EAAE,CAAC,CAAC,gBAAgB,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC,KAC5C,OAAO,CAAC;QAAE,OAAO,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,CAAC,CAAC;CAClE;AAID,UAAU,aAAa,CAAC,MAAM,SAAS,WAAW;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,gBAAgB,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,kBAAkB,CAAC,CAAC;IACvD,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC;CAC/B;AAED,4DAA4D;AAC5D,wBAAgB,SAAS,CAAC,MAAM,SAAS,WAAW,EAClD,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,GAC1B,OAAO,CAAC,MAAM,CAAC,CAUjB;AAID;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,SAAS,WAAW,EACnD,OAAO,EAAE,MAAM,MAAM,GACpB,MAAM,CAgBR;AAID,sEAAsE;AACtE,MAAM,WAAW,QAAQ;IACvB,0BAA0B;IAC1B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,OAAO,EAAE,EAChB,SAAS,CAAC,EAAE,QAAQ,EAAE,GACrB,OAAO,EAAE,CAeX;AAID;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CAcjE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CAI1E"}

package/dist/tool-contract.js

@@ -0,0 +1,101 @@
+/**
+ * Tool contract pattern — typed, composable MCP tool definitions.
+ *
+ * ZERO external dependencies beyond Zod (already required by MCP SDK).
+ *
+ * Inspired by Claude Code's Tool<Input,Output> pattern:
+ * - Separates tool definition from MCP registration
+ * - Permission pipeline (allow/deny/ask)
+ * - Input validation lifecycle
+ * - Lazy schema construction
+ * - Concurrency and read-only markers for pool assembly
+ */
+/** Build a typed tool definition with sensible defaults. */
+export function buildTool(opts) {
+    return {
+        name: opts.name,
+        description: opts.description,
+        inputSchema: opts.inputSchema,
+        isReadOnly: opts.isReadOnly ?? false,
+        isConcurrencySafe: opts.isConcurrencySafe ?? true,
+        checkPermissions: opts.checkPermissions,
+        call: opts.call,
+    };
+}
+// ─── Lazy Schema ────────────────────────────────────────────────────
+/**
+ * Defer schema construction until first access.
+ * Useful when Zod shapes depend on runtime config.
+ */
+export function lazySchema(factory) {
+    let cached = null;
+    return new Proxy({}, {
+        get(_target, prop, receiver) {
+            if (!cached)
+                cached = factory();
+            return Reflect.get(cached, prop, receiver);
+        },
+        ownKeys() {
+            if (!cached)
+                cached = factory();
+            return Reflect.ownKeys(cached);
+        },
+        getOwnPropertyDescriptor(_target, prop) {
+            if (!cached)
+                cached = factory();
+            return Object.getOwnPropertyDescriptor(cached, prop);
+        },
+    });
+}
+/**
+ * Assemble a tool pool from definitions, applying deny rules and deduplication.
+ * Returns only tools that pass all rules.
+ */
+export function assembleToolPool(tools, denyRules) {
+    const denied = new Set();
+    for (const rule of denyRules ?? []) {
+        for (const name of rule.names)
+            denied.add(name);
+    }
+    const seen = new Set();
+    const result = [];
+    for (const tool of tools) {
+        if (denied.has(tool.name))
+            continue;
+        if (seen.has(tool.name))
+            continue;
+        seen.add(tool.name);
+        result.push(tool);
+    }
+    return result;
+}
+// ─── MCP Adapter ────────────────────────────────────────────────────
+/**
+ * Register a ToolDef on an MCP server instance.
+ *
+ * This is the thin adapter that bridges our typed tool definitions
+ * to the MCP SDK's `server.tool()` registration.
+ */
+export function wrapForMcp(tool, server) {
+    server.tool(tool.name, tool.description, tool.inputSchema, async (input) => {
+        // Permission check
+        if (tool.checkPermissions) {
+            const perm = tool.checkPermissions(input);
+            if (perm.decision === "deny") {
+                return {
+                    content: [{ type: "text", text: `Denied: ${perm.reason}` }],
+                    isError: true,
+                };
+            }
+        }
+        return tool.call(input);
+    });
+}
+/**
+ * Register all tools from a pool onto an MCP server.
+ */
+export function registerToolPool(tools, server) {
+    for (const tool of tools) {
+        wrapForMcp(tool, server);
+    }
+}

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

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/tools/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAQ9C;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CA8I5E"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/tools/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAU9C;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CA8I5E"}

package/dist/tools/auth.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
-import { deviceAuthLogin, loadStoredCredentials, resolveApiKey, resolveApiKeyWithRefresh, } from "../auth.js";
+import { McpTokenManager, deviceAuthLogin, loadStoredCredentials, resolveApiKey, } from "../auth.js";
+const tokenManager = new McpTokenManager();
 /**
  * Register auth tools on the MCP server.
  */
@@ -29,10 +30,10 @@ export function registerAuthTools(server, client) {
                 ],
             };
         }
-        // Token might be expired — try refresh before opening browser
+        // Token might be expired — try proactive refresh before opening browser
         const stored = loadStoredCredentials();
         if (stored?.refresh_token) {
-            const refreshed = await resolveApiKeyWithRefresh();
+            const refreshed = await tokenManager.getValidToken();
             if (refreshed) {
                 client.updateApiKey(refreshed);
                 return {
@@ -83,11 +84,11 @@ export function registerAuthTools(server, client) {
         }
     });
     server.tool("whoami", "Check current authentication status — whether the MCP server has valid credentials.", {}, async () => {
-        // First try sync resolution
-        let key = resolveApiKey();
-        // If no key found, try async refresh
+        // Try token manager (proactive refresh)
+        let key = await tokenManager.getValidToken();
+        // If token manager returned empty, key might still be in sync path
         if (!key) {
-            key = await resolveApiKeyWithRefresh();
+            key = resolveApiKey();
             if (key) {
                 return {
                     content: [

package/dist/tools/read.d.ts

@@ -1,17 +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 buildReadTools(client: OkaClient): ToolDef[];
 /**
  * Register read tools on the MCP server.
- *
- * Tools:
- * - context — ranked learnings for a topic (flagship query)
- * - learnings — browse institutional knowledge
- * - decisions — decision log
- * - patterns — recurring patterns
- * - suggest — evidence-ranked priorities
- * - backlog — agentic product backlog
- * - priorities — evidence-ranked priorities from approved backlog
- * - consolidate — manually trigger a consolidation run
  */
 export declare function registerReadTools(server: McpServer, client: OkaClient): void;
 //# sourceMappingURL=read.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../src/tools/read.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EACV,SAAS,EAKV,MAAM,cAAc,CAAC;AAiItB;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CAopB5E"}
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../src/tools/read.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EACV,SAAS,EAKV,MAAM,cAAc,CAAC;AAKtB,OAAO,EAA+B,KAAK,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAgIhF,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,EAAE,CAivB3D;AAID;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CAE5E"}