mthds 0.9.0 → 0.11.0

package/README.md

@@ -136,24 +136,31 @@ npx mthds setup runner pipelex
 
 ### Configure the API runner
 
-The API runner is the default. Set it up interactively:
+The local pipelex runner is the default; to use the hosted (or self-hosted) API instead, set up the API runner interactively:
 
 ```bash
 mthds setup runner api
 ```
 
-This prompts for the API URL and API key (masked input) and saves them to `~/.mthds/config`.
+This prompts for the API base URL and an API key (masked input), and saves them to `~/.mthds/config`.
+
+There is ONE base URL — the host only, with no version prefix. The SDK composes every endpoint as `{base}/v1/{endpoint}`:
+
+- **`base-url`** — hosted: `https://api.pipelex.com` (the default). Self-hosted: `http://localhost:8081` (a bare [pipelex-api](https://github.com/Pipelex/pipelex-api) runner).
 
 You can also set values directly:
 
 ```bash
 mthds config set api-key YOUR_KEY
-mthds config set api-url https://your-api-instance.com
+# Hosted (default):
+mthds config set base-url https://api.pipelex.com
+# Self-hosted bare runner:
+mthds config set base-url http://localhost:8081
 ```
 
 Configuration is stored in `~/.mthds/config` and shared between mthds-js and mthds-python.
 
-You can also use environment variables (`PIPELEX_API_KEY`, `PIPELEX_API_URL`) which take precedence over the config file.
+You can also use environment variables (`MTHDS_API_KEY`, `MTHDS_API_URL`) which take precedence over the config file.
 
 See the [SDK Usage](#sdk-usage) section below to connect to a Pipelex API instance programmatically.
 
@@ -171,11 +178,11 @@ npm install mthds
 import { MthdsApiClient } from "mthds";
 
 const client = new MthdsApiClient({
-  apiBaseUrl: "https://api.pipelex.com",
+  baseUrl: "https://api.pipelex.com",
   apiToken: "your-api-key",
 });
 
-const result = await client.executePipeline({
+const result = await client.execute({
   pipe_code: "my-pipeline",
   inputs: {
     topic: "quantum computing",
@@ -185,50 +192,65 @@ const result = await client.executePipeline({
 console.log(result.pipe_output);
 ```
 
+The base URL is the host only — every endpoint composes as `{baseUrl}/v1/{endpoint}` (e.g. `https://api.pipelex.com/v1/execute`); `/health` resolves to the origin root.
+
 ### Self-hosted API
 
-Point the client to your own [pipelex-api](https://github.com/Pipelex/pipelex-api) instance:
+Point the client at your own [pipelex-api](https://github.com/Pipelex/pipelex-api) instance — the same `MTHDSProtocol` surface, same paths:
 
 ```typescript
 const client = new MthdsApiClient({
-  apiBaseUrl: "http://localhost:8081",
+  baseUrl: "http://localhost:8081",
   apiToken: "your-api-key",
 });
 ```
 
+The bare open-source runner has no run store, so the durable run-lifecycle methods (`getRunStatus`/`getRunResult`/`waitForResult`) throw a clear `RunLifecycleUnavailableError` against it — use `execute` (blocking) or `start` instead (completion delivery is implementation-defined — see your runner's API documentation). The `GET /v1/version` handshake tells the SDK which deployment it is talking to.
+
+> Note: the bare-runner blocking path returns the runner's native `pipe_output`, whereas the hosted durable path returns `main_stuff` + `graph_spec`. Cross-shape normalization is a v1 TODO.
+
 ### Environment variables
 
 Instead of passing options to the constructor, you can set environment variables:
 
 | Variable | Description |
 |----------|-------------|
-| `PIPELEX_API_URL` | Base URL of the API |
-| `PIPELEX_API_KEY` | API authentication token |
+| `MTHDS_API_URL` | API base URL — host only, no version prefix (default `https://api.pipelex.com`) |
+| `MTHDS_API_KEY` | API authentication token |
 
 ```typescript
-// Reads PIPELEX_API_URL and PIPELEX_API_KEY from the environment
+// Reads MTHDS_API_URL and MTHDS_API_KEY from the environment
 const client = new MthdsApiClient();
 ```
 
 ### Methods
 
-| Method | Description |
-|--------|-------------|
-| `executePipeline(options)` | Execute a pipeline and wait for the result |
-| `startPipeline(options)` | Start a pipeline asynchronously |
+The client implements the MTHDS Protocol plus the hosted run-lifecycle extension:
+
+| Method | Route | Description |
+|--------|-------|-------------|
+| `execute(options)` | `POST /v1/execute` | Execute a method and wait for the result — returns a `RunResultExecute` (throws `RunStillRunningError` on the protocol's optional 202 degrade) |
+| `start(options)` | `POST /v1/start` | Start a method asynchronously — returns a `RunResultStart` with the authoritative `pipeline_run_id` |
+| `validate(mthdsContents, allowSignatures?, mthdsSources?)` | `POST /v1/validate` | Parse, validate, and dry-run a bundle — returns a typed `PipelexValidationResult` discriminated on `is_valid`; an invalid bundle is a produced verdict (`is_valid: false` with `validation_errors`), not a throw. Only a no-verdict non-2xx (malformed request, auth, server fault) throws `ApiResponseError`. `mthdsSources` (optional, parallel to `mthdsContents`) names each submitted file so cross-file diagnostics resolve the owning file |
+| `models(category?)` | `GET /v1/models` | The model deck the runner routes to |
+| `version()` | `GET /v1/version` | Protocol + implementation versions (the feature-detection handshake) |
+| `getRunStatus(runId)` | `GET /v1/runs/{id}/status` | Hosted extension — self-healing status read |
+| `getRunResult(runId)` | `GET /v1/runs/{id}/results` | Hosted extension — single-shot result lookup |
+| `waitForResult(runId, options?)` | — | Hosted extension — poll to a terminal state |
 
-### Pipeline options
+### Run options
 
 | Option | Type | Description |
 |--------|------|-------------|
-| `pipe_code` | `string` | Pipeline code to execute |
-| `mthds_content` | `string` | Raw method content (alternative to `pipe_code`) |
-| `inputs` | `Record<string, string \| string[] \| object>` | Pipeline input variables |
+| `pipe_code` | `string` | Pipe code to execute |
+| `mthds_contents` | `string[]` | Raw bundle contents (alternative to `pipe_code`) |
+| `inputs` | `Record<string, string \| string[] \| object>` | Method input variables |
 | `output_name` | `string` | Name of the output to return |
 | `output_multiplicity` | `boolean \| number` | Expected output multiplicity |
-| `dynamic_output_concept_code` | `string` | Dynamic output concept code |
+| `dynamic_output_concept_ref` | `string` | Dynamic output concept reference |
+| `extra` | `Record<string, unknown>` | Server-specific extension args, forwarded verbatim into the request body (e.g. a stored-method id) |
 
-Either `pipe_code` or `mthds_content` must be provided.
+Either `pipe_code` or `mthds_contents` must be provided (or a server-specific extension arg via `extra`). Anything beyond the protocol's basic args is server-specific and rides the generic `extra` option, merged into the request body — the server you call defines and handles its own extension args (a client-supplied run id, where a server supports one, is such an extension; the request side never names it). `startAndWaitForResult()` runs the whole start + poll lifecycle in one call.
 
 ## Telemetry
 

package/dist/agent/binaries.js

@@ -22,7 +22,7 @@ const VERSION_RE = /^[\w-]+\s+(\d+\.\d+\.\d+)/;
 const PIPELEX_PKG = {
     package: "pipelex",
     uv_package: "pipelex",
-    version_constraint: ">=0.30.2",
+    version_constraint: ">=0.32.1",
     version_extract: VERSION_RE,
     install_url: "https://pypi.org/project/pipelex/",
     auto_installable: true,
@@ -31,7 +31,7 @@ const PIPELEX_PKG = {
 const PIPELEX_TOOLS_PKG = {
     package: "pipelex-tools",
     uv_package: "pipelex-tools",
-    version_constraint: ">=0.4.0",
+    version_constraint: ">=0.6.0",
     version_extract: VERSION_RE,
     install_url: "https://pypi.org/project/pipelex-tools/",
     auto_installable: true,

package/dist/agent/commands/api-commands.d.ts

@@ -11,3 +11,11 @@ import type { Runner } from "../../runners/types.js";
  * Only called when --runner=api.
  */
 export declare function registerApiRunnerCommands(program: Command, makeRunner: () => Runner): void;
+/**
+ * Run the protocol validate (`POST /v1/validate`) and emit the agent envelope.
+ * `/validate` is a diagnostic endpoint: a valid bundle returns the structural
+ * artifacts (`is_valid: true`); an invalid bundle is a produced verdict (a 200
+ * `is_valid: false` body), surfaced as a structured ValidateBundleError envelope —
+ * not a thrown error. A non-2xx (a no-verdict condition) still throws.
+ */
+export declare function runProtocolValidate(runner: Runner, mthdsContents: string[], allowSignatures: boolean, mthdsSources?: string[]): Promise<void>;

package/dist/agent/commands/api-commands.js

@@ -7,9 +7,9 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { agentError, agentSuccess, AGENT_ERROR_DOMAINS } from "../output.js";
-function collect(val, prev) {
-    return [...prev, val];
-}
+import { isApiRunner } from "../../cli/commands/utils.js";
+import { MODEL_CATEGORIES } from "../../protocol/models.js";
+import { ApiResponseError, RunFailedError, RunTimeoutError } from "../../runners/api/exceptions.js";
 /**
  * Register all API-runner commands on the program.
  * Only called when --runner=api.
@@ -114,7 +114,7 @@ export function registerApiRunnerCommands(program, makeRunner) {
     validateGroup
         .command("bundle")
         .argument("[target]", "Bundle file (.mthds) or directory")
-        .option("--pipe <code>", "Pipe code to validate within the bundle")
+        .option("--allow-signatures", "Tolerate unimplemented pipe signatures")
         .option("--content <mthds>", "Bundle content as a string")
         .description("Validate a bundle file or content")
         .allowUnknownOption()
@@ -123,62 +123,26 @@ export function registerApiRunnerCommands(program, makeRunner) {
         .action(async (target, options) => {
         const runner = safeCreateRunner(makeRunner);
         const mthdsContent = resolveContent(target, options.content);
-        try {
-            const result = await runner.validate({
-                mthds_contents: [mthdsContent],
-                pipe_code: options.pipe,
-            });
-            if (result.success) {
-                agentSuccess({ ...result });
-            }
-            else {
-                agentError(result.message, "ValidationError", {
-                    error_domain: AGENT_ERROR_DOMAINS.VALIDATION,
-                });
-            }
-        }
-        catch (err) {
-            agentError(err.message, "RunnerError", {
-                error_domain: AGENT_ERROR_DOMAINS.RUNNER,
-            });
-        }
+        // A real file path (not inline --content) names the source for diagnostics.
+        const mthdsSources = !options.content && target ? [target] : undefined;
+        await runProtocolValidate(runner, [mthdsContent], options.allowSignatures ?? false, mthdsSources);
     });
     validateGroup
         .command("pipe")
-        .argument("<target>", "Pipe code or .mthds bundle file")
-        .option("--pipe <code>", "Pipe code to validate")
-        .description("Validate a pipe by code or bundle file")
+        .argument("<target>", ".mthds bundle file")
+        .option("--allow-signatures", "Tolerate unimplemented pipe signatures")
+        .description("Validate a bundle file (protocol validate covers every pipe in it)")
         .allowUnknownOption()
         .allowExcessArguments(true)
         .exitOverride()
         .action(async (target, options) => {
         const runner = safeCreateRunner(makeRunner);
-        if (target.endsWith(".mthds")) {
-            const mthdsContent = readFileOrError(target);
-            try {
-                const result = await runner.validate({
-                    mthds_contents: [mthdsContent],
-                    pipe_code: options.pipe,
-                });
-                handleValidateResult(result);
-            }
-            catch (err) {
-                agentError(err.message, "RunnerError", {
-                    error_domain: AGENT_ERROR_DOMAINS.RUNNER,
-                });
-            }
-        }
-        else {
-            try {
-                const result = await runner.validate({ pipe_code: target });
-                handleValidateResult(result);
-            }
-            catch (err) {
-                agentError(err.message, "RunnerError", {
-                    error_domain: AGENT_ERROR_DOMAINS.RUNNER,
-                });
-            }
+        if (!target.endsWith(".mthds")) {
+            agentError("Validating a bare pipe code is not supported via the API runner — the protocol validate takes bundle contents. Pass a .mthds file.", "ArgumentError", { error_domain: AGENT_ERROR_DOMAINS.ARGUMENT });
+            return;
         }
+        const mthdsContent = readFileOrError(target);
+        await runProtocolValidate(runner, [mthdsContent], options.allowSignatures ?? false, [target]);
     });
     validateGroup
         .command("method")
@@ -188,20 +152,8 @@ export function registerApiRunnerCommands(program, makeRunner) {
         .allowUnknownOption()
         .allowExcessArguments(true)
         .exitOverride()
-        .action(async (target, options) => {
-        const runner = safeCreateRunner(makeRunner);
-        try {
-            const result = await runner.validate({
-                method_url: target,
-                pipe_code: options.pipe,
-            });
-            handleValidateResult(result);
-        }
-        catch (err) {
-            agentError(err.message, "RunnerError", {
-                error_domain: AGENT_ERROR_DOMAINS.RUNNER,
-            });
-        }
+        .action(async () => {
+        agentError("'validate method' is not supported via the API runner — the protocol validate takes bundle contents, not a method URL. Pass a .mthds file to 'validate bundle', or use --runner pipelex.", "UnsupportedError", { error_domain: AGENT_ERROR_DOMAINS.RUNNER });
     });
     // ── inputs ──
     const inputsGroup = program
@@ -310,12 +262,17 @@ export function registerApiRunnerCommands(program, makeRunner) {
             inputs = parseJsonOrError(raw, "inputs file");
         }
         try {
-            const result = await runner.execute({
+            const result = await runner.startAndWaitForResult({
                 mthds_contents: [mthdsContent],
                 pipe_code: pipeCode,
                 inputs,
             });
-            agentSuccess({ ...result });
+            agentSuccess({
+                state: "completed",
+                pipeline_run_id: result.pipeline_run_id,
+                main_stuff: result.main_stuff ?? result.pipe_output ?? null,
+                graph_spec: result.graph_spec ?? null,
+            });
         }
         catch (err) {
             agentError(err.message, "RunnerError", {
@@ -349,20 +306,31 @@ export function registerApiRunnerCommands(program, makeRunner) {
         .allowExcessArguments(true)
         .exitOverride()
         .action(runAction);
-    // ── models ──
-    program
-        .command("models")
-        .description("List available model presets, aliases, and waterfalls")
-        .option("--type <type>", "Filter by model category (repeatable)", collect, [])
+    // ── run start ──
+    // Submit a run and return its id immediately. All run state lives behind the
+    // returned `pipeline_run_id` (DB + Temporal), so an agent can submit here,
+    // disconnect, and later resume with `run status` / `run result` / `run poll`.
+    runGroup
+        .command("start")
+        .argument("[target]", "Bundle file (.mthds) or directory")
+        .option("--pipe <code>", "Pipe code to run")
+        .option("-i, --inputs <file>", "Path to JSON inputs file")
+        .option("--content <mthds>", "Bundle content as a string")
+        .option("--inputs-json <json>", "Inputs as a JSON string")
+        .option("--extra <json>", "Server-specific extension args as a JSON object (e.g. a stored-method run) — forwarded to the runner verbatim")
+        .option("--output-name <name>", "Name of the output slot to write to")
+        .option("--output-multiplicity <value>", "Output multiplicity: 'false', 'true', or an exact count")
+        .option("--dynamic-output <concept_ref>", "Override for the dynamic output concept ref")
+        .description("Start a run and return its id without waiting")
         .allowUnknownOption()
         .allowExcessArguments(true)
         .exitOverride()
-        .action(async (options) => {
+        .action(async (target, options) => {
         const runner = safeCreateRunner(makeRunner);
+        const startOptions = resolveStartOptions(target, options);
         try {
-            const request = options.type?.length ? { type: options.type } : undefined;
-            const result = await runner.models(request);
-            agentSuccess({ ...result });
+            const ack = await runner.start(startOptions);
+            agentSuccess({ ...ack });
         }
         catch (err) {
             agentError(err.message, "RunnerError", {
@@ -370,24 +338,151 @@ export function registerApiRunnerCommands(program, makeRunner) {
             });
         }
     });
-    // ── check-model ──
-    program
-        .command("check-model")
-        .description("Validate a model reference with fuzzy suggestions")
-        .argument("<reference>", "Model reference to check")
-        .requiredOption("--type <type>", "Model category (llm, extract, img_gen, search)")
-        .option("--format <format>", "DEPRECATED: agent CLI emits JSON only via agentSuccess envelope")
+    // ── run status ──
+    runGroup
+        .command("status")
+        .argument("<pipeline_run_id>", "Run id")
+        .description("Fetch a run's current status by id (self-healing)")
+        .allowUnknownOption()
+        .allowExcessArguments(true)
+        .exitOverride()
+        .action(async (runId) => {
+        const runner = safeCreateRunner(makeRunner);
+        try {
+            const run = await runner.getRunStatus(runId);
+            agentSuccess({ ...run });
+        }
+        catch (err) {
+            agentError(err.message, "RunnerError", {
+                error_domain: AGENT_ERROR_DOMAINS.RUNNER,
+            });
+        }
+    });
+    // ── run result ──
+    // Single-shot result lookup: 202 → still running, 200 → result, 409 → failed.
+    runGroup
+        .command("result")
+        .argument("<pipeline_run_id>", "Run id")
+        .description("Fetch a run's result by id, once (does not wait)")
         .allowUnknownOption()
         .allowExcessArguments(true)
         .exitOverride()
-        .action(async (reference, options) => {
-        if (options.format) {
-            agentError("`--format` is no longer supported on `mthds-agent check-model`. The agent CLI always emits JSON via the agentSuccess envelope.", "ArgumentError", { error_domain: AGENT_ERROR_DOMAINS.ARGUMENT });
+        .action(async (runId) => {
+        const runner = safeCreateRunner(makeRunner);
+        let state;
+        try {
+            state = await runner.getRunResult(runId);
+        }
+        catch (err) {
+            agentError(err.message, "RunnerError", {
+                error_domain: AGENT_ERROR_DOMAINS.RUNNER,
+            });
             return;
         }
+        switch (state.state) {
+            case "running":
+                agentSuccess({
+                    state: "running",
+                    pipeline_run_id: state.pipeline_run_id,
+                    retry_after_seconds: state.retry_after_seconds,
+                    hint: `Run is still in progress. Poll with: mthds-agent run poll ${runId}`,
+                });
+                break;
+            case "completed":
+                agentSuccess({
+                    state: "completed",
+                    pipeline_run_id: state.pipeline_run_id,
+                    main_stuff: state.result.main_stuff ?? null,
+                    graph_spec: state.result.graph_spec ?? null,
+                });
+                break;
+            case "failed":
+                agentError(state.message, "RunFailedError", {
+                    error_domain: AGENT_ERROR_DOMAINS.PIPELINE,
+                    retryable: false,
+                });
+                break;
+        }
+    });
+    // ── run poll ──
+    // Block until the run reaches a terminal state. Ctrl-C (or any SIGINT) stops
+    // waiting WITHOUT cancelling the run — the run keeps executing server-side
+    // and can be resumed by id.
+    runGroup
+        .command("poll")
+        .argument("<pipeline_run_id>", "Run id")
+        .option("--interval <seconds>", "Base poll interval in seconds (default 2)")
+        .option("--timeout <seconds>", "Max seconds to wait before giving up (default 1200)")
+        .description("Poll a run to completion, then return its result")
+        .allowUnknownOption()
+        .allowExcessArguments(true)
+        .exitOverride()
+        .action(async (runId, options) => {
+        const runner = safeCreateRunner(makeRunner);
+        const intervalMs = parsePositiveSeconds(options.interval, "--interval");
+        const timeoutMs = parsePositiveSeconds(options.timeout, "--timeout");
+        const controller = new AbortController();
+        const onSigint = () => controller.abort();
+        process.once("SIGINT", onSigint);
+        try {
+            const result = await runner.waitForResult(runId, {
+                intervalMs,
+                timeoutMs,
+                signal: controller.signal,
+            });
+            agentSuccess({
+                state: "completed",
+                pipeline_run_id: runId,
+                main_stuff: result.main_stuff ?? null,
+                graph_spec: result.graph_spec ?? null,
+            });
+        }
+        catch (err) {
+            if (controller.signal.aborted) {
+                // Walk-away: not an error. Report the run as still resumable by id.
+                agentSuccess({
+                    state: "running",
+                    pipeline_run_id: runId,
+                    resumable: true,
+                    hint: `Stopped waiting; the run continues. Resume with: mthds-agent run poll ${runId}`,
+                });
+            }
+            else if (err instanceof RunFailedError) {
+                agentError(err.message, "RunFailedError", {
+                    error_domain: AGENT_ERROR_DOMAINS.PIPELINE,
+                    retryable: false,
+                });
+            }
+            else if (err instanceof RunTimeoutError) {
+                agentError(err.message, "RunTimeoutError", {
+                    error_domain: AGENT_ERROR_DOMAINS.RUNNER,
+                    retryable: true,
+                    hint: `The run is still executing. Resume with: mthds-agent run poll ${runId}`,
+                });
+            }
+            else {
+                agentError(err.message, "RunnerError", {
+                    error_domain: AGENT_ERROR_DOMAINS.RUNNER,
+                });
+            }
+        }
+        finally {
+            process.removeListener("SIGINT", onSigint);
+        }
+    });
+    // ── models ──
+    program
+        .command("models")
+        .description("List the model deck (models, aliases, waterfalls)")
+        .option("--type <type>", "Filter by model category (llm, extract, img_gen, search)")
+        .allowUnknownOption()
+        .allowExcessArguments(true)
+        .exitOverride()
+        .action(async (options) => {
         const runner = safeCreateRunner(makeRunner);
+        const category = parseModelCategory(options.type);
         try {
-            const result = await runner.checkModel({ reference, type: options.type });
+            const result = await runner.models(category);
             agentSuccess({ ...result });
         }
         catch (err) {
@@ -396,6 +491,21 @@ export function registerApiRunnerCommands(program, makeRunner) {
             });
         }
     });
+    // ── check-model ──
+    // check-model is a LOCAL CLI capability (pipelex runner) only — the MTHDS
+    // API has no check-model route. Registered here so the API runner errors
+    // cleanly instead of failing with an opaque 404.
+    program
+        .command("check-model")
+        .description("Validate a model reference with fuzzy suggestions (pipelex runner only)")
+        .argument("<reference>", "Model reference to check")
+        .option("--type <type>", "Model category (llm, extract, img_gen, search)")
+        .allowUnknownOption()
+        .allowExcessArguments(true)
+        .exitOverride()
+        .action(async () => {
+        agentError("check-model is not available on the API runner — the MTHDS API has no check-model route. It is a local capability of the pipelex runner: re-run with --runner pipelex. To list what the API can route to, use: mthds-agent models", "UnsupportedError", { error_domain: AGENT_ERROR_DOMAINS.RUNNER });
+    });
 }
 // ── Helpers ──
 function safeCreateRunner(makeRunner) {
@@ -485,13 +595,120 @@ function resolvePipeCode(mthdsContent, pipeCodeOption) {
     });
     throw new Error("unreachable");
 }
-function handleValidateResult(result) {
-    if (result.success) {
-        agentSuccess({ ...result });
+function resolveRunInputs(options) {
+    if (options.inputsJson)
+        return parseJsonOrError(options.inputsJson, "--inputs-json");
+    if (options.inputs) {
+        const raw = readFileOrError(options.inputs);
+        return parseJsonOrError(raw, "inputs file");
+    }
+    return undefined;
+}
+function resolveStartOptions(target, options) {
+    const outputs = {
+        output_name: options.outputName,
+        output_multiplicity: parseMultiplicity(options.outputMultiplicity),
+        dynamic_output_concept_ref: options.dynamicOutput,
+    };
+    const extra = parseExtraOption(options.extra);
+    // No inline bundle → an extension-only start: the run is identified entirely by
+    // server-specific args passed through `--extra` (e.g. a stored-method run). The
+    // runner is the source of truth for what `extra` it accepts — the SDK and CLI
+    // never name those args.
+    if (!target && !options.content) {
+        return { pipe_code: options.pipe, inputs: resolveRunInputs(options), ...outputs, extra };
+    }
+    // resolveContentForRun may set options.inputs (directory auto-discovery), so
+    // resolve the bundle before reading inputs.
+    const mthdsContent = resolveContentForRun(target, options);
+    const pipeCode = resolvePipeCode(mthdsContent, options.pipe);
+    return { pipe_code: pipeCode, mthds_contents: [mthdsContent], inputs: resolveRunInputs(options), ...outputs, extra };
+}
+/** Parse `--extra <json>` into the generic extension passthrough — a JSON object of server-defined args. */
+function parseExtraOption(raw) {
+    if (!raw)
+        return undefined;
+    const parsed = parseJsonOrError(raw, "--extra");
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        agentError("--extra must be a JSON object of server-specific args.", "ArgumentError", {
+            error_domain: AGENT_ERROR_DOMAINS.ARGUMENT,
+        });
+        throw new Error("unreachable");
+    }
+    return parsed;
+}
+/** Parse `--output-multiplicity`: "false"/"true" → boolean, a positive integer → count. */
+function parseMultiplicity(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (raw === "true")
+        return true;
+    if (raw === "false")
+        return false;
+    const count = Number(raw);
+    if (Number.isInteger(count) && count > 0)
+        return count;
+    agentError("--output-multiplicity must be 'true', 'false', or a positive integer.", "ArgumentError", { error_domain: AGENT_ERROR_DOMAINS.ARGUMENT });
+    throw new Error("unreachable");
+}
+function parsePositiveSeconds(raw, label) {
+    if (raw === undefined)
+        return undefined;
+    const seconds = Number(raw);
+    if (!Number.isFinite(seconds) || seconds <= 0) {
+        agentError(`${label} must be a positive number of seconds.`, "ArgumentError", {
+            error_domain: AGENT_ERROR_DOMAINS.ARGUMENT,
+        });
+        throw new Error("unreachable");
+    }
+    return seconds * 1000;
+}
+/** Parse the `--type` model-category filter, erroring on unknown values. */
+function parseModelCategory(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (MODEL_CATEGORIES.includes(raw)) {
+        return raw;
+    }
+    agentError(`--type must be one of: ${MODEL_CATEGORIES.join(", ")}.`, "ArgumentError", { error_domain: AGENT_ERROR_DOMAINS.ARGUMENT });
+    throw new Error("unreachable");
+}
+/**
+ * Run the protocol validate (`POST /v1/validate`) and emit the agent envelope.
+ * `/validate` is a diagnostic endpoint: a valid bundle returns the structural
+ * artifacts (`is_valid: true`); an invalid bundle is a produced verdict (a 200
+ * `is_valid: false` body), surfaced as a structured ValidateBundleError envelope —
+ * not a thrown error. A non-2xx (a no-verdict condition) still throws.
+ */
+export async function runProtocolValidate(runner, mthdsContents, allowSignatures, mthdsSources) {
+    try {
+        // `mthds_sources` is a Pipelex-API extension (not the pure protocol), so it
+        // rides only the concrete client — reach it via `isApiRunner`. The server
+        // threads each source onto `validation_errors[].source`, so agent consumers
+        // can resolve the owning file from the structured envelope.
+        const report = mthdsSources !== undefined && isApiRunner(runner)
+            ? await runner.validate(mthdsContents, allowSignatures, mthdsSources)
+            : await runner.validate(mthdsContents, allowSignatures);
+        if (report.is_valid === false) {
+            agentError(report.message, "ValidateBundleError", {
+                error_domain: AGENT_ERROR_DOMAINS.VALIDATION,
+                is_valid: false,
+                validation_errors: report.validation_errors,
+            });
+        }
+        agentSuccess({ success: true, ...report });
     }
-    else {
-        agentError(result.message, "ValidationError", {
-            error_domain: AGENT_ERROR_DOMAINS.VALIDATION,
+    catch (err) {
+        // Only no-verdict conditions reach here now: a request-shape 422 (malformed
+        // body / mthds_sources mismatch), auth, or a server fault.
+        if (err instanceof ApiResponseError && err.status === 422) {
+            agentError(err.serverMessage ?? err.message, "ValidationError", {
+                error_domain: AGENT_ERROR_DOMAINS.VALIDATION,
+            });
+            return;
+        }
+        agentError(err.message, "RunnerError", {
+            error_domain: AGENT_ERROR_DOMAINS.RUNNER,
         });
     }
 }