@aexhq/sdk 0.40.15 → 0.41.0

package/dist/_contracts/{run-config.js → session-config.js}

@@ -1,10 +1,10 @@
 /**
- * Run-request config and composition refs for the public SDK/CLI surface.
+ * SessionRecord-request config and composition refs for the public SDK/CLI surface.
  *
  * Public composition concepts:
  *
  *   - `SkillRef` is the PUBLIC wire-level reference to a workspace skill: just
- *     `{ kind:"skill", name }`. The binding is BY NAME and mutable — the run
+ *     `{ kind:"skill", name }`. The binding is BY NAME and mutable — the session
  *     resolves the name to the workspace skill's current bytes at submit time.
  *     It travels in `submission.skills` (NOT `submission.tools`).
  *
@@ -16,12 +16,12 @@
  *
  *   - `McpServerRef` is the non-secret part of an MCP server declaration:
  *     `name` and `url`. Bearer / cookie / per-request headers travel in
- *     the run's vaulted `secrets.mcpServers` block keyed by the same
+ *     the session's vaulted `secrets.mcpServers` block keyed by the same
  *     `name`, and never enter the hashed submission payload or the
- *     run snapshot.
+ *     session snapshot.
  *
- *   - `RunRequestConfig` is the credential-free set of run parameters that
- *     can be persisted to disk (e.g. `aex run --config run.json`) or
+ *   - `SessionRequestConfig` is the credential-free set of session parameters that
+ *     can be persisted to disk (e.g. `aex start --config session.json`) or
  *     returned from ordinary application helper functions. It excludes
  *     `secrets`/`idempotencyKey`/`signal`; strings are already resolved at
  *     the call site before submission.
@@ -35,7 +35,7 @@
  * Keep this as the public source of truth for the SDK/CLI composition
  * boundary.
  */
-import { parseRunModel } from "./models.js";
+import { parseModelName } from "./models.js";
 // ---------------------------------------------------------------------------
 // Skill ID + name format
 // ---------------------------------------------------------------------------
@@ -336,7 +336,7 @@ export function hasSkillMdAtRoot(manifest) {
     return manifest.entries.some((entry) => entry.path === "SKILL.md");
 }
 // ---------------------------------------------------------------------------
-// McpServerRef (non-secret) + RunConfigMcpServer (with optional headers)
+// McpServerRef (non-secret) + SessionConfigMcpServer (with optional headers)
 // ---------------------------------------------------------------------------
 /**
  * Remote MCP transports Aex accepts. Both are over HTTP — `http`
@@ -367,13 +367,13 @@ export function parseMcpServerRef(input, path) {
     }
     const record = input;
     rejectStdioMcpShape(record);
-    // Headers belong on `RunConfigMcpServer`, not the non-secret wire ref;
+    // Headers belong on `SessionConfigMcpServer`, not the non-secret wire ref;
     // and the wire `submission.mcpServers` must NEVER contain headers. So
     // reject any field other than {name,url,transport} explicitly to make a
     // caller accidentally inlining `headers` into the non-secret half fail
     // loudly instead of silently dropping the field.
-    // `parseRunConfigMcpServerRef` handles the headers case separately for
-    // run-config entries.
+    // `parseSessionConfigMcpServerRef` handles the headers case separately for
+    // session-config entries.
     for (const key of Object.keys(record)) {
         if (key !== "name" && key !== "url" && key !== "transport") {
             throw new Error(`${path}.${key} is not an allowed field for McpServerRef; permitted: name, url, transport`);
@@ -394,7 +394,7 @@ export function parseMcpServerRef(input, path) {
         }
         // Auth belongs in `secrets.mcpServers[i].headers`, never in the URL
         // itself. A `https://user:pass@host` style URL would be persisted in
-        // the non-secret run snapshot and hashed into the idempotency key —
+        // the non-secret session snapshot and hashed into the idempotency key —
         // both unacceptable for credential material.
         if (parsed.username !== "" || parsed.password !== "") {
             throw new Error(`${path}.url must not contain userinfo (username/password); use secrets.mcpServers[].headers for auth`);
@@ -556,11 +556,11 @@ function parseRemoteMcpTransport(input, field) {
     return input;
 }
 /**
- * Strict parser for run-config MCP server entries. Allows only the
- * `{name, url, headers?}` shape so config loaded from `--config run.json`
+ * Strict parser for session-config MCP server entries. Allows only the
+ * `{name, url, headers?}` shape so config loaded from `--config session.json`
  * cannot smuggle unrelated fields past the parser.
  */
