@oka-core/reason 0.2.15 → 0.2.16

package/dist/cron.js

@@ -0,0 +1,215 @@
+/**
+ * Minimal 5-field cron expression parser and next-run calculator.
+ *
+ * Field syntax: wildcard (*), step ( * /N), range (N-M), range-step (N-M/S),
+ * list (N,M,...), plain value (N). Sunday alias: 7 → 0.
+ *
+ * All times are local timezone. DST-safe: spring-forward gaps are skipped,
+ * fall-back duplicates fire once (vixie-cron semantics).
+ */
+const FIELD_RANGES = [
+    { min: 0, max: 59 }, // minute
+    { min: 0, max: 23 }, // hour
+    { min: 1, max: 31 }, // dayOfMonth
+    { min: 1, max: 12 }, // month
+    { min: 0, max: 6 }, // dayOfWeek (0=Sunday; 7 accepted as alias)
+];
+function expandField(field, range) {
+    const { min, max } = range;
+    const out = new Set();
+    for (const part of field.split(",")) {
+        // wildcard or */N
+        const stepMatch = part.match(/^\*(?:\/(\d+))?$/);
+        if (stepMatch) {
+            const step = stepMatch[1] ? parseInt(stepMatch[1], 10) : 1;
+            if (step < 1)
+                return null;
+            for (let i = min; i <= max; i += step)
+                out.add(i);
+            continue;
+        }
+        // N-M or N-M/S
+        const rangeMatch = part.match(/^(\d+)-(\d+)(?:\/(\d+))?$/);
+        if (rangeMatch) {
+            const lo = parseInt(rangeMatch[1], 10);
+            const hi = parseInt(rangeMatch[2], 10);
+            const step = rangeMatch[3] ? parseInt(rangeMatch[3], 10) : 1;
+            const isDow = min === 0 && max === 6;
+            const effMax = isDow ? 7 : max;
+            if (lo > hi || step < 1 || lo < min || hi > effMax)
+                return null;
+            for (let i = lo; i <= hi; i += step) {
+                out.add(isDow && i === 7 ? 0 : i);
+            }
+            continue;
+        }
+        // plain N
+        const singleMatch = part.match(/^\d+$/);
+        if (singleMatch) {
+            let n = parseInt(part, 10);
+            if (min === 0 && max === 6 && n === 7)
+                n = 0;
+            if (n < min || n > max)
+                return null;
+            out.add(n);
+            continue;
+        }
+        return null;
+    }
+    if (out.size === 0)
+        return null;
+    return Array.from(out).sort((a, b) => a - b);
+}
+/**
+ * Parse a 5-field cron expression into expanded number arrays.
+ * Returns null if invalid or unsupported syntax.
+ */
+export function parseCronExpression(expr) {
+    const parts = expr.trim().split(/\s+/);
+    if (parts.length !== 5)
+        return null;
+    const expanded = [];
+    for (let i = 0; i < 5; i++) {
+        const result = expandField(parts[i], FIELD_RANGES[i]);
+        if (!result)
+            return null;
+        expanded.push(result);
+    }
+    return {
+        minute: expanded[0],
+        hour: expanded[1],
+        dayOfMonth: expanded[2],
+        month: expanded[3],
+        dayOfWeek: expanded[4],
+    };
+}
+/**
+ * Compute the next Date strictly after `from` that matches the cron fields.
+ * Uses local timezone. Walks forward minute-by-minute, bounded at 366 days.
+ *
+ * Standard cron: when both dayOfMonth and dayOfWeek are constrained
+ * (neither is the full range), a date matches if EITHER matches.
+ */
+export function computeNextCronRun(fields, from) {
+    const minuteSet = new Set(fields.minute);
+    const hourSet = new Set(fields.hour);
+    const domSet = new Set(fields.dayOfMonth);
+    const monthSet = new Set(fields.month);
+    const dowSet = new Set(fields.dayOfWeek);
+    const domWild = fields.dayOfMonth.length === 31;
+    const dowWild = fields.dayOfWeek.length === 7;
+    // Round up to the next whole minute (strictly after `from`)
+    const t = new Date(from.getTime());
+    t.setSeconds(0, 0);
+    t.setMinutes(t.getMinutes() + 1);
+    const maxIter = 366 * 24 * 60;
+    for (let i = 0; i < maxIter; i++) {
+        const month = t.getMonth() + 1;
+        if (!monthSet.has(month)) {
+            t.setMonth(t.getMonth() + 1, 1);
+            t.setHours(0, 0, 0, 0);
+            continue;
+        }
+        const dom = t.getDate();
+        const dow = t.getDay();
+        const dayMatches = domWild && dowWild
+            ? true
+            : domWild
+                ? dowSet.has(dow)
+                : dowWild
+                    ? domSet.has(dom)
+                    : domSet.has(dom) || dowSet.has(dow);
+        if (!dayMatches) {
+            t.setDate(t.getDate() + 1);
+            t.setHours(0, 0, 0, 0);
+            continue;
+        }
+        if (!hourSet.has(t.getHours())) {
+            t.setHours(t.getHours() + 1, 0, 0, 0);
+            continue;
+        }
+        if (!minuteSet.has(t.getMinutes())) {
+            t.setMinutes(t.getMinutes() + 1);
+            continue;
+        }
+        return t;
+    }
+    return null;
+}
+// --- cronToHuman ---
+const DAY_NAMES = [
+    "Sunday",
+    "Monday",
+    "Tuesday",
+    "Wednesday",
+    "Thursday",
+    "Friday",
+    "Saturday",
+];
+function formatLocalTime(minute, hour) {
+    const d = new Date(2000, 0, 1, hour, minute);
+    return d.toLocaleTimeString("en-US", { hour: "numeric", minute: "2-digit" });
+}
+/**
+ * Convert a cron expression to a human-readable description.
+ * Covers common patterns; falls through to the raw string for complex ones.
+ */
+export function cronToHuman(cron) {
+    const parts = cron.trim().split(/\s+/);
+    if (parts.length !== 5)
+        return cron;
+    const [minute, hour, dayOfMonth, month, dayOfWeek] = parts;
+    // Every N minutes: */N * * * *
+    const everyMinMatch = minute.match(/^\*\/(\d+)$/);
+    if (everyMinMatch &&
+        hour === "*" &&
+        dayOfMonth === "*" &&
+        month === "*" &&
+        dayOfWeek === "*") {
+        const n = parseInt(everyMinMatch[1], 10);
+        return n === 1 ? "Every minute" : `Every ${n} minutes`;
+    }
+    // Every hour: N * * * *
+    if (minute.match(/^\d+$/) &&
+        hour === "*" &&
+        dayOfMonth === "*" &&
+        month === "*" &&
+        dayOfWeek === "*") {
+        const m = parseInt(minute, 10);
+        if (m === 0)
+            return "Every hour";
+        return `Every hour at :${m.toString().padStart(2, "0")}`;
+    }
+    // Every N hours: M */N * * *
+    const everyHourMatch = hour.match(/^\*\/(\d+)$/);
+    if (minute.match(/^\d+$/) &&
+        everyHourMatch &&
+        dayOfMonth === "*" &&
+        month === "*" &&
+        dayOfWeek === "*") {
+        const n = parseInt(everyHourMatch[1], 10);
+        const m = parseInt(minute, 10);
+        const suffix = m === 0 ? "" : ` at :${m.toString().padStart(2, "0")}`;
+        return n === 1 ? `Every hour${suffix}` : `Every ${n} hours${suffix}`;
+    }
+    if (!minute.match(/^\d+$/) || !hour.match(/^\d+$/))
+        return cron;
+    const m = parseInt(minute, 10);
+    const h = parseInt(hour, 10);
+    // Daily: M H * * *
+    if (dayOfMonth === "*" && month === "*" && dayOfWeek === "*") {
+        return `Every day at ${formatLocalTime(m, h)}`;
+    }
+    // Specific day of week: M H * * D
+    if (dayOfMonth === "*" && month === "*" && dayOfWeek.match(/^\d$/)) {
+        const dayIndex = parseInt(dayOfWeek, 10) % 7;
+        const dayName = DAY_NAMES[dayIndex];
+        if (dayName)
+            return `Every ${dayName} at ${formatLocalTime(m, h)}`;
+    }
+    // Weekdays: M H * * 1-5
+    if (dayOfMonth === "*" && month === "*" && dayOfWeek === "1-5") {
+        return `Weekdays at ${formatLocalTime(m, h)}`;
+    }
+    return cron;
+}

