@aexhq/sdk 0.24.0 → 0.25.1

package/README.md

@@ -2,163 +2,74 @@
 title: aex
 ---
 
-# aex
+# @aexhq/sdk
 
-aex is a TypeScript-first SDK + CLI for running autonomous agent sessions across providers through the managed aex service. Everything an agent or human needs is reachable through **one** import and **one** binary.
+aex is an agent execution platform for launching autonomous agents from a simple TypeScript SDK and CLI.
 
-```ts
-import {
-  AgentExecutor,        // the only client class — submits durable runs to aex
-  RunModels,            // closed public model id constants
-  Skill,                // local, URL, and catalog skill bundles normalized to assets
-  McpServer,            // MCP server declarations (headers split into secrets server-side)
-  ProxyEndpoint,        // per-run managed HTTP proxy endpoint
-  AgentsMd,             // AGENTS.md / CLAUDE.md uploads
-  File,                 // arbitrary workspace files mounted into the session
-  validateProxyAuth     // helper that fails fast on policy/auth mismatch
-} from "@aexhq/sdk";
-```
-
-```bash
-aex run     --config ./run.json --api-token ant_… \
-                --anthropic-api-key sk-ant-… --follow
-aex status  <run-id>             --api-token …
-aex wait    <run-id> [--timeout 8m] [--interval 2s] --api-token …
-aex events  <run-id> [--follow] [--timeout 8m]  --api-token …
-aex outputs <run-id>             --api-token …
-aex download <run-id> [--only outputs|events|metadata] [--out path] --api-token …
-aex cancel  <run-id>             --api-token …
-aex delete  <run-id>             --api-token …
-aex whoami                       --api-token …
-aex skills  <upload|list|get|delete> [flags] --api-token …
-aex delete-asset <assetId|hash>  --api-token …
-```
+The package ships:
 
-The SDK class and the CLI are backed by the same public `@aexhq/contracts` operations module — any read or write you can do through one, you can do through the other, against the same durable run records. The same npm package also ships the in-container `aex` CLI as its `bin` entry; managed runs mount that CLI inside the runner so skills can call `aex proxy …` against the per-run manifest. See [product capabilities and boundaries](docs/product-boundaries.md).
+- `AgentExecutor` for submit, run, wait, stream, inspect, download, cancel, and delete.
+- Typed run primitives: `Models`, `Providers`, `RuntimeSizes`, `Skill`, `AgentsMd`, `File`, `McpServer`, `ProxyEndpoint`, and `Secret`.
+- A bundled `aex` CLI with the same run, status, events, outputs, download, cancel, delete, whoami, and skills operations.
 
-The aex URL defaults to `https://api.aex.dev`. Set `--aex-url` on the CLI or `baseUrl` on `AgentExecutor` for local, staging, or hosted aex API planes. This is not a supported self-host deployment claim. The workspace is derived server-side from your API token (1:1 binding), so there is no `--workspace` flag and no `workspaceId` option.
+## Install
 
-## Product boundaries
-
-- Multi-provider via the managed runtime. The published surface is the same
-  regardless of provider:
-  - omit `runtime` or pass `runtime: "managed"`; every provider uses the
-    managed runtime and BYOK provider-proxy.
-  - `provider: "anthropic" | "deepseek" | "openai" | "gemini" | "mistral"`.
-  - See [provider/runtime capabilities](docs/provider-runtime-capabilities.md)
-    for the generated matrix.
-- BYO provider key + MCP credentials + skill references — passed inline on every submission and held in run-scoped custody, with cleanup/revocation attempted at terminal. Cross-provider keys are rejected loudly at submission time.
-- Workspace is the tenant boundary. Workspace identity is derived server-side from the API token (1:1 binding); the SDK / CLI never name it.
-- No SDK-side storage of provider keys, MCP credentials, or output file contents.
-- Cleanup runs by default for tracked runtime resources.
-- Product boundaries are explicit: see [product capabilities and boundaries](docs/product-boundaries.md) for what aex owns, inherits, and does not support.
+```bash
+npm install @aexhq/sdk
+```
 
