wicked-crew 0.16.11 → 0.16.13

package/dist/learnings/service.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Run learnings, part 2: from a run's record to the approve queue (the operator's 2026-10-30 ask).
+ *
+ *  - At the run's CHECKPOINTS (a power checkpoint, a unit done, a gate decided) the template
+ *    learnings found so far ({@link extractLearnings}: a flaky test, a check the sandbox could not
+ *    start) are filed at once.
+ *  - At the run's END the rest of the evidence (rulings, steers, decisions, review findings, base-red
+ *    checks) goes to ONE cheap seat that did not build the run: a `distill-learnings` run, one seat,
+ *    one turn, no repository. Crew files what it writes. When no such seat can run (none signed in,
+ *    the launch refused, it wrote nothing usable), the evidence is filed raw, trimmed and capped.
+ *  - The distil run is never a person's to answer (wicked-crew#1251 follow-up: a codex distil that
+ *    rightly found nothing replied in under 200 characters, failed the engine's substance floor and
+ *    sat in the operator's queue as "Waiting on you"). Its outcome is its report file, read here, so
+ *    whatever gate it stops at (a short reply, a crashed seat), crew stops the run and files from
+ *    the report: an empty one is recorded as "none found", a missing one files the evidence raw.
+ *
+ * Everything filed is a PROPOSAL of kind `memory` in estate's queue, attributed to the SOURCE run
+ * (`provenance.run_id`), faceted by repo, project and seat. Nothing is written without a person's
+ * approval. The same evidence is never proposed twice: a candidate whose text is already in the queue
+ * (pending or approved) or in the memory store is skipped, whichever run filed it.
+ *
+ * Never throws into the event pump: every failure is logged and the run is left as it was.
+ */
+import type { SessionView } from 'wicked-crew-api-types';
+import type { LaunchRunInput, WorkflowDef } from '../core/types.js';
+import type { LooseEvent } from '../insights/run-facts.js';
+import { type LearningKind } from './extract.js';
+export declare const DISTILL_WORKFLOW = "distill-learnings";
+export declare const DISTILL_WORKFLOW_FILE: string;
+export declare const HANDOFF_FILE = "handoff.json";
+export declare const OUT_DIR = "out";
+export declare const REPORT_FILE = "report.json";
+/** Written once a source run's learnings were filed at its end: a resume's second terminal frame files nothing. */
+export declare const FILED_FILE = "filed.json";
+/** The distil run launched for a source run (its id and seat). */
+export declare const DISTILL_FILE = "distill.json";
+/** The agent named on a learning crew worded itself (a template, or raw evidence). */
+export declare const CREW_AGENT = "crew";
+/** The most learnings one run proposes from its end (the distil seat's, or the raw fallback). */
+export declare const MAX_END_LEARNINGS = 5;
+/** The shortest learning worth a person's time (estate refuses shorter bodies too). */
+export declare const MIN_LEARNING_CHARS = 40;
+export declare const MAX_LEARNING_CHARS = 1500;
+/** Runs whose own record is not a source of learnings: they capture, review or set up. */
+export declare const NO_LEARNINGS_WORKFLOWS: ReadonlySet<string>;
+export type RunLearningsMode = 'off' | 'extract' | 'distill';
+/** `WICKED_CREW_RUN_LEARNINGS`: `off`, `extract` (no distil seat), `distill` (the default). A test process
+ *  (vitest, NODE_ENV=test) defaults to `off`, so a headless server never spawns estate on a stub run's frames. */
+export declare function runLearningsMode(env?: NodeJS.ProcessEnv): RunLearningsMode;
+/** Where each source run's distil handoff lives: outside the daemon state home (the worker fence), like reviews. */
+export declare function defaultLearningsDir(env?: NodeJS.ProcessEnv): string;
+export declare function loadDistillWorkflow(file?: string): WorkflowDef;
+/** One row of estate's `proposal.list`, read loosely. */
+export interface ProposalRow {
+    id: string;
+    kind_type: string;
+    state: string;
+    created_at?: number;
+    payload: Record<string, unknown>;
+    facets: Record<string, unknown>;
+    provenance: Record<string, unknown>;
+}
+/** What `GET /runs/:id/learnings` answers. */
+export interface RunLearningsView {
+    runId: string;
+    proposed: number;
+    pending: number;
+    approved: number;
+    rejected: number;
+    /** A distil seat is still reading this run's evidence. */
+    distilling: boolean;
+    items: Array<{
+        id: string;
+        state: string;
+        capture: string | null;
+        content: string;
+        agent: string | null;
+        createdAt: number | null;
+    }>;
+}
+export interface SubmitArgs {
+    kind_type: 'memory';
+    payload: Record<string, unknown>;
+    facets: Record<string, string>;
+}
+export interface RunLearningsDeps {
+    adapter: {
+        sessionsDetail(): Promise<SessionView[]>;
+        runEvents(runId: string): Promise<LooseEvent[] | null>;
+        seatsForWorkflow(workflowId: string): Promise<unknown[]>;
+        launchRun(input: LaunchRunInput): Promise<string>;
+        /** Stop a run (a distil run that parked at a gate: its outcome is read from its report, never asked of a person). */
+        cancelRun(runId: string): Promise<unknown>;
+    };
+    /** File one proposal attributed to `runId` (its provenance), as `agent`. Returns the proposal id. */
+    submit(runId: string, agent: string, args: SubmitArgs): Promise<string | null>;
+    /** Every proposal in the queue, any state. */
+    listProposals(): Promise<ProposalRow[]>;
+    /** The text of every memory in the store (the dedupe set). */
+    listMemoryContents(): Promise<string[]>;
+    /** The launch bookkeeping a chained run gets (launch entry, project filing, `runChained` frame). */
+    launched?(distillRunId: string, sourceRunId: string, projectId: string | null): void;
+    learningsDir: string;
+    mode: RunLearningsMode;
+    log: (msg: string) => void;
+    newRunId: () => string;
+}
+/** The proposals one run filed (provenance), as the run's end card and the queue's filter read them. */
+export declare function learningsOfRun(runId: string, rows: readonly ProposalRow[]): RunLearningsView['items'];
+/** How many distinct evidence items the distil seat accounted for (`checked[]`, kept or dropped with a reason). */
+export declare function checkedCount(raw: unknown, evidenceIds?: ReadonlySet<string>): number;
+/**
+ * A distil report's learnings, validated: known kind, sane length, at most {@link MAX_END_LEARNINGS}. `null` when
+ * there is no usable report: none, malformed, or entries none of which survive validation. An explicitly EMPTY list is
+ * the seat's judgment (nothing durable) and is kept as `[]`.
+ */
+export declare function parseDistillReport(raw: unknown): Array<{
+    kind: LearningKind;
+    content: string;
+}> | null;
+export declare class RunLearningsService {
+    private readonly deps;
+    /**
+     * Every sweep and reconcile runs on ONE daemon-wide queue: the dedupe read and the submits that follow it are
+     * atomic across runs (two runs that hit the same flaky test propose it once), and a run's end, its distil report
+     * and a resume's second terminal frame never interleave. A task already queued and not yet started is not queued
+     * twice.
+     */
+    private tail;
+    private readonly queued;
+    /** distil run id → its source run (rebuilt from disk after a restart). */
+    private readonly distills;
+    private distillsLoaded;
+    constructor(deps: RunLearningsDeps);
+    private dirOf;
+    private enqueue;
+    /** Fold one engine frame. Never throws. */
+    onEvent(event: {
+        type: string;
+        session?: unknown;
+    }): void;
+    /** Read the run's record and file what is new (a test's direct entry; frames go through {@link onEvent}). */
+    sweep(runId: string, phase: 'checkpoint' | 'end'): Promise<void>;
+    private onEnd;
+    /**
+     * After a restart: finish every run whose end was interrupted. A handoff with no distil run (the daemon stopped
+     * before the launch) is ended again; a distil run that ended while the daemon was down is reconciled; one the
+     * daemon no longer knows is filed raw. Never throws.
+     */
+    recover(): Promise<void>;
+    private viewOf;
+    private sweepOnce;
+    /** The distil run recorded for a source run, if one was launched. */
+    private distillOf;
+    /** The normalized text of every proposal in the queue (a person's rejection is not proposed again) and every stored memory. */
+    private knownTexts;
+    private file;
+    /** No distil seat: the evidence as it is, trimmed and capped, for a person to edit or reject. */
+    /** `failedBefore`: submits of this end that already failed. The run is marked filed only when none did, so a
+     *  failed submit is retried on the next recovery (the dedupe keeps what landed from landing twice). */
+    private fileRaw;
+    private markFiled;
+    /** A seat that did not build this run, signed in and eligible; `null` when there is none. */
+    private distillSeat;
+    /** Launch the distil run. `null` when it could not be launched (the caller files the evidence raw). */
+    private launchDistill;
+    /** After a restart: which distil run belongs to which source run, from the handoff directories. */
+    private loadDistills;
+    /** The evidence ids the distil seat was handed (`e1`…), as crew wrote them. */
+    private handoffEvidenceIds;
+    private readJson;
+    /**
+     * A distil run stopped at a gate. It is never a person's to answer: crew stops it and files from its report (the
+     * seat's judgment, even when it is "none found"), or files the evidence raw when the seat wrote nothing usable.
+     * Only a live frame does this; a distil already parked when the daemon starts is left as it is.
+     */
+    private stopParkedDistill;
+    /** A distil run ended: file what it wrote under the source run, or the raw evidence when it wrote nothing usable. */
+    reconcileDistill(distillRunId: string, sourceRunId: string): Promise<void>;
+    /** The run's end card: what it proposed, and whether a distil seat is still at it. */
+    view(runId: string): Promise<RunLearningsView>;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/learnings/service.d.ts.map

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