@method-ai-hq/sdk 0.0.0-stage → 0.14.3

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

@@ -0,0 +1,47 @@
+import type { MethodClient } from "./method-client.js";
+type Language = "python" | "node";
+export declare function detectLanguage(app: string): Language;
+export declare function connectCommand(args: string[], client: MethodClient): Promise<{
+    install: string;
+    code: string;
+    secrets_to_set_on_the_host: string[];
+    next: string[];
+    gitignore?: string;
+    key: {
+        name: string;
+        written_to: string;
+        note: string;
+        kept?: never;
+    } | {
+        kept: string;
+        name?: never;
+        written_to?: never;
+        note?: never;
+    };
+    published?: string;
+    app: string;
+    language: Language;
+    method_id: string | undefined;
+    published_version_id: string;
+}>;
+/** `method answer RUN_ID [--answer JSON]`: show a production run's question, or answer it. */
+export declare function answerCommand(args: string[], client: MethodClient): Promise<import("./production.js").ProductionRun | {
+    run_id: string;
+    status: import("./production.js").RunStatus;
+    message: string;
+    step?: never;
+    question?: never;
+    form?: never;
+    expires_at?: never;
+    next?: never;
+} | {
+    run_id: string;
+    step: string;
+    question: string;
+    form: unknown;
+    expires_at: string | null;
+    next: string;
+    status?: never;
+    message?: never;
+}>;
+export {};

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

