@aexhq/sdk 0.13.6

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

@@ -0,0 +1,212 @@
+/**
+ * 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;
+    readonly status: string;
+    readonly workspaceId?: string;
+    readonly createdAt?: string;
+    readonly updatedAt?: string;
+    readonly terminalAt?: string | null;
+    readonly errorMessage?: string | null;
+    readonly usage?: UsageSummary;
+    readonly costTelemetry?: import("./run-cost.js").RunCostTelemetry;
+    readonly runtimeManifest?: import("./runtime-manifest.js").RuntimeManifest;
+    readonly [key: string]: unknown;
+}
+export interface UsageSummary {
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+    readonly cacheReadInputTokens?: number;
+    readonly cacheCreationInputTokens?: number;
+    readonly totalTokens?: number;
+}
+/**
+ * A run event as recorded by the dashboard. Includes the `type` field
+ * that the `is*Event` type guards narrow on plus any provider payload.
+ *
+ * The unified-stream discriminators (`channel`, `source`, `sourceSeq`,
+ * `emittedAt`, `receivedAt`, `level`) carry through from the coordinator
+ * envelope (see `event-envelope.ts` —
+ * {@link import("./event-envelope.js").AexEvent}) so SDK/CLI consumers can
+ * split/filter the one stream by channel or source. All are OPTIONAL: archived
+ * events from before the unification (and any producer that omits an ordering
+ * attribute) lack them, an absent `channel` means `"event"` (see `channelOf`),
+ * and `level` is present only on `log`-channel records.
+ */
+export interface RunEvent {
+    readonly id: string;
+    readonly type: string;
+    readonly runId?: string;
+    readonly recordedAt?: string;
+    /** Which sub-stream this record rides — `"event"` (typed) or `"log"`. Absent ⇒ `"event"`. */
+    readonly channel?: import("./event-envelope.js").AexEventChannel;
+    /** Coarse origin classifier (agent/worker/runtime/mcp/aex/workflow/machine). */
+    readonly source?: import("./event-envelope.js").AexEventSource;
+    /** Per-source monotonic counter assigned at the source (carried, not re-ordered). */
+    readonly sourceSeq?: number;
+    /** Source wall-clock ms at emit (carried for a best-effort client time view). */
+    readonly emittedAt?: number;
+    /** The DO's authoritative receive-time (wall-clock ms) stamped at ingest, companion to `seq`. */
+    readonly receivedAt?: number;
+    /** Log severity, first-class on a `channel: "log"` record ("info" | "warn" | "error"). */
+    readonly level?: import("./event-envelope.js").AexLogLevel;
+    readonly [key: string]: unknown;
+}
+/**
+ * Provider-emitted event payload. Provider-specific fields are passed through
+ * structurally so historical events and managed-runner events can be displayed
+ * and downloaded without each client needing provider-specific schemas.
+ */
+export interface ProviderEvent {
+    readonly type: string;
+    readonly id?: string | undefined;
+    readonly created_at?: string | undefined;
+    readonly [key: string]: unknown;
+}
+/**
+ * One captured output file as the dashboard reports it. Use
+ * `createOutputLink` to get a short-lived signed URL for download.
+ */
+export interface Output {
+    readonly id: string;
+    readonly filename?: string;
+    readonly sizeBytes?: number;
+    readonly contentType?: string;
+    readonly createdAt?: string;
+    readonly [key: string]: unknown;
+}
+export type OutputFilePathMatch = "exact" | "suffix";
+export interface OutputFilePathSelector {
+    readonly path: string;
+    readonly match?: OutputFilePathMatch;
+}
+export interface OutputFileIdSelector {
+    readonly id: string;
+}
+export type OutputFileSelector = Output | OutputFileIdSelector | OutputFilePathSelector;
+export interface OutputFileDownload {
+    readonly output: Output;
+    readonly bytes: Uint8Array;
+}
+export interface SignedOutputLink {
+    readonly url: string;
+    readonly expiresAt?: string;
+    readonly [key: string]: unknown;
+}
+export interface WhoAmI {
+    readonly principalType: "api_token" | "user";
+    readonly workspaceId?: string;
+    readonly tokenId?: string;
+    readonly tokenName?: string | null;
+    readonly scopes?: readonly string[];
+    /**
+     * Workspace-level caps the BFF will enforce on subsequent calls.
+     * Surfaced so consumers (e.g. broll's app-side admission gate) can
+     * decide whether to keep their own gate or rely on platform headers.
+     * All fields optional — older BFFs may omit. Numbers are concrete
+     * snapshots at the time of the `whoami` call.
+     */
+    readonly caps?: {
+        /** Token-bucket cap on POST /api/runs per minute, per workspace. */
+        readonly runSubmitPerMinute?: number;
+        /** Hard cap on concurrent non-terminal runs the workspace may hold. */
+        readonly maxConcurrentRuns?: number;
+        /** Storage cap (bytes) on captured output objects, workspace-wide. */
+        readonly storageCapBytes?: number;
+        /** Current captured-output usage in bytes. */
+        readonly storageUsedBytes?: number;
+        /**
+         * Wall-clock ceiling on a single run before forced termination.
+         * `null` means no aex-imposed cap, but this is **not unlimited
+         * overall**: the managed runner, infrastructure, or upstream provider may
+         * still impose a ceiling, and a run that exceeds it terminates regardless.
+         */
+        readonly maxRunDurationMs?: number | null;
+    };
+    readonly [key: string]: unknown;
+}
+/**
+ * Workspace skill bundle as the dashboard BFF returns it. Mirrors a row
+ * of `skill_bundles` joined with its computed manifest. `state` is the
+ * upload lifecycle (`pending` -> `ready`); only `ready` rows are
+ * referenceable from a run. `deletedAt` is the soft-delete tombstone
+ * (`null` for live bundles).
+ *
+ * See the public architecture notes and server-side persistence schema for
+ * the authoritative shape.
+ */
+export interface Skill {
+    readonly id: string;
+    readonly workspaceId?: string;
+    readonly name: string;
+    readonly state: "pending" | "ready";
+    readonly hash?: string | null;
+    readonly sizeBytes?: number | null;
+    readonly fileCount?: number | null;
+    readonly manifest?: ReadonlyArray<{
+        readonly path: string;
+        readonly size: number;
+        readonly mode: number;
+    }>;
+    readonly createdAt?: string;
+    readonly updatedAt?: string;
+    readonly finalizedAt?: string | null;
+    readonly deletedAt?: string | null;
+    readonly [key: string]: unknown;
+}
+/**
+ * Wire-level record for a workspace AgentsMd file as returned by the BFF.
+ * Mirrors `PublicWorkspaceFile` from the dashboard service layer.
+ */
+export interface AgentsMdRecord {
+    readonly id: string;
+    readonly kind?: "agentsmd";
+    readonly name: string;
+    readonly state: "pending" | "ready";
+    readonly hash?: string | null;
+    readonly sizeBytes?: number | null;
+    readonly fileCount?: number | null;
+    readonly manifest?: ReadonlyArray<{
+        readonly path: string;
+        readonly size: number;
+        readonly mode: number;
+    }>;
+    readonly createdAt?: string;
+    readonly updatedAt?: string;
+    readonly finalizedAt?: string | null;
+    readonly deletedAt?: string | null;
+    readonly [key: string]: unknown;
+}
+/**
+ * Wire-level record for a workspace File as returned by the BFF.
+ * Mirrors `PublicWorkspaceFile` from the dashboard service layer
+ * with kind='file' and `f_*` ids.
+ */
+export interface FileRecord {
+    readonly id: string;
+    readonly kind?: "file";
+    readonly name: string;
+    readonly state: "pending" | "ready";
+    readonly hash?: string | null;
+    readonly sizeBytes?: number | null;
+    readonly fileCount?: number | null;
+    readonly manifest?: ReadonlyArray<{
+        readonly path: string;
+        readonly size: number;
+        readonly mode: number;
+    }>;
+    readonly createdAt?: string;
+    readonly updatedAt?: string;
+    readonly finalizedAt?: string | null;
+    readonly deletedAt?: string | null;
+    readonly [key: string]: unknown;
+}

