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

package/dist/packages/sdk/src/hosted-models.js

@@ -0,0 +1,81 @@
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+const Default = z.object({ provider: z.literal('openrouter'), model: z.string().trim().min(1) });
+// A model service that is briefly unavailable gets three attempts in all, like classification.
+const attempts = 3;
+/** Where a run's hosted model requests go: this computer's own OpenRouter key when it has one, else the account. */
+export async function hostedModelsFor(client) {
+    const { ownKeyEnv, ownKeyModels } = await import('./own-model-key.js');
+    const env = ownKeyEnv();
+    return env ? ownKeyModels(env) : managedModels(client);
+}
+/** Hosted models through the signed-in Method account. The account's model credit pays for them. */
+export function managedModels(client) {
+    return {
+        async model() {
+            return Default.parse(await client.request('/api/cli/models/default', 'GET', undefined, true, { stallMs: 30_000 })).model;
+        },
+        async request(body, signal) {
+            const request = { request_id: randomUUID(), request: body };
+            for (let attempt = 1;; attempt++) {
+                try {
+                    // No time limit: the server sends nothing until the model has answered, which can take minutes.
+                    return await client.request('/api/cli/models/respond', 'POST', request, true, { signal, stallMs: 0, maxResponseBytes: 4 * 1024 * 1024 });
+                }
+                catch (error) {
+                    if (attempt >= attempts || signal.aborted || !(error.status === 503 || error.status === 429) || error.code === 'model_credit_used')
+                        throw error;
+                    await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
+                }
+            }
+        },
+    };
+}
+const PrivateModels = z.object({ models: z.array(z.object({ id: z.string(), providers: z.array(z.string()) })), default: z.string().nullable().optional(), checked_at: z.string() });
+const day = 24 * 60 * 60_000;
+/**
+ * The hosted models that work with the private options (no training, zero data retention), from the server. The list
+ * is kept for a day under the Method cache; undefined when it cannot be fetched and no copy is saved.
+ */
+export async function privateModels(client, options = {}) {
+    const { methodCache } = await import('./prepare.js');
+    const { createHash } = await import('node:crypto');
+    const { existsSync, readFileSync } = await import('node:fs');
+    const { join } = await import('node:path');
+    const { writePrivateJson } = await import('./files.js');
+    const file = join(methodCache(), 'models', `private-${createHash('sha256').update(client.server).digest('hex').slice(0, 16)}.json`);
+    let saved;
+    try {
+        saved = existsSync(file) ? PrivateModels.parse(JSON.parse(readFileSync(file, 'utf8'))) : undefined;
+    }
+    catch {
+        saved = undefined;
+    }
+    if (saved && !options.refresh && Date.now() - Date.parse(saved.checked_at) < day)
+        return saved;
+    try {
+        const signal = options.waitMs ? AbortSignal.timeout(options.waitMs) : undefined;
+        const list = PrivateModels.parse(await client.request('/api/cli/models/private', 'GET', undefined, true, { stallMs: 15_000, ...(signal ? { signal } : {}) }));
+        writePrivateJson(file, list);
+        return list;
+    }
+    catch (error) {
+        if (options.refresh && !saved)
+            throw error;
+        return saved;
+    }
+}
+/** method models [--refresh] [--server URL]: the hosted models that work with the private options. */
+export async function modelsCommand(args, clientFactory) {
+    const { parseArgs } = await import('node:util');
+    const { DEFAULT_SERVER } = await import('./method-client.js');
+    const { values } = parseArgs({ args, options: { refresh: { type: 'boolean' }, server: { type: 'string' } } });
+    const client = clientFactory(values.server ?? DEFAULT_SERVER);
+    if (!client.token())
+        throw Error('Run method login first. The list of private models comes from your Method account.');
+    const list = await privateModels(client, { refresh: !!values.refresh });
+    if (!list)
+        throw Error('Method cannot be reached, and no saved list exists. Try again when online.');
+    process.stdout.write(JSON.stringify({ private: 'Each model below has a provider that does not train on requests and keeps no copy (zero data retention). Hosted runs use only those providers.',
+        default: list.default ?? null, checked_at: list.checked_at, models: list.models.map(model => model.id), use: 'Name a model ID on a step (model: provider/model) or in models:.' }, null, 2) + '\n');
+}

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

