@method-ai-hq/sdk 0.15.1 → 0.17.0

package/README.md

@@ -3,7 +3,7 @@
 MIT-licensed JavaScript API and the `method` CLI. Source and releases: https://github.com/method-ai-hq/method-sdk
 
 ```sh
-npm install https://github.com/method-ai-hq/method-sdk/releases/download/v0.15.1/method-ai-hq-sdk-0.15.1.tgz
+npm install https://github.com/method-ai-hq/method-sdk/releases/download/v0.17.0/method-ai-hq-sdk-0.17.0.tgz
 npx method --version
 ```
 

package/dist/packages/method-document/src/conversion-report.d.ts

@@ -70,11 +70,11 @@ export declare const ConversionReportSchema: z.ZodObject<{
 }, "strict", z.ZodTypeAny, {
     status: "ready" | "needs_review";
     schema: "workflow-conversion/1";
+    attempts: number;
     references: {
         sha256: string;
         name: string;
     }[];
-    attempts: number;
     source_sha256: string;
     workflow_sha256: string;
     selected_attempt: number;
@@ -101,11 +101,11 @@ export declare const ConversionReportSchema: z.ZodObject<{
 }, {
     status: "ready" | "needs_review";
     schema: "workflow-conversion/1";
+    attempts: number;
     references: {
         sha256: string;
         name: string;
     }[];
-    attempts: number;
     source_sha256: string;
     workflow_sha256: string;
     selected_attempt: number;

package/dist/packages/sdk/examples/outbound-management/README.md

@@ -24,7 +24,7 @@ The `draft_tasks` prompt shows two tasks written the way they should be, for
 contacts that are not in the CRM: a reply to a pricing question and an
 introduction request. Replace them with two drafts that you sent and liked.
 
-The three browser steps accept the `untrusted_content_can_act` warning: each
+The three browser steps accept the `untrusted_reaches_action` warning: each
 agent reads pages with a signed-in browser that could also send, and the
 `accept:` line on each step gives the reason to keep it. Nothing is sent until
 you review the tasks.

package/dist/packages/sdk/examples/outbound-management/outbound.method

@@ -58,7 +58,7 @@ steps:
     name: Read campaign email
     no_effect_reason: Reads the mailbox in the browser; sends, replies to, and deletes nothing.
     accept:
-      untrusted_content_can_act: The agent needs the signed-in mailbox to read campaign email. The prompt asks it only to search and read; nothing is sent until a person reviews the tasks.
+      untrusted_reaches_action: The agent needs the signed-in mailbox to read campaign email. The prompt asks it only to search and read; nothing is sent until a person reviews the tasks.
     changes: [environment.browser]
     in:
       mailbox_url: target.mailbox_url
@@ -94,7 +94,7 @@ steps:
     name: Find prospects in Happenstance
     no_effect_reason: Searches Happenstance in the browser; sends no messages or introduction requests.
     accept:
-      untrusted_content_can_act: The agent needs the signed-in Happenstance account to search the network. The prompt asks it only to search; no message or introduction request is sent.
+      untrusted_reaches_action: The agent needs the signed-in Happenstance account to search the network. The prompt asks it only to search; no message or introduction request is sent.
     changes: [environment.browser]
     after: read_email
     in:
@@ -132,7 +132,7 @@ steps:
     name: Check each prospect's pages
     no_effect_reason: Reads company and LinkedIn pages in the browser; sends no messages or connection requests.
     accept:
-      untrusted_content_can_act: The agent needs the signed-in browser to read LinkedIn profiles. The prompt asks it only to read pages; no message or connection request is sent.
+      untrusted_reaches_action: The agent needs the signed-in browser to read LinkedIn profiles. The prompt asks it only to read pages; no message or connection request is sent.
     changes: [environment.browser]
     after: find_prospects
     each: {prospect: prospects}

package/dist/packages/sdk/examples/social-briefing/README.md

@@ -29,7 +29,7 @@ default connection copies the last-used Chrome profile and runs headless. Run
 
 - `no_effect_reason`: the browser step only reads. It sends, posts, and submits
   nothing, so there is no change to read back.
-- `accept: {untrusted_content_can_act: ...}`: `validate` warns when an agent that
+- `accept: {untrusted_reaches_action: ...}`: `validate` warns when an agent that
   reads web pages could also change things with the same browser. Here the agent
   needs the signed-in browser to read, and a person reads the briefing before it
   is shared, so the warning is accepted with that reason.

package/dist/packages/sdk/examples/social-briefing/social-briefing.method

@@ -18,7 +18,7 @@ steps:
   gather_sources:
     no_effect_reason: Reads posts and papers in the browser; sends, posts and submits nothing.
     accept:
-      untrusted_content_can_act: The agent needs the signed-in browser to read Grok, alphaXiv, and LinkedIn. The prompt asks it only to search and read, and a person reads the briefing before it is shared.
+      untrusted_reaches_action: The agent needs the signed-in browser to read Grok, alphaXiv, and LinkedIn. The prompt asks it only to search and read, and a person reads the briefing before it is shared.
     name: Find and read sources
     changes:
       - environment.browser

package/dist/packages/sdk/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@method-ai-hq/sdk",
-    "version": "0.15.1",
+    "version": "0.17.0",
     "description": "Build and run reusable .method files with checked steps and saved results.",
     "license": "MIT",
     "type": "module",
@@ -35,7 +35,7 @@
         "prepack": "npm --prefix ../.. run build"
     },
     "dependencies": {
-        "@withmethod/runtime": "https://codeload.github.com/method-ai-hq/method-spec/tar.gz/c45c5ba1a3432b8d4e90ff07a7457eef5ea0f371",
+        "@withmethod/runtime": "https://codeload.github.com/method-ai-hq/method-spec/tar.gz/54461cb387d8f10813db05bb0cea29c0a3a53504",
         "fflate": "^0.8.3",
         "yaml": "^2.9.0",
         "zod": "^3.25.76"

package/dist/packages/sdk/src/authoring-instructions.d.ts

@@ -5,7 +5,7 @@ export declare const designProcedure = "# Choose the design\n\n| Requirement | S
 /** The full check rules; in concepts. */
 export declare const checkRules = "# Checks\n\nAdd a check only when it catches a concrete failure that matters to the result. Output types and the runtime already validate shapes; do not repeat them. Do not check wording, headings, keywords, lengths, or counts unless the task requires them: \"write accurate prose\" is not a reason to match strings.\n\nUse the simplest check that proves the fact: a built-in equals, count, present, or file check, a script, or an agent check. Local file writes need no check: the runtime observes files connections itself. A change to a service, an API, email, or a browser that sends needs an effect that reads the result back, because a receipt or a 200 status shows only that the request was accepted. Use a built-in observer (http, sqlite, file) when one fits. When a change cannot or need not be observed, such as a browser step that only reads, write no_effect_reason instead.\n\nExisting checks and tests are implementation choices, not user requirements. Remove a check that is unnecessary, repeats other validation, or enforces a requirement that nobody asked for. Delete the tests and instructions that exist only for it, and do not replace it. Do not change useful output only to satisfy a check.\n";
 /** The rules that make a first Method work quickly. They come before every other part of the guide. */
-export declare const firstMethodRules = "# Build a Method\n\n1. **Sign in first.** Run `method status`. If it is not signed in, run `method login` and let the user approve in the browser. Signed in, model and classification steps need no keys, each run saves a version when the file changed, and runs appear on the dashboard.\n2. **Each model or classifier request is its own step**: `call`, `agent`, or `classify`, with its prompt in the Method, so the user can change one prompt, run again, and compare. A script never calls a model API. When the user already has code that does the work, keep its fixed logic as `run` steps and move each prompt and rubric into its own step; do not wrap the code. \"The same thing\" means the same behavior in steps. If a request cannot become a step because Method lacks a feature, tell the user what is missing.\n3. **Show the design, then build it in the same turn.** Show each step with its type, purpose, and output, and a table of the prompts and rubrics in the user's existing work, each with the step that holds it. Do not wait for approval unless the user asked to approve first. Ask only for information that you cannot find and that would change the design.\n4. **Run early and often.** Write the first steps, validate, run, then add the next steps. Fix errors. Fix each warning, or accept it with the user's reason. Never add a check only to remove a warning. A new run reuses every step whose definition and inputs did not change, so each run executes only what changed. `--rerun STEP` runs a step again anyway; `--fresh` runs every step.\n5. **Keep the inputs of the existing code.** If the code takes an ID and looks up the record, the Method takes the same ID and looks it up the same way.\n6. **Use the defaults without asking.** Model steps use the account's hosted models and `classify` uses Method's classifier, so no model or classifier keys are needed. To keep the model that existing code uses, add `models: {writer: provider/model}` to the Method and use `model: writer` in the steps (or `model: provider/model` on the step); it needs no key. Keep the models that the Method or the existing code names: when a model step fails, show the error and ask before you change its model. Run records go to the user's account. When the user asks that run data stay on this computer or not be uploaded, set `run_data: device`: the run's inputs, outputs, and files stay here, and the account keeps only each step's status and timing. Model steps still send each step's input to the model to answer it; nothing is kept. Tell the user that in one line, then run again.\n7. **Keys stay out of chat.** Declare each key that a script needs under `secrets:` with its purpose; every script of the Method receives all of its declared secrets. Run `method secret find` in the Method's folder: it lists the key files nearby and the names in each, never the values, and prints the import command. Run that command and tell the user which file each key came from: the key stays on this computer, so there is nothing to ask. If it finds nothing, ask the user to run `method secret set NAME`, which opens a private form in their browser. Never open, print, or search a key file (`cat`, `grep`, an editor), including Method's own secret store, and never ask for a value in chat: the values would go into the chat. When a run says Method's model credit is used up, run `method config model-key` yourself: it takes the user's own OpenRouter key from the one nearby key file that holds it, or opens a private form for it. Then run again.\n8. **Choose a sample yourself** from the user's data, and check that it has the sources the Method needs. Ask only when there is no good sample.\n9. **Iterate.** `method run` prints a `dashboard` link when the run starts and again with its result. Give the user the link as soon as the run starts. After a good run, show the result and the link, and ask what to change. Change the step and run again. Show only results that a run made: never write or edit a result by hand, and fix a wrong result in the Method, not in the data it reads. If you cannot run, say so.\n10. **Publish** with `method publish FILE --reason TEXT` when the user wants to share or schedule a version. It runs the Method's cases first.\n11. **Talk about the work, not about Method.** Unless the user asks, do not mention Method's versions, formats, settings files, or other internal files, and do not ask the user about them, about models, or about which saved version to use. Method updates itself and converts older Method files when it runs them. When the user asks whether a Method works, or asks you to make it work, run it with the inputs of a recent run (`--inputs-from RUN_ID`) and show the result and the dashboard link in a few sentences. Say that it works only after a run completed.\n12. **One file for each Method.** Change and run a Method in its own file. Do not copy it to a temporary or other folder to change it: Method does not run or save the copy while the Method's file exists, and names that file.\n13. **Questions in a run are for the user.** When a run stops with `needs_input`, ask the user its `question` in plain words, wait for the answer, and continue the run with it as the output says. Never answer it yourself.\n14. **Make each run easy to find and to run again.** Give the Method a `run_label` that tells its runs apart, such as `inputs.topic`. When an input can be empty and a default picks the value, point `run_label` at the step output that holds the resolved value, not at the input. Put the readable output, such as the report text or the message, in `result`, not only in files. Write a `run_prompt` that says where each input comes from (for example \"as_of is today's date in YYYY-MM-DD\") and what to show at the end. Leave SDK, runtime, and version details out of it.\n15. **Run again from the dashboard.** When the user pastes a \"Run again\" prompt from the dashboard, run with `--inputs-from RUN_ID` and change only what the prompt names: put those values in a file and add `--inputs FILE`.\n\nWhen a run fails, read its `fix` and `diagnostics`, change the step, and run again.\n";
+export declare const firstMethodRules = "# Build a Method\n\n1. **Sign in first.** Run `method status`. If it is not signed in, run `method login` and let the user approve in the browser. Signed in, model and classification steps need no keys, each run saves a version when the file changed, and runs appear on the dashboard.\n2. **Each model or classifier request is its own step**: `call`, `agent`, or `classify`, with its prompt in the Method, so the user can change one prompt, run again, and compare. A script never calls a model API. When the user already has code that does the work, keep its fixed logic as `run` steps and move each prompt and rubric into its own step; do not wrap the code. \"The same thing\" means the same behavior in steps. If a request cannot become a step because Method lacks a feature, tell the user what is missing.\n3. **Show the design, then build it in the same turn.** Show each step with its type, purpose, and output, and a table of the prompts and rubrics in the user's existing work, each with the step that holds it. Do not wait for approval unless the user asked to approve first. Ask only for information that you cannot find and that would change the design.\n4. **Run early and often.** Write the first steps, validate, run, then add the next steps. Fix errors. Fix each warning, or accept it with the user's reason. Never add a check only to remove a warning. A new run reuses every step whose definition and inputs did not change, so each run executes only what changed. `--rerun STEP` runs a step again anyway; `--fresh` runs every step.\n5. **Keep the inputs of the existing code.** If the code takes an ID and looks up the record, the Method takes the same ID and looks it up the same way.\n6. **Use the defaults without asking.** Model steps use the account's hosted models and `classify` uses Method's classifier, so no model or classifier keys are needed. To keep the model that existing code uses, add `models: {writer: provider/model}` to the Method and use `model: writer` in the steps (or `model: provider/model` on the step); it needs no key. Keep the models that the Method or the existing code names: when a model step fails, show the error and ask before you change its model. Run records go to the user's account. When the user asks that run data stay on this computer or not be uploaded, set `run_data: device`: the run's inputs, outputs, and files stay here, and the account keeps only each step's status and timing. Model steps still send each step's input to the model to answer it; nothing is kept. Tell the user that in one line, then run again.\n7. **Keys stay out of chat.** Declare each key that a script needs under `secrets:` with its purpose; every script of the Method receives all of its declared secrets. Run `method secret find` in the Method's folder: it lists the key files nearby and the names in each, never the values, and prints the import command. Run that command and tell the user which file each key came from: the key stays on this computer, so there is nothing to ask. If it finds nothing, ask the user to run `method secret set NAME`, which opens a private form in their browser. Never open, print, or search a key file (`cat`, `grep`, an editor), including Method's own secret store, and never ask for a value in chat: the values would go into the chat. When a run says Method's model credit is used up, run `method config model-key` yourself: it takes the user's own OpenRouter key from the one nearby key file that holds it, or opens a private form for it. Then run again.\n8. **Choose a sample yourself** from the user's data, and check that it has the sources the Method needs. Ask only when there is no good sample.\n9. **Iterate.** `method run` prints a `dashboard` link when the run starts and again with its result. Give the user the link as soon as the run starts. After a good run, show the result and the link, and ask what to change. Change the step and run again. Show only results that a run made: never write or edit a result by hand, and fix a wrong result in the Method, not in the data it reads. If you cannot run, say so.\n10. **Publish** with `method publish FILE --reason TEXT` when the user wants to share or schedule a version. It runs the Method's cases first.\n11. **Talk about the work, not about Method.** Unless the user asks, do not mention Method's versions, formats, settings files, or other internal files, and do not ask the user about them, about models, or about which saved version to use. Method updates itself and converts older Method files when it runs them. When the user asks whether a Method works, or asks you to make it work, run it with the inputs of a recent run (`--inputs-from RUN_ID`) and show the result and the dashboard link in a few sentences. Say that it works only after a run completed.\n12. **One file for each Method.** Change and run a Method in its own file. Do not copy it to a temporary or other folder to change it: Method does not run or save the copy while the Method's file exists, and names that file.\n13. **Questions in a run are for the user.** When a run stops with `needs_input`, ask the user its `question` in plain words, wait for the answer, and continue the run with it as the output says. Never answer it yourself.\n14. **Make each run easy to find and to run again.** Give the Method a `run_label` that tells its runs apart, such as `inputs.topic`. When an input can be empty and a default picks the value, point `run_label` at the step output that holds the resolved value, not at the input. Put the readable output, such as the report text or the message, in `result`, not only in files. Write a `run_prompt` that says where each input comes from (for example \"as_of is today's date in YYYY-MM-DD\") and what to show at the end. Leave SDK, runtime, and version details out of it.\n15. **Run again from the dashboard.** When the user pastes a \"Run again\" prompt from the dashboard, run with `--inputs-from RUN_ID` and change only what the prompt names: put those values in a file and add `--inputs FILE`.\n\nWhen a run fails, read failure.headline and failure.next, change what they name, and run again.\n";
 /** How to write the prompt inside a call, agent, or classify step. */
 export declare const promptRules = "# Write each prompt\n\n- **One task per prompt.** If a prompt says \"then\" or has several jobs, make several steps.\n- **Say what to do.** Leave out background that does not change the output.\n- **Show 1 to 3 examples of good output.** Take them from the user's work: examples in an existing prompt, a past output that the user approved, or the first run that the user accepts. Pass a long example as an input, not as text in the prompt.\n- **Put the output shape in `out`**, not in the prompt.\n- **Say what to do when the input does not have the answer**, for example \"leave due empty\". For classify, add an option such as `unclear`.\n\nBefore:\n\n```text\nYou are an expert support analyst with years of experience. Our company values clear\ncommunication. Read the tickets, decide which ones are urgent, write a summary, and\nreturn JSON with a \"summary\" key. Make it good.\n```\n\nAfter (urgency is a classify step before this one; the shape is in `out`):\n\n```text\nWrite a five-sentence summary of this week's support tickets for the team.\nStart with the high-urgency tickets. Quote no customer names.\nWrite it in the style of this summary from an earlier week:\n\n{{example}}\n```\n";
 /** Enough of the format to write a Method without reading the JSON schema. */
@@ -16,5 +16,5 @@ export declare const costRules = "Before describing execution cost, check how th
 /** What to watch after a Method works. */
 export declare const watchRules = "# Watch it\n\n- Look at failed and unconfirmed runs on the dashboard. A run that needs attention says which step failed and why.\n- For classify, watch how often the choice is `unclear` or below your threshold. A rise means the inputs changed.\n- For slow effects such as email delivery, schedule `method observe --pending`.\n";
 /** What to do after a Method works: production, improvement, and script cards. */
-export declare const afterRules = "# After it works\n\n- **Put it in an app:** `method connect APP_FOLDER` publishes it and prints the code to add.\n- **Improve the results:** when the user wants the results changed, `method improve FILE --note TEXT` makes a proposal from the recent runs; `method apply FILE` merges it.\n- **Explain the scripts:** `method explain FILE` writes a card for each script step.\n";
+export declare const afterRules = "# After it works\n\n- **Put it in an app:** `method connect APP_FOLDER` publishes it and prints the code to add.\n- **Record each reaction:** after you show a result, run `method judge RUN_ID wrong --note \"THEIR WORDS\"` (with `--corrected FILE` when they gave the right result) when the user corrects it or asks to change the Method because of it, and `method judge RUN_ID right` when they use or approve it. Do not ask them to confirm it. Method fixes the Method from wrong judgments; `method changes FILE` lists what it changed. For a Method that keeps run content on this computer, `method improve FILE --note TEXT` makes a local proposal and `method apply FILE` merges it.\n- **Explain the scripts:** `method explain FILE` writes a card for each script step.\n";
 export declare const exampleSelection = "After choosing the step types, read the examples that fit the design. Use their syntax; choose the steps for this task yourself.";

package/dist/packages/sdk/src/authoring-instructions.js

@@ -45,7 +45,7 @@ export const firstMethodRules = `# Build a Method
 14. **Make each run easy to find and to run again.** Give the Method a \`run_label\` that tells its runs apart, such as \`inputs.topic\`. When an input can be empty and a default picks the value, point \`run_label\` at the step output that holds the resolved value, not at the input. Put the readable output, such as the report text or the message, in \`result\`, not only in files. Write a \`run_prompt\` that says where each input comes from (for example "as_of is today's date in YYYY-MM-DD") and what to show at the end. Leave SDK, runtime, and version details out of it.
 15. **Run again from the dashboard.** When the user pastes a "Run again" prompt from the dashboard, run with \`--inputs-from RUN_ID\` and change only what the prompt names: put those values in a file and add \`--inputs FILE\`.
 
-When a run fails, read its \`fix\` and \`diagnostics\`, change the step, and run again.
+When a run fails, read failure.headline and failure.next, change what they name, and run again.
 `;
 /** How to write the prompt inside a call, agent, or classify step. */
 export const promptRules = `# Write each prompt
@@ -150,7 +150,7 @@ export const watchRules = `# Watch it
 export const afterRules = `# After it works
 
 - **Put it in an app:** \`method connect APP_FOLDER\` publishes it and prints the code to add.
-- **Improve the results:** when the user wants the results changed, \`method improve FILE --note TEXT\` makes a proposal from the recent runs; \`method apply FILE\` merges it.
+- **Record each reaction:** after you show a result, run \`method judge RUN_ID wrong --note "THEIR WORDS"\` (with \`--corrected FILE\` when they gave the right result) when the user corrects it or asks to change the Method because of it, and \`method judge RUN_ID right\` when they use or approve it. Do not ask them to confirm it. Method fixes the Method from wrong judgments; \`method changes FILE\` lists what it changed. For a Method that keeps run content on this computer, \`method improve FILE --note TEXT\` makes a local proposal and \`method apply FILE\` merges it.
 - **Explain the scripts:** \`method explain FILE\` writes a card for each script step.
 `;
 export const exampleSelection = "After choosing the step types, read the examples that fit the design. Use their syntax; choose the steps for this task yourself.";

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

@@ -1,3 +1,5 @@
 import { type RunInspection } from "../../workflow-language/src/inspection.js";
+/** The runtime's status of a finished run, in the dashboard's words; undefined for a status that is not known. */
+export declare function runStatus(status: unknown): RunInspection["status"] | undefined;
 /** Convert the public trace into the dashboard's stable inspection contract. */
 export declare function inspectCurrentRun(root: string, activeSnapshot?: boolean, includeFiles?: boolean | "references"): RunInspection;

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

@@ -5,6 +5,10 @@ import { join, sep, basename } from "node:path";
 import { createHash } from "node:crypto";
 import { loadWorkflow } from "../../workflow-language/src/validate.js";
 import { InspectionSchema } from "../../workflow-language/src/inspection.js";
+const finalEvents = new Set(["run.completed", "run.failed"]);
+const statuses = { completed: "succeeded", needs_input: "waiting_for_you", unconfirmed: "unconfirmed", failed: "failed" };
+/** The runtime's status of a finished run, in the dashboard's words; undefined for a status that is not known. */
+export function runStatus(status) { return typeof status === "string" && Object.hasOwn(statuses, status) ? statuses[status] : undefined; }
 /** Convert the public trace into the dashboard's stable inspection contract. */
 export function inspectCurrentRun(root, activeSnapshot = false, includeFiles = false) {
     const path = (name) => {
@@ -40,22 +44,24 @@ export function inspectCurrentRun(root, activeSnapshot = false, includeFiles = f
             ...(typeof event.operation_id === 'string' ? { operation_id: event.operation_id } : {}),
             ...(typeof event.confidence === 'number' ? { confidence: event.confidence } : {}),
             ...(event.kind === 'classify' && event.usage !== undefined ? { usage: event.usage } : {}),
-            ...(typeof event.duration_ms === 'number' ? { duration_ms: event.duration_ms } : event.event.startsWith('run.') && typeof event.elapsed_ms === 'number' ? { duration_ms: event.elapsed_ms } : {}),
+            // Only the final run event gives the run its duration.
+            ...(typeof event.duration_ms === 'number' ? { duration_ms: event.duration_ms } : finalEvents.has(event.event) && typeof event.elapsed_ms === 'number' ? { duration_ms: event.elapsed_ms } : {}),
             at: event.at, type: event.event === "human.required" ? "human_input_required" : event.event.replaceAll(".", "_"),
-            ...(event.check ? { detail: `${event.check.status}: ${event.check.reason}` } : event.message || event.error ? { detail: String(event.message ?? event.error).slice(0, 4000) } : event.code ? { detail: String(event.code) } : {}),
+            // The runtime writes one plain sentence for each event that users see.
+            ...(event.message || event.error ? { detail: String(event.message ?? event.error).slice(0, 4000) } : event.code ? { detail: String(event.code) } : {}),
             ...(Number.isInteger(event.sequence) ? { sequence: event.sequence } : {}),
             ...(["action", "check"].includes(event.phase) ? { phase: event.phase } : {}),
             ...(typeof event.tool === "string" ? { tool: event.tool } : {}),
             ...(typeof event.call_id === "string" ? { call_id: event.call_id } : {}),
             ...(typeof event.child === "string" ? { child: event.child } : {}),
-            ...(Number.isSafeInteger(event.completed) && Number.isSafeInteger(event.total) ? { completed: event.completed, total: event.total, ...(typeof event.unit === "string" ? { unit: event.unit } : {}) } : {}),
+            ...(Number.isSafeInteger(event.completed) && Number.isSafeInteger(event.total) ? { completed: event.completed } : {}),
+            ...(Number.isSafeInteger(event.total) ? { total: event.total, ...(typeof event.unit === "string" ? { unit: event.unit } : {}) } : {}),
+            ...(typeof event.key === "string" ? { key: event.key } : {}),
+            ...(Number.isSafeInteger(event.attempt) ? { attempt: event.attempt } : {}), ...(Number.isSafeInteger(event.attempts) ? { attempts: event.attempts } : {}),
             ...(event.entrypoint ? { command: [event.runtime, event.entrypoint, ...(event.args ?? [])].filter(Boolean).join(" ") } : typeof event.command === "string" ? { command: event.command } : {}),
             ...(event.exit_code !== undefined ? { exit_code: event.exit_code } : {}),
             ...(typeof event.diagnostics === "string" && event.diagnostics ? { diagnostics: event.diagnostics.length <= 4000 ? event.diagnostics : event.diagnostics.slice(0, 1000) + "\n[middle omitted]\n" + event.diagnostics.slice(-3000) } : {}),
         };
-        // Effect verdicts are run events, so the dashboard shows them without a new inspection field.
-        if (event.event === "effect.observed")
-            recorded.detail = `${event.effect}: ${event.verdict}${event.final ? "" : " (observation continues)"}. ${String(event.reason ?? "")}`.slice(0, 4000);
         if (event.event === "run.status_changed")
             recorded.detail = `Status changed from ${event.from} to ${event.to} after a later observation.`;
         if (event.event === "effects.waived")
@@ -94,7 +100,6 @@ export function inspectCurrentRun(root, activeSnapshot = false, includeFiles = f
             row.changes = {};
             delete row.prompts;
             delete row.verification;
-            delete row.failure;
             delete row.observed_effects;
         }
         row.events.push(recorded);
@@ -105,7 +110,6 @@ export function inspectCurrentRun(root, activeSnapshot = false, includeFiles = f
             row.inputs = event.inputs;
             row.checks = [];
             delete row.outputs;
-            delete row.error;
         }
         if (event.event === "step.candidate") {
             const { state, ...outputs } = event.candidate;
@@ -127,20 +131,25 @@ export function inspectCurrentRun(root, activeSnapshot = false, includeFiles = f
         if (event.event === "step.skipped")
             row.status = "skipped";
         if (event.event === "human.required")
-            row.status = "needs_attention";
+            row.status = "waiting_for_you";
+    }
+    const status = active ? "running" : runStatus(summary.status);
+    if (!status)
+        throw Error(`The run record has an unknown status: ${String(summary.status)}.`);
+    const failure = active ? undefined : summary.failure;
+    if (!active && !["completed", "unconfirmed"].includes(summary.status)) {
+        // The failed step's failed tasks are failed. Other unfinished tasks stopped with the run; the failure is not theirs.
+        const failed = summary.status === "failed" && failure?.step ? new Set((failure.failed_iterations?.length ? failure.failed_iterations : [failure.iteration ?? 0]).map((i) => `${failure.step}:${i}`)) : new Set();
+        for (const [id, row] of Object.entries(invocations))
+            if (["running", "returned"].includes(row.status))
+                row.status = failed.has(id) ? "failed" : "stopped";
     }
-    if (!active && summary.status !== "completed")
-        for (const row of Object.values(invocations))
-            if (["running", "returned"].includes(row.status)) {
-                row.status = "needs_attention";
-                row.error = summary.error ?? "Run interrupted";
-            }
     const files = includeFiles ? attachResultFiles(workflow, invocations, [join(root, "artifacts")], join(root, "artifacts"), includeFiles === "references") : undefined;
     const lastAccepted = events.filter(e => e.event === "step.accepted").at(-1);
     return InspectionSchema.parse({ schema: "workflow-inspection/2", workflow, run_id: basename(root), local_run_directory: root,
         ...(typeof (summary.started_at ?? start?.at) === 'string' ? { started_at: summary.started_at ?? start.at } : {}),
         ...(typeof (summary.device_name ?? start?.device_name) === 'string' ? { device_name: summary.device_name ?? start.device_name } : {}),
-        events: runEvents, ...(includeFiles ? { files } : {}), status: active ? "running" : summary.status === "completed" ? "succeeded" : "needs_attention",
-        ...(summary.error ? { error: summary.error } : {}), inputs: start?.inputs ?? {}, state: lastAccepted?.state ?? start?.initial_state ?? {},
+        events: runEvents, ...(includeFiles ? { files } : {}), status,
+        ...(failure ? { failure } : {}), inputs: start?.inputs ?? {}, state: lastAccepted?.state ?? start?.initial_state ?? {},
         resources: Object.fromEntries(Object.entries(start?.config?.environment ?? {}).map(([key, value]) => [key, { description: workflow.environment?.[key]?.description ?? key, path: value }])), invocations });
 }

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

@@ -13,6 +13,7 @@ import { writePrivateJson } from './files.js';
 import { runMethod as executeMethod } from "@withmethod/runtime/runner.js";
 import { localSetup } from "./local-setup.js";
 import { authoringPath } from "./authoring.js";
+import { failureLines } from "./failure.js";
 export { executeMethod as runCurrentMethod };
 /** Recent run folders on this computer, newest first. The runtime reuses only iterations whose key matches. */
 export function recentRuns(exclude, limit = 20) {
@@ -148,8 +149,11 @@ export async function runCurrentFile(file, flags, syncFactory, onEvent, client =
         let display = synced ? { ...result, dashboard: sync.dashboard, dashboard_sync: synced } : result;
         // A run that waits for a person shows the question itself, so the agent can ask the user and pass on the answer.
         const question = result.status === 'needs_input' ? (await import('./worker.js')).lastQuestion(authoringPath(flags['run-dir'])) : null;
-        if (question)
-            display = { ...display, question, fix: `Ask the user this question in plain words and wait for the answer; do not answer it yourself. Then write {"steps": {"${question.step}": {"outputs": {...}}}} with the user's answer (the fields are in question.form) to a file, and run the same command again with --resume --run-dir ${JSON.stringify(flags['run-dir'])} --human FILE.` };
+        if (question && display.failure)
+            display = { ...display, question, failure: { ...display.failure, next: { ...display.failure.next, text: `Ask the user this question in plain words and wait for the answer; do not answer it yourself. Then write {"steps": {"${question.step}": {"outputs": {...}}}} with the user's answer (the fields are in question.form) to a file, and run the same command again with --resume --run-dir ${JSON.stringify(flags['run-dir'])} --human FILE.` } } };
+        // People read three plain lines on stderr; agents, apps, and tests parse the JSON on stdout.
+        if (result.status === "failed" && display.failure)
+            process.stderr.write(failureLines(display.failure) + (display.dashboard ? `Dashboard: ${display.dashboard}\n` : ""));
         process.stdout.write(JSON.stringify(display, null, 2) + "\n");
         // 3: every step finished, but an observer could not confirm an external change.
         if (result.status !== "completed")

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

@@ -0,0 +1,11 @@
+import { type RunFailure } from "../../workflow-language/src/inspection.js";
+/**
+ * The failure record of a run that stopped before its first step. A runtime error carries its own record; an SDK error
+ * gets one from the runtime's templates: an SDK setup error has a code or is a plain Error, and any other error type
+ * is a bug in Method.
+ */
+export declare function setupFailure(error: any): RunFailure;
+/** The record of a run whose own record Method could not read. */
+export declare function unreadableRecord(error: unknown): RunFailure;
+/** The three plain lines that a failed run prints on stderr. */
+export declare function failureLines(failure: RunFailure): string;

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

@@ -0,0 +1,25 @@
+import { failureRecord } from "@withmethod/runtime/failure.js";
+import { FailureOwnerSchema, FailureSchema, ownerText } from "../../workflow-language/src/inspection.js";
+/**
+ * The failure record of a run that stopped before its first step. A runtime error carries its own record; an SDK error
+ * gets one from the runtime's templates: an SDK setup error has a code or is a plain Error, and any other error type
+ * is a bug in Method.
+ */
+export function setupFailure(error) {
+    if (FailureSchema.safeParse(error?.failure).success)
+        return error.failure;
+    const owner = FailureOwnerSchema.safeParse(error?.owner).success ? error.owner
+        : error?.code === "needs_input" ? "needs_you"
+            : error?.code || error?.constructor === Error ? "setup" : "method_platform";
+    const message = error instanceof Error ? error.message : String(error);
+    return FailureSchema.parse(failureRecord({ message, owner, ...(error?.code ? { code: error.code } : {}), ...(error?.missing ? { missing: error.missing } : {}) }, { phase: "setup" }));
+}
+/** The record of a run whose own record Method could not read. */
+export function unreadableRecord(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { ...FailureSchema.parse(failureRecord({ message, owner: "method_platform", code: "unreadable_record" })), headline: "Method could not read this run's record." };
+}
+/** The three plain lines that a failed run prints on stderr. */
+export function failureLines(failure) {
+    return `Failed: ${failure.headline}\nWhose problem: ${ownerText(failure.owner)}\nNext: ${failure.next.text}\n`;
+}

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

@@ -1,5 +1,5 @@
 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. */
+/** run_id: the run folder on this computer that the note is about. */
 export type ImproveRequest = {
     step_id?: string;
     note?: string;
@@ -27,11 +27,14 @@ type ProposalKind = 'change' | 'case' | 'rubric' | 'script' | 'none';
  * 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;
+export declare const judgmentsLine = "Method fixes this Method from your judgments. Record the person's reaction: method judge RUN_ID wrong --note \"...\".";
 /**
- * `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.
+ * `method improve FILE`. A Method that keeps run content in the account is fixed from the person's judgments
+ * (method judge), so this prints that and starts nothing. A Method with device run data (run_data: device, or an
+ * organization that keeps run content on devices) 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>;
+export declare function improveCommand(args: string[], clientFactory: (server: string) => MethodClient, run?: RunFile): Promise<boolean | undefined>;
 /** Download the published improve.method and its files into the Method cache, once per version. */
 export declare function cachedImproveMethod(client: MethodClient): Promise<{
     file: string;

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

@@ -9,7 +9,7 @@ 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 { currentVersion, methodContent } from './versions.js';
 import { localRuns, saveLocalProposal } from './proposals.js';
 const kinds = ['change', 'case', 'rubric', 'script', 'none'];
 /**
@@ -50,9 +50,12 @@ const nextStep = (file, id, kind) => ({
     none: 'No safe change was found.',
 })[kind];
 const print = (value) => process.stdout.write(JSON.stringify(value, null, 2) + '\n');
+export const judgmentsLine = 'Method fixes this Method from your judgments. Record the person\'s reaction: method judge RUN_ID wrong --note "...".';
 /**
- * `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.
+ * `method improve FILE`. A Method that keeps run content in the account is fixed from the person's judgments
+ * (method judge), so this prints that and starts nothing. A Method with device run data (run_data: device, or an
+ * organization that keeps run content on devices) 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' } } });
@@ -66,24 +69,15 @@ export async function improveCommand(args, clientFactory, run) {
     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;
-        }
+    if (document.run_data !== 'device' && !await (await import('./method-sync.js')).organizationKeepsContent(client)) {
+        process.stdout.write(judgmentsLine + '\n');
+        return;
     }
+    // A note is about the newest run of the Method on this computer.
+    const newest = request.note ? (await localRuns(file))[0] : undefined;
     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. */

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

@@ -9,7 +9,7 @@ export function inspectRun(directory, options = {}) {
     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")) : [] });
+        return InspectionSchema.parse({ ...initial, local_run_directory: root, ...(failure ? { status: failure.code === 'needs_input' ? 'waiting_for_you' : 'failed', failure } : {}), 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);

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

@@ -0,0 +1,20 @@
+import { type MethodClient } from './method-client.js';
+export declare const maxNoteLength = 4000;
+export declare const maxCorrectedBytes: number;
+export type Judgment = {
+    id: string;
+    run_id: string;
+    method_id: string;
+    verdict: 'right' | 'wrong';
+    step_id: string | null;
+    created_at: string;
+};
+/** The corrected result in a file: its JSON value when it parses as JSON, or else its text. */
+export declare function correctedValue(path: string): unknown;
+/** The one line that says what was recorded. */
+export declare function judgmentLine(judgment: Pick<Judgment, 'verdict' | 'step_id'>, fixing: boolean): string;
+/**
+ * `method judge RUN_ID right|wrong [--step ID] [--note TEXT] [--corrected FILE] [--json]`: record the person's reaction
+ * to a run's result. RUN_ID is the dashboard run ID or this computer's run ID; the server resolves both.
+ */
+export declare function judgeCommand(args: string[], clientFactory: (server: string) => MethodClient): Promise<void>;

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

@@ -0,0 +1,59 @@
+import { readFileSync, statSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { DEFAULT_SERVER } from './method-client.js';
+export const maxNoteLength = 4000;
+export const maxCorrectedBytes = 1024 * 1024;
+/** The corrected result in a file: its JSON value when it parses as JSON, or else its text. */
+export function correctedValue(path) {
+    let size;
+    try {
+        size = statSync(path).size;
+    }
+    catch {
+        throw Error(`Cannot read ${path}.`);
+    }
+    if (size > maxCorrectedBytes)
+        throw Error(`${path} is larger than 1 MB. Give a shorter corrected result.`);
+    const text = readFileSync(path, 'utf8');
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+/** The one line that says what was recorded. */
+export function judgmentLine(judgment, fixing) {
+    return `Recorded: ${judgment.verdict}${judgment.step_id ? ` on step ${judgment.step_id}` : ''}.${fixing ? ' Method is fixing it in the background.' : ''}`;
+}
+/**
+ * `method judge RUN_ID right|wrong [--step ID] [--note TEXT] [--corrected FILE] [--json]`: record the person's reaction
+ * to a run's result. RUN_ID is the dashboard run ID or this computer's run ID; the server resolves both.
+ */
+export async function judgeCommand(args, clientFactory) {
+    const usage = 'Use method judge RUN_ID right|wrong [--step STEP_ID] [--note TEXT] [--corrected FILE].';
+    const { values, positionals } = parseArgs({ args, allowPositionals: true, options: {
+            step: { type: 'string' }, note: { type: 'string' }, corrected: { type: 'string' }, json: { type: 'boolean' }, server: { type: 'string' }
+        } });
+    const [runId, verdict] = positionals;
+    if (!runId || !verdict || positionals.length !== 2)
+        throw Error(usage);
+    if (verdict !== 'right' && verdict !== 'wrong')
+        throw Error(`Judge the result right or wrong, not ${verdict}. ${usage}`);
+    const note = values.note?.trim();
+    if (values.note !== undefined && !note)
+        throw Error('Write the person\'s words after --note.');
+    if (note && note.length > maxNoteLength)
+        throw Error(`The note has ${note.length} characters; the most is ${maxNoteLength}.`);
+    if (values.step !== undefined && !values.step.trim())
+        throw Error('Write the step ID after --step.');
+    const body = { verdict, ...(values.step ? { step_id: values.step.trim() } : {}), ...(note ? { note } : {}),
+        ...(values.corrected !== undefined ? { corrected: correctedValue(values.corrected) } : {}) };
+    const client = clientFactory(values.server ?? DEFAULT_SERVER);
+    const response = await client.request(`/api/cli/runs/${encodeURIComponent(runId)}/judgments`, 'POST', body);
+    if (values.json) {
+        process.stdout.write(JSON.stringify(response, null, 2) + '\n');
+        return;
+    }
+    process.stdout.write(judgmentLine(response.judgment, !!response.fixing) + '\n');
+}

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

@@ -12,7 +12,7 @@ export declare const commandHelp: Record<string, Command>;
 export declare function renderCommand(name: string, includeCommon?: boolean): string;
 export declare const guideTopics: readonly ["start", "concepts", "execution", "examples", "example", "recipes", "recovery", "commands"];
 export declare function authoringGuide(topic?: string, exampleId?: string): string;
-export declare const overviewHelp = "Method \u2014 author, save and run methods with your coding agent.\n\nBefore creating, editing, or proposing a Method, run `method authoring` and read its guidance. Do this before choosing an existing Method as a reference.\n\nLearn: method authoring                 Start the installed guide.\n       method authoring all             Read the full manual offline.\n       method COMMAND --help            Read arguments, results and examples.\n       method help step add             Read help for a subcommand.\n       method schema [TYPE]             Read a formal JSON schema.\n\nLocal drafts: init, show, set, remove, step add/update/remove/move,\n              check set/remove, validate, diff.\nOnline documents: list, get, steps, step, publish, explain.\nImprovements: improve, proposals, apply.\nKeys for scripts: secret find, secret import, secret set, secret list.\nExecution and evidence: run, run-status, wait, cancel, runs, logs, sync, observe.\nEffects and corrections: effect add/list, case new/retire/list, test.\nInputs and shared state: bind, state.\nBrowser and computer setup: browser connect, config.\nAccount access: status, login, logout, devices, revoke.\nProduction runs: connect, answer, keys create/list/revoke, worker.\n\nSign in with method login first. Read the authoring guide, give each prompt its own step, write the files, validate, and run. Each signed-in run saves a version when the file changed. Publish a version when the user wants to share or schedule it.\nUse method run task.method to run it.\nOnline server: https://app.withmethod.ai. Use --server only to select another\nserver. Sign-in uses browser approval. Never send credentials in chat.\n";
+export declare const overviewHelp = "Method \u2014 author, save and run methods with your coding agent.\n\nBefore creating, editing, or proposing a Method, run `method authoring` and read its guidance. Do this before choosing an existing Method as a reference.\n\nLearn: method authoring                 Start the installed guide.\n       method authoring all             Read the full manual offline.\n       method COMMAND --help            Read arguments, results and examples.\n       method help step add             Read help for a subcommand.\n       method schema [TYPE]             Read a formal JSON schema.\n\nLocal drafts: init, show, set, remove, step add/update/remove/move,\n              check set/remove, validate, diff.\nOnline documents: list, get, steps, step, publish, explain.\nResults and improvements: judge, changes, improve, apply.\nKeys for scripts: secret find, secret import, secret set, secret list.\nExecution and evidence: run, run-status, wait, cancel, runs, logs, sync, observe.\nEffects and corrections: effect add/list, case new/retire/list, test.\nInputs and shared state: bind, state.\nBrowser and computer setup: browser connect, config.\nAccount access: status, login, logout, devices, revoke.\nProduction runs: connect, answer, keys create/list/revoke, worker.\n\nSign in with method login first. Read the authoring guide, give each prompt its own step, write the files, validate, and run. Each signed-in run saves a version when the file changed. Publish a version when the user wants to share or schedule it.\nUse method run task.method to run it.\nOnline server: https://app.withmethod.ai. Use --server only to select another\nserver. Sign-in uses browser approval. Never send credentials in chat.\n";
 /** Resolve help before parsing flags, creating a client, or touching any draft. */
 export declare function methodHelp(args: string[]): string | undefined;
 /** The CLI and published reference use this same command inventory. */