narai-primitives 2.0.0-rc.1

package/dist/toolkit/hardship/curate.js

@@ -0,0 +1,113 @@
+/**
+ * Normalize a free-form context string so minor differences (whitespace,
+ * timestamps, UUIDs) collapse into the same cluster.
+ */
+export function normalizeContext(raw) {
+    return raw
+        .toLowerCase()
+        .replace(/\s+/g, " ")
+        .replace(/\d{4}-\d{2}-\d{2}t[\d:.z+-]*/g, "<ts>")
+        .replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/g, "<uuid>")
+        .replace(/\b\d{6,}\b/g, "<num>")
+        .trim();
+}
+function clusterKey(entry) {
+    return [
+        entry.connector,
+        entry.action,
+        entry.kind,
+        entry.scope ?? "",
+        normalizeContext(entry.context),
+    ].join("\0");
+}
+function addUnique(list, item, cap) {
+    if (list.length >= cap)
+        return;
+    if (!list.includes(item))
+        list.push(item);
+}
+/**
+ * Cluster a flat list of entries. Stable output: clusters are sorted by
+ * count descending, then by last_ts descending.
+ */
+export function clusterHardships(entries) {
+    const byKey = new Map();
+    for (const e of entries) {
+        const key = clusterKey(e);
+        let cluster = byKey.get(key);
+        if (cluster === undefined) {
+            cluster = {
+                signature: key,
+                connector: e.connector,
+                action: e.action,
+                kind: e.kind,
+                scope: e.scope ?? null,
+                count: 0,
+                first_ts: e.ts,
+                last_ts: e.ts,
+                sample_contexts: [],
+                sample_resolutions: [],
+                sessions: [],
+            };
+            byKey.set(key, cluster);
+        }
+        cluster.count += 1;
+        if (e.ts < cluster.first_ts)
+            cluster.first_ts = e.ts;
+        if (e.ts > cluster.last_ts)
+            cluster.last_ts = e.ts;
+        addUnique(cluster.sample_contexts, e.context, 5);
+        if (e.resolution !== undefined && e.resolution.length > 0) {
+            addUnique(cluster.sample_resolutions, e.resolution, 5);
+        }
+        if (e.session_id !== undefined)
+            addUnique(cluster.sessions, e.session_id, 10);
+    }
+    return Array.from(byKey.values()).sort((a, b) => b.count - a.count || (b.last_ts < a.last_ts ? 1 : -1));
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Curation marker — stored as MD frontmatter on `hardships.md`.
+// ───────────────────────────────────────────────────────────────────────────
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/;
+export function readCurationMarker(md) {
+    const match = FRONTMATTER_RE.exec(md);
+    if (!match)
+        return { last_curated_ts: null, last_curated_count: 0 };
+    const body = match[1];
+    const lines = body.split("\n");
+    let ts = null;
+    let count = 0;
+    for (const line of lines) {
+        const [k, ...rest] = line.split(":");
+        if (!k)
+            continue;
+        const value = rest.join(":").trim();
+        if (k.trim() === "last_curated_ts") {
+            ts = value || null;
+        }
+        else if (k.trim() === "last_curated_count") {
+            const parsed = Number(value);
+            if (Number.isFinite(parsed))
+                count = parsed;
+        }
+    }
+    return { last_curated_ts: ts, last_curated_count: count };
+}
+export function writeCurationMarker(md, marker) {
+    const frontmatter = [
+        "---",
+        `last_curated_ts: ${marker.last_curated_ts ?? ""}`,
+        `last_curated_count: ${marker.last_curated_count}`,
+        "---",
+        "",
+    ].join("\n");
+    const stripped = md.replace(FRONTMATTER_RE, "");
+    return frontmatter + stripped;
+}
+/** Filter entries newer than the last-curated timestamp. */
+export function entriesSinceLastCuration(entries, marker) {
+    if (marker.last_curated_ts === null)
+        return [...entries];
+    return entries.filter((e) => e.ts > marker.last_curated_ts);
+}
+//# sourceMappingURL=curate.js.map

package/dist/toolkit/hardship/curate.js.map

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

package/dist/toolkit/hardship/patterns.d.ts

@@ -0,0 +1,32 @@
+export interface PatternMatcher {
+    context_regex?: string;
+}
+export interface Pattern {
+    pattern_id: string;
+    status: "active" | "draft";
+    confidence: number;
+    kind: string;
+    actions?: string[];
+    matcher: PatternMatcher;
+    advice: string;
+}
+export interface PatternsFile {
+    version: number;
+    last_updated?: string;
+    patterns: Pattern[];
+}
+export interface HardshipFacts {
+    kind: string;
+    action: string;
+    context: string;
+}
+export interface MatchedPattern {
+    pattern_id: string;
+    advice: string;
+    confidence: number;
+}
+export declare function loadPatterns(filePath: string): PatternsFile;
+export declare function matchPattern(patterns: readonly Pattern[], facts: HardshipFacts): MatchedPattern | null;
+/** Test helper — clear the mtime cache. */
+export declare function _resetPatternCache(): void;
+//# sourceMappingURL=patterns.d.ts.map

package/dist/toolkit/hardship/patterns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patterns.d.ts","sourceRoot":"","sources":["../../../src/toolkit/hardship/patterns.ts"],"names":[],"mappings":"AAeA,MAAM,WAAW,cAAc;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,OAAO;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,QAAQ,GAAG,OAAO,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,EAAE,cAAc,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAyBD,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,CAoC3D;AAED,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,SAAS,OAAO,EAAE,EAC5B,KAAK,EAAE,aAAa,GACnB,cAAc,GAAG,IAAI,CAqBvB;AAED,2CAA2C;AAC3C,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}