@@ -0,0 +1,55 @@
+import { type MethodClient } from './method-client.js';
+/** run_id: the run that the note is about; an account run ID for an account improvement, a run folder for one on this computer. */
+export type ImproveRequest = {
+    step_id?: string;
+    note?: string;
+    case_id?: string;
+    run_id?: string;
+};
+/** Runs a local Method file; the default is the runtime that `method run FILE` uses. */
+export type RunFile = (file: string, flags: Record<string, unknown>, syncFactory: undefined, onEvent: undefined, client: MethodClient, baseConfig: undefined, secrets: Record<string, string>) => Promise<{
+    status: string;
+    result?: unknown;
+}>;
+/** The SubmitProposal that improve.method returns, read from its result. */
+export type ImproveProposal = {
+    cause: string;
+    workflow: unknown | null;
+    evidence: {
+        kind: ProposalKind;
+        steps?: string[];
+        [key: string]: unknown;
+    };
+};
+type ProposalKind = 'change' | 'case' | 'rubric' | 'script' | 'none';
+/**
+ * Read the result of improve.method: {proposal: <SubmitProposal as JSON text>, kind, proposal_id}. A change has the
+ * proposed workflow; a case or rubric fix has case_suggestion; a script change has script_change; none has neither.
+ */
+export declare function readImproveResult(result: unknown): ImproveProposal;
+/**
+ * `method improve FILE`. A Method with account run data starts an improvement run in the account. A Method with device
+ * run data runs improve.method on this computer, so its run content stays here, and saves a local proposal.
+ */
+export declare function improveCommand(args: string[], clientFactory: (server: string) => MethodClient, run?: RunFile): Promise<boolean>;
+/** Download the published improve.method and its files into the Method cache, once per version. */
+export declare function cachedImproveMethod(client: MethodClient): Promise<{
+    file: string;
+    root: string;
+    version_id: string;
+}>;
+/**
+ * Run improve.method on this computer and save its result as a local proposal of the file. The run gets the signed-in
+ * key and server as its IMPROVE_API_KEY and IMPROVE_SERVER secrets, for this run only: they stay in memory.
+ */
+export declare function improveOnDevice(client: MethodClient, file: string, request: ImproveRequest, run?: RunFile): Promise<{
+    proposal_id: string;
+    source: string;
+    file: string;
+    kind: ProposalKind;
+    cause: string;
+    steps: string[];
+    proposal_file: string;
+    next: string;
+}>;
+export {};

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

