@nestm/storage 0.1.0-alpha.7 → 0.1.0-alpha.8

package/CHANGELOG.md

@@ -1,5 +1,115 @@
 # @nestm/storage
 
+## 0.1.0-alpha.8
+
+### Minor Changes
+
+- d81c6f4: Add a typed `mapCreateConflict` hook to the AI SDK workspace adapter so
+  applications can represent atomic create collisions as domain results without
+  mutating generated tools. Keep replace/ETag conflicts fail-closed and sanitize
+  mapper failures at the tool boundary.
+
+  Mark workspace tools with optional inputs or a combined create/replace union as
+  non-strict for provider schema generation while retaining strict Zod runtime
+  validation.
+
+- a0ea392: Add injectable, replica-safe workspace pagination cursors. The workspace now
+  binds versioned cursor payloads to stable store, mount, tenant/workspace, prefix,
+  operation, query, limit, and expiry context; authorizes non-consuming replay
+  before that expiry; and rejects altered or cross-context continuations.
+  Successful continuation still depends on the embedded provider cursor remaining
+  valid and available.
+
+  Export an AES-256-GCM key-ring codec for stateless multi-replica deployments and
+  an asynchronous byte-payload codec contract for shared durable opaque-token
+  stores. Cursor payloads and tokens are bounded, provider continuations remain
+  opaque, and pagination fails closed when no cursor mechanism is configured.
+  Compatible replicas rely on the universal driver contract for non-consuming,
+  instance-portable provider cursors whose position is independent of page size
+  while the provider token remains valid. Cursor expiry is not a provider-token
+  retention, snapshot-isolation, or uptime promise; provider invalidation remains
+  an operational list failure.
+
+- d996b92: Split the aggregate S3 conditional-mutation and copy declarations into exact
+  create, replace, delete, read, source-copy, destination-copy, atomic-promotion,
+  and multipart-completion capabilities. Add independent AWS S3, Cloudflare R2,
+  and fail-closed custom-endpoint profiles that force unverified drivers
+  read-only; enforce complete physical-key byte budgets; normalize provider
+  errors without retaining raw provider payloads or causes; and publish a reusable
+  provider conformance contract with gated filesystem, AWS, R2, and custom suites.
+
+  Normalize every provider ETag to a canonical bare 1–1024-byte visible ASCII
+  token and serialize exactly one HTTP quote pair at S3 request boundaries.
+  Quoted, weak, wildcard, list-shaped, control-bearing, non-ASCII, and otherwise
+  unsafe values now fail closed instead of being accepted as arbitrary non-empty
+  strings. Applications that persisted quoted ETags must refresh them from
+  provider metadata before conditional mutation; this prevents wildcard/list and
+  header-ambiguity inputs from widening an exact-match precondition.
+
+  Specify and test provider list cursors as non-consuming replayable tokens for
+  unchanged provider state, so higher-level replayable pagination can fail closed
+  when a provider cannot meet that contract.
+
+  Exercise the complete advertised source-condition by destination-condition
+  promotion matrix, including stale-state preservation and competing stale/valid
+  requests. Provider documentation or audited implementation evidence remains
+  required for the internal one-linearization-point claim.
+
+  Ordinary and conditional provider failures now expose stable public messages
+  and preserve only normalized codes and retry flags; raw provider bodies,
+  request metadata, and nested causes are not retained in loggable error shapes.
+
+  Raise the `@aws-sdk/client-s3` peer floor to 3.919.0, the first release that
+  serializes destination conditions for `CopyObject`, and verify the real wire
+  headers in the packed minimum-peer consumer. Native AWS construction now
+  disables environment and shared-config endpoint URL overrides, while the public
+  capability helper derives custom-endpoint provenance from the actual SDK client
+  instead of a duplicated caller hint. Capability decoration is now single-use
+  per raw S3 adapter, preventing broader operations from surviving a later
+  narrower profile application.
+
+  Bind S3 provider authority to package-private raw-client and adapter-method
+  identity plus the exact surface snapshot installed by capability decoration.
+  Structurally S3-backed raw adapters are rejected until they pass through the
+  package helper, regardless of adapter name, proxying, or forged global symbols;
+  same-client aliases cannot replace their raw client, ordinary methods, policies,
+  or conditional operations. Unverified custom endpoints and noncanonical
+  S3-backed provider slugs are forced read-only, while an explicit branded profile
+  unlocks only its declared conditional operations. Endpoint and public-URL
+  provenance now follows the adapter actually produced by the provider loader,
+  including `configJson`.
+
+  Retain `publicBaseUrl` construction policy in the package-owned `s3()` helper
+  so omitted decorator hints cannot re-enable an expiring-download claim. Unknown
+  foreign S3 construction conservatively disables that claim. Validate the exact
+  physical adapter key without stripping leading slashes, and include configured
+  separators plus list/search-derived prefixes in the provider byte budget before
+  dispatch. Search uses files-sdk's own inferred glob-prefix and zero-result
+  semantics instead of duplicating its matcher logic. The innermost dispatch guard
+  repeats these checks after supported in-process plugins have transformed an
+  operation; adapters and plugins remain trusted code rather than a sandbox
+  boundary.
+
+  Derive signed-upload policy claims from the branded provider profile instead
+  of granting them to every S3-compatible endpoint. Native AWS proves content
+  type and POST size-range enforcement; Cloudflare R2 proves content type but not
+  POST form size ranges; omitted custom declarations normalize to false/false so
+  the gateway fails closed. Profile authority is backed by a package-private
+  WeakSet after deep freezing, so reflecting and copying the nominal brand symbol
+  cannot forge conformance evidence.
+
+  Treat the built-in AWS profile as an immutable ceiling for every SDK client
+  with native endpoint provenance, independent of mutable adapter display names.
+  Explicit profiles may narrow its operations, policy bits, and key limit but
+  cannot raise the 1,024-byte physical-key budget or add unsupported claims.
+
+  Enforce every requested signed-upload constraint at URL creation time.
+  Content-type-constrained PUT URLs now sign the `content-type` header; bounded
+  AWS uploads use exact POST MIME and byte-range conditions; unsupported profile
+  constraints and lower-only S3 ranges fail before signing. Bounded POST uploads
+  also reject physical keys ending in AWS's `${filename}` template so an exact
+  authorized key cannot be widened into a prefix policy.
+
 ## 0.1.0-alpha.7
 
 ### Minor Changes

