@jinn-network/jinn-layer 0.1.0

package/dist/distill-mcp-server.js

@@ -0,0 +1,281 @@
+import { spawn } from 'node:child_process';
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod/v3';
+import { DEFAULT_CAPTURES_DIR, DEFAULT_DISTILL_CAPTURE_LIMIT, DEFAULT_EPISODES_DIR, loadRecentDistillSources, } from './distill-captures.js';
+import { clusterTraceCards, readTrace, searchTraceCards, traceCardFromCapture, } from './distill-traces.js';
+import { recordDistillFeedback } from './distill-feedback.js';
+const traceReadModes = ['summary', 'events', 'tool_calls', 'transcript_excerpt', 'full_transcript'];
+export function createDistillMcpServer(deps = {}) {
+    const server = new McpServer({
+        name: 'jinn-local-distill',
+        version: '0.1.0',
+    });
+    server.tool('distill_trace_search', 'Search local trace cards from canonical local episodes (plus a read-only legacy capture fallback). Use this before reading full traces; returns compact cards only.', {
+        episodesDir: z.string().optional().describe('Directory containing canonical EpisodeV1 files. Defaults to JINN_LAYER_EPISODES_DIR or ~/.jinn-client/harness-layer/episodes.'),
+        capturesDir: z.string().optional().describe('Deprecated directory containing legacy CapturedTask JSON files.'),
+        limit: z.number().int().positive().max(500).optional().describe('Maximum captures to load and maximum cards to return.'),
+        query: z.string().optional().describe('Free-text query across summary, tools, commands, files, errors, and outcome.'),
+        command: z.string().optional().describe('Command substring filter.'),
+        file: z.string().optional().describe('Touched-file substring filter.'),
+        error: z.string().optional().describe('Error substring filter.'),
+        tool: z.string().optional().describe('Tool-name substring filter.'),
+        outcome: z.enum(['completed', 'failed', 'abandoned']).optional().describe('Outcome status filter.'),
+    }, async (args) => {
+        const source = distillSourceDirs(args, deps.env);
+        const limit = args.limit ?? DEFAULT_DISTILL_CAPTURE_LIMIT;
+        const captures = await loadRecentDistillSources({ ...source, limit });
+        const cards = searchTraceCards(captures.map(traceCardFromCapture), {
+            query: args.query,
+            command: args.command,
+            file: args.file,
+            error: args.error,
+            tool: args.tool,
+            outcome: args.outcome,
+            limit,
+        });
+        return jsonResponse({ ...source, count: cards.length, cards });
+    });
+    server.tool('distill_trace_read', 'Read a selected local trace by traceId or sessionId. Prefer summary, transcript_excerpt, or tool_calls before requesting full_transcript.', {
+        episodesDir: z.string().optional().describe('Directory containing canonical EpisodeV1 files.'),
+        capturesDir: z.string().optional().describe('Deprecated directory containing legacy CapturedTask JSON files.'),
+        limit: z.number().int().positive().max(500).optional().describe('Maximum captures to load while locating the trace.'),
+        traceId: z.string().optional().describe('Trace id returned by distill_trace_search, e.g. local-capture:<sessionId>.'),
+        sessionId: z.string().optional().describe('Raw session id when traceId is not available.'),
+        mode: z.enum(traceReadModes).optional().describe('Read mode. full_transcript requires allowFullTranscript=true.'),
+        query: z.string().optional().describe('Optional excerpt filter for transcript_excerpt mode.'),
+        readLimit: z.number().int().positive().max(200).optional().describe('Maximum events returned for transcript_excerpt mode.'),
+        allowFullTranscript: z.boolean().optional().describe('Required explicit opt-in for full_transcript reads.'),
+    }, async (args) => {
+        const source = distillSourceDirs(args, deps.env);
+        const captures = await loadRecentDistillSources({
+            ...source,
+            limit: args.limit ?? DEFAULT_DISTILL_CAPTURE_LIMIT,
+        });
+        const capture = findCapture(captures, { traceId: args.traceId, sessionId: args.sessionId });
+        if (!capture)
+            return errorResponse(`Trace not found: ${args.traceId ?? args.sessionId ?? '(missing id)'}`);
+        try {
+            return jsonResponse(readTrace(capture, {
+                mode: args.mode ?? 'summary',
+                query: args.query,
+                limit: args.readLimit,
+                allowFullTranscript: args.allowFullTranscript,
+            }));
+        }
+        catch (err) {
+            return errorResponse(err instanceof Error ? err.message : String(err));
+        }
+    });
+    server.tool('distill_trace_cluster', 'Group local trace cards into candidate skill opportunities using repeated commands, files, and error signals. This is a cheap pre-distill scan.', {
+        episodesDir: z.string().optional().describe('Directory containing canonical EpisodeV1 files.'),
+        capturesDir: z.string().optional().describe('Deprecated directory containing legacy CapturedTask JSON files.'),
+        limit: z.number().int().positive().max(500).optional().describe('Maximum captures to load.'),
+    }, async (args) => {
+        const source = distillSourceDirs(args, deps.env);
+        const captures = await loadRecentDistillSources({
+            ...source,
+            limit: args.limit ?? DEFAULT_DISTILL_CAPTURE_LIMIT,
+        });
+        const candidates = clusterTraceCards(captures.map(traceCardFromCapture));
+        return jsonResponse({ ...source, count: candidates.length, candidates });
+    });
+    server.tool('distill_local', 'Run local skill distillation over captured traces by delegating to jinn-layer distill. Requires confirm:true because it can call an LLM and write staged or installed skills.', {
+        confirm: z.boolean().optional().describe('Must be true to execute. Omit or false to receive a preview envelope.'),
+        episodesDir: z.string().optional().describe('Directory containing canonical EpisodeV1 files.'),
+        capturesDir: z.string().optional().describe('Deprecated directory containing legacy CapturedTask JSON files.'),
+        out: z.string().optional().describe('Output directory for distilled skills.'),
+        limit: z.number().int().positive().max(500).optional().describe('Maximum captures to distill.'),
+        traceIds: z.array(z.string()).optional().describe('Optional selected trace IDs to distill, as returned by distill_trace_search or distill_trace_cluster.'),
+        sessionIds: z.array(z.string()).optional().describe('Optional selected raw session IDs to distill.'),
+        install: z.string().optional().describe('Install choice passed to --install: all, none, or a specific skill name.'),
+        resume: z.boolean().optional().describe('Pass --resume so already-covered sessions are skipped.'),
+        distiller: z.enum(['claude', 'codex']).optional().describe('LLM provider to use for the distiller pass.'),
+        distillerModel: z.string().optional().describe('Distiller model name. This is separate from the runtime model recorded in the skill.'),
+    }, async (args) => {
+        if (!args.confirm) {
+            return jsonResponse({
+                schemaVersion: 1,
+                status: 'preview',
+                tool: 'distill_local',
+                description: 'Run local distillation over captured traces.',
+                effects: [
+                    'Reads canonical local EpisodeV1 files and, when using the default location, legacy captured-task JSON as a compatibility fallback.',
+                    'Calls the selected user LLM provider through the existing jinn-layer distill flow.',
+                    'Writes distilled skill packages under the output/staging directory and may install selected skills.',
+                ],
+                followUp: {
+                    tool: 'distill_local',
+                    arguments: { ...args, confirm: true },
+                },
+            });
+        }
+        return runLocalDistill({
+            episodesDir: args.episodesDir,
+            capturesDir: args.capturesDir,
+            out: args.out,
+            limit: args.limit,
+            traceIds: args.traceIds,
+            sessionIds: args.sessionIds,
+            install: args.install,
+            resume: args.resume,
+            distiller: args.distiller,
+            distillerModel: args.distillerModel,
+        }, deps);
+    });
+    server.tool('distill_feedback_record', 'Record local user feedback for an experimental distilled skill. Use this after a later session uses the skill and the user accepts a helped/hurt/mixed/unused verdict.', {
+        skillName: z.string().min(1).describe('Distilled skill name.'),
+        verdict: z.enum(['helped', 'hurt', 'mixed', 'unused']).describe('User-visible outcome of using the skill.'),
+        sessionId: z.string().optional().describe('Session where the skill was used, if known.'),
+        notes: z.string().optional().describe('Short user-approved note about what to improve or preserve.'),
+        acceptedChanges: z.array(z.string()).optional().describe('Concrete user-approved changes to apply in a later skill improvement pass.'),
+        feedbackPath: z.string().optional().describe('Override feedback JSONL path. Defaults to JINN_LAYER_DISTILL_FEEDBACK_PATH or ~/.jinn-client/harness-layer/distill-feedback.jsonl.'),
+    }, async (args) => {
+        const record = recordDistillFeedback({
+            skillName: args.skillName,
+            verdict: args.verdict,
+            ...(args.sessionId ? { sessionId: args.sessionId } : {}),
+            ...(args.notes ? { notes: args.notes } : {}),
+            ...(args.acceptedChanges ? { acceptedChanges: args.acceptedChanges } : {}),
+        }, {
+            ...(args.feedbackPath ? { path: args.feedbackPath } : {}),
+            ...(deps.env ? { env: deps.env } : {}),
+        });
+        return jsonResponse({ recorded: record });
+    });
+    return server;
+}
+export async function runLocalDistill(args, deps = {}) {
+    const resolved = resolveJinnLayerCommand(deps.env, deps.platform);
+    const hasSelection = (args.traceIds?.length ?? 0) > 0 || (args.sessionIds?.length ?? 0) > 0;
+    // Preserve the synchronous spawn boundary for ordinary calls. Selection
+    // needs an async canonical-store read; an unselected run does not.
+    const selected = hasSelection ? await materializeSelectedCaptures(args, deps.env) : {};
+    if (selected.error)
+        return errorResponse(selected.error);
+    const argv = [
+        ...resolved.prefixArgs,
+        'distill',
+        '--where',
+        'local',
+        '--json',
+    ];
+    const capturesDir = selected.capturesDir ?? args.capturesDir;
+    if (!selected.capturesDir && args.episodesDir)
+        argv.push('--episodes', args.episodesDir);
+    if (capturesDir)
+        argv.push('--captures', capturesDir);
+    if (args.out)
+        argv.push('--out', args.out);
+    if (args.limit !== undefined)
+        argv.push('--limit', String(args.limit));
+    if (args.install)
+        argv.push('--install', args.install);
+    if (args.resume)
+        argv.push('--resume');
+    if (args.distiller)
+        argv.push('--distiller', args.distiller);
+    if (args.distillerModel)
+        argv.push('--distiller-model', args.distillerModel);
+    const spawnFn = deps.spawn ?? spawn;
+    const child = spawnFn(resolved.command, argv, {
+        env: { ...process.env, ...(deps.env ?? {}) },
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    try {
+        const result = await collectChild(child);
+        return jsonResponse({
+            command: [basename(resolved.command), ...argv],
+            exitCode: result.exitCode,
+            stdout: result.stdout,
+            stderr: result.stderr,
+            ...(selected.traceCount !== undefined ? { selectedTraceCount: selected.traceCount } : {}),
+        }, result.exitCode === 0 ? undefined : true);
+    }
+    finally {
+        if (selected.tempDir)
+            rmSync(selected.tempDir, { recursive: true, force: true });
+    }
+}
+function jsonResponse(value, isError) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(value) }],
+        ...(isError ? { isError } : {}),
+    };
+}
+function errorResponse(message) {
+    return jsonResponse({ error: { message } }, true);
+}
+function distillSourceDirs(args, env = process.env) {
+    const episodesOverride = args.episodesDir ?? env['JINN_LAYER_EPISODES_DIR'];
+    const legacyOverride = args.capturesDir ?? env['JINN_LAYER_CAPTURES_DIR'];
+    const episodesDir = episodesOverride ?? legacyOverride ?? DEFAULT_EPISODES_DIR;
+    const legacyCapturesDir = legacyOverride ?? (episodesOverride ? undefined : DEFAULT_CAPTURES_DIR);
+    return {
+        episodesDir,
+        ...(legacyCapturesDir ? { legacyCapturesDir } : {}),
+    };
+}
+function findCapture(captures, ids) {
+    const sessionId = ids.sessionId ?? ids.traceId?.replace(/^local-capture:/, '');
+    if (!sessionId)
+        return undefined;
+    return captures.find((capture) => capture.session.sessionId === sessionId);
+}
+function resolveJinnLayerCommand(env = process.env, platform = process.platform) {
+    const sibling = fileURLToPath(new URL('./bin/jinn-layer.js', import.meta.url));
+    if (platform === 'win32') {
+        if (!existsSync(sibling)) {
+            throw new Error(`co-installed jinn-layer CLI is missing on Windows: ${sibling}`);
+        }
+        return { command: process.execPath, prefixArgs: [sibling] };
+    }
+    if (env['JINN_LAYER_BIN'])
+        return { command: env['JINN_LAYER_BIN'], prefixArgs: [] };
+    if (existsSync(sibling))
+        return { command: process.execPath, prefixArgs: [sibling] };
+    return { command: 'jinn-layer', prefixArgs: [] };
+}
+async function materializeSelectedCaptures(args, env = process.env) {
+    const selectedIds = new Set([
+        ...(args.sessionIds ?? []),
+        ...(args.traceIds ?? []).map((id) => id.replace(/^local-capture:/, '')),
+    ].filter((id) => id.trim() !== ''));
+    if (selectedIds.size === 0)
+        return {};
+    const source = distillSourceDirs(args, env);
+    const captures = (await loadRecentDistillSources({
+        ...source,
+        limit: args.limit ?? DEFAULT_DISTILL_CAPTURE_LIMIT,
+    }))
+        .filter((capture) => selectedIds.has(capture.session.sessionId));
+    if (captures.length === 0) {
+        return { error: `No selected traces found in ${source.episodesDir}` };
+    }
+    const tempDir = mkdtempSync(join(tmpdir(), 'jinn-distill-selected-'));
+    for (const capture of captures) {
+        writeFileSync(join(tempDir, `${safeFilePart(capture.session.sessionId)}.json`), `${JSON.stringify(capture, null, 2)}\n`, { mode: 0o600 });
+    }
+    return { capturesDir: tempDir, tempDir, traceCount: captures.length };
+}
+function safeFilePart(value) {
+    const safe = value.replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 128);
+    return safe || 'capture';
+}
+function collectChild(child) {
+    return new Promise((resolve, reject) => {
+        let stdout = '';
+        let stderr = '';
+        child.stdout?.on('data', (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.stderr?.on('data', (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.once('error', reject);
+        child.once('close', (code) => resolve({ exitCode: code, stdout, stderr }));
+    });
+}

package/dist/distill-mode.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The `distill` where-it-runs mode — the persistent consent setting (issue #1490).
+ *
+ * A three-value setting: `local` runs a frontier pass here now, `defer` holds
+ * the operator's captures locally and runs nothing, `off` stops reserving
+ * captures for distillation at all. An absent (or unrecognised) setting reads
+ * as `unset`, which triggers the first-run consent flow.
+ *
+ * The mode is a real fact on disk, not an interactive-only prompt: the flag
+ * (`distill --where <mode>`) and the prompt write the same `{ where }` value, so
+ * a script can set it without a TTY (mirrors `cli/commands/auth.ts`, the one
+ * interactive-prompt precedent in the client). It lives next to the harness
+ * layer's other operator state (captures, skills, ledger) under
+ * `~/.jinn-client/harness-layer/`.
+ */
+/** The three where-it-runs modes the operator can record. */
+export type DistillMode = 'local' | 'defer' | 'off';
+/** A recorded mode, or `unset` when none is on disk (→ first-run consent). */
+export type DistillModeState = DistillMode | 'unset';
+/** The default mode file, alongside the layer's other operator state. */
+export declare const DEFAULT_DISTILL_MODE_PATH: string;
+/**
+ * The pre-rename (single-l) mode file (#1532), read as a fallback when the
+ * path being read is absent — a mode recorded before the rename is still
+ * honoured. Never written.
+ */
+export declare const LEGACY_DISTILL_MODE_PATH: string;
+/** The two distiller providers the persisted default may name. */
+export type DistillDefaultProvider = 'claude' | 'codex';
+/** The persisted per-axis distiller defaults, sibling to `where`. */
+export interface DistillDefaults {
+    distiller?: DistillDefaultProvider;
+    distillerModel?: string;
+}
+/**
+ * Read the recorded mode. A missing file, malformed JSON, or a `where` value
+ * that is not one of the three modes all read as `unset` — the fail-safe that
+ * routes a bare `distill` to the first-run consent rather than to a run.
+ *
+ * When `path` is absent, the legacy single-l file is consulted (#1532) so a
+ * mode recorded before the rename still counts. Defaults to the legacy path
+ * only when reading the default path — a custom `path` opts out unless a
+ * `legacyPath` is passed explicitly.
+ */
+export declare function readDistillMode(path?: string, legacyPath?: string | undefined): DistillModeState;
+/**
+ * Persist the mode as the design's `{ where }` shape, creating the parent
+ * directory if needed. The flag and the prompt both call this, so the two paths
+ * write identically.
+ */
+export declare function writeDistillMode(mode: DistillMode, path?: string): void;
+/**
+ * Read the persisted distiller defaults. Same fail-safe as `readDistillMode`:
+ * an unrecognised `distiller` or a non-string `distillerModel` reads as absent,
+ * so a corrupt field falls back to the provider default rather than erroring.
+ */
+export declare function readDistillDefaults(path?: string): DistillDefaults;
+/**
+ * Merge the given distiller-default patch into the doc, preserving `where` and
+ * any default not named in the patch. Writes the same pretty JSON shape.
+ */
+export declare function writeDistillDefaults(patch: DistillDefaults, path?: string): void;

package/dist/distill-mode.js

@@ -0,0 +1,107 @@
+/**
+ * The `distill` where-it-runs mode — the persistent consent setting (issue #1490).
+ *
+ * A three-value setting: `local` runs a frontier pass here now, `defer` holds
+ * the operator's captures locally and runs nothing, `off` stops reserving
+ * captures for distillation at all. An absent (or unrecognised) setting reads
+ * as `unset`, which triggers the first-run consent flow.
+ *
+ * The mode is a real fact on disk, not an interactive-only prompt: the flag
+ * (`distill --where <mode>`) and the prompt write the same `{ where }` value, so
+ * a script can set it without a TTY (mirrors `cli/commands/auth.ts`, the one
+ * interactive-prompt precedent in the client). It lives next to the harness
+ * layer's other operator state (captures, skills, ledger) under
+ * `~/.jinn-client/harness-layer/`.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+/** The default mode file, alongside the layer's other operator state. */
+export const DEFAULT_DISTILL_MODE_PATH = join(homedir(), '.jinn-client', 'harness-layer', 'distill.json');
+/**
+ * The pre-rename (single-l) mode file (#1532), read as a fallback when the
+ * path being read is absent — a mode recorded before the rename is still
+ * honoured. Never written.
+ */
+export const LEGACY_DISTILL_MODE_PATH = join(homedir(), '.jinn-client', 'harness-layer', 'distil.json');
+const MODES = ['local', 'defer', 'off'];
+function isDistillMode(value) {
+    return typeof value === 'string' && MODES.includes(value);
+}
+const PROVIDERS = ['claude', 'codex'];
+function isDefaultProvider(value) {
+    return typeof value === 'string' && PROVIDERS.includes(value);
+}
+/** Parse the whole doc off disk once; a missing/malformed file is `{}`. */
+function readDoc(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        const doc = JSON.parse(readFileSync(path, 'utf-8'));
+        return typeof doc === 'object' && doc !== null ? doc : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Read the recorded mode. A missing file, malformed JSON, or a `where` value
+ * that is not one of the three modes all read as `unset` — the fail-safe that
+ * routes a bare `distill` to the first-run consent rather than to a run.
+ *
+ * When `path` is absent, the legacy single-l file is consulted (#1532) so a
+ * mode recorded before the rename still counts. Defaults to the legacy path
+ * only when reading the default path — a custom `path` opts out unless a
+ * `legacyPath` is passed explicitly.
+ */
+export function readDistillMode(path = DEFAULT_DISTILL_MODE_PATH, legacyPath = path === DEFAULT_DISTILL_MODE_PATH
+    ? LEGACY_DISTILL_MODE_PATH
+    : undefined) {
+    if (!existsSync(path)) {
+        if (legacyPath !== undefined && existsSync(legacyPath)) {
+            return readDistillMode(legacyPath, undefined);
+        }
+        return 'unset';
+    }
+    const doc = readDoc(path);
+    return isDistillMode(doc.where) ? doc.where : 'unset';
+}
+/**
+ * Persist the mode as the design's `{ where }` shape, creating the parent
+ * directory if needed. The flag and the prompt both call this, so the two paths
+ * write identically.
+ */
+export function writeDistillMode(mode, path = DEFAULT_DISTILL_MODE_PATH) {
+    const doc = readDoc(path);
+    doc.where = mode;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(doc, null, 2) + '\n', { encoding: 'utf-8' });
+}
+/**
+ * Read the persisted distiller defaults. Same fail-safe as `readDistillMode`:
+ * an unrecognised `distiller` or a non-string `distillerModel` reads as absent,
+ * so a corrupt field falls back to the provider default rather than erroring.
+ */
+export function readDistillDefaults(path = DEFAULT_DISTILL_MODE_PATH) {
+    const doc = readDoc(path);
+    const out = {};
+    if (isDefaultProvider(doc.distiller))
+        out.distiller = doc.distiller;
+    if (typeof doc.distillerModel === 'string' && doc.distillerModel !== '') {
+        out.distillerModel = doc.distillerModel;
+    }
+    return out;
+}
+/**
+ * Merge the given distiller-default patch into the doc, preserving `where` and
+ * any default not named in the patch. Writes the same pretty JSON shape.
+ */
+export function writeDistillDefaults(patch, path = DEFAULT_DISTILL_MODE_PATH) {
+    const doc = readDoc(path);
+    if (patch.distiller !== undefined)
+        doc.distiller = patch.distiller;
+    if (patch.distillerModel !== undefined)
+        doc.distillerModel = patch.distillerModel;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(doc, null, 2) + '\n', { encoding: 'utf-8' });
+}

package/dist/distill-progress.d.ts

@@ -0,0 +1,78 @@
+/**
+ * NDJSON progress events for a `distill` run (#1533).
+ *
+ * A run is a silent multi-minute blocking call (one frontier subprocess per
+ * cluster), so any wrapper — the harness plugin's background runner, a script,
+ * CI — needs a machine-readable event stream to show progress ambiently. The
+ * emitter writes one JSON object per line to the given stream (the CLI passes
+ * stderr; stdout stays reserved for the `--json` result), stamping every line
+ * with a schema version, timestamp, and run id.
+ *
+ * Consumers MUST ignore lines that do not parse as JSON or lack the `v` field:
+ * the stream is shared with plain-text warnings (e.g. malformed-capture skips).
+ *
+ * Ordering guarantee: `run_start` → `cluster_plan` → (`cluster_start` →
+ * `heartbeat`* → `cluster_end`)* → `run_end`; `run_end` is always last and is
+ * emitted on every terminal branch, so a watcher can treat it as the single
+ * end-of-run signal.
+ */
+/** Anything line-writable — `process.stderr` in production, a sink in tests. */
+export interface ProgressStream {
+    write(chunk: string): unknown;
+}
+/** Mint a per-invocation run id: `distill-<unixms>-<4hex>`. */
+export declare function newRunId(): string;
+export interface RunStartFields {
+    capturesConsidered: number;
+    toDistill: number;
+    resume: boolean;
+    distillProvider: string;
+    distillModel: string;
+    capturesDir?: string;
+    stagingDir?: string;
+    activeDir?: string;
+}
+export interface ClusterPlanFields {
+    clusterCount: number;
+    clusters: Array<{
+        clusterId: string;
+        index: number;
+        captureCount: number;
+        label?: string;
+    }>;
+}
+export interface ClusterStartFields {
+    clusterId: string;
+    index: number;
+    total: number;
+    label?: string;
+}
+export interface ClusterEndFields extends ClusterStartFields {
+    outcome: 'published' | 'rejected' | 'error';
+    skillName?: string;
+    reason?: string;
+    error?: string;
+    durationMs?: number;
+}
+export interface RunEndFields {
+    outcome: 'ok' | 'partial' | 'empty';
+    clusterCount: number;
+    published: string[];
+    rejectedCount: number;
+    errorCount: number;
+    installed: string[];
+    stagingDir?: string;
+}
+export interface NdjsonProgressEmitter {
+    runStart(fields: RunStartFields): void;
+    clusterPlan(fields: ClusterPlanFields): void;
+    clusterStart(fields: ClusterStartFields): void;
+    clusterEnd(fields: ClusterEndFields): void;
+    /** Always the last event; clears any live heartbeat and stamps the run duration. */
+    runEnd(fields: RunEndFields): void;
+}
+export interface ProgressEmitterOpts {
+    /** Heartbeat period while a cluster's LLM call is in flight. Default 15s. */
+    heartbeatMs?: number;
+}
+export declare function createNdjsonProgressEmitter(stream: ProgressStream, runId: string, opts?: ProgressEmitterOpts): NdjsonProgressEmitter;

package/dist/distill-progress.js

@@ -0,0 +1,69 @@
+/**
+ * NDJSON progress events for a `distill` run (#1533).
+ *
+ * A run is a silent multi-minute blocking call (one frontier subprocess per
+ * cluster), so any wrapper — the harness plugin's background runner, a script,
+ * CI — needs a machine-readable event stream to show progress ambiently. The
+ * emitter writes one JSON object per line to the given stream (the CLI passes
+ * stderr; stdout stays reserved for the `--json` result), stamping every line
+ * with a schema version, timestamp, and run id.
+ *
+ * Consumers MUST ignore lines that do not parse as JSON or lack the `v` field:
+ * the stream is shared with plain-text warnings (e.g. malformed-capture skips).
+ *
+ * Ordering guarantee: `run_start` → `cluster_plan` → (`cluster_start` →
+ * `heartbeat`* → `cluster_end`)* → `run_end`; `run_end` is always last and is
+ * emitted on every terminal branch, so a watcher can treat it as the single
+ * end-of-run signal.
+ */
+import { randomBytes } from 'node:crypto';
+/** Mint a per-invocation run id: `distill-<unixms>-<4hex>`. */
+export function newRunId() {
+    return `distill-${Date.now()}-${randomBytes(2).toString('hex')}`;
+}
+const DEFAULT_HEARTBEAT_MS = 15_000;
+export function createNdjsonProgressEmitter(stream, runId, opts = {}) {
+    const heartbeatMs = opts.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
+    const runStartedAt = Date.now();
+    let heartbeat;
+    function emit(event, fields) {
+        stream.write(JSON.stringify({ v: 1, event, ts: new Date().toISOString(), runId, ...fields }) + '\n');
+    }
+    function clearHeartbeat() {
+        if (heartbeat !== undefined) {
+            clearInterval(heartbeat);
+            heartbeat = undefined;
+        }
+    }
+    return {
+        runStart(fields) {
+            emit('run_start', { ...fields });
+        },
+        clusterPlan(fields) {
+            emit('cluster_plan', { ...fields });
+        },
+        clusterStart(fields) {
+            emit('cluster_start', { ...fields });
+            clearHeartbeat();
+            const clusterStartedAt = Date.now();
+            heartbeat = setInterval(() => {
+                emit('heartbeat', {
+                    clusterId: fields.clusterId,
+                    index: fields.index,
+                    total: fields.total,
+                    elapsedMs: Date.now() - clusterStartedAt,
+                });
+            }, heartbeatMs);
+            // Liveness only — never keep the process alive for a heartbeat.
+            heartbeat.unref?.();
+        },
+        clusterEnd(fields) {
+            clearHeartbeat();
+            emit('cluster_end', { ...fields });
+        },
+        runEnd(fields) {
+            clearHeartbeat();
+            emit('run_end', { ...fields, durationMs: Date.now() - runStartedAt });
+        },
+    };
+}

package/dist/distill-prompt.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `jinn-skill-distill-prompt-v1` — the layer-1-evidence → layer-2-skill
+ * distillation prompt (spec/2026-07-06-distillation-v1.md §7, D4/D10 + v0.5).
+ *
+ * Three modes keyed to the cluster's tier (§7), following the SkillRL
+ * decomposition (arXiv 2602.08234, §2.4) plus the ExpeL contrastive axis:
+ * successes → strategic patterns; evaluator-confirmed failures → failure
+ * lessons stated as DIAGNOSIS, not prescription (the verified-counterfactual
+ * rule — the evidence verifies THAT an attempt failed, not the fix); and
+ * both-polarity instances → one contrastive skill whose counterfactual IS the
+ * verified pass. Every mode emits the fixed skeleton and a trigger/anti-trigger
+ * description. Single-shot and flat for v1 (recursion/hierarchy are v3).
+ *
+ * Like `SESSION_DERIVED_DISTILL_PROMPT_V1`, this is a foundation reference
+ * implementation, not protocol canon: a later network-task version may
+ * substitute it, and the SHA-256 below is published on every distilled skill
+ * (`metadata.jinn.distillPromptSha256`) so generated skills stay auditable.
+ */
+export declare const JINN_SKILL_DISTILL_PROMPT_V1 = "You distil verified agent evidence into ONE reusable Agent-Skill (a SKILL.md package).\n\nInput: a cluster of evaluator-verified traces for one coding sub-problem, and a MODE.\n\nMODE = strategic-pattern (the traces are SUCCESSES):\n- Extract the critical decision points and the generalizable behavior that made the solve work \u2014 the strategy a future agent should reuse, not the specific diff.\n\nMODE = failure-lesson (the traces are evaluator-confirmed FAILURES):\n- The evidence verifies THAT this approach failed \u2014 it does NOT verify what would have worked. State the DIAGNOSIS: the failure point and WHY the approach fails (\"this fails because \u2026\"). Do NOT prescribe a fix as fact. You MAY offer a hypothesis, but it must be explicitly marked as one (\"likely \u2026\", \"consider \u2026\") \u2014 never an imperative \"instead, do X\" or \"the correct fix is X\". A verified counterfactual is only available in contrastive mode.\n\nMODE = contrastive (the traces are BOTH a verified PASS and a confirmed FAIL of the SAME problem):\n- The delta between the pass and the fail is the signal \u2014 extract the causal decision that separates success from failure (what the passing attempt did that the failing one did not). Here the counterfactual IS verified (the pass really worked), so you MAY state it as fact.\n\nEvery skill (all modes):\n- Produce a name (lowercase-hyphen), a description, and a markdown body.\n- The description is the retrieval surface and MUST carry BOTH a trigger and an anti-trigger: \"Use when \u2026 Not for: \u2026\". The anti-trigger names the nearby-but-situationally-wrong case the skill must NOT fire on. For a failure-lesson the trigger is the RISKY situation and the anti-trigger the safe lookalike.\n- The body MUST use EXACTLY these five sections, each non-empty, in this order:\n  ## When to use\n  ## Strategy\n  ## Steps\n  ## Pitfalls\n  ## Verify\n- Generalize: name the transferable rule, not the instance. Do NOT copy verbatim diff hunks, file paths, symbol names, instance ids, or PR numbers \u2014 those are contamination and are rejected downstream.\n- Never include secrets, keys, tokens, or credentials. A skill has no legitimate need to carry raw key material.\n- Use placeholder paths (/path/to/project) and invented example identifiers. Never real home directories (/Users/<name>, /home/<name>), real email addresses, or machine-specific paths \u2014 the output scrub redacts those shapes, and ANY redaction drops the whole skill (fail-closed), deterministically, on every retry.\n- Be concise. A skill that restates the raw trace has not earned its place over just retrieving the trace.";
+export declare const JINN_SKILL_DISTILL_PROMPT_V1_SHA256 = "44bf8cad03c6d3c17dd726e0f0b9a3375703028bc4be08d15804442626c6c195";
+/**
+ * `jinn-skill-meta-distill-prompt-v1` — the stage-2 cross-instance meta-distill
+ * prompt (issue #1463). Input is a BATCH of stage-1 skills that already share a
+ * polarity (all strategic-pattern, all failure-lesson, or all contrastive),
+ * each labelled with an opaque source id (s1, s2, …). The task is to find the
+ * ONE rule that recurs across the batch and is corroborated by AT LEAST TWO
+ * DISTINCT instances, and to name which sources corroborate it.
+ *
+ * Like the v1 distill prompt, this is a foundation reference, not protocol
+ * canon; its SHA-256 is published on every meta-distilled skill
+ * (`metadata.jinn.distillPromptSha256`).
+ */
+export declare const JINN_SKILL_META_DISTILL_PROMPT_V1 = "You distil a BATCH of already-distilled Agent-Skills into ONE higher-order cross-instance Agent-Skill (a SKILL.md package).\n\nInput: a batch of skills, each labelled with an opaque source id (s1, s2, \u2026). Every skill in the batch shares a POLARITY (given below), and each came from a DIFFERENT coding sub-problem instance.\n\nMODE = cross-instance:\n- Find the ONE recurring rule that generalises across the batch \u2014 the pattern, lesson, or delta that shows up in two or more of the sources for DIFFERENT instances. A rule that appears in only a single source is NOT cross-instance evidence and must not be emitted.\n- Corroboration is the signal: emit a skill only for a rule that at least two DISTINCT sources support. List those source ids in \"supports\".\n\nPOLARITY = strategic-pattern: the sources are recurring success strategies \u2014 extract the shared generalizable behavior.\nPOLARITY = failure-lesson: the sources are recurring failure diagnoses. State the shared DIAGNOSIS (\"this class of approach fails because \u2026\"). Do NOT prescribe a fix as fact \u2014 no imperative \"instead, do X\" or \"the correct fix is X\"; a hypothesis MUST be marked as one (\"likely \u2026\", \"consider \u2026\"). A verified counterfactual is only available in contrastive polarity.\nPOLARITY = contrastive: the sources are recurring pass\u2194fail deltas \u2014 extract the shared causal decision that separates success from failure; here the counterfactual IS verified, so you MAY state it as fact.\n\nEvery skill:\n- Produce a name (lowercase-hyphen), a description, a markdown body, and a \"supports\" list of the source ids that corroborate the rule.\n- The description is the retrieval surface and MUST carry BOTH a trigger and an anti-trigger: \"Use when \u2026 Not for: \u2026\".\n- The body MUST use EXACTLY these five sections, each non-empty, in this order:\n  ## When to use\n  ## Strategy\n  ## Steps\n  ## Pitfalls\n  ## Verify\n- Generalize: name the transferable rule, not any single instance. Do NOT copy verbatim diff hunks, file paths, symbol names, instance ids, or PR numbers \u2014 those are contamination and are rejected downstream.\n- Never include secrets, keys, tokens, or credentials. Use placeholder paths (/path/to/project) and invented example identifiers; never real home directories, emails, or machine-specific paths \u2014 the output scrub drops the whole skill (fail-closed) on any redaction.\n- Be concise. A cross-instance skill that merely concatenates its sources has not earned its place.";
+export declare const JINN_SKILL_META_DISTILL_PROMPT_V1_SHA256 = "6d21ed583cb8f3f3f92449c6b67a247be287a767517a9f83ec891e7f737b388b";