antpath 0.10.14 → 0.11.0

package/dist/_shared/runtime-manifest.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Runtime manifest: the per-run, per-provider description of where
+ * antpath places things inside the agent container, plus the merged
+ * env-var bag delivered via `RUNTIME.env` / `RUNTIME.json`.
+ *
+ * Two consumers, one source of truth:
+ *
+ *   1. The dashboard BFF computes a manifest at submitRun-response
+ *      time (from the validated submission + the chosen provider)
+ *      and echoes it on the wire as `Run.runtimeManifest`. The SDK
+ *      exposes it as `RunRef.runtimeManifest` so caller code (broll's
+ *      dispatcher, anyone rendering catalog markdown pre-submission)
+ *      can substitute path strings without guessing.
+ *
+ *   2. The worker uses the same builder + the same `renderRuntimeEnv`
+ *      / `renderRuntimeJson` helpers to materialise the two RUNTIME
+ *      files mounted into every session, so the in-container view
+ *      and the SDK-side view are byte-for-byte the same set of
+ *      keys/values.
+ *
+ * Manifest values are derived: the BFF and worker both compute them
+ * from the same input (provider + customer envVars). Nothing is
+ * persisted separately — the source of truth for the customer half
+ * remains `submission.environment.envVars` on the run row; the antpath
+ * half is constant for a given provider+SDK-version pair.
+ */
+/**
+ * Set of providers whose runtime contract antpath models. Today only
+ * `"anthropic"` ships; the field is on the manifest so forward-compat
+ * consumers can branch on it without us having to silently change
+ * what `runtimeManifest` means when we add a second provider.
+ */
+export type RuntimeProvider = "anthropic";
+/**
+ * The in-container paths the agent and skill code reference at
+ * runtime. All fields are absolute, all reflect Anthropic Managed
+ * Agents' session-mount rebase rule (every `mount_path` lands under
+ * `/mnt/session/uploads/` regardless of the leading slash) — see
+ * `references/architecture-decisions.md`.
+ *
+ * `skillsRoot` is the location of Skills API-registered bundles, which
+ * the runtime auto-discovers under `/workspace/skills/<name>/` —
+ * empirically a separate root from the session-resource mounts, NOT
+ * under `/mnt/session/uploads/`.
+ */
+export interface RuntimeManifest {
+    readonly provider: RuntimeProvider;
+    /** Where Skills-API-registered bundles auto-discover (Anthropic). */
+    readonly skillsRoot: string;
+    /** Parent dir of File mounts: `<filesRoot>/<f_id>/<rel-path>`. */
+    readonly filesRoot: string;
+    /** Parent dir of non-SKILL.md asset mounts: `<assetsRoot>/<skl_id>/<rel-path>`. */
+    readonly assetsRoot: string;
+    /** Absolute path the agent writes output files into for capture. */
+    readonly outputsRoot: string;
+    /** Absolute path of the in-container antpath CLI (invoke via `node`). */
+    readonly antpathCli: string;
+    /** Absolute path of the per-run proxy-endpoints manifest. */
+    readonly indexJson: string;
+    /** Absolute path of the always-mounted antpath runtime contract README. */
+    readonly readme: string;
+    /** Absolute path of the machine-readable manifest mirror. */
+    readonly runtimeJson: string;
+    /** Absolute path of the POSIX-shell-sourceable runtime env file. */
+    readonly runtimeEnv: string;
+    /**
+     * Merged env-var bag: antpath-set runtime keys (with reserved
+     * `ANTPATH_` prefix) plus customer-supplied `environment.envVars`.
+     * Both `RUNTIME.env` and `RUNTIME.json` are rendered from this
+     * exact map; `__KEY__` substitution in agent-facing markdown
+     * resolves against this exact map.
+     */
+    readonly envVars: Readonly<Record<string, string>>;
+}
+/**
+ * Anthropic Managed Agents container paths. Kept here so the BFF and
+ * the worker render identical values; the worker's `proxy-bootstrap`
+ * constants are validated against these by a regression test
+ * (`packages/shared/test/runtime-manifest.test.ts`).
+ *
+ * Path facts (each verified at least once by a live session, locked
+ * in `references/architecture-decisions.md`):
+ *   - Session resources mount under `/mnt/session/uploads/` (rebase).
+ *   - Skills API places bundles under `/workspace/skills/<name>/`
+ *     — a SEPARATE root from session-resource mounts.
+ *   - Files API mounts file_ids at the requested mount_path, also
+ *     rebased — antpath threads them under `<filesRoot>/<f_id>/<rel>`.
+ *   - Only `/mnt/session/outputs` files are auto-registered with the
+ *     Files API for terminal-time capture.
+ */
+declare const ANTHROPIC_PATHS: Readonly<{
+    readonly skillsRoot: "/workspace/skills";
+    readonly filesRoot: "/mnt/session/uploads/antpath/files";
+    readonly assetsRoot: "/mnt/session/uploads/antpath/assets";
+    readonly outputsRoot: "/mnt/session/outputs";
+    readonly antpathCli: "/mnt/session/uploads/antpath/antpath";
+    readonly indexJson: "/mnt/session/uploads/antpath/index.json";
+    readonly readme: "/mnt/session/uploads/antpath/SKILLS.md";
+    readonly runtimeJson: "/mnt/session/uploads/antpath/RUNTIME.json";
+    readonly runtimeEnv: "/mnt/session/uploads/antpath/RUNTIME.env";
+}>;
+/**
+ * Container paths exposed for a given provider. Today only
+ * `"anthropic"` is recognised; calling with anything else throws so
+ * forward-compat surfaces the missing provider entry instead of
+ * silently emitting Anthropic paths.
+ */
+export declare function runtimePathsFor(provider: RuntimeProvider): typeof ANTHROPIC_PATHS;
+export interface BuildRuntimeManifestInput {
+    readonly provider: RuntimeProvider;
+    /**
+     * Customer-supplied `environment.envVars` from the validated
+     * submission. Keys with the reserved `ANTPATH_` prefix are
+     * filtered out defensively — the strict submission parser already
+     * rejects them, but defence-in-depth means a malformed snapshot
+     * (or a future bypass) can't poison the manifest.
+     */
+    readonly customerEnvVars?: Readonly<Record<string, string>> | undefined;
+}
+/**
+ * Build the runtime manifest for a single submission. Pure function:
+ * same input → same output → safe to call from the BFF response path
+ * and from the worker bootstrap path with identical results.
+ */
+export declare function buildRuntimeManifest(input: BuildRuntimeManifestInput): RuntimeManifest;
+/**
+ * Render the RUNTIME.env file mounted into every session. POSIX-shell
+ * sourceable (`source /mnt/session/uploads/antpath/RUNTIME.env`).
+ * Values are double-quoted with `"`, `\`, `$`, and backtick escaped
+ * so any UTF-8 string survives a `source` invocation. Lines are LF
+ * (Unix), no trailing CR — the container is Linux regardless of
+ * caller platform.
+ *
+ * Output order: antpath keys first (in stable order from
+ * `buildRuntimeManifest`), then customer keys in insertion order.
+ * The same ordering is preserved in RUNTIME.json.
+ */
+export declare function renderRuntimeEnv(manifest: RuntimeManifest): string;
+/**
+ * Render the RUNTIME.json file mounted into every session. Stable
+ * canonical JSON (2-space indent, key order matches the manifest)
+ * so the file is reviewable as a tracked artifact when captured into
+ * a run's output archive.
+ */
+export declare function renderRuntimeJson(manifest: RuntimeManifest): string;
+/**
+ * Pattern matched by `substituteRuntimePlaceholders`. A placeholder is
+ * `__KEY__` where `KEY` matches POSIX shell key rules (uppercase, digits,
+ * underscores, starting with a letter or underscore). The literal form
+ * is deliberately conservative — no `{{ }}` templating, no expressions,
+ * no escape syntax. If a customer needs the literal string `__KEY__` in
+ * agent-facing markdown, they avoid the matching key in their envVars
+ * map.
+ */
+export declare const RUNTIME_PLACEHOLDER_PATTERN: RegExp;
+/**
+ * Substitute `__KEY__` placeholders in agent-facing markdown against
+ * the manifest's envVars map. Fail-fast on unknown keys: the function
+ * throws `RuntimePlaceholderError` naming the offending key + filePath
+ * so the worker can surface a lint-style failure at materialization
+ * time, before the agent ever sees the file.
+ *
+ * Pure function; safe to call from the BFF, the worker materializer,
+ * or tests. The two callers in production are:
+ *
+ *   - Worker materialization: rewrite SKILL.md / AGENTS.md / .md
+ *     entries inside skill, file, and AgentsMd bundles before they
+ *     mount or upload.
+ *   - SDK / customer code: customers can apply the same helper in
+ *     their dispatcher when they want to render templates locally
+ *     before uploading. The merged envVars map is `runtimeManifest.envVars`.
+ *
+ * @param content   The text to rewrite.
+ * @param envVars   Map of allowed placeholder keys → values. Typically
+ *                  `runtimeManifest.envVars` from `buildRuntimeManifest`.
+ * @param filePath  Optional path of the source file, included in the
+ *                  error message when a placeholder is unresolved.
+ *                  Helps the customer locate the offending line.
+ */
+export declare function substituteRuntimePlaceholders(content: string, envVars: Readonly<Record<string, string>>, filePath?: string): string;
+/**
+ * Thrown by `substituteRuntimePlaceholders` when a `__KEY__` token in
+ * agent-facing markdown does not resolve against the merged env-var
+ * map. Surfaced at run materialization, before the run reaches the
+ * agent — the customer fixes the typo at the SDK call site, no
+ * tokens are spent on a misrouted run.
+ */
+export declare class RuntimePlaceholderError extends Error {
+    constructor(message: string);
+}
+export {};

