@aexhq/sdk 0.38.1 → 0.40.0

package/dist/file.js

@@ -1,7 +1,9 @@
-import { readdir, readFile, stat } from "node:fs/promises";
-import { join, relative } from "node:path";
-import { DEFAULT_FILE_MOUNT_PATH, assertValidMountPath } from "./_contracts/index.js";
+import { createReadStream } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
+import { DEFAULT_FILE_MOUNT_PATH, RESERVED_META_ENTRY, assertValidMountPath, bundleManifestIsEmpty, serializeBundleManifest } from "./_contracts/index.js";
 import { hashSkillBundle } from "./bundle.js";
+import { frameCanonicalZipSync, streamBundleZip } from "./canonical-zip.js";
+import { walkDirectory } from "./node-walk.js";
 import { zipSync } from "fflate";
 /**
  * File — arbitrary bytes (single file or zipped folder) delivered to
@@ -19,6 +21,15 @@ import { zipSync } from "fflate";
  * `subtitles.srt` becomes `/workspace/subtitles.srt`, a folder lands its entries
  * under `/workspace/`. The resolved path is surfaced back on the Run record.
  *
+ * FIDELITY: a directory walk captures executable bits and symlinks into a
+ * `.aexmeta.json` sidecar (emitted only when such metadata exists, so a
+ * pure-content bundle stays byte-identical → dedup continuity), and honors
+ * `.aexignore` (gitignore-compatible) plus always-on defaults (`.git/`,
+ * `node_modules/`). SCALE: a large input (total raw size over the streaming
+ * threshold, `File.fromPath` only) is uploaded via a streaming two-pass
+ * multipart flow that holds only one entry + one part in memory, lifting the
+ * old ~2 GiB in-memory ceiling.
+ *
  * `client.run` / `openSession` materializes the bytes to the hosted asset store
  * before the run lands; the wire ref becomes `kind:"asset"`. Repeat uploads of the
  * same bytes are deduped.
@@ -26,11 +37,14 @@ import { zipSync } from "fflate";
 export class File {
     #ref;
     #bytes;
+    /** Large-input streaming driver — re-runs the deterministic canonical-zip framer per pass. */
+    #drive;
     /** Asset id cached after the first use, so reuse skips a re-upload. */
     #assetId;
