@aexhq/sdk 0.13.6

package/dist/_contracts/runtime-manifest.js

@@ -0,0 +1,98 @@
+/**
+ * Runtime manifest: the per-run, per-provider description of where
+ * aex places things inside the agent container, plus the merged
+ * env-var bag delivered via `RUNTIME.env` / `RUNTIME.json`.
+ *
+ * The hosted API computes a manifest at submitRun-response time
+ * (from the validated submission + the chosen provider) via
+ * {@link buildRuntimeManifest} and echoes it on the wire as
+ * `Run.runtimeManifest`, so caller code (anyone rendering catalog markdown
+ * pre-submission, or resolving aex's in-container path strings) doesn't
+ * have to guess.
+ * The managed runtime materialises the actual `RUNTIME.env` / `RUNTIME.json`
+ * files in-container from the same provider + envVars inputs, so the
+ * SDK-side view and the in-container view describe the same layout.
+ *
+ * Manifest values are derived, never persisted separately — the source
+ * of truth for the customer half remains `submission.environment.envVars`
+ * on the run row; the aex half is constant for a given
+ * provider+SDK-version pair.
+ */
+/**
+ * Managed-runner container paths. Kept here so the BFF, worker, and
+ * in-container bridge render identical values; runtime bootstrap constants are
+ * validated against these by a regression test
+ * (`packages/contracts/test/runtime-manifest.test.ts`).
+ */
+const ANTHROPIC_PATHS = Object.freeze({
+    skillsRoot: "/workspace/skills",
+    filesRoot: "/mnt/session/uploads/aex/files",
+    assetsRoot: "/mnt/session/uploads/aex/assets",
+    aexCli: "/mnt/session/uploads/aex/aex",
+    indexJson: "/mnt/session/uploads/aex/index.json",
+    readme: "/mnt/session/uploads/aex/SKILLS.md",
+    runtimeJson: "/mnt/session/uploads/aex/RUNTIME.json",
+    runtimeEnv: "/mnt/session/uploads/aex/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 aex-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 AEX_PREFIX = "AEX_";
+/**
+ * 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 aexEnvVars = {
+        AEX_PROVIDER: input.provider,
+        AEX_CLI: paths.aexCli,
+        AEX_SKILLS_ROOT: paths.skillsRoot,
+        AEX_FILES_ROOT: paths.filesRoot,
+        AEX_ASSETS_ROOT: paths.assetsRoot,
+        AEX_INDEX_JSON: paths.indexJson,
+        AEX_README: paths.readme,
+        AEX_RUNTIME_JSON: paths.runtimeJson,
+        AEX_RUNTIME_ENV: paths.runtimeEnv
+    };
+    const customerEnvVars = {};
+    for (const [key, value] of Object.entries(input.customerEnvVars ?? {})) {
+        if (key.startsWith(AEX_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({ ...aexEnvVars, ...customerEnvVars });
+    return Object.freeze({
+        provider: input.provider,
+        skillsRoot: paths.skillsRoot,
+        filesRoot: paths.filesRoot,
+        assetsRoot: paths.assetsRoot,
+        aexCli: paths.aexCli,
+        indexJson: paths.indexJson,
+        readme: paths.readme,
+        runtimeJson: paths.runtimeJson,
+        runtimeEnv: paths.runtimeEnv,
+        envVars
+    });
+}
+//# sourceMappingURL=runtime-manifest.js.map

package/dist/_contracts/runtime-security-profile.d.ts

@@ -0,0 +1,27 @@
+export declare const RUNTIME_SECURITY_PROFILES: readonly ["strict", "standard", "developer"];
+export type RuntimeSecurityProfileName = (typeof RUNTIME_SECURITY_PROFILES)[number];
+export interface RuntimeSecurityProfile {
+    readonly name: RuntimeSecurityProfileName;
+    readonly defaultNetworkingMode: "limited" | "open";
+    readonly allowOpenNetworking: boolean;
+    readonly allowRuntimePackages: boolean;
+    readonly allowCustomerEnvVars: boolean;
+    readonly allowProxyEndpoints: boolean;
+    readonly allowMcpServers: boolean;
+}
+export interface RuntimeSecurityProfileEvaluationInput {
+    readonly networkingMode?: "limited" | "open";
+    readonly packageCount?: number;
+    readonly customerEnvVarCount?: number;
+    readonly proxyEndpointCount?: number;
+    readonly mcpServerCount?: number;
+}
+export interface RuntimeSecurityProfileViolation {
+    readonly field: string;
+    readonly reason: string;
+}
+export declare const RUNTIME_SECURITY_PROFILE_CONFIG: Readonly<Record<RuntimeSecurityProfileName, RuntimeSecurityProfile>>;
+export declare function parseRuntimeSecurityProfile(input: unknown): RuntimeSecurityProfileName | undefined;
+export declare function resolveRuntimeSecurityProfile(input: RuntimeSecurityProfileName | undefined): RuntimeSecurityProfile;
+export declare function serializeRuntimeSecurityProfile(profile: RuntimeSecurityProfileName): string;
+export declare function evaluateRuntimeSecurityProfile(profileName: RuntimeSecurityProfileName | undefined, input: RuntimeSecurityProfileEvaluationInput): readonly RuntimeSecurityProfileViolation[];

package/dist/_contracts/runtime-security-profile.js

@@ -0,0 +1,82 @@
+export const RUNTIME_SECURITY_PROFILES = ["strict", "standard", "developer"];
+export const RUNTIME_SECURITY_PROFILE_CONFIG = Object.freeze({
+    strict: Object.freeze({
+        name: "strict",
+        defaultNetworkingMode: "limited",
+        allowOpenNetworking: false,
+        allowRuntimePackages: false,
+        allowCustomerEnvVars: true,
+        allowProxyEndpoints: true,
+        allowMcpServers: true
+    }),
+    standard: Object.freeze({
+        name: "standard",
+        defaultNetworkingMode: "limited",
+        allowOpenNetworking: true,
+        allowRuntimePackages: true,
+        allowCustomerEnvVars: true,
+        allowProxyEndpoints: true,
+        allowMcpServers: true
+    }),
+    developer: Object.freeze({
+        name: "developer",
+        defaultNetworkingMode: "open",
+        allowOpenNetworking: true,
+        allowRuntimePackages: true,
+        allowCustomerEnvVars: true,
+        allowProxyEndpoints: true,
+        allowMcpServers: true
+    })
+});
+export function parseRuntimeSecurityProfile(input) {
+    if (input === undefined || input === null) {
+        return undefined;
+    }
+    if (typeof input !== "string" || !RUNTIME_SECURITY_PROFILES.includes(input)) {
+        throw new Error(`securityProfile must be one of: ${RUNTIME_SECURITY_PROFILES.join(", ")} (got ${JSON.stringify(input)})`);
+    }
+    return input;
+}
+export function resolveRuntimeSecurityProfile(input) {
+    return RUNTIME_SECURITY_PROFILE_CONFIG[input ?? "standard"];
+}
+export function serializeRuntimeSecurityProfile(profile) {
+    parseRuntimeSecurityProfile(profile);
+    return profile;
+}
+export function evaluateRuntimeSecurityProfile(profileName, input) {
+    const profile = resolveRuntimeSecurityProfile(profileName);
+    const violations = [];
+    if (input.networkingMode === "open" && !profile.allowOpenNetworking) {
+        violations.push({
+            field: "environment.networking.mode",
+            reason: `${profile.name} requires limited networking`
+        });
+    }
+    if ((input.packageCount ?? 0) > 0 && !profile.allowRuntimePackages) {
+        violations.push({
+            field: "environment.packages",
+            reason: `${profile.name} does not allow runtime package installs`
+        });
+    }
+    if ((input.customerEnvVarCount ?? 0) > 0 && !profile.allowCustomerEnvVars) {
+        violations.push({
+            field: "environment.envVars",
+            reason: `${profile.name} does not allow customer runtime env vars`
+        });
+    }
+    if ((input.proxyEndpointCount ?? 0) > 0 && !profile.allowProxyEndpoints) {
+        violations.push({
+            field: "proxyEndpoints",
+            reason: `${profile.name} does not allow HTTP proxy endpoints`
+        });
+    }
+    if ((input.mcpServerCount ?? 0) > 0 && !profile.allowMcpServers) {
+        violations.push({
+            field: "submission.mcpServers",
+            reason: `${profile.name} does not allow MCP servers`
+        });
+    }
+    return Object.freeze(violations);
+}
+//# sourceMappingURL=runtime-security-profile.js.map

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

@@ -0,0 +1,144 @@
+/**
+ * Managed runtime sizing presets.
+ *
+ * The public contract exposes product-level runtime size tokens, not host
+ * implementation details. The closed token set keeps invalid resource pairings
+ * out of the wire contract while leaving the concrete host mapping private.
+ */
+export interface RuntimeResources {
+    readonly cpus: number;
+    readonly memoryMb: number;
+}
+/**
+ * The single source of truth: every offered preset, keyed by its wire token.
+ * Tokens intentionally remain stable product presets.
+ */
+export declare const RUNTIME_SIZE_PRESETS: {
+    readonly "shared-1x-256mb": {
+        readonly cpus: 1;
+        readonly memoryMb: 256;
+    };
+    readonly "shared-1x-512mb": {
+        readonly cpus: 1;
+        readonly memoryMb: 512;
+    };
+    readonly "shared-1x-1gb": {
+        readonly cpus: 1;
+        readonly memoryMb: 1024;
+    };
+    readonly "shared-1x-2gb": {
+        readonly cpus: 1;
+        readonly memoryMb: 2048;
+    };
+    readonly "shared-2x-512mb": {
+        readonly cpus: 2;
+        readonly memoryMb: 512;
+    };
+    readonly "shared-2x-1gb": {
+        readonly cpus: 2;
+        readonly memoryMb: 1024;
+    };
+    readonly "shared-2x-2gb": {
+        readonly cpus: 2;
+        readonly memoryMb: 2048;
+    };
+    readonly "shared-2x-4gb": {
+        readonly cpus: 2;
+        readonly memoryMb: 4096;
+    };
+    readonly "shared-4x-1gb": {
+        readonly cpus: 4;
+        readonly memoryMb: 1024;
+    };
+    readonly "shared-4x-2gb": {
+        readonly cpus: 4;
+        readonly memoryMb: 2048;
+    };
+    readonly "shared-4x-4gb": {
+        readonly cpus: 4;
+        readonly memoryMb: 4096;
+    };
+    readonly "shared-4x-8gb": {
+        readonly cpus: 4;
+        readonly memoryMb: 8192;
+    };
+    readonly "shared-8x-2gb": {
+        readonly cpus: 8;
+        readonly memoryMb: 2048;
+    };
+    readonly "shared-8x-4gb": {
+        readonly cpus: 8;
+        readonly memoryMb: 4096;
+    };
+    readonly "shared-8x-8gb": {
+        readonly cpus: 8;
+        readonly memoryMb: 8192;
+    };
+    readonly "shared-8x-16gb": {
+        readonly cpus: 8;
+        readonly memoryMb: 16384;
+    };
+};
+/** The accepted runtime-size values (the wire/CLI tokens). */
+export type RuntimeSize = keyof typeof RUNTIME_SIZE_PRESETS;
+/** All preset tokens, ordered as declared. Handy for CLI help + validation. */
+export declare const RUNTIME_SIZES: readonly RuntimeSize[];
+/** Default when `runtimeSize` is omitted. */
+export declare const DEFAULT_RUNTIME_SIZE: RuntimeSize;
+/**
+ * Symbol-style accessors for TS callers. `RuntimeSizes.SHARED_2X_2GB`
+ * resolves to the wire token `"shared-2x-2gb"`.
+ */
+export declare const RuntimeSizes: {
+    readonly SHARED_1X_256MB: "shared-1x-256mb";
+    readonly SHARED_1X_512MB: "shared-1x-512mb";
+    readonly SHARED_1X_1GB: "shared-1x-1gb";
+    readonly SHARED_1X_2GB: "shared-1x-2gb";
+    readonly SHARED_2X_512MB: "shared-2x-512mb";
+    readonly SHARED_2X_1GB: "shared-2x-1gb";
+    readonly SHARED_2X_2GB: "shared-2x-2gb";
+    readonly SHARED_2X_4GB: "shared-2x-4gb";
+    readonly SHARED_4X_1GB: "shared-4x-1gb";
+    readonly SHARED_4X_2GB: "shared-4x-2gb";
+    readonly SHARED_4X_4GB: "shared-4x-4gb";
+    readonly SHARED_4X_8GB: "shared-4x-8gb";
+    readonly SHARED_8X_2GB: "shared-8x-2gb";
+    readonly SHARED_8X_4GB: "shared-8x-4gb";
+    readonly SHARED_8X_8GB: "shared-8x-8gb";
+    readonly SHARED_8X_16GB: "shared-8x-16gb";
+};
+/** Resolve a preset token to its product-level resource descriptor. */
+export declare function runtimeResources(size: RuntimeSize): RuntimeResources;
+/**
+ * Validate the wire `runtimeSize` field. `undefined` (omitted) is allowed and
+ * consumers apply {@link DEFAULT_RUNTIME_SIZE}.
+ */
+export declare function parseRuntimeSize(input: unknown): RuntimeSize | undefined;
+/** Default run deadline when `timeout` is omitted (1 hour). */
+export declare const DEFAULT_RUN_TIMEOUT_MS: number;
+/** Hard ceiling on a run deadline (6 hours). */
+export declare const MAX_RUN_TIMEOUT_MS: number;
+/** Floor on a run deadline (1 minute). */
+export declare const MIN_RUN_TIMEOUT_MS: number;
+/**
+ * Parse a human duration string (`"1h"`, `"90m"`, `"3600s"`, `"500ms"`, or a
+ * bare-ms integer) into milliseconds. Throws on malformed input.
+ */
+export declare function parseDurationToMs(input: string): number;
+/**
+ * Validate the wire `timeout` field (a duration string) into a bounded ms
+ * value. `undefined` (omitted) returns `undefined`; the consumer applies
+ * {@link DEFAULT_RUN_TIMEOUT_MS}.
+ */
+export declare function parseRunTimeout(input: unknown): number | undefined;
+/** Apply the default when a parsed `timeoutMs` is absent. */
+export declare function resolveRunTimeoutMs(timeoutMs: number | undefined): number;
+/** Format a millisecond deadline as a second-granularity duration string. */
+export declare function orchestrationTimeoutString(ms: number): string;
+/** Runtime process: time to wait after graceful interrupt before hard kill. */
+export declare const RUN_PROCESS_KILL_GRACE_MS: number;
+/**
+ * Orchestrator: extra window past `timeoutMs` to wait for terminal callback
+ * before host-level cleanup.
+ */
+export declare const RUN_TERMINAL_GRACE_MS: number;

package/dist/_contracts/runtime-sizes.js

@@ -0,0 +1,136 @@
+/**
+ * Managed runtime sizing presets.
+ *
+ * The public contract exposes product-level runtime size tokens, not host
+ * implementation details. The closed token set keeps invalid resource pairings
+ * out of the wire contract while leaving the concrete host mapping private.
+ */
+/**
+ * The single source of truth: every offered preset, keyed by its wire token.
+ * Tokens intentionally remain stable product presets.
+ */
+export const RUNTIME_SIZE_PRESETS = {
+    "shared-1x-256mb": { cpus: 1, memoryMb: 256 },
+    "shared-1x-512mb": { cpus: 1, memoryMb: 512 },
+    "shared-1x-1gb": { cpus: 1, memoryMb: 1024 },
+    "shared-1x-2gb": { cpus: 1, memoryMb: 2048 },
+    "shared-2x-512mb": { cpus: 2, memoryMb: 512 },
+    "shared-2x-1gb": { cpus: 2, memoryMb: 1024 },
+    "shared-2x-2gb": { cpus: 2, memoryMb: 2048 },
+    "shared-2x-4gb": { cpus: 2, memoryMb: 4096 },
+    "shared-4x-1gb": { cpus: 4, memoryMb: 1024 },
+    "shared-4x-2gb": { cpus: 4, memoryMb: 2048 },
+    "shared-4x-4gb": { cpus: 4, memoryMb: 4096 },
+    "shared-4x-8gb": { cpus: 4, memoryMb: 8192 },
+    "shared-8x-2gb": { cpus: 8, memoryMb: 2048 },
+    "shared-8x-4gb": { cpus: 8, memoryMb: 4096 },
+    "shared-8x-8gb": { cpus: 8, memoryMb: 8192 },
+    "shared-8x-16gb": { cpus: 8, memoryMb: 16384 }
+};
+/** All preset tokens, ordered as declared. Handy for CLI help + validation. */
+export const RUNTIME_SIZES = Object.keys(RUNTIME_SIZE_PRESETS);
+/** Default when `runtimeSize` is omitted. */
+export const DEFAULT_RUNTIME_SIZE = "shared-1x-512mb";
+/**
+ * Symbol-style accessors for TS callers. `RuntimeSizes.SHARED_2X_2GB`
+ * resolves to the wire token `"shared-2x-2gb"`.
+ */
+export const RuntimeSizes = {
+    SHARED_1X_256MB: "shared-1x-256mb",
+    SHARED_1X_512MB: "shared-1x-512mb",
+    SHARED_1X_1GB: "shared-1x-1gb",
+    SHARED_1X_2GB: "shared-1x-2gb",
+    SHARED_2X_512MB: "shared-2x-512mb",
+    SHARED_2X_1GB: "shared-2x-1gb",
+    SHARED_2X_2GB: "shared-2x-2gb",
+    SHARED_2X_4GB: "shared-2x-4gb",
+    SHARED_4X_1GB: "shared-4x-1gb",
+    SHARED_4X_2GB: "shared-4x-2gb",
+    SHARED_4X_4GB: "shared-4x-4gb",
+    SHARED_4X_8GB: "shared-4x-8gb",
+    SHARED_8X_2GB: "shared-8x-2gb",
+    SHARED_8X_4GB: "shared-8x-4gb",
+    SHARED_8X_8GB: "shared-8x-8gb",
+    SHARED_8X_16GB: "shared-8x-16gb"
+};
+/** Resolve a preset token to its product-level resource descriptor. */
+export function runtimeResources(size) {
+    return RUNTIME_SIZE_PRESETS[size];
+}
+/**
+ * Validate the wire `runtimeSize` field. `undefined` (omitted) is allowed and
+ * consumers apply {@link DEFAULT_RUNTIME_SIZE}.
+ */
+export function parseRuntimeSize(input) {
+    if (input === undefined) {
+        return undefined;
+    }
+    if (typeof input !== "string" || !RUNTIME_SIZES.includes(input)) {
+        throw new Error(`runtimeSize must be one of: ${RUNTIME_SIZES.join(", ")} (got ${JSON.stringify(input)})`);
+    }
+    return input;
+}
+// ===========================================================================
+// Run timeout
+// ===========================================================================
+/** Default run deadline when `timeout` is omitted (1 hour). */
+export const DEFAULT_RUN_TIMEOUT_MS = 60 * 60 * 1000;
+/** Hard ceiling on a run deadline (6 hours). */
+export const MAX_RUN_TIMEOUT_MS = 6 * 60 * 60 * 1000;
+/** Floor on a run deadline (1 minute). */
+export const MIN_RUN_TIMEOUT_MS = 60 * 1000;
+const DURATION_PATTERN = /^(\d+(?:\.\d+)?)(ms|s|m|h)?$/;
+/**
+ * Parse a human duration string (`"1h"`, `"90m"`, `"3600s"`, `"500ms"`, or a
+ * bare-ms integer) into milliseconds. Throws on malformed input.
+ */
+export function parseDurationToMs(input) {
+    const match = DURATION_PATTERN.exec(input.trim());
+    if (!match) {
+        throw new Error(`invalid duration ${JSON.stringify(input)} (expected e.g. "1h", "90m", "30s", "500ms", or a bare ms integer)`);
+    }
+    const value = Number(match[1]);
+    if (!Number.isFinite(value) || value < 0) {
+        throw new Error(`invalid duration ${JSON.stringify(input)} (must be a non-negative number)`);
+    }
+    const unit = match[2] ?? "ms";
+    const factor = unit === "h" ? 3_600_000 : unit === "m" ? 60_000 : unit === "s" ? 1_000 : 1;
+    return Math.round(value * factor);
+}
+/**
+ * Validate the wire `timeout` field (a duration string) into a bounded ms
+ * value. `undefined` (omitted) returns `undefined`; the consumer applies
+ * {@link DEFAULT_RUN_TIMEOUT_MS}.
+ */
+export function parseRunTimeout(input) {
+    if (input === undefined) {
+        return undefined;
+    }
+    if (typeof input !== "string") {
+        throw new Error(`timeout must be a duration string (e.g. "1h", "30m"); got ${JSON.stringify(input)}`);
+    }
+    const ms = parseDurationToMs(input);
+    if (ms < MIN_RUN_TIMEOUT_MS) {
+        throw new Error(`timeout must be at least ${MIN_RUN_TIMEOUT_MS}ms (1m); got ${ms}ms`);
+    }
+    if (ms > MAX_RUN_TIMEOUT_MS) {
+        throw new Error(`timeout must be at most ${MAX_RUN_TIMEOUT_MS}ms (6h); got ${ms}ms`);
+    }
+    return ms;
+}
+/** Apply the default when a parsed `timeoutMs` is absent. */
+export function resolveRunTimeoutMs(timeoutMs) {
+    return timeoutMs ?? DEFAULT_RUN_TIMEOUT_MS;
+}
+/** Format a millisecond deadline as a second-granularity duration string. */
+export function orchestrationTimeoutString(ms) {
+    return `${Math.max(1, Math.ceil(ms / 1000))}s`;
+}
+/** Runtime process: time to wait after graceful interrupt before hard kill. */
+export const RUN_PROCESS_KILL_GRACE_MS = 60 * 1000;
+/**
+ * Orchestrator: extra window past `timeoutMs` to wait for terminal callback
+ * before host-level cleanup.
+ */
+export const RUN_TERMINAL_GRACE_MS = 90 * 1000;
+//# sourceMappingURL=runtime-sizes.js.map