@@ -0,0 +1,159 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { randomBytes, randomUUID } from 'node:crypto';
+import { parseArgs } from 'node:util';
+import { MethodPackageSchema, packageDigest, packagePath } from '../../contracts/src/method-package.js';
+import { loadWorkflow } from '../../workflow-language/src/validate.js';
+import { authoringPath, readDocument } from './authoring.js';
+import { DEFAULT_SERVER } from './method-client.js';
+import { fileHash } from './method-files.js';
+import { methodCache } from './prepare.js';
+import { writePrivateJson } from './files.js';
+import { currentVersion, methodContent, methodIdPattern } from './versions.js';
+import { localRuns, saveLocalProposal } from './proposals.js';
+const kinds = ['change', 'case', 'rubric', 'script', 'none'];
+/**
+ * Read the result of improve.method: {proposal: <SubmitProposal as JSON text>, kind, proposal_id}. A change has the
+ * proposed workflow; a case or rubric fix has case_suggestion; a script change has script_change; none has neither.
+ */
+export function readImproveResult(result) {
+    const value = result;
+    if (!value || typeof value.proposal !== 'string')
+        throw Error('The improvement run gave no proposal.');
+    let proposal;
+    try {
+        proposal = JSON.parse(value.proposal);
+    }
+    catch {
+        throw Error('The improvement run gave a proposal that is not JSON.');
+    }
+    if (typeof proposal?.cause !== 'string' || !proposal.cause.trim())
+        throw Error('The improvement proposal has no cause.');
+    const evidence = proposal.evidence;
+    if (!evidence || typeof evidence !== 'object' || !kinds.includes(evidence.kind))
+        throw Error('The improvement proposal has no known kind.');
+    if (value.kind !== undefined && value.kind !== evidence.kind)
+        throw Error(`The improvement run says kind ${String(value.kind)}, but its proposal is kind ${evidence.kind}.`);
+    if (evidence.kind === 'change' && (!proposal.workflow || typeof proposal.workflow !== 'object'))
+        throw Error('The improvement proposal is a change without a workflow.');
+    if ((evidence.kind === 'case' || evidence.kind === 'rubric') && !evidence.case_suggestion)
+        throw Error(`The improvement proposal is a ${evidence.kind} fix without case_suggestion.`);
+    if (evidence.kind === 'script' && !evidence.script_change)
+        throw Error('The improvement proposal is a script change without script_change.');
+    return { cause: proposal.cause.trim(), workflow: evidence.kind === 'change' ? proposal.workflow : null, evidence };
+}
+const nextStep = (file, id, kind) => ({
+    change: `Read the proposal, then run method apply ${file} ${id}. It does not publish.`,
+    case: `Run method apply ${file} ${id} to see the case to record.`,
+    rubric: `Run method apply ${file} ${id} to see the case rubric to fix.`,
+    script: `Run method apply ${file} ${id} to see the script change.`,
+    none: 'No safe change was found.',
+})[kind];
+const print = (value) => process.stdout.write(JSON.stringify(value, null, 2) + '\n');
+/**
+ * `method improve FILE`. A Method with account run data starts an improvement run in the account. A Method with device
+ * run data runs improve.method on this computer, so its run content stays here, and saves a local proposal.
+ */
+export async function improveCommand(args, clientFactory, run) {
+    const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { case: { type: 'string' }, note: { type: 'string' }, step: { type: 'string' }, server: { type: 'string' } } });
+    if (positionals.length !== 1)
+        throw Error('Use method improve FILE [--case ID] [--note TEXT] [--step ID].');
+    const file = authoringPath(positionals[0]), document = readDocument(file), workflow = loadWorkflow(methodContent(document));
+    if (values.step && !Object.hasOwn(workflow.steps, values.step))
+        throw Error(`Step ${values.step} is not in ${positionals[0]}.`);
+    if (values.case && !/^[a-z0-9][a-z0-9-]{0,79}$/.test(values.case))
+        throw Error('Use a case ID: lowercase letters, digits, and hyphens.');
+    if (values.note !== undefined && !values.note.trim())
+        throw Error('Write the correction after --note.');
+    const request = { ...(values.step ? { step_id: values.step } : {}), ...(values.note ? { note: values.note.trim() } : {}), ...(values.case ? { case_id: values.case } : {}) };
+    // A note is about the newest run of the Method on this computer.
+    const newest = request.note ? (await localRuns(file))[0] : undefined;
+    const client = clientFactory(values.server ?? DEFAULT_SERVER);
+    if (!client.token())
+        await client.login();
+    if (document.run_data !== 'device') {
+        const id = document.id;
+        if (typeof id !== 'string' || !methodIdPattern.test(id))
+            throw Error(`${positionals[0]} has no id: line, so your account has no version of it. Run method run ${positionals[0]} once while signed in, then run method improve again.`);
+        try {
+            const { improvement } = await client.request(`/api/methods/${encodeURIComponent(id)}/improvements`, 'POST', { ...request, ...(newest?.account_run_id ? { run_id: newest.account_run_id } : {}) });
+            return print({ improvement, url: `${client.server}/methods/${id}`, next: `Method's improvement agent is working; it takes a few minutes. Run method proposals ${positionals[0]} --wait (give the command 10 minutes): it returns with the proposal. Then show it to the user.` });
+        }
+        catch (error) {
+            if (error.code !== 'device_data')
+                throw error;
+        }
+    }
+    return print(await improveOnDevice(client, file, { ...request, ...(newest ? { run_id: newest.dir } : {}) }, run));
+}
+/** Download the published improve.method and its files into the Method cache, once per version. */
+export async function cachedImproveMethod(client) {
+    const saved = await client.request('/api/cli/improve/method');
+    if (!/^v_[a-f0-9]{32}$/.test(saved.version_id))
+        throw Error('Method sent an improvement Method without a version ID.');
+    const root = join(methodCache(), 'improve', saved.version_id);
+    mkdirSync(root, { recursive: true, mode: 0o700 });
+    if (saved.package) {
+        const pack = MethodPackageSchema.parse(saved.package);
+        if (packageDigest(saved.workflow, pack) !== pack.digest)
+            throw Error('The improvement Method package checksum does not match.');
+        for (const f of pack.files) {
+            const path = resolve(root, packagePath(f.path));
+            if (existsSync(path) && fileHash(readFileSync(path)) === f.sha256)
+                continue;
+            const bytes = await client.transfer(`/api/cli/improve/files/${f.sha256}`);
+            if (bytes.length !== f.size || fileHash(bytes) !== f.sha256)
+                throw Error(`The improvement Method file checksum does not match: ${f.path}`);
+            mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+            writeFileSync(`${path}.download`, bytes, { mode: 0o600 });
+            renameSync(`${path}.download`, path);
+        }
+    }
+    const file = join(root, 'improve.method');
+    writePrivateJson(file, saved.workflow);
+    return { file, root, version_id: saved.version_id };
+}
+/**
+ * Run improve.method on this computer and save its result as a local proposal of the file. The run gets the signed-in
+ * key and server as its IMPROVE_API_KEY and IMPROVE_SERVER secrets, for this run only: they stay in memory.
+ */
+export async function improveOnDevice(client, file, request, run) {
+    const token = client.token();
+    if (!token)
+        throw Error('Sign in with method login, then run method improve again.');
+    const secrets = { IMPROVE_API_KEY: token, IMPROVE_SERVER: client.server };
+    const improve = await cachedImproveMethod(client);
+    const runDir = join(methodCache(), 'runs', randomUUID());
+    const inputs = join(runDir, 'improve-inputs.json');
+    writePrivateJson(inputs, { method_file: file, case_id: request.case_id ?? '', note: request.note ?? '', step_id: request.step_id ?? '', grant_id: '', run_id: request.run_id ?? '', make_case: false });
+    const runFile = run ?? (await import('./current-runtime.js')).runCurrentFile;
+    process.stderr.write(`Improving ${file} on this computer. Its run content stays here.\n`);
+    // The run prints its own result; send it to stderr so that stdout holds only the proposal.
+    const write = process.stdout.write;
+    process.stdout.write = ((chunk, ...rest) => process.stderr.write(chunk, ...rest));
+    let result;
+    try {
+        result = await runFile(improve.file, { inputs, 'run-dir': runDir, workspace: improve.root, server: client.server }, undefined, undefined, client, undefined, secrets);
+    }
+    finally {
+        process.stdout.write = write;
+    }
+    if (result.status !== 'completed')
+        throw Error(`The improvement run stopped with status ${result.status}. Its records are in ${runDir}.`);
+    let submitted;
+    try {
+        submitted = readImproveResult(result.result);
+    }
+    catch (error) {
+        throw Error(`${error.message} Its records are in ${runDir}.`);
+    }
+    const id = `lp_${randomBytes(8).toString('hex')}`, document = readDocument(file);
+    const path = saveLocalProposal(file, {
+        id, method_id: typeof document.id === 'string' ? document.id : null, base_version_id: (await currentVersion(file))?.version_id ?? null,
+        status: 'open', cause: submitted.cause, evidence: submitted.evidence, created_at: new Date().toISOString(),
+        base_workflow: methodContent(document), proposed_workflow: submitted.workflow,
+        improvement: { version_id: improve.version_id, run_dir: runDir },
+    });
+    const kind = submitted.evidence.kind;
+    return { proposal_id: id, source: 'local', file, kind, cause: submitted.cause, steps: submitted.evidence.steps ?? [], proposal_file: path, next: nextStep(file, id, kind) };
+}

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