-## Quickstart (SDK)
+## First Run
 
 ```ts
-import { AgentExecutor, RunModels } from "@aexhq/sdk";
+import { AgentExecutor, Models, Providers } from "@aexhq/sdk";
 
 const aex = new AgentExecutor({
-  apiToken: process.env.AEX_API_TOKEN!,
-  // baseUrl defaults to https://api.aex.dev - set it for local or staging planes.
+  apiToken: process.env.AEX_API_TOKEN!
 });
 
 const runId = await aex.submit({
-  model: RunModels.CLAUDE_HAIKU_4_5,
-  system: "You are a concise automation agent.",
-  prompt: "Write a short answer about agent-first SDK design.",
+  provider: Providers.ANTHROPIC,
+  model: Models.CLAUDE_HAIKU_4_5,
+  prompt: "Write the report and save outputs.",
   secrets: { apiKey: process.env.ANTHROPIC_API_KEY! }
 });
 
-const run = await aex.wait(runId);
-console.log(run.status);
-
-for (const output of await aex.outputs(runId)) {
-  console.log(output.id, output.filename);
-}
-
-const report = await aex.downloadOutput(runId, { path: "report.txt", match: "suffix" });
-console.log(new TextDecoder().decode(report));
-
-await aex.downloadOutputs(runId, { to: "./outputs.zip" });
-```
-
-Reusable, credential-free configs can be ordinary functions:
-
-```ts
-function summarise(topic: string) {
-  return {
-    model: RunModels.CLAUDE_HAIKU_4_5,
-    system: "You are a concise automation agent.",
-    prompt: `Write a short answer about ${topic}.`
-  };
+for await (const event of aex.stream(runId)) {
+  console.log(event.type);
 }
 
-const runId = await aex.submit({
-  ...summarise("agent-first SDK design"),
-  secrets: { apiKey: process.env.ANTHROPIC_API_KEY! }
-});
-```
-
-Stream events live with `aex.stream(runId)`:
+const run = await aex.wait(runId);
+console.log(run.status);
 
-```ts
-for await (const event of aex.stream(runId)) {
-  if (event.type === "TEXT_MESSAGE_CONTENT") {
-    // typed event helpers live under `aex`'s event guard exports.
-  }
-}
+await aex.download(runId, { to: "./run.zip" });
 ```
 
-The same flow from the CLI (two equivalent forms):
+The same request can run from the CLI:
 
 ```bash
 aex run \
   --api-token "$AEX_API_TOKEN" \
   --anthropic-api-key "$ANTHROPIC_API_KEY" \
   --model claude-haiku-4-5 \
-  --system "You are a concise automation agent." \
-  --prompt "Write a short answer about agent-first SDK design." \
-  --follow
-
-aex run \
-  --api-token "$AEX_API_TOKEN" \
-  --anthropic-api-key "$ANTHROPIC_API_KEY" \
-  --config ./run.json \
+  --prompt "Write the report and save outputs." \
   --follow
 ```
 
-`--config` accepts a plain run-config JSON file for a single run request: `{ model, system?, prompt, skills?, mcpServers?, environment?, runtimeSize?, timeout?, postHook?, proxyEndpoints?, metadata? }`. There is no saved-definition product or interpolation DSL — build the JSON at the call site. SDK code should use `RunModels`; config JSON is validated against the same `RUN_MODELS` allowlist.
+## Feature Areas
 