package/dist/env.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Environment variable utilities — zero external dependencies.
+ *
+ * Provides consistent truthy/falsy parsing for env vars and a KEY=VALUE
+ * argument parser. Handles the three-state problem (true/false/undefined).
+ *
+ * Inspired by Claude Code's `src/utils/envUtils.ts` (generic parts only).
+ */
+/**
+ * Check if an environment variable is truthy.
+ * Recognizes: "1", "true", "yes", "on" (case-insensitive).
+ * Returns `false` for undefined/empty.
+ */
+export declare function isEnvTruthy(val: string | boolean | undefined): boolean;
+/**
+ * Check if an environment variable is explicitly set to a falsy value.
+ * Recognizes: "0", "false", "no", "off" (case-insensitive).
+ * Returns `false` for undefined (distinguishes "not set" from "set to false").
+ */
+export declare function isEnvDefinedFalsy(val: string | boolean | undefined): boolean;
+/**
+ * Parse an array of `KEY=VALUE` strings into a record.
+ * Ignores entries without `=`.
+ */
+export declare function parseEnvVars(rawArgs: string[] | undefined): Record<string, string>;
+//# sourceMappingURL=env.d.ts.map

package/dist/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,CAItE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,CAI5E;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EAAE,GAAG,SAAS,GAC5B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUxB"}