@@ -0,0 +1,13 @@
+export { runMethod } from "./run-method.js";
+export { methodSchema, configSchema } from "@withmethod/runtime/schema.js";
+export { loadWorkflow as loadMethod, serializeWorkflow as serializeMethod } from "../../workflow-language/src/validate.js";
+export { WorkflowSchema as MethodSchema, type Workflow as MethodDocument } from "../../workflow-language/src/schema.js";
+export { Method, MethodApiError, verifyWebhook, type AskEvent, type AskHandler, type StartRunOptions, type StartedRun, type ProductionRun, type RunStatus } from "./production.js";
+export { seal as sealRunData, open as openRunData, inputsDigest } from "./run-data.js";
+export { ProductionWorker, cliExecutor, type WorkerOptions, type WorkerResult } from "./worker.js";
+export { inspectRun } from "./inspect.js";
+export { InspectionSchema, copyInstructions } from "../../workflow-language/src/inspection.js";
+export { saveWorkflowLink as saveMethodLink, isWorkflowLink as isMethodLink } from "./link.js";
+export { reportProgress, relayCodexProgress, type ProgressUpdate } from "./progress.js";
+export { runProcess, type ProcessCommand } from "./process.js";
+export { checkedFile, writePrivateJson } from "./files.js";

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

@@ -0,0 +1,13 @@
+export { runMethod } from "./run-method.js";
+export { methodSchema, configSchema } from "@withmethod/runtime/schema.js";
+export { loadWorkflow as loadMethod, serializeWorkflow as serializeMethod } from "../../workflow-language/src/validate.js";
+export { WorkflowSchema as MethodSchema } from "../../workflow-language/src/schema.js";
+export { Method, MethodApiError, verifyWebhook } from "./production.js";
+export { seal as sealRunData, open as openRunData, inputsDigest } from "./run-data.js";
+export { ProductionWorker, cliExecutor } from "./worker.js";
+export { inspectRun } from "./inspect.js";
+export { InspectionSchema, copyInstructions } from "../../workflow-language/src/inspection.js";
+export { saveWorkflowLink as saveMethodLink, isWorkflowLink as isMethodLink } from "./link.js";
+export { reportProgress, relayCodexProgress } from "./progress.js";
+export { runProcess } from "./process.js";
+export { checkedFile, writePrivateJson } from "./files.js";

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