-Runtime controls: omit `builtins` to use the default `["developer"]` toolkit, pass `builtins: []` to disable builtins for a pure-MCP run, use `outputMode: "stream"` for per-token assistant text, prefer `RuntimeSizes` for `runtimeSize`, and use `postHook` to run a verifier command after the agent exits successfully.
+- **Agent runtime:** managed autonomous runs with filesystem read/edit, grep/glob/head/tail, open web fetch/search defaults, optional notebook tools, and post-hook repair.
+- **Durable infrastructure:** run records, status, wait/cancel/delete, idempotency, typed events, output capture, downloads, timeouts, and runtime sizes.
+- **Agent composition:** skills, files, AGENTS.md, remote MCP servers, proxy endpoints, environment variables, packages, and networking controls.
+- **Subagents:** typed parent/child lineage for async child runs, output handoff, and bounded agent delegation.
+- **Models and providers:** Anthropic, DeepSeek, OpenAI, Gemini, Mistral, OpenRouter, Doubao, and Doubao China behind one submission shape.
+- **Typed control surface:** strongly typed SDK inputs, CLI parity, BYOK secrets, scoped proxy auth, redaction, and output modes.
 
-## Test commands
-
-```text
-pnpm test                # unit (deterministic; uses fakes/snapshots)
-pnpm test:user:offline   # clean install of packed/published SDK, no live API
-pnpm test:user           # live hosted API user tests
-pnpm test:user:heavy     # explicit heavy live canary
-```
-
-User tests auto-pack the current SDK when no artifact env is set. CI can pin a
-specific artifact with exactly one of `AEX_USER_TEST_TARBALL` or
-`AEX_USER_TEST_VERSION`; live runs also need `AEX_API_URL`,
-`AEX_API_TOKEN`, and `DEEPSEEK_API_KEY`.
-
-## Guides
+## Docs
 
 - [Quickstart](docs/quickstart.md)
-- [Run config](docs/run-config.md)
-- [Run record](docs/run-record.md)
-- [Product capabilities and boundaries](docs/product-boundaries.md)
+- [Run configuration](docs/run-config.md)
+- [Agent tools](docs/concepts/agent-tools.md)
+- [Composition](docs/concepts/composition.md)
+- [Secrets](docs/secrets.md)
+- [Limits](docs/limits.md)
 - [Provider/runtime capabilities](docs/provider-runtime-capabilities.md)
-- [Credentials](docs/credentials.md)
-- [MCP](docs/mcp.md)
-- [Skills](docs/skills.md)
-- [Outputs](docs/outputs.md)
-- [Events](docs/events.md)
-- [Cleanup](docs/cleanup.md)
-- [Testing](docs/testing.md)
-- [Release](docs/release.md)
-

package/dist/_contracts/index.d.ts

@@ -18,7 +18,6 @@ export * from "./run-cost.js";
 export * from "./run-custody.js";
 export * from "./run-retention.js";
 export * from "./side-effect-audit.js";
-export * from "./managed-key.js";
 export * from "./stable.js";
 export * from "./sdk-secrets.js";
 export * from "./sdk-errors.js";

package/dist/_contracts/index.js

@@ -18,7 +18,6 @@ export * from "./run-cost.js";
 export * from "./run-custody.js";
 export * from "./run-retention.js";
 export * from "./side-effect-audit.js";
-export * from "./managed-key.js";
 export * from "./stable.js";
 export * from "./sdk-secrets.js";
 export * from "./sdk-errors.js";

package/dist/_contracts/models.js