package/dist/env.js

@@ -0,0 +1,50 @@
+/**
+ * Environment variable utilities — zero external dependencies.
+ *
+ * Provides consistent truthy/falsy parsing for env vars and a KEY=VALUE
+ * argument parser. Handles the three-state problem (true/false/undefined).
+ *
+ * Inspired by Claude Code's `src/utils/envUtils.ts` (generic parts only).
+ */
+const TRUTHY = new Set(["1", "true", "yes", "on"]);
+const FALSY = new Set(["0", "false", "no", "off"]);
+/**
+ * Check if an environment variable is truthy.
+ * Recognizes: "1", "true", "yes", "on" (case-insensitive).
+ * Returns `false` for undefined/empty.
+ */
+export function isEnvTruthy(val) {
+    if (typeof val === "boolean")
+        return val;
+    if (!val)
+        return false;
+    return TRUTHY.has(val.toLowerCase());
+}
+/**
+ * Check if an environment variable is explicitly set to a falsy value.
+ * Recognizes: "0", "false", "no", "off" (case-insensitive).
+ * Returns `false` for undefined (distinguishes "not set" from "set to false").
+ */
+export function isEnvDefinedFalsy(val) {
+    if (typeof val === "boolean")
+        return !val;
+    if (!val)
+        return false;
+    return FALSY.has(val.toLowerCase());
+}
+/**
+ * Parse an array of `KEY=VALUE` strings into a record.
+ * Ignores entries without `=`.
+ */
+export function parseEnvVars(rawArgs) {
+    if (!rawArgs)
+        return {};
+    const result = {};
+    for (const arg of rawArgs) {
+        const idx = arg.indexOf("=");
+        if (idx > 0) {
+            result[arg.slice(0, idx)] = arg.slice(idx + 1);
+        }
+    }
+    return result;
+}