package/dist/_contracts/runtime-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=runtime-types.js.map

package/dist/_contracts/sdk-errors.d.ts

@@ -0,0 +1,34 @@
+export type AexErrorCode = "RUN_CONFIG_INVALID" | "CREDENTIAL_INVALID" | "PROVIDER_ERROR" | "RUN_STATE_ERROR" | "CLEANUP_ERROR" | "RUNTIME_UNSUPPORTED" | "API_ERROR";
+export declare class AexError extends Error {
+    readonly code: AexErrorCode;
+    readonly details?: unknown;
+    constructor(code: AexErrorCode, message: string, details?: unknown);
+}
+export declare class RunConfigValidationError extends AexError {
+    constructor(message: string, details?: unknown);
+}
+export declare class CredentialValidationError extends AexError {
+    constructor(message: string, details?: unknown);
+}
+export declare class ProviderError extends AexError {
+    readonly status: number | undefined;
+    constructor(message: string, options?: {
+        status?: number;
+        details?: unknown;
+    });
+}
+export declare class RunStateError extends AexError {
+    constructor(message: string, details?: unknown);
+}
+export declare class CleanupError extends AexError {
+    constructor(message: string, details?: unknown);
+}
+/**
+ * Thrown by SDK and CLI operations when the dashboard BFF returns a non-2xx
+ * response. Carries the HTTP status and parsed body for the caller to inspect.
+ */
+export declare class AexApiError extends AexError {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, message: string, body: unknown);
+}

