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

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @nestm/storage
 
+## 0.1.0-alpha.9
+
+### Minor Changes
+
+- aec25d6: Add explicit last-write-wins workspace write, copy, and unconditional-delete
+  operations that traverse the ordinary Files SDK plugin, hook, and receipt
+  pipeline while retaining the existing native conditional create, replace,
+  copy, move, and delete variants. Unconditional delete requires both `write` and
+  `delete`; move remains conditional-only because a non-atomic
+  download/upload/delete sequence could delete a newer source generation. Add a
+  separate `write` permission and an AI tool factory mutation-mode switch whose
+  default remains conditional.
+
+  Add bounded binary workspace reads through `readBytes`, alongside the existing
+  UTF-8 `readText` API. `readBytes` is a required `StorageWorkspace` member, so
+  custom interface implementations and typed test doubles must add it when
+  upgrading; workspaces returned by `mountStorageWorkspace` need no changes.
+
+### Patch Changes
+
+- 37e0d8d: Fail conditional storage operations closed when caller-configured Files SDK
+  plugins, hooks, or receipts would be bypassed by native adapter extensions.
+  Ordinary operations continue through Files SDK while incompatible conditional
+  capabilities are hidden until Files SDK exposes one shared interception boundary.
+
 ## 0.1.0-alpha.8
 
 ### Minor Changes

package/README.md