-function parseRunConfigMcpServerRef(input, path) {
+function parseSessionConfigMcpServerRef(input, path) {
     if (input === null || typeof input !== "object" || Array.isArray(input)) {
         throw new Error(`${path} must be an object`);
     }
@@ -568,7 +568,7 @@ function parseRunConfigMcpServerRef(input, path) {
     rejectStdioMcpShape(record);
     for (const key of Object.keys(record)) {
         if (key !== "name" && key !== "url" && key !== "headers" && key !== "transport") {
-            throw new Error(`${path}.${key} is not an allowed field for RunConfigMcpServer; permitted: name, url, transport, headers`);
+            throw new Error(`${path}.${key} is not an allowed field for SessionConfigMcpServer; permitted: name, url, transport, headers`);
         }
     }
     // Reuse the {name,url,transport} validator by passing the stripped object.
@@ -593,17 +593,17 @@ function parseRunConfigMcpServerRef(input, path) {
     return { ...ref, headers };
 }
 // ---------------------------------------------------------------------------
-// Run request config parser (used by CLI to load `run.json`)
+// SessionRecord request config parser (used by CLI to load `session.json`)
 // ---------------------------------------------------------------------------
 /**
- * Parse a run request config from JSON. Defensive — used by the host CLI to
- * load `--config run.json`. Throws with the JSON path that failed so
+ * Parse a session request config from JSON. Defensive — used by the host CLI to
+ * load `--config session.json`. Throws with the JSON path that failed so
  * a user can fix their file. Headers are preserved here and split out
  * later by the SDK normalisation step.
  */
-export function parseRunRequestConfig(input) {
+export function parseSessionRequestConfig(input) {
     if (input === null || typeof input !== "object" || Array.isArray(input)) {
-        throw new Error("run request config must be an object");
+        throw new Error("session request config must be an object");
     }
     const record = input;
     const allowed = new Set([
@@ -618,23 +618,23 @@ export function parseRunRequestConfig(input) {
     ]);
     for (const key of Object.keys(record)) {
         if (!allowed.has(key)) {
-            throw new Error(`run request config contains unexpected field: ${key}`);
+            throw new Error(`session request config contains unexpected field: ${key}`);
         }
     }
-    const model = parseRunModel(record.model, "run request config model");
+    const model = parseModelName(record.model, "session request config model");
     const system = record.system;
     if (system !== undefined && typeof system !== "string") {
-        throw new Error("run request config system, when provided, must be a string");
+        throw new Error("session request config system, when provided, must be a string");
     }
-    const prompt = parseRunRequestConfigPrompt(record.prompt);
-    const mcpServers = parseRunRequestConfigMcpServers(record.mcpServers);
+    const prompt = parseSessionRequestConfigPrompt(record.prompt);
+    const mcpServers = parseSessionRequestConfigMcpServers(record.mcpServers);
     return {
         model,
         ...(system !== undefined ? { system } : {}),
         prompt,
         ...(mcpServers !== undefined ? { mcpServers } : {}),
         // environment / metadata: passed through as-is — the BFF revalidates
-        // them via `parseRunSubmissionRequest`,
+        // them via `parseSessionSubmissionRequest`,
         // so duplicating the heavyweight parsers here would mean two sources
         // of truth. The CLI surfaces structural errors at submission time.
         ...(record.environment !== undefined
@@ -651,10 +651,10 @@ export function parseRunRequestConfig(input) {
             : {})
     };
 }
-function parseRunRequestConfigPrompt(value) {
+function parseSessionRequestConfigPrompt(value) {
     if (typeof value === "string") {
         if (value.length === 0) {
-            throw new Error("run request config prompt must be a non-empty string");
+            throw new Error("session request config prompt must be a non-empty string");
         }
         return value;
     }
@@ -663,35 +663,35 @@ function parseRunRequestConfigPrompt(value) {
         for (let i = 0; i < value.length; i++) {
             const item = value[i];
             if (typeof item !== "string" || item.length === 0) {
-                throw new Error(`run request config prompt[${i}] must be a non-empty string`);
+                throw new Error(`session request config prompt[${i}] must be a non-empty string`);
             }
             arr.push(item);
         }
         if (arr.length === 0) {
-            throw new Error("run request config prompt must be a non-empty string or array of strings");
+            throw new Error("session request config prompt must be a non-empty string or array of strings");
         }
         return arr;
     }
-    throw new Error("run request config prompt must be a string or array of strings");
+    throw new Error("session request config prompt must be a string or array of strings");
 }
-function parseRunRequestConfigMcpServers(value) {
+function parseSessionRequestConfigMcpServers(value) {
     if (value === undefined) {
         return undefined;
     }
     if (!Array.isArray(value)) {
-        throw new Error("run request config mcpServers must be an array");
+        throw new Error("session request config mcpServers must be an array");
     }
     const seen = new Set();
     return value.map((item, index) => {
-        const entry = parseRunConfigMcpServerRef(item, `run request config mcpServers[${index}]`);
+        const entry = parseSessionConfigMcpServerRef(item, `session request config mcpServers[${index}]`);
         if (seen.has(entry.name)) {
-            throw new Error(`run request config mcpServers duplicate name: ${entry.name}`);
+            throw new Error(`session request config mcpServers duplicate name: ${entry.name}`);
         }
         seen.add(entry.name);
         return entry;
     });
 }
-export function normaliseRunRequestConfig(config) {
+export function normaliseSessionRequestConfig(config) {
     const prompt = typeof config.prompt === "string" ? [config.prompt] : config.prompt;
     const mcpServers = [];
     const mcpServerSecrets = [];

package/dist/_contracts/session-cost.d.ts

@@ -0,0 +1,140 @@
+import type { ProviderName } from "./submission.js";
+export declare const SESSION_COST_TELEMETRY_SCHEMA_VERSION = 1;
+export declare const SESSION_USAGE_SAMPLE_SCHEMA_VERSION = 1;
+export declare const SESSION_COST_SUMMARY_STATUSES: readonly ["pending", "partial", "complete", "unavailable", "not_applicable"];
+export type SessionCostSummaryStatus = (typeof SESSION_COST_SUMMARY_STATUSES)[number];
+export declare const SESSION_USAGE_SAMPLE_UNITS: readonly ["token", "millisecond", "byte", "byte_millisecond", "count", "file", "credit_unit"];
+export type SessionUsageSampleUnit = (typeof SESSION_USAGE_SAMPLE_UNITS)[number];
+export declare const SESSION_USAGE_SAMPLE_SOURCE_TYPES: readonly ["coordinator-event", "session-event", "usage-ledger", "file-object", "proxy-call", "runtime-job", "provider-session", "storage-accrual", "manual-adjustment"];
+export type SessionUsageSampleSourceType = (typeof SESSION_USAGE_SAMPLE_SOURCE_TYPES)[number];
+export declare const SESSION_USAGE_SAMPLE_METRICS: readonly ["provider.input_tokens", "provider.output_tokens", "provider.cache_read_input_tokens", "provider.cache_creation_input_tokens", "provider.total_tokens", "runtime.queued_ms", "runtime.active_ms", "runtime.file_capture_ms", "runtime.cleanup_ms", "session.total_ms", "file.discovered_files", "file.captured_files", "file.failed_files", "file.captured_bytes", "retry.runtime_attempts", "retry.provider_poll", "retry.file_capture", "retry.file_upload", "capture.uploaded_files", "capture.failed_files", "capture.total_bytes", "storage.current_bytes", "storage.byte_milliseconds", "proxy.call_count", "proxy.failed_call_count", "proxy.request_bytes", "proxy.response_bytes", "proxy.duration_ms"];
+export type SessionUsageSampleMetric = (typeof SESSION_USAGE_SAMPLE_METRICS)[number];
+export interface SessionUsageSampleSource {
+    readonly type: SessionUsageSampleSourceType;
+    readonly id: string;
+    readonly observedAt?: string;
+}
+export interface SessionUsageSample {
+    readonly schemaVersion: typeof SESSION_USAGE_SAMPLE_SCHEMA_VERSION;
+    readonly sampleId?: string;
+    readonly sessionId?: string;
+    readonly metric: SessionUsageSampleMetric;
+    readonly unit: SessionUsageSampleUnit;
+    readonly quantity: number;
+    readonly source: SessionUsageSampleSource;
+    readonly provider?: ProviderName | string;
+    readonly model?: string;
+    readonly recordedAt?: string;
+}
+export type SessionUsageSampleInput = Omit<SessionUsageSample, "schemaVersion" | "unit"> & {
+    readonly unit?: SessionUsageSampleUnit;
+};
+export interface SessionCostSourceSummary {
+    readonly sampleCount: number;
+    readonly metrics?: readonly SessionUsageSampleMetric[];
+    readonly sourceTypes?: readonly SessionUsageSampleSourceType[];
+    readonly sourceSampleIds?: readonly string[];
+}
+export interface SessionCostDurations {
+    readonly queuedMs?: number;
+    readonly runtimeMs?: number;
+    readonly fileCaptureMs?: number;
+    readonly cleanupMs?: number;
+    readonly totalMs?: number;
+}
+export interface SessionCostFileTelemetry {
+    readonly discoveredFiles?: number;
+    readonly capturedFiles?: number;
+    readonly failedFiles?: number;
+    readonly capturedBytes?: number;
+}
+export interface SessionCostRetryTelemetry {
+    readonly runtimeAttempts?: number;
+    readonly providerPollRetries?: number;
+    readonly fileCaptureRetries?: number;
+    readonly fileUploadRetries?: number;
+}
+export interface SessionCostCaptureTelemetry {
+    readonly attempted: boolean;
+    readonly uploadedFiles?: number;
+    readonly failedFiles?: number;
+    readonly totalBytes?: number;
+    readonly failureReasons?: readonly string[];
+}
+export interface SessionCostProviderUsage {
+    readonly provider: ProviderName | string;
+    readonly model?: string;
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+    readonly cacheReadInputTokens?: number;
+    readonly cacheCreationInputTokens?: number;
+    readonly totalTokens?: number;
+    readonly sourceEventId?: string;
+    readonly sourceSampleIds?: readonly string[];
+}
+export interface SessionCostStorageTelemetry {
+    readonly storedBytes?: number;
+    readonly byteMilliseconds?: number;
+}
+export interface SessionCostProxyTelemetry {
+    readonly calls?: number;
+    readonly failedCalls?: number;
+    readonly requestBytes?: number;
+    readonly responseBytes?: number;
+    readonly durationMs?: number;
+}
+/**
+ * The basis for a {@link SessionCostTelemetry.billedCostUsd}: an honest marker of
+ * whether the figure is a settle-time ESTIMATE or has been RECONCILED against
+ * authoritative actuals. Deliberately carries NO rate-card version or unit
+ * rates — the platform's public-safe convention treats `rateCard`/`margin` as
+ * private tokens (session-cost.test.ts privateCostFieldPattern), so the version the
+ * figure was derived under stays internal (recorded only in the platform's
+ * internal raw-usage export).
+ */
+export declare const SESSION_COST_BASIS_STATUSES: readonly ["estimated", "reconciled"];
+export type SessionCostBasisStatus = (typeof SESSION_COST_BASIS_STATUSES)[number];
+export interface SessionCostBasis {
+    readonly currency: "USD";
+    readonly status: SessionCostBasisStatus;
+}
+export interface SessionCostTelemetry {
+    readonly schemaVersion: typeof SESSION_COST_TELEMETRY_SCHEMA_VERSION;
+    readonly sessionId?: string;
+    readonly provider?: ProviderName | string;
+    readonly recordedAt?: string;
+    readonly status?: SessionCostSummaryStatus;
+    readonly sourceSummary?: SessionCostSourceSummary;
+    readonly durations?: SessionCostDurations;
+    readonly files?: SessionCostFileTelemetry;
+    readonly retries?: SessionCostRetryTelemetry;
+    readonly capture?: SessionCostCaptureTelemetry;
+    readonly providerUsage?: readonly SessionCostProviderUsage[];
+    readonly storage?: SessionCostStorageTelemetry;
+    readonly proxy?: SessionCostProxyTelemetry;
+    /**
+     * Customer-facing AEX cost of serving this session, USD — a REPORTED ESTIMATE,
+     * not a charge (telemetry/showback only; no invoicing or credit deduction).
+     * = rawCostUsd × marginMultiplier (margin currently a global 1.0). EXCLUDES
+     * the customer's BYOK provider spend. The raw (pre-margin) figure is kept
+     * internal and never appears on this public-safe shape. A plain number, so it
+     * passes the session-record public-safe archive scan. Absent when the session incurred
+     * no priced AEX usage.
+     */
+    readonly billedCostUsd?: number;
+    /** Currency + estimate/reconciled basis for {@link billedCostUsd}. */
+    readonly costBasis?: SessionCostBasis;
+}
+export type SessionCostTelemetryInput = Omit<SessionCostTelemetry, "schemaVersion">;
+export interface SessionCostTelemetryFromUsageSamplesInput {
+    readonly sessionId?: string;
+    readonly provider?: ProviderName | string;
+    readonly recordedAt?: string;
+    readonly status?: SessionCostSummaryStatus;
+    readonly samples: readonly SessionUsageSampleInput[];
+}
+export declare function buildSessionUsageSample(input: SessionUsageSampleInput): SessionUsageSample;
+export declare function buildSessionCostTelemetry(input: SessionCostTelemetryInput): SessionCostTelemetry;
+export declare function buildSessionCostTelemetryFromUsageSamples(input: SessionCostTelemetryFromUsageSamplesInput): SessionCostTelemetry;
+export declare function summarizeUsageSamples(samples: readonly SessionUsageSampleInput[]): SessionCostSourceSummary;
+export declare function mergeSessionCostTelemetry(base: SessionCostTelemetry, next: SessionCostTelemetryInput): SessionCostTelemetry;