@method-ai-hq/sdk 0.19.0 → 0.20.0

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

@@ -0,0 +1,108 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve, sep } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { parseArgs } from 'node:util';
+import { packagePath } from '../../contracts/src/method-package.js';
+import { authoringPath, readDocument } from './authoring.js';
+import { DEFAULT_SERVER } from './method-client.js';
+import { fileHash } from './method-files.js';
+import { writePrivateJson } from './files.js';
+import { localMethodFolder } from './local-judgments.js';
+import { lastChangedFile, recordLastChange } from './fix-outcomes.js';
+import { undoneLine } from './fix-lines.js';
+import { methodIdPattern } from './versions.js';
+const undoFolder = (file) => join(dirname(resolve(file)), '.method', 'undo');
+const hashOf = (path) => existsSync(path) ? fileHash(readFileSync(path)) : null;
+const inFolder = (file, path) => {
+    const folder = dirname(resolve(file)), full = resolve(folder, packagePath(path));
+    if (!full.startsWith(folder + sep))
+        throw Error(`The change names a file outside the Method folder: ${path}`);
+    return full;
+};
+/** Take what the file and the named files are now, before a change is written. */
+export function snapshot(file, paths) {
+    return { text: readFileSync(file, 'utf8'), files: Object.fromEntries(paths.map(path => { const full = inFolder(file, path); return [path, existsSync(full) ? readFileSync(full).toString('base64') : null]; })) };
+}
+/** Record a change after it was written, so method undo can restore the state before it. */
+export function recordChange(file, kind, cause, what, before) {
+    localMethodFolder(file);
+    mkdirSync(undoFolder(file), { recursive: true, mode: 0o700 });
+    const record = { id: `un_${Date.now().toString(36)}_${randomBytes(4).toString('hex')}`, file: basename(file), kind, created_at: new Date().toISOString(), cause, what, before,
+        after: { sha256: fileHash(readFileSync(file)), files: Object.fromEntries(Object.keys(before.files).map(path => [path, hashOf(inFolder(file, path))])) } };
+    writePrivateJson(join(undoFolder(file), `${record.id}.json`), record);
+    recordLastChange(file);
+    return record;
+}
+/** The changes of this file that can be undone, newest first. */
+export function undoRecords(file) {
+    const folder = undoFolder(file);
+    if (!existsSync(folder))
+        return [];
+    return readdirSync(folder).filter(name => name.endsWith('.json')).map(name => ({ ...JSON.parse(readFileSync(join(folder, name), 'utf8')), path: join(folder, name) }))
+        .filter(record => record.file === basename(file) && !record.undone_at).sort((a, b) => b.created_at.localeCompare(a.created_at));
+}
+/**
+ * Restore the Method file, and the files the change wrote, as they were before the last change Method made (or before
+ * the change `id`, which must be the last one). A file that changed after that change is not overwritten. Returns the
+ * undone record; the caller saves the restored file as a new version.
+ */
+export function undoLast(file, id) {
+    const last = undoRecords(file)[0];
+    if (!last || (id && last.id !== id))
+        throw Error(`Method has not changed ${basename(file)} on this computer${id ? ' since that change' : ''}, so there is nothing to undo.`);
+    if (fileHash(readFileSync(file)) !== last.after.sha256 || Object.entries(last.after.files).some(([path, sha]) => hashOf(inFolder(file, path)) !== sha))
+        throw Error(`${basename(file)} changed after Method's last change, so undo would lose that work. Undo the change by hand, or restore an earlier version on the Method page.`);
+    writeFileSync(file, last.before.text);
+    for (const [path, content] of Object.entries(last.before.files)) {
+        const full = inFolder(file, path);
+        if (content === null)
+            rmSync(full, { force: true });
+        else {
+            mkdirSync(dirname(full), { recursive: true });
+            writeFileSync(full, Buffer.from(content, 'base64'));
+        }
+    }
+    writePrivateJson(last.path, { ...stripPath(last), undone_at: new Date().toISOString() });
+    return last;
+}
+/**
+ * `method undo [FILE] [--json]`: restore the Method file, and the files the change wrote, as they were before the last
+ * fix, pruning change, or removed learned rule. The restored file is saved as a new version.
+ */
+export async function undoCommand(args, clientFactory) {
+    const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { json: { type: 'boolean' }, server: { type: 'string' } } });
+    if (positionals.length > 1)
+        throw Error('Use method undo [FILE].');
+    const file = positionals[0] ? authoringPath(positionals[0]) : defaultFile();
+    const last = undoLast(file);
+    const version = await saveVersion(clientFactory(values.server ?? DEFAULT_SERVER), file, `Undid Method's change: ${last.cause}`.slice(0, 500));
+    const line = undoneLine(last.what);
+    process.stdout.write(values.json ? JSON.stringify({ undone: { kind: last.kind, cause: last.cause, created_at: last.created_at }, version: version ?? null, line }, null, 2) + '\n' : line + '\n');
+}
+const stripPath = ({ path: _path, ...record }) => record;
+function defaultFile() {
+    const here = readdirSync(process.cwd()).filter(name => name.endsWith('.method'));
+    if (here.length === 1)
+        return resolve(here[0]);
+    const last = lastChangedFile();
+    if (last)
+        return last;
+    throw Error('Name the Method file: method undo FILE.');
+}
+/** Save a changed file as a new version when this computer is signed in. Undefined when it cannot be saved now. */
+export async function saveVersion(client, file, reason) {
+    const id = readDocument(file).id;
+    if (typeof id !== 'string' || !methodIdPattern.test(id) || !client.token())
+        return undefined;
+    try {
+        const { Outbox } = await import('./outbox.js');
+        const { prepareVersion } = await import('./versions.js');
+        const outbox = new Outbox(client);
+        const version = await prepareVersion(client, outbox, file, reason);
+        await outbox.drain();
+        return await outbox.whenSaved(version.version_id) ? { version_id: version.version_id, url: version.url } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -0,0 +1,20 @@
+import type { MethodClient } from './method-client.js';
+export type Watched = {
+    judgment: string;
+    caseId: string;
+};
+/** The corrections to watch: those that a fix answered, and those whose note became a learned rule, in the last 30 days. */
+export declare function watchedCorrections(file: string, now?: number): Watched[];
+type Judge = (expect: any[], outcome: any, caseDir: string, file: string) => Promise<{
+    status: string;
+}>;
+/**
+ * Judge one finished run against the watched corrections and send {held, run_id} for each. When the account reopens a
+ * correction (its problem came back on 2 runs), the next run of the Method says so and offers undo. A correction that
+ * the run cannot show (its output is missing) is skipped.
+ */
+export declare function watchRun(client: MethodClient, file: string, runDir: string, judge?: Judge): Promise<{
+    judgment: string;
+    held: boolean;
+}[]>;
+export {};

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

@@ -0,0 +1,86 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { readDocument } from './authoring.js';
+import { methodIdPattern } from './versions.js';
+import { correctionCaseId } from './improve.js';
+import { saveNotice, storedOutcomes } from './fix-outcomes.js';
+import { cameBackLine } from './fix-lines.js';
+import { activeRules, readLearned } from './learned.js';
+// Watching fixes: after a normal run, the output that the run already made is judged against the corrections that
+// fixes and learned rules of the last 30 days answered. Nothing runs again. The account gets {held, run_id} per
+// correction and opens a correction again when its problem came back on 2 runs; the next run of the Method says so.
+const watchDays = 30;
+/** The corrections to watch: those that a fix answered, and those whose note became a learned rule, in the last 30 days. */
+export function watchedCorrections(file, now = Date.now()) {
+    const id = readDocument(file).id;
+    if (typeof id !== 'string' || !methodIdPattern.test(id))
+        return [];
+    const since = now - watchDays * 86_400_000, found = new Map();
+    for (const record of storedOutcomes(id)) {
+        const o = record.outcome;
+        if (record.status !== 'done' || !o || Date.parse(record.finished_at ?? record.started_at) < since)
+            continue;
+        if (o.outcome === 'fixed' || (o.outcome === 'could_not_test' && o.rule_added))
+            found.set(o.id, { judgment: o.id, caseId: correctionCaseId(o.id) });
+    }
+    try {
+        for (const { rule } of activeRules(readLearned(file))) {
+            const judgment = rule.from?.judgment;
+            if (judgment && Date.parse(rule.created) >= since)
+                found.set(judgment, { judgment, caseId: rule.from?.case ?? correctionCaseId(judgment) });
+        }
+    }
+    catch { /* no readable learned rules */ }
+    const cases = join(dirname(file), 'cases');
+    return [...found.values()].filter(w => existsSync(join(cases, w.caseId, 'case.json')));
+}
+/** Judge with the prepared judges of the Method, two when both Claude Code and Codex are signed in. */
+const defaultJudge = async (expect, outcome, caseDir, file) => {
+    const { preparedConfig, judgeProfiles, evaluateWithJudges } = await import('./quality.js');
+    const prepared = await preparedConfig(file, {}, { judge: true });
+    return evaluateWithJudges(expect, outcome, { caseDir, config: prepared.config, options: { runOptions: { processPath: prepared.processPath, ...(prepared.hostedModels ? { hostedModels: prepared.hostedModels } : {}) } } }, await judgeProfiles(prepared.config));
+};
+/**
+ * Judge one finished run against the watched corrections and send {held, run_id} for each. When the account reopens a
+ * correction (its problem came back on 2 runs), the next run of the Method says so and offers undo. A correction that
+ * the run cannot show (its output is missing) is skipped.
+ */
+export async function watchRun(client, file, runDir, judge = defaultJudge) {
+    const methodId = readDocument(file).id;
+    const watched = watchedCorrections(file);
+    if (!watched.length || !client.token())
+        return [];
+    const { outcomeOfRun } = await import('@withmethod/runtime/cases.js');
+    const outcome = await outcomeOfRun(runDir);
+    const results = [];
+    const runId = (() => { try {
+        return JSON.parse(readFileSync(join(runDir, 'run-id.json'), 'utf8')).id;
+    }
+    catch {
+        return undefined;
+    } })();
+    for (const w of watched) {
+        const caseDir = join(dirname(file), 'cases', w.caseId);
+        const made = JSON.parse(readFileSync(join(caseDir, 'case.json'), 'utf8'));
+        let judged;
+        try {
+            judged = await judge(made.expect ?? [], outcome, caseDir, file);
+        }
+        catch {
+            continue;
+        }
+        if (judged.status === 'unverifiable')
+            continue;
+        const held = judged.status === 'pass';
+        results.push({ judgment: w.judgment, held });
+        // The account counts the runs where the problem came back; on the second it opens the correction again.
+        let reply;
+        try {
+            reply = await client.request(`/api/cli/judgments/${encodeURIComponent(w.judgment)}/watch`, 'POST', { held, ...(runId ? { run_id: runId } : {}) });
+        }
+        catch { /* the next run sends its own */ }
+        if (reply?.reopened)
+            saveNotice(methodId, file, 'came_back', cameBackLine(made.note));
+    }
+    return results;
+}

package/dist/packages/workflow-language/src/inspection.d.ts

@@ -141,6 +141,8 @@ export declare const RunEventSchema: z.ZodObject<{
     key: z.ZodOptional<z.ZodString>;
     attempt: z.ZodOptional<z.ZodNumber>;
     attempts: z.ZodOptional<z.ZodNumber>;
+    considered: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    applied: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strict", z.ZodTypeAny, {
     at: string;
     type: string;
@@ -171,6 +173,8 @@ export declare const RunEventSchema: z.ZodObject<{
     unit?: string | undefined;
     attempt?: number | undefined;
     attempts?: number | undefined;
+    considered?: string[] | undefined;
+    applied?: string[] | undefined;
 }, {
     at: string;
     type: string;
@@ -201,6 +205,8 @@ export declare const RunEventSchema: z.ZodObject<{
     unit?: string | undefined;
     attempt?: number | undefined;
     attempts?: number | undefined;
+    considered?: string[] | undefined;
+    applied?: string[] | undefined;
 }>;
 export declare const InspectionSchema: z.ZodObject<{
     started_at: z.ZodOptional<z.ZodString>;
@@ -429,6 +435,8 @@ export declare const InspectionSchema: z.ZodObject<{
         key: z.ZodOptional<z.ZodString>;
         attempt: z.ZodOptional<z.ZodNumber>;
         attempts: z.ZodOptional<z.ZodNumber>;
+        considered: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        applied: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     }, "strict", z.ZodTypeAny, {
         at: string;
         type: string;
@@ -459,6 +467,8 @@ export declare const InspectionSchema: z.ZodObject<{
         unit?: string | undefined;
         attempt?: number | undefined;
         attempts?: number | undefined;
+        considered?: string[] | undefined;
+        applied?: string[] | undefined;
     }, {
         at: string;
         type: string;
@@ -489,6 +499,8 @@ export declare const InspectionSchema: z.ZodObject<{
         unit?: string | undefined;
         attempt?: number | undefined;
         attempts?: number | undefined;
+        considered?: string[] | undefined;
+        applied?: string[] | undefined;
     }>, "many">>;
     invocations: z.ZodRecord<z.ZodString, z.ZodObject<{
         step_id: z.ZodString;
@@ -570,6 +582,8 @@ export declare const InspectionSchema: z.ZodObject<{
             key: z.ZodOptional<z.ZodString>;
             attempt: z.ZodOptional<z.ZodNumber>;
             attempts: z.ZodOptional<z.ZodNumber>;
+            considered: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            applied: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         }, "strict", z.ZodTypeAny, {
             at: string;
             type: string;
@@ -600,6 +614,8 @@ export declare const InspectionSchema: z.ZodObject<{
             unit?: string | undefined;
             attempt?: number | undefined;
             attempts?: number | undefined;
+            considered?: string[] | undefined;
+            applied?: string[] | undefined;
         }, {
             at: string;
             type: string;
@@ -630,6 +646,8 @@ export declare const InspectionSchema: z.ZodObject<{
             unit?: string | undefined;
             attempt?: number | undefined;
             attempts?: number | undefined;
+            considered?: string[] | undefined;
+            applied?: string[] | undefined;
         }>, "many">;
         observed_effects: z.ZodOptional<z.ZodUnion<[z.ZodObject<{
             network: z.ZodArray<z.ZodString, "many">;
@@ -699,6 +717,8 @@ export declare const InspectionSchema: z.ZodObject<{
             unit?: string | undefined;
             attempt?: number | undefined;
             attempts?: number | undefined;
+            considered?: string[] | undefined;
+            applied?: string[] | undefined;
         }[];
         step_id: string;
         inputs?: Record<string, Json> | undefined;
@@ -760,6 +780,8 @@ export declare const InspectionSchema: z.ZodObject<{
             unit?: string | undefined;
             attempt?: number | undefined;
             attempts?: number | undefined;
+            considered?: string[] | undefined;
+            applied?: string[] | undefined;
         }[];
         step_id: string;
         inputs?: Record<string, Json> | undefined;
@@ -833,6 +855,8 @@ export declare const InspectionSchema: z.ZodObject<{
             unit?: string | undefined;
             attempt?: number | undefined;
             attempts?: number | undefined;
+            considered?: string[] | undefined;
+            applied?: string[] | undefined;
         }[];
         step_id: string;
         inputs?: Record<string, Json> | undefined;
@@ -937,6 +961,8 @@ export declare const InspectionSchema: z.ZodObject<{
         unit?: string | undefined;
         attempt?: number | undefined;
         attempts?: number | undefined;
+        considered?: string[] | undefined;
+        applied?: string[] | undefined;
     }[] | undefined;
 }, {
     status: "running" | "waiting_for_you" | "succeeded" | "unconfirmed" | "failed";
@@ -989,6 +1015,8 @@ export declare const InspectionSchema: z.ZodObject<{
             unit?: string | undefined;
             attempt?: number | undefined;
             attempts?: number | undefined;
+            considered?: string[] | undefined;
+            applied?: string[] | undefined;
         }[];
         step_id: string;
         inputs?: Record<string, Json> | undefined;
@@ -1093,6 +1121,8 @@ export declare const InspectionSchema: z.ZodObject<{
         unit?: string | undefined;
         attempt?: number | undefined;
         attempts?: number | undefined;
+        considered?: string[] | undefined;
+        applied?: string[] | undefined;
     }[] | undefined;
 }>;
 export type RunInspection = z.infer<typeof InspectionSchema>;

package/dist/packages/workflow-language/src/inspection.js

@@ -39,6 +39,8 @@ export const RunEventSchema = z.strictObject({
     total: z.number().int().nonnegative().optional(), unit: z.string().max(50).optional(),
     // Notice events: key is the same for each repeat of one problem, so a newer notice replaces an older one.
     key: z.string().max(500).optional(), attempt: z.number().int().positive().optional(), attempts: z.number().int().positive().optional(),
+    // learned_applied: the IDs of the learned rules that the step considered and the ones it added to its prompt.
+    considered: z.array(z.string().max(100)).max(500).optional(), applied: z.array(z.string().max(100)).max(500).optional(),
 });
 export const InspectionSchema = z.strictObject({
     started_at: z.string().optional(), device_name: z.string().optional(),
@@ -137,7 +139,7 @@ export function observedValue(item, inspection, invocation) {
  */
 export function deviceOnly(inspection) {
     const failure = inspection.failure ? (({ evidence, details, diagnostics, ...kept }) => ({ failure: kept }))(inspection.failure) : {};
-    const event = ({ at, type, sequence, phase, duration_ms, usage, provider, model, kind, exit_code, completed, total, key, attempt, attempts }) => Object.fromEntries(Object.entries({ at, type, sequence, phase, duration_ms, usage, provider, model, kind, exit_code, completed, total, key, attempt, attempts }).filter(([, value]) => value !== undefined));
+    const event = ({ at, type, sequence, phase, duration_ms, usage, provider, model, kind, exit_code, completed, total, key, attempt, attempts, considered, applied }) => Object.fromEntries(Object.entries({ at, type, sequence, phase, duration_ms, usage, provider, model, kind, exit_code, completed, total, key, attempt, attempts, considered, applied }).filter(([, value]) => value !== undefined));
     return {
         schema: inspection.schema, content: 'device', workflow: inspection.workflow, run_id: inspection.run_id, status: inspection.status, ...failure,
         ...(inspection.started_at ? { started_at: inspection.started_at } : {}), ...(inspection.device_name ? { device_name: inspection.device_name } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@method-ai-hq/sdk",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Build and run reusable .method files with checked steps and saved results.",
   "license": "MIT",
   "type": "module",
@@ -35,7 +35,7 @@
     "prepack": "npm --prefix ../.. run build"
   },
   "dependencies": {
-    "@withmethod/runtime": "https://codeload.github.com/method-ai-hq/method-spec/tar.gz/v0.15.0",
+    "@withmethod/runtime": "https://codeload.github.com/method-ai-hq/method-spec/tar.gz/v0.16.1",
     "fflate": "^0.8.3",
     "yaml": "^2.9.0",
     "zod": "^3.25.76"