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

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

@@ -0,0 +1,284 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { assertSchema } from "@withmethod/runtime/validate.js";
+import { DEFAULT_SERVER, MethodClient, serverOrigin } from "./method-client.js";
+import { inputsDigest, open, seal } from "./run-data.js";
+import { ProductionWorker } from "./worker.js";
+export class MethodApiError extends Error {
+    status;
+    code;
+    body;
+    constructor(status, code, message, body) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.body = body;
+    }
+}
+const terminal = new Set(["succeeded", "failed", "cancelled"]);
+/** The production API client. Every request sends Authorization: Bearer CREDENTIAL. */
+export class ServiceApi {
+    apiKey;
+    fetcher;
+    server;
+    constructor(apiKey, server, fetcher = fetch) {
+        this.apiKey = apiKey;
+        this.fetcher = fetcher;
+        if (!/^(mk_live_|method_)[A-Za-z0-9_-]{43}$/.test(apiKey))
+            throw Error("Use a Method service key (mk_live_…). Run method connect APP_FOLDER to make one, or method login on this computer.");
+        this.server = serverOrigin(server);
+    }
+    async request(path, method = "GET", body, timeoutMs = 30_000, signal) {
+        const response = await this.send(path, method, body === undefined ? undefined : JSON.stringify(body), body === undefined ? {} : { "content-type": "application/json" }, timeoutMs, signal);
+        if (response.status === 204)
+            return { status: 204, body: null };
+        const text = await response.text();
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            throw new MethodApiError(response.status, "invalid_response", `${response.status}: Method returned a non-JSON response (${method} ${path}).`);
+        }
+        if (!response.ok)
+            throw new MethodApiError(response.status, String(parsed.code ?? parsed.error ?? "request_failed"), `${response.status}: ${String(parsed.message ?? parsed.error ?? "Method request failed")}`, parsed);
+        return { status: response.status, body: parsed };
+    }
+    /** Send or get raw bytes (a run folder). */
+    async bytes(path, method, body, headers = {}) {
+        const response = await this.send(path, method, body, { ...headers, ...(body ? { "content-type": "application/octet-stream" } : {}) }, 120_000);
+        const data = Buffer.from(await response.arrayBuffer());
+        if (!response.ok) {
+            let parsed = {};
+            try {
+                parsed = JSON.parse(data.toString("utf8"));
+            }
+            catch { /* Not JSON. */ }
+            throw new MethodApiError(response.status, String(parsed.code ?? "request_failed"), `${response.status}: ${String(parsed.message ?? "Method request failed")}`, parsed);
+        }
+        return data;
+    }
+    send(path, method, body, headers, timeoutMs, signal) {
+        const timeout = AbortSignal.timeout(timeoutMs);
+        return this.fetcher(this.server + path, {
+            method, redirect: "error", signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
+            headers: { authorization: `Bearer ${this.apiKey}`, ...headers }, ...(body === undefined ? {} : { body: body }),
+        });
+    }
+}
+/** Verify a webhook: Method-Signature is t=TIMESTAMP,v1=HEX(HMAC-SHA256(secret, `${t}.${body}`)). Pass the raw body. */
+export function verifyWebhook(body, signature, secret, options = {}) {
+    const match = signature?.match(/^t=(\d+),v1=([a-f0-9]{64})$/);
+    if (!match)
+        return false;
+    const age = Math.abs((options.now ?? Date.now()) / 1000 - Number(match[1]));
+    if (age > (options.toleranceSeconds ?? 300))
+        return false;
+    const text = typeof body === "string" ? body : Buffer.from(body).toString("utf8");
+    const expected = createHmac("sha256", secret).update(`${match[1]}.${text}`).digest();
+    return timingSafeEqual(expected, Buffer.from(match[2], "hex"));
+}
+/** METHOD_API_KEY and METHOD_SERVER from .env in a folder. Other lines are not read. */
+export function dotenvValues(folder = process.cwd()) {
+    const file = join(folder, ".env");
+    if (!existsSync(file))
+        return {};
+    const found = {};
+    for (const line of readFileSync(file, "utf8").split(/\r?\n/)) {
+        const match = line.match(/^\s*(?:export\s+)?(METHOD_API_KEY|METHOD_SERVER)\s*=\s*(.*?)\s*$/);
+        if (match)
+            found[match[1]] = match[2].replace(/^(['"])(.*)\1$/, "$2");
+    }
+    return found;
+}
+/** The credential of the libraries: apiKey, METHOD_API_KEY, .env, then the CLI sign-in. */
+export function resolveCredential(options = {}) {
+    const dotenv = dotenvValues();
+    const server = options.server ?? process.env.METHOD_SERVER ?? dotenv.METHOD_SERVER ?? DEFAULT_SERVER;
+    const key = options.apiKey ?? process.env.METHOD_API_KEY ?? dotenv.METHOD_API_KEY;
+    if (key)
+        return { key, server };
+    let signedIn = null;
+    try {
+        signedIn = new MethodClient(server).token();
+    }
+    catch { /* No sign-in for this server. */ }
+    if (signedIn)
+        return { key: signedIn, server };
+    throw Error("Set METHOD_API_KEY (run method connect APP_FOLDER to write it to the app's .env), or sign in on this computer with method login.");
+}
+export class Method {
+    options;
+    api;
+    /** Results of runs that this process's worker finished. A device run's result exists only here. */
+    local = new Map();
+    waiting = new Map();
+    handlers = new Map();
+    asked = new Set();
+    runData = new Map();
+    lazyMethods = new Set();
+    lazyWorker;
+    lazyRuns = 0;
+    runs = {
+        start: async (options) => {
+            const inputs = options.inputs ?? {};
+            const send = async (sealed) => (await this.api.request("/v1/runs", "POST", {
+                method: options.method, ...(options.version ? { version: options.version } : {}),
+                ...(sealed ? { inputs: {}, sealed_inputs: seal(this.api.apiKey, "inputs", options.method, inputs), inputs_digest: inputsDigest(this.api.apiKey, options.method, inputs) } : { inputs }),
+                ...(options.idempotencyKey ? { idempotency_key: options.idempotencyKey } : {}), ...(options.webhookUrl ? { webhook_url: options.webhookUrl } : {}),
+                ...(options.onAsk ?? this.options.onAsk ? { answered_by: "app" } : {}),
+            })).body;
+            // A device run's inputs are sealed here. The server says which Methods keep run content on devices.
+            const sealIt = Object.keys(inputs).length > 0 && await this.keepsOnDevice(options.method);
+            let started;
+            try {
+                started = await send(sealIt);
+            }
+            catch (error) {
+                if (!(error instanceof MethodApiError && error.code === "seal_inputs"))
+                    throw error;
+                this.runData.set(options.method, { value: "device", at: Date.now() });
+                started = await send(true);
+            }
+            const handler = options.onAsk ?? this.options.onAsk;
+            if (handler)
+                this.handlers.set(started.run_id, handler);
+            return started;
+        },
+        get: async (runId) => this.withLocal((await this.api.request(`/v1/runs/${encodeURIComponent(runId)}`)).body),
+        cancel: async (runId) => this.withLocal((await this.api.request(`/v1/runs/${encodeURIComponent(runId)}/cancel`, "POST", {})).body),
+        /** Answer the waiting question of a run. The answer must match the question's form. */
+        answer: async (runId, answer) => {
+            const run = await this.runs.get(runId);
+            if (run.status !== "waiting" || !run.question)
+                throw new MethodApiError(409, "not_waiting", `The run is ${run.status}; it has no question to answer.`);
+            const asked = this.openQuestion(run);
+            try {
+                assertSchema(asked.form, answer, "Answer");
+            }
+            catch (error) {
+                throw new MethodApiError(422, "invalid_answer", error.message);
+            }
+            const body = run.question.sealed ? { step: run.question.step, sealed_answer: seal(this.api.apiKey, "answer", run.method_id, answer) } : { step: run.question.step, answer };
+            return this.withLocal((await this.api.request(`/v1/runs/${encodeURIComponent(runId)}/answer`, "POST", body)).body);
+        },
+        /**
+         * Wait until the run ends. Checks the server every intervalMs, and returns at once when this process's worker finishes
+         * it. A question of a run with an ask handler goes to the handler.
+         */
+        wait: async (runId, options = {}) => {
+            const deadline = Date.now() + (options.timeoutMs ?? 30 * 60_000);
+            for (;;) {
+                const run = await this.runs.get(runId);
+                // This process's worker saves a result before it completes the run, so a finished run has its local result here.
+                if (terminal.has(run.status)) {
+                    this.handlers.delete(runId);
+                    return run;
+                }
+                if (run.status === "waiting" && run.question)
+                    await this.ask(run, options.onAsk);
+                if (Date.now() > deadline)
+                    throw new MethodApiError(408, "wait_timeout", `The run is still ${run.status}.`);
+                await new Promise(resolve => {
+                    const wake = () => { clearTimeout(timer); this.waiting.get(runId)?.delete(wake); resolve(); };
+                    const timer = setTimeout(wake, Math.min(options.intervalMs ?? 2_000, Math.max(0, deadline - Date.now())));
+                    this.waiting.set(runId, (this.waiting.get(runId) ?? new Set()).add(wake));
+                });
+            }
+        },
+        /** Start a run and wait for its result. Needs a worker: method.run() starts one in this process. */
+        run: async (options) => this.runs.wait((await this.runs.start(options)).run_id, options),
+    };
+    worker = {
+        /** Claim and run queued runs in this process. Results reach onResult, runs.wait, and the dashboard. */
+        start: (options = {}) => {
+            const worker = new ProductionWorker(this.api, { ...options,
+                onResult: async (result) => {
+                    this.local.set(result.run_id, result);
+                    this.wake(result.run_id);
+                    await options.onResult?.(result);
+                },
+                onWaiting: async (waiting) => { this.wake(waiting.run_id); await options.onWaiting?.(waiting); } });
+            worker.start();
+            return worker;
+        },
+    };
+    webhooks = { verify: verifyWebhook };
+    static webhooks = { verify: verifyWebhook };
+    constructor(options = {}) {
+        this.options = options;
+        const { key, server } = resolveCredential(options);
+        this.api = new ServiceApi(key, server, options.fetch);
+    }
+    /**
+     * Run a published Method and wait for its result. The first call starts a worker in this process (unless the options
+     * say worker: false), so the run needs nothing else running. The worker stops when no method.run() call is waiting,
+     * so a script that calls method.run() exits when it is done; close() is not needed.
+     */
+    async run(options) {
+        this.ensureWorker(options.method);
+        this.lazyRuns++;
+        try {
+            return await this.runs.run(options);
+        }
+        // The worker stops claiming at once; a run it holds still finishes. run() returns without waiting for that.
+        finally {
+            if (--this.lazyRuns === 0)
+                void this.close().catch(() => { });
+        }
+    }
+    /** Stop this process's worker. Runs in progress finish first. */
+    async close(options = {}) {
+        const worker = this.lazyWorker;
+        this.lazyWorker = undefined;
+        await worker?.stop(options);
+    }
+    ensureWorker(method) {
+        if (this.options.worker === false)
+            return;
+        this.lazyMethods.add(method);
+        if (this.lazyWorker?.running)
+            return;
+        const extra = typeof this.options.worker === "object" ? this.options.worker : {};
+        this.lazyWorker = this.worker.start({ ...extra, methods: this.lazyMethods });
+    }
+    wake(runId) { for (const wake of this.waiting.get(runId) ?? [])
+        wake(); }
+    async keepsOnDevice(method) {
+        const known = this.runData.get(method);
+        if (known && Date.now() - known.at < 5 * 60_000)
+            return known.value === "device";
+        try {
+            const found = (await this.api.request(`/v1/methods/${encodeURIComponent(method)}`)).body;
+            this.runData.set(method, { value: found.run_data, at: Date.now() });
+            return found.run_data === "device";
+        }
+        catch {
+            return false; /* The server refuses plain inputs of a device run (seal_inputs), and start seals them then. */
+        }
+    }
+    openQuestion(run) {
+        const asked = run.question;
+        if (!asked.sealed)
+            return { question: asked.question ?? "", form: asked.form ?? {} };
+        return open(this.api.apiKey, "question", run.method_id, asked.sealed);
+    }
+    /** Give a waiting question to the run's ask handler, once. */
+    async ask(run, override) {
+        const handler = override ?? this.handlers.get(run.run_id);
+        const question = run.question, id = `${question.id}:${question.asked_at}`;
+        if (!handler || this.asked.has(id))
+            return;
+        this.asked.add(id);
+        const opened = this.openQuestion(run);
+        const answer = (value) => this.runs.answer(run.run_id, value);
+        const value = await handler({ run_id: run.run_id, step: question.step, question: opened.question, form: opened.form, answer });
+        if (value && typeof value === "object")
+            await answer(value);
+    }
+    withLocal(run) {
+        const local = this.local.get(run.run_id);
+        return local && local.result !== undefined && run.result === undefined ? { ...run, result: local.result } : run;
+    }
+}

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

@@ -0,0 +1,12 @@
+export type ProgressUpdate = {
+    message: string;
+    completed?: number;
+    total?: number;
+    unit?: string;
+    child?: string;
+};
+/** Opt-in public text only. Does not write to the script's result stdout. */
+export declare function reportProgress(update: ProgressUpdate): boolean;
+/** Relay only supported public Codex JSON events from a child process. */
+export declare function relayCodexProgress(stream: AsyncIterable<Uint8Array>, child: string): Promise<void>;
+export declare function progressMain(args: string[]): Promise<void>;

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

@@ -0,0 +1,48 @@
+import { writeSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { progressMessage, codexProgress } from "@withmethod/runtime/progress.js";
+import { readLines } from "@withmethod/runtime/io.js";
+/** Opt-in public text only. Does not write to the script's result stdout. */
+export function reportProgress(update) {
+    const value = progressMessage(update);
+    const fd = Number(process.env.METHOD_PROGRESS_FD);
+    if (!value || !Number.isInteger(fd) || fd < 3)
+        return false;
+    try {
+        writeSync(fd, JSON.stringify(value) + "\n");
+        return true;
+    }
+    catch (error) {
+        if (["EPIPE", "EBADF"].includes(error.code ?? ""))
+            return false;
+        throw error;
+    }
+}
+/** Relay only supported public Codex JSON events from a child process. */
+export async function relayCodexProgress(stream, child) {
+    await readLines(stream, async (line) => {
+        let event;
+        try {
+            event = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        const value = codexProgress(event);
+        if (value)
+            reportProgress({ ...value, child });
+    });
+}
+export async function progressMain(args) {
+    const { values } = parseArgs({ args, options: { message: { type: "string" }, completed: { type: "string" }, total: { type: "string" }, unit: { type: "string" }, child: { type: "string" }, codex: { type: "boolean" } }, strict: true });
+    if (values.codex) {
+        if (!values.child || values.message)
+            throw Error("Use method progress --codex --child NAME with Codex JSON on stdin.");
+        await relayCodexProgress(process.stdin, values.child);
+    }
+    else {
+        if (!values.message)
+            throw Error("Supply --message TEXT, or --codex --child NAME.");
+        reportProgress({ message: values.message, ...(values.child ? { child: values.child } : {}), ...(values.unit ? { unit: values.unit } : {}), ...(values.completed !== undefined ? { completed: Number(values.completed) } : {}), ...(values.total !== undefined ? { total: Number(values.total) } : {}) });
+    }
+}

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

@@ -0,0 +1,73 @@
+import { type MethodClient } from './method-client.js';
+/** A proposed change to a Method, from the account (a server proposal) or from `method improve` on this computer. */
+export type ProposalRecord = {
+    id: string;
+    source: 'account' | 'local';
+    method_id: string | null;
+    base_version_id: string | null;
+    status: string;
+    cause: string;
+    evidence: any;
+    created_at: string;
+    base_workflow: unknown;
+    proposed_workflow: unknown | null;
+};
+export type MergeConflict = {
+    path: string;
+    base: unknown;
+    ours: unknown;
+    theirs: unknown;
+};
+export type MergeResult = {
+    clean: true;
+    workflow: any;
+} | {
+    clean: false;
+    conflicts: MergeConflict[];
+};
+/**
+ * Three-way merge of Method documents, per step and per top-level key. base is the version the proposal started from,
+ * ours is the local file, and theirs is the proposed version. A part that only one side changed takes that change; a part
+ * that both sides changed in different ways is a conflict.
+ */
+export declare function mergeMethod(base: any, ours: any, theirs: any): MergeResult;
+/** The steps whose definition differs between two documents. */
+export declare function changedSteps(before: any, after: any): string[];
+export declare const localProposalFolder: (file: string) => string;
+/** Save a local proposal as a private file. The .method folder is not for Git: its proposals can hold run content. */
+export declare function saveLocalProposal(file: string, record: Omit<ProposalRecord, 'source'> & Record<string, unknown>): string;
+export declare function localProposals(file: string): (ProposalRecord & {
+    path: string;
+})[];
+type RequestOptions = {
+    signal?: AbortSignal;
+    stallMs?: number;
+};
+type Applied = {
+    status: 'applied';
+    steps: string[];
+    version_id: string | undefined;
+    warning?: string;
+} | {
+    status: 'conflict';
+    conflicts: MergeConflict[];
+} | {
+    status: 'invalid';
+    error: string;
+};
+/** Merge a proposal into the file. A clean merge writes the file and marks the proposal applied. Never publishes. */
+export declare function applyProposal(client: MethodClient | undefined, file: string, proposal: ProposalRecord, options?: RequestOptions): Promise<Applied>;
+/**
+ * Before a command that takes a .method FILE: when this computer is signed in and the Method has an accepted proposal,
+ * merge it into the file and print one line. A conflict prints what the coding agent must resolve; the command goes on.
+ * Offline, signed out, or on any error, it does nothing.
+ */
+export declare function autoApply(args: string[], clientFactory: (server: string) => MethodClient): Promise<void>;
+/** Run folders of this Method on this computer, newest first, with the account run ID of each run that was saved to the account. */
+export declare function localRuns(file: string): Promise<{
+    dir: string;
+    account_run_id: string | null;
+}[]>;
+/** `method improve`, `method proposals`, and `method apply`. */
+export declare function proposalCommand(args: string[], clientFactory: (server: string) => MethodClient): Promise<boolean | undefined>;
+export {};