package/README.md

@@ -36,6 +36,14 @@ such as `files-sdk/gcs`:
 pnpm add files-sdk@2.2.3
 ```
 
+Pass AWS-SDK-backed S3 adapters through the package-owned `s3()` and
+`withS3Capabilities()` helpers (or use `createS3StorageDriver()`).
+`createFilesSdkDriver()` rejects a structurally S3-backed raw adapter that has
+not crossed this provenance boundary, even when a wrapper renames or proxies
+the adapter. This prevents callers from bypassing endpoint and provider-profile
+checks by omitting the capability decorator or replacing the public `raw`
+property while retaining methods closed over the original client.
+
 Install only the native SDKs required by the chosen provider. For example:
 
 ```sh
@@ -50,6 +58,11 @@ pnpm add @google-cloud/storage google-auth-library
 pnpm add @azure/storage-blob @azure/core-auth @azure/identity
 ```
 
+`@aws-sdk/client-s3` 3.919.0 or newer is required. Earlier releases omit
+destination `If-Match` and `If-None-Match` from the serialized `CopyObject`
+request even when those fields appear in a newer compile-time command shape;
+the package peer range and packed minimum-peer smoke test enforce this floor.
+
 `files-sdk` currently declares its optional Nest peer for Nest 10 and 11. This
 library does not import `files-sdk/nestjs`; the Nest 12 integration is entirely
 owned here. A package manager may nevertheless report that temporary optional
@@ -110,12 +123,46 @@ control characters, repeated separators, and `.` or `..` segments are rejected
 rather than normalized. Keys and provider cursors returned by a driver are also
 checked before they are converted back to logical paths.
 
+Pagination requires a server-owned cursor configuration. The built-in
+`Aes256GcmStorageWorkspaceCursorCodec` produces versioned, authenticated,
+encrypted tokens that can resume on another request, process, or replica when
+every replica constructs an equivalent codec from the same key ring and uses
+the same stable store identity, physical prefix, mount ID, trusted scope, and
+effective limits. Use one codec instance per process, use a dedicated 32-byte
+key, retain rotated decryption keys for at least one cursor TTL, and derive
+`mountId` and `scope` only from authenticated server context.
+
+The underlying driver must also implement the universal replayable list-cursor
+contract against the same logical backend namespace: its cursor cannot be
+consumed or tied to one driver instance. While the provider cursor remains
+valid and available, an outer cursor can be retried until its authenticated
+expiry. That expiry is only an authorization ceiling: it does not extend a
+provider token's lifetime or promise snapshot isolation, provider availability,
+network access, or valid credentials. Provider invalidation is an operational
+list failure, and concurrent object changes remain subject to provider
+continuation semantics. Without a codec, single-page operations still work but
+a continuation fails closed.
+
 ```ts