package/dist/toolkit/hardship/patterns.js

@@ -0,0 +1,98 @@
+/**
+ * patterns.ts — load patterns.yaml, match hardship facts, produce hints.
+ *
+ * Hot-path: called on every non-success envelope. Cached with mtime
+ * invalidation so a freshly-curated patterns.yaml is picked up without
+ * restart (within the same process).
+ */
+import * as fs from "node:fs";
+import { createRequire } from "node:module";
+// js-yaml is a direct toolkit dependency (see package.json). Use createRequire
+// for sync loading from an ESM module; dynamic import() would force the hot
+// path to be async.
+const requireSync = createRequire(import.meta.url);
+const cache = new Map();
+const EMPTY = { version: 1, patterns: [] };
+function isPattern(obj) {
+    if (!obj || typeof obj !== "object")
+        return false;
+    const p = obj;
+    return (typeof p["pattern_id"] === "string" &&
+        (p["status"] === "active" || p["status"] === "draft") &&
+        typeof p["confidence"] === "number" &&
+        typeof p["kind"] === "string" &&
+        typeof p["advice"] === "string" &&
+        typeof p["matcher"] === "object" &&
+        p["matcher"] !== null);
+}
+export function loadPatterns(filePath) {
+    let stat;
+    try {
+        stat = fs.statSync(filePath);
+    }
+    catch {
+        return EMPTY;
+    }
+    const cached = cache.get(filePath);
+    if (cached && cached.mtimeMs === stat.mtimeMs)
+        return cached.file;
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, "utf-8");
+    }
+    catch {
+        return EMPTY;
+    }
+    const yaml = requireSync("js-yaml");
+    let parsed;
+    try {
+        parsed = yaml.load(raw);
+    }
+    catch {
+        return EMPTY;
+    }
+    if (!parsed || typeof parsed !== "object")
+        return EMPTY;
+    const p = parsed;
+    const rawPatterns = Array.isArray(p["patterns"]) ? p["patterns"] : [];
+    const file = {
+        version: typeof p["version"] === "number" ? p["version"] : 1,
+        ...(typeof p["last_updated"] === "string"
+            ? { last_updated: p["last_updated"] }
+            : {}),
+        patterns: rawPatterns.filter(isPattern),
+    };
+    cache.set(filePath, { mtimeMs: stat.mtimeMs, file });
+    return file;
+}
+export function matchPattern(patterns, facts) {
+    for (const p of patterns) {
+        if (p.status !== "active")
+            continue;
+        if (p.kind !== facts.kind)
+            continue;
+        if (p.actions && p.actions.length > 0 && !p.actions.includes(facts.action)) {
+            continue;
+        }
+        if (p.matcher.context_regex) {
+            try {
+                if (!new RegExp(p.matcher.context_regex).test(facts.context))
+                    continue;
+            }
+            catch {
+                continue; // malformed regex — skip pattern
+            }
+        }
+        return {
+            pattern_id: p.pattern_id,
+            advice: p.advice,
+            confidence: p.confidence,
+        };
+    }
+    return null;
+}
+/** Test helper — clear the mtime cache. */
+export function _resetPatternCache() {
+    cache.clear();
+}
+//# sourceMappingURL=patterns.js.map