package/dist/errors.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Typed error hierarchy for the Oka Reason platform.
+ *
+ * Zero external dependencies — pure domain layer.
+ * (Imports only from sibling domain modules.)
+ *
+ * Inspired by Claude Code's error taxonomy:
+ * - Every error has a machine-readable `code` and human-readable `message`
+ * - `telemetryMessage` is PII-safe (never includes tokens, paths, user IDs)
+ * - `isRetryable` flag drives retry logic in the client
+ * - `category` enables grouping in dashboards
+ */
+export type ErrorCategory = "authentication" | "authorization" | "validation" | "network" | "security" | "resource" | "internal";
+export declare class OkaError extends Error {
+    /** Machine-readable error code (e.g., "NETWORK_ERROR", "PATH_TRAVERSAL"). */
+    readonly code: string;
+    /** Grouping category for dashboards. */
+    readonly category: ErrorCategory;
+    /** PII-safe message suitable for telemetry — never includes tokens, paths, or user IDs. */
+    readonly telemetryMessage: string;
+    /** Whether this error is transient and the operation can be retried. */
+    readonly isRetryable: boolean;
+    constructor(message: string, opts: {
+        code: string;
+        category: ErrorCategory;
+        telemetryMessage?: string;
+        isRetryable?: boolean;
+        cause?: unknown;
+    });
+}
+export declare class AuthenticationError extends OkaError {
+    constructor(message: string, opts?: {
+        cause?: unknown;
+    });
+}
+export declare class AuthorizationError extends OkaError {
+    constructor(message: string, opts?: {
+        cause?: unknown;
+    });
+}
+export declare class ValidationError extends OkaError {
+    constructor(message: string, opts?: {
+        cause?: unknown;
+    });
+}
+export declare class PathSecurityError extends OkaError {
+    constructor(message: string, opts?: {
+        cause?: unknown;
+    });
+}
+export declare class ContentTooLargeError extends OkaError {
+    readonly sizeBytes: number;
+    readonly maxBytes: number;
+    constructor(sizeBytes: number, maxBytes: number, opts?: {
+        cause?: unknown;
+    });
+}
+export declare class SecretDetectedError extends OkaError {
+    readonly patternName: string;
+    constructor(patternName: string, opts?: {
+        cause?: unknown;
+    });
+}
+export declare class NetworkError extends OkaError {
+    readonly statusCode?: number;
+    constructor(message: string, opts?: {
+        statusCode?: number;
+        isRetryable?: boolean;
+        cause?: unknown;
+    });
+}
+export declare class AbortError extends OkaError {
+    constructor(message?: string, opts?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Check if an error is any kind of abort (our AbortError, DOMException, SDK abort).
+ * Mirrors CC's isAbortError() pattern.
+ */
+export declare function isAbortError(err: unknown): boolean;
+/** Check if an error is retryable (transient network/capacity issue). */
+export declare function isRetryableError(err: unknown): boolean;
+/**
+ * Extract a PII-safe message for telemetry from any error.
+ * Never includes tokens, file paths, user IDs, or stack traces.
+ */
+export declare function toSafeTelemetryMessage(err: unknown): string;
+/**
+ * Normalize any thrown value into an Error instance.
+ * Mirrors CC's toError() utility.
+ */
+export declare function toError(err: unknown): Error;
+/**
+ * Extract a user-facing error message suitable for MCP tool responses.
+ * More informative than telemetry messages but still avoids raw stack traces.
+ */
+export declare function toUserMessage(err: unknown): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,MAAM,MAAM,aAAa,GACrB,gBAAgB,GAChB,eAAe,GACf,YAAY,GACZ,SAAS,GACT,UAAU,GACV,UAAU,GACV,UAAU,CAAC;AAIf,qBAAa,QAAS,SAAQ,KAAK;IACjC,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wCAAwC;IACxC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,2FAA2F;IAC3F,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,wEAAwE;IACxE,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;gBAG5B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,aAAa,CAAC;QACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;CASJ;AAID,qBAAa,mBAAoB,SAAQ,QAAQ;gBACnC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAUxD;AAED,qBAAa,kBAAmB,SAAQ,QAAQ;gBAClC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAUxD;AAID,qBAAa,eAAgB,SAAQ,QAAQ;gBAC/B,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAUxD;AAED,qBAAa,iBAAkB,SAAQ,QAAQ;gBACjC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAUxD;AAED,qBAAa,oBAAqB,SAAQ,QAAQ;IAChD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAe5E;AAID,qBAAa,mBAAoB,SAAQ,QAAQ;IAC/C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBAEjB,WAAW,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAW5D;AAID,qBAAa,YAAa,SAAQ,QAAQ;IACxC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;gBAG3B,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAgBzE;AAID,qBAAa,UAAW,SAAQ,QAAQ;gBAC1B,OAAO,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAUzD;AAID;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAIlD;AAED,yEAAyE;AACzE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAKtD;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAS3D;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,KAAK,CAI3C;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAclD"}

package/dist/errors.js

@@ -0,0 +1,214 @@
+/**
+ * Typed error hierarchy for the Oka Reason platform.
+ *
+ * Zero external dependencies — pure domain layer.
+ * (Imports only from sibling domain modules.)
+ *
+ * Inspired by Claude Code's error taxonomy:
+ * - Every error has a machine-readable `code` and human-readable `message`
+ * - `telemetryMessage` is PII-safe (never includes tokens, paths, user IDs)
+ * - `isRetryable` flag drives retry logic in the client
+ * - `category` enables grouping in dashboards
+ */
+import { humanReadableSize } from "./format.js";
+// ─── Base Error ──────────────────────────────────────────────────────
+export class OkaError extends Error {
+    /** Machine-readable error code (e.g., "NETWORK_ERROR", "PATH_TRAVERSAL"). */
+    code;
+    /** Grouping category for dashboards. */
+    category;
+    /** PII-safe message suitable for telemetry — never includes tokens, paths, or user IDs. */
+    telemetryMessage;
+    /** Whether this error is transient and the operation can be retried. */
+    isRetryable;
+    constructor(message, opts) {
+        super(message, { cause: opts.cause });
+        this.name = "OkaError";
+        this.code = opts.code;
+        this.category = opts.category;
+        this.telemetryMessage = opts.telemetryMessage ?? opts.code;
+        this.isRetryable = opts.isRetryable ?? false;
+    }
+}
+// ─── Authentication / Authorization ──────────────────────────────────
+export class AuthenticationError extends OkaError {
+    constructor(message, opts) {
+        super(message, {
+            code: "AUTHENTICATION_FAILED",
+            category: "authentication",
+            telemetryMessage: "authentication failed",
+            isRetryable: false,
+            cause: opts?.cause,
+        });
+        this.name = "AuthenticationError";
+    }
+}
+export class AuthorizationError extends OkaError {
+    constructor(message, opts) {
+        super(message, {
+            code: "FORBIDDEN",
+            category: "authorization",
+            telemetryMessage: "forbidden",
+            isRetryable: false,
+            cause: opts?.cause,
+        });
+        this.name = "AuthorizationError";
+    }
+}
+// ─── Validation ──────────────────────────────────────────────────────
+export class ValidationError extends OkaError {
+    constructor(message, opts) {
+        super(message, {
+            code: "VALIDATION_ERROR",
+            category: "validation",
+            telemetryMessage: "input validation failed",
+            isRetryable: false,
+            cause: opts?.cause,
+        });
+        this.name = "ValidationError";
+    }
+}
+export class PathSecurityError extends OkaError {
+    constructor(message, opts) {
+        super(message, {
+            code: "PATH_TRAVERSAL",
+            category: "security",
+            telemetryMessage: "path traversal detected",
+            isRetryable: false,
+            cause: opts?.cause,
+        });
+        this.name = "PathSecurityError";
+    }
+}
+export class ContentTooLargeError extends OkaError {
+    sizeBytes;
+    maxBytes;
+    constructor(sizeBytes, maxBytes, opts) {
+        super(`Content too large: ${humanReadableSize(sizeBytes)} (max ${humanReadableSize(maxBytes)})`, {
+            code: "CONTENT_TOO_LARGE",
+            category: "resource",
+            telemetryMessage: `content too large: ${sizeBytes}B > ${maxBytes}B`,
+            isRetryable: false,
+            cause: opts?.cause,
+        });
+        this.name = "ContentTooLargeError";
+        this.sizeBytes = sizeBytes;
+        this.maxBytes = maxBytes;
+    }
+}
+// ─── Security ────────────────────────────────────────────────────────
+export class SecretDetectedError extends OkaError {
+    patternName;
+    constructor(patternName, opts) {
+        super(`Secret detected in content: ${patternName}`, {
+            code: "SECRET_DETECTED",
+            category: "security",
+            telemetryMessage: `secret detected: ${patternName}`,
+            isRetryable: false,
+            cause: opts?.cause,
+        });
+        this.name = "SecretDetectedError";
+        this.patternName = patternName;
+    }
+}
+// ─── Network ─────────────────────────────────────────────────────────
+export class NetworkError extends OkaError {
+    statusCode;
+    constructor(message, opts) {
+        const status = opts?.statusCode;
+        // 5xx and network failures are retryable; 4xx are not
+        const retryable = opts?.isRetryable ?? (status === undefined || status >= 500);
+        super(message, {
+            code: "NETWORK_ERROR",
+            category: "network",
+            telemetryMessage: status ? `HTTP ${status}` : "network error",
+            isRetryable: retryable,
+            cause: opts?.cause,
+        });
+        this.name = "NetworkError";
+        this.statusCode = status;
+    }
+}
+// ─── Abort ───────────────────────────────────────────────────────────
+export class AbortError extends OkaError {
+    constructor(message, opts) {
+        super(message ?? "Operation aborted", {
+            code: "ABORTED",
+            category: "internal",
+            telemetryMessage: "operation aborted",
+            isRetryable: false,
+            cause: opts?.cause,
+        });
+        this.name = "AbortError";
+    }
+}
+// ─── Helpers ─────────────────────────────────────────────────────────
+/**
+ * Check if an error is any kind of abort (our AbortError, DOMException, SDK abort).
+ * Mirrors CC's isAbortError() pattern.
+ */
+export function isAbortError(err) {
+    if (err instanceof AbortError)
+        return true;
+    if (err instanceof Error && err.name === "AbortError")
+        return true;
+    return false;
+}
+/** Check if an error is retryable (transient network/capacity issue). */
+export function isRetryableError(err) {
+    if (err instanceof OkaError)
+        return err.isRetryable;
+    // Treat generic network errors as retryable
+    if (err instanceof TypeError && err.message.includes("fetch"))
+        return true;
+    return false;
+}
+/**
+ * Extract a PII-safe message for telemetry from any error.
+ * Never includes tokens, file paths, user IDs, or stack traces.
+ */
+export function toSafeTelemetryMessage(err) {
+    if (err instanceof OkaError)
+        return err.telemetryMessage;
+    if (err instanceof Error) {
+        // Strip anything that looks like a path, token, or email
+        const msg = err.message;
+        if (msg.length > 200)
+            return `${err.name}: [message too long]`;
+        return err.name;
+    }
+    return "unknown error";
+}
+/**
+ * Normalize any thrown value into an Error instance.
+ * Mirrors CC's toError() utility.
+ */
+export function toError(err) {
+    if (err instanceof Error)
+        return err;
+    if (typeof err === "string")
+        return new Error(err);
+    return new Error(String(err));
+}
+/**
+ * Extract a user-facing error message suitable for MCP tool responses.
+ * More informative than telemetry messages but still avoids raw stack traces.
+ */
+export function toUserMessage(err) {
+    if (err instanceof AuthenticationError) {
+        return "Authentication failed — run mcp__oka__login to re-authenticate.";
+    }
+    if (err instanceof NetworkError) {
+        const status = err.statusCode;
+        if (status === 429)
+            return "Rate limited — please try again shortly.";
+        if (status && status >= 500)
+            return `Server error (HTTP ${status}) — please try again.`;
+        return err.message;
+    }
+    if (err instanceof OkaError)
+        return err.message;
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}

package/dist/format.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Format utilities — human-readable sizes and durations.
+ *
+ * ZERO external dependencies — pure domain layer.
+ */
+/**
+ * Format a byte count as a human-readable string.
+ *
+ * @example humanReadableSize(1536) // "1.5 KB"
+ * @example humanReadableSize(0) // "0 B"
+ */
+export declare function humanReadableSize(bytes: number): string;
+/**
+ * Format a duration in milliseconds as a human-readable string.
+ *
+ * @example humanReadableDuration(350) // "350ms"
+ * @example humanReadableDuration(1200) // "1.2s"
+ * @example humanReadableDuration(135000) // "2m 15s"
+ */
+export declare function humanReadableDuration(ms: number): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAevD;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAcxD"}

package/dist/format.js

@@ -0,0 +1,48 @@
+/**
+ * Format utilities — human-readable sizes and durations.
+ *
+ * ZERO external dependencies — pure domain layer.
+ */
+const SIZE_UNITS = ["B", "KB", "MB", "GB", "TB"];
+/**
+ * Format a byte count as a human-readable string.
+ *
+ * @example humanReadableSize(1536) // "1.5 KB"
+ * @example humanReadableSize(0) // "0 B"
+ */
+export function humanReadableSize(bytes) {
+    if (bytes < 0)
+        return `-${humanReadableSize(-bytes)}`;
+    if (bytes === 0)
+        return "0 B";
+    let value = bytes;
+    let unitIndex = 0;
+    while (value >= 1024 && unitIndex < SIZE_UNITS.length - 1) {
+        value /= 1024;
+        unitIndex++;
+    }
+    const formatted = unitIndex === 0 ? String(value) : value.toFixed(1).replace(/\.0$/, "");
+    return `${formatted} ${SIZE_UNITS[unitIndex]}`;
+}
+/**
+ * Format a duration in milliseconds as a human-readable string.
+ *
+ * @example humanReadableDuration(350) // "350ms"
+ * @example humanReadableDuration(1200) // "1.2s"
+ * @example humanReadableDuration(135000) // "2m 15s"
+ */
+export function humanReadableDuration(ms) {
+    if (ms < 0)
+        return `-${humanReadableDuration(-ms)}`;
+    if (ms < 1000)
+        return `${Math.round(ms)}ms`;
+    const seconds = ms / 1000;
+    if (seconds < 60) {
+        return `${seconds.toFixed(1).replace(/\.0$/, "")}s`;
+    }
+    const minutes = Math.floor(seconds / 60);
+    const remainingSeconds = Math.round(seconds % 60);
+    if (remainingSeconds === 0)
+        return `${minutes}m`;
+    return `${minutes}m ${remainingSeconds}s`;
+}