@@ -0,0 +1,203 @@
+import { appendFileSync, existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, join, relative, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { authoringPath, readDocument } from "./authoring.js";
+import { dotenvValues, Method, MethodApiError, ServiceApi } from "./production.js";
+import { open } from "./run-data.js";
+// `method connect [APP_FOLDER]`: connect an app to the Method in this folder. It makes a service key named after the app,
+// writes it to the app's .env without showing it, publishes the Method if it has no published version, and prints the
+// install line and the code for the app's language. `method answer RUN_ID`: answer a production run's question.
+const PRODUCTION_SERVER = "https://app.withmethod.ai";
+/** The one Method file in a folder (not in run folders). */
+function methodFile(folder, given) {
+    if (given)
+        return authoringPath(given);
+    const found = readdirSync(folder).filter(name => /\.method$/i.test(name) && statSync(join(folder, name)).isFile());
+    if (found.length === 1)
+        return join(folder, found[0]);
+    if (!found.length)
+        throw Error("No .method file in this folder. Run method connect from the Method's folder, or give --file METHOD_FILE.");
+    throw Error(`This folder has more than one Method (${found.join(", ")}). Give --file METHOD_FILE.`);
+}
+export function detectLanguage(app) {
+    const has = (name) => existsSync(join(app, name));
+    if (has("package.json"))
+        return "node";
+    if (["pyproject.toml", "requirements.txt", "setup.py", "Pipfile", "uv.lock", "poetry.lock"].some(has))
+        return "python";
+    if (readdirSync(app).some(name => name.endsWith(".py")))
+        return "python";
+    if (readdirSync(app).some(name => /\.(m?js|ts)$/.test(name)))
+        return "node";
+    throw Error(`Cannot tell the language of ${app}: add package.json (Node) or pyproject.toml or requirements.txt (Python).`);
+}
+function installLine(app, language) {
+    const has = (name) => existsSync(join(app, name));
+    if (language === "node") {
+        const pack = process.env.METHOD_NODE_PACKAGE || "@method-ai-hq/sdk";
+        return has("pnpm-lock.yaml") ? `pnpm add ${pack}` : has("yarn.lock") ? `yarn add ${pack}` : has("bun.lockb") || has("bun.lock") ? `bun add ${pack}` : `npm install ${pack}`;
+    }
+    const pack = process.env.METHOD_PYTHON_PACKAGE || "method-ai";
+    return has("uv.lock") ? `uv add ${pack}` : has("poetry.lock") ? `poetry add ${pack}` : `pip install ${pack}`;
+}
+function example(document, language, methodId, hasAsk) {
+    const inputs = Object.entries(document.inputs ?? {}).filter(([, def]) => !Object.hasOwn(def ?? {}, "default"));
+    if (language === "python") {
+        const values = inputs.map(([name]) => `"${name}": ${name}`).join(", ");
+        return [
+            "from withmethod import Method",
+            "",
+            "method = Method()  # reads METHOD_API_KEY from the environment or .env",
+            "",
+            ...(hasAsk ? [
+                "# The Method asks a person before it finishes, so start the run and answer it later.",
+                `method.worker.start(methods=["${methodId}"])  # once, when the app starts: runs this Method's runs here`,
+                `run_id = method.runs.start("${methodId}", {${values}}, idempotency_key=...)["run_id"]  # one key for each event; keep run_id`,
+                "",
+                "# Where the person decides (for example an approve endpoint):",
+                "method.runs.answer(run_id, {...})  # the ask step's out fields",
+                'result = method.runs.wait(run_id)["result"]',
+            ] : [
+                `run = method.run("${methodId}", {${values}}, idempotency_key=...)  # one key for each event`,
+                `result = run["result"]`,
+            ]),
+        ].join("\n");
+    }
+    const values = inputs.map(([name]) => name).join(", ");
+    return [
+        'import { Method } from "@method-ai-hq/sdk";',
+        "",
+        "const method = new Method(); // reads METHOD_API_KEY from the environment or .env",
+        "",
+        ...(hasAsk ? [
+            "// The Method asks a person before it finishes, so start the run and answer it later.",
+            `method.worker.start({ methods: ["${methodId}"] }); // once, when the app starts: runs this Method's runs here`,
+            `const { run_id } = await method.runs.start({ method: "${methodId}", inputs: { ${values} }, idempotencyKey: ... }); // keep run_id`,
+            "",
+            "// Where the person decides (for example an approve endpoint):",
+            "await method.runs.answer(run_id, { ... }); // the ask step's out fields",
+            "const result = (await method.runs.wait(run_id)).result;",
+        ] : [
+            `const run = await method.run({ method: "${methodId}", inputs: { ${values} }, idempotencyKey: ... });`,
+            "const result = run.result;",
+        ]),
+    ].join("\n");
+}
+/** Add KEY=VALUE to .env, or replace the line that sets KEY. */
+function writeEnv(file, name, value) {
+    const text = existsSync(file) ? readFileSync(file, "utf8") : "";
+    const pattern = new RegExp(`^\\s*(?:export\\s+)?${name}\\s*=.*$`, "m");
+    if (pattern.test(text))
+        writeFileSync(file, text.replace(pattern, `${name}=${value}`), { mode: 0o600 });
+    else
+        writeFileSync(file, `${text}${text && !text.endsWith("\n") ? "\n" : ""}${name}=${value}\n`, { mode: 0o600 });
+}
+/** Keep .env out of git: add it to the app's .gitignore when the app is in a git repository. */
+function ignoreEnv(app) {
+    let folder = resolve(app);
+    for (;;) {
+        if (existsSync(join(folder, ".git")))
+            break;
+        const parent = resolve(folder, "..");
+        if (parent === folder)
+            return null;
+        folder = parent;
+    }
+    const file = join(app, ".gitignore");
+    const lines = existsSync(file) ? readFileSync(file, "utf8").split(/\r?\n/).map(line => line.trim()) : [];
+    if (lines.some(line => [".env", "/.env", ".env*", "*.env"].includes(line)))
+        return null;
+    appendFileSync(file, `${lines.length && lines.at(-1) !== "" ? "\n" : ""}.env\n`);
+    return relative(process.cwd(), file) || file;
+}
+export async function connectCommand(args, client) {
+    const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { file: { type: "string" }, server: { type: "string" } } });
+    const app = resolve(positionals[0] ?? ".");
+    if (!existsSync(app) || !statSync(app).isDirectory())
+        throw Error(`${app} is not a folder. Use method connect APP_FOLDER.`);
+    const file = methodFile(process.cwd(), values.file);
+    const document = readDocument(file);
+    const language = detectLanguage(app);
+    if (!client.token())
+        await client.login();
+    const envFile = join(app, ".env");
+    // An app that has a working key keeps it: connect again makes no second key.
+    let key = dotenvValues(app).METHOD_API_KEY, keyName = basename(app), madeKey = false;
+    if (key) {
+        try {
+            await new ServiceApi(key, client.server).request("/v1/methods/" + encodeURIComponent(document.id ?? "wf_none"));
+        }
+        catch (error) {
+            if (error instanceof MethodApiError && error.status === 401)
+                key = undefined;
+        }
+    }
+    if (!key) {
+        const created = await client.request("/api/service-keys", "POST", { name: keyName });
+        key = created.key;
+        keyName = created.name;
+        madeKey = true;
+        writeEnv(envFile, "METHOD_API_KEY", key);
+    }
+    // A server other than the hosted one (a local or test server) goes to .env too, so the app reaches the same server.
+    if (client.server !== PRODUCTION_SERVER)
+        writeEnv(envFile, "METHOD_SERVER", client.server);
+    const ignored = ignoreEnv(app);
+    // The app runs the published version. Publish the current file when the Method has none.
+    let methodId = document.id, published = null, publishedNow = false;
+    if (methodId) {
+        try {
+            published = (await new ServiceApi(key, client.server).request(`/v1/methods/${encodeURIComponent(methodId)}`)).body.published_version_id;
+        }
+        catch (error) {
+            if (!(error instanceof MethodApiError && error.status === 404))
+                throw error;
+        }
+    }
+    if (!published) {
+        const { publish } = await import("./versions.js");
+        const result = await publish(client, file, `Connected to ${basename(app)}.`);
+        methodId = result.workflow_id;
+        published = result.version_id;
+        publishedNow = true;
+    }
+    const hasAsk = Object.values(document.steps ?? {}).some((step) => step?.ask);
+    const secrets = Object.keys(document.secrets ?? {});
+    return {
+        app, language, method_id: methodId, published_version_id: published, ...(publishedNow ? { published: "now" } : {}),
+        key: madeKey ? { name: keyName, written_to: envFile, note: "The key is in .env only. It is not shown." } : { kept: envFile },
+        ...(ignored ? { gitignore: `Added .env to ${ignored}.` } : {}),
+        install: installLine(app, language),
+        code: example(document, language, methodId, hasAsk),
+        secrets_to_set_on_the_host: secrets,
+        next: [
+            `Run in ${app}: ${installLine(app, language)}`,
+            "Add the code where the app handles the event. The first run starts a worker in the app's process; on a server, run `method worker` beside it with the same METHOD_API_KEY if you prefer.",
+            ...(secrets.length ? [`Set these secrets where the app runs: ${secrets.join(", ")}. On this computer, method secret set NAME works.`] : []),
+            hasAsk ? "Questions of ask steps go to the ask handler; without one, to the dashboard inbox and an email to the person who published the Method." : "",
+            "Production runs show on the dashboard under Production.",
+        ].filter(Boolean),
+    };
+}
+/** `method answer RUN_ID [--answer JSON]`: show a production run's question, or answer it. */
+export async function answerCommand(args, client) {
+    const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { answer: { type: "string" }, server: { type: "string" } } });
+    const runId = positionals[0];
+    if (!runId)
+        throw Error("Use method answer RUN_ID [--answer JSON].");
+    // A device run's question is sealed with the key that started it: METHOD_API_KEY, the app's .env in this folder, or
+    // this computer's sign-in (runs that an app started on this laptop without a key).
+    if (!process.env.METHOD_API_KEY && !dotenvValues().METHOD_API_KEY && !client.token())
+        await client.login();
+    const credential = process.env.METHOD_API_KEY ?? dotenvValues().METHOD_API_KEY ?? client.token();
+    const method = new Method({ apiKey: credential, server: client.server, worker: false });
+    const run = await method.runs.get(runId);
+    if (run.status !== "waiting" || !run.question)
+        return { run_id: runId, status: run.status, message: "This run has no question to answer." };
+    const question = run.question;
+    const asked = question.sealed ? open(credential, "question", run.method_id, question.sealed) : { question: question.question ?? "", form: question.form };
+    if (values.answer === undefined)
+        return { run_id: runId, step: question.step, question: asked.question, form: asked.form, expires_at: question.expires_at,
+            next: `method answer ${runId} --answer '${JSON.stringify(Object.fromEntries(Object.keys(asked.form?.properties ?? {}).map(name => [name, "…"])))}'` };
+    return await method.runs.answer(runId, JSON.parse(values.answer));
+}

package/dist/packages/sdk/src/current-inspection.d.ts

@@ -0,0 +1,3 @@
+import { type RunInspection } from "../../workflow-language/src/inspection.js";
+/** Convert the public trace into the dashboard's stable inspection contract. */
+export declare function inspectCurrentRun(root: string, activeSnapshot?: boolean, includeFiles?: boolean | "references"): RunInspection;

package/dist/packages/sdk/src/current-inspection.js

@@ -0,0 +1,146 @@
+import { documentForDigest } from "@withmethod/runtime/document.js";
+import { attachResultFiles } from "./result-files.js";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { join, sep, basename } from "node:path";
+import { createHash } from "node:crypto";
+import { loadWorkflow } from "../../workflow-language/src/validate.js";
+import { InspectionSchema } from "../../workflow-language/src/inspection.js";
+/** Convert the public trace into the dashboard's stable inspection contract. */
+export function inspectCurrentRun(root, activeSnapshot = false, includeFiles = false) {
+    const path = (name) => {
+        const actual = realpathSync(join(root, name));
+        if (!actual.startsWith(root + sep))
+            throw Error("Run record escapes the run directory.");
+        return actual;
+    };
+    const read = (name) => JSON.parse(readFileSync(path(name), "utf8"));
+    const rawMethod = read("method.json");
+    const workflow = loadWorkflow(rawMethod);
+    const manifest = read("manifest.json");
+    // The runtime hashes the Method without its id: line.
+    const digest = createHash("sha256").update(JSON.stringify(documentForDigest(rawMethod))).digest("hex");
+    if (manifest.method_sha256 !== digest)
+        throw Error("Saved method hash does not match the run.");
+    const active = existsSync(join(root, ".lock"));
+    if (active && (!activeSnapshot || readFileSync(path(".lock"), "utf8") !== String(process.pid)))
+        throw Error("Finish the run before exporting its records.");
+    const summary = read("summary.json");
+    const events = readFileSync(path("events.jsonl"), "utf8").split("\n").filter(Boolean).map(line => JSON.parse(line));
+    const start = events.find(e => e.event === "run.started");
+    const invocations = {};
+    const setup = existsSync(join(root, 'setup.json')) ? read('setup.json') : [];
+    const runEvents = setup;
+    for (const event of events) {
+        // Keep useful trace fields; do not upload tool arguments, environment values, or process stdout.
+        const recorded = {
+            ...(typeof event.provider === 'string' ? { provider: event.provider } : {}),
+            ...(typeof event.model === 'string' ? { model: event.model } : {}),
+            ...(event.kind === 'classify' ? { kind: 'classify' } : {}),
+            ...(typeof event.request_id === 'string' ? { request_id: event.request_id } : {}),
+            ...(typeof event.operation_id === 'string' ? { operation_id: event.operation_id } : {}),
+            ...(typeof event.confidence === 'number' ? { confidence: event.confidence } : {}),
+            ...(event.kind === 'classify' && event.usage !== undefined ? { usage: event.usage } : {}),
+            ...(typeof event.duration_ms === 'number' ? { duration_ms: event.duration_ms } : event.event.startsWith('run.') && typeof event.elapsed_ms === 'number' ? { duration_ms: event.elapsed_ms } : {}),
+            at: event.at, type: event.event === "human.required" ? "human_input_required" : event.event.replaceAll(".", "_"),
+            ...(event.check ? { detail: `${event.check.status}: ${event.check.reason}` } : event.message || event.error ? { detail: String(event.message ?? event.error).slice(0, 4000) } : event.code ? { detail: String(event.code) } : {}),
+            ...(Number.isInteger(event.sequence) ? { sequence: event.sequence } : {}),
+            ...(["action", "check"].includes(event.phase) ? { phase: event.phase } : {}),
+            ...(typeof event.tool === "string" ? { tool: event.tool } : {}),
+            ...(typeof event.call_id === "string" ? { call_id: event.call_id } : {}),
+            ...(typeof event.child === "string" ? { child: event.child } : {}),
+            ...(Number.isSafeInteger(event.completed) && Number.isSafeInteger(event.total) ? { completed: event.completed, total: event.total, ...(typeof event.unit === "string" ? { unit: event.unit } : {}) } : {}),
+            ...(event.entrypoint ? { command: [event.runtime, event.entrypoint, ...(event.args ?? [])].filter(Boolean).join(" ") } : typeof event.command === "string" ? { command: event.command } : {}),
+            ...(event.exit_code !== undefined ? { exit_code: event.exit_code } : {}),
+            ...(typeof event.diagnostics === "string" && event.diagnostics ? { diagnostics: event.diagnostics.length <= 4000 ? event.diagnostics : event.diagnostics.slice(0, 1000) + "\n[middle omitted]\n" + event.diagnostics.slice(-3000) } : {}),
+        };
+        // Effect verdicts are run events, so the dashboard shows them without a new inspection field.
+        if (event.event === "effect.observed")
+            recorded.detail = `${event.effect}: ${event.verdict}${event.final ? "" : " (observation continues)"}. ${String(event.reason ?? "")}`.slice(0, 4000);
+        if (event.event === "run.status_changed")
+            recorded.detail = `Status changed from ${event.from} to ${event.to} after a later observation.`;
+        if (event.event === "effects.waived")
+            recorded.detail = event.waived.map((w) => `Not observed: ${w.step} (${w.reason})`).join("; ").slice(0, 4000);
+        if (event.event === "effects.fixtures_passed")
+            recorded.detail = `${event.fixtures.length} effect fixtures gave their expected verdicts.`;
+        if (event.event === "run.started" && event.forked_from) {
+            const fork = event.forked_from;
+            recorded.detail = `Forked from run ${fork.run_dir} (execution ${fork.execution_id}). Reused: ${fork.steps.map((s) => s.step).join(", ")}. `
+                + (fork.changed_files.length ? `Changed files: ${fork.changed_files.map((f) => `${f.file} (${f.change})`).join(", ")}. Only the entrypoints of reused steps were compared.` : "No bundle file changed.");
+        }
+        if (!event.step) {
+            runEvents.push(recorded);
+            continue;
+        }
+        if (event.event === "step.imported") {
+            // A fork reuses accepted iterations from its parent run; they have no started event here.
+            const imported = { ...recorded, detail: `Reused from run ${event.parent_run_dir} (execution ${event.parent_execution_id})` };
+            const iterations = event.skipped ? [null] : event.outputs ?? [];
+            iterations.forEach((outputs, iteration) => {
+                const row = invocations[`${event.step}:${iteration}`] ??= { step_id: event.step, status: "running", checks: [], changes: {}, events: [] };
+                row.events.push(imported);
+                if (event.skipped)
+                    row.status = "skipped";
+                else {
+                    row.status = "passed";
+                    row.outputs = outputs;
+                }
+            });
+            continue;
+        }
+        const id = `${event.step}:${event.iteration ?? 0}`;
+        const row = invocations[id] ??= { step_id: event.step, status: "running", checks: [], changes: {}, events: [] };
+        if (event.event === "step.started") {
+            row.events = [];
+            row.changes = {};
+            delete row.prompts;
+            delete row.verification;
+            delete row.failure;
+            delete row.observed_effects;
+        }
+        row.events.push(recorded);
+        if (event.event === "prompt.rendered")
+            (row.prompts ??= []).push({ sequence: event.sequence, phase: event.phase, template: event.template, rendered: event.rendered });
+        if (event.event === "step.started") {
+            row.status = "running";
+            row.inputs = event.inputs;
+            row.checks = [];
+            delete row.outputs;
+            delete row.error;
+        }
+        if (event.event === "step.candidate") {
+            const { state, ...outputs } = event.candidate;
+            row.outputs = outputs;
+            row.status = "returned";
+        }
+        if (event.event === "check.completed")
+            row.checks.push({ id: String(event.sequence), result: event.check.status === "unknown" ? "ambiguous" : event.check.status, summary: event.check.reason, evidence: event.check.evidence, method: typeof workflow.steps[event.step]?.check === "object" && Object.hasOwn(Object(workflow.steps[event.step].check), "kind") ? "executor" : "assert" });
+        if (event.event === "step.accepted") {
+            row.status = "passed";
+            row.outputs = event.outputs;
+            row.changes = event.state;
+            row.verification = event.check.status === "unchecked" ? "unchecked" : "checked";
+            if (event.observed_effects)
+                row.observed_effects = event.observed_effects;
+        }
+        if (event.event === "process.failed" && event.phase === "action" && !event.tool && event.observed_effects)
+            row.observed_effects = event.observed_effects;
+        if (event.event === "step.skipped")
+            row.status = "skipped";
+        if (event.event === "human.required")
+            row.status = "needs_attention";
+    }
+    if (!active && summary.status !== "completed")
+        for (const row of Object.values(invocations))
+            if (["running", "returned"].includes(row.status)) {
+                row.status = "needs_attention";
+                row.error = summary.error ?? "Run interrupted";
+            }
+    const files = includeFiles ? attachResultFiles(workflow, invocations, [join(root, "artifacts")], join(root, "artifacts"), includeFiles === "references") : undefined;
+    const lastAccepted = events.filter(e => e.event === "step.accepted").at(-1);
+    return InspectionSchema.parse({ schema: "workflow-inspection/2", workflow, run_id: basename(root), local_run_directory: root,
+        ...(typeof (summary.started_at ?? start?.at) === 'string' ? { started_at: summary.started_at ?? start.at } : {}),
+        ...(typeof (summary.device_name ?? start?.device_name) === 'string' ? { device_name: summary.device_name ?? start.device_name } : {}),
+        events: runEvents, ...(includeFiles ? { files } : {}), status: active ? "running" : summary.status === "completed" ? "succeeded" : "needs_attention",
+        ...(summary.error ? { error: summary.error } : {}), inputs: start?.inputs ?? {}, state: lastAccepted?.state ?? start?.initial_state ?? {},
+        resources: Object.fromEntries(Object.entries(start?.config?.environment ?? {}).map(([key, value]) => [key, { description: workflow.environment?.[key]?.description ?? key, path: value }])), invocations });
+}

package/dist/packages/sdk/src/current-runtime.d.ts

@@ -0,0 +1,14 @@
+import { MethodClient } from './method-client.js';
+import { runMethod as executeMethod } from "@withmethod/runtime/runner.js";
+import type { MethodSync } from "./method-sync.js";
+import type { parse } from "./local-cli.js";
+export { executeMethod as runCurrentMethod };
+/** Recent run folders on this computer, newest first. The runtime reuses only iterations whose key matches. */
+export declare function recentRuns(exclude: string, limit?: number): string[];
+/**
+ * Run a local Method file. The run starts at once: saving and run records go through the outbox and never stop or fail
+ * the run. baseConfig is a configuration the SDK made (a saved version's package); otherwise localSetup builds it.
+ * runSecrets are values that the SDK gives this run only (such as the signed-in key for improve.method); they come
+ * before the shell and the secret store, and are never saved.
+ */
+export declare function runCurrentFile(file: string, flags: ReturnType<typeof parse>["values"], syncFactory?: () => MethodSync, onEvent?: (event: any) => Promise<void>, client?: MethodClient, baseConfig?: any, runSecrets?: Record<string, string>): Promise<import("@withmethod/runtime/api-types.js").RunResult>;

package/dist/packages/sdk/src/current-runtime.js

@@ -0,0 +1,167 @@
+import { managedClassification } from './classification-client.js';
+import { MethodClient } from './method-client.js';
+import { openBrowser } from './browser.js';
+import { readFileSync, existsSync, mkdirSync, readdirSync, statSync } from "node:fs";
+import { join, dirname, resolve } from 'node:path';
+import { hostedModelsFor, managedModels } from './hosted-models.js';
+import { resolveSecrets } from './secrets.js';
+import { randomUUID } from 'node:crypto';
+import { assertCheckpointExecutor } from '@withmethod/runtime/executor-version.js';
+import { accountNeeds, checkAgents, resolveAgentProfiles } from './capabilities.js';
+import { prepareRuntime, methodCache } from './prepare.js';
+import { writePrivateJson } from './files.js';
+import { runMethod as executeMethod } from "@withmethod/runtime/runner.js";
+import { localSetup } from "./local-setup.js";
+import { authoringPath } from "./authoring.js";
+export { executeMethod as runCurrentMethod };
+/** Recent run folders on this computer, newest first. The runtime reuses only iterations whose key matches. */
+export function recentRuns(exclude, limit = 20) {
+    const roots = [join(methodCache(), 'runs'), join(process.cwd(), '.method-runs'), dirname(resolve(exclude))];
+    const found = new Map();
+    for (const root of new Set(roots.map(path => resolve(path)))) {
+        let names = [];
+        try {
+            names = readdirSync(root);
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            const dir = join(root, name);
+            if (dir === resolve(exclude))
+                continue;
+            try {
+                found.set(dir, statSync(join(dir, 'checkpoint.json')).mtimeMs);
+            }
+            catch { /* not a run */ }
+        }
+    }
+    return [...found].sort((a, b) => b[1] - a[1]).slice(0, limit).map(([dir]) => dir);
+}
+/**
+ * Run a local Method file. The run starts at once: saving and run records go through the outbox and never stop or fail
+ * the run. baseConfig is a configuration the SDK made (a saved version's package); otherwise localSetup builds it.
+ * runSecrets are values that the SDK gives this run only (such as the signed-in key for improve.method); they come
+ * before the shell and the secret store, and are never saved.
+ */
+export async function runCurrentFile(file, flags, syncFactory, onEvent, client = new MethodClient(flags.server), baseConfig, runSecrets = {}) {
+    if (flags.resume && !flags['run-dir'])
+        throw Error('Resume needs --run-dir.');
+    flags = { ...flags, 'run-dir': flags['run-dir'] ?? join(process.cwd(), '.method-runs', randomUUID()) };
+    const json = (path) => path ? JSON.parse(readFileSync(authoringPath(path), "utf8")) : undefined;
+    if (flags.resume)
+        assertCheckpointExecutor(json(join(flags['run-dir'], 'checkpoint.json')));
+    const setup = await localSetup(file, flags, baseConfig);
+    let config = setup.config;
+    const agent = setup.agent;
+    const sourceRoot = setup.sourceRoot;
+    const method = (await import('./authoring.js')).readDocument(file);
+    const controller = new AbortController();
+    const stop = () => controller.abort(Object.assign(new Error("Interrupted by operator"), { code: "interrupted" }));
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+    let sync;
+    let failure;
+    let runFailed = false;
+    let browser;
+    try {
+        try {
+            sync = syncFactory?.();
+        }
+        catch (error) {
+            process.stderr.write(`Run records stay on this computer: ${error.message}\n`);
+        }
+        // Records the start; sends nothing. The outbox starts when the run starts.
+        await sync?.start(method, json(flags.inputs) ?? {}, {}, false);
+        // A run with its own OpenRouter key (config.classification.api_key_env) needs no Method sign-in for classification.
+        const needs = accountNeeds(method, config, agent);
+        const classification = needs.classification ? managedClassification(client) : undefined;
+        // Classification uses the Method account. Hosted models are used when this computer is signed in.
+        if (classification && !client.token())
+            await client.login();
+        const resolvedFile = flags['run-dir'] ? join(authoringPath(flags['run-dir']), 'runtime.resolved.json') : undefined;
+        const priorCheckpoint = !!flags.resume && !!resolvedFile && !existsSync(resolvedFile)
+            && existsSync(join(dirname(resolvedFile), 'checkpoint.json'));
+        let prepared;
+        if (priorCheckpoint) {
+            // Direct executor runs retain the supplied config without SDK preparation.
+            prepared = { config, processPath: process.env.PATH ?? '', prepareBundle: async () => { } };
+        }
+        else {
+            if (flags.resume && resolvedFile && existsSync(resolvedFile))
+                config = JSON.parse(readFileSync(resolvedFile, 'utf8'));
+            else {
+                let hostedModel;
+                if (needs.models && client.token()) {
+                    try {
+                        hostedModel = await managedModels(client).model();
+                    }
+                    catch (error) {
+                        process.stderr.write(`Hosted models are unavailable (${error.message}). Using a local agent.\n`);
+                    }
+                }
+                config.models = await resolveAgentProfiles(method, config, agent, hostedModel);
+                if (classification)
+                    config.classification = await classification.resolve(controller.signal);
+            }
+            await checkAgents(config.models);
+            prepared = await prepareRuntime(sourceRoot, config, method);
+            config = prepared.config;
+            if (resolvedFile) {
+                mkdirSync(dirname(resolvedFile), { recursive: true, mode: 0o700 });
+                writePrivateJson(resolvedFile, config);
+            }
+            if (flags['run-dir']) {
+                const path = join(authoringPath(flags['run-dir']), 'setup.json');
+                const events = existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : [];
+                writePrivateJson(path, [...events, { at: new Date().toISOString(), type: 'setup_completed' }]);
+            }
+        }
+        browser = await openBrowser(method, config, flags['run-dir'], controller.signal);
+        const hostedModels = Object.values(config.models ?? {}).some((profile) => profile.backend === 'method') ? await hostedModelsFor(client) : undefined;
+        const result = await executeMethod(authoringPath(file), config, {
+            runDir: flags["run-dir"] ? authoringPath(flags["run-dir"]) : undefined,
+            agent: agent, inputs: json(flags.inputs), state: json(flags.state), resume: flags.resume, retry: flags.retry,
+            cacheFrom: flags.resume ? [] : recentRuns(authoringPath(flags['run-dir'])),
+            fresh: flags.fresh ? true : flags.rerun?.length ? flags.rerun.flatMap(step => step.split(',')).map(step => step.trim()).filter(Boolean) : undefined,
+            secrets: { ...resolveSecrets(Object.keys(method.secrets ?? {})), ...Object.fromEntries(Object.entries(runSecrets).filter(([key]) => Object.hasOwn(method.secrets ?? {}, key))) }, ...(hostedModels ? { hostedModels } : {}),
+            human: json(flags.human), signal: controller.signal,
+            ...(browser ? { connections: browser.connections } : {}),
+            sourceRoot, ...(classification ? { classification } : {}),
+            processPath: prepared.processPath,
+            prepareBundle: prepared.prepareBundle,
+            onStart: async ({ method, inputs }) => {
+                // A configured binding that the Method does not declare is not one of its connections.
+                await sync?.start(method, inputs, Object.fromEntries(Object.entries(config.environment ?? {}).filter(([key]) => method.environment?.[key]).map(([key, path]) => [key, { description: method.environment[key].description, path: String(path) }])));
+            },
+            onEvent: async (event) => { await onEvent?.(event); sync?.snapshot(); if (flags.verbose)
+                process.stderr.write(JSON.stringify(event) + "\n"); },
+        });
+        runFailed = !['completed', 'unconfirmed'].includes(result.status);
+        const synced = await sync?.finish();
+        const display = synced ? { ...result, dashboard_sync: synced } : result;
+        process.stdout.write(JSON.stringify(display, null, 2) + "\n");
+        // 3: every step finished, but an observer could not confirm an external change.
+        if (result.status !== "completed")
+            process.exitCode = { needs_input: 2, unconfirmed: 3 }[result.status] ?? 1;
+        return result;
+    }
+    catch (error) {
+        failure = error;
+        throw error;
+    }
+    finally {
+        try {
+            await browser?.close();
+        }
+        catch (error) {
+            if (!failure && !runFailed && !controller.signal.aborted)
+                throw error;
+        }
+        finally {
+            process.removeListener("SIGINT", stop);
+            process.removeListener("SIGTERM", stop);
+            await sync?.finish(failure);
+        }
+    }
+}

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

@@ -0,0 +1,17 @@
+export declare const MINIMUM_CODEX_VERSION = "0.153.0";
+export declare const MINIMUM_NODE_MAJOR = 22;
+export type Finding = {
+    ok: true;
+    detail: string;
+} | {
+    ok: false;
+    detail: string;
+};
+export declare function parseVersion(text: string): string | null;
+/** Negative when left is older than right. */
+export declare function compareVersions(left: string, right: string): number;
+export declare function checkNode(version?: string): Finding;
+/** Requires codex ${MINIMUM_CODEX_VERSION}+ with `codex exec --dangerously-bypass-approvals-and-sandbox`. */
+export declare function checkCodex(command?: string): Promise<Finding>;
+/** The default run directory root must accept a private file. */
+export declare function checkRunDirectory(root: string): Finding;