@method-ai-hq/sdk 0.18.2 → 0.20.0

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

@@ -1,5 +1,4 @@
 import { type MethodClient } from './method-client.js';
-import { type RunFile } from './improve.js';
 export declare const maxNoteLength = 4000;
 export declare const maxCorrectedBytes: number;
 export type Judgment = {
@@ -12,17 +11,31 @@ export type Judgment = {
 };
 /** The corrected result in a file: its JSON value when it parses as JSON, or else its text. */
 export declare function correctedValue(path: string): unknown;
-/** The line that says what was recorded. */
-export declare function judgmentLine(judgment: Pick<Judgment, 'verdict' | 'step_id'>): string;
 /**
  * `method judge RUN_ID right|wrong [--step ID] [--note TEXT] [--corrected FILE] [--json]`: record the person's reaction
  * to a run's result. RUN_ID is the dashboard run ID or this computer's run ID; the server resolves both. When the run's
  * content stays on this computer (run_data: device), the account gets the verdict and step only, and the judgment with
- * its note and corrected result goes in .method/judgments.jsonl next to the Method file. A wrong judgment then fixes the
- * Method here, in the foreground: method judge makes a regression case from the note, finds a change with the user's
- * own Claude Code or Codex, and applies it only when it fixes the run and breaks no earlier correction. It prints one
- * line: what changed, or why nothing did.
+ * its note and corrected result goes in .method/judgments.jsonl next to the Method file. A wrong judgment then starts
+ * the fix on this computer in its own process and returns at once with one line; method wait prints what the fix did,
+ * and so does the next method run of the Method.
  */
-export declare function judgeCommand(args: string[], clientFactory: (server: string) => MethodClient, options?: {
-    run?: RunFile;
-}): Promise<void>;
+export declare function judgeCommand(args: string[], clientFactory: (server: string) => MethodClient): Promise<void>;
+/** The run's Method file fixes the correction: the file that ran the run, else the Method's home file on this computer. */
+export declare function fileForJudgment(server: string, judgment: Pick<Judgment, 'method_id'>, runFile: string | undefined): string | undefined;
+/** Two judgments of the same run and step by two people with opposite verdicts: neither is fixed until one is kept. */
+export type HeldPair = {
+    run_id: string;
+    step_id: string | null;
+    judgments: Array<{
+        id: string;
+        verdict: string;
+        noted_by: string | null;
+        note: string | null;
+    }>;
+};
+/**
+ * `method answer JUDGMENT_ID "THEIR WORDS"`: send the person's answer to the question that a fix asked, and start the
+ * fix again with it. For a Method whose run content stays on this computer, the account keeps no answer, so the words
+ * also stay next to the Method file.
+ */
+export declare function answerJudgmentCommand(args: string[], clientFactory: (server: string) => MethodClient): Promise<void>;

package/dist/packages/sdk/src/judge.js

@@ -3,8 +3,11 @@ import { basename } from 'node:path';
 import { parseArgs } from 'node:util';
 import { DEFAULT_SERVER } from './method-client.js';
 import { deviceRun, findRunFolder, methodFileOfRun, saveLocalJudgment } from './local-judgments.js';
-import { fixCorrections, waitingLine } from './improve.js';
-import { readHome } from './home.js';
+import { catchUp, readHome } from './home.js';
+import { readDocument } from './authoring.js';
+import { localJudgments } from './local-judgments.js';
+import { fixStarter, markWorking, saveError, storedOutcomes } from './fix-outcomes.js';
+import { approvedLine, heldPairLine, notHereLine, workingAnswerLine, workingLine } from './fix-lines.js';
 export const maxNoteLength = 4000;
 export const maxCorrectedBytes = 1024 * 1024;
 /** The corrected result in a file: its JSON value when it parses as JSON, or else its text. */
@@ -26,25 +29,22 @@ export function correctedValue(path) {
         return text;
     }
 }
-/** The line that says what was recorded. */
-export function judgmentLine(judgment) {
-    return `Recorded: ${judgment.verdict}${judgment.step_id ? ` on step ${judgment.step_id}` : ''}.`;
-}
 /**
  * `method judge RUN_ID right|wrong [--step ID] [--note TEXT] [--corrected FILE] [--json]`: record the person's reaction
  * to a run's result. RUN_ID is the dashboard run ID or this computer's run ID; the server resolves both. When the run's
  * content stays on this computer (run_data: device), the account gets the verdict and step only, and the judgment with
- * its note and corrected result goes in .method/judgments.jsonl next to the Method file. A wrong judgment then fixes the
- * Method here, in the foreground: method judge makes a regression case from the note, finds a change with the user's
- * own Claude Code or Codex, and applies it only when it fixes the run and breaks no earlier correction. It prints one
- * line: what changed, or why nothing did.
+ * its note and corrected result goes in .method/judgments.jsonl next to the Method file. A wrong judgment then starts
+ * the fix on this computer in its own process and returns at once with one line; method wait prints what the fix did,
+ * and so does the next method run of the Method.
  */