@@ -0,0 +1,6 @@
+import { type RunInspection } from "../../workflow-language/src/inspection.js";
+/** Export known run records. File previews are opt-in and must match saved hashes. */
+export declare function inspectRun(directory: string, options?: {
+    includeFiles?: boolean | "references"; /** Internal: only called synchronously by the owning SDK process. */
+    activeSnapshot?: boolean;
+}): RunInspection;

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

@@ -0,0 +1,17 @@
+import { inspectCurrentRun } from "./current-inspection.js";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { InspectionSchema } from "../../workflow-language/src/inspection.js";
+/** Export known run records. File previews are opt-in and must match saved hashes. */
+export function inspectRun(directory, options = {}) {
+    const requested = resolve(directory);
+    const root = realpathSync(requested);
+    if (!existsSync(join(root, "method.json")) && existsSync(join(root, "setup-inspection.json")) && existsSync(join(root, "request.json"))) {
+        const initial = JSON.parse(readFileSync(join(root, "setup-inspection.json"), "utf8"));
+        const failure = existsSync(join(root, "setup-error.json")) ? JSON.parse(readFileSync(join(root, "setup-error.json"), "utf8")) : null;
+        return InspectionSchema.parse({ ...initial, local_run_directory: root, ...(failure ? { status: 'needs_attention', error: failure.error } : {}), events: existsSync(join(root, "setup.json")) ? JSON.parse(readFileSync(join(root, "setup.json"), "utf8")) : [] });
+    }
+    if (existsSync(join(root, "method.json")))
+        return inspectCurrentRun(root, options.activeSnapshot, options.includeFiles);
+    throw Error("UNSUPPORTED_RUN: only current Method run records are supported.");
+}

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