@@ -37,8 +37,7 @@ export const MODEL_PROVIDER_IDS = {
     // China Volcengine Ark gateway (`doubao-cn`). Ark accepts the API-format
     // model NAME directly in the chat-completions `model` field (no `ep-…`
     // inference-endpoint id). The native strings are the same Ark catalog ids on
-    // both gateways; BytePlus per-account availability is confirmed at live-verify
-    // (both providers ship `live-unverified` until then — provider-support.ts).
+    // both gateways.
     //   pro   — Doubao Seed 1.8 (flagship, 256K context).
     //   flash — Doubao Seed 1.6 Flash (fast/cheap, 256K context).
     "doubao-seed-pro": { doubao: "doubao-seed-1-8-251228", "doubao-cn": "doubao-seed-1-8-251228" },

package/dist/_contracts/operations.d.ts

@@ -1,6 +1,6 @@
 import type { HttpClient } from "./http.js";
 import type { RunUnit } from "./run-unit.js";
-import type { AgentsMdRecord, FileRecord, Output, OutputFileDownload, OutputFileSelector, Run, RunEvent, SecretRecord, SecretReveal, SignedOutputLink, Skill, WhoAmI } from "./runtime-types.js";
+import type { AgentsMdRecord, FileRecord, Output, OutputLink, OutputLinkOptions, OutputFileDownload, OutputFileSelector, OutputFileType, OutputQuery, Run, RunEvent, SecretRecord, SecretReveal, Skill, WhoAmI } from "./runtime-types.js";
 import type { PlatformRunSubmissionInput } from "./submission.js";
 /**
  * The single source of truth for SDK<->BFF transport. The SDK class
@@ -47,8 +47,13 @@ export interface CoordinatorTicket {
  * coordinator is configured for the deployment (HTTP 503).
  */
 export declare function getCoordinatorTicket(http: HttpClient, runId: string): Promise<CoordinatorTicket>;
-export declare function listOutputs(http: HttpClient, runId: string): Promise<readonly Output[]>;
-export declare function createOutputLink(http: HttpClient, runId: string, outputId: string): Promise<SignedOutputLink>;
+export declare function listOutputs(http: HttpClient, runId: string, query?: OutputQuery): Promise<readonly Output[]>;
+export declare function findOutputs(http: HttpClient, runId: string, query: OutputQuery): Promise<readonly Output[]>;
+export declare function findOutput(http: HttpClient, runId: string, query: OutputQuery): Promise<Output | null>;
+export type OutputLinkSelector = string | OutputFileSelector | OutputQuery;
+export declare function outputLink(http: HttpClient, runId: string, selectorOrQuery: OutputLinkSelector, options?: OutputLinkOptions): Promise<OutputLink>;
+export declare function createOutputLink(http: HttpClient, runId: string, selectorOrQuery: OutputLinkSelector, options?: OutputLinkOptions): Promise<OutputLink>;
+export declare function eventArchiveLink(http: HttpClient, runId: string, options?: OutputLinkOptions): Promise<OutputLink>;
 export declare function resolveOutputFileSelector(outputs: readonly Output[], selector: OutputFileSelector, runId?: string): Output;
 export declare function downloadOutput(http: HttpClient, runId: string, selector: OutputFileSelector): Promise<OutputFileDownload>;
 export declare function cancelRun(http: HttpClient, runId: string): Promise<void>;
@@ -61,6 +66,9 @@ export declare function deleteRun(http: HttpClient, runId: string): Promise<void
  */
 export declare function deleteWorkspaceAsset(http: HttpClient, hash: string): Promise<void>;
 export declare function whoami(http: HttpClient): Promise<WhoAmI>;
+export declare function filterOutputs(outputs: readonly Output[], query: OutputQuery): readonly Output[];
+export declare function classifyOutput(output: Pick<Output, "filename" | "contentType">): OutputFileType;
+export declare function normalizeOutputLinkExpiresIn(input?: OutputLinkOptions["expiresIn"]): number;
 /**
  * Download EVERYTHING public about a run as one zip, organised into the three
  * namespace folders:
@@ -215,8 +223,8 @@ export declare function createSecret(http: HttpClient, args: {
 export declare function listSecrets(http: HttpClient): Promise<readonly SecretRecord[]>;
 /** Metadata for one workspace secret by name. Never returns the value. */
 export declare function getSecret(http: HttpClient, name: string): Promise<SecretRecord>;
-/** Audited value read — the only path that returns a workspace secret value. */
-export declare function revealSecret(http: HttpClient, name: string): Promise<SecretReveal>;
+/** Audited value read — the preferred path that returns a workspace secret value. */
+export declare function getSecretValue(http: HttpClient, name: string): Promise<SecretReveal>;
 /** Replace the value of an existing workspace secret; bumps its version. */
 export declare function rotateSecret(http: HttpClient, args: {
     readonly name: string;

package/dist/_contracts/operations.js

@@ -64,12 +64,50 @@ export async function listRunEvents(http, runId) {
 export async function getCoordinatorTicket(http, runId) {
     return http.request(`/api/runs/${encodeURIComponent(runId)}/events/ticket`, { method: "POST" });
 }
-export async function listOutputs(http, runId) {
+export async function listOutputs(http, runId, query) {
     const result = await http.request(`/api/runs/${encodeURIComponent(runId)}/outputs`);
-    return result.outputs;
+    return query === undefined ? result.outputs : filterOutputs(result.outputs, query);
+}
+export async function findOutputs(http, runId, query) {
+    return listOutputs(http, runId, query);
+}
+export async function findOutput(http, runId, query) {
+    const matches = await findOutputs(http, runId, query);
+    if (matches.length === 0)
+        return null;
+    if (matches.length === 1)
+        return matches[0];
+    throw new RunStateError("findOutput: output query matched multiple files", {
+        runId,
+        matches: matches.map((output) => output.filename ?? output.id)
+    });
 }
-export async function createOutputLink(http, runId, outputId) {
-    return http.request(`/api/runs/${encodeURIComponent(runId)}/outputs/${encodeURIComponent(outputId)}/link`, { method: "POST" });
+export async function outputLink(http, runId, selectorOrQuery, options) {
+    const output = await resolveOutputLinkTarget(http, runId, selectorOrQuery);
+    const expiresInSeconds = normalizeOutputLinkExpiresIn(options?.expiresIn);
+    const result = await http.request(`/api/runs/${encodeURIComponent(runId)}/outputs/${encodeURIComponent(output.id)}/link`, {
+        method: "POST",
+        body: JSON.stringify({ expiresInSeconds })
+    });
+    return {
+        ...result,
+        expiresInSeconds: result.expiresInSeconds ?? expiresInSeconds,
+        output: result.output ?? output
+    };
+}
+export async function createOutputLink(http, runId, selectorOrQuery, options) {
+    return outputLink(http, runId, selectorOrQuery, options);
+}
+export async function eventArchiveLink(http, runId, options) {
+    const expiresInSeconds = normalizeOutputLinkExpiresIn(options?.expiresIn);
+    const result = await http.request(`/api/runs/${encodeURIComponent(runId)}/events/link`, {
+        method: "POST",
+        body: JSON.stringify({ expiresInSeconds })
+    });
+    return {
+        ...result,
+        expiresInSeconds: result.expiresInSeconds ?? expiresInSeconds
+    };
 }
 export function resolveOutputFileSelector(outputs, selector, runId) {
     if (isPathSelector(selector)) {
@@ -173,6 +211,178 @@ function isPathSelector(selector) {
 function normalizeOutputLookupPath(path) {
     return path.replace(/\\/g, "/").replace(/^\/+/, "");
 }
+export function filterOutputs(outputs, query) {
+    return outputs.filter((output) => outputMatchesQuery(output, query));
+}
+export function classifyOutput(output) {
+    const contentType = normalizeContentType(output.contentType);
+    if (contentType) {
+        if (contentType === "application/json" || contentType.endsWith("+json") || contentType.includes("json")) {
+            return "json";
+        }
+        if (contentType.startsWith("text/"))
+            return "text";
+        if (contentType.startsWith("image/"))
+            return "image";
+        if (contentType.startsWith("audio/"))
+            return "audio";
+        if (contentType.startsWith("video/"))
+            return "video";
+        if (contentType === "application/pdf")
+            return "pdf";
+        if (contentType === "application/zip" ||
+            contentType === "application/gzip" ||
+            contentType === "application/x-gzip" ||
+            contentType === "application/x-tar" ||
+            contentType === "application/x-7z-compressed" ||
+            contentType === "application/vnd.rar" ||
+            contentType === "application/zstd") {
+            return "archive";
+        }
+        if (contentType === "application/octet-stream")
+            return "binary";
+        return "unknown";
+    }
+    const extension = extensionOf(output.filename);
+    if (!extension)
+        return "unknown";
+    if (["json", "jsonl", "ndjson"].includes(extension))
+        return "json";
+    if (["txt", "log", "md", "markdown", "csv", "tsv", "xml", "html", "htm", "yaml", "yml"].includes(extension)) {
+        return "text";
+    }
+    if (["png", "jpg", "jpeg", "gif", "webp", "avif", "bmp", "tif", "tiff", "svg"].includes(extension)) {
+        return "image";
+    }
+    if (["mp3", "wav", "flac", "m4a", "aac", "ogg", "oga", "opus"].includes(extension))
+        return "audio";
+    if (["mp4", "mov", "m4v", "webm", "mkv", "avi"].includes(extension))
+        return "video";
+    if (extension === "pdf")
+        return "pdf";
+    if (["zip", "tar", "tgz", "gz", "bz2", "xz", "7z", "rar", "zst"].includes(extension))
+        return "archive";
+    if (["bin", "exe", "dll", "so", "dylib", "dmg", "iso"].includes(extension))
+        return "binary";
+    return "unknown";
+}
+export function normalizeOutputLinkExpiresIn(input = "1h") {
+    if (typeof input === "number") {
+        if (!Number.isFinite(input) || input <= 0) {
+            throw new RunStateError("outputLink: expiresIn must be a positive number of seconds", {
+                expiresIn: input
+            });
+        }
+        return Math.floor(input);
+    }
+    if (input === "15m")
+        return 15 * 60;
+    if (input === "1h")
+        return 60 * 60;
+    if (input === "1d")
+        return 24 * 60 * 60;
+    throw new RunStateError("outputLink: expiresIn must be seconds, \"15m\", \"1h\", or \"1d\"", {
+        expiresIn: input
+    });
+}
+async function resolveOutputLinkTarget(http, runId, selectorOrQuery) {
+    if (typeof selectorOrQuery === "string") {
+        if (selectorOrQuery.length === 0) {
+            throw new RunStateError("outputLink: selector must include an output id or query", { runId });
+        }
+        return { id: selectorOrQuery };
+    }
+    if (hasOutputId(selectorOrQuery)) {
+        if (selectorOrQuery.id.length === 0) {
+            throw new RunStateError("outputLink: selector must include an output id or query", { runId });
+        }
+        return selectorOrQuery;
+    }
+    if (isPathSelector(selectorOrQuery) && selectorOrQuery.match === "suffix") {
+        return resolveOutputFileSelector(await listOutputs(http, runId), selectorOrQuery, runId);
+    }
+    const match = await findOutput(http, runId, selectorOrQuery);
+    if (match)
+        return match;
+    throw new RunStateError("outputLink: output query matched no files", { runId });
+}
+function outputMatchesQuery(output, query) {
+    const normalizedPath = typeof output.filename === "string" ? normalizeOutputQueryPath(output.filename) : "";
+    if (query.path !== undefined && normalizedPath !== normalizeOutputQueryPath(query.path)) {
+        return false;
+    }
+    if (query.filename !== undefined) {
+        const basename = basenameOf(normalizedPath);
+        if (typeof query.filename === "string") {
+            if (basename !== query.filename)
+                return false;
+        }
+        else {
+            query.filename.lastIndex = 0;
+            if (!query.filename.test(basename))
+                return false;
+        }
+    }
+    if (query.dir !== undefined && !directoryMatches(normalizedPath, query.dir, query.recursive ?? true)) {
+        return false;
+    }
+    if (query.extension !== undefined && extensionOf(normalizedPath) !== normalizeExtension(query.extension)) {
+        return false;
+    }
+    if (query.contentType !== undefined && !contentTypeMatches(output.contentType, query.contentType)) {
+        return false;
+    }
+    if (query.type !== undefined && classifyOutput(output) !== query.type) {
+        return false;
+    }
+    return true;
+}
+function hasOutputId(value) {
+    return Boolean(value && typeof value === "object" && "id" in value && typeof value.id === "string");
+}
+function normalizeOutputQueryPath(path) {
+    let normalized = path.replace(/\\/g, "/").replace(/^\/+/, "");
+    while (normalized === "outputs" || normalized.startsWith("outputs/")) {
+        normalized = normalized === "outputs" ? "" : normalized.slice("outputs/".length);
+    }
+    return normalized.replace(/\/+$/, "");
+}
+function basenameOf(path) {
+    return path.split("/").filter(Boolean).pop() ?? "";
+}
+function directoryMatches(path, dir, recursive) {
+    const normalizedDir = normalizeOutputQueryPath(dir);
+    if (normalizedDir.length === 0)
+        return true;
+    const prefix = `${normalizedDir}/`;
+    if (!path.startsWith(prefix))
+        return false;
+    const remainder = path.slice(prefix.length);
+    return remainder.length > 0 && (recursive || !remainder.includes("/"));
+}
+function normalizeExtension(extension) {
+    return extension.replace(/^\.+/, "").toLowerCase();
+}
+function extensionOf(path) {
+    if (!path)
+        return "";
+    const basename = basenameOf(normalizeOutputQueryPath(path));
+    const index = basename.lastIndexOf(".");
+    return index > 0 && index < basename.length - 1 ? basename.slice(index + 1).toLowerCase() : "";
+}
+function normalizeContentType(contentType) {
+    return (contentType ?? "").split(";")[0].trim().toLowerCase();
+}
+function contentTypeMatches(actual, expected) {
+    const normalizedActual = normalizeContentType(actual);
+    const normalizedExpected = normalizeContentType(expected);
+    if (!normalizedActual || !normalizedExpected)
+        return false;
+    if (normalizedExpected.endsWith("/*")) {
+        return normalizedActual.startsWith(normalizedExpected.slice(0, -1));
+    }
+    return normalizedActual === normalizedExpected;
+}
 /**
  * Download EVERYTHING public about a run as one zip, organised into the three
  * namespace folders:
@@ -468,7 +678,7 @@ export async function findSkillByName(http, name) {
     return skills.find((skill) => skill.name === name) ?? null;
 }
 // ===========================================================================
-// AgentsMd (workspace_files kind='agentsmd') operations
+// AgentsMd upload helpers. Launch submissions use content-addressed asset refs.
 // ===========================================================================
 /**
  * Upload a workspace AgentsMd file as a markdown string. The BFF
@@ -505,7 +715,7 @@ function unwrapAgentsMd(result) {
     return result;
 }
 // ===========================================================================
-// File (workspace_files kind='file') operations
+// File upload helpers. Launch submissions use content-addressed asset refs.
 // ===========================================================================
 /**
  * Upload a workspace File as a zip bundle. The BFF canonicalises the
@@ -547,7 +757,7 @@ function unwrapFile(result) {
 // Value-bearing requests (create/rotate) carry the value in the JSON BODY,
 // never the URL/query, so it never lands in logs or the request line. Reads
 // split by sensitivity: `getSecret`/`listSecrets` return METADATA only;
-// `revealSecret` is the audited value read (POST so it's a logged action).
+// `getSecretValue` is the audited value read (POST so it's a logged action).
 // ===========================================================================
 /** Create a named workspace secret. The value travels in the body. */
 export async function createSecret(http, args) {
@@ -569,9 +779,9 @@ export async function getSecret(http, name) {
     const result = await http.request(`/api/secrets/${encodeURIComponent(name)}`);
     return unwrapSecret(result);
 }
-/** Audited value read — the only path that returns a workspace secret value. */
-export async function revealSecret(http, name) {
-    return http.request(`/api/secrets/${encodeURIComponent(name)}/reveal`, {
+/** Audited value read — the preferred path that returns a workspace secret value. */
+export async function getSecretValue(http, name) {
+    return http.request(`/api/secrets/${encodeURIComponent(name)}/get_value`, {
         method: "POST"
     });
 }