package/dist/_contracts/sdk-errors.js

@@ -0,0 +1,52 @@
+import { redactSecrets } from "./sdk-secrets.js";
+export class AexError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(redactSecrets(message));
+        this.name = this.constructor.name;
+        this.code = code;
+        this.details = details === undefined ? undefined : redactSecrets(details);
+    }
+}
+export class RunConfigValidationError extends AexError {
+    constructor(message, details) {
+        super("RUN_CONFIG_INVALID", message, details);
+    }
+}
+export class CredentialValidationError extends AexError {
+    constructor(message, details) {
+        super("CREDENTIAL_INVALID", message, details);
+    }
+}
+export class ProviderError extends AexError {
+    status;
+    constructor(message, options = {}) {
+        super("PROVIDER_ERROR", message, options.details);
+        this.status = options.status;
+    }
+}
+export class RunStateError extends AexError {
+    constructor(message, details) {
+        super("RUN_STATE_ERROR", message, details);
+    }
+}
+export class CleanupError extends AexError {
+    constructor(message, details) {
+        super("CLEANUP_ERROR", message, details);
+    }
+}
+/**
+ * Thrown by SDK and CLI operations when the dashboard BFF returns a non-2xx
+ * response. Carries the HTTP status and parsed body for the caller to inspect.
+ */
+export class AexApiError extends AexError {
+    status;
+    body;
+    constructor(status, message, body) {
+        super("API_ERROR", message, body);
+        this.status = status;
+        this.body = redactSecrets(body);
+    }
+}
+//# sourceMappingURL=sdk-errors.js.map

package/dist/_contracts/sdk-secrets.d.ts

@@ -0,0 +1,31 @@
+import { Transform } from "node:stream";
+export declare class SecretString {
+    #private;
+    constructor(value: string, label?: string);
+    unwrap(): string;
+    toString(): string;
+    toJSON(): string;
+}
+export declare function redactSecrets<T>(value: T): T;
+/**
+ * Redact every secret-shaped run in `input`.
+ *
+ * `known` is an OPTIONAL belt-and-suspenders set of literal values to also mask
+ * (e.g. creds the caller happens to have loaded). Correctness does NOT depend on
+ * it — every shape above is caught with or without seeding — but masking known
+ * values first removes any residual substring of a value the shapes split.
+ */
+export declare function redactString(input: string, known?: Iterable<string>): string;
+export declare function containsSecretLikeValue(input: string): boolean;
+/**
+ * A line-buffered `Transform` that redacts secrets BEFORE bytes touch disk or
+ * console. Pipe a child process's stdout/stderr through it
+ * (`child.stdout.pipe(createRedactingStream()).pipe(process.stdout)`) so a
+ * secret can never be written and "cleaned up after"; the secret you didn't
+ * recognise is the one already on disk.
+ *
+ * Buffers by line so a secret split across a chunk boundary is still redacted:
+ * a partial trailing line is held until the next chunk (or `flush`) completes
+ * it. `known` is forwarded to `redactString` for optional value seeding.
+ */
+export declare function createRedactingStream(known?: Iterable<string>): Transform;

package/dist/_contracts/sdk-secrets.js

