@method-ai-hq/sdk 0.19.0 → 0.20.0

package/dist/packages/sdk/src/improve.d.ts

@@ -1,4 +1,5 @@
 import type { MethodClient } from './method-client.js';
+import type { CorrectionOutcome } from './fix-lines.js';
 /** A judgment as improve.method reads it. new marks the corrections to fix now; run is the account record of a run with no folder here. */
 export type ImproveJudgment = {
     id: string;
@@ -13,13 +14,12 @@ export type ImproveJudgment = {
     created_at: string;
     new?: boolean;
     run?: unknown;
+    noted_by?: string | null;
+    /** The question that an earlier fix asked about this correction, and the person's answer. */
+    question?: string;
+    answer?: string;
 };
-/** What the loop did with one correction, as the account records it. */
-export type CorrectionOutcome = {
-    id: string;
-    outcome: 'fixed' | 'no_change' | 'already_changed' | 'held';
-    detail?: string;
-};
+export type { CorrectionOutcome };
 /** Runs a local Method file; the default is the runtime that `method run FILE` uses. */
 export type RunFile = (file: string, flags: Record<string, unknown>, syncFactory: undefined, onEvent: undefined, client: MethodClient, baseConfig: undefined, secrets: Record<string, string>) => Promise<{
     status: string;
@@ -41,13 +41,17 @@ export type ImproveProposal = {
         [key: string]: unknown;
     };
 };
+export type ImproveResult = ImproveProposal & {
+    capped: string;
+    outcomes: CorrectionOutcome[];
+    background_cases: string[];
+    summary: string;
+};
 export type FixOutcome = {
     file: string;
     judgments: string[];
-    corrections: number;
-    from_dashboard: number;
     kind: 'change' | 'none';
-    line: string;
+    applied: boolean;
     cause: string;
     steps: string[];
     cases: {
@@ -57,11 +61,9 @@ export type FixOutcome = {
             reason: string;
         }[];
     };
-    earlier_passed: number;
     version?: {
         version_id: string;
         url: string;
-        undo: string;
     } | undefined;
     usage: {
         model_calls: number;
@@ -70,16 +72,31 @@ export type FixOutcome = {
     } | null;
     capped: string;
     log: string;
-    changed?: string;
-    outcomes?: CorrectionOutcome[];
+    outcomes: CorrectionOutcome[];
+    /** The cases that run after an applied change, and the undo record of that change. */
+    background_cases: string[];
+    undo_id?: string | undefined;
+    /** The corrections that the applied change answered, with their notes. */
+    fixed: {
+        id: string;
+        note: string | null;
+    }[];
 };
 /**
- * Read the result of improve.method: {proposal: <SubmitProposal as JSON text>, kind, proposal_id, capped}. A change has
- * the tested workflow (and a changed package file for a script change); none has no workflow.
+ * One outcome of improve.method in the form the lines read: {id, outcome, detail, reason?, question?, held_with?,
+ * learned_rule?, again?, tests?: {case, base, candidate: {passes, runs}, guards: []}, tried?}. A fixed outcome's detail
+ * says what is different now; a held outcome's detail is about the loop, so the line names only the other person.
  */
-export declare function readImproveResult(result: unknown): ImproveProposal & {
-    capped: string;
-};
+export declare function loopOutcome(o: any): CorrectionOutcome;
+/**
+ * Read the result of improve.method: {proposal: <SubmitProposal as JSON text>, kind, proposal_id, outcomes: <JSON text,
+ * one outcome per new correction>, background_cases: [case ids], summary: one plain line}. A change has the tested
+ * workflow and the changed package files (a script, learned.json). A pruning sweep (mode prune) has no outcomes; its
+ * summary says what it removed, and what it left because nothing checks it.
+ */
+export declare function readImproveResult(result: unknown, options?: {
+    prune?: boolean;
+}): ImproveResult;
 /**
  * Download the published improve.method and its files into the Method cache, once per version. For developers of
  * improve.method: METHOD_IMPROVE_METHOD=PATH runs that local improve.method file instead, from its own folder.
@@ -90,13 +107,12 @@ export declare function cachedImproveMethod(client: MethodClient): Promise<{
     version_id: string;
 }>;
 /**
- * Run improve.method on this computer. Its model steps and its scripts' model requests follow the rule of every run:
+ * Run improve.method on this computer (mode prune: the pruning pass). Its model steps and its scripts' model requests follow the rule of every run:
  * the user's own Claude Code or Codex first, hosted models only without one. The run gets the signed-in key and server
  * as its IMPROVE_API_KEY and IMPROVE_SERVER secrets, for this run only. Its output goes to a log file.
  */
-export declare function runImprovement(client: MethodClient, file: string, judgments: ImproveJudgment[], runFolders: string[], run?: RunFile): Promise<{
+export declare function runImprovement(client: MethodClient, file: string, judgments: ImproveJudgment[], runFolders: string[], run?: RunFile, mode?: 'prune'): Promise<{
     log: string;
-    summary: any;
     cause: string;
     workflow: unknown | null;
     files: {
@@ -110,48 +126,129 @@ export declare function runImprovement(client: MethodClient, file: string, judgm
         [key: string]: unknown;
     };
     capped: string;
+    outcomes: CorrectionOutcome[];
+    background_cases: string[];
+    summary: string;
 }>;
 /** The ID of the regression case that a correction makes: one per judgment, so a later loop finds it. */
 export declare const correctionCaseId: (judgmentId: string) => string;
+/** One thing that the person saw: the result, a step output, a file the run wrote, or a call or effect it made. */
+type Seen = {
+    ref: string;
+    label: string;
+    value: unknown;
+};
+/** What the person saw of a run, with the ref that a case uses for each thing (runtime 0.16.0 refs). */
+export declare function seenOfRun(outcome: any): Seen[];
 /**
- * Make the regression case of a correction, even from vague words such as "it's not even redlined": a model writes 1 to
- * 3 plain sentences from the note and the run's result, and method case new keeps them only when they fail on the run.
- * A rule that fails nothing gets one more try with the reason. The person's words decide a conflict with an instruction.
+ * Make the regression case of a correction, even from vague words such as "it's not even redlined". A model reads what
+ * the person saw (the result, the files the run wrote, and the calls and effects it made) and writes 1 to 3 plain
+ * sentences, each about one of those things; for a note about form or a missing action, also a small check script. A
+ * sentence is kept only when it fails on the corrected run and passes on every approved run of the same part, with two
+ * judges when both Claude Code and Codex are signed in. Sentences that do not fail get one more try with the reason.
  */
 export declare function caseFromCorrection(file: string, judgment: {
     id: string;
     note: string | null;
     corrected?: unknown;
     noted_by?: string | null;
-}, runDir: string): Promise<{
+    answer?: string | null;
+}, runDir: string, options?: {
+    approvedRuns?: string[];
+}): Promise<{
     id: string;
     made: boolean;
 }>;
+/** The corrections of a Method that wait for a fix. */
+export declare function waitingCorrections(client: MethodClient, file: string, methodId: string, waitMs?: number): Promise<{
+    note: string | null;
+    corrected: {} | null;
+    answer: string | null;
+    run_dir: string | undefined;
+    id: string;
+    run_id: string;
+    step_id: string | null;
+    verdict: "right" | "wrong";
+    source: string;
+    created_at: string;
+    pending: boolean;
+    noted_by?: string | null;
+    outcome?: string | null;
+    handled_by?: string | null;
+    held_with?: string | null;
+    question?: string | null;
+}[]>;
 /**
- * Fix the pending corrections of a Method file on this computer: the loop. Returns undefined when nothing waits. It
- * takes the pending corrections in the account first, so two computers never fix one correction twice, and gives them
- * back when the loop stops before it decides. A subscription limit or another failure of the model service is a plain
- * error.
+ * Fix the pending corrections of a Method file on this computer: one pass of the loop. Returns undefined when nothing
+ * waits. It takes the pending corrections in the account first, so two computers never fix one correction twice, and
+ * gives them back when the loop stops before it decides. Each correction gets its own outcome. A subscription limit or
+ * another failure of the model service is a plain error.
  */
 export declare function fixCorrections(client: MethodClient, file: string, options?: {
     run?: RunFile;
     waitMs?: number;
+    skip?: Set<string>;
 }): Promise<FixOutcome | undefined>;
+/** Whether a fix of the Method runs on this computer now. */
+export declare function fixRunning(methodId: string): boolean;
 /**
  * Fix the waiting corrections of a Method file while holding its lock, pass after pass until none waits, so the
- * corrections that arrive during a pass join the next. Returns undefined when another fix of the Method holds the lock.
+ * corrections that arrive during a pass join the next. Each correction's outcome is saved for method wait. After a pass
+ * that changed the file, the other cases run (improve.method's background_cases): a failure undoes that change. Then a
+ * pruning pass runs when it is due. Returns undefined when another fix of the Method holds the lock.
  */
 export declare function fixWaiting(client: MethodClient, file: string, options?: {
     run?: RunFile;
     waitMs?: number;
+    runCases?: RunCases;
 }): Promise<FixOutcome[] | undefined>;
+/** Runs cases of a Method file (quality.ts runCases); tests replace it. */
+export type RunCases = (file: string, flags: Record<string, never>, options: {
+    ids: string[];
+}) => Promise<{
+    cases: {
+        id: string;
+        verdict: string;
+    }[];
+}>;
+/**
+ * The later check of an applied change: the Method's other cases (improve.method's background_cases) run on the changed
+ * file. A failing case that belongs to a retired learned rule (its from.case) brings that rule back. Any other failure
+ * undoes the change, saves the restored file as a new version, and opens the corrections it answered again, so the next
+ * method run fixes them anew. Each of these says one line on the next method run or method wait.
+ */
+export declare function checkBackground(client: MethodClient, file: string, fix: Pick<FixOutcome, 'background_cases' | 'undo_id' | 'fixed' | 'cause'>, options?: {
+    runCases?: RunCases;
+}): Promise<{
+    failed: string[];
+    restored: string[];
+    undone: boolean;
+    reopened: string[];
+}>;
+/**
+ * The pruning pass (improve.method with mode prune): it retires learned rules and deletes prompt text that tests show
+ * no longer change any result, and reports text that no test covers without deleting it. The change applies at once,
+ * with undo; the next method run or method wait shows the sweep's summary line.
+ */
+export declare function pruneMethod(client: MethodClient, file: string, options?: {
+    run?: RunFile;
+}): Promise<{
+    changed: boolean;
+} | undefined>;
 /**
  * Fix the Method for one correction: run the fix, or, when a fix of the Method already runs on this computer, wait for
- * the fix that takes this correction. Returns the outcome of the fix that took it, or undefined when no fix here took it.
+ * the fix that takes this correction. Returns the stored outcome, or undefined when no fix here took it.
  */
 export declare function fixCorrection(client: MethodClient, file: string, judgmentId: string, options?: {
     run?: RunFile;
     pollMs?: number;
-}): Promise<FixOutcome | undefined>;
-/** The one line for corrections that waited, printed before method run or method judge goes on. */
-export declare function waitingLine(outcome: FixOutcome): string;
+}): Promise<import("./fix-outcomes.js").StoredOutcome | undefined>;
+/**
+ * `method __fix FILE --judgment ID... [--prune]`: the fix of method judge, method answer and method run, in its own
+ * process. Every correction it was started for ends with a stored outcome or error.
+ */
+export declare function backgroundFix(client: MethodClient, file: string, ids: string[], options?: {
+    run?: RunFile;
+    prune?: boolean;
+    pollMs?: number;
+}): Promise<void>;