package/dist/toolkit/hardship/patterns.js.map

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

package/dist/toolkit/hardship/preamble.d.ts

@@ -0,0 +1,13 @@
+export interface RenderSkillPreambleOptions {
+    connector: string;
+    scope?: string | null;
+    cwd?: string;
+    home?: string;
+}
+/**
+ * Walk all 4 tiers and collect every active pattern. Dedupe by pattern_id
+ * preferring the most-specific tier's version. Return a markdown block
+ * or "" if there are no active patterns.
+ */
+export declare function renderSkillPreamble(opts: RenderSkillPreambleOptions): string;
+//# sourceMappingURL=preamble.d.ts.map

package/dist/toolkit/hardship/preamble.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preamble.d.ts","sourceRoot":"","sources":["../../../src/toolkit/hardship/preamble.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,0BAA0B;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,0BAA0B,GAC/B,MAAM,CA+BR"}

package/dist/toolkit/hardship/preamble.js

@@ -0,0 +1,47 @@
+/**
+ * preamble.ts — render the session-start "Known gotchas" markdown block
+ * for a connector. Called from each connector's SKILL.md plugin loader.
+ */
+import * as path from "node:path";
+import { resolveTierPaths } from "./scope.js";
+import { loadPatterns } from "./patterns.js";
+/**
+ * Walk all 4 tiers and collect every active pattern. Dedupe by pattern_id
+ * preferring the most-specific tier's version. Return a markdown block
+ * or "" if there are no active patterns.
+ */
+export function renderSkillPreamble(opts) {
+    const scope = opts.scope ?? null;
+    const tiers = resolveTierPaths({
+        connector: opts.connector,
+        scope,
+        cwd: opts.cwd ?? process.cwd(),
+        home: opts.home ?? process.env["HOME"] ?? "/",
+    });
+    const seen = new Map();
+    for (const t of tiers) {
+        const file = loadPatterns(path.join(t.dir, "patterns.yaml"));
+        for (const p of file.patterns) {
+            if (p.status !== "active")
+                continue;
+            if (!seen.has(p.pattern_id)) {
+                seen.set(p.pattern_id, p);
+            }
+        }
+    }
+    if (seen.size === 0)
+        return "";
+    const bullets = [];
+    for (const p of seen.values()) {
+        const firstLine = p.advice.split("\n")[0]?.trim() ?? "";
+        bullets.push(`- **${p.pattern_id}**: ${firstLine}`);
+    }
+    return [
+        `## Known gotchas (auto — ${opts.connector})`,
+        ...bullets,
+        "",
+        `_Auto-injected from curated hardships. Run \`/curate\` to refresh._`,
+        "",
+    ].join("\n");
+}
+//# sourceMappingURL=preamble.js.map

package/dist/toolkit/hardship/preamble.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preamble.js","sourceRoot":"","sources":["../../../src/toolkit/hardship/preamble.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAgB,MAAM,eAAe,CAAC;AAS3D;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAAgC;IAEhC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC;IACjC,MAAM,KAAK,GAAG,gBAAgB,CAAC;QAC7B,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,KAAK;QACL,GAAG,EAAE,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE;QAC9B,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,GAAG;KAC9C,CAAC,CAAC;IACH,MAAM,IAAI,GAAG,IAAI,GAAG,EAAmB,CAAC;IACxC,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC,CAAC;QAC7D,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC9B,IAAI,CAAC,CAAC,MAAM,KAAK,QAAQ;gBAAE,SAAS;YACpC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,EAAE,CAAC;gBAC5B,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;YAC5B,CAAC;QACH,CAAC;IACH,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAC/B,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;QAC9B,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;QACxD,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,UAAU,OAAO,SAAS,EAAE,CAAC,CAAC;IACtD,CAAC;IACD,OAAO;QACL,4BAA4B,IAAI,CAAC,SAAS,GAAG;QAC7C,GAAG,OAAO;QACV,EAAE;QACF,qEAAqE;QACrE,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/dist/toolkit/hardship/read.d.ts