@@ -0,0 +1,220 @@
+import { Transform } from "node:stream";
+/**
+ * Value-AGNOSTIC secret patterns: each matches a SHAPE, not a known value.
+ * Correctness must not depend on seeding the redactor with the literal
+ * secret — the two real leaks this project hit were a database password that
+ * survived a naive `sed` mask (as a substring) and an Anthropic key emitted by
+ * `wrangler workflows describe` that the harness NEVER loaded. A value-seeded
+ * redactor is blind to both; these patterns catch them by form.
+ *
+ * Ordering matters: structured shapes (connection strings, auth headers, JWT)
+ * come BEFORE the generic key/entropy catch-alls so the more descriptive
+ * `[REDACTED …]` label wins on overlapping matches.
+ */
+const SECRET_PATTERNS = [
+    // postgres / postgresql connection strings — redact the whole URI so the
+    // embedded password can never survive as a substring (the `sed`-mask leak).
+    /\bpostgres(?:ql)?:\/\/[^\s"']+/gi,
+    // Authorization: Bearer <token> — redact the credential, keep the header name
+    // so logs stay legible.
+    /\b(Authorization\s*:\s*Bearer)\s+[A-Za-z0-9._~+/=-]{8,}/gi,
+    // Anthropic + OpenAI-style prefixed keys.
+    /sk-ant-[A-Za-z0-9_-]{16,}/g,
+    /sk-[A-Za-z0-9_-]{20,}/g,
+    // aex workspace / proxy tokens: apt_… / ant_….
+    /\b(?:apt|ant)_[A-Za-z0-9_-]{16,}/g,
+    // Slack tokens.
+    /xox[pbar]-[A-Za-z0-9-]{10,}/g,
+    // AWS access key id + secret access key shapes.
+    /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g,
+    /\baws_secret_access_key["'\s:=]+[A-Za-z0-9/+=]{40}/gi,
+    // JWT-shaped: header.payload.signature, each base64url, header starts `eyJ`.
+    /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g,
+    // Keyword-introduced secret assignments (bearer/token/api_key/…).
+    /(?:bearer|token|api[_-]?key|access[_-]?token|refresh[_-]?token|client[_-]?secret)["'\s:=]+[A-Za-z0-9_\-./+=]{12,}/gi
+];
+const REDACTED = "[REDACTED]";
+/**
+ * Generic high-entropy token catch-all, applied AFTER the named patterns.
+ * Catches the secret nobody recognised: any long base64url/hex-ish run that is
+ * BOTH high-entropy AND character-class-diverse.
+ *
+ * The candidate run deliberately EXCLUDES `_`: secrets are contiguous opaque
+ * runs, whereas `SCREAMING_SNAKE_CASE` env names and `snake_case` identifiers
+ * are `_`-separated words — excluding `_` breaks those into sub-24 fragments so
+ * they are never eaten (the `CF_CONFORMANCE_PROBE_URL` false positive). The
+ * class-diversity gate (≥2 of lower/upper/digit) then keeps the remaining
+ * single-class runs (all-lowercase module paths like `internal/modules/esm`)
+ * while still catching mixed-case/alnum secret blobs. Entropy alone cannot
+ * separate these — `the_quick…` (4.16) out-scores a real key prefix.
+ */
+const HIGH_ENTROPY_CANDIDATE = /[A-Za-z0-9+/=-]{24,}/g;
+const ENTROPY_BITS_PER_CHAR = 3.0;
+const MIN_CHAR_CLASSES = 2;
+/**
+ * A mixed-case run with no digit and < this length is treated as a benign
+ * identifier, not a secret. Real opaque secrets are alnum-mixed (carry a
+ * digit) or very long; digit-free camelCase identifiers like
+ * `asyncRunEntryPointWithESMLoader` / `createDurableObjectNamespace` (which
+ * appear in stack traces the diagnostic bundle captures) are 24–39 chars and
+ * digit-free — eating them would gut debuggability. The length escape hatch
+ * still catches the rare long digit-free secret.
+ */
+const HIGH_ENTROPY_NO_DIGIT_MIN_LEN = 40;
+export class SecretString {
+    #value;
+    constructor(value, label = "secret") {
+        if (!value) {
+            throw new Error(`${label} is required`);
+        }
+        this.#value = value;
+    }
+    unwrap() {
+        return this.#value;
+    }
+    toString() {
+        return REDACTED;
+    }
+    toJSON() {
+        return REDACTED;
+    }
+}
+export function redactSecrets(value) {
+    if (typeof value === "string") {
+        return redactString(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => redactSecrets(item));
+    }
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [key, item] of Object.entries(value)) {
+            if (isSecretKey(key)) {
+                out[key] = REDACTED;
+            }
+            else {
+                out[key] = redactSecrets(item);
+            }
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Redact every secret-shaped run in `input`.
+ *
+ * `known` is an OPTIONAL belt-and-suspenders set of literal values to also mask
+ * (e.g. creds the caller happens to have loaded). Correctness does NOT depend on
+ * it — every shape above is caught with or without seeding — but masking known
+ * values first removes any residual substring of a value the shapes split.
+ */
+export function redactString(input, known = []) {
+    let out = input;
+    for (const value of known) {
+        if (value && value.length >= 4) {
+            out = out.split(value).join(REDACTED);
+        }
+    }
+    out = SECRET_PATTERNS.reduce((current, pattern) => current.replace(pattern, (match, captured) => 
+    // Patterns with a captured prefix (Authorization header) keep the
+    // prefix; the rest replace the whole match.
+    typeof captured === "string" ? `${captured} ${REDACTED}` : REDACTED), out);
+    return out.replace(HIGH_ENTROPY_CANDIDATE, (match) => looksHighEntropySecret(match) ? REDACTED : match);
+}
+export function containsSecretLikeValue(input) {
+    if (SECRET_PATTERNS.some((pattern) => {
+        pattern.lastIndex = 0;
+        return pattern.test(input);
+    })) {
+        return true;
+    }
+    HIGH_ENTROPY_CANDIDATE.lastIndex = 0;
+    let candidate;
+    while ((candidate = HIGH_ENTROPY_CANDIDATE.exec(input)) !== null) {
+        if (looksHighEntropySecret(candidate[0])) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * A line-buffered `Transform` that redacts secrets BEFORE bytes touch disk or
+ * console. Pipe a child process's stdout/stderr through it
+ * (`child.stdout.pipe(createRedactingStream()).pipe(process.stdout)`) so a
+ * secret can never be written and "cleaned up after"; the secret you didn't
+ * recognise is the one already on disk.
+ *
+ * Buffers by line so a secret split across a chunk boundary is still redacted:
+ * a partial trailing line is held until the next chunk (or `flush`) completes
+ * it. `known` is forwarded to `redactString` for optional value seeding.
+ */
+export function createRedactingStream(known = []) {
+    const knownValues = [...known];
+    let carry = "";
+    return new Transform({
+        transform(chunk, _encoding, callback) {
+            carry += chunk.toString();
+            const lastNewline = carry.lastIndexOf("\n");
+            if (lastNewline === -1) {
+                callback();
+                return;
+            }
+            const ready = carry.slice(0, lastNewline + 1);
+            carry = carry.slice(lastNewline + 1);
+            callback(null, redactString(ready, knownValues));
+        },
+        flush(callback) {
+            if (carry === "") {
+                callback();
+                return;
+            }
+            const tail = carry;
+            carry = "";
+            callback(null, redactString(tail, knownValues));
+        }
+    });
+}
+function isSecretKey(key) {
+    return /(?:api[_-]?key|authorization|token|secret|password|credential)/i.test(key);
+}
+/** A candidate run is a high-entropy secret if it is both information-dense
+ * AND mixes character classes (the property that separates opaque secret blobs
+ * from single-class identifiers/paths). */
+function looksHighEntropySecret(value) {
+    if (charClassCount(value) < MIN_CHAR_CLASSES)
+        return false;
+    if (shannonEntropyBits(value) < ENTROPY_BITS_PER_CHAR)
+        return false;
+    // Require a digit OR extreme length so digit-free mixed-case identifiers
+    // (stack-trace frames, API symbol names) are not destroyed in diagnostic
+    // output, while real secret shapes (alnum-mixed, or very long) still match.
+    return /[0-9]/.test(value) || value.length >= HIGH_ENTROPY_NO_DIGIT_MIN_LEN;
+}
+/** How many of {lowercase, uppercase, digit} appear in `value` (0–3). */
+function charClassCount(value) {
+    let count = 0;
+    if (/[a-z]/.test(value))
+        count++;
+    if (/[A-Z]/.test(value))
+        count++;
+    if (/[0-9]/.test(value))
+        count++;
+    return count;
+}
+/** Shannon entropy in bits/char — the per-character information density. */
+function shannonEntropyBits(value) {
+    if (value.length === 0) {
+        return 0;
+    }
+    const counts = new Map();
+    for (const char of value) {
+        counts.set(char, (counts.get(char) ?? 0) + 1);
+    }
+    let bits = 0;
+    for (const count of counts.values()) {
+        const p = count / value.length;
+        bits -= p * Math.log2(p);
+    }
+    return bits;
+}
+//# sourceMappingURL=sdk-secrets.js.map