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

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

@@ -0,0 +1,294 @@
+/** Effect observation, recorded cases, the save gate, and library observers. */
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { createHash } from "node:crypto";
+import { parseArgs } from "node:util";
+import { observeRun, pendingRuns } from "@withmethod/runtime/observe.js";
+import { createCase, retireCase, listCases, testSuite } from "@withmethod/runtime/cases.js";
+import { authoringPath, editDocument, readDocument } from "./authoring.js";
+import { localSetup } from "./local-setup.js";
+import { resolveAgentProfiles, checkAgents, accountNeeds } from "./capabilities.js";
+import { hostedModelsFor, managedModels } from "./hosted-models.js";
+import { managedClassification } from "./classification-client.js";
+import { MethodClient } from "./method-client.js";
+import { prepareRuntime, methodCache } from "./prepare.js";
+import { writePrivateJson } from "./files.js";
+const print = (value) => process.stdout.write(JSON.stringify(value, null, 2) + "\n");
+const json = (path) => path ? JSON.parse(readFileSync(authoringPath(path), "utf8")) : undefined;
+/** The same runtime preparation as method run, without starting a run. Hosted models are used when signed in. */
+export async function preparedConfig(file, flags, options = {}) {
+    const setup = await localSetup(file, flags);
+    const method = readDocument(file);
+    const config = setup.config;
+    const client = new MethodClient();
+    let hostedModel;
+    const signedIn = (() => { try {
+        return !!client.token();
+    }
+    catch {
+        return false;
+    } })();
+    // A rubric judge is a model step too: without a local agent, a signed-in computer judges with the account's model.
+    const judge = options.judge && !setup.agent && !config.models?.judge;
+    if ((accountNeeds(method, config, setup.agent).models || judge) && signedIn) {
+        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, setup.agent, hostedModel);
+    if (judge && hostedModel)
+        config.models.judge = { backend: "method", model: hostedModel };
+    // Classify steps that run live use the account's classifier, as method run does.
+    const classification = accountNeeds(method, config, setup.agent).classification && signedIn ? managedClassification(client) : undefined;
+    if (classification)
+        config.classification = await classification.resolve(new AbortController().signal);
+    await checkAgents(config.models);
+    const prepared = await prepareRuntime(setup.sourceRoot, config, method);
+    const hostedModels = Object.values(prepared.config.models ?? {}).some((profile) => profile.backend === 'method') ? await hostedModelsFor(client) : undefined;
+    return { config: prepared.config, sourceRoot: setup.sourceRoot, processPath: prepared.processPath, prepareBundle: prepared.prepareBundle, ...(hostedModels ? { hostedModels } : {}), ...(classification ? { classification } : {}) };
+}
+/** Run directories that this computer's Method runs use by default. */
+export const defaultRunRoots = () => [resolve(".method-runs"), join(methodCache(), "runs")];
+export async function observeCommand(args) {
+    const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { pending: { type: "string", multiple: true }, sync: { type: "boolean" } } });
+    const dirs = positionals.map(dir => authoringPath(dir));
+    if (!dirs.length)
+        for (const root of values.pending ?? defaultRunRoots())
+            dirs.push(...await pendingRuns(authoringPath(root)));
+    const runs = [];
+    for (const dir of dirs) {
+        try {
+            const result = await observeRun(dir, {});
+            let dashboard;
+            // A late observation can change a synced run; upload the new record so the dashboard shows it.
+            if (result.changed && existsSync(join(dir, "method-sync.json")) && values.sync !== false) {
+                try {
+                    const { MethodSync } = await import("./method-sync.js");
+                    await MethodSync.retry(dir);
+                    dashboard = "saved";
+                }
+                catch (error) {
+                    dashboard = `not saved: ${error.message}. Retry with method sync ${dir}`;
+                }
+            }
+            runs.push({ run_dir: dir, status: result.status, changed: result.changed, observed: result.observed.map((e) => ({ effect: e.effect, verdict: e.verdict, reason: e.reason })),
+                next_observation_at: result.effects?.next_observation_at ?? null, ...(dashboard ? { dashboard } : {}) });
+        }
+        catch (error) {
+            runs.push({ run_dir: dir, error: error.message, code: error.code ?? "observe_failed" });
+        }
+    }
+    print({ runs, note: dirs.length ? undefined : "No run has open effects." });
+    if (runs.some(run => "error" in run))
+        process.exitCode = 1;
+}
+/** A fingerprint of a Method and the files it runs, to tell whether its cases were checked since the last change. */
+export function methodFingerprint(file) {
+    const folder = dirname(file), method = readDocument(file);
+    const parts = [readFileSync(file, "utf8")];
+    const paths = new Set(method.files ?? []);
+    for (const step of Object.values(method.steps ?? {})) {
+        for (const exec of [step.do, step.check])
+            if (exec?.kind === "run")
+                paths.add(exec.entrypoint);
+        for (const effect of Object.values(step.effects ?? {}))
+            for (const exec of [effect.observe, effect.judge])
+                if (exec?.kind === "run")
+                    paths.add(exec.entrypoint);
+    }
+    for (const path of [...paths].sort()) {
+        try {
+            parts.push(path, readFileSync(join(folder, path), "utf8"));
+        }
+        catch {
+            parts.push(path, "missing");
+        }
+    }
+    return createHash("sha256").update(JSON.stringify(parts)).digest("hex");
+}
+const checkedFile = (file) => join(methodCache(), "checked", createHash("sha256").update(file).digest("hex") + ".json");
+function recordChecked(file, report) {
+    mkdirSync(dirname(checkedFile(file)), { recursive: true, mode: 0o700 });
+    writePrivateJson(checkedFile(file), { file, fingerprint: methodFingerprint(file), passed: report.passed, cases: report.cases.length, at: new Date().toISOString() });
+}
+/** One line for method run when the Method changed since its cases last passed. */
+export async function casesNotice(file) {
+    const cases = (await listCases(file)).filter((c) => c.status === "active");
+    if (!cases.length)
+        return undefined;
+    let checked;
+    try {
+        checked = JSON.parse(readFileSync(checkedFile(file), "utf8"));
+    }
+    catch { /* never checked */ }
+    if (checked?.passed && checked.fingerprint === methodFingerprint(file))
+        return undefined;
+    return `${cases.length} case${cases.length === 1 ? "" : "s"} not checked since this Method changed: method test ${file}`;
+}
+/** The Method's declared secrets from this computer or the environment, as method run gives them. */
+async function declaredSecrets(file) {
+    const { resolveSecrets } = await import("./secrets.js");
+    return resolveSecrets(Object.keys(readDocument(file)?.secrets ?? {}));
+}
+/** Run the cases of a Method with the same preparation as method run. */
+export async function runCases(file, flags, options = {}) {
+    const prepared = await preparedConfig(file, flags, { judge: true });
+    const report = await testSuite(file, prepared.config, { ...options,
+        runOptions: { processPath: prepared.processPath, prepareBundle: prepared.prepareBundle, secrets: await declaredSecrets(file), ...(prepared.classification ? { classification: prepared.classification } : {}), ...(prepared.hostedModels ? { hostedModels: prepared.hostedModels } : {}), ...(flags.agent ? { agent: flags.agent } : {}) } });
+    if (!options.ids && !options.casesDir)
+        recordChecked(file, report);
+    return report;
+}
+export async function testCommand(args) {
+    const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { case: { type: "string", multiple: true }, new: { type: "string", multiple: true }, baseline: { type: "string" }, cases: { type: "string" }, workspace: { type: "string" }, agent: { type: "string" } } });
+    const file = positionals[0];
+    if (!file || positionals.length !== 1)
+        throw Error("Use method test FILE [--case ID]... [--baseline OLD_FILE] [--new ID]...");
+    const report = await runCases(authoringPath(file), values, { casesDir: values.cases ? authoringPath(values.cases) : undefined, ids: values.case,
+        baseline: values.baseline ? authoringPath(values.baseline) : undefined, newIds: values.new ?? [] });
+    print(report);
+    process.exitCode = report.passed ? 0 : 1;
+}
+/**
+ * The save gate: a version that breaks an approved case is refused, unless each failing case is accepted with a
+ * reason. Returns a line for the version's record.
+ */
+export async function caseGate(file, accept = [], reason) {
+    const cases = (await listCases(file)).filter((c) => c.status === "active");
+    if (!cases.length)
+        return { line: undefined, report: undefined };
+    // A save checks every case; say so first, because live model steps and judges take time and cost money.
+    process.stderr.write(`Checking ${cases.length} case${cases.length === 1 ? "" : "s"} before saving. Cases whose model steps changed run them live, up to three times each.\n`);
+    const report = await runCases(file, {});
+    const t = report.totals;
+    process.stderr.write(`Cases checked in ${Math.round(t.duration_ms / 1000)} s: ${t.live_model_steps} live model step${t.live_model_steps === 1 ? "" : "s"}, ${t.judge_calls} judge call${t.judge_calls === 1 ? "" : "s"}.\n`);
+    const failing = report.cases.filter((c) => !["pass", "fixed"].includes(c.verdict));
+    const unaccepted = failing.filter((c) => !accept.includes(c.id));
+    if (unaccepted.length)
+        throw Object.assign(Error(`This version breaks ${unaccepted.length} approved case${unaccepted.length === 1 ? "" : "s"}: ${unaccepted.map((c) => `${c.id} (${c.verdict}: ${c.note})`).join("; ")}. Fix the Method and run method test, or retire a case whose rule no longer applies with method case retire. To publish anyway, add --accept-failing-case ${unaccepted.map((c) => c.id).join(",")} with --reason.`), { code: "cases_failed" });
+    if (failing.length && !reason)
+        throw Error("Give --reason for accepting a failing case.");
+    return { report, line: failing.length ? `Cases: ${report.cases.length - failing.length} of ${report.cases.length} passed; accepted failing ${failing.map((c) => c.id).join(", ")}.` : `Cases: ${report.cases.length} of ${report.cases.length} passed.` };
+}
+export async function caseCommand(args) {
+    const text = { type: "string" };
+    const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { run: text, "passing-run": text, id: text, note: text, rubric: { type: "string", multiple: true }, ref: text, context: { type: "string", multiple: true }, expect: text,
+            observations: text, redact: text, runs: text, "min-pass": text, author: text, reason: text, by: text, cases: text, workspace: text, agent: text,
+            "retention-days": text, supersedes: { type: "string", multiple: true } } });
+    const [action, file, id] = positionals;
+    if (!file || !["new", "retire", "list"].includes(action ?? ""))
+        throw Error("Use method case new|retire|list FILE. See method help case new.");
+    const methodFile = authoringPath(file);
+    const casesDir = values.cases ? authoringPath(values.cases) : undefined;
+    const integer = (value, name) => { if (value === undefined)
+        return undefined; const n = Number(value); if (!Number.isSafeInteger(n))
+        throw Error(`${name} must be an integer.`); return n; };
+    if (action === "list")
+        return print((await listCases(methodFile, casesDir)).map(({ id, status, note, created, superseded_by, retention_until }) => ({ id, status, note, created, superseded_by, retention_until })));
+    if (action === "retire") {
+        if (!id || !values.reason)
+            throw Error("Supply the case ID and --reason.");
+        await retireCase(methodFile, id, { by: values.by ?? null, reason: values.reason, casesDir });
+        return print({ retired: id });
+    }
+    if (!values.id || !values.note || (!values.run && !values["passing-run"]))
+        throw Error('Supply --id, --note "the person\'s words", and --run (the run that went wrong) or --passing-run (a run that was right).');
+    if (!values.rubric?.length && !values.expect)
+        throw Error('Say what must be true with --rubric "plain sentence" (repeatable), or give --expect FILE.');
+    const prepared = await preparedConfig(methodFile, { ...(values.workspace ? { workspace: values.workspace } : {}), ...(values.agent ? { agent: values.agent } : {}) }, { judge: true });
+    const privacy = casesPrivacyWarning(methodFile, casesDir);
+    if (privacy)
+        process.stderr.write(privacy + "\n");
+    print(await createCase({ methodFile, runDir: values.run ? authoringPath(values.run) : undefined, passingRun: values["passing-run"] ? authoringPath(values["passing-run"]) : undefined,
+        id: values.id, note: values.note, author: values.author ?? null, rubric: values.rubric ?? [], ref: values.ref, context: values.context ?? [], expect: json(values.expect) ?? [],
+        observations: json(values.observations), redact: json(values.redact), runs: integer(values.runs, "--runs"), minPass: integer(values["min-pass"], "--min-pass"),
+        retentionDays: integer(values["retention-days"], "--retention-days"), supersedes: values.supersedes ?? [], casesDir, config: prepared.config,
+        options: { runOptions: { processPath: prepared.processPath, secrets: await declaredSecrets(methodFile), ...(prepared.classification ? { classification: prepared.classification } : {}), ...(prepared.hostedModels ? { hostedModels: prepared.hostedModels } : {}), ...(values.agent ? { agent: values.agent } : {}) } } }));
+}
+/**
+ * A case copies run data (inputs, outputs, written files) into cases/. When that folder would be committed to a Git
+ * repository, say so once per case: the repository may be shared.
+ */
+export function casesPrivacyWarning(methodFile, casesDir) {
+    const folder = casesDir ?? join(dirname(methodFile), "cases");
+    try {
+        execFileSync("git", ["-C", dirname(methodFile), "rev-parse", "--is-inside-work-tree"], { stdio: "ignore" });
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        execFileSync("git", ["-C", dirname(methodFile), "check-ignore", "-q", join(folder, "x", "recording.json")], { stdio: "ignore" });
+        return undefined;
+    }
+    catch { /* not ignored */ }
+    return `Note: ${folder} keeps copies of run data (inputs, outputs and written files) and is inside a Git repository. Commit it only if that data may be shared with everyone who can read the repository. To keep the data local, add this line to .gitignore: ${relative(dirname(methodFile), folder)}/*/recording.json, and the same for files/ and artifacts/; or use --redact.`;
+}
+const library = () => fileURLToPath(new URL("../observers/", import.meta.url));
+export function observerLibrary() {
+    return readdirSync(library()).filter(name => existsSync(join(library(), name, "observer.json"))).sort()
+        .map(name => ({ name, ...JSON.parse(readFileSync(join(library(), name, "observer.json"), "utf8")) }));
+}
+/** Copy a reviewed observer into the Method folder and declare the effect on a step. */
+export async function effectCommand(args) {
+    const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { observer: { type: "string" }, connection: { type: "string" }, intent: { type: "string" }, in: { type: "string", multiple: true }, set: { type: "string", multiple: true }, horizon: { type: "string" }, blocking: { type: "boolean" } } });
+    const [action, file, stepId, name] = positionals;
+    if (action === "list")
+        return print(observerLibrary().map(({ name, description, needs }) => ({ name, description, needs })));
+    if (action !== "add" || !file || !stepId || !name || !values.observer)
+        throw Error("Use method effect add FILE STEP NAME --observer OBSERVER [--connection NAME] [--in ALIAS=REF]... [--set KEY=VALUE]... or method effect list.");
+    const entry = observerLibrary().find(item => item.name === values.observer);
+    if (!entry)
+        throw Error(`Unknown observer ${values.observer}. Use method effect list.`);
+    const methodFile = authoringPath(file), folder = dirname(methodFile), target = join(folder, "observers", entry.name);
+    const connection = values.connection ?? entry.connection.name;
+    const bindings = Object.fromEntries((values.in ?? []).map(pair => { const at = pair.indexOf("="); if (at < 1)
+        throw Error("Use --in ALIAS=REFERENCE."); return [pair.slice(0, at), pair.slice(at + 1)]; }));
+    for (const required of entry.inputs ?? [])
+        if (!Object.hasOwn(bindings, required.alias))
+            throw Error(`The ${entry.name} observer needs --in ${required.alias}=REFERENCE: ${required.description}`);
+    const settings = { connection, ...Object.fromEntries((values.set ?? []).map(pair => { const at = pair.indexOf("="); if (at < 1)
+            throw Error("Use --set KEY=VALUE."); return [pair.slice(0, at), pair.slice(at + 1)]; })) };
+    // Fill the observer's own placeholders; {token} and {inputs.NAME} stay for the observer to fill at run time.
+    const observerArgs = (entry.effect.args ?? []).map((arg) => arg.replace(/\{([a-z_]+)\}/g, (match, key) => {
+        if (key === "token")
+            return match;
+        if (!Object.hasOwn(settings, key))
+            throw Error(`The ${entry.name} observer needs --set ${key}=VALUE. ${entry.needs}`);
+        return settings[key];
+    }));
+    const result = editDocument(methodFile, doc => {
+        const step = doc.steps?.[stepId];
+        if (!step)
+            throw Error(`Step not found: ${stepId}.`);
+        if (!(step.changes ?? []).some((c) => c.startsWith("environment.")))
+            throw Error(`${stepId} changes no environment. Declare the changed connection in changes first.`);
+        if (doc.format !== "method/3.4")
+            doc.format = "method/3.4";
+        doc.environment ??= {};
+        const existing = doc.environment[connection];
+        if (existing && existing.role !== "observer")
+            throw Error(`Environment ${connection} exists and is not an observer connection. Choose --connection NAME.`);
+        doc.environment[connection] = { type: entry.connection.type, description: entry.connection.description, role: "observer" };
+        const path = (file) => relative(folder, join(target, file)).split("\\").join("/");
+        step.effects = { ...step.effects, [name]: {
+                intent: values.intent ?? entry.effect.intent, in: bindings,
+                observe: { kind: "run", runtime: entry.effect.observe_runtime ?? "node", entrypoint: path("fetch.mjs"), ...(observerArgs.length ? { args: observerArgs } : {}) },
+                judge: { kind: "run", runtime: "node", entrypoint: path("judge.mjs") }, fixtures: path("fixtures"),
+                schedule: { ...entry.effect.schedule, ...(values.horizon ? { horizon: values.horizon } : {}) }, confirm: entry.effect.confirm,
+                ...(values.blocking ? { blocking: true } : {}),
+            } };
+        return doc;
+    });
+    if (!existsSync(target)) {
+        mkdirSync(dirname(target), { recursive: true });
+        cpSync(join(library(), entry.name), target, { recursive: true });
+    }
+    print({ file: methodFile, step: stepId, effect: name, observer: entry.name, copied_to: target, connection,
+        setup: entry.setup, workflow: result });
+}

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

