antpath 0.10.15 → 0.11.4

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/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));
 }