package/dist/_shared/runtime-manifest.js

@@ -0,0 +1,221 @@
+/**
+ * Runtime manifest: the per-run, per-provider description of where
+ * antpath places things inside the agent container, plus the merged
+ * env-var bag delivered via `RUNTIME.env` / `RUNTIME.json`.
+ *
+ * Two consumers, one source of truth:
+ *
+ *   1. The dashboard BFF computes a manifest at submitRun-response
+ *      time (from the validated submission + the chosen provider)
+ *      and echoes it on the wire as `Run.runtimeManifest`. The SDK
+ *      exposes it as `RunRef.runtimeManifest` so caller code (broll's
+ *      dispatcher, anyone rendering catalog markdown pre-submission)
+ *      can substitute path strings without guessing.
+ *
+ *   2. The worker uses the same builder + the same `renderRuntimeEnv`
+ *      / `renderRuntimeJson` helpers to materialise the two RUNTIME
+ *      files mounted into every session, so the in-container view
+ *      and the SDK-side view are byte-for-byte the same set of
+ *      keys/values.
+ *
+ * Manifest values are derived: the BFF and worker both compute them
+ * from the same input (provider + customer envVars). Nothing is
+ * persisted separately — the source of truth for the customer half
+ * remains `submission.environment.envVars` on the run row; the antpath
+ * half is constant for a given provider+SDK-version pair.
+ */
+/**
+ * Anthropic Managed Agents container paths. Kept here so the BFF and
+ * the worker render identical values; the worker's `proxy-bootstrap`
+ * constants are validated against these by a regression test
+ * (`packages/shared/test/runtime-manifest.test.ts`).
+ *
+ * Path facts (each verified at least once by a live session, locked
+ * in `references/architecture-decisions.md`):
+ *   - Session resources mount under `/mnt/session/uploads/` (rebase).
+ *   - Skills API places bundles under `/workspace/skills/<name>/`
+ *     — a SEPARATE root from session-resource mounts.
+ *   - Files API mounts file_ids at the requested mount_path, also
+ *     rebased — antpath threads them under `<filesRoot>/<f_id>/<rel>`.
+ *   - Only `/mnt/session/outputs` files are auto-registered with the
+ *     Files API for terminal-time capture.
+ */
+const ANTHROPIC_PATHS = Object.freeze({
+    skillsRoot: "/workspace/skills",
+    filesRoot: "/mnt/session/uploads/antpath/files",
+    assetsRoot: "/mnt/session/uploads/antpath/assets",
+    outputsRoot: "/mnt/session/outputs",
+    antpathCli: "/mnt/session/uploads/antpath/antpath",
+    indexJson: "/mnt/session/uploads/antpath/index.json",
+    readme: "/mnt/session/uploads/antpath/SKILLS.md",
+    runtimeJson: "/mnt/session/uploads/antpath/RUNTIME.json",
+    runtimeEnv: "/mnt/session/uploads/antpath/RUNTIME.env"
+});
+/**
+ * Container paths exposed for a given provider. Today only
+ * `"anthropic"` is recognised; calling with anything else throws so
+ * forward-compat surfaces the missing provider entry instead of
+ * silently emitting Anthropic paths.
+ */
+export function runtimePathsFor(provider) {
+    if (provider === "anthropic") {
+        return ANTHROPIC_PATHS;
+    }
+    throw new Error(`Unknown runtime provider: ${provider}`);
+}
+/**
+ * Reserved env-var prefix for antpath-set runtime keys. Mirrors the
+ * constant in `submission.ts`; duplicated here so this module is
+ * self-contained and can be tree-shaken by SDK consumers that don't
+ * need the submission parser.
+ */
+const ANTPATH_PREFIX = "ANTPATH_";
+/**
+ * Build the runtime manifest for a single submission. Pure function:
+ * same input → same output → safe to call from the BFF response path
+ * and from the worker bootstrap path with identical results.
+ */
+export function buildRuntimeManifest(input) {
+    const paths = runtimePathsFor(input.provider);
+    const antpathEnvVars = {
+        ANTPATH_PROVIDER: input.provider,
+        ANTPATH_CLI: paths.antpathCli,
+        ANTPATH_OUTPUTS: paths.outputsRoot,
+        ANTPATH_SKILLS_ROOT: paths.skillsRoot,
+        ANTPATH_FILES_ROOT: paths.filesRoot,
+        ANTPATH_ASSETS_ROOT: paths.assetsRoot,
+        ANTPATH_INDEX_JSON: paths.indexJson,
+        ANTPATH_README: paths.readme,
+        ANTPATH_RUNTIME_JSON: paths.runtimeJson,
+        ANTPATH_RUNTIME_ENV: paths.runtimeEnv
+    };
+    const customerEnvVars = {};
+    for (const [key, value] of Object.entries(input.customerEnvVars ?? {})) {
+        if (key.startsWith(ANTPATH_PREFIX)) {
+            // Defensive filter; the strict parser rejects this at submit
+            // time. If a stored snapshot somehow carries a reserved key
+            // we drop it rather than letting it shadow our value.
+            continue;
+        }
+        customerEnvVars[key] = value;
+    }
+    const envVars = Object.freeze({ ...antpathEnvVars, ...customerEnvVars });
+    return Object.freeze({
+        provider: input.provider,
+        skillsRoot: paths.skillsRoot,
+        filesRoot: paths.filesRoot,
+        assetsRoot: paths.assetsRoot,
+        outputsRoot: paths.outputsRoot,
+        antpathCli: paths.antpathCli,
+        indexJson: paths.indexJson,
+        readme: paths.readme,
+        runtimeJson: paths.runtimeJson,
+        runtimeEnv: paths.runtimeEnv,
+        envVars
+    });
+}
+/**
+ * Render the RUNTIME.env file mounted into every session. POSIX-shell
+ * sourceable (`source /mnt/session/uploads/antpath/RUNTIME.env`).
+ * Values are double-quoted with `"`, `\`, `$`, and backtick escaped
+ * so any UTF-8 string survives a `source` invocation. Lines are LF
+ * (Unix), no trailing CR — the container is Linux regardless of
+ * caller platform.
+ *
+ * Output order: antpath keys first (in stable order from
+ * `buildRuntimeManifest`), then customer keys in insertion order.
+ * The same ordering is preserved in RUNTIME.json.
+ */
+export function renderRuntimeEnv(manifest) {
+    const lines = [
+        "# antpath runtime environment (mounted at " + manifest.runtimeEnv + ")",
+        "# Generated per-run by the antpath worker; do not edit.",
+        "# Source from bash: `source " + manifest.runtimeEnv + "`",
+        ""
+    ];
+    for (const [key, value] of Object.entries(manifest.envVars)) {
+        lines.push(`${key}="${escapeForDoubleQuotedShell(value)}"`);
+    }
+    return lines.join("\n") + "\n";
+}
+/**
+ * Render the RUNTIME.json file mounted into every session. Stable
+ * canonical JSON (2-space indent, key order matches the manifest)
+ * so the file is reviewable as a tracked artifact when captured into
+ * a run's output archive.
+ */
+export function renderRuntimeJson(manifest) {
+    // Manifest is already frozen with the desired key order — JSON.stringify
+    // preserves insertion order, so the file mirrors the wire shape.
+    return JSON.stringify(manifest, null, 2) + "\n";
+}
+/**
+ * Escape a string for embedding inside a POSIX double-quoted shell
+ * literal. Only `\`, `"`, `$`, and backtick need escaping inside
+ * `"..."`; everything else (including single quotes, spaces, UTF-8)
+ * passes through verbatim. Newlines stay literal so multi-line
+ * values render across multiple lines in the file but are read back
+ * as a single value by `source`.
+ */
+function escapeForDoubleQuotedShell(value) {
+    return value.replace(/[\\"$`]/g, (ch) => `\\${ch}`);
+}
+/**
+ * Pattern matched by `substituteRuntimePlaceholders`. A placeholder is
+ * `__KEY__` where `KEY` matches POSIX shell key rules (uppercase, digits,
+ * underscores, starting with a letter or underscore). The literal form
+ * is deliberately conservative — no `{{ }}` templating, no expressions,
+ * no escape syntax. If a customer needs the literal string `__KEY__` in
+ * agent-facing markdown, they avoid the matching key in their envVars
+ * map.
+ */
+export const RUNTIME_PLACEHOLDER_PATTERN = /__([A-Z_][A-Z0-9_]*)__/g;
+/**
+ * Substitute `__KEY__` placeholders in agent-facing markdown against
+ * the manifest's envVars map. Fail-fast on unknown keys: the function
+ * throws `RuntimePlaceholderError` naming the offending key + filePath
+ * so the worker can surface a lint-style failure at materialization
+ * time, before the agent ever sees the file.
+ *
+ * Pure function; safe to call from the BFF, the worker materializer,
+ * or tests. The two callers in production are:
+ *
+ *   - Worker materialization: rewrite SKILL.md / AGENTS.md / .md
+ *     entries inside skill, file, and AgentsMd bundles before they
+ *     mount or upload.
+ *   - SDK / customer code: customers can apply the same helper in
+ *     their dispatcher when they want to render templates locally
+ *     before uploading. The merged envVars map is `runtimeManifest.envVars`.
+ *
+ * @param content   The text to rewrite.
+ * @param envVars   Map of allowed placeholder keys → values. Typically
+ *                  `runtimeManifest.envVars` from `buildRuntimeManifest`.
+ * @param filePath  Optional path of the source file, included in the
+ *                  error message when a placeholder is unresolved.
+ *                  Helps the customer locate the offending line.
+ */
+export function substituteRuntimePlaceholders(content, envVars, filePath) {
+    return content.replace(RUNTIME_PLACEHOLDER_PATTERN, (match, key) => {
+        if (key in envVars) {
+            return envVars[key];
+        }
+        const where = filePath ? ` (in ${filePath})` : "";
+        throw new RuntimePlaceholderError(`unresolved runtime placeholder ${match}${where}: key ${JSON.stringify(key)} ` +
+            `is not in environment.envVars or the antpath runtime keys. ` +
+            `Available keys: ${Object.keys(envVars).sort().join(", ")}`);
+    });
+}
+/**
+ * Thrown by `substituteRuntimePlaceholders` when a `__KEY__` token in
+ * agent-facing markdown does not resolve against the merged env-var
+ * map. Surfaced at run materialization, before the run reaches the
+ * agent — the customer fixes the typo at the SDK call site, no
+ * tokens are spent on a misrouted run.
+ */
+export class RuntimePlaceholderError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RuntimePlaceholderError";
+    }
+}
+//# sourceMappingURL=runtime-manifest.js.map