@@ -0,0 +1,5 @@
+import { type AttachedFile } from "../../workflow-language/src/result-files.js";
+import { type Workflow } from "../../workflow-language/src/schema.js";
+import type { RunInspection } from "../../workflow-language/src/inspection.js";
+/** Read only declared file outputs and explicitly listed website assets. Never scan a directory. */
+export declare function attachResultFiles(workflow: Workflow, invocations: RunInspection["invocations"], roots: string[], artifactRoot?: string, referencesOnly?: boolean): AttachedFile[];

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

@@ -0,0 +1,149 @@
+import { effectiveOutputs } from '../../workflow-language/src/schema.js';
+import { gzipSync, gunzipSync } from "node:zlib";
+import { Buffer } from "node:buffer";
+import { dirname, join, resolve, sep, extname } from "node:path";
+import { checkedFile } from "./files.js";
+import { WebsiteManifestSchema, MAX_RESULT_FILES, MAX_RESULT_BYTES, MAX_RESULT_TRANSFER_BYTES, } from "../../workflow-language/src/result-files.js";
+import { FileArtifactSchema, } from "../../workflow-language/src/schema.js";
+const mediaTypes = {
+    ".html": "text/html",
+    ".htm": "text/html",
+    ".md": "text/markdown",
+    ".txt": "text/plain",
+    ".json": "application/json",
+    ".csv": "text/csv",
+    ".css": "text/css",
+    ".js": "text/javascript",
+    ".mjs": "text/javascript",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".pdf": "application/pdf",
+    ".zip": "application/zip",
+    ".woff2": "font/woff2",
+};
+/** Read only declared file outputs and explicitly listed website assets. Never scan a directory. */
+export function attachResultFiles(workflow, invocations, roots, artifactRoot, referencesOnly = false) {
+    const files = [], seen = new Set();
+    let remaining = MAX_RESULT_BYTES, transferRemaining = MAX_RESULT_TRANSFER_BYTES;
+    const observed_at = new Date().toISOString();
+    const attach = (reference, title, mediaType) => {
+        const identity = JSON.stringify(reference);
+        if (seen.has(identity)) {
+            const file = files.find((file) => file.path === reference.path && file.sha256 === reference.sha256);
+            return {
+                file,
+                ...(file.data !== undefined
+                    ? { bytes: file.encoding === "gzip" ? gunzipSync(Buffer.from(file.data, "base64"), { maxOutputLength: MAX_RESULT_BYTES }) : Buffer.from(file.data, "base64") }
+                    : {}),
+            };
+        }
+        if (files.length >= MAX_RESULT_FILES)
+            return;
+        seen.add(identity);
+        const file = {
+            ...reference,
+            title: title.slice(0, 160),
+            media_type: mediaType ??
+                mediaTypes[extname(reference.path).toLowerCase()] ??
+                "application/octet-stream",
+            status: "unavailable",
+            observed_at,
+        };
+        files.push(file);
+        try {
+            if (files.length > MAX_RESULT_FILES || remaining <= 0 || transferRemaining <= 0)
+                throw Error("The run attachment limit was reached (20,000 files, 100 MB decoded, or 20 MB transferred).");
+            const localPath = artifactRoot
+                ? resolve(artifactRoot, reference.path)
+                : reference.path;
+            if (artifactRoot &&
+                (!localPath.startsWith(artifactRoot + sep) ||
+                    reference.path.startsWith("/")))
+                throw Error("The output is outside the run artifacts folder.");
+            const result = checkedFile({ ...reference, path: localPath }, roots);
+            if (result.bytes.length > remaining)
+                throw Error("The file exceeds the remaining 100 MB run attachment limit.");
+            if (referencesOnly) {
+                remaining -= result.bytes.length;
+                file.status = "verified";
+                file.bytes = result.bytes.length;
+                return { file, bytes: result.bytes };
+            }
+            const compressed = gzipSync(result.bytes);
+            const useGzip = compressed.length < result.bytes.length;
+            const payload = useGzip ? compressed : result.bytes;
+            if (payload.length > transferRemaining)
+                throw Error("The file exceeds the remaining 20 MB transfer limit.");
+            transferRemaining -= payload.length;
+            remaining -= result.bytes.length;
+            file.status = "verified";
+            file.bytes = result.bytes.length;
+            file.data = Buffer.from(payload).toString("base64");
+            if (useGzip)
+                file.encoding = "gzip";
+            // Text is decoded by the reader from the attached bytes, avoiding duplicate payloads.
+            return { file, bytes: result.bytes };
+        }
+        catch (error) {
+            file.reason =
+                error instanceof Error
+                    ? error.message
+                    : "The file could not be attached.";
+            return { file };
+        }
+    };
+    const visit = (shape, value, title) => {
+        const def = typeof shape === "string" ? { type: shape } : shape;
+        if (def.type === "file") {
+            const ref = FileArtifactSchema.safeParse(value);
+            if (!ref.success)
+                return;
+            const attached = attach(ref.data, title);
+            if (!attached)
+                return;
+            if ("format" in def &&
+                def.format === "method-website" &&
+                attached.bytes) {
+                try {
+                    const manifest = WebsiteManifestSchema.parse(JSON.parse(new TextDecoder().decode(attached.bytes)));
+                    const members = manifest.files.map((member) => ({
+                        ...member,
+                        path: join(dirname(ref.data.path), member.path),
+                    }));
+                    attached.file.title = manifest.title;
+                    attached.file.media_type = "application/vnd.method.website+json";
+                    attached.file.website = {
+                        entrypoint: join(dirname(ref.data.path), manifest.entrypoint),
+                        files: members,
+                    };
+                    for (const member of members)
+                        attach({ path: member.path, sha256: member.sha256 }, member.path, member.media_type);
+                }
+                catch (error) {
+                    attached.file.reason = "The website file list is invalid: " + (error instanceof Error ? error.message : String(error));
+                }
+            }
+        }
+        else if (def.type === "record" &&
+            "fields" in def &&
+            value &&
+            typeof value === "object") {
+            for (const [name, child] of Object.entries(def.fields ?? {}))
+                visit(child, value[name], name.replaceAll("_", " "));
+        }
+        else if (def.type === "list" && Array.isArray(value)) {
+            for (const item of value)
+                if ("fields" in def && def.fields)
+                    visit({ type: "record", fields: def.fields }, item, title);
+                else if ("items" in def && def.items)
+                    visit(def.items, item, title);
+        }
+    };
+    for (const row of Object.values(invocations))
+        for (const [name, shape] of Object.entries(effectiveOutputs(workflow.steps[row.step_id] ?? {})))
+            visit(shape, row.outputs?.[name], name.replaceAll("_", " "));
+    return files;
+}