-export async function judgeCommand(args, clientFactory, options = {}) {
-    const usage = 'Use method judge RUN_ID right|wrong [--step STEP_ID] [--note TEXT] [--corrected FILE].';
+export async function judgeCommand(args, clientFactory) {
+    const usage = 'Use method judge RUN_ID right|wrong [--step STEP_ID] [--note TEXT] [--corrected FILE], or method judge RUN_ID keep JUDGMENT_ID.';
     const { values, positionals } = parseArgs({ args, allowPositionals: true, options: {
             step: { type: 'string' }, note: { type: 'string' }, corrected: { type: 'string' }, json: { type: 'boolean' }, server: { type: 'string' }
         } });
     const [runId, verdict] = positionals;
+    if (runId && verdict === 'keep' && positionals.length === 3)
+        return keepCommand(runId, positionals[2], values, clientFactory);
     if (!runId || !verdict || positionals.length !== 2)
         throw Error(usage);
     if (verdict !== 'right' && verdict !== 'wrong')
@@ -72,24 +72,108 @@ export async function judgeCommand(args, clientFactory, options = {}) {
             id: response.judgment.id, run_id: runId, account_run_id: response.judgment.run_id ?? null, run_dir: runDir, method_id: response.judgment.method_id ?? null,
             file: basename(runFile), step_id: step ?? null, verdict, note: note ?? null, ...(corrected !== undefined ? { corrected } : {}), created_at: response.judgment.created_at,
         });
-    const recorded = judgmentLine(response.judgment);
-    if (verdict === 'right') {
-        process.stdout.write(values.json ? JSON.stringify({ judgment: response.judgment }, null, 2) + '\n' : recorded + '\n');
+    // A judgment that contradicts another person's judgment of the same step is held: show both, with the two choices.
+    const pairs = response.held ? await heldPairs(client, response.judgment.method_id, response.judgment.id) : [];
+    if (verdict === 'right' || response.held) {
+        print(values.json ? { judgment: response.judgment, ...(pairs.length ? { held: pairs } : {}) } : [verdict === 'right' && !response.held ? approvedLine : 'Noted.', ...pairs.flatMap(heldLines)]);
         return;
     }
-    // The Method file: the one that ran the run, else the Method's home file on this computer.
-    const home = response.judgment.method_id ? readHome(client.server, response.judgment.method_id)?.path : undefined;
-    const file = runFile ?? (home && existsSync(home) ? home : undefined);
-    if (!file) {
-        const line = `${recorded} The Method file is not on this computer, so the next method run of it on a computer fixes it.`;
-        process.stdout.write(values.json ? JSON.stringify({ judgment: response.judgment, fix: null }, null, 2) + '\n' : line + '\n');
+    return startFix(client, response.judgment, runFile, values);
+}
+const print = (value) => process.stdout.write(Array.isArray(value) ? value.join('\n') + '\n' : JSON.stringify(value, null, 2) + '\n');
+/** The run's Method file fixes the correction: the file that ran the run, else the Method's home file on this computer. */
+export function fileForJudgment(server, judgment, runFile) {
+    const home = judgment.method_id ? readHome(server, judgment.method_id)?.path : undefined;
+    return runFile ?? (home && existsSync(home) ? home : undefined);
+}
+/** Start the fix of a correction in its own process and return: method wait gives its outcome. */
+async function startFix(client, judgment, runFile, values, line = workingLine) {
+    const file = fileForJudgment(client.server, judgment, runFile);
+    if (!file || !judgment.method_id) {
+        print(values.json ? { judgment, fix: null } : [notHereLine]);
         return;
     }
-    const fix = await fixCorrections(client, file, options);
-    if (values.json) {
-        process.stdout.write(JSON.stringify({ judgment: response.judgment, fix: fix ?? null }, null, 2) + '\n');
+    // The fix starts from the newest version; a teammate's change of the same step stops it until the person combines them.
+    const caught = await catchUp(client, file, 'fixing');
+    if (caught.status === 'conflict') {
+        print(values.json ? { judgment, fix: null, stopped: caught.result } : [caught.result.failure.headline]);
+        process.exitCode = 2;
         return;
     }
-    const line = !fix ? `${recorded} Another loop is fixing it.` : fix.corrections > 1 ? `${recorded} ${waitingLine(fix)}` : `${recorded} ${fix.line}`;
-    process.stdout.write(line + '\n');
+    if ('line' in caught)
+        process.stderr.write(caught.line + '\n');
+    markWorking(judgment.method_id, file, [judgment.id]);
+    try {
+        await fixStarter.start(file, judgment.method_id, [judgment.id], client.server);
+    }
+    catch (error) {
+        saveError(judgment.method_id, file, judgment.id, error.message);
+        throw error;
+    }
+    print(values.json ? { judgment, fix: { status: 'working', wait: `method wait ${judgment.id}` } } : [line]);
+}
+/** The held pairs of a Method, from its judgments in the account. Nothing when they cannot be read. */
+async function heldPairs(client, methodId, mine) {
+    if (!methodId)
+        return [];
+    let judgments;
+    try {
+        judgments = (await client.request(`/api/cli/methods/${encodeURIComponent(methodId)}/judgments`)).judgments ?? [];
+    }
+    catch {
+        return [];
+    }
+    const byId = new Map(judgments.map(j => [j.id, j])), pairs = [], seen = new Set();
+    for (const j of judgments) {
+        const other = j.outcome === 'held' && j.held_with ? byId.get(j.held_with) : undefined;
+        if (!other || seen.has(j.id) || seen.has(other.id))
+            continue;
+        seen.add(j.id);
+        seen.add(other.id);
+        const [first, second] = mine === other.id ? [other, j] : [j, other];
+        pairs.push({ run_id: j.run_id, step_id: j.step_id ?? null, judgments: [first, second].map(x => ({ id: x.id, verdict: x.verdict, noted_by: x.noted_by ?? null, note: x.note ?? null })) });
+    }
+    return pairs;
+}
+/** The person's line of a held pair, then the agent's line with the two commands. */
+const heldLines = (pair) => [heldPairLine(pair.judgments),
+    `Ask the person which one is right, then keep it: ${pair.judgments.map(j => `method judge ${pair.run_id} keep ${j.id} (${j.noted_by ?? 'this one'}'s)`).join(' or ')}.`];
+/** `method judge RUN keep JUDGMENT_ID`: keep this judgment of a held pair; the other one is set aside. A kept wrong judgment is fixed. */
+async function keepCommand(runId, judgmentId, values, clientFactory) {
+    const client = clientFactory(values.server ?? DEFAULT_SERVER);
+    const response = await client.request(`/api/judgments/${encodeURIComponent(judgmentId)}/settle`, 'POST', { keep: true });
+    const kept = response.judgment;
+    const recorded = `Kept ${kept?.noted_by ? `${kept.noted_by}'s view` : 'this view'}: the result is ${kept?.verdict ?? 'as judged'}.`;
+    if (kept?.verdict !== 'wrong' || !kept.method_id) {
+        print(values.json ? { judgment: kept ?? { id: judgmentId } } : [recorded]);
+        return;
+    }
+    const runDir = findRunFolder(runId);
+    return startFix(client, kept, runDir ? methodFileOfRun(runDir) : undefined, values, `${recorded} ${workingLine}`);
+}
+/**
+ * `method answer JUDGMENT_ID "THEIR WORDS"`: send the person's answer to the question that a fix asked, and start the
+ * fix again with it. For a Method whose run content stays on this computer, the account keeps no answer, so the words
+ * also stay next to the Method file.
+ */
+export async function answerJudgmentCommand(args, clientFactory) {
+    const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { json: { type: 'boolean' }, server: { type: 'string' } } });
+    const [id, ...words] = positionals, answer = words.join(' ').trim();
+    if (!id || !answer)
+        throw Error('Use method answer JUDGMENT_ID "THE PERSON\'S WORDS".');
+    if (answer.length > maxNoteLength)
+        throw Error(`The answer has ${answer.length} characters; the most is ${maxNoteLength}.`);
+    const stored = storedOutcomes().find(r => r.judgment === id);
+    const file = stored && existsSync(stored.file) ? stored.file : undefined;
+    const device = !!file && readDocument(file).run_data === 'device';
+    const client = clientFactory(values.server ?? DEFAULT_SERVER);
+    // The account keeps no answer for a device Method; the words stay next to the Method file.
+    const response = await client.request(`/api/cli/judgments/${encodeURIComponent(id)}/answer`, 'POST', { answer });
+    const judgment = response.judgment ?? { id, method_id: stored?.method_id };
+    if (device && file) {
+        const before = localJudgments(file).filter(j => j.id === id).at(-1);
+        if (before)
+            saveLocalJudgment(file, { ...before, answer });
+    }
+    return startFix(client, { id, method_id: judgment.method_id ?? stored?.method_id ?? '' }, file, values, workingAnswerLine);
 }

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

@@ -0,0 +1,43 @@
+import { type MethodClient } from './method-client.js';
+export type LearnedRule = {
+    id: string;
+    when: string | null;
+    then: string;
+    by: string | null;
+    from: {
+        judgment?: string;
+        case?: string;
+    } | null;
+    status: 'active' | 'retired';
+    created: string;
+    retired_at: string | null;
+    retired_reason: string | null;
+    /** What the fix loop keeps about a rule: base_failures, base_runs, dormant, merged_from. */
+    meta?: {
+        base_failures?: number;
+        base_runs?: number;
+        dormant?: boolean;
+        merged_from?: string[];
+    };
+};
+export type Learned = {
+    format: 'method-learned/1';
+    steps: Record<string, LearnedRule[]>;
+};
+export declare const learnedFile: (file: string) => string;
+export declare function readLearned(file: string): Learned;
+/** The active rules of a Method in a stable order: by step, then by date. */
+export declare function activeRules(learned: Learned): {
+    step: string;
+    rule: LearnedRule;
+}[];
+/** How often each rule applied, from the learned.applied events of this Method's runs on this computer. */
+export declare function appliedCounts(file: string): Promise<Map<string, number>>;
+/** A rule in plain words: "When the client is Acme, accept five years." */
+export declare const ruleText: (rule: Pick<LearnedRule, "when" | "then">) => string;
+/**
+ * `method learned FILE [--remove NUMBER|ID] [--json]`: the rules the agent learned from corrections, in plain words,
+ * with who taught each one and how often it applied. --remove retires one rule (by its number in the list or its ID);
+ * the change is saved as a new version, and method undo brings it back.
+ */
+export declare function learnedCommand(args: string[], clientFactory: (server: string) => MethodClient): Promise<void>;

package/dist/packages/sdk/src/learned.js

@@ -0,0 +1,97 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { parseArgs } from 'node:util';
+import { authoringPath } from './authoring.js';
+import { DEFAULT_SERVER } from './method-client.js';
+import { recordChange, saveVersion, snapshot } from './undo.js';
+import { removedRuleLine } from './fix-lines.js';
+export const learnedFile = (file) => join(dirname(file), 'learned.json');
+export function readLearned(file) {
+    const path = learnedFile(file);
+    if (!existsSync(path))
+        return { format: 'method-learned/1', steps: {} };
+    const value = JSON.parse(readFileSync(path, 'utf8'));
+    if (value?.format !== 'method-learned/1' || typeof value.steps !== 'object')
+        throw Error(`${basename(path)} is not a learned rules file.`);
+    return value;
+}
+/** The active rules of a Method in a stable order: by step, then by date. */
+export function activeRules(learned) {
+    return Object.entries(learned.steps).flatMap(([step, rules]) => rules.filter(r => r.status === 'active').map(rule => ({ step, rule })))
+        .sort((a, b) => a.rule.created.localeCompare(b.rule.created));
+}
+/** How often each rule applied, from the learned.applied events of this Method's runs on this computer. */
+export async function appliedCounts(file) {
+    const { localRuns } = await import('./proposals.js');
+    const counts = new Map();
+    for (const run of await localRuns(file)) {
+        let text = '';
+        try {
+            text = readFileSync(join(run.dir, 'events.jsonl'), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const line of text.split('\n')) {
+            if (!line.includes('learned.applied'))
+                continue;
+            try {
+                const event = JSON.parse(line);
+                if (event.event === 'learned.applied')
+                    for (const id of event.applied ?? [])
+                        counts.set(id, (counts.get(id) ?? 0) + 1);
+            }
+            catch { /* a partial line */ }
+        }
+    }
+    return counts;
+}
+const day = (iso) => { const date = new Date(iso); return Number.isNaN(date.getTime()) ? '' : date.toLocaleDateString('en-GB', { day: 'numeric', month: 'short', timeZone: 'UTC' }); };
+/** A rule in plain words: "When the client is Acme, accept five years." */
+export const ruleText = (rule) => {
+    const then = rule.then.trim().replace(/[.\s]+$/, '');
+    // A condition reads as part of the sentence: "The email is in German." becomes "When the email is in German, ...".
+    const when = rule.when?.trim().replace(/^when\s+/i, '').replace(/[.,\s]+$/, '').replace(/^[A-Z](?=[a-z])/, c => c.toLowerCase());
+    return when ? `When ${when}, ${then.charAt(0).toLowerCase()}${then.slice(1)}.` : `${then}.`;
+};
+const usedText = (n) => n === 0 ? 'not used yet' : n === 1 ? 'used once' : `used ${n} times`;
+/**
+ * `method learned FILE [--remove NUMBER|ID] [--json]`: the rules the agent learned from corrections, in plain words,
+ * with who taught each one and how often it applied. --remove retires one rule (by its number in the list or its ID);
+ * the change is saved as a new version, and method undo brings it back.
+ */
+export async function learnedCommand(args, clientFactory) {
+    const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { remove: { type: 'string' }, json: { type: 'boolean' }, server: { type: 'string' } } });
+    if (positionals.length !== 1)
+        throw Error('Use method learned FILE [--remove NUMBER].');
+    const file = authoringPath(positionals[0]);
+    const learned = readLearned(file), rules = activeRules(learned);
+    if (values.remove !== undefined) {
+        const wanted = values.remove.trim(), index = /^\d+$/.test(wanted) ? Number(wanted) - 1 : rules.findIndex(r => r.rule.id === wanted);
+        const chosen = rules[index];
+        if (!chosen)
+            throw Error(`There is no learned rule ${wanted}. List them with method learned ${basename(file)}.`);
+        const client = clientFactory(values.server ?? DEFAULT_SERVER);
+        const { signedInName } = await import('./quality.js');
+        const name = await signedInName(client);
+        const before = snapshot(file, ['learned.json']);
+        Object.assign(chosen.rule, { status: 'retired', retired_at: new Date().toISOString(), retired_reason: `Removed by ${name ?? 'the person'}.` });
+        writeFileSync(learnedFile(file), JSON.stringify(learned, null, 2) + '\n');
+        const text = ruleText(chosen.rule);
+        recordChange(file, 'learned', `Removed the learned rule "${text}"`, `the rule "${text}" is back`, before);
+        await saveVersion(client, file, `Removed a learned rule: ${text}`.slice(0, 500));
+        process.stdout.write(values.json ? JSON.stringify({ removed: chosen.rule }, null, 2) + '\n' : removedRuleLine(text) + '\n');
+        return;
+    }
+    const counts = await appliedCounts(file);
+    if (values.json) {
+        process.stdout.write(JSON.stringify({ rules: rules.map(({ step, rule }) => ({ ...rule, step, applied: counts.get(rule.id) ?? 0, text: ruleText(rule) })) }, null, 2) + '\n');
+        return;
+    }
+    if (!rules.length) {
+        process.stdout.write('This agent has not learned any rules from corrections yet.\n');
+        return;
+    }
+    const lines = rules.map(({ rule }, i) => `${i + 1}. ${ruleText(rule)} (${[rule.by, day(rule.created)].filter(Boolean).join(', ')}${rule.by || day(rule.created) ? '; ' : ''}${usedText(counts.get(rule.id) ?? 0)})`);
+    process.stdout.write(['What this agent learned from corrections:', ...lines, `Remove one: method learned ${basename(file)} --remove NUMBER`].join('\n') + '\n');
+}

package/dist/packages/sdk/src/local-cli.js

@@ -33,8 +33,6 @@ export function parse(args) {
 export async function run(target, flags, syncFactory) {
     const path = isWorkflowLink(target) ? (await saveWorkflowLink(target, process.cwd())).path : resolve(target);
     (await import("./legacy.js")).convertLegacyOrThrow(path);
-    if (!syncFactory)
-        await (await import("./home.js")).followAccount(new MethodClient(flags.server), path);
     loadWorkflow(methodContent(readDocument(path)));
     const notice = await (await import("./quality.js")).casesNotice(path);
     if (notice)
@@ -51,8 +49,9 @@ export async function run(target, flags, syncFactory) {
         flags = await withInputsFrom(flags, flags["run-dir"], path, client);
     }
     const account = syncFactory ? undefined : await accountSync(path, flags);
+    let result;
     try {
-        await runCurrentFile(path, flags, syncFactory ?? account?.sync);
+        result = await runCurrentFile(path, flags, syncFactory ?? account?.sync);
     }
     finally {
         if (account) {
@@ -62,6 +61,12 @@ export async function run(target, flags, syncFactory) {
             // Script cards are made after the run, so that this run's inputs can be replayed. They never delay or fail it.
             if (savedVersions(account.client.server)[account.version.version_id])
                 (await import("./explain.js")).startBackgroundExplain(path, account.version.workflow, account.version.version_id, account.client.server);
+            // The output of this run is judged against the corrections that recent fixes answered, in the background.
+            if (result?.status === "completed" && !flags.resume) {
+                const { watchedCorrections } = await import("./watch.js");
+                if (watchedCorrections(path).length)
+                    (await import("./fix-outcomes.js")).fixStarter.watch(path, flags["run-dir"], account.client.server);
+            }
         }
     }
 }

package/dist/packages/sdk/src/local-judgments.d.ts

@@ -15,6 +15,8 @@ export type LocalJudgment = {
     note: string | null;
     corrected?: unknown;
     created_at: string;
+    /** The person's answer to the fix's question; a later line of the same judgment adds it. */
+    answer?: string;
 };
 /** The file that a run folder records: the Method file that method run ran. */
 export declare const methodFileRecord = "method-file.json";

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

@@ -0,0 +1,38 @@
+export type MergeConflict = {
+    path: string;
+    base: unknown;
+    ours: unknown;
+    theirs: unknown;
+};
+/** Not clean: workflow keeps ours at each conflict. */
+export type MergeResult = {
+    clean: true;
+    workflow: any;
+} | {
+    clean: false;
+    conflicts: MergeConflict[];
+    workflow: any;
+};
+/**
+ * Three-way merge of Method documents, per step and per top-level key. base is the version both sides started from
+ * (an empty base when there is none), ours is the local file, and theirs is the other version.
+ */
+export declare function mergeMethod(base: any, ours: any, theirs: any): MergeResult;
+export type PackageFile = {
+    path: string;
+    sha256: string;
+};
+export type FilesMergeResult<T extends PackageFile = PackageFile> = {
+    clean: boolean;
+    files: T[];
+    conflicts: {
+        path: string;
+    }[];
+};
+/**
+ * Three-way merge of a Method's package files, by path and sha256. A file that only one side added, changed or removed
+ * takes that change; a file that both sides changed in different ways is a conflict (ours stays in files).
+ */
+export declare function mergeFiles<T extends PackageFile>(base: T[], ours: T[], theirs: T[]): FilesMergeResult<T>;
+/** The steps whose definition differs between two documents. */
+export declare function changedSteps(before: any, after: any): string[];

package/dist/packages/sdk/src/merge.js

@@ -0,0 +1,65 @@
+import { isDeepStrictEqual } from 'node:util';
+const isObject = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+/** Keys of ours in their order; a key that only theirs has goes after the key before it in theirs. */
+function keyOrder(ours, theirs) {
+    const keys = Object.keys(ours), theirKeys = Object.keys(theirs);
+    theirKeys.forEach((key, index) => {
+        if (keys.includes(key))
+            return;
+        const before = theirKeys.slice(0, index).reverse().find(other => keys.includes(other));
+        keys.splice(before === undefined ? 0 : keys.indexOf(before) + 1, 0, key);
+    });
+    return keys;
+}
+/**
+ * Three-way merge of Method documents, per step and per top-level key. base is the version both sides started from
+ * (an empty base when there is none), ours is the local file, and theirs is the other version.
+ */
+export function mergeMethod(base, ours, theirs) {
+    if (isDeepStrictEqual(ours, base))
+        return { clean: true, workflow: theirs };
+    if (isDeepStrictEqual(theirs, base) || isDeepStrictEqual(ours, theirs))
+        return { clean: true, workflow: ours };
+    const conflicts = [];
+    const pick = (path, b, o, t) => {
+        if (isDeepStrictEqual(o, t) || isDeepStrictEqual(b, t))
+            return o;
+        if (isDeepStrictEqual(b, o))
+            return t;
+        conflicts.push({ path, base: b, ours: o, theirs: t });
+        return o;
+    };
+    const merge = (path, b, o, t, nested) => {
+        const result = {};
+        for (const key of keyOrder(o, t)) {
+            const at = path ? `${path}.${key}` : key;
+            const value = nested(key) && isObject(o[key]) && isObject(t[key]) && isObject(b?.[key] ?? {})
+                ? merge(at, b?.[key] ?? {}, o[key], t[key], () => false) : pick(at, b?.[key], o[key], t[key]);
+            if (value !== undefined)
+                result[key] = value;
+        }
+        return result;
+    };
+    const workflow = merge('', isObject(base) ? base : {}, ours, theirs, key => key === 'steps');
+    return conflicts.length ? { clean: false, conflicts, workflow } : { clean: true, workflow };
+}
+/**
+ * Three-way merge of a Method's package files, by path and sha256. A file that only one side added, changed or removed
+ * takes that change; a file that both sides changed in different ways is a conflict (ours stays in files).
+ */
+export function mergeFiles(base, ours, theirs) {
+    const byPath = (list) => new Map(list.map(f => [f.path, f]));
+    const b = byPath(base), o = byPath(ours), t = byPath(theirs);
+    const files = [], conflicts = [];
+    for (const path of [...new Set([...o.keys(), ...t.keys(), ...b.keys()])].sort()) {
+        const [bs, os, ts] = [b.get(path)?.sha256, o.get(path)?.sha256, t.get(path)?.sha256];
+        const kept = os === ts || bs === ts ? o.get(path) : bs === os ? t.get(path) : (conflicts.push({ path }), o.get(path));
+        if (kept)
+            files.push(kept);
+    }
+    return { clean: !conflicts.length, files, conflicts };
+}
+/** The steps whose definition differs between two documents. */
+export function changedSteps(before, after) {
+    return [...new Set([...Object.keys(before?.steps ?? {}), ...Object.keys(after?.steps ?? {})])].filter(id => !isDeepStrictEqual(before?.steps?.[id], after?.steps?.[id]));
+}

package/dist/packages/sdk/src/method-client.js

@@ -90,7 +90,7 @@ export class MethodClient {
             throw Object.assign(Error(`${status}: ${title || statusText || "Method returned a non-JSON response"} (${method} ${path}). Local run files are preserved.`), { status });
         }
         if (!ok)
-            throw Object.assign(Error(`${status}: ${String(result.message ?? result.error ?? "Method request failed").slice(0, 1000)}`), { status, code: typeof result.code === 'string' ? result.code.slice(0, 100) : 'method_request_failed' });
+            throw Object.assign(Error(`${status}: ${String(result.message ?? result.error ?? "Method request failed").slice(0, 1000)}`), { status, code: typeof result.code === 'string' ? result.code.slice(0, 100) : 'method_request_failed', body: result });
         return result;
     }
     /** Upload (data) or download bytes. Retries a lost connection or a server error twice; stops only when no bytes move. */

package/dist/packages/sdk/src/method-files.d.ts

@@ -3,12 +3,13 @@ import type { MethodClient } from './method-client.js';
 export declare const runtimeVersion: string;
 export declare const fileHash: (data: Uint8Array) => string;
 export declare function contained(root: string, name: string): string;
-/** The files that a saved package holds: declared files, script entrypoints, and dependency lockfiles. */
+/** The files that a saved package holds: declared files, script entrypoints, dependency lockfiles, and learned rules. */
 export declare function packageFileNames(root: string, workflow: any): string[];
 /**
  * The files of the Method's cases/ folder. A Method with account run data saves its cases with each version; a Method
  * with device run data keeps them on this computer. Hidden files and links are not included. A file over the package
- * limit of 20 MB is not included; its name goes to tooLarge, so the save can say so.
+ * limit of 20 MB is not included; its name goes to tooLarge, so the save can say so. A case's snapshot/ folder (copies of
+ * the files its run read) is never included: it stays on this computer.
  */
 export declare const maxPackageFileBytes = 20000000;
 export declare function caseFileNames(root: string, tooLarge?: string[]): string[];

package/dist/packages/sdk/src/method-files.js

@@ -13,17 +13,18 @@ export function contained(root, name) {
         throw Error(`File leaves the Method folder: ${name}`);
     return path;
 }
-/** The files that a saved package holds: declared files, script entrypoints, and dependency lockfiles. */
+/** The files that a saved package holds: declared files, script entrypoints, dependency lockfiles, and learned rules. */
 export function packageFileNames(root, workflow) {
     const executions = [...Object.values(workflow.steps).flatMap((s) => [s.do, s.check, ...Object.values(s.effects ?? {}).flatMap((e) => [e.observe, e.judge])]),
         ...Object.values(workflow.tools ?? {}).map((t) => t.run)].filter(Boolean);
     return [...new Set([...(workflow.files ?? []), ...executions.filter(e => e.kind === 'run').map(e => e.entrypoint),
-            ...['package.json', 'package-lock.json', 'pyproject.toml', 'uv.lock'].filter(name => existsSync(resolve(root, name)))])].sort();
+            ...['package.json', 'package-lock.json', 'pyproject.toml', 'uv.lock', 'learned.json'].filter(name => existsSync(resolve(root, name)))])].sort();
 }
 /**
  * The files of the Method's cases/ folder. A Method with account run data saves its cases with each version; a Method
  * with device run data keeps them on this computer. Hidden files and links are not included. A file over the package
- * limit of 20 MB is not included; its name goes to tooLarge, so the save can say so.
+ * limit of 20 MB is not included; its name goes to tooLarge, so the save can say so. A case's snapshot/ folder (copies of
+ * the files its run read) is never included: it stays on this computer.
  */
 export const maxPackageFileBytes = 20_000_000;
 export function caseFileNames(root, tooLarge = []) {
@@ -36,6 +37,9 @@ export function caseFileNames(root, tooLarge = []) {
             const name = `${relativeDir}/${entry.name}`;
             if (entry.name.startsWith('.'))
                 continue;
+            // cases/ID/snapshot/ holds copies of what a run read (client documents): it stays on this computer.
+            if (entry.isDirectory() && entry.name === 'snapshot' && /^cases\/[^/]+$/.test(relativeDir))
+                continue;
             try {
                 packagePath(name);
             }

package/dist/packages/sdk/src/method-help.d.ts

@@ -12,7 +12,7 @@ export declare const commandHelp: Record<string, Command>;
 export declare function renderCommand(name: string, includeCommon?: boolean): string;
 export declare const guideTopics: readonly ["start", "concepts", "execution", "examples", "example", "recipes", "recovery", "commands"];
 export declare function authoringGuide(topic?: string, exampleId?: string): string;
-export declare const overviewHelp = "Method \u2014 author, save and run methods with your coding agent.\n\nBefore creating, editing, or proposing a Method, run `method authoring` and read its guidance. Do this before choosing an existing Method as a reference.\n\nLearn: method authoring                 Start the installed guide.\n       method authoring all             Read the full manual offline.\n       method COMMAND --help            Read arguments, results and examples.\n       method help step add             Read help for a subcommand.\n       method schema [TYPE]             Read a formal JSON schema.\n\nLocal drafts: init, show, set, remove, step add/update/remove/move,\n              check set/remove, validate, diff.\nOnline documents: list, get, steps, step, publish, explain.\nResults and improvements: judge, changes.\nKeys for scripts: secret find, secret import, secret set, secret list.\nExecution and evidence: run, run-status, wait, cancel, runs, logs, sync, observe.\nEffects and corrections: effect add/list, case new/retire/list, test.\nInputs and shared state: bind, state.\nBrowser and computer setup: browser connect, config.\nAccount access: status, login, logout, devices, revoke.\nProduction runs: connect, answer, keys create/list/revoke, worker.\n\nSign in with method login first. Read the authoring guide, give each prompt its own step, write the files, validate, and run. Each signed-in run saves a version when the file changed. Publish a version when the user wants to share or schedule it.\nUse method run task.method to run it.\nOnline server: https://app.withmethod.ai. Use --server only to select another\nserver. Sign-in uses browser approval. Never send credentials in chat.\n";
+export declare const overviewHelp = "Method \u2014 author, save and run methods with your coding agent.\n\nBefore creating, editing, or proposing a Method, run `method authoring` and read its guidance. Do this before choosing an existing Method as a reference.\n\nLearn: method authoring                 Start the installed guide.\n       method authoring all             Read the full manual offline.\n       method COMMAND --help            Read arguments, results and examples.\n       method help step add             Read help for a subcommand.\n       method schema [TYPE]             Read a formal JSON schema.\n\nLocal drafts: init, show, set, remove, step add/update/remove/move,\n              check set/remove, validate, diff.\nOnline documents: list, get, steps, step, publish, explain.\nResults and improvements: judge, wait, answer, learned, undo, changes.\nKeys for scripts: secret find, secret import, secret set, secret list.\nExecution and evidence: run, run-status, wait, cancel, runs, logs, sync, observe.\nEffects and corrections: effect add/list, case new/retire/list, test.\nInputs and shared state: bind, state.\nBrowser and computer setup: browser connect, config.\nAccount access: status, login, logout, devices, revoke.\nProduction runs: connect, answer, keys create/list/revoke, worker.\n\nSign in with method login first. Read the authoring guide, give each prompt its own step, write the files, validate, and run. Each signed-in run saves a version when the file changed. Publish a version when the user wants to share or schedule it.\nUse method run task.method to run it.\nOnline server: https://app.withmethod.ai. Use --server only to select another\nserver. Sign-in uses browser approval. Never send credentials in chat.\n";
 /** Resolve help before parsing flags, creating a client, or touching any draft. */
 export declare function methodHelp(args: string[]): string | undefined;
 /** The CLI and published reference use this same command inventory. */