package/dist/_shared/runtime-types.d.ts

@@ -1,8 +1,13 @@
-import type { JsonValue, PlatformInlineSecrets, PlatformProxyEndpoint } from "./submission.js";
 /**
  * Loose record describing a run as the dashboard BFF returns it. Concrete
  * dashboard-managed fields appear in the index signature; the SDK and CLI
  * may surface them without strong typing per-field.
+ *
+ * `runtimeManifest` is derived from the validated submission + the chosen
+ * provider on every read — see `runtime-manifest.ts`. It is `undefined`
+ * on responses from BFFs that predate Phase 2 of the runtime-environment
+ * rollout; SDK consumers MUST treat it as best-effort and not panic on
+ * its absence.
  */
 export interface Run {
     readonly id: string;
@@ -15,6 +20,7 @@ export interface Run {
     readonly terminalAt?: string | null;
     readonly errorMessage?: string | null;
     readonly usage?: UsageSummary;
+    readonly runtimeManifest?: import("./runtime-manifest.js").RuntimeManifest;
     readonly [key: string]: unknown;
 }
 export interface UsageSummary {
@@ -175,18 +181,3 @@ export interface FileRecord {
     readonly deletedAt?: string | null;
     readonly [key: string]: unknown;
 }
-/**
- * Full submission as the SDK and CLI assemble it before posting. The
- * `template` is the SDK-level ResolvedTemplate (or a JSON-encoded one);
- * the SDK/CLI converts to PlatformTemplateSubmission via the mapper.
- */
-export interface RunSubmissionInput {
-    readonly workspaceId: string;
-    readonly idempotencyKey?: string;
-    readonly variables?: Record<string, JsonValue>;
-    readonly secrets: PlatformInlineSecrets;
-    readonly proxyEndpoints?: readonly PlatformProxyEndpoint[];
-    readonly cleanup?: {
-        readonly session?: "retain" | "delete";
-    };
-}

package/dist/_shared/sse.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Tiny SSE (text/event-stream) parser used by the SDK / CLI to consume
+ * the dashboard's `/api/runs/:id/events/stream` endpoint without
+ * pulling in a DOM `EventSource` dependency. Node's `fetch` returns a
+ * web `ReadableStream<Uint8Array>` body; this parser turns that into
+ * an async iterable of `SseFrame`s.
+ *
+ * The wire grammar follows the WHATWG HTML spec § Server-sent events:
+ *
+ *   - Lines are separated by `\n`, `\r`, or `\r\n`.
+ *   - A `:` prefix marks a comment — ignored.
+ *   - `field: value` (or `field:value`, with no space) — leading space
+ *     after the colon is stripped.
+ *   - Recognised fields: `event`, `data`, `id`, `retry`.
+ *   - Multiple `data:` lines join with `\n`.
+ *   - A blank line dispatches the current frame and resets the buffer.
+ *   - `event:` defaults to `"message"` when absent.
+ *
+ * The parser is deliberately a free function so it can be unit-tested
+ * against synthesized chunk boundaries (one byte at a time, mid-frame,
+ * across UTF-8 multi-byte sequences) without spinning up a real
+ * connection.
+ */
+export interface SseFrame {
+    readonly id?: string;
+    readonly event: string;
+    readonly data: string;
+    readonly retry?: number;
+}
+/**
+ * Stateful parser: feed in chunks (in any size), pull out completed
+ * frames. Designed for `for await` consumption — see `iterateSse`.
+ */
+export declare class SseParser {
+    #private;
+    /**
+     * Push a chunk of raw bytes through the parser. Returns any frames
+     * that completed during this chunk. Chunks may contain zero, one,
+     * or many frame boundaries — the parser handles partial trailing
+     * data internally.
+     */
+    pushBytes(chunk: Uint8Array): readonly SseFrame[];
+    /**
+     * Push a text chunk directly. Used by the parser tests so they can
+     * exercise byte-boundary edge cases without manufacturing a
+     * `TextDecoder` round-trip.
+     */
+    pushText(text: string): readonly SseFrame[];
+    /**
+     * Indicate end-of-stream. Returns any final frame that the dispatcher
+     * was holding when the stream closed mid-frame (no trailing blank
+     * line). The dispatcher pattern is: blank line dispatches; if the
+     * remote closes after a partial frame, that frame is dropped per the
+     * spec.
+     */
+    flush(): void;
+    /**
+     * Current "last event id" — the cursor the SSE spec instructs the
+     * client to replay on automatic reconnection. Callers use this to
+     * resume after a disconnect.
+     */
+    get lastEventId(): string | undefined;
+}
+/**
+ * Convert a web `ReadableStream<Uint8Array>` (the body of a fetch
+ * Response) into an async iterable of SSE frames. The stream is
+ * consumed exactly once; the caller is responsible for cancelling
+ * the underlying reader on abort.
+ *
+ * The reader is raced against the abort signal so a long-blocked
+ * server (no chunks for many seconds) still releases the loop
+ * promptly when the consumer aborts.
+ */
+export declare function iterateSse(body: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncIterable<SseFrame>;

package/dist/_shared/stable.d.ts

@@ -1,22 +1,27 @@
 /**
- * Canonical hosted antpath URL. Used as the default `baseUrl` for the
- * SDK `AntpathClient` and the host-side CLI `--dashboard-url` flag.
+ * Canonical hosted antpath API plane URL. Used as the default `baseUrl`
+ * for the SDK `AntpathClient` and the host-side CLI `--antpath-url`
+ * flag.
  *
- * Pinned to the `www.` host on purpose: the apex `antpath.ai` issues a
- * 307 redirect to `https://www.antpath.ai`, and HTTP clients strip the
- * `Authorization` header on cross-origin redirects (WHATWG Fetch §5.5).
- * Hitting the apex would make every authenticated call from a default
- * client land as a 401 `authentication required`. Always go direct.
+ * Pinned to `api.antpath.ai` on purpose: the dashboard at
+ * `www.antpath.ai` is the human UX surface, while `api.antpath.ai`
+ * owns the runtime/API plane (run submission, provider proxy, MCP
+ * proxy, runner callbacks). Both the apex `antpath.ai` and `www.` host
+ * may issue redirects, and HTTP clients strip the `Authorization`
+ * header on cross-origin redirects (WHATWG Fetch §5.5) — hitting them
+ * would make authenticated calls land as 401s. Always go direct to
+ * the API plane.
  *
  * A single canonical default is not a "footnote mode" — it is the
  * canonical product. Self-hosted deployments override via the
- * explicit `baseUrl` / `--dashboard-url` parameter. The value lives in
+ * explicit `baseUrl` / `--antpath-url` parameter. The value lives in
  * source (no env-var override) so the agent reading the SDK call site
  * can see exactly where the call goes.
  *
  * See `references/development-principles.md` (Agent-first surface
- * design, Concrete rule 3).
+ * design, Concrete rule 3) and
+ * `references/deepseek-runtime-mcp-plan.md` (API plane).
  */
-export declare const ANTPATH_DEFAULT_BASE_URL = "https://www.antpath.ai";
+export declare const ANTPATH_DEFAULT_BASE_URL = "https://api.antpath.ai";
 export declare function stableStringify(value: unknown): string;
 export declare function sha256(value: unknown): string;

package/dist/_shared/stable.js

@@ -1,24 +1,29 @@
 import { createHash } from "node:crypto";
 /**
- * Canonical hosted antpath URL. Used as the default `baseUrl` for the
- * SDK `AntpathClient` and the host-side CLI `--dashboard-url` flag.
+ * Canonical hosted antpath API plane URL. Used as the default `baseUrl`
+ * for the SDK `AntpathClient` and the host-side CLI `--antpath-url`
+ * flag.
  *
- * Pinned to the `www.` host on purpose: the apex `antpath.ai` issues a
- * 307 redirect to `https://www.antpath.ai`, and HTTP clients strip the
- * `Authorization` header on cross-origin redirects (WHATWG Fetch §5.5).
- * Hitting the apex would make every authenticated call from a default
- * client land as a 401 `authentication required`. Always go direct.
+ * Pinned to `api.antpath.ai` on purpose: the dashboard at
+ * `www.antpath.ai` is the human UX surface, while `api.antpath.ai`
+ * owns the runtime/API plane (run submission, provider proxy, MCP
+ * proxy, runner callbacks). Both the apex `antpath.ai` and `www.` host
+ * may issue redirects, and HTTP clients strip the `Authorization`
+ * header on cross-origin redirects (WHATWG Fetch §5.5) — hitting them
+ * would make authenticated calls land as 401s. Always go direct to
+ * the API plane.
  *
  * A single canonical default is not a "footnote mode" — it is the
  * canonical product. Self-hosted deployments override via the
- * explicit `baseUrl` / `--dashboard-url` parameter. The value lives in
+ * explicit `baseUrl` / `--antpath-url` parameter. The value lives in
  * source (no env-var override) so the agent reading the SDK call site
  * can see exactly where the call goes.
  *
  * See `references/development-principles.md` (Agent-first surface
- * design, Concrete rule 3).
+ * design, Concrete rule 3) and
+ * `references/deepseek-runtime-mcp-plan.md` (API plane).
  */
-export const ANTPATH_DEFAULT_BASE_URL = "https://www.antpath.ai";
+export const ANTPATH_DEFAULT_BASE_URL = "https://api.antpath.ai";
 export function stableStringify(value) {
     return JSON.stringify(sortValue(value));
 }