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

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

@@ -0,0 +1,192 @@
+/**
+ * The issues of a local Method: the runtime's methodIssues (format and code checks, with this computer's secret
+ * values and the files that will be uploaded), the model privacy check, and the model checks. Only errors block.
+ */
+import { existsSync, mkdirSync, openSync, closeSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { basename, dirname, join, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { randomUUID } from 'node:crypto';
+import { methodIssues } from '@withmethod/runtime/document.js';
+import { isModelId } from '@withmethod/runtime/semantics.js';
+import { parseDocumentValue } from '../../workflow-language/src/validate.js';
+import { authoringPath } from './authoring.js';
+import { changedSteps, checkTargets, checks, checksDir, evaluateTarget, modelIssues, runChecks, shownChecks } from './model-checks.js';
+import { packageFileNames } from './method-files.js';
+import { MethodClient } from './method-client.js';
+/** A .env file holds secret values: issue checks never read it. */
+export const refused = (path) => /^\.env(\.|$)/.test(basename(path));
+/** A file of the Method folder as text; undefined when it is missing, outside the folder, or not allowed. */
+export function folderReader(file) {
+    const root = realpathSync(dirname(resolve(file)));
+    return (path) => {
+        try {
+            const target = realpathSync(resolve(root, path));
+            if (!target.startsWith(root + sep) || refused(target))
+                return undefined;
+            return readFileSync(target, 'utf8');
+        }
+        catch {
+            return undefined;
+        }
+    };
+}
+function folderBytes(file, names) {
+    const root = realpathSync(dirname(resolve(file))), files = {};
+    for (const name of names) {
+        try {
+            const target = realpathSync(resolve(root, name));
+            if (target.startsWith(root + sep) && !refused(target))
+                files[name] = readFileSync(target);
+        }
+        catch { /* A missing file is reported by preflight. */ }
+    }
+    return files;
+}
+/** The hosted model ID that each call or agent step (or agent check) names, with the field. */
+export function hostedModelUses(method) {
+    const uses = [];
+    for (const [id, step] of Object.entries(method.steps ?? {}))
+        for (const [field, exec] of [['do.model', step.do], ['check.model', step.check]]) {
+            if (!exec || !['call', 'agent'].includes(exec.kind) || typeof exec.model !== 'string')
+                continue;
+            const named = method.models?.[exec.model];
+            // A local-agent entry ({agent: codex | claude}) is not a hosted model.
+            if (named?.agent)
+                continue;
+            const model = typeof named === 'string' ? named : typeof named?.model === 'string' ? named.model : isModelId(exec.model) ? exec.model : undefined;
+            if (model)
+                uses.push({ step: id, field, model, ...(named ? { name: exec.model } : {}) });
+        }
+    return uses;
+}
+/** model_not_private: a step names a hosted model that has no private endpoint. Deterministic from the saved list. */
+export function privacyIssues(method, privateIds) {
+    return hostedModelUses(method).filter(use => !privateIds.has(use.model)).map(use => ({
+        code: 'model_not_private', level: 'warning', step: use.step, field: use.field,
+        message: `${use.step} uses ${use.model}${use.name ? ` (models.${use.name})` : ''}, which no provider serves with the private options (no training, zero data retention), so hosted runs refuse it.`,
+        fix: 'Choose a model from method models.',
+    }));
+}
+/**
+ * legacy_runtime_json and legacy_sidecar: an old runtime.json or FILE.method.json is next to the Method. Method files
+ * no longer read them, so a run would lose their settings. The fix says what to move where; nothing is changed here.
+ */
+export function legacyIssues(file) {
+    const path = authoringPath(file), folder = dirname(path), issues = [];
+    if (existsSync(join(folder, 'runtime.json')))
+        issues.push({ code: 'legacy_runtime_json', level: 'error',
+            message: `runtime.json is next to ${basename(path)}. Methods no longer read runtime.json, so its settings would be lost.`,
+            fix: 'Move each part into the Method, then delete runtime.json. models -> top-level models: (NAME: provider/model, or {model, max_output_tokens, reasoning_effort}); a profile with backend codex or claude -> NAME: {agent: codex|claude, model, reasoning_effort} (keep its model and reasoning_effort). limits -> top-level limits:. step_defaults -> limits.step. tools -> top-level tools:. environment paths -> method bind ID NAME --file FOLDER (a folder beside the Method with the connection name needs nothing). classification.api_key_env -> method config model-key. runtimes and allow_local_processes need nothing. Set format: method/3.4 and remove runtime.json from files:.' });
+    if (existsSync(`${path}.method.json`))
+        issues.push({ code: 'legacy_sidecar', level: 'error',
+            message: `${basename(path)}.method.json is next to ${basename(path)}. Methods keep their ID in the file now.`,
+            fix: `Put its workflow_id as the line id: wf_... directly after format: method/3.4 in ${basename(path)}, then delete ${basename(path)}.method.json.` });
+    return issues;
+}
+/**
+ * All issues of a Method file. With changed, model checks run for the steps whose text changed since the last
+ * validate (in parallel, waitMs in all; the rest finish in the background). Without it, only cached answers are used.
+ */
+export async function collectIssues(file, options = {}) {
+    const path = authoringPath(file), text = readFileSync(path, 'utf8');
+    const legacy = legacyIssues(path), first = [...legacy, ...methodIssues(text)];
+    if (first.some(issue => issue.level === 'error'))
+        return { issues: first, pending: 0, notChecked: [], invalid: true };
+    const method = parseDocumentValue(text), read = folderReader(path);
+    const { deviceSecretValues, resolveSecrets } = await import('./secrets.js');
+    const declared = Object.keys(method.secrets ?? {});
+    const client = options.client ?? new MethodClient();
+    const signedIn = (() => { try {
+        return !!client.token();
+    }
+    catch {
+        return false;
+    } })();
+    const changed = options.phase === 'publish' ? undefined : changedSteps(path, method, read);
+    const targets = checkTargets(method, read);
+    const provider = signedIn ? (await import('./classification-client.js')).managedClassification(client) : undefined;
+    const run = changed ? targets.filter(target => changed.has(target.step)) : [];
+    const [{ done, pending }, list] = await Promise.all([
+        runChecks(provider, run, options.waitMs ?? 3000),
+        signedIn ? (await import('./hosted-models.js')).privateModels(client, { waitMs: options.waitMs ?? 3000 }).catch(() => undefined) : Promise.resolve(undefined),
+    ]);
+    // Unchanged steps use the answers saved earlier; a missing one is not computed now.
+    const { cached } = await import('./model-checks.js');
+    const results = [...done, ...targets.filter(target => !run.includes(target)).flatMap(target => { const hit = cached(target.key); return hit ? [hit] : []; })];
+    if (pending.length && provider && options.background !== false)
+        finishInBackground(pending);
+    const computed = new Set(results.map(result => `${result.check} ${result.step}`));
+    // Shadow checks and checks without an answer give no accept_unused note.
+    const notChecked = [...Object.keys(checks).filter(code => !shownChecks.includes(code) || targets.some(target => target.check === code && !computed.has(`${code} ${target.step}`))),
+        ...(list ? [] : ['model_not_private'])];
+    const issues = methodIssues(text, {
+        secretValues: deviceSecretValues(declared), availableSecrets: Object.keys(resolveSecrets(declared)), phase: 'validate',
+        files: folderBytes(path, packageFileNames(dirname(path), method)),
+        issues: [...modelIssues(results), ...(list ? privacyIssues(method, new Set(list.models.map(model => model.id))) : [])],
+        notChecked,
+    });
+    return { issues, ...(changed ? { changed } : {}), pending: provider ? pending.length : 0, notChecked };
+}
+/** Finish the checks that did not answer in time in a detached process, so the next validate has their answers. */
+function finishInBackground(targets) {
+    try {
+        if (process.env.METHOD_NO_BACKGROUND_CHECKS === '1')
+            return;
+        const dir = join(checksDir(), 'pending');
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const file = join(dir, `${randomUUID()}.json`);
+        writeFileSync(file, JSON.stringify(targets), { mode: 0o600 });
+        const suffix = import.meta.url.endsWith('.ts') ? '.ts' : '.js';
+        const entry = fileURLToPath(new URL(`./method${suffix}`, import.meta.url));
+        const log = openSync(join(dir, 'checks.log'), 'a', 0o600);
+        const child = spawn(process.execPath, [...process.execArgv, entry, '__checks', file], { detached: true, stdio: ['ignore', log, log], env: { ...process.env, METHOD_RUN_WORKER: '' } });
+        closeSync(log);
+        child.on('error', () => { });
+        child.unref();
+    }
+    catch { /* A check never delays or fails validate. */ }
+}
+/** The background worker: answer each pending target and save it in the cache. */
+export async function checksWorker(file) {
+    const targets = JSON.parse(readFileSync(file, 'utf8'));
+    const { rmSync } = await import('node:fs');
+    rmSync(file, { force: true });
+    const provider = (await import('./classification-client.js')).managedClassification(new MethodClient());
+    await Promise.allSettled(targets.map(target => evaluateTarget(provider, target, AbortSignal.timeout(120_000))));
+}
+const where = (issue) => [issue.file ?? (issue.step ? `steps.${issue.step}${issue.field ? `.${issue.field}` : ''}` : issue.field), issue.line ? `line ${issue.line}` : undefined].filter(Boolean).join(', ');
+/** One issue as the coding agent reads it: what is wrong, what to do, and, for a warning on a step, how to accept it. */
+export function formatIssue(issue) {
+    return { level: issue.level, code: issue.code, ...(where(issue) ? { at: where(issue) } : {}), message: issue.message, fix: issue.fix,
+        ...(issue.level === 'warning' && issue.step ? { accept: `Or, if the user decides to keep it, add accept: {${issue.code}: "<the user's reason>"} to step ${issue.step}.` } : {}) };
+}
+/**
+ * The issues that validate prints: every error; every open warning on a changed step (and those not on a step);
+ * notes only when asked. Accepted ones are counted.
+ */
+export function shownIssues(report, flags = {}) {
+    const open = report.issues.filter(issue => issue.accepted === undefined);
+    const errors = open.filter(issue => issue.level === 'error');
+    const warnings = open.filter(issue => issue.level === 'warning');
+    const fresh = flags.all || !report.changed ? warnings : warnings.filter(issue => !issue.step || report.changed.has(issue.step));
+    const listed = fresh;
+    const notes = open.filter(issue => issue.level === 'note');
+    const hidden = warnings.length - listed.length;
+    return {
+        issues: [...errors, ...listed, ...(flags.notes || flags.all ? notes : [])].map(formatIssue),
+        issue_counts: { errors: errors.length, warnings: warnings.length, notes: notes.length, accepted: report.issues.length - open.length },
+        ...(hidden ? { more_warnings: `${hidden} more warning${hidden === 1 ? '' : 's'} on unchanged steps. method validate FILE --all lists them.` } : {}),
+        ...(report.pending ? { checks: `${report.pending} check${report.pending === 1 ? '' : 's'} pending` } : {}),
+    };
+}
+export const guideLine = 'Fix errors. Fix each warning, or accept it with the user\'s reason. Never add a check only to remove a warning.';
+/** The publish gate: errors refuse the publish; every open warning and note is listed. */
+export async function publishIssues(client, file) {
+    const { issues } = await collectIssues(file, { phase: 'publish', client });
+    const errors = issues.filter(issue => issue.level === 'error');
+    if (errors.length)
+        throw Object.assign(Error(`Nothing was published. Fix ${errors.length === 1 ? 'this error' : 'these errors'}, then publish again: ${errors.map(issue => `${issue.code}${where(issue) ? ` (${where(issue)})` : ''}: ${issue.message} ${issue.fix}`).join(' ')}`), { code: 'method_has_errors', issues: errors.map(formatIssue) });
+    const open = issues.filter(issue => issue.accepted === undefined), accepted = issues.length - open.length;
+    return { ...(open.length ? { issues: open.map(formatIssue) } : {}), ...(accepted ? { accepted_issues: accepted } : {}) };
+}

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

@@ -0,0 +1,46 @@
+import { Outbox } from "./outbox.js";
+import { MethodClient } from "./method-client.js";
+import { type RunInspection } from "../../workflow-language/src/inspection.js";
+export declare class MethodSync {
+    readonly client: MethodClient;
+    readonly directory: string;
+    private state;
+    private pending;
+    private stopped;
+    private sending;
+    private initial;
+    private warned;
+    private live;
+    private deviceChecked;
+    private timer;
+    private scheduled;
+    readonly outbox: Outbox;
+    constructor(client: MethodClient, directory: string, workflowId: string, versionId: string, runId?: string, device?: boolean, outbox?: Outbox);
+    get device(): boolean;
+    private get item();
+    private save;
+    private upload;
+    private send;
+    /**
+     * Record the run's start. This sends nothing and never throws: the run never waits for the account. With live, the
+     * outbox starts sending (the version first) and the run's records follow it.
+     */
+    start(workflow: RunInspection["workflow"], inputs: RunInspection["inputs"], resources: RunInspection["resources"], live?: boolean): Promise<void>;
+    snapshot(): void;
+    private capture;
+    private warn;
+    /**
+     * Send the final record: the outbox sends the version first. Resolves "saved" or "pending"; a pending run stays in
+     * the outbox. Never throws.
+     */
+    finish(failure?: unknown): Promise<"saved" | "pending">;
+    private finished;
+    private finishOnce;
+    /** Send the final local record of a run. Never runs business actions. */
+    static retry(directory: string, client?: MethodClient): Promise<void>;
+}
+/**
+ * The organization setting "Keep run content on devices". When it cannot be read, the run's content stays on this
+ * computer: the server would refuse the content anyway when the setting is on.
+ */
+export declare function organizationKeepsContent(client: MethodClient): Promise<boolean>;

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

@@ -0,0 +1,293 @@
+import { transferResults } from "./result-transfer.js";
+import { existsSync, readFileSync } from "node:fs";
+import { Outbox } from "./outbox.js";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { inspectRun } from "./inspect.js";
+import { writePrivateJson } from "./files.js";
+import { MethodClient } from "./method-client.js";
+import { InspectionSchema, deviceOnly, } from "../../workflow-language/src/inspection.js";
+const SyncSchema = z.object({
+    schema: z.literal("method-sync/1"),
+    server: z.string(),
+    id: z.string().uuid(),
+    workflow_id: z.string(),
+    version_id: z.string(),
+    sequence: z.number().int().nonnegative(),
+    dashboard_id: z.string().optional(),
+    // The run's content stays on this computer, also when the sync is retried later.
+    device: z.literal(true).optional(),
+});
+export class MethodSync {
+    client;
+    directory;
+    state;
+    pending = Promise.resolve();
+    stopped = false;
+    sending = false;
+    initial;
+    warned = false;
+    live = false;
+    deviceChecked = false;
+    timer;
+    scheduled;
+    outbox;
+    constructor(client, directory, workflowId, versionId, runId, 
+    // run_data: device, or the organization keeps run content on devices. The account receives the run's shape and
+    // timing; its content stays on this computer. The organization setting is read when the first record is sent.
+    device = false, outbox) {
+        this.client = client;
+        this.directory = directory;
+        this.outbox = outbox ?? new Outbox(client);
+        const path = join(directory, "method-sync.json");
+        this.state = existsSync(path)
+            ? SyncSchema.parse(JSON.parse(readFileSync(path, "utf8")))
+            : {
+                schema: "method-sync/1",
+                server: client.server,
+                id: runId ?? randomUUID(),
+                workflow_id: workflowId,
+                version_id: versionId,
+                sequence: 0,
+            };
+        if (this.state.server !== client.server ||
+            this.state.workflow_id !== workflowId ||
+            this.state.version_id !== versionId)
+            throw Error("This run is linked to another Method or server.");
+        if (device)
+            this.state.device = true;
+        this.save();
+    }
+    get device() {
+        return this.state.device === true;
+    }
+    get item() {
+        return { kind: "run", server: this.client.server, run_dir: this.directory, version_id: this.state.version_id, pid: process.pid };
+    }
+    save() {
+        writePrivateJson(join(this.directory, "method-sync.json"), this.state);
+    }
+    async upload(inspection) {
+        // A run record is sent after its version is on the server.
+        if (!await this.outbox.whenSaved(this.state.version_id))
+            throw Error("The version is not saved yet.");
+        if (!this.device && !this.deviceChecked) {
+            if (await organizationKeepsContent(this.client)) {
+                this.state.device = true;
+                this.save();
+            }
+            this.deviceChecked = true;
+        }
+        if (this.device)
+            inspection = deviceOnly(inspection);
+        const payload = {
+            workflow_id: this.state.workflow_id,
+            version_id: this.state.version_id,
+            sequence: ++this.state.sequence,
+            inspection,
+        };
+        this.save();
+        if (inspection.files?.length) {
+            // Publish completed work even if transferring its result files is interrupted.
+            await this.send({ ...payload, inspection: { ...inspection, files: undefined } });
+            payload.sequence = ++this.state.sequence;
+            this.save();
+            payload.inspection = { ...inspection, files: await transferResults(this.client, this.directory, inspection.files) };
+        }
+        await this.send(payload);
+    }
+    async send(payload) {
+        const result = await retryTransfer(() => this.client.request(`/api/cli/runs/${this.state.id}`, "PUT", payload, true, { stallMs: 60_000 }));
+        if (!this.state.dashboard_id)
+            process.stderr.write(`Dashboard: ${this.client.server}/runs/${result.id}\n`);
+        this.state.dashboard_id = result.id;
+        this.save();
+        this.warned = false;
+    }
+    /**
+     * Record the run's start. This sends nothing and never throws: the run never waits for the account. With live, the
+     * outbox starts sending (the version first) and the run's records follow it.
+     */
+    async start(workflow, inputs, resources, live = true) {
+        try {
+            if (this.live)
+                return;
+            this.initial = {
+                schema: "workflow-inspection/2",
+                workflow,
+                run_id: this.state.id,
+                status: "running",
+                inputs,
+                resources,
+                invocations: {},
+                events: existsSync(join(this.directory, "setup.json")) ? JSON.parse(readFileSync(join(this.directory, "setup.json"), "utf8")) : [],
+            };
+            // A completed checkpoint remains completed when reconnecting or adding result files.
+            try {
+                const saved = inspectRun(this.directory, { includeFiles: "references" });
+                if (saved.status === 'succeeded')
+                    this.initial = saved;
+            }
+            catch { /* Preparation has no checkpoint yet. */ }
+            writePrivateJson(join(this.directory, 'setup-inspection.json'), this.initial);
+            this.outbox.add(this.item);
+            if (!live)
+                return;
+            this.live = true;
+            this.outbox.start();
+            const initial = this.initial;
+            this.sending = true;
+            this.pending = this.upload(initial).catch(error => this.warn(error)).finally(() => { this.sending = false; });
+            this.timer = setInterval(() => this.capture(), 5000);
+            this.timer.unref();
+        }
+        catch (error) {
+            this.warn(error);
+        }
+    }
+    snapshot() {
+        if (this.stopped || this.scheduled || !this.live)
+            return;
+        // Coalesce tool bursts before reading the journal or encoding attachments.
+        this.scheduled = setTimeout(() => {
+            this.scheduled = undefined;
+            this.capture();
+        }, 1000);
+        this.scheduled.unref();
+    }
+    capture() {
+        if (this.stopped)
+            return;
+        if (this.sending) {
+            this.snapshot();
+            return;
+        }
+        // Read synchronously on the SDK event loop, before any await. Atomic SDK files cannot change during this read.
+        let inspection;
+        try {
+            inspection = inspectRun(this.directory, { activeSnapshot: true, includeFiles: "references" });
+        }
+        catch {
+            return;
+        }
+        this.sending = true;
+        this.pending = this.upload(inspection).catch(error => this.warn(error)).finally(() => {
+            this.sending = false;
+        });
+    }
+    warn(error) {
+        // Before the version is saved, the run's last line says what happens; nothing else is printed.
+        if (!this.warned && String(error).includes("not saved yet")) {
+            this.warned = true;
+            return;
+        }
+        if (!this.warned)
+            process.stderr.write(`Dashboard sync paused: ${String(error)}\nRun records remain here; any later method command sends them.\n`);
+        this.warned = true;
+    }
+    /**
+     * Send the final record: the outbox sends the version first. Resolves "saved" or "pending"; a pending run stays in
+     * the outbox. Never throws.
+     */
+    async finish(failure) {
+        this.finished ??= this.finishOnce(failure);
+        return this.finished;
+    }
+    finished;
+    async finishOnce(failure) {
+        this.stopped = true;
+        clearInterval(this.timer);
+        clearTimeout(this.scheduled);
+        try {
+            if (!this.initial)
+                this.outbox.add(this.item);
+            await this.pending;
+            await this.outbox.drain();
+            let inspection;
+            try {
+                inspection = inspectRun(this.directory, { includeFiles: "references" });
+            }
+            catch (error) {
+                if (!this.initial)
+                    throw error;
+                inspection = {
+                    ...this.initial,
+                    events: existsSync(join(this.directory, "setup.json")) ? JSON.parse(readFileSync(join(this.directory, "setup.json"), "utf8")) : this.initial.events,
+                    status: "needs_attention",
+                    error: failure instanceof Error
+                        ? failure.message
+                        : String(failure ?? error),
+                };
+                // A run that failed before its first step keeps this record for a later sync.
+                writePrivateJson(join(this.directory, "setup-inspection.json"), inspection);
+            }
+            await this.upload(inspection);
+            this.outbox.remove(this.item);
+            return "saved";
+        }
+        catch (error) {
+            this.warn(error);
+            this.outbox.release(this.item);
+            return "pending";
+        }
+    }
+    /** Send the final local record of a run. Never runs business actions. */
+    static async retry(directory, client) {
+        const state = SyncSchema.parse(JSON.parse(readFileSync(join(directory, "method-sync.json"), "utf8")));
+        const sync = new MethodSync(client ?? new MethodClient(state.server), directory, state.workflow_id, state.version_id);
+        let inspection;
+        try {
+            inspection = inspectRun(directory, { includeFiles: "references" });
+        }
+        catch (error) {
+            if (!existsSync(join(directory, "setup-inspection.json")))
+                throw error;
+            inspection = InspectionSchema.parse(JSON.parse(readFileSync(join(directory, "setup-inspection.json"), "utf8")));
+        }
+        if (state.dashboard_id) {
+            const saved = await sync.client.request(`/api/workspace/runs/${state.dashboard_id}`);
+            // A later observation can change a finished run's status; then the local record replaces the saved one.
+            if (saved.run.status === "succeeded" && inspection.status === "succeeded") {
+                // Keep bytes already saved if the local file was removed or changed.
+                const files = [...(saved.run.inspection.files ?? [])];
+                for (const file of inspection.files ?? []) {
+                    const index = files.findIndex(old => old.path === file.path && old.sha256 === file.sha256);
+                    if (index >= 0 && files[index].stored)
+                        continue;
+                    if (index >= 0)
+                        files[index] = file;
+                    else
+                        files.push(file);
+                }
+                inspection = { ...saved.run.inspection, files };
+            }
+        }
+        await sync.upload(inspection);
+        sync.outbox.remove(sync.item);
+    }
+}
+async function retryTransfer(send) {
+    for (let attempt = 0;; attempt++)
+        try {
+            return await send();
+        }
+        catch (error) {
+            if (attempt >= 2 || /\b4\d\d:/.test(String(error)) && !String(error).includes('429:'))
+                throw error;
+            await new Promise(r => setTimeout(r, 500 * 2 ** attempt));
+        }
+}
+/**
+ * The organization setting "Keep run content on devices". When it cannot be read, the run's content stays on this
+ * computer: the server would refuse the content anyway when the setting is on.
+ */
+export async function organizationKeepsContent(client) {
+    try {
+        const me = await client.request("/api/cli/me");
+        return me?.organization?.keep_run_content_on_devices === true;
+    }
+    catch {
+        return true;
+    }
+}

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

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { MethodClient } from "./method-client.js";
+/** The next step for a failure before the first step. */
+export declare function setupFix(error: any): any;
+export declare function methodMain(args?: string[], clientFactory?: (server: string) => MethodClient): Promise<boolean | void>;