-import { mountStorageWorkspace } from '@nestm/storage/workspace';
+import {
+  Aes256GcmStorageWorkspaceCursorCodec,
+  mountStorageWorkspace,
+} from '@nestm/storage/workspace';
+
+// cursorKey is a separately validated 32-byte secret from deployment config.
+const cursorCodec = new Aes256GcmStorageWorkspaceCursorCodec({
+  activeKeyId: 'v1',
+  keys: { v1: cursorKey },
+});
 
 const workspace = mountStorageWorkspace(agentFiles, {
   // Use an opaque server-derived run id, never a value selected by the model.
   prefix: `workspaces/${runId}`,
+  cursor: {
+    codec: cursorCodec,
+    mountId: `agent-workspace:${runId}`,
+    scope: `organization:${organizationId}/workspace:${workspaceId}`,
+  },
   permissions: [
     'list',
     'read',
@@ -127,6 +174,8 @@ const workspace = mountStorageWorkspace(agentFiles, {
     'delete',
   ],
   limits: {
+    cursorTtlMs: 5 * 60 * 1000,
+    maxCursorBytes: 4096,
     maxReadBytes: 1024 * 1024,
     maxWriteBytes: 1024 * 1024,
     maxPageSize: 100,
@@ -220,6 +269,8 @@ import type { ToolSet } from 'ai';
                 // A validated, opaque coordinate from trusted auth/run state.
                 // It is never accepted from a prompt or tool input.
                 prefix: context.storagePrefix,
+                // Includes the singleton codec plus stable mountId and scope.
+                cursor: context.cursorConfiguration,
                 permissions: [
                   'list',
                   'read',
@@ -261,6 +312,24 @@ workspace capability remains the authorization boundary even when approval is
 disabled. The module's `AiSdkService.files()` API is the model provider's file
 upload facility and is unrelated to storage workspaces.
 
+Atomic create collisions remain sanitized tool errors by default. Applications
+that model an existing destination as a normal tool result can map that one
+case while preserving replace/ETag conflicts as failures:
+
+```ts
+const tools = createAiSdkWorkspaceTools({
+  workspace,
+  mapCreateConflict: ({ path }) => ({
+    kind: 'artifact-conflict' as const,
+    path,
+    status: 'already-exists' as const,
+  }),
+});
+```
+
+The mapper receives only the logical workspace path; provider errors, object
+keys, and mount coordinates are never exposed.
+
 This logical confinement is sufficient for a `ToolLoopAgent` whose only file
 capabilities are these tools. It cannot constrain a coding harness that already
 has shell, `node:fs`, or subprocess access. For Codex/Claude-style harnesses,
@@ -463,19 +532,36 @@ listStorageProviderSecretEnvVars('s3').map((variable) => variable.key);
 The catalog is pure data and pulls in no adapter, so it is safe in config UIs,
 health checks, and startup validation.
 
-The `s3` slug additionally carries the conditional-promotion and signed-policy
-capabilities described under
-[Race-free staged-object promotion](#race-free-staged-object-promotion); every
-other provider exposes exactly what its adapter declares. When the provider _is_
-known at build time, import `@nestm/storage/files-sdk/s3` or
-`@nestm/storage/files-sdk/fs` directly and skip the indirection.
+The `s3` slug additionally carries the verified per-operation profile and
+signed-policy capabilities described under
+[Exact provider conditions and staged-object promotion](#exact-provider-conditions-and-staged-object-promotion);
+every provider not backed by the AWS S3 SDK exposes what its adapter declares.
+When the provider _is_ known at build time, import
+`@nestm/storage/files-sdk/s3` or `@nestm/storage/files-sdk/fs` directly and skip
+the indirection.
+
+S3 endpoint and public-URL provenance is resolved from the adapter that
+`files-sdk` actually constructs, including values merged from `configJson`.
+An unaudited endpoint forces the driver read-only, and a `publicBaseUrl` removes
+the signed-download TTL guarantee because the resulting public URL does not
+expire. AWS-SDK-backed noncanonical provider slugs (for example an S3-compatible
+provider wrapper) also default to unverified/read-only; only the canonical
+`s3` provider may infer the native AWS profile, and a custom endpoint becomes
+writable only with an explicit branded `S3ProviderProfile`.
+
+Before enabling conditional operations for a custom S3-compatible endpoint,
+run the reusable
+[provider conformance contract](https://github.com/nestm-dev/storage/blob/main/docs/provider-conformance.md)
+against dedicated test credentials. Unknown endpoints are forced read-only and
+receive no inferred conditional capabilities.
 
 ## Storage API
 
 `StorageClient` exposes:
 
 - `upload`, `downloadStream`, `head`, `exists`, `delete`, `copy`, and `move`;
-- conditional staged-object `promote` when the driver advertises it;
+- exact `uploadConditional`, `downloadConditional`, `deleteConditional`, and
+  staged-object `promote` operations when the driver advertises each primitive;
 - `list`, cursor-aware `listAll`, and lazy `search`;
 - `signDownload` and discriminated PUT/POST `signUpload`;
 - `uploadMany`, `downloadMany`, `headMany`, `existsMany`, and `deleteMany`;
@@ -483,6 +569,24 @@ known at build time, import `@nestm/storage/files-sdk/s3` or
 - provider capability inspection; and
 - pause/resume/abort through `StorageUploadControl`.
 
+Provider list cursors are opaque, non-consuming continuation tokens. Replaying
+the same cursor and page limit against unchanged provider-visible state must
+return an equivalent page and continuation position, even after a descendant
+cursor has been used. A cursor is bound to the logical store, `prefix`, and
+`delimiter`, but not to `limit`, retries, timeout, or abort signal; callers may
+change those transport/page-size options while resuming the same position.
+
+The cursor must work through a newly constructed compatible driver targeting
+the same backend namespace while the provider token remains valid and
+available; it cannot depend on process-, client-, or session-local state. An
+adapter for a consuming or instance-bound provider token must materialize a
+stable continuation before it can provide conforming paginated
+`StorageDriver.list` results. This contract lets a caller safely retry, replay,
+or resume pagination on another replica. It does not promise a provider-token
+lifetime, snapshot isolation across concurrent mutations, or provider,
+network, credential, or authorization availability. Provider invalidation is
+an ordinary list-operation failure.
+
 Downloads are streaming by default:
 
 ```ts
@@ -505,11 +609,54 @@ Node `Readable` uploads are accepted and converted to Web streams without
 buffering. Provider capability gaps fail closed with `StorageError` rather than
 silently discarding a range, metadata, or cache-control request.
 
-### Race-free staged-object promotion
-
-The S3 bridge advertises ETag- and version-conditional server-side copy. This
-lets an application validate a staged object and copy that exact source to its
-final key instead of re-reading whichever bytes occupy the staging key later:
+### Exact provider conditions and staged-object promotion
+
+Capabilities distinguish conditional create, replace, delete, read, source
+copy, destination copy, atomic source-and-destination promotion, and multipart
+completion. They also declare the complete physical-key byte budget. Callers
+must check the exact primitive they need; a missing field is unsupported and is
+never widened from another operation.
+
+The physical-key budget applies to the exact key sent to the adapter. It
+therefore counts leading slashes for unprefixed drivers, the separator added to
+a configured driver prefix, and provider prefixes derived for `list` or
+`search`. Over-budget object keys and explicit list/search prefixes fail before
+provider dispatch rather than being normalized into a shorter key. A glob's
+provider prefix is the exact prefix inferred by files-sdk itself, and that
+derived list operation passes through the same final guard. A non-positive
+`maxResults` performs no provider walk and therefore dispatches no prefix.
+
+Adapters and plugins execute as trusted in-process code; this package does not
+attempt to sandbox a plugin that performs its own network or filesystem I/O.
+For supported plugin pipelines that forward operations through `next`, the
+physical-key guard is the innermost wrapper, after caller plugins and before
+the adapter call. A plugin therefore cannot widen an upload key or list/search
+prefix past the declared byte ceiling while still using the normal dispatch
+pipeline.
+
+Storage-facing ETags have one canonical representation: a bare, case-sensitive
+opaque token with no HTTP quotes. Canonical values contain 1–1024 visible
+ASCII bytes and exclude commas, backslashes, whitespace, control characters,
+`DEL`, non-ASCII text, the `*` wildcard, and case-insensitive `W/` weak-tag
+prefixes. Treat the value as opaque: preserve the exact string returned by
+`head`, reads, or writes and pass it back unchanged to a conditional operation.
+Do not add or remove quotes in application code. S3-compatible drivers remove
+exactly one valid provider-owned quote pair on ingress and add exactly one pair
+when serializing the HTTP header.
+
+This tightens the precondition boundary. Quoted or otherwise non-canonical
+ETags that older versions happened to accept now fail with `INVALID_ARGUMENT`,
+and an unsafe provider result fails with a sanitized `PROVIDER` error instead
+of being exposed as a usable validator. Applications that persisted quoted
+ETags must refresh them with `head` rather than trimming them heuristically.
+Strict normalization prevents a caller-controlled wildcard, entity-tag list,
+weak validator, or malformed header value from widening an operation that
+promises one exact strong match.
+
+The native AWS S3 profile advertises ETag- and version-conditioned server-side
+copy. This lets an application validate a staged object and copy that exact
+source to its final key instead of re-reading whichever bytes occupy the
+staging key later:
 
 ```ts
 import { StorageError, StorageErrorCode } from '@nestm/storage';
@@ -532,9 +679,58 @@ await media.delete(stagingKey);
 ```
 
 `sourceVersion` can select an immutable S3 version and may be combined with
-`sourceEtag`. A promotion without either identity is rejected. Drivers that do
-not publish `capabilities.conditionalCopy` fail with `NOT_SUPPORTED` rather
-than falling back to an unsafe ordinary copy.
+`sourceEtag`. A destination condition can independently require create-only or
+replacement of an exact ETag. Combining source and destination predicates also
+requires `capabilities.conditionalCopyDestination.atomicWithSource`; otherwise
+the request fails with `NOT_SUPPORTED`. A promotion must contain at least one
+source or destination predicate.
+
+Cloudflare R2 has a separate stable profile: create, replace, ETag-conditioned
+read, and ETag-conditioned source copy are enabled, while conditional delete,
+destination copy, atomic promotion, version predicates, and conditional
+multipart completion remain absent. R2 proves content-type binding for
+presigned PUT requests but not POST-form size ranges, so its signed-upload
+policy is `{ contentType: true, sizeRange: false }` and the gateway refuses to
+mint its POST upload form. Cloudflare documents that presigned `POST` form
+uploads are not supported in its
+[presigned URL contract](https://developers.cloudflare.com/r2/api/s3/presigned-urls/).
+Direct R2 signed-upload calls that request a size bound likewise fail with
+`NOT_SUPPORTED` before signing.
+Custom S3-compatible endpoints start with no conditional operations and the
+entire driver is forced read-only until an explicit conformance-verified
+`S3ProviderProfile` is supplied. Omitting `signedUploadPolicy` while defining a
+custom profile normalizes both policy claims to `false`; providers may opt in
+only to constraints their conformance evidence proves.
+
+Successful S3 signed uploads enforce every requested constraint. A request
+with `contentType` and no `maxSize` uses a presigned PUT whose signature
+includes the `content-type` header. A request with `maxSize` uses a POST policy
+with `content-length-range` and, when present, an exact `Content-Type`
+condition. S3 cannot express a lower-only `minSize` through this contract, so
+that shape fails with `NOT_SUPPORTED`; an unclaimed profile constraint also
+fails before credentials are resolved or a URL is minted. Literal physical
+keys ending in AWS's `${filename}` POST template are rejected for bounded
+uploads because the SDK otherwise widens the exact key condition to a prefix.
+
+`withS3Capabilities()` decorates a raw S3 adapter in place and may be applied
+only once. Construct a fresh raw adapter when selecting a different profile;
+reapplying the helper is rejected so a previous broader profile cannot survive
+a later narrower declaration. The selected profile is bound to the exact
+reserved capability and operation members installed by that decoration;
+same-client aliases may change display metadata but cannot add or replace those
+members to widen the profile.
+
+An explicit profile applied to a native AWS SDK endpoint may only narrow the
+immutable `AWS_S3_PROVIDER_PROFILE`. It cannot raise the complete-key budget
+above 1,024 bytes or claim an operation/policy bit absent from the built-in
+profile. This containment follows actual SDK endpoint provenance even when an
+adapter alias changes its display name.
+
+The package-owned `s3()` factory also retains whether `publicBaseUrl` was
+configured even when the second `withS3Capabilities()` options object is
+omitted. In that case `signedDownloadPolicy.expiresIn` is false. Foreign S3
+adapters whose construction metadata is unavailable receive the same
+conservative false value instead of claiming an enforceable TTL.
 
 ### Resumable uploads
 
@@ -676,8 +872,11 @@ by `maxSignedUploadBytes`, and require an exact lowercase MIME type from
 `attachment` or `inline` response disposition; arbitrary response-header text
 and filenames are rejected. A driver must also advertise
 `signedUploadPolicy.contentType` and `signedUploadPolicy.sizeRange`; otherwise
-the gateway refuses to mint the URL. `createS3StorageDriver()` advertises both
-and uses S3 POST policy conditions. Signed downloads similarly require
+the gateway refuses to mint the URL. Native AWS advertises both and uses S3
+POST policy conditions. R2 advertises content-type enforcement but not a POST
+size range, while omitted custom declarations normalize both claims to false;
+the gateway therefore fails closed for those profiles. Signed downloads
+similarly require
 `signedDownloadPolicy.expiresIn`. The S3 factory advertises it only when no
 permanent `publicBaseUrl` was configured, preventing a configured TTL from
 silently returning a non-expiring public link.

package/SECURITY.md

@@ -56,11 +56,40 @@ untrusted agent code. A tenant id, run id, prefix, provider cursor, snapshot id,
 or fork id supplied by a model is not a safe mount coordinate.
 
 The workspace accepts only canonical mount-relative POSIX paths and rechecks
-every key returned by a driver before unscoping it. Its cursors are opaque and
-bound to the mount and query. Permissions, byte limits, result limits, and
-conditional mutation preconditions are enforced inside the capability; tool
-omission and user approval are additional workflow controls, not the
-authorization boundary.
+every key returned by a driver before unscoping it. Pagination cursors are bound
+to the store, normalized physical prefix, stable mount identity, trusted
+tenant/workspace scope, operation, complete effective limits, normalized query,
+and expiry. Provider continuations and prefixes stay inside the encrypted or
+server-side payload. Both layers are non-consuming: a durable opaque token
+store must read rather than consume a record, and an embedded provider cursor
+must remain replayable through a fresh compatible driver against the same
+backend namespace while that provider cursor remains valid and available.
+Provider cursors cannot depend on process-local state; an adapter for a
+consuming or instance-bound backend token must materialize a stable continuation
+before exposing paginated `StorageDriver.list` results.
+
+Under unchanged provider-visible state, cursors are reusable while their
+provider continuation remains valid and available. The authenticated expiry is
+an authorization ceiling, not a guarantee of provider-token lifetime, snapshot
+isolation, provider/network availability, or valid credentials. Provider
+invalidation remains an operational failure, and concurrent mutations remain
+subject to provider ordering, duplicate, and omission semantics.
+
+Production pagination must configure either the built-in AES-256-GCM codec with
+a dedicated shared 32-byte key ring or an authenticated shared durable token
+store. Do not reuse an authentication, session, storage-provider, or encryption
+key from another purpose. All replicas must use the same stable identities and
+key ring, compatible driver configuration, and logical backend namespace. New
+cursors use the active key id; retain prior keys for at least the maximum cursor
+TTL during rotation. Dropping a key, changing a binding field, or restarting
+with a different ephemeral key intentionally invalidates outstanding cursors.
+Tokens and decoded payloads are bounded, and malformed, altered, expired,
+cross-query, cross-operation, cross-workspace, and cross-store cursors fail
+closed.
+
+Permissions, byte limits, result limits, and conditional mutation preconditions
+are enforced inside the capability; tool omission and user approval are
+additional workflow controls, not the authorization boundary.
 
 Conditional mutations can still have an ambiguous outcome when a remote
 provider commits and then loses or violates its response, or when a configured

package/dist/ai-sdk/ai-sdk-workspace-tools.d.ts

@@ -1,4 +1,4 @@
-import { type ToolSet } from 'ai';
+import { type JSONValue, type ToolSet } from 'ai';
 import { type StorageWorkspace } from '../workspace/index.js';
 import { type StorageErrorCode as StorageErrorCodeValue } from '../storage.error.js';
 export declare const AI_SDK_WORKSPACE_TOOL_NAMES: readonly ['workspace_list', 'workspace_stat', 'workspace_read_file', 'workspace_search', 'workspace_write_file', 'workspace_copy_file', 'workspace_move_file', 'workspace_delete_file'];
@@ -9,7 +9,12 @@ export type AiSdkWorkspaceMutationToolName = Extract<AiSdkWorkspaceToolName, 'wo
  * approval, matching an omitted policy.
  */
 export type AiSdkWorkspaceApprovalConfig = boolean | Partial<Record<AiSdkWorkspaceMutationToolName, boolean>>;
-export interface CreateAiSdkWorkspaceToolsOptions {
+export interface AiSdkWorkspaceCreateConflict {
+    /** The logical destination inside the mounted workspace. */
+    readonly path: string;
+}
+export type AiSdkWorkspaceCreateConflictMapper<Result extends JSONValue> = (conflict: AiSdkWorkspaceCreateConflict) => PromiseLike<Result> | Result;
+export interface CreateAiSdkWorkspaceToolsOptions<CreateConflictResult extends JSONValue = never> {
     /** The already-mounted, policy-enforcing workspace exposed to the tools. */
     workspace: StorageWorkspace;
     /**
@@ -19,6 +24,12 @@ export interface CreateAiSdkWorkspaceToolsOptions {
     maxReadBytes?: number;
     /** Mutation tools require approval by default. */
     requireApproval?: AiSdkWorkspaceApprovalConfig;
+    /**
+     * Maps an atomic create collision to an application result. When omitted,
+     * the collision remains an AiSdkWorkspaceToolError like every other storage
+     * failure. Replace conflicts are never mapped by this hook.
+     */
+    mapCreateConflict?: AiSdkWorkspaceCreateConflictMapper<CreateConflictResult>;
 }
 export type AiSdkWorkspaceToolErrorCode = StorageErrorCodeValue;
 /**
@@ -58,6 +69,6 @@ export interface AiSdkWorkspacePageResult {
  * The workspace remains the enforcing boundary if a retained tool reference
  * is invoked after further narrowing.
  */
-export declare function createAiSdkWorkspaceTools({ workspace, maxReadBytes: requestedMaxReadBytes, requireApproval, }: CreateAiSdkWorkspaceToolsOptions): ToolSet;
+export declare function createAiSdkWorkspaceTools<CreateConflictResult extends JSONValue = never>({ workspace, maxReadBytes: requestedMaxReadBytes, requireApproval, mapCreateConflict, }: CreateAiSdkWorkspaceToolsOptions<CreateConflictResult>): ToolSet;
 export declare function isAiSdkWorkspaceMutationToolName(value: string): value is AiSdkWorkspaceMutationToolName;
 //# sourceMappingURL=ai-sdk-workspace-tools.d.ts.map

package/dist/ai-sdk/ai-sdk-workspace-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ai-sdk-workspace-tools.d.ts","sourceRoot":"","sources":["../../src/ai-sdk/ai-sdk-workspace-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,OAAO,EAAE,MAAM,IAAI,CAAC;AAGxC,OAAO,EAEL,KAAK,gBAAgB,EAItB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAGL,KAAK,gBAAgB,IAAI,qBAAqB,EAC/C,MAAM,qBAAqB,CAAC;AAE7B,eAAO,MAAM,2BAA2B,YACtC,gBAAgB,EAChB,gBAAgB,EAChB,qBAAqB,EACrB,kBAAkB,EAClB,sBAAsB,EACtB,qBAAqB,EACrB,qBAAqB,EACrB,uBAAuB,CACf,CAAC;AAEX,MAAM,MAAM,sBAAsB,GAChC,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/C,MAAM,MAAM,8BAA8B,GAAG,OAAO,CAClD,sBAAsB,EACpB,sBAAsB,GACtB,qBAAqB,GACrB,qBAAqB,GACrB,uBAAuB,CAC1B,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,4BAA4B,GACtC,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,8BAA8B,EAAE,OAAO,CAAC,CAAC,CAAC;AAErE,MAAM,WAAW,gCAAgC;IAC/C,4EAA4E;IAC5E,SAAS,EAAE,gBAAgB,CAAC;IAC5B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kDAAkD;IAClD,eAAe,CAAC,EAAE,4BAA4B,CAAC;CAChD;AAED,MAAM,MAAM,2BAA2B,GAAG,qBAAqB,CAAC;AAsBhE;;;GAGG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,QAAQ,CAAC,IAAI,EAAE,2BAA2B,CAAC;IAE3C,YAAY,IAAI,EAAE,2BAA2B,EAI5C;CACF;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,6BAA6B;IAC5C,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,yBAAyB,GACnC,wBAAwB,GAAG,6BAA6B,CAAC;AAE3D,MAAM,WAAW,4BAA6B,SAAQ,wBAAwB;IAC5E,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,yBAAyB,EAAE,CAAC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AA2MD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,EACxC,SAAS,EACT,YAAY,EAAE,qBAAqB,EACnC,eAAsB,GACvB,EAAE,gCAAgC,GAAG,OAAO,CA2R5C;AAED,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,MAAM,GACZ,KAAK,IAAI,8BAA8B,CAEzC"}
+{"version":3,"file":"ai-sdk-workspace-tools.d.ts","sourceRoot":"","sources":["../../src/ai-sdk/ai-sdk-workspace-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,SAAS,EAAE,KAAK,OAAO,EAAE,MAAM,IAAI,CAAC;AAGxD,OAAO,EAGL,KAAK,gBAAgB,EAItB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAGL,KAAK,gBAAgB,IAAI,qBAAqB,EAC/C,MAAM,qBAAqB,CAAC;AAG7B,eAAO,MAAM,2BAA2B,YACtC,gBAAgB,EAChB,gBAAgB,EAChB,qBAAqB,EACrB,kBAAkB,EAClB,sBAAsB,EACtB,qBAAqB,EACrB,qBAAqB,EACrB,uBAAuB,CACf,CAAC;AAEX,MAAM,MAAM,sBAAsB,GAChC,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/C,MAAM,MAAM,8BAA8B,GAAG,OAAO,CAClD,sBAAsB,EACpB,sBAAsB,GACtB,qBAAqB,GACrB,qBAAqB,GACrB,uBAAuB,CAC1B,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,4BAA4B,GACtC,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,8BAA8B,EAAE,OAAO,CAAC,CAAC,CAAC;AAErE,MAAM,WAAW,4BAA4B;IAC3C,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,kCAAkC,CAAC,MAAM,SAAS,SAAS,IAAI,CACzE,QAAQ,EAAE,4BAA4B,KACnC,WAAW,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;AAElC,MAAM,WAAW,gCAAgC,CAC/C,oBAAoB,SAAS,SAAS,GAAG,KAAK;IAE9C,4EAA4E;IAC5E,SAAS,EAAE,gBAAgB,CAAC;IAC5B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kDAAkD;IAClD,eAAe,CAAC,EAAE,4BAA4B,CAAC;IAC/C;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,kCAAkC,CAAC,oBAAoB,CAAC,CAAC;CAC9E;AAED,MAAM,MAAM,2BAA2B,GAAG,qBAAqB,CAAC;AAsBhE;;;GAGG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,QAAQ,CAAC,IAAI,EAAE,2BAA2B,CAAC;IAE3C,YAAY,IAAI,EAAE,2BAA2B,EAI5C;CACF;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,6BAA6B;IAC5C,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,yBAAyB,GACnC,wBAAwB,GAAG,6BAA6B,CAAC;AAE3D,MAAM,WAAW,4BAA6B,SAAQ,wBAAwB;IAC5E,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,yBAAyB,EAAE,CAAC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AA2OD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,oBAAoB,SAAS,SAAS,GAAG,KAAK,EAC9C,EACA,SAAS,EACT,YAAY,EAAE,qBAAqB,EACnC,eAAsB,EACtB,iBAAiB,GAClB,EAAE,gCAAgC,CAAC,oBAAoB,CAAC,GAAG,OAAO,CA6SlE;AAED,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,MAAM,GACZ,KAAK,IAAI,8BAA8B,CAEzC"}