@@ -167,6 +167,7 @@ const workspace = mountStorageWorkspace(agentFiles, {
     'list',
     'read',
     'search',
+    'write',
     'create',
     'replace',
     'copy',
@@ -199,8 +200,16 @@ await workspace.writeFile('src/main.ts', 'export const ready = false;\n', {
   etag: created.etag,
   contentType: 'text/typescript',
 });
+
+const image = await workspace.readBytes('assets/logo.png');
+console.log(image.bytes.byteLength);
 ```
 
+`readBytes` is now a required member of the exported `StorageWorkspace`
+interface. Workspaces returned by `mountStorageWorkspace` provide it
+automatically; custom implementations and typed test doubles must add the
+method when adopting this alpha minor.
+
 Create, replace, and delete are conditional operations. A driver that cannot
 enforce the requested not-exists or ETag precondition fails with
 `NOT_SUPPORTED`; the workspace never substitutes an `exists()`/`head()` check
@@ -215,6 +224,32 @@ the call returns `CONFLICT`; inspect both logical paths before retrying. This
 preserves at least one copy across provider timeouts and post-operation hook
 failures, but does not pretend a multi-object move is transactionally atomic.
 
+Callers that prefer the ordinary Files pipeline can opt into explicit
+last-write-wins variants. The `write` permission is separate from conditional
+`create` and `replace` authority:
+
+```ts
+await workspace.writeFile('notes.txt', 'latest contents', {
+  mode: 'overwrite',
+});
+await workspace.copyFile('notes.txt', 'backup.txt', { mode: 'overwrite' });
+await workspace.deleteFile('backup.txt', { mode: 'unconditional' });
+```
+
+Overwrite copy reads the latest source through the ordinary download pipeline,
+enforces `maxWriteBytes` while collecting it, and uploads it through the
+ordinary upload pipeline. It never substitutes the provider's server-side
+copy. These paths compose with Files SDK plugins, hooks, and receipts, including
+the built-in `encryption()` plugin. That plugin is useful compatibility
+evidence, not an Artifact-specific security policy: strict encrypted-only
+reads, tenant/path-bound AAD, key custody and rotation, and copy/move rules
+remain application-owned.
+
+Move remains conditional-only. A last-write-wins download/upload/delete
+sequence could copy one source generation and then delete a newer generation
+written during the transfer. Use the ETag-conditional `moveFile` variant when a
+move is required.
+
 A child mount may further restrict a directory, permissions, or limits, but it
 cannot widen any of them:
 
@@ -275,6 +310,7 @@ import type { ToolSet } from 'ai';
                   'list',
                   'read',
                   'search',
+                  'write',
                   'create',
                   'replace',
                   'copy',
@@ -312,6 +348,13 @@ 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.
 
+`mutationMode` defaults to `'conditional'`. A trusted composition can instead
+select `{ mutationMode: 'last-write-wins' }`; generated mutation schemas then
+omit ETags and modes, hardcode the explicit overwrite/unconditional workspace
+variants, and require `write` permission for destination mutations.
+Unconditional delete requires both `write` and `delete`. The move tool is
+omitted in last-write-wins mode because Workspace move remains conditional-only.
+
 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:
@@ -328,7 +371,8 @@ const tools = createAiSdkWorkspaceTools({
 ```
 
 The mapper receives only the logical workspace path; provider errors, object
-keys, and mount coordinates are never exposed.
+keys, and mount coordinates are never exposed. `mapCreateConflict` is valid
+only in conditional mode and is rejected with last-write-wins mode.
 
 This logical confinement is sufficient for a `ToolLoopAgent` whose only file
 capabilities are these tools. It cannot constrain a coding harness that already
@@ -555,6 +599,47 @@ run the reusable
 against dedicated test credentials. Unknown endpoints are forced read-only and
 receive no inferred conditional capabilities.
 
+## Files SDK responsibility boundary
+
+Files SDK is the upstream authority for the generic storage data plane:
+provider adapters, generic CRUD, bulk and list operations, retries, transfers
+and sync, its plugin pipeline, and framework-neutral gateway mechanics.
+`@nestm/storage` retains the guarantees that Files SDK does not currently
+provide: NestJS 12 named stores, exact native conditional/CAS capabilities,
+`StorageWorkspace` permissions and limits, bounded storage errors, and
+capability-scoped AI tools.
+
+On the alpha.8 base, ordinary `FilesSdkStorageDriver` operations already
+delegate to the Files SDK pipeline. The exception is the native conditional
+adapter extensions: the current Files SDK operation union does not include
+them, so they cannot run through caller-configured Files plugins, hooks, or
+receipts. Until Files SDK provides one interception boundary for ordinary and
+conditional operations, the driver applies this interim fail-closed
+compatibility rule:
+
+| Caller Files configuration                        | Ordinary operations                  | Conditional operations                                   |
+| ------------------------------------------------- | ------------------------------------ | -------------------------------------------------------- |
+| No plugins, active hooks, or receipts             | Files pipeline                       | Advertised when the adapter supports the exact primitive |
+| One or more plugins                               | Files pipeline, including transforms | Hidden; direct invocation returns `NOT_SUPPORTED`        |
+| Any active hook                                   | Files pipeline and hook callbacks    | Hidden; direct invocation returns `NOT_SUPPORTED`        |
+| Receipts enabled with `true` or an options object | Files pipeline and receipts          | Hidden; direct invocation returns `NOT_SUPPORTED`        |
+
+An empty plugin list, an empty hooks object, and `receipts: false` do not trigger
+the gate. NestM's internal physical-key guard does not trigger it either. When
+available, direct conditional paths independently apply prefixing, the
+physical-key budget, mutation read-only restrictions, default
+retry/signal/timeout options, and bounded error mapping. `StoragePlugin` remains
+a separate veto/observation boundary; it is not a substitute for Files body or
+result transforms. This compatibility gate is intended to be removed once
+native CAS can traverse the upstream operation and plugin pipeline rather than
+becoming a second generic CRUD facade here.
+
+`StorageWorkspace` therefore exposes both contracts without weakening either:
+its existing create/replace, exact-read copy/move, and conditional-delete paths
+retain native CAS and this fail-closed gate, while explicit overwrite and
+unconditional-delete variants use the ordinary Files pipeline. Lower-level
+conditional client and driver APIs remain available to callers that need them.
+
 ## Storage API
 
 `StorageClient` exposes:

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

@@ -9,6 +9,7 @@ export type AiSdkWorkspaceMutationToolName = Extract<AiSdkWorkspaceToolName, 'wo
  * approval, matching an omitted policy.
  */
 export type AiSdkWorkspaceApprovalConfig = boolean | Partial<Record<AiSdkWorkspaceMutationToolName, boolean>>;
+export type AiSdkWorkspaceMutationMode = 'conditional' | 'last-write-wins';
 export interface AiSdkWorkspaceCreateConflict {
     /** The logical destination inside the mounted workspace. */
     readonly path: string;
@@ -24,10 +25,16 @@ export interface CreateAiSdkWorkspaceToolsOptions<CreateConflictResult extends J
     maxReadBytes?: number;
     /** Mutation tools require approval by default. */
     requireApproval?: AiSdkWorkspaceApprovalConfig;
+    /**
+     * Selects the mutation contract exposed to the model. Conditional mode is
+     * the default; last-write-wins uses the workspace's ordinary Files path.
+     */
+    mutationMode?: AiSdkWorkspaceMutationMode;
     /**
      * 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.
+     * failure. Replace conflicts are never mapped by this hook. This option is
+     * valid only when mutationMode is conditional.
      */
     mapCreateConflict?: AiSdkWorkspaceCreateConflictMapper<CreateConflictResult>;
 }
@@ -69,6 +76,6 @@ export interface AiSdkWorkspacePageResult {
  * The workspace remains the enforcing boundary if a retained tool reference
  * is invoked after further narrowing.
  */
-export declare function createAiSdkWorkspaceTools<CreateConflictResult extends JSONValue = never>({ workspace, maxReadBytes: requestedMaxReadBytes, requireApproval, mapCreateConflict, }: CreateAiSdkWorkspaceToolsOptions<CreateConflictResult>): ToolSet;
+export declare function createAiSdkWorkspaceTools<CreateConflictResult extends JSONValue = never>({ workspace, maxReadBytes: requestedMaxReadBytes, mutationMode, 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,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"}
+{"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,MAAM,0BAA0B,GAAG,aAAa,GAAG,iBAAiB,CAAC;AAE3E,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;;;OAGG;IACH,YAAY,CAAC,EAAE,0BAA0B,CAAC;IAC1C;;;;;OAKG;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,YAA4B,EAC5B,eAAsB,EACtB,iBAAiB,GAClB,EAAE,gCAAgC,CAAC,oBAAoB,CAAC,GAAG,OAAO,CAmYlE;AAED,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,MAAM,GACZ,KAAK,IAAI,8BAA8B,CAEzC"}

package/dist/ai-sdk/ai-sdk-workspace-tools.js

@@ -16,7 +16,7 @@ export const AI_SDK_WORKSPACE_TOOL_NAMES = [
 const SAFE_ERROR_MESSAGES = {
     [StorageErrorCode.NOT_FOUND]: 'The requested workspace path was not found.',
     [StorageErrorCode.UNAUTHORIZED]: 'This operation is not permitted in the workspace.',
-    [StorageErrorCode.CONFLICT]: 'The operation conflicts with current workspace state. Refresh metadata and retry with the current ETag or a new destination.',
+    [StorageErrorCode.CONFLICT]: 'The operation conflicts with current workspace state. Inspect the affected paths before retrying.',
     [StorageErrorCode.READ_ONLY]: 'This operation is not permitted in the workspace.',
     [StorageErrorCode.INVALID_ARGUMENT]: 'The workspace tool input was rejected.',
     [StorageErrorCode.NOT_SUPPORTED]: 'This workspace operation is not supported by the configured storage.',
@@ -210,7 +210,13 @@ function serializePage(page) {
  * The workspace remains the enforcing boundary if a retained tool reference
  * is invoked after further narrowing.
  */
-export function createAiSdkWorkspaceTools({ workspace, maxReadBytes: requestedMaxReadBytes, requireApproval = true, mapCreateConflict, }) {
+export function createAiSdkWorkspaceTools({ workspace, maxReadBytes: requestedMaxReadBytes, mutationMode = 'conditional', requireApproval = true, mapCreateConflict, }) {
+    if (mutationMode !== 'conditional' && mutationMode !== 'last-write-wins') {
+        throw new RangeError('mutationMode must be "conditional" or "last-write-wins".');
+    }
+    if (mutationMode === 'last-write-wins' && mapCreateConflict !== undefined) {
+        throw new RangeError('mapCreateConflict is available only in conditional mutation mode.');
+    }
     const maxReadBytes = resolveReadLimit(workspace, requestedMaxReadBytes);
     const tools = {};
     const pathSchema = logicalPath('File path', workspace.limits.maxPathBytes);
@@ -248,7 +254,9 @@ export function createAiSdkWorkspaceTools({ workspace, maxReadBytes: requestedMa
     }
     if (workspace.allows('read')) {
         tools.workspace_stat = tool({
-            description: 'Inspect a file inside the mounted workspace without reading its contents. Returns the ETag required for safe replace, move, and delete operations.',
+            description: mutationMode === 'conditional'
+                ? 'Inspect a file inside the mounted workspace without reading its contents. Returns the ETag required for safe replace, move, and delete operations.'
+                : 'Inspect a file inside the mounted workspace without reading its contents. Any returned ETag is informational in last-write-wins mode.',
             strict: true,
             inputSchema: z.object({ path: pathSchema }).strict(),
             execute: ({ path }, { abortSignal }) => executeSafely(abortSignal, async () => serializeFile(await workspace.stat(path, operationOptions(abortSignal)))),
@@ -291,62 +299,96 @@ export function createAiSdkWorkspaceTools({ workspace, maxReadBytes: requestedMa
             }))),
         });
     }
-    const canCreate = workspace.allows('create');
-    const canReplace = workspace.allows('replace');
-    if (canCreate || canReplace) {
-        const commonWriteShape = {
-            path: pathSchema,
-            content: z
-                .string()
-                .refine((value) => utf8Encoder.encode(value).byteLength <=
-                workspace.limits.maxWriteBytes, {
-                message: `Content exceeds the ${workspace.limits.maxWriteBytes}-byte workspace write limit.`,
-            })
-                .describe(`UTF-8 text to write. The workspace enforces its ${workspace.limits.maxWriteBytes}-byte write limit.`),
-        };
-        const createSchema = z
-            .object({ ...commonWriteShape, mode: z.literal('create') })
-            .strict();
-        const replaceSchema = z
-            .object({
-            ...commonWriteShape,
-            mode: z.literal('replace'),
-            etag: etagSchema,
+    const commonWriteShape = {
+        path: pathSchema,
+        content: z
+            .string()
+            .refine((value) => utf8Encoder.encode(value).byteLength <=
+            workspace.limits.maxWriteBytes, {
+            message: `Content exceeds the ${workspace.limits.maxWriteBytes}-byte workspace write limit.`,
         })
-            .strict();
-        const inputSchema = canCreate && canReplace
-            ? z.discriminatedUnion('mode', [createSchema, replaceSchema])
-            : canCreate
-                ? createSchema
-                : replaceSchema;
+            .describe(`UTF-8 text to write. The workspace enforces its ${workspace.limits.maxWriteBytes}-byte write limit.`),
+    };
+    if (mutationMode === 'last-write-wins' && workspace.allows('write')) {
+        const inputSchema = z.object(commonWriteShape).strict();
         tools.workspace_write_file = tool({
-            description: canCreate && canReplace
-                ? 'Create a new UTF-8 text file or replace an existing file inside the mounted workspace. Create fails if the destination exists; replace requires its current ETag.'
-                : canCreate
-                    ? 'Create a new UTF-8 text file inside the mounted workspace. The operation fails if the destination already exists.'
-                    : 'Replace an existing UTF-8 text file inside the mounted workspace using its current ETag.',
-            // The combined create/replace schema is a discriminated union. OpenAI
-            // strict function tools reject its root-level oneOf, while the runtime
-            // Zod schema continues to validate every tool call in non-strict mode.
-            strict: !(canCreate && canReplace),
+            description: 'Write a UTF-8 text file inside the mounted workspace. An existing destination is overwritten; the last successful writer wins.',
+            strict: true,
             inputSchema,
             needsApproval: resolveApproval('workspace_write_file', requireApproval),
-            execute: (input, { abortSignal }) => executeCreateAware(abortSignal, input, async () => serializeFile(input.mode === 'create'
-                ? await workspace.writeFile(input.path, input.content, {
-                    mode: 'create',
-                    ...operationOptions(abortSignal),
-                })
-                : await workspace.writeFile(input.path, input.content, {
-                    mode: 'replace',
-                    etag: input.etag,
-                    ...operationOptions(abortSignal),
-                })), mapCreateConflict),
+            execute: ({ path, content }, { abortSignal }) => executeSafely(abortSignal, async () => serializeFile(await workspace.writeFile(path, content, {
+                mode: 'overwrite',
+                ...operationOptions(abortSignal),
+            }))),
         });
     }
-    const canCopy = workspace.allows('copy') &&
-        workspace.allows('read') &&
-        workspace.allows('create');
-    if (canCopy) {
+    else if (mutationMode === 'conditional') {
+        const canCreate = workspace.allows('create');
+        const canReplace = workspace.allows('replace');
+        if (canCreate || canReplace) {
+            const createSchema = z
+                .object({ ...commonWriteShape, mode: z.literal('create') })
+                .strict();
+            const replaceSchema = z
+                .object({
+                ...commonWriteShape,
+                mode: z.literal('replace'),
+                etag: etagSchema,
+            })
+                .strict();
+            const inputSchema = canCreate && canReplace
+                ? z.discriminatedUnion('mode', [createSchema, replaceSchema])
+                : canCreate
+                    ? createSchema
+                    : replaceSchema;
+            tools.workspace_write_file = tool({
+                description: canCreate && canReplace
+                    ? 'Create a new UTF-8 text file or replace an existing file inside the mounted workspace. Create fails if the destination exists; replace requires its current ETag.'
+                    : canCreate
+                        ? 'Create a new UTF-8 text file inside the mounted workspace. The operation fails if the destination already exists.'
+                        : 'Replace an existing UTF-8 text file inside the mounted workspace using its current ETag.',
+                // The combined create/replace schema is a discriminated union. OpenAI
+                // strict function tools reject its root-level oneOf, while the runtime
+                // Zod schema continues to validate every tool call in non-strict mode.
+                strict: !(canCreate && canReplace),
+                inputSchema,
+                needsApproval: resolveApproval('workspace_write_file', requireApproval),
+                execute: (input, { abortSignal }) => executeCreateAware(abortSignal, input, async () => serializeFile(input.mode === 'create'
+                    ? await workspace.writeFile(input.path, input.content, {
+                        mode: 'create',
+                        ...operationOptions(abortSignal),
+                    })
+                    : await workspace.writeFile(input.path, input.content, {
+                        mode: 'replace',
+                        etag: input.etag,
+                        ...operationOptions(abortSignal),
+                    })), mapCreateConflict),
+            });
+        }
+    }
+    const canCopy = workspace.allows('copy') && workspace.allows('read');
+    if (mutationMode === 'last-write-wins' &&
+        canCopy &&
+        workspace.allows('write')) {
+        tools.workspace_copy_file = tool({
+            description: 'Copy the latest readable contents of a file inside the mounted workspace. The source remains intact, and an existing destination is overwritten.',
+            strict: true,
+            inputSchema: z
+                .object({
+                source: logicalPath('Source file path', workspace.limits.maxPathBytes),
+                destination: logicalPath('Destination file path', workspace.limits.maxPathBytes),
+            })
+                .strict(),
+            needsApproval: resolveApproval('workspace_copy_file', requireApproval),
+            execute: ({ source, destination }, { abortSignal }) => executeSafely(abortSignal, async () => serializeFile(await workspace.copyFile(source, destination, {
+                mode: 'overwrite',
+                ...operationOptions(abortSignal),
+            }))),
+        });
+    }
+    else if (mutationMode === 'conditional' &&
+        canCopy &&
+        workspace.allows('create')) {
         tools.workspace_copy_file = tool({
             description: 'Copy an exact observed version of a file inside the mounted workspace. The source remains intact, and the operation fails if the source changed or the destination already exists.',
             strict: true,
@@ -364,11 +406,11 @@ export function createAiSdkWorkspaceTools({ workspace, maxReadBytes: requestedMa
             }))),
         });
     }
-    const canMove = workspace.allows('move') &&
+    if (mutationMode === 'conditional' &&
+        workspace.allows('move') &&
         workspace.allows('read') &&
-        workspace.allows('create') &&
-        workspace.allows('delete');
-    if (canMove) {
+        workspace.allows('delete') &&
+        workspace.allows('create')) {
         tools.workspace_move_file = tool({
             description: "Move a file inside the mounted workspace using the source's current ETag. The operation fails if the destination already exists. If source deletion cannot be confirmed, the destination is retained and the tool reports a conflict; inspect both paths before retrying.",
             strict: true,
@@ -386,7 +428,24 @@ export function createAiSdkWorkspaceTools({ workspace, maxReadBytes: requestedMa
             }))),
         });
     }
-    if (workspace.allows('delete')) {
+    if (mutationMode === 'last-write-wins' &&
+        workspace.allows('delete') &&
+        workspace.allows('write')) {
+        tools.workspace_delete_file = tool({
+            description: 'Unconditionally delete the current file at a path inside the mounted workspace.',
+            strict: true,
+            inputSchema: z.object({ path: pathSchema }).strict(),
+            needsApproval: resolveApproval('workspace_delete_file', requireApproval),
+            execute: ({ path }, { abortSignal }) => executeSafely(abortSignal, async () => {
+                await workspace.deleteFile(path, {
+                    mode: 'unconditional',
+                    ...operationOptions(abortSignal),
+                });
+                return { deleted: true, path };
+            }),
+        });
+    }
+    else if (mutationMode === 'conditional' && workspace.allows('delete')) {
         tools.workspace_delete_file = tool({
             description: 'Delete a file inside the mounted workspace using its current ETag.',
             strict: true,