@@ -0,0 +1,12 @@
+import type { Workflow } from "../../workflow-language/src/schema.js";
+export declare function isWorkflowLink(value: string): boolean;
+/**
+ * Download a signed workflow link and keep it as <id>.workflow in the directory.
+ * The saved file is reused when its bytes match; a different file is never overwritten.
+ */
+export declare function saveWorkflowLink(link: string, directory: string, fetchImpl?: typeof fetch): Promise<{
+    path: string;
+    reused: boolean;
+    source: string;
+    workflow: Workflow;
+}>;

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

@@ -0,0 +1,53 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { loadWorkflow } from "../../workflow-language/src/validate.js";
+export function isWorkflowLink(value) { return /^https?:\/\//iu.test(value); }
+const message = (error) => error instanceof Error ? error.message : String(error);
+async function failure(response) {
+    const text = await response.text().catch(() => "");
+    let code = "";
+    try {
+        code = String(JSON.parse(text).error ?? "");
+    }
+    catch { /* Not JSON. */ }
+    if (code === "link_expired")
+        return "LINK_EXPIRED: this link has expired. Open the method page, copy the command again, and run it.";
+    if (code === "link_invalid")
+        return "LINK_INVALID: this link is not valid. Copy the whole command from the method page and run it again.";
+    if (code === "workflow_source_not_ready")
+        return "WORKFLOW_NOT_READY: this method is still being built. When the method page shows it is ready, run the command again.";
+    if (response.status === 404)
+        return "LINK_NOT_FOUND: no method exists at this link. Copy the command from the method page again.";
+    return `LINK_FAILED: the method link returned ${response.status}${text.trim() ? `: ${text.trim().slice(0, 200)}` : ""}.`;
+}
+/**
+ * Download a signed workflow link and keep it as <id>.workflow in the directory.
+ * The saved file is reused when its bytes match; a different file is never overwritten.
+ */
+export async function saveWorkflowLink(link, directory, fetchImpl = fetch) {
+    let response;
+    try {
+        response = await fetchImpl(link, { headers: { accept: "application/json" } });
+    }
+    catch (error) {
+        throw new Error(`LINK_UNREACHABLE: could not download ${link}: ${message(error)}`);
+    }
+    if (!response.ok)
+        throw new Error(await failure(response));
+    const source = await response.text();
+    let workflow;
+    try {
+        workflow = loadWorkflow(source);
+    }
+    catch (error) {
+        throw new Error(`LINK_INVALID: the link did not return a valid method: ${message(error)}`);
+    }
+    const path = resolve(directory, `${workflow.name.toLowerCase().replace(/[^a-z0-9]+/g, "-")}.method`);
+    if (existsSync(path)) {
+        if (readFileSync(path, "utf8") === source)
+            return { path, reused: true, source, workflow };
+        throw new Error(`WORKFLOW_FILE_CONFLICT: ${path} already exists with different content. Move or rename it, then run the command again.`);
+    }
+    writeFileSync(path, source, { flag: "wx", mode: 0o600 });
+    return { path, reused: false, source, workflow };
+}

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

@@ -0,0 +1,24 @@
+import type { MethodSync } from "./method-sync.js";
+export declare function parse(args: string[]): {
+    values: {
+        server?: string;
+        agent?: string;
+        background?: boolean;
+        state?: string;
+        out?: string;
+        inputs?: string;
+        workspace?: string;
+        "run-dir"?: string;
+        fresh?: boolean;
+        rerun?: string[];
+        resume?: boolean;
+        human?: string;
+        retry?: string[];
+        "include-files"?: boolean;
+        verbose?: boolean;
+        help?: boolean;
+    };
+    positionals: string[];
+};
+export declare function run(target: string, flags: ReturnType<typeof parse>["values"], syncFactory?: () => MethodSync): Promise<void>;
+export declare function localMain(args?: string[]): Promise<void>;

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

@@ -0,0 +1,146 @@
+import { runCurrentFile } from "./current-runtime.js";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { executionLabel } from "../../workflow-language/src/schema.js";
+import { loadWorkflow } from "../../workflow-language/src/validate.js";
+import { renderPrompt } from "../../method-document/src/conversion-report.js";
+import { checkNode } from "./doctor.js";
+import { writePrivateJson } from "./files.js";
+import { isWorkflowLink, saveWorkflowLink } from "./link.js";
+import { inspectRun } from "./inspect.js";
+import { accountNeeds, checkConfiguration, resolveAgentProfiles } from './capabilities.js';
+import { MethodClient } from "./method-client.js";
+import { MethodSync as Sync } from "./method-sync.js";
+import { prepareVersion, savedLine, methodContent } from "./versions.js";
+import { Outbox, savedVersions } from "./outbox.js";
+import { readComputerSettings } from "./computer-settings.js";
+import { localSetup } from "./local-setup.js";
+import { readDocument } from "./authoring.js";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+const help = "Use method run, steps, prompt, inspect, or doctor. See method help.";
+export function parse(args) {
+    return parseArgs({ args, allowPositionals: true, options: {
+            server: { type: "string" }, agent: { type: "string" }, background: { type: "boolean" }, state: { type: "string" }, out: { type: "string" }, inputs: { type: "string" }, workspace: { type: "string" },
+            "run-dir": { type: "string" }, fresh: { type: "boolean" }, rerun: { type: "string", multiple: true }, resume: { type: "boolean" }, human: { type: "string" }, retry: { type: "string", multiple: true },
+            "include-files": { type: "boolean" }, verbose: { type: "boolean" }, help: { type: "boolean" }
+        } });
+}
+export async function run(target, flags, syncFactory) {
+    const path = isWorkflowLink(target) ? (await saveWorkflowLink(target, process.cwd())).path : resolve(target);
+    const legacy = (await import("./method-issues.js")).legacyIssues(path);
+    if (legacy.length)
+        throw Error(legacy.map(issue => `${issue.code}: ${issue.message} ${issue.fix}`).join('\n'));
+    loadWorkflow(methodContent(readDocument(path)));
+    const notice = await (await import("./quality.js")).casesNotice(path);
+    if (notice)
+        process.stderr.write(notice + "\n");
+    const update = await (await import("./update.js")).updateNotice();
+    if (update)
+        process.stderr.write(update + "\n");
+    (await import("./prepare.js")).pruneCachedRuns();
+    flags = { ...flags, "run-dir": flags["run-dir"] ?? join(process.cwd(), ".method-runs", randomUUID()) };
+    const account = syncFactory ? undefined : await accountSync(path, flags);
+    try {
+        await runCurrentFile(path, flags, syncFactory ?? account?.sync);
+    }
+    finally {
+        if (account) {
+            // The run's records were sent when it finished; this sends what is left and says where the version is.
+            await account.outbox.drain();
+            process.stderr.write(savedLine(account.client, account.outbox, account.version) + "\n");
+            // Script cards are made after the run, so that this run's inputs can be replayed. They never delay or fail it.
+            if (savedVersions(account.client.server)[account.version.version_id])
+                (await import("./explain.js")).startBackgroundExplain(path, account.version.workflow, account.version.version_id, account.client.server);
+        }
+    }
+}
+/**
+ * When this computer is signed in, each run of a local file belongs to the version of its content. Saving sends no
+ * request before the run: the version ID comes from the content, and the outbox uploads the version and the run's
+ * records while and after it runs. A save failure never stops the run. A run that needs the account starts sign-in.
+ */
+async function accountSync(path, flags) {
+    const client = new MethodClient(flags.server);
+    const runDir = resolve(flags["run-dir"]), linked = join(runDir, "method-sync.json");
+    try {
+        const outbox = new Outbox(client);
+        if (flags.resume) {
+            if (!existsSync(linked) || !client.token())
+                return undefined;
+            const state = JSON.parse(readFileSync(linked, "utf8"));
+            const version = await prepareVersion(client, outbox, path);
+            if (version.version_id !== state.version_id)
+                throw Error("The file changed since this run started. Resume runs the version it started with; its records stay on this computer.");
+            return { client, outbox, version, sync: () => new Sync(client, runDir, state.workflow_id, state.version_id, state.id, readDocument(path).run_data === "device", outbox) };
+        }
+        const method = readDocument(path);
+        const setup = await localSetup(path, flags);
+        const needs = accountNeeds(method, setup.config, setup.agent);
+        if (needs.classification && !client.token())
+            await client.login();
+        if (!client.token()) {
+            process.stderr.write(`Sign in to keep versions and runs in your account${needs.models ? " and to use hosted models" : ""}: method login\n`);
+            return undefined;
+        }
+        const version = await prepareVersion(client, outbox, path);
+        return { client, outbox, version, sync: () => new Sync(client, runDir, version.method_id, version.version_id, undefined, method.run_data === "device", outbox) };
+    }
+    catch (error) {
+        process.stderr.write(`Not saved to your Method account: ${error.message} The run continues on this computer.\n`);
+        return undefined;
+    }
+}
+export async function localMain(args = process.argv.slice(2)) {
+    const parsed = parse(args);
+    const [command, target] = parsed.positionals;
+    const flags = parsed.values;
+    if (flags.help || !command) {
+        process.stdout.write(help);
+        return;
+    }
+    if (command === "inspect") {
+        if (!target || parsed.positionals.length !== 2 || !flags.out)
+            throw new Error("Use method inspect RUN_DIRECTORY --out inspection.json.");
+        const output = resolve(flags.out);
+        if (existsSync(output))
+            throw new Error("INSPECTION_EXISTS: choose a new output file.");
+        writePrivateJson(output, inspectRun(target, { includeFiles: flags["include-files"] ?? false }));
+        process.stdout.write(`Saved run evidence: ${output}\nContains run inputs and results. Load it in the method viewer; no upload occurs.\n`);
+        return;
+    }
+    if (command === "doctor") {
+        if (parsed.positionals.length !== 1)
+            throw new Error(help);
+        const node = checkNode();
+        process.stdout.write(node.detail + "\n");
+        if (!node.ok) {
+            process.exitCode = 1;
+            return;
+        }
+        const config = { allow_local_processes: true }, agent = flags.agent ?? readComputerSettings().agent;
+        // Without a local agent, model steps use hosted models after method login; scripts need no agent.
+        try {
+            config.models = await resolveAgentProfiles({ steps: { agent: { do: { kind: 'agent', model: 'default' } } } }, config, agent);
+        }
+        catch (error) {
+            if (agent || error.code !== 'needs_input')
+                throw error;
+            process.stdout.write('No local agent found. Model steps use hosted models after method login.\n');
+        }
+        await checkConfiguration(config);
+        process.stdout.write('Runtime configuration checked. No method was run. Use method validate FILE to check the Method and its declared dependencies.\n');
+        return;
+    }
+    if (!["steps", "prompt", "run"].includes(command) || !target || parsed.positionals.length !== 2)
+        throw new Error(help);
+    if (command === "run")
+        return run(target, flags);
+    const workflow = loadWorkflow(methodContent(readDocument(resolve(target))));
+    if (command === "steps") {
+        process.stdout.write(Object.entries(workflow.steps).map(([id, step], index) => `${index + 1}. ${id}: ${step.name ?? id.replaceAll("_", " ")} (${executionLabel(step).toLowerCase()}; ${step.check ? "checked" : "unchecked"})`).join("\n") + "\n");
+        return;
+    }
+    process.stdout.write(renderPrompt(workflow) + "\n");
+}

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

@@ -0,0 +1,15 @@
+/**
+ * The runtime configuration for a local Method. No file beside the Method is read: models come from the Method,
+ * limits and tools from the Method (tools are copied into the configuration), connections and an own classifier key from this computer (computer.json), and
+ * runtimes from PATH. A files connection with no
+ * binding uses the folder of the same name beside the Method, when it exists.
+ * `base` is a configuration that the SDK made itself (a saved version's package); bindings still apply.
+ */
+export declare function localSetup(file: string, flags: {
+    workspace?: string;
+    agent?: string;
+}, base?: any): Promise<{
+    config: any;
+    sourceRoot: string;
+    agent: string | undefined;
+}>;