@@ -0,0 +1,34 @@
+import type { HardshipEntry } from "./record.js";
+import { type TierName } from "./scope.js";
+import { type HardshipFacts, type MatchedPattern } from "./patterns.js";
+export interface ReadOptions {
+    cwd?: string;
+    home?: string;
+    /** Tenant scope; null (default) walks only the global tiers. */
+    scope?: string | null;
+}
+/**
+ * Load the curated MD for a connector across all tiers. Each tier's file,
+ * if present, is concatenated in tier order (most specific first) separated
+ * by a visible divider. Returns `""` when no tier has content.
+ */
+export declare function readCuratedHardships(connector: string, opts?: ReadOptions): string;
+/** Load raw JSONL entries, newest-first, across all tiers combined. */
+export declare function readRawHardships(connector: string, opts?: ReadOptions): HardshipEntry[];
+/** Count JSONL entries for a connector across all tiers. Used by the reminder. */
+export declare function countRawHardships(connector: string, opts?: ReadOptions): number;
+export interface ReadFirstMatchingPatternOptions {
+    connector: string;
+    scope: string | null;
+    cwd?: string;
+    home?: string;
+    facts: HardshipFacts;
+}
+export interface TierMatch {
+    tier: TierName;
+    match: MatchedPattern;
+    /** "tenant" if the tier included a tenant hash, "global" otherwise. */
+    scopeLevel: "tenant" | "global";
+}
+export declare function readFirstMatchingPattern(opts: ReadFirstMatchingPatternOptions): TierMatch | null;
+//# sourceMappingURL=read.d.ts.map

package/dist/toolkit/hardship/read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../../src/toolkit/hardship/read.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAoB,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,cAAc,EACpB,MAAM,eAAe,CAAC;AAEvB,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AA8BD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE,WAAgB,GACrB,MAAM,CAWR;AAED,uEAAuE;AACvE,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE,WAAgB,GACrB,aAAa,EAAE,CAqBjB;AAcD,kFAAkF;AAClF,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE,WAAgB,GACrB,MAAM,CAER;AAED,MAAM,WAAW,+BAA+B;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,aAAa,CAAC;CACtB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,cAAc,CAAC;IACtB,uEAAuE;IACvE,UAAU,EAAE,QAAQ,GAAG,QAAQ,CAAC;CACjC;AAED,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,+BAA+B,GACpC,SAAS,GAAG,IAAI,CAelB"}

package/dist/toolkit/hardship/read.js

@@ -0,0 +1,116 @@
+/**
+ * Reader for hardship artifacts. 4-tier walk (project-tenant → project-global
+ * → user-tenant → user-global); non-existent tier files are skipped.
+ *
+ *   project-tenant: <cwd>/.claude/connectors/<name>/tenants/<hash>/{hardships.jsonl,hardships.md}
+ *   project-global: <cwd>/.claude/connectors/<name>/global/{hardships.jsonl,hardships.md}
+ *   user-tenant:    <home>/.claude/connectors/<name>/tenants/<hash>/{hardships.jsonl,hardships.md}
+ *   user-global:    <home>/.claude/connectors/<name>/global/{hardships.jsonl,hardships.md}
+ *
+ * When `scope` is null, only the two `-global` tiers are walked.
+ *
+ * MD is merged: each tier's file is concatenated in tier order with a
+ * divider; empty / missing tiers are skipped. Agents reading the MD see
+ * most-specific guidance first. Sections with identical headings are NOT
+ * auto-merged — that is the curation step's job.
+ *
+ * JSONL is concatenated across all tiers, then sorted newest-first by `ts`.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { resolveTierPaths } from "./scope.js";
+import { loadPatterns, matchPattern, } from "./patterns.js";
+/** Return candidate file paths across all tiers (existence not checked). */
+function hardshipPaths(connector, opts, filename) {
+    const tiers = resolveTierPaths({
+        connector,
+        scope: opts.scope ?? null,
+        cwd: opts.cwd ?? process.cwd(),
+        home: opts.home ?? process.env["HOME"] ?? "/",
+    });
+    return tiers.map((t) => ({ tier: t.name, path: path.join(t.dir, filename) }));
+}
+function tryReadFile(filePath) {
+    try {
+        return fs.readFileSync(filePath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Load the curated MD for a connector across all tiers. Each tier's file,
+ * if present, is concatenated in tier order (most specific first) separated
+ * by a visible divider. Returns `""` when no tier has content.
+ */
+export function readCuratedHardships(connector, opts = {}) {
+    const files = hardshipPaths(connector, opts, "hardships.md");
+    const parts = [];
+    for (const f of files) {
+        const raw = tryReadFile(f.path);
+        if (raw === null)
+            continue;
+        const trimmed = raw.trim();
+        if (trimmed.length === 0)
+            continue;
+        parts.push(`<!-- layer: ${f.tier} (${f.path}) -->\n${trimmed}`);
+    }
+    return parts.join("\n\n---\n\n");
+}
+/** Load raw JSONL entries, newest-first, across all tiers combined. */
+export function readRawHardships(connector, opts = {}) {
+    const files = hardshipPaths(connector, opts, "hardships.jsonl");
+    const entries = [];
+    for (const f of files) {
+        const raw = tryReadFile(f.path);
+        if (raw === null)
+            continue;
+        for (const line of raw.split("\n")) {
+            const trimmed = line.trim();
+            if (trimmed.length === 0)
+                continue;
+            try {
+                const parsed = JSON.parse(trimmed);
+                if (isHardshipEntry(parsed)) {
+                    entries.push(parsed);
+                }
+            }
+            catch {
+                // Skip malformed lines silently.
+            }
+        }
+    }
+    entries.sort((a, b) => (a.ts < b.ts ? 1 : a.ts > b.ts ? -1 : 0));
+    return entries;
+}
+function isHardshipEntry(v) {
+    if (typeof v !== "object" || v === null)
+        return false;
+    const o = v;
+    return (typeof o["ts"] === "string" &&
+        typeof o["connector"] === "string" &&
+        typeof o["action"] === "string" &&
+        typeof o["kind"] === "string" &&
+        typeof o["context"] === "string");
+}
+/** Count JSONL entries for a connector across all tiers. Used by the reminder. */
+export function countRawHardships(connector, opts = {}) {
+    return readRawHardships(connector, opts).length;
+}
+export function readFirstMatchingPattern(opts) {
+    const tiers = resolveTierPaths({
+        connector: opts.connector,
+        scope: opts.scope,
+        cwd: opts.cwd ?? process.cwd(),
+        home: opts.home ?? process.env["HOME"] ?? "/",
+    });
+    for (const tier of tiers) {
+        const file = loadPatterns(path.join(tier.dir, "patterns.yaml"));
+        const match = matchPattern(file.patterns, opts.facts);
+        if (match) {
+            return { tier: tier.name, match, scopeLevel: tier.scopeLevel };
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=read.js.map

package/dist/toolkit/hardship/read.js.map

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

package/dist/toolkit/hardship/record.d.ts

@@ -0,0 +1,43 @@
+/** A single friction observation. `ts` / `connector` / `session_id` are stamped by the writer. */
+export interface HardshipEntry {
+    ts: string;
+    connector: string;
+    action: string;
+    /** Coarse category: "rate_limit" | "auth" | "not_found" | "timeout" | "validation" | "schema" | ... */
+    kind: string;
+    /** Human-readable description of what happened. */
+    context: string;
+    /** Tenant scope key (e.g. base URL). null = connector-wide, not tenant-specific. */
+    scope: string | null;
+    /** Optional — what (if anything) resolved it or made it tolerable. */
+    resolution?: string;
+    /** Optional session id correlating with audit trail. */
+    session_id?: string;
+}
+export type HardshipInput = Omit<HardshipEntry, "ts" | "connector" | "session_id" | "scope"> & {
+    scope?: string | null;
+};
+export interface HardshipWriterOptions {
+    connector: string;
+    enabled?: boolean;
+    sessionId?: string;
+    /** Override cwd (tests). Defaults to `process.cwd()`. */
+    cwd?: string;
+    /** Override home (tests). Defaults to `process.env["HOME"] ?? "/"`. */
+    home?: string;
+    /** Force a specific path (tests, or operator override). Bypasses discovery. */
+    explicitPath?: string;
+}
+export interface ResolveHardshipPathOptions {
+    connector: string;
+    scope: string | null;
+    cwd?: string;
+    home?: string;
+}
+/** Compute where a hardship entry will be written given connector + scope + env. */
+export declare function resolveHardshipPath(opts: ResolveHardshipPathOptions): string;
+export interface HardshipRecorder {
+    (entry: HardshipInput): void;
+}
+export declare function createHardshipRecorder(opts: HardshipWriterOptions): HardshipRecorder;
+//# sourceMappingURL=record.d.ts.map

package/dist/toolkit/hardship/record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../../../src/toolkit/hardship/record.ts"],"names":[],"mappings":"AAoBA,kGAAkG;AAClG,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,uGAAuG;IACvG,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,oFAAoF;IACpF,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,EAAE,IAAI,GAAG,WAAW,GAAG,YAAY,GAAG,OAAO,CAAC,GAAG;IAC7F,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,CAAC;AAEF,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,0BAA0B;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,oFAAoF;AACpF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,0BAA0B,GAAG,MAAM,CAgB5E;AAED,MAAM,WAAW,gBAAgB;IAC/B,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;CAC9B;AAED,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,qBAAqB,GAC1B,gBAAgB,CAmClB"}

package/dist/toolkit/hardship/record.js

@@ -0,0 +1,74 @@
+/**
+ * Hardship logger. Append-only JSONL capture of agent-observed friction.
+ *
+ * Storage layering (3.0, tiered):
+ *   project-tenant: <cwd>/.claude/connectors/<name>/tenants/<hash>/hardships.jsonl
+ *   project-global: <cwd>/.claude/connectors/<name>/global/hardships.jsonl
+ *   user-tenant:    <home>/.claude/connectors/<name>/tenants/<hash>/hardships.jsonl
+ *   user-global:    <home>/.claude/connectors/<name>/global/hardships.jsonl
+ *
+ * Write goes to the most-specific tier available. If cwd/.claude/ exists,
+ * project-* tiers are eligible; otherwise user-* tiers only.
+ *
+ * Non-failing: disk errors are swallowed. Hardship MUST NEVER crash the
+ * caller — that would turn a friction observation into a full outage.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { resolveTierPaths } from "./scope.js";
+/** Compute where a hardship entry will be written given connector + scope + env. */
+export function resolveHardshipPath(opts) {
+    const cwd = opts.cwd ?? process.cwd();
+    const home = opts.home ?? process.env["HOME"] ?? "/";
+    const tiers = resolveTierPaths({
+        connector: opts.connector,
+        scope: opts.scope,
+        cwd,
+        home,
+    });
+    const hasProject = fs.existsSync(path.join(cwd, ".claude"));
+    for (const t of tiers) {
+        if (!hasProject && t.name.startsWith("project-"))
+            continue;
+        return path.join(t.dir, "hardships.jsonl");
+    }
+    // Unreachable: tiers always contains a user-global entry.
+    return path.join(tiers[tiers.length - 1].dir, "hardships.jsonl");
+}
+export function createHardshipRecorder(opts) {
+    const connector = opts.connector;
+    return (input) => {
+        if (opts.enabled === false)
+            return;
+        const scope = input.scope ?? null;
+        const dest = opts.explicitPath ??
+            resolveHardshipPath({
+                connector,
+                scope,
+                ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
+                ...(opts.home !== undefined ? { home: opts.home } : {}),
+            });
+        try {
+            fs.mkdirSync(path.dirname(dest), { recursive: true });
+            const entry = {
+                ts: new Date().toISOString(),
+                connector,
+                action: input.action,
+                kind: input.kind,
+                context: input.context,
+                scope,
+                ...(input.resolution !== undefined
+                    ? { resolution: input.resolution }
+                    : {}),
+                ...(opts.sessionId !== undefined
+                    ? { session_id: opts.sessionId }
+                    : {}),
+            };
+            fs.appendFileSync(dest, JSON.stringify(entry) + "\n", "utf-8");
+        }
+        catch {
+            // swallow — never raise into caller
+        }
+    };
+}
+//# sourceMappingURL=record.js.map

package/dist/toolkit/hardship/record.js.map

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

package/dist/toolkit/hardship/scope.d.ts

@@ -0,0 +1,20 @@
+export type TierName = "project-tenant" | "project-global" | "user-tenant" | "user-global";
+export interface Tier {
+    name: TierName;
+    dir: string;
+    scopeLevel: "tenant" | "global";
+}
+export type TierPaths = Tier[];
+/**
+ * 16-char hex sha256 prefix. Stable across processes, short enough for
+ * filesystem paths, collision probability negligible for O(100) tenants.
+ */
+export declare function hashScopeKey(key: string): string;
+export interface ResolveTierPathsOptions {
+    connector: string;
+    scope: string | null;
+    cwd: string;
+    home: string;
+}
+export declare function resolveTierPaths(opts: ResolveTierPathsOptions): TierPaths;
+//# sourceMappingURL=scope.d.ts.map