-    constructor(ref, bytes) {
+    constructor(ref, bytes, drive) {
         this.#ref = ref;
         this.#bytes = bytes;
+        this.#drive = drive;
     }
     get ref() {
         return this.#ref;
@@ -82,42 +96,83 @@ export class File {
      * preserves its real basename (with extension) as the sole zip entry, so the
      * agent finds it at `<mountPath>/<basename>` after unzip. Directories walk
      * recursively into a canonical zip (sorted relative paths, deterministic
-     * mtime), landing each entry under `<mountPath>/`. `mountPath` defaults to
-     * `/workspace`. The optional `name` is only the storage slug (dedup label);
-     * it never affects the on-disk filename.
+     * mtime), landing each entry under `<mountPath>/`. Executable bits + symlinks
+     * are captured into a `.aexmeta.json` sidecar; `.aexignore` (+ defaults) prune
+     * the walk. `mountPath` defaults to `/workspace`. The optional `name` is only
+     * the storage slug (dedup label); it never affects the on-disk filename.
      */
     static async fromPath(path, args) {
         const stats = await stat(path);
         const mountPath = resolveMountPath(args?.mountPath, "File.fromPath");
         // `name` is only the storage slug (dedup label), never the on-disk filename.
-        // Slugify a provided name so the stored slug stays DNS-clean; derive from the
-        // basename when omitted.
         const slug = args?.name !== undefined ? slugFromFilename(args.name) : inferNameFromPath(path);
-        let zip;
-        if (stats.isDirectory()) {
-            zip = await buildDirZip(path);
+        return stats.isDirectory()
+            ? File.#fromDirectory(path, slug, mountPath, args?.ignore)
+            : File.#fromSingleFile(path, slug, mountPath, stats.size, (stats.mode & 0o111) !== 0);
+    }
+    /** Directory branch: walk + fidelity sidecar + small/streaming path selection. */
+    static async #fromDirectory(path, slug, mountPath, ignore) {
+        const walk = await walkDirectory(path, ignore);
+        if (walk.entries.length === 0 && walk.symlinks.length === 0) {
+            throw new Error(`File.fromPath: directory ${JSON.stringify(path)} is empty (no regular files or symlinks)`);
         }
-        else {
-            const bytes = await readFile(path);
-            const basename = path.replace(/\\/g, "/").replace(/\/+$/, "").split("/").at(-1) ?? "";
-            const filename = sanitiseFilename(basename) ?? `${slug}`;
-            zip = zipSync({ [filename]: [bytes, { mtime: ZIP_EPOCH }] }, { level: 6 });
+        const meta = { exec: walk.exec, symlinks: walk.symlinks };
+        const sidecar = bundleManifestIsEmpty(meta)
+            ? undefined
+            : serializeBundleManifest({ v: 1, exec: walk.exec, symlinks: walk.symlinks });
+        if (walk.totalSize <= SMALL_UPLOAD_THRESHOLD_BYTES) {
+            // Small: read all bytes and build the canonical zip in memory (single PUT).
+            const ordered = [];
+            for (const entry of walk.entries) {
+                ordered.push([entry.rel, new Uint8Array(await readFile(entry.absPath))]);
+            }
+            if (sidecar)
+                ordered.push([RESERVED_META_ENTRY, sidecar]);
+            const zip = frameCanonicalZipSync(ordered);
+            const contentHash = await hashSkillBundle(zip);
+            return new File({ kind: "draft", name: slug, contentHash, mountPath }, zip);
         }
-        const contentHash = await hashSkillBundle(zip);
-        const ref = {
-            kind: "draft",
-            name: slug,
-            contentHash,
-            mountPath
-        };
-        return new File(ref, zip);
+        // Large: stream the canonical zip (never materialize the whole bundle).
+        const sources = buildEntrySources(walk.entries, sidecar);
+        const drive = (sink) => streamBundleZip(sources, sink);
+        return new File({ kind: "draft", name: slug, mountPath }, undefined, drive);
+    }
+    /** Single-file branch: preserve the basename; capture the +x bit; small/streaming by size. */
+    static async #fromSingleFile(path, slug, mountPath, size, isExecutable) {
+        const basename = path.replace(/\\/g, "/").replace(/\/+$/, "").split("/").at(-1) ?? "";
+        const filename = sanitiseFilename(basename) ?? `${slug}`;
+        const sidecar = isExecutable
+            ? serializeBundleManifest({ v: 1, exec: [filename], symlinks: [] })
+            : undefined;
+        if (size <= SMALL_UPLOAD_THRESHOLD_BYTES) {
+            const bytes = new Uint8Array(await readFile(path));
+            const ordered = [[filename, bytes]];
+            if (sidecar)
+                ordered.push([RESERVED_META_ENTRY, sidecar]);
+            const zip = frameCanonicalZipSync(ordered);
+            const contentHash = await hashSkillBundle(zip);
+            return new File({ kind: "draft", name: slug, contentHash, mountPath }, zip);
+        }
+        const sources = [
+            {
+                name: filename,
+                size,
+                read: async () => new Uint8Array(await readFile(path)),
+                openStream: () => fileByteStream(path)
+            }
+        ];
+        if (sidecar)
+            sources.push({ name: RESERVED_META_ENTRY, size: sidecar.length, read: () => sidecar });
+        const drive = (sink) => streamBundleZip(sources, sink);
+        return new File({ kind: "draft", name: slug, mountPath }, undefined, drive);
     }
     /**
      * Internal: yield the draft's zipped bytes + metadata so
-     * `client.run` / `openSession` can upload it as an asset.
+     * `client.run` / `openSession` can upload it as an asset (single PUT).
+     * Returns undefined for a streaming (large) draft — use {@link _takeDraftStream}.
      */
     _takeDraftBundle() {
-        if (this.#ref.kind !== "draft" || !this.#bytes) {
+        if (this.#ref.kind !== "draft" || !this.#bytes || this.#ref.contentHash === undefined) {
             return undefined;
         }
         return {
@@ -127,6 +182,16 @@ export class File {
             mountPath: this.#ref.mountPath
         };
     }
+    /**
+     * Internal: yield the draft's canonical-zip stream driver so `client.run` can
+     * upload it via the streaming multipart flow. Returns undefined for the small
+     * (in-memory) draft — use {@link _takeDraftBundle}.
+     */
+    _takeDraftStream() {
+        if (this.#ref.kind !== "draft" || !this.#drive)
+            return undefined;
+        return { name: this.#ref.name, mountPath: this.#ref.mountPath, drive: this.#drive };
+    }
     toJSON() {
         if (this.#ref.kind === "draft") {
             throw new Error("File: draft Files cannot be JSON-serialised — they only become wire refs when " +
@@ -137,6 +202,34 @@ export class File {
 }
 const ZIP_EPOCH = new Date(Date.UTC(1980, 0, 1));
 const WORKSPACE_NAME_RE = /^[a-z0-9][a-z0-9-]{0,62}[a-z0-9]$/;
+/**
+ * Total raw input size (via `stat`, before reading bytes) above which
+ * `File.fromPath` streams the upload instead of building the whole zip in
+ * memory. A pure performance/simplicity switch, NOT a correctness boundary — the
+ * streaming framer is byte-identical to the in-memory `zipSync` for Canonical A,
+ * so a bundle at the threshold dedups either way.
+ */
+const SMALL_UPLOAD_THRESHOLD_BYTES = 64 * 1024 * 1024;
+/** Build lazy zip entry sources from walked descriptors, appending the sidecar LAST. */
+function buildEntrySources(entries, sidecar) {
+    const sources = entries.map((entry) => ({
+        name: entry.rel,
+        size: entry.size,
+        read: async () => new Uint8Array(await readFile(entry.absPath)),
+        openStream: () => fileByteStream(entry.absPath)
+    }));
+    if (sidecar) {
+        sources.push({ name: RESERVED_META_ENTRY, size: sidecar.length, read: () => sidecar });
+    }
+    return sources;
+}
+/** Async-iterate a file's bytes in native stream chunks (for Canonical-B giant entries). */
+async function* fileByteStream(absPath) {
+    const stream = createReadStream(absPath);
+    for await (const chunk of stream) {
+        yield chunk;
+    }
+}
 /**
  * Resolve + validate a caller-supplied `mountPath`, defaulting to `/workspace`.
  * Shares {@link assertValidMountPath} with the contracts parser so the SDK and
@@ -185,31 +278,4 @@ function inferNameFromPath(path) {
     const base = normalised.split("/").at(-1) ?? "";
     return slugFromFilename(base);
 }
-async function buildDirZip(dirPath) {
-    const files = [];
-    await walkDir(dirPath, dirPath, files);
-    if (files.length === 0) {
-        throw new Error(`File.fromPath: directory ${JSON.stringify(dirPath)} is empty (no regular files)`);
-    }
-    files.sort((a, b) => (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0));
-    const zippable = {};
-    for (const { rel, bytes } of files) {
-        zippable[rel] = [bytes, { mtime: ZIP_EPOCH }];
-    }
-    return zipSync(zippable, { level: 6 });
-}
-async function walkDir(base, current, result) {
-    const entries = await readdir(current, { withFileTypes: true });
-    for (const entry of entries) {
-        const fullPath = join(current, entry.name);
-        if (entry.isDirectory()) {
-            await walkDir(base, fullPath, result);
-        }
-        else if (entry.isFile()) {
-            const bytes = await readFile(fullPath);
-            const rel = relative(base, fullPath).replace(/\\/g, "/");
-            result.push({ rel, bytes: new Uint8Array(bytes) });
-        }
-    }
-}
 //# sourceMappingURL=file.js.map

package/dist/file.js.map

@@ -1 +1 @@
-{"version":3,"file":"file.js","sourceRoot":"","sources":["../src/file.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"file.js","sourceRoot":"","sources":["../src/file.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,37 +1,46 @@
 /**
  * Public surface of the `aex` SDK.
  *
- * `Aex` is the single SDK client. Composition primitives are `Tool` / `Tools`
- * (skill-tools), `McpServer`, `AgentsMd`, `File`, and `Secret`. Everything else
- * is types, errors, and event type guards re-exported from `@aexhq/contracts`.
+ * `Aex` is the single SDK client. Composition primitives are `Tool`, `Skill`,
+ * `McpServer`, `AgentsMd`, `File`, and `Secret`. Everything else is types,
+ * errors, and event type guards re-exported from `@aexhq/contracts`.
  */
-export { Aex, AgentsMdClient, FilesClient, SecretsClient, SessionClient, SessionHandle, SessionTurnStream } from "./client.js";
-export type { AexOptions, Message, OutputDownloadOptions, OutputFilePathMatch, OutputFilePathSelector, OutputFileSelector, OutputLinkSelector, RunCollectOptions, RunResult, SessionCreateOptions, SessionEnvironmentOptions, SessionEvents, SessionInput, SessionMessages, SessionOutputs, SessionOverrides, SessionRunOptions, SessionRunResult, SessionSendOptions, SessionTurnResult, SessionWebhooks, StreamEventsOptions, WaitForRunOptions } from "./client.js";
+export { Aex, AgentsMdClient, ChildRunHandle, FilesClient, OutputsClient, SecretsClient, SessionClient, SessionHandle, SessionTurnStream, SkillsClient } from "./client.js";
+export type { AexOptions, BatchOptions, Message, OutputDownloadOptions, OutputFilePathMatch, OutputFilePathSelector, OutputFileSelector, OutputLinkSelector, PerSessionOutputSearchQuery, RunCollectOptions, RunEvents, RunOutputs, RunResult, SessionCreateOptions, SessionEnvironmentOptions, SessionEvents, SessionInput, SessionMessages, SessionOutputs, SessionOverrides, SessionRunOptions, SessionRunResult, SessionSendOptions, SessionTerminalRead, SessionTurnResult, SessionWebhooks, SettleAwait, StreamEventsOptions, SubmitResult, WaitForRunOptions } from "./client.js";
 export { Tool } from "./tool.js";
-export { SkillTool, Tools } from "./skill-tool.js";
+export { Skill } from "./skill.js";
 export { AgentsMd } from "./agents-md.js";
 export { File } from "./file.js";
 export { McpServer } from "./mcp-server.js";
 export { Secret } from "./secret.js";
 export type { SecretEnvSubmissionEntry } from "./secret.js";
 export { bundleSkillFiles, hashSkillBundle } from "./bundle.js";
-export type { BundledSkill, BundledTool, SkillFiles, ToolBundleManifest } from "./bundle.js";
-export { AexApiError, AexError, AexNetworkError, CleanupError, CredentialValidationError, ProviderError, RunConfigValidationError, RunStateError } from "./_contracts/index.js";
+export type { BundledSkill, BundledTool, BundleMeta, SkillFiles, ToolBundleManifest } from "./bundle.js";
+export { AEX_API_ERROR_CODES, AEX_API_ERROR_MESSAGES, AEX_API_ERROR_REMEDIES, AexApiError, AexAuthError, AexError, AexIdempotencyConflictError, AexNetworkError, AexNotFoundError, CleanupError, CredentialValidationError, ProviderError, RunConfigValidationError, RunStateError, apiErrorFromResponse, isAexApiErrorCode, isAuthError, isIdempotencyConflict, isInsufficientScope, isNotFound } from "./_contracts/index.js";
+export type { AexApiErrorCode } from "./_contracts/index.js";
 export { AexRateLimitError, isRateLimited, isThrottleFault, parseProviderFault } from "./retry.js";
 export type { ProviderFault, RetryOptions } from "./retry.js";
-export { MCP_SERVER_NAME_PATTERN, SKILL_BUNDLE_LIMITS, SkillBundleValidationError, normaliseSkillBundlePath, validateSkillBundleEntry, validateSkillBundleManifest } from "./_contracts/index.js";
-export type { AssetRef, AgentsMdRef, FileRef, McpServerRef, SkillBundleEntry, SkillBundleManifest, SkillToolRef, ToolInputSchema, ToolRef } from "./_contracts/index.js";
-export type { AgentsMdRecord as AgentsMdRecordWire, BillingCheckoutPlanKey, BillingCheckoutRequest, BillingHostedSession, BillingLedgerEntry, BillingLedgerPage, BillingLedgerQuery, BillingPortalRequest, BillingSummary, FileRecord as FileRecordWire, Output, OutputFileType, OutputLink, OutputLinkOptions, OutputQuery, OutputSearchQuery, OutputSearchHit, OutputSearchPage, OutputText, ProviderEvent, ReadOutputTextOptions, Run, Session, SessionEvent, SessionListPage, SessionListQuery, SessionRetentionPolicy, SessionStatus, SessionSummary, SessionTurn, RunRecordArchiveFileV1, RunRecordArchiveFileRoleV1, RunRecordArchiveNamespaceV1, RunRecordCostV1, RunRecordDownloadErrorV1, RunRecordFileStatusV1, RunRecordManifestV1, RunRecordMetadataV1, RunRecordNamespaceV1, RunRecordSubmissionSnapshotV1, RunRecordV1, RunEvent, RunWebhookDelivery, RunWebhookDeliveryStatus, RuntimeManifest, SecretRecord, UsageSummary, WebhookSigningSecret, WhoAmI } from "./_contracts/index.js";
+export { MCP_SERVER_NAME_PATTERN, SKILL_BUNDLE_LIMITS, SKILL_NAME_PATTERN, SKILL_RESERVED_NAMES, SkillBundleValidationError, normaliseSkillBundlePath, validateSkillBundleEntry, validateSkillBundleManifest } from "./_contracts/index.js";
+export type { AssetRef, AgentsMdRef, FileRef, McpServerRef, SkillBundleEntry, SkillBundleManifest, SkillRecord as SkillRecordWire, SkillRef, ToolInputSchema, ToolRef } from "./_contracts/index.js";
+export type { AgentsMdRecord as AgentsMdRecordWire, BillingCheckoutPlanKey, BillingCheckoutRequest, BillingHostedSession, BillingLedgerEntry, BillingLedgerPage, BillingLedgerQuery, BillingPortalRequest, BillingSummary, FileRecord as FileRecordWire, Output, OutputFileType, OutputLink, OutputLinkOptions, OutputQuery, OutputSearchQuery, OutputSearchHit, OutputSearchPage, OutputText, ProviderEvent, ReadOutputTextOptions, Run, Session, SessionEvent, SessionListPage, SessionListQuery, SessionRetentionPolicy, SessionStatus, SessionSummary, SessionTurn, RunRecordArchiveFileV1, RunRecordArchiveFileRoleV1, RunRecordArchiveNamespaceV1, RunRecordCostV1, RunRecordDownloadErrorV1, RunRecordFileStatusV1, RunRecordManifestV1, RunRecordMetadataV1, RunRecordNamespaceV1, RunRecordSubmissionSnapshotV1, RunRecordV1, RunWebhookDelivery, RunWebhookDeliveryStatus, RuntimeManifest, SecretRecord, UsageSummary, WebhookSigningSecret, WhoAmI } from "./_contracts/index.js";
 export type { PlatformInlineSecrets as InlineSecrets, PlatformMcpServerSecret as McpServerSecret, PlatformEnvironment as RunEnvironment, PlatformRunSubmissionRequest, RunLimits, RunWebhookSpec, } from "./_contracts/index.js";
 export { CUSTODY_MANIFEST_SCHEMA_VERSION, RUN_RECORD_MANIFEST_SCHEMA_VERSION, RUN_RECORD_SCHEMA_VERSION, DEFAULT_RUNTIME_SIZE, RUNTIME_SIZE_PRESETS, RUNTIME_SIZES } from "./_contracts/index.js";
 export { RuntimeSizes as Sizes } from "./_contracts/index.js";
 export type { RuntimeResources, RuntimeSize } from "./_contracts/index.js";
 export { BUILTIN_TOOL_NAMES, BuiltinTools, DEFAULT_BUILTIN_TOOLS, resolveBuiltinToolNames } from "./_contracts/index.js";
 export type { BuiltinToolName } from "./_contracts/index.js";
-export { DEFAULT_RUN_PROVIDER, RUN_MODELS, RUN_MODELS_BY_PROVIDER, MODEL_PROVIDER_IDS, Models, providerForModel, providersForModel, resolveProviderModelId, isRunModel, parseRunModel, Providers, RUN_PROVIDERS } from "./_contracts/index.js";
+export { DEFAULT_RUN_PROVIDER, RUN_MODELS, RUN_MODELS_BY_PROVIDER, MODEL_PROVIDER_IDS, Models, providerForModel, providersForModel, resolveModelProvider, resolveProviderModelId, isRunModel, parseRunModel, Providers, RUN_PROVIDERS, suggest } from "./_contracts/index.js";
 export type { RunModel, RunProvider } from "./_contracts/index.js";
-export { AEX_RUN_SETTLED_NAME, isCustom, isEventChannel, isFromSource, isLog, isRunError, isRunFinished, isRunSettled, isRunStarted, isRunTerminal, isTextMessage, isToolCallResult, isToolCallStart } from "./_contracts/index.js";
-export type { RunFinishedRunEvent, TextMessageRunEvent, ToolCallResultRunEvent, ToolCallStartRunEvent } from "./_contracts/index.js";
+export { usageFromProviderUsage } from "./_contracts/index.js";
+export type { BatchItemResult, BatchResult, ChildRunRef, ResolvableRunRef, RunOutcome, RunRefusalReason, SettledResult } from "./_contracts/index.js";
+export { SESSION_STATUSES, SESSION_TERMINAL_OUTCOMES, isTerminalSessionStatus } from "./_contracts/index.js";
+export type { SessionTerminalOutcome } from "./_contracts/index.js";
+export { PLANE_BASE_URLS, parseApiKey } from "./_contracts/index.js";
+export type { ApiKeyPlane, ParsedApiKey } from "./_contracts/index.js";
+export { RESPONSE_FORMAT_KINDS, STREAMABLE_SHAPES, isStreamableProvider, parseApprovalGate, parseResponseFormat } from "./_contracts/index.js";
+export type { ApprovalGate, ResponseFormat, ResponseFormatKind, StreamableShape } from "./_contracts/index.js";
+export { AEX_RUN_SETTLED_NAME } from "./_contracts/index.js";
+export type { AexEventView, TextMessageEventView, ToolCallResultEventView, ToolCallStartEventView } from "./_contracts/index.js";
 export { SecretString, redactSecrets } from "./_contracts/index.js";
 export { verifyAexWebhook } from "./_contracts/index.js";
 export type { VerifyAexWebhookInput } from "./_contracts/index.js";

package/dist/index.js

@@ -1,21 +1,23 @@
 /**
  * Public surface of the `aex` SDK.
  *
- * `Aex` is the single SDK client. Composition primitives are `Tool` / `Tools`
- * (skill-tools), `McpServer`, `AgentsMd`, `File`, and `Secret`. Everything else
- * is types, errors, and event type guards re-exported from `@aexhq/contracts`.
+ * `Aex` is the single SDK client. Composition primitives are `Tool`, `Skill`,
+ * `McpServer`, `AgentsMd`, `File`, and `Secret`. Everything else is types,
+ * errors, and event type guards re-exported from `@aexhq/contracts`.
  */
-export { Aex, AgentsMdClient, FilesClient, SecretsClient, SessionClient, SessionHandle, SessionTurnStream } from "./client.js";
+export { Aex, AgentsMdClient, ChildRunHandle, FilesClient, OutputsClient, SecretsClient, SessionClient, SessionHandle, SessionTurnStream, SkillsClient } from "./client.js";
 // Composition primitives
 export { Tool } from "./tool.js";
-export { SkillTool, Tools } from "./skill-tool.js";
+export { Skill } from "./skill.js";
 export { AgentsMd } from "./agents-md.js";
 export { File } from "./file.js";
 export { McpServer } from "./mcp-server.js";
 export { Secret } from "./secret.js";
 export { bundleSkillFiles, hashSkillBundle } from "./bundle.js";
-// Errors
-export { AexApiError, AexError, AexNetworkError, CleanupError, CredentialValidationError, ProviderError, RunConfigValidationError, RunStateError } from "./_contracts/index.js";
+// Errors. One wire→exception factory (`apiErrorFromResponse`) + a stable
+// `apiCode` on every `AexApiError`; typed subclasses (`AexAuthError` /
+// `AexIdempotencyConflictError` / `AexNotFoundError`) each narrow with a guard.
+export { AEX_API_ERROR_CODES, AEX_API_ERROR_MESSAGES, AEX_API_ERROR_REMEDIES, AexApiError, AexAuthError, AexError, AexIdempotencyConflictError, AexNetworkError, AexNotFoundError, CleanupError, CredentialValidationError, ProviderError, RunConfigValidationError, RunStateError, apiErrorFromResponse, isAexApiErrorCode, isAuthError, isIdempotencyConflict, isInsufficientScope, isNotFound } from "./_contracts/index.js";
 // Built-in transport resilience. Every BFF request is retried on transient
 // failures (429/5xx/529 + network errors) with bounded backoff + jitter,
 // honoring `Retry-After`; tune or disable via the client's `retry` option.
@@ -23,7 +25,7 @@ export { AexApiError, AexError, AexNetworkError, CleanupError, CredentialValidat
 // `isRateLimited`), which can carry an upstream `ProviderFault`.
 export { AexRateLimitError, isRateLimited, isThrottleFault, parseProviderFault } from "./retry.js";
 // Skill-bundle / MCP wire types
-export { MCP_SERVER_NAME_PATTERN, SKILL_BUNDLE_LIMITS, SkillBundleValidationError, normaliseSkillBundlePath, validateSkillBundleEntry, validateSkillBundleManifest } from "./_contracts/index.js";
+export { MCP_SERVER_NAME_PATTERN, SKILL_BUNDLE_LIMITS, SKILL_NAME_PATTERN, SKILL_RESERVED_NAMES, SkillBundleValidationError, normaliseSkillBundlePath, validateSkillBundleEntry, validateSkillBundleManifest } from "./_contracts/index.js";
 // Runtime sizing — the closed set of valid managed runtime presets.
 // Prefer the `Sizes` symbol const (e.g. `Sizes.SHARED_2X_8GB`)
 // so an invalid token is a compile error, not a runtime 400.
@@ -36,12 +38,27 @@ export { RuntimeSizes as Sizes } from "./_contracts/index.js";
 export { BUILTIN_TOOL_NAMES, BuiltinTools, DEFAULT_BUILTIN_TOOLS, resolveBuiltinToolNames } from "./_contracts/index.js";
 // Provider/model surface. Provider choice decides the upstream model route;
 // execution uses the managed path.
-export { DEFAULT_RUN_PROVIDER, RUN_MODELS, RUN_MODELS_BY_PROVIDER, MODEL_PROVIDER_IDS, Models, providerForModel, providersForModel, resolveProviderModelId, isRunModel, parseRunModel, Providers, RUN_PROVIDERS } from "./_contracts/index.js";
-// Event guards. The lifecycle/channel guards (isRunStarted/isRunError/isCustom/
-// isLog/…) operate on the coordinator `AexEvent` envelope; isTextMessage /
-// isToolCallStart / isToolCallResult / isRunFinished narrow the loose `RunEvent`
-// snapshot shape `listEvents` / `RunResult.events` return, typing `.data`.
-export { AEX_RUN_SETTLED_NAME, isCustom, isEventChannel, isFromSource, isLog, isRunError, isRunFinished, isRunSettled, isRunStarted, isRunTerminal, isTextMessage, isToolCallResult, isToolCallStart } from "./_contracts/index.js";
+export { DEFAULT_RUN_PROVIDER, RUN_MODELS, RUN_MODELS_BY_PROVIDER, MODEL_PROVIDER_IDS, Models, providerForModel, providersForModel, resolveModelProvider, resolveProviderModelId, isRunModel, parseRunModel, Providers, RUN_PROVIDERS, suggest } from "./_contracts/index.js";
+// Unified settled-result / batch / typed-decode / lineage surface (WS3/WS8/WS10).
+export { usageFromProviderUsage } from "./_contracts/index.js";
+// Status vocabulary (WS1): the terminal-outcome half + guard, bound to the run
+// outcome SSoT. The bare session `error` is retired — a failed turn is `failed`.
+export { SESSION_STATUSES, SESSION_TERMINAL_OUTCOMES, isTerminalSessionStatus } from "./_contracts/index.js";
+// Self-describing API-key codec + plane routing (WS11): the constructor parses
+// the key to derive the plane baseUrl and fail fast on a plane mismatch.
+export { PLANE_BASE_URLS, parseApiKey } from "./_contracts/index.js";
+// Structured-output (schema-decode), HITL approval-gate, and the streaming
+// capability model (WS9/WS10).
+export { RESPONSE_FORMAT_KINDS, STREAMABLE_SHAPES, isStreamableProvider, parseApprovalGate, parseResponseFormat } from "./_contracts/index.js";
+// Event methods. Every event the SDK yields — the turn stream (`session.send()`),
+// `session.events().list()`, `session.events().streamEnvelopes()`, and
+// `RunResult.events` — is an `AexEventView`: the coordinator envelope enriched
+// with one type-guard METHOD per standardized event type, so a consumer branches
+// with `event.isTextMessage()` / `event.isToolCallStart()` / `event.isRunError()`
+// / … instead of a free-function guard or a raw `event.type === "…"` compare.
+// `isTextMessage()` / `isToolCallStart()` / `isToolCallResult()` additionally
+// NARROW `event.data` to that type's fields (e.g. `event.data.text` is `string`).
+export { AEX_RUN_SETTLED_NAME } from "./_contracts/index.js";
 // Secret utilities
 export { SecretString, redactSecrets } from "./_contracts/index.js";
 // Webhook verification — customers verify inbound run webhooks (Standard

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,GAAG,EACH,cAAc,EACd,WAAW,EACX,aAAa,EACb,aAAa,EACb,aAAa,EACb,iBAAiB,EAClB,MAAM,aAAa,CAAC;AA2BrB,yBAAyB;AACzB,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGhE,SAAS;AACT,OAAO,EACL,WAAW,EACX,QAAQ,EACR,eAAe,EACf,YAAY,EACZ,yBAAyB,EACzB,aAAa,EACb,wBAAwB,EACxB,aAAa,EACd,MAAM,kBAAkB,CAAC;AAE1B,2EAA2E;AAC3E,yEAAyE;AACzE,2EAA2E;AAC3E,qEAAqE;AACrE,iEAAiE;AACjE,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAGnG,gCAAgC;AAChC,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,0BAA0B,EAC1B,wBAAwB,EACxB,wBAAwB,EACxB,2BAA2B,EAC5B,MAAM,kBAAkB,CAAC;AA6E1B,oEAAoE;AACpE,+DAA+D;AAC/D,6DAA6D;AAC7D,OAAO,EACL,+BAA+B,EAC/B,kCAAkC,EAClC,yBAAyB,EACzB,oBAAoB,EACpB,oBAAoB,EACpB,aAAa,EACd,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,YAAY,IAAI,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAGzD,8EAA8E;AAC9E,oFAAoF;AACpF,wEAAwE;AACxE,8EAA8E;AAC9E,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAGpH,4EAA4E;AAC5E,mCAAmC;AACnC,OAAO,EACL,oBAAoB,EACpB,UAAU,EACV,sBAAsB,EACtB,kBAAkB,EAClB,MAAM,EACN,gBAAgB,EAChB,iBAAiB,EACjB,sBAAsB,EACtB,UAAU,EACV,aAAa,EACb,SAAS,EACT,aAAa,EACd,MAAM,kBAAkB,CAAC;AAM1B,gFAAgF;AAChF,2EAA2E;AAC3E,iFAAiF;AACjF,2EAA2E;AAC3E,OAAO,EACL,oBAAoB,EACpB,QAAQ,EACR,cAAc,EACd,YAAY,EACZ,KAAK,EACL,UAAU,EACV,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,eAAe,EAChB,MAAM,kBAAkB,CAAC;AAQ1B,mBAAmB;AACnB,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAE/D,yEAAyE;AACzE,6EAA6E;AAC7E,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/node-fs.d.ts

@@ -1,12 +1,29 @@
-import type { SkillFiles } from "./bundle.js";
+import type { BundleMeta } from "./bundle.js";
+import { type IgnoreOptions } from "./node-walk.js";
 /**
- * Walk a local directory and load every regular file into an in-memory
- * `SkillFiles` map. Symlinks and non-regular files are skipped (a
- * symlink that points outside the root would still be skipped because
- * we use `lstat` semantics). Paths are normalised to forward-slash
- * relative form so they can flow into `bundleSkillFiles` directly.
+ * Fidelity-aware read of a local skill/tool directory into an in-memory files map
+ * plus its bundle metadata. Delegates to the shared {@link walkDirectory} (the
+ * SAME fidelity walk `File.fromPath` uses), so skills/tools now honor `.aexignore`
+ * + the always-on defaults (`.git/`, `node_modules/`, …), capture executable bits
+ * + symlinks into `meta` (destined for the `.aexmeta.json` sidecar), and never
+ * silently vanish a non-regular file (surfaced in `dropped`).
  *
- * Bun/Node filesystem runtimes only. Browser callers should use
- * `bundleSkillFiles` with a pre-built files map instead.
+ * INVARIANT: for a directory with NO exec bits, NO symlinks, and NO ignored paths,
+ * `meta` is empty → the downstream bundler emits NO sidecar, so the bundle bytes
+ * are byte-identical to the pre-fidelity `readDirectoryAsFiles` output (dedup
+ * continuity). Only metadata (or an `.aexignore`/ignored path) changes the bytes.
+ *
+ * Bun/Node filesystem runtimes only. Browser callers pass a pre-built files map to
+ * `bundleSkillFiles` / `bundleToolFiles` directly and never reach this module.
  */
-export declare function readDirectoryAsFiles(rootDir: string): Promise<SkillFiles>;
+export interface DirectoryBundle {
+    /** Regular-file bytes, keyed by forward-slash bundle-relative path. */
+    readonly files: Record<string, Uint8Array>;
+    /** Exec bits + symlinks → the `.aexmeta.json` sidecar (empty ⇒ no sidecar emitted). */
+    readonly meta: BundleMeta;
+    /** Non-regular files skipped (FIFO/socket/device) — never silently vanished. Sorted. */
+    readonly dropped: readonly string[];
+    /** Count of paths pruned by the ignore layers (`.aexignore` + defaults). */
+    readonly ignoredCount: number;
+}
+export declare function readDirectoryWithFidelity(rootDir: string, ignore?: IgnoreOptions): Promise<DirectoryBundle>;

package/dist/node-fs.js

@@ -1,44 +1,19 @@
-import { readFile, readdir, stat } from "node:fs/promises";
-import { join, posix, relative, sep } from "node:path";
-/**
- * Walk a local directory and load every regular file into an in-memory
- * `SkillFiles` map. Symlinks and non-regular files are skipped (a
- * symlink that points outside the root would still be skipped because
- * we use `lstat` semantics). Paths are normalised to forward-slash
- * relative form so they can flow into `bundleSkillFiles` directly.
- *
- * Bun/Node filesystem runtimes only. Browser callers should use
- * `bundleSkillFiles` with a pre-built files map instead.
- */
-export async function readDirectoryAsFiles(rootDir) {
+import { readFile } from "node:fs/promises";
+import { walkDirectory } from "./node-walk.js";
+export async function readDirectoryWithFidelity(rootDir, ignore) {
     if (typeof rootDir !== "string" || !rootDir) {
-        throw new Error("readDirectoryAsFiles: rootDir is required");
-    }
-    const rootStat = await stat(rootDir);
-    if (!rootStat.isDirectory()) {
-        throw new Error(`readDirectoryAsFiles: ${rootDir} is not a directory`);
+        throw new Error("readDirectoryWithFidelity: rootDir is required");
     }
+    const walk = await walkDirectory(rootDir, ignore);
     const files = {};
-    await walk(rootDir, rootDir, files);
-    return files;
-}
-async function walk(rootDir, currentDir, out) {
-    const entries = await readdir(currentDir, { withFileTypes: true });
-    for (const dirent of entries) {
-        const full = join(currentDir, dirent.name);
-        if (dirent.isSymbolicLink()) {
-            continue;
-        }
-        if (dirent.isDirectory()) {
-            await walk(rootDir, full, out);
-            continue;
-        }
-        if (!dirent.isFile()) {
-            continue;
-        }
-        const rel = relative(rootDir, full);
-        const posixPath = sep === "/" ? rel : rel.split(sep).join(posix.sep);
-        out[posixPath] = await readFile(full);
+    for (const entry of walk.entries) {
+        files[entry.rel] = new Uint8Array(await readFile(entry.absPath));
     }
+    return {
+        files,
+        meta: { exec: walk.exec, symlinks: walk.symlinks },
+        dropped: walk.dropped,
+        ignoredCount: walk.ignoredCount
+    };
 }
 //# sourceMappingURL=node-fs.js.map

package/dist/node-fs.js.map

@@ -1 +1 @@
-{"version":3,"file":"node-fs.js","sourceRoot":"","sources":["../src/node-fs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAGvD;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,OAAe;IACxD,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,CAAC,OAAO,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC/D,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,CAAC;IACrC,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,yBAAyB,OAAO,qBAAqB,CAAC,CAAC;IACzE,CAAC;IACD,MAAM,KAAK,GAA+B,EAAE,CAAC;IAC7C,MAAM,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;IACpC,OAAO,KAAK,CAAC;AACf,CAAC;AAED,KAAK,UAAU,IAAI,CAAC,OAAe,EAAE,UAAkB,EAAE,GAA+B;IACtF,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IACnE,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QAC3C,IAAI,MAAM,CAAC,cAAc,EAAE,EAAE,CAAC;YAC5B,SAAS;QACX,CAAC;QACD,IAAI,MAAM,CAAC,WAAW,EAAE,EAAE,CAAC;YACzB,MAAM,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;YAC/B,SAAS;QACX,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;YACrB,SAAS;QACX,CAAC;QACD,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QACpC,MAAM,SAAS,GAAG,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACrE,GAAG,CAAC,SAAS,CAAC,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;IACxC,CAAC;AACH,CAAC"}
+{"version":3,"file":"node-fs.js","sourceRoot":"","sources":["../src/node-fs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,OAAO,EAAE,aAAa,EAAsB,MAAM,gBAAgB,CAAC;AA6BnE,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAAC,OAAe,EAAE,MAAsB;IACrF,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,CAAC,OAAO,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;IACpE,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAClD,MAAM,KAAK,GAA+B,EAAE,CAAC;IAC7C,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QACjC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,UAAU,CAAC,MAAM,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;IACnE,CAAC;IACD,OAAO;QACL,KAAK;QACL,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE;QAClD,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,YAAY,EAAE,IAAI,CAAC,YAAY;KAChC,CAAC;AACJ,CAAC"}