package/dist/packages/sdk/src/result-transfer.d.ts

@@ -0,0 +1,21 @@
+import type { MethodClient } from './method-client.js';
+import type { AttachedFile } from '../../workflow-language/src/result-files.js';
+/** Transfer declared artifacts independently; server receipts make retries resumable. */
+export declare function transferResults(client: MethodClient, directory: string, files: AttachedFile[]): Promise<{
+    stored: boolean;
+    sha256: string;
+    status: "verified" | "unavailable";
+    path: string;
+    observed_at: string;
+    bytes?: number | undefined;
+    media_type?: string | undefined;
+    title?: string | undefined;
+    website?: {
+        files: {
+            sha256: string;
+            path: string;
+            media_type: string;
+        }[];
+        entrypoint: string;
+    } | undefined;
+}[]>;

package/dist/packages/sdk/src/result-transfer.js

@@ -0,0 +1,37 @@
+import { join } from 'node:path';
+import { checkedFile } from './files.js';
+/** Transfer declared artifacts independently; server receipts make retries resumable. */
+export async function transferResults(client, directory, files) {
+    const local = files.filter(f => !f.stored);
+    const invalid = local.find(f => f.status !== 'verified');
+    if (invalid)
+        throw Error(`Result upload pending: ${invalid.path}: ${invalid.reason}`);
+    const unique = [...new Map(local.map(f => [f.sha256, f])).values()];
+    const missing = new Set();
+    for (let offset = 0; offset < unique.length; offset += 256) {
+        const result = await client.request('/api/cli/result-files/missing', 'POST', {
+            files: unique.slice(offset, offset + 256).map(f => ({ sha256: f.sha256, bytes: f.bytes })),
+        });
+        result.missing.forEach(hash => missing.add(hash));
+    }
+    const send = async (file) => {
+        const bytes = checkedFile({ path: join(directory, 'artifacts', file.path), sha256: file.sha256 }, [join(directory, 'artifacts')]).bytes;
+        await client.transfer(`/api/cli/result-files/${file.sha256}`, bytes);
+    };
+    const needed = unique.filter(f => missing.has(f.sha256));
+    // Avoid concurrent large buffers on the receiving Worker.
+    for (const file of needed.filter(f => (f.bytes ?? 0) > 4_000_000))
+        await send(file);
+    const queue = needed.filter(f => (f.bytes ?? 0) <= 4_000_000);
+    let next = 0;
+    const results = await Promise.allSettled(Array.from({ length: Math.min(6, queue.length) }, async () => {
+        while (next < queue.length) {
+            const file = queue[next++];
+            await send(file);
+        }
+    }));
+    const failed = results.find((result) => result.status === "rejected");
+    if (failed)
+        throw failed.reason;
+    return files.map(({ data, encoding, text, reason, ...file }) => ({ ...file, stored: true }));
+}

package/dist/packages/sdk/src/run-data.d.ts

@@ -0,0 +1,11 @@
+export type SealedKind = "inputs" | "question" | "answer" | "snapshot";
+/** Seal a JSON value. */
+export declare function seal(credential: string, kind: SealedKind, methodId: string, value: unknown): string;
+/** Open a sealed JSON value. Fails with code wrong_key when another credential sealed it. */
+export declare function open<T = unknown>(credential: string, kind: SealedKind, methodId: string, sealed: string): T;
+export declare function sealBytes(credential: string, methodId: string, bytes: Uint8Array): Buffer;
+export declare function openBytes(credential: string, methodId: string, sealed: Uint8Array): Buffer;
+/** The idempotency digest of sealed inputs: equal inputs give an equal digest, and the server cannot reverse it. */
+export declare function inputsDigest(credential: string, methodId: string, inputs: unknown): string;
+/** `method __run-data seal|open KIND METHOD_ID`: the Python library seals with this (stdin JSON in, stdout out). */
+export declare function runDataCommand(args: string[]): Promise<void>;

package/dist/packages/sdk/src/run-data.js

@@ -0,0 +1,80 @@
+import { createCipheriv, createDecipheriv, createHmac, hkdfSync, randomBytes } from "node:crypto";
+// Sealed run content for device runs in the production queue. The key is derived on the client from the credential
+// that starts the run (a service key, or the CLI sign-in): HKDF-SHA256 of the credential, then AES-256-GCM. The server
+// has only the SHA-256 of the credential, so it cannot derive the key and cannot open what it stores.
+//
+// Text:  "v1." + base64url(12-byte IV) + "." + base64url(ciphertext and 16-byte tag)
+// Bytes: "MRS1" + IV + tag + ciphertext (a run folder)
+// The additional data names what is sealed and for which Method, so one sealed value cannot stand in for another.
+const SALT = Buffer.from("method-run-data/1");
+const encryptionKey = (credential) => Buffer.from(hkdfSync("sha256", Buffer.from(credential, "utf8"), SALT, "aes-256-gcm", 32));
+const digestKey = (credential) => Buffer.from(hkdfSync("sha256", Buffer.from(credential, "utf8"), SALT, "hmac-sha256", 32));
+const aad = (kind, methodId) => Buffer.from(`method-run-data/1:${kind}:${methodId}`);
+/** Seal a JSON value. */
+export function seal(credential, kind, methodId, value) {
+    const iv = randomBytes(12), cipher = createCipheriv("aes-256-gcm", encryptionKey(credential), iv);
+    cipher.setAAD(aad(kind, methodId));
+    const body = Buffer.concat([cipher.update(JSON.stringify(value), "utf8"), cipher.final(), cipher.getAuthTag()]);
+    return `v1.${iv.toString("base64url")}.${body.toString("base64url")}`;
+}
+/** Open a sealed JSON value. Fails with code wrong_key when another credential sealed it. */
+export function open(credential, kind, methodId, sealed) {
+    const match = sealed.match(/^v1\.([A-Za-z0-9_-]{16})\.([A-Za-z0-9_-]+)$/);
+    if (!match)
+        throw Object.assign(Error("This is not sealed run data."), { code: "invalid_sealed" });
+    const body = Buffer.from(match[2], "base64url");
+    try {
+        const decipher = createDecipheriv("aes-256-gcm", encryptionKey(credential), Buffer.from(match[1], "base64url"));
+        decipher.setAAD(aad(kind, methodId));
+        decipher.setAuthTag(body.subarray(body.length - 16));
+        return JSON.parse(Buffer.concat([decipher.update(body.subarray(0, body.length - 16)), decipher.final()]).toString("utf8"));
+    }
+    catch {
+        throw Object.assign(Error("This run's content was sealed with another key. Use the METHOD_API_KEY that started the run."), { code: "wrong_key" });
+    }
+}
+export function sealBytes(credential, methodId, bytes) {
+    const iv = randomBytes(12), cipher = createCipheriv("aes-256-gcm", encryptionKey(credential), iv);
+    cipher.setAAD(aad("snapshot", methodId));
+    const body = Buffer.concat([cipher.update(bytes), cipher.final()]);
+    return Buffer.concat([Buffer.from("MRS1"), iv, cipher.getAuthTag(), body]);
+}
+export function openBytes(credential, methodId, sealed) {
+    const data = Buffer.from(sealed);
+    if (data.subarray(0, 4).toString("latin1") !== "MRS1")
+        throw Object.assign(Error("This is not a sealed run folder."), { code: "invalid_sealed" });
+    try {
+        const decipher = createDecipheriv("aes-256-gcm", encryptionKey(credential), data.subarray(4, 16));
+        decipher.setAAD(aad("snapshot", methodId));
+        decipher.setAuthTag(data.subarray(16, 32));
+        return Buffer.concat([decipher.update(data.subarray(32)), decipher.final()]);
+    }
+    catch {
+        throw Object.assign(Error("This run folder was sealed with another key. Use the METHOD_API_KEY that started the run."), { code: "wrong_key" });
+    }
+}
+/** The idempotency digest of sealed inputs: equal inputs give an equal digest, and the server cannot reverse it. */
+export function inputsDigest(credential, methodId, inputs) {
+    return createHmac("sha256", digestKey(credential)).update(`${methodId}\n${canonical(inputs)}`).digest("hex");
+}
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    if (value && typeof value === "object")
+        return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonical(value[key])}`).join(",")}}`;
+    return JSON.stringify(value);
+}
+/** `method __run-data seal|open KIND METHOD_ID`: the Python library seals with this (stdin JSON in, stdout out). */
+export async function runDataCommand(args) {
+    const [action, kind, methodId] = args;
+    const credential = process.env.METHOD_API_KEY;
+    if (!credential || !methodId || !["inputs", "question", "answer"].includes(kind ?? "") || !["seal", "open", "digest"].includes(action ?? ""))
+        throw Error("Use METHOD_API_KEY=… method __run-data seal|open|digest inputs|question|answer METHOD_ID < VALUE");
+    let text = "";
+    for await (const chunk of process.stdin)
+        text += chunk;
+    const result = action === "seal" ? seal(credential, kind, methodId, JSON.parse(text))
+        : action === "digest" ? inputsDigest(credential, methodId, JSON.parse(text))
+            : open(credential, kind, methodId, text.trim());
+    process.stdout.write(JSON.stringify(result) + "\n");
+}

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

@@ -0,0 +1,2 @@
+/** Execute current Methods with the single public runtime. */
+export { runMethod } from "@withmethod/runtime/runner.js";

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

@@ -0,0 +1,2 @@
+/** Execute current Methods with the single public runtime. */
+export { runMethod } from "@withmethod/runtime/runner.js";

package/dist/packages/sdk/src/run-saved.d.ts

@@ -0,0 +1,5 @@
+import { MethodClient } from './method-client.js';
+import type { parse } from './local-cli.js';
+/** A run whose steps all finished: completed, or unconfirmed (an external change could not be confirmed). */
+export declare const finishedRun: (status: string) => status is "completed" | "unconfirmed";
+export declare function runSaved(saved: any, flags: ReturnType<typeof parse>['values'], client: MethodClient): Promise<any>;