@jinn-network/jinn-layer 0.1.0

package/dist/distill-captures.js

@@ -0,0 +1,283 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { createEvidenceAdapter } from '@jinn-network/core';
+import { parseCapturedTask } from './capture.js';
+import { parseSkillMarkdown } from './skill-package.js';
+/** Deprecated CapturedTask directory retained as a read-only fallback. */
+export const DEFAULT_CAPTURES_DIR = join(homedir(), '.jinn-client', 'harness-layer', 'captures');
+/** Canonical complete EpisodeV1 records, distinct from legacy distill captures. */
+export const DEFAULT_EPISODES_DIR = join(homedir(), '.jinn-client', 'harness-layer', 'episodes');
+/** Local skills library `distill` installs into by default. */
+export const DEFAULT_SKILLS_INSTALL_DIR = join(homedir(), '.jinn-client', 'harness-layer', 'skills');
+/** How many recent own captures `distill` considers when --limit is unset. */
+export const DEFAULT_DISTILL_CAPTURE_LIMIT = 50;
+/**
+ * Load the operator's most recent own captures from `dir`. Every `*.json` file
+ * must be a `CapturedTask`; malformed files are skipped with a stderr warning
+ * so machine-readable stdout stays parseable.
+ */
+export function loadRecentCaptures(dir, limit) {
+    if (!existsSync(dir))
+        return [];
+    const parsed = [];
+    for (const file of readdirSync(dir)) {
+        if (!file.endsWith('.json'))
+            continue;
+        try {
+            parsed.push(parseCapturedTask(JSON.parse(readFileSync(join(dir, file), 'utf-8'))));
+        }
+        catch (err) {
+            console.warn(`[distill] skipping malformed capture file ${file}: ` +
+                `${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    parsed.sort((a, b) => b.session.capturedAt.localeCompare(a.session.capturedAt));
+    return parsed.slice(0, limit);
+}
+/**
+ * Project the canonical local evidence record into the input shape consumed by
+ * the existing rung-1 distillation engine. The projection is intentionally
+ * lossless for trace facts the distiller understands; episode-only state stays
+ * in the canonical record and is never copied to another store.
+ */
+export function episodeToCapturedTask(episode) {
+    const session = episode.session;
+    const task = episode.task;
+    const environment = episode.environment;
+    const generatorModel = environment.generatorModel;
+    const verifier = environment.verifier;
+    const cost = episode.cost;
+    const attemptGroup = episode.attemptGroup;
+    const lineage = episode.lineage;
+    return parseCapturedTask({
+        session: {
+            sessionId: session.sessionId,
+            capturedAt: session.capturedAt,
+            ...(session.kind ? { kind: session.kind } : {}),
+            ...(session.parentSessionId ? { parentSessionId: session.parentSessionId } : {}),
+        },
+        task: {
+            summary: task.summary,
+            // Historical CapturedTask files required at least one distribution tag,
+            // while EpisodeV1 correctly permits an empty list. The harness identity
+            // is a factual local-only fallback needed solely by this compatibility
+            // projection.
+            distributionTags: task.distributionTags.length > 0
+                ? task.distributionTags
+                : [environment.harness.name],
+            ...(task.repositorySlug ? { repositorySlug: task.repositorySlug } : {}),
+            ...(task.baseCommit ? { baseCommit: task.baseCommit } : {}),
+            ...(task.createdAt !== undefined ? { createdAt: task.createdAt } : {}),
+            ...(task.instanceId ? { instanceId: task.instanceId } : {}),
+        },
+        environment: {
+            harness: {
+                name: environment.harness.name,
+                version: environment.harness.version,
+            },
+            model: environment.model,
+            tools: environment.tools,
+            skillsLoadout: environment.skillsLoadout,
+            ...(generatorModel ? {
+                generatorModel: {
+                    id: generatorModel.id,
+                    source: generatorModel.source,
+                    ...(generatorModel.provider ? { provider: generatorModel.provider } : {}),
+                    ...(generatorModel.openWeights !== undefined
+                        ? { openWeights: generatorModel.openWeights }
+                        : {}),
+                },
+            } : {}),
+            ...(environment.distributionClass
+                ? { distributionClass: environment.distributionClass }
+                : {}),
+            ...(verifier ? {
+                verifier: {
+                    type: verifier.type,
+                    failToPass: verifier.failToPass,
+                    passToPass: verifier.passToPass,
+                    ...(verifier.evalSemanticsVersion
+                        ? { evalSemanticsVersion: verifier.evalSemanticsVersion }
+                        : {}),
+                },
+            } : {}),
+        },
+        steps: episode.trajectory.map((step) => ({
+            spanId: step.spanId,
+            parentSpanId: step.parentSpanId,
+            kind: step.kind,
+            name: step.name,
+            startTimeUnixNano: step.startTimeUnixNano,
+            endTimeUnixNano: step.endTimeUnixNano,
+            attributes: step.attributes,
+            redactedKeys: step.redactedKeys,
+            ...(step.events ? {
+                events: step.events.map((event) => ({
+                    timeUnixNano: event.timeUnixNano,
+                    name: event.name,
+                    ...(event.attributes ? { attributes: event.attributes } : {}),
+                })),
+            } : {}),
+            ...(step.status ? {
+                status: {
+                    code: step.status.code,
+                    ...(step.status.message ? { message: step.status.message } : {}),
+                },
+            } : {}),
+        })),
+        outcome: {
+            status: episode.outcome.status,
+            verifiabilityTier: episode.outcome.verificationStrength,
+            ...(episode.outcome.summary ? { summary: episode.outcome.summary } : {}),
+        },
+        cost: {
+            durationMs: cost.durationMs,
+            ...(cost.tokens ? {
+                tokens: { input: cost.tokens.input, output: cost.tokens.output },
+            } : {}),
+            ...(cost.usdEstimate ? { usdEstimate: cost.usdEstimate } : {}),
+        },
+        ...(attemptGroup ? {
+            attemptGroup: {
+                groupId: attemptGroup.groupId,
+                attemptId: attemptGroup.attemptId,
+                relatedAttemptRefs: attemptGroup.relatedAttemptRefs,
+                ...(attemptGroup.groupSize !== undefined ? { groupSize: attemptGroup.groupSize } : {}),
+                ...(attemptGroup.nPass !== undefined ? { nPass: attemptGroup.nPass } : {}),
+                ...(attemptGroup.nFail !== undefined ? { nFail: attemptGroup.nFail } : {}),
+            },
+        } : {}),
+        ...(lineage ? {
+            lineage: {
+                episodeId: lineage.episodeId,
+                ...(lineage.mintRef ? { mintRef: lineage.mintRef } : {}),
+            },
+        } : {}),
+        provenance: episode.provenance,
+    });
+}
+/**
+ * Load recent local-learning inputs from the canonical episode store, then
+ * merge historical CapturedTask files during the deprecation window. A
+ * canonical episode always wins for a duplicate session id, even when the old
+ * file has a later timestamp, and the limit is applied only after global sort.
+ */
+export async function loadRecentDistillSources(options) {
+    const evidence = createEvidenceAdapter({ capturesDir: options.episodesDir });
+    const listed = await evidence.list();
+    if (listed.status === 'unavailable') {
+        console.warn(`[distill] canonical episode store unavailable: ${listed.reason}`);
+    }
+    const canonicalBySession = new Map();
+    if (listed.status !== 'unavailable') {
+        for (const episode of listed.value ?? []) {
+            try {
+                const projected = episodeToCapturedTask(episode);
+                const existing = canonicalBySession.get(projected.session.sessionId);
+                if (!existing || projected.session.capturedAt > existing.session.capturedAt) {
+                    canonicalBySession.set(projected.session.sessionId, projected);
+                }
+            }
+            catch (err) {
+                console.warn(`[distill] skipping episode ${episode.episodeId} that cannot be projected: ` +
+                    `${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    const merged = new Map(canonicalBySession);
+    if (options.legacyCapturesDir) {
+        for (const legacy of loadRecentCaptures(options.legacyCapturesDir, Number.MAX_SAFE_INTEGER)) {
+            if (!merged.has(legacy.session.sessionId)) {
+                merged.set(legacy.session.sessionId, legacy);
+            }
+        }
+    }
+    return [...merged.values()]
+        .sort((a, b) => b.session.capturedAt.localeCompare(a.session.capturedAt))
+        .slice(0, options.limit);
+}
+/** Staging directory beside the active generated-skill directory. */
+export function stagingDirFor(activeDir) {
+    return `${activeDir.replace(/[/\\]+$/, '')}-staged`;
+}
+/** Derive local skill history from the canonical active/staged SKILL.md files. */
+export function localSkillProvenance(activeDir, stagedDir = stagingDirFor(activeDir)) {
+    const skills = new Map();
+    const scan = (dir, state) => {
+        if (!existsSync(dir))
+            return;
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const md = join(dir, entry.name, 'SKILL.md');
+            if (!existsSync(md))
+                continue;
+            try {
+                const pkg = parseSkillMarkdown(readFileSync(md, 'utf-8'));
+                const sourceSessionIds = pkg.jinn.provenance
+                    .map((ref) => /^local-capture:(.+)$/.exec(ref)?.[1])
+                    .filter((sessionId) => Boolean(sessionId));
+                if (sourceSessionIds.length === 0)
+                    continue;
+                const ref = `local-skill:${pkg.name}`;
+                const existing = skills.get(ref);
+                if (existing?.state === 'installed')
+                    continue;
+                skills.set(ref, {
+                    ref,
+                    sourceSessionIds: [...new Set(sourceSessionIds)],
+                    state,
+                });
+            }
+            catch {
+                // History is a structured JSON process command. Skip malformed local
+                // artifacts without contaminating its process output.
+            }
+        }
+    };
+    scan(activeDir, 'installed');
+    scan(stagedDir, 'staged');
+    return [...skills.values()].sort((a, b) => a.ref.localeCompare(b.ref));
+}
+/**
+ * The session ids already covered by a generated skill under any of `dirs`.
+ * Both active and staged skill dirs count so `--resume` never re-spends a
+ * capture that already produced a skill.
+ */
+export function coveredSessionIds(dirs) {
+    const covered = new Set();
+    for (const dir of dirs) {
+        if (!existsSync(dir))
+            continue;
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const md = join(dir, entry.name, 'SKILL.md');
+            if (!existsSync(md))
+                continue;
+            try {
+                const pkg = parseSkillMarkdown(readFileSync(md, 'utf-8'));
+                for (const ref of pkg.jinn.provenance) {
+                    const m = /^local-capture:(.+)$/.exec(ref);
+                    if (m?.[1])
+                        covered.add(m[1]);
+                }
+            }
+            catch {
+                // A skill dir we can't parse can't prove coverage.
+            }
+        }
+    }
+    return covered;
+}
+/**
+ * Map local provenance refs to human labels for run panels. Unknown refs remain
+ * unchanged so non-local provenance stays auditable.
+ */
+export function provenanceLabels(pkg, summaryBySession) {
+    return pkg.jinn.provenance.map((ref) => {
+        const m = /^local-capture:(.+)$/.exec(ref);
+        return m?.[1] ? (summaryBySession.get(m[1]) ?? m[1]) : ref;
+    });
+}

package/dist/distill-feedback.d.ts

@@ -0,0 +1,20 @@
+export type DistillFeedbackVerdict = 'helped' | 'hurt' | 'mixed' | 'unused';
+export interface DistillFeedbackInput {
+    skillName: string;
+    verdict: DistillFeedbackVerdict;
+    sessionId?: string;
+    notes?: string;
+    acceptedChanges?: string[];
+    recordedAt?: string;
+}
+export interface DistillFeedbackRecord extends DistillFeedbackInput {
+    schema: 'jinn.distill.feedback.v1';
+    recordedAt: string;
+}
+export declare const DEFAULT_DISTILL_FEEDBACK_PATH: string;
+export declare function distillFeedbackPathFromEnv(env?: NodeJS.ProcessEnv): string;
+export declare function recordDistillFeedback(input: DistillFeedbackInput, opts?: {
+    path?: string;
+    env?: NodeJS.ProcessEnv;
+}): DistillFeedbackRecord;
+export declare function readDistillFeedback(path?: string): DistillFeedbackRecord[];

package/dist/distill-feedback.js

@@ -0,0 +1,30 @@
+import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+export const DEFAULT_DISTILL_FEEDBACK_PATH = join(homedir(), '.jinn-client', 'harness-layer', 'distill-feedback.jsonl');
+export function distillFeedbackPathFromEnv(env = process.env) {
+    return env['JINN_LAYER_DISTILL_FEEDBACK_PATH'] ?? DEFAULT_DISTILL_FEEDBACK_PATH;
+}
+export function recordDistillFeedback(input, opts = {}) {
+    const record = {
+        schema: 'jinn.distill.feedback.v1',
+        skillName: input.skillName,
+        verdict: input.verdict,
+        recordedAt: input.recordedAt ?? new Date().toISOString(),
+        ...(input.sessionId ? { sessionId: input.sessionId } : {}),
+        ...(input.notes ? { notes: input.notes } : {}),
+        ...(input.acceptedChanges && input.acceptedChanges.length > 0 ? { acceptedChanges: input.acceptedChanges } : {}),
+    };
+    const path = opts.path ?? distillFeedbackPathFromEnv(opts.env);
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    appendFileSync(path, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+    return record;
+}
+export function readDistillFeedback(path = DEFAULT_DISTILL_FEEDBACK_PATH) {
+    const text = readFileSync(path, 'utf8');
+    return text
+        .split('\n')
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => JSON.parse(line));
+}

package/dist/distill-llm.d.ts

@@ -0,0 +1,138 @@
+/**
+ * The distill LLM port — runs `jinn-skill-distill-prompt-v1` over one evidence
+ * cluster via the `claude` CLI and returns a {@link DistillLLMOutput}
+ * (spec/2026-07-06-distillation-v1.md §7). This is the model call that
+ * `distillClusters` injects as `DistillDeps.distill`; the distiller itself owns
+ * the downstream scrub / contamination / publish steps.
+ *
+ * The port is deliberately thin: it builds the model input (the versioned
+ * distill prompt + a serialized view of the cluster), spawns `claude` in
+ * non-interactive mode reading that input on stdin, and parses a strict
+ * `{ name, description, body }` JSON object back out of stdout (tolerating a
+ * leading/trailing prose wrapper the model may emit around it).
+ *
+ * Auth is ambient: the `claude` CLI resolves its own credentials (a logged-in
+ * session, `CLAUDE_CODE_OAUTH_TOKEN`, or `ANTHROPIC_API_KEY` from the env). This
+ * port never reads, sets, or manages a key — matching the daemon's other
+ * `claude -p` call sites (`src/runner/claude.ts`, the claude-code adapter).
+ */
+import type { DistillCluster, DistillLLMOutput, MetaDistillLLMOutput } from './distill.js';
+import type { MetaCluster } from './cluster.js';
+/**
+ * Default distiller model — the strongest available (opus-class), NOT the
+ * daemon-wide cheap default (spec §5, v0.5). Distillation is offline, one-shot,
+ * and cheap relative to the measurement run, and its quality is model-sensitive
+ * — so it pins the best model. Overridable via `JINN_DISTILL_MODEL` at the CLI.
+ */
+export declare const DEFAULT_MODEL = "claude-opus-4-8";
+/** Default Codex distiller model for quality runs; override with `JINN_DISTILL_MODEL`. */
+export declare const DEFAULT_CODEX_MODEL = "gpt-5.5";
+/**
+ * Default per-cluster subprocess deadline (#1534). A hung `claude`/`codex`
+ * child would otherwise block a run forever — silently, since nothing prints
+ * until the run completes. On expiry the child is killed and the cluster lands
+ * in `errors[]`; the run continues. Override with `--cluster-timeout` /
+ * `JINN_DISTILL_CLUSTER_TIMEOUT_S`.
+ */
+export declare const DEFAULT_CLUSTER_TIMEOUT_MS = 600000;
+/** A distiller subprocess exceeded its per-cluster deadline and was killed. */
+export declare class DistillTimeoutError extends Error {
+    constructor(label: string, timeoutMs: number);
+}
+/** One row of the discoverable distiller catalog (`distill models`). */
+export interface DistillerCatalogEntry {
+    provider: 'claude' | 'codex';
+    model: string;
+    /** `local` runs on this machine; `hosted` sends captures off-machine (none yet). */
+    execution: 'local' | 'hosted';
+    cost: string;
+    privacy: string;
+    isDefault?: boolean;
+}
+/**
+ * The static, honest catalog of runnable distillers. Every entry is `local`
+ * today — no hosted distiller exists (both ports spawn a local CLI). The models
+ * reference `DEFAULT_MODEL` / `DEFAULT_CODEX_MODEL` directly so the catalog and
+ * the provider defaults cannot drift.
+ */
+export declare const DISTILLER_CATALOG: readonly DistillerCatalogEntry[];
+/**
+ * The subset of `node:child_process` a spawned child exposes that this port
+ * uses. Injected so tests capture the args + feed canned stdout without ever
+ * spawning a real `claude`.
+ */
+export interface ChildLike {
+    stdin: {
+        write(chunk: string): void;
+        end(): void;
+    } | null;
+    stdout: {
+        on(event: 'data', listener: (chunk: Buffer | string) => void): void;
+    } | null;
+    stderr: {
+        on(event: 'data', listener: (chunk: Buffer | string) => void): void;
+    } | null;
+    on(event: 'error', listener: (err: Error) => void): void;
+    on(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): void;
+    /** Optional so pre-#1534 test fakes stay valid; real children always have it. */
+    kill?(signal?: NodeJS.Signals): void;
+}
+/** Minimal spawn signature: `(command, args) => child`. Satisfied by `child_process.spawn`. */
+export type SpawnLike = (command: string, args: readonly string[]) => ChildLike;
+/**
+ * Build the full model input: the versioned distill prompt, the serialized
+ * cluster, and a strict-JSON output contract. The contract is explicit so the
+ * downstream parser has an object to extract even if the model wraps it in prose.
+ */
+export declare function buildDistillInput(prompt: string, cluster: DistillCluster): string;
+/**
+ * Build the distill LLM port. Returns the `DistillDeps.distill` function: given
+ * a cluster, spawn `claude -p --model <model>`, pipe the built input on stdin,
+ * collect stdout, and parse the strict JSON output.
+ *
+ * @param opts.claudePath  Path to the `claude` executable (default `claude`).
+ * @param opts.model       Model id (default `claude-opus-4-8` — opus-class, §5).
+ * @param opts.spawnImpl   Injected spawn (default `child_process.spawn`); tests
+ *                         pass a fake so no real `claude` is invoked.
+ */
+export declare function createClaudeDistiller(opts?: {
+    claudePath?: string;
+    model?: string;
+    spawnImpl?: SpawnLike;
+    timeoutMs?: number;
+}): (cluster: DistillCluster) => Promise<DistillLLMOutput>;
+/**
+ * Build the Codex distill LLM port. This mirrors {@link createClaudeDistiller}
+ * but invokes `codex exec` with read-only sandboxing, no approvals, ephemeral
+ * session state, and a JSON schema file for structured final output.
+ */
+export declare function createCodexDistiller(opts?: {
+    codexPath?: string;
+    model?: string;
+    spawnImpl?: SpawnLike;
+    timeoutMs?: number;
+}): (cluster: DistillCluster) => Promise<DistillLLMOutput>;
+/** Build the full meta model input: the versioned meta prompt + the sources + the JSON contract. */
+export declare function buildMetaDistillInput(prompt: string, cluster: MetaCluster): string;
+/**
+ * Build the stage-2 meta-distill LLM port (issue #1463). Same spawn/parse
+ * scaffolding as {@link createClaudeDistiller}: spawns `claude -p --model`,
+ * pipes {@link buildMetaDistillInput} on stdin, and parses the strict JSON
+ * (tolerating a prose wrapper via the shared {@link extractJsonObject}).
+ */
+export declare function createClaudeMetaDistiller(opts?: {
+    claudePath?: string;
+    model?: string;
+    spawnImpl?: SpawnLike;
+    timeoutMs?: number;
+}): (cluster: MetaCluster) => Promise<MetaDistillLLMOutput>;
+/**
+ * Build the Codex stage-2 meta-distill port. Same prompt and validation as the
+ * Claude meta port, with Codex structured output enforced by JSON schema.
+ */
+export declare function createCodexMetaDistiller(opts?: {
+    codexPath?: string;
+    model?: string;
+    spawnImpl?: SpawnLike;
+    timeoutMs?: number;
+}): (cluster: MetaCluster) => Promise<MetaDistillLLMOutput>;