@nestm/storage 0.1.0-alpha.1 → 0.1.0-alpha.11

package/SECURITY.md

@@ -23,3 +23,131 @@ cross-store pruning, or dependency compromise are especially useful.
 For a vulnerability originating in NestJS, `files-sdk`, or a provider SDK,
 follow that project's security policy as well. You may still report it here
 privately when this integration needs a mitigation.
+
+## Gateway security boundary
+
+Mounting the optional HTTP gateway requires both authentication guards and a
+`StorageGatewayKeyPolicy`. The policy receives parsed paths and must derive the
+provider key space from trusted request context. Do not treat a client prefix
+or object key as a tenant identifier. `unsafeAllowUnscopedKeys` exists only to
+migrate trusted single-tenant deployments and is unsafe on an exposed gateway.
+
+Signed URL expiry, signed-upload byte size, and signed-upload MIME are bounded
+by module configuration and cannot be increased by a request. Only `inline`
+and `attachment` content dispositions are accepted. File type still must be
+verified from magic bytes after upload; a signed MIME condition proves only
+what header the uploader supplied. The gateway rejects signed-upload drivers
+that do not advertise provider-enforced content-type and size-range policies.
+It also rejects download adapters that cannot guarantee the requested expiry;
+in particular, the S3 bridge does not treat `publicBaseUrl` links as expiring.
+
+For staged uploads on S3, use `promote`/`promoteTo` with the ETag returned by
+the validated `head` or with an immutable provider version. Ordinary `copy`
+does not protect against a staging-key replay between validation and copy.
+Conditional promotion keeps the staging source; delete it only after the
+application's metadata transaction commits.
+
+## Workspace security boundary
+
+Durable file workflows use opaque host scopes and explicit persistence ports.
+The host must reauthorize `transaction`'s `permission` on every call, including
+idempotent replay, and serialize the scope's draft state across replicas. Head
+predicates, all head changes, and committed draft receipts must share one
+rollback-capable host transaction. Streamed object preparation is outside that
+transaction; the package does not make object-store writes multi-file atomic.
+Provider/network response loss can remain ambiguous. Reconcile by replaying the
+durable request; do not infer rollback from an abort or lost response.
+
+Construct protected catalog/workflow handles from the same trusted host scope,
+bind their execution signal, and keep storage clients and persistence ports
+private. The protector rechecks fresh authorization and composes caller aborts;
+the host transaction independently rechecks authority at commit.
+Workflow restrictions check each persisted draft's create/replace intent on
+mutation and replay; they cannot widen grants, limits or detach parent abort.
+The checks do not depend on a public draft-read permission. Product-only
+feature closures must capture these same checks when the handle is acquired.
+The structural catalog/workflow getters do not authenticate untrusted objects.
+
+Staged bodies use native create-only writes and exact ETag reads. Integrity
+receipts verify full draft chunks during assembly. Conditional body removal is
+available only as a host-invoked primitive: references, eligibility and cleanup
+races are host-owned. Never delete a body merely because a commit request failed
+or timed out; another in-flight or committed request may reference it. The
+memory adapter is volatile and its raw Map is a trusted escape hatch, not an
+authorization boundary.
+
+`StorageWorkspace` is a narrowing capability for storage operations. Construct
+it from trusted application context, keep the underlying `StorageClient` and
+mount prefix private, and pass only the workspace or its AI tool set to
+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. 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
+post-operation plugin fails after the driver has committed. Known post-commit
+failures report `StorageError.applied === true`; a conditional upload also
+carries `appliedEtag` when its committed generation is known. This is positive
+evidence, not a complete remote-commit oracle: a timeout, connection loss, or
+exhausted retry can lose a provider success response and still leave
+`applied === false`. Do not reissue an ambiguous predicate blindly. Reconcile
+the logical destination first, using an exact ETag read when `appliedEtag` is
+available and inspecting the relevant source/destination state for copy or
+delete. Create-only and ETag preconditions prevent a blind retry from silently
+overwriting a different object, but they cannot make a multi-object move
+transactionally atomic.
+
+This guarantee covers calls made through `StorageWorkspace`. It does not
+confine arbitrary `node:fs`, shell, subprocess, or native-code access in the
+same process. A coding harness with built-in shell or filesystem tools must run
+inside an OS sandbox (container, VM, or equivalent) that exposes only a
+materialized workspace. Setting `cwd` to a workspace directory is not
+isolation.
+
+For local filesystem storage, use a dedicated service-owned root and route all
+in-process mutations through the package-decorated adapter; its ordinary and
+conditional mutation paths share one lock domain. A separate process,
+unwrapped adapter, or direct filesystem writer can bypass that coordination and
+must not mutate the tree concurrently. High-level Node filesystem checks reject
+symlinks and hard-linked object files in existing workspace read and mutation
+paths, including metadata sidecars, but cannot provide a race-proof boundary
+against an actor that can replace path components between validation and use.
+For that threat model, mount only the workspace into a separate
+UID/container/VM and synchronize approved results back through storage. The
+local adapter also commits the body and metadata sidecar as two files; a process
+crash between their atomic renames can require reconciliation.

package/dist/ai-sdk/ai-sdk-file-workflow-tools.d.ts

@@ -0,0 +1,37 @@
+import { type ToolSet } from 'ai';
+import { z } from 'zod';
+import type { StorageFileCatalogCapability, StorageFileWorkflowCapability } from '../workspace/index.js';
+export interface CreateAiSdkFileWorkflowToolsOptions<Receipt> {
+    readonly workflow: StorageFileWorkflowCapability<Receipt>;
+    readonly requireApproval?: boolean;
+    /** Host-generated token, scoped and stable across replay of this tool call. */
+    readonly idempotencyKey?: (toolCallId: string) => string;
+    readonly maxChunkBytes?: number;
+}
+export interface CreateAiSdkCatalogFileToolsOptions<Receipt> {
+    readonly catalog: StorageFileCatalogCapability<Receipt>;
+    readonly requireApproval?: boolean;
+    readonly commandId?: (toolCallId: string) => string;
+    readonly maxWriteBytes?: number;
+}
+export declare const AI_SDK_FILE_WORKFLOW_TOOL_NAMES: readonly ['workspace_begin_file_draft', 'workspace_append_file_draft', 'workspace_list_file_drafts', 'workspace_read_file_draft', 'workspace_list_file_draft_parts', 'workspace_cancel_file_draft', 'workspace_commit_files'];
+export declare const AI_SDK_CATALOG_FILE_TOOL_NAMES: readonly ['workspace_list', 'workspace_stat', 'workspace_search', 'workspace_read_file', 'workspace_search_content', 'workspace_write_file', 'workspace_append_file', 'workspace_edit_file'];
+/** Typed extension seam for host-only metadata; preserves generic byte validation. */
+export declare function createAiSdkCatalogFileEditSchemas(maxWriteBytes?: number): {
+    append: z.ZodObject<{
+        path: z.ZodString;
+        expectedEtag: z.ZodString;
+        content: z.ZodString;
+    }, z.core.$strict>;
+    edit: z.ZodObject<{
+        path: z.ZodString;
+        expectedEtag: z.ZodString;
+        oldText: z.ZodString;
+        newText: z.ZodString;
+    }, z.core.$strict>;
+};
+/** Generic durable-file tools. Provider upload controls are a separate capability. */
+export declare function createAiSdkFileWorkflowTools<Receipt>(options: CreateAiSdkFileWorkflowToolsOptions<Receipt>): ToolSet;
+/** Catalog-backed alternative to the existing raw-workspace tool factory. */
+export declare function createAiSdkCatalogFileTools<Receipt>(options: CreateAiSdkCatalogFileToolsOptions<Receipt>): ToolSet;
+//# sourceMappingURL=ai-sdk-file-workflow-tools.d.ts.map

package/dist/ai-sdk/ai-sdk-file-workflow-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-sdk-file-workflow-tools.d.ts","sourceRoot":"","sources":["../../src/ai-sdk/ai-sdk-file-workflow-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,OAAO,EAAE,MAAM,IAAI,CAAC;AACxC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EACV,4BAA4B,EAC5B,6BAA6B,EAC9B,MAAM,uBAAuB,CAAC;AAG/B,MAAM,WAAW,mCAAmC,CAAC,OAAO;IAC1D,QAAQ,CAAC,QAAQ,EAAE,6BAA6B,CAAC,OAAO,CAAC,CAAC;IAC1D,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,+EAA+E;IAC/E,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,CAAC;IACzD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AACD,MAAM,WAAW,kCAAkC,CAAC,OAAO;IACzD,QAAQ,CAAC,OAAO,EAAE,4BAA4B,CAAC,OAAO,CAAC,CAAC;IACxD,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,CAAC;IACpD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AACD,eAAO,MAAM,+BAA+B,YAC1C,4BAA4B,EAC5B,6BAA6B,EAC7B,4BAA4B,EAC5B,2BAA2B,EAC3B,iCAAiC,EACjC,6BAA6B,EAC7B,wBAAwB,CAChB,CAAC;AACX,eAAO,MAAM,8BAA8B,YACzC,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,qBAAqB,EACrB,0BAA0B,EAC1B,sBAAsB,EACtB,uBAAuB,EACvB,qBAAqB,CACb,CAAC;AAuCX,sFAAsF;AACtF,wBAAgB,iCAAiC,CAAC,aAAa,SAAO;IAGlE,MAAM;;;;;IACN,IAAI;;;;;;EAOP;AAED,sFAAsF;AACtF,wBAAgB,4BAA4B,CAAC,OAAO,EAClD,OAAO,EAAE,mCAAmC,CAAC,OAAO,CAAC,GACpD,OAAO,CA6GT;AAED,6EAA6E;AAC7E,wBAAgB,2BAA2B,CAAC,OAAO,EACjD,OAAO,EAAE,kCAAkC,CAAC,OAAO,CAAC,GACnD,OAAO,CAgIT"}

package/dist/ai-sdk/ai-sdk-file-workflow-tools.js

@@ -0,0 +1,258 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+import { isStorageError } from '../storage.error.js';
+import { AiSdkWorkspaceToolError } from './ai-sdk-workspace-tools.js';
+export const AI_SDK_FILE_WORKFLOW_TOOL_NAMES = [
+    'workspace_begin_file_draft',
+    'workspace_append_file_draft',
+    'workspace_list_file_drafts',
+    'workspace_read_file_draft',
+    'workspace_list_file_draft_parts',
+    'workspace_cancel_file_draft',
+    'workspace_commit_files',
+];
+export const AI_SDK_CATALOG_FILE_TOOL_NAMES = [
+    'workspace_list',
+    'workspace_stat',
+    'workspace_search',
+    'workspace_read_file',
+    'workspace_search_content',
+    'workspace_write_file',
+    'workspace_append_file',
+    'workspace_edit_file',
+];
+const offset = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+const identity = z.string().min(1).max(256);
+const etag = z.string().min(1).max(1024);
+const path = z.string().min(1).max(1024);
+const page = { offset: offset.default(0) };
+function textSchema(maxBytes) {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1)
+        throw new TypeError('Text tool limit must be a positive safe integer.');
+    return z
+        .string()
+        .max(maxBytes)
+        .refine((text) => !/[\uD800-\uDFFF]/u.test(text), 'Text must be well-formed UTF-8.')
+        .refine((text) => new TextEncoder().encode(text).byteLength <= maxBytes, `Use at most ${maxBytes} UTF-8 bytes per call.`);
+}
+async function safe(work) {
+    try {
+        return await work();
+    }
+    catch (error) {
+        if (isStorageError(error))
+            throw new AiSdkWorkspaceToolError(error.code, {
+                applied: error.applied,
+                ...(error.appliedEtag === undefined
+                    ? {}
+                    : { appliedEtag: error.appliedEtag }),
+            });
+        if (error instanceof DOMException && error.name === 'AbortError')
+            throw new AiSdkWorkspaceToolError('ABORTED');
+        throw new AiSdkWorkspaceToolError('PROVIDER');
+    }
+}
+/** Typed extension seam for host-only metadata; preserves generic byte validation. */
+export function createAiSdkCatalogFileEditSchemas(maxWriteBytes = 8192) {
+    const content = textSchema(maxWriteBytes);
+    return {
+        append: z.strictObject({ path, expectedEtag: etag, content }),
+        edit: z.strictObject({
+            path,
+            expectedEtag: etag,
+            oldText: content.refine((text) => text.length > 0),
+            newText: content,
+        }),
+    };
+}
+/** Generic durable-file tools. Provider upload controls are a separate capability. */
+export function createAiSdkFileWorkflowTools(options) {
+    const { workflow } = options;
+    const tools = {};
+    const content = textSchema(Math.min(options.maxChunkBytes ?? 8192, workflow.limits.maxChunkBytes));
+    const approval = options.requireApproval ?? true;
+    if (workflow.allows('read'))
+        Object.assign(tools, {
+            workspace_list_file_drafts: tool({
+                description: 'List durable drafts. Resume open drafts at their current UTF-8 byte size; use nextOffset for pagination.',
+                inputSchema: z.strictObject(page),
+                execute: (input, context) => safe(() => workflow.list({ ...input, signal: context.abortSignal })),
+            }),
+            workspace_read_file_draft: tool({
+                description: `Read a draft window of at most ${workflow.limits.maxReadBytes} UTF-8 bytes. Continue with nextOffset, which is a byte position at a Unicode boundary.`,
+                inputSchema: z.strictObject({ draftId: identity, ...page }),
+                execute: (input, context) => safe(() => workflow.read({ ...input, signal: context.abortSignal })),
+            }),
+            workspace_list_file_draft_parts: tool({
+                description: 'List bounded chunk integrity receipts for resumption. Each receipt contains its byte offset, size, and SHA-256.',
+                inputSchema: z.strictObject({ draftId: identity, ...page }),
+                execute: (input, context) => safe(() => workflow.parts({ ...input, signal: context.abortSignal })),
+            }),
+        });
+    if (workflow.allows('write'))
+        Object.assign(tools, {
+            workspace_begin_file_draft: tool({
+                strict: false,
+                needsApproval: approval,
+                description: 'Begin a durable text draft without changing a visible file. Omit expectedEtag to create a new path; supply the exact current ETag to replace. Use drafts for substantial content and resume interrupted drafts.',
+                inputSchema: z.strictObject({ path, expectedEtag: etag.optional() }),
+                execute: (input, context) => safe(() => workflow.begin({
+                    ...input,
+                    text: true,
+                    idempotencyKey: options.idempotencyKey?.(context.toolCallId) ??
+                        context.toolCallId,
+                    signal: context.abortSignal,
+                })),
+            }),
+            workspace_append_file_draft: tool({
+                needsApproval: approval,
+                description: 'Append a bounded UTF-8 chunk at the draft’s returned byte size. Replaying identical bytes at the same offset is safe; different bytes or a stale offset fail.',
+                inputSchema: z.strictObject({
+                    draftId: identity,
+                    offset,
+                    content: content.refine((text) => text.length > 0),
+                }),
+                execute: (input, context) => safe(() => workflow.append({
+                    draftId: input.draftId,
+                    offset: input.offset,
+                    bytes: new TextEncoder().encode(input.content),
+                    signal: context.abortSignal,
+                })),
+            }),
+            workspace_cancel_file_draft: tool({
+                needsApproval: approval,
+                description: 'Cancel an unfinished draft without changing a visible file. A committed draft cannot be cancelled.',
+                inputSchema: z.strictObject({ draftId: identity }),
+                execute: (input, context) => safe(() => workflow.cancel({ ...input, signal: context.abortSignal })),
+            }),
+        });
+    if (workflow.allows('commit'))
+        tools.workspace_commit_files = tool({
+            strict: false,
+            needsApproval: approval,
+            description: `Atomically commit 1–${workflow.limits.maxCommitFiles} distinct completed drafts. Supply exact byte sizes. Optional SHA-256 must be known, never invented. A stale head rolls the whole batch back; replay returns stored receipts.`,
+            inputSchema: z.strictObject({
+                drafts: z
+                    .array(z.strictObject({
+                    draftId: identity,
+                    size: offset,
+                    sha256: z
+                        .string()
+                        .regex(/^[0-9a-f]{64}$/u)
+                        .optional(),
+                }))
+                    .min(1)
+                    .max(workflow.limits.maxCommitFiles),
+            }),
+            execute: (input, context) => safe(async () => ({
+                items: await workflow.commit({
+                    ...input,
+                    signal: context.abortSignal,
+                }),
+            })),
+        });
+    return Object.freeze(tools);
+}
+/** Catalog-backed alternative to the existing raw-workspace tool factory. */
+export function createAiSdkCatalogFileTools(options) {
+    const { catalog } = options;
+    const tools = {};
+    const content = textSchema(Math.min(options.maxWriteBytes ?? 8192, catalog.limits.maxWriteBytes));
+    const editSchemas = createAiSdkCatalogFileEditSchemas(Math.min(options.maxWriteBytes ?? 8192, catalog.limits.maxWriteBytes));
+    const approval = options.requireApproval ?? true;
+    const commandId = options.commandId ?? ((toolCallId) => toolCallId);
+    if (catalog.allows('read'))
+        Object.assign(tools, {
+            workspace_list: tool({
+                strict: false,
+                description: 'List authorized file catalog entries. Paths are mount-relative. Continue with nextOffset.',
+                inputSchema: z.strictObject({
+                    directory: z.string().optional(),
+                    ...page,
+                }),
+                execute: (input, context) => safe(() => catalog.list({ ...input, signal: context.abortSignal })),
+            }),
+            workspace_stat: tool({
+                description: 'Read a file identity, ETag, size and content type without loading its body.',
+                inputSchema: z.strictObject({ path }),
+                execute: (input, context) => safe(() => catalog.stat({ ...input, signal: context.abortSignal })),
+            }),
+            workspace_search: tool({
+                description: 'Search file paths by literal substring. Continue with nextOffset even when a page has no matches.',
+                inputSchema: z.strictObject({
+                    query: z.string().min(1).max(256),
+                    ...page,
+                }),
+                execute: (input, context) => safe(() => catalog.search({ ...input, signal: context.abortSignal })),
+            }),
+            workspace_read_file: tool({
+                strict: false,
+                description: `Read at most ${catalog.limits.maxReadBytes} UTF-8 bytes. offset/nextOffset are byte positions at Unicode boundaries. Continue with nextOffset and the same expectedEtag.`,
+                inputSchema: z.strictObject({
+                    path,
+                    expectedEtag: etag.optional(),
+                    ...page,
+                }),
+                execute: (input, context) => safe(() => catalog.readWindow({ ...input, signal: context.abortSignal })),
+            }),
+            workspace_search_content: tool({
+                strict: false,
+                description: `Search literal text in one exact file revision. Scan at most ${catalog.limits.maxSearchScanBytes} bytes per call. Continue with nextOffset and the same expectedEtag.`,
+                inputSchema: z.strictObject({
+                    path,
+                    expectedEtag: etag,
+                    query: z.string().min(1).max(256),
+                    ...page,
+                }),
+                execute: (input, context) => safe(() => catalog.searchContent({ ...input, signal: context.abortSignal })),
+            }),
+        });
+    if (catalog.allows('write'))
+        Object.assign(tools, {
+            workspace_write_file: tool({
+                strict: false,
+                needsApproval: approval,
+                description: 'Create or conditionally replace a small UTF-8 file. Omit expectedEtag to create; supply the exact current ETag to replace. Use durable drafts for substantial content.',
+                inputSchema: z.strictObject({
+                    path,
+                    expectedEtag: etag.optional(),
+                    content,
+                }),
+                execute: (input, context) => safe(() => catalog.write({
+                    ...input,
+                    commandId: commandId(context.toolCallId),
+                    signal: context.abortSignal,
+                })),
+            }),
+            workspace_append_file: tool({
+                needsApproval: approval,
+                description: 'Append a bounded UTF-8 chunk to one exact file revision. Pass the latest ETag; retry identity prevents duplicate appends. Durable drafts support large generation.',
+                inputSchema: editSchemas.append,
+                execute: (input, context) => safe(() => catalog.edit({
+                    path: input.path,
+                    expectedEtag: input.expectedEtag,
+                    change: { kind: 'append', text: input.content },
+                    commandId: commandId(context.toolCallId),
+                    signal: context.abortSignal,
+                })),
+            }),
+            workspace_edit_file: tool({
+                needsApproval: approval,
+                description: 'Replace one exact unique text span at the latest expectedEtag. oldText must match exactly once. The result carries the next revision receipt.',
+                inputSchema: editSchemas.edit,
+                execute: (input, context) => safe(() => catalog.edit({
+                    path: input.path,
+                    expectedEtag: input.expectedEtag,
+                    change: {
+                        kind: 'replace',
+                        oldText: input.oldText,
+                        newText: input.newText,
+                    },
+                    commandId: commandId(context.toolCallId),
+                    signal: context.abortSignal,
+                })),
+            }),
+        });
+    return Object.freeze(tools);
+}
+//# sourceMappingURL=ai-sdk-file-workflow-tools.js.map

package/dist/ai-sdk/ai-sdk-file-workflow-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-sdk-file-workflow-tools.js","sourceRoot":"","sources":["../../src/ai-sdk/ai-sdk-file-workflow-tools.ts"],"names":[],"mappings":"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","sourcesContent":["import { tool, type ToolSet } from 'ai';\nimport { z } from 'zod';\nimport { isStorageError } from '../storage.error.js';\nimport type {\n  StorageFileCatalogCapability,\n  StorageFileWorkflowCapability,\n} from '../workspace/index.js';\nimport { AiSdkWorkspaceToolError } from './ai-sdk-workspace-tools.js';\n\nexport interface CreateAiSdkFileWorkflowToolsOptions<Receipt> {\n  readonly workflow: StorageFileWorkflowCapability<Receipt>;\n  readonly requireApproval?: boolean;\n  /** Host-generated token, scoped and stable across replay of this tool call. */\n  readonly idempotencyKey?: (toolCallId: string) => string;\n  readonly maxChunkBytes?: number;\n}\nexport interface CreateAiSdkCatalogFileToolsOptions<Receipt> {\n  readonly catalog: StorageFileCatalogCapability<Receipt>;\n  readonly requireApproval?: boolean;\n  readonly commandId?: (toolCallId: string) => string;\n  readonly maxWriteBytes?: number;\n}\nexport const AI_SDK_FILE_WORKFLOW_TOOL_NAMES = [\n  'workspace_begin_file_draft',\n  'workspace_append_file_draft',\n  'workspace_list_file_drafts',\n  'workspace_read_file_draft',\n  'workspace_list_file_draft_parts',\n  'workspace_cancel_file_draft',\n  'workspace_commit_files',\n] as const;\nexport const AI_SDK_CATALOG_FILE_TOOL_NAMES = [\n  'workspace_list',\n  'workspace_stat',\n  'workspace_search',\n  'workspace_read_file',\n  'workspace_search_content',\n  'workspace_write_file',\n  'workspace_append_file',\n  'workspace_edit_file',\n] as const;\n\nconst offset = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);\nconst identity = z.string().min(1).max(256);\nconst etag = z.string().min(1).max(1024);\nconst path = z.string().min(1).max(1024);\nconst page = { offset: offset.default(0) };\nfunction textSchema(maxBytes: number) {\n  if (!Number.isSafeInteger(maxBytes) || maxBytes < 1)\n    throw new TypeError('Text tool limit must be a positive safe integer.');\n  return z\n    .string()\n    .max(maxBytes)\n    .refine(\n      (text) => !/[\\uD800-\\uDFFF]/u.test(text),\n      'Text must be well-formed UTF-8.',\n    )\n    .refine(\n      (text) => new TextEncoder().encode(text).byteLength <= maxBytes,\n      `Use at most ${maxBytes} UTF-8 bytes per call.`,\n    );\n}\nasync function safe<Result>(work: () => Promise<Result>): Promise<Result> {\n  try {\n    return await work();\n  } catch (error) {\n    if (isStorageError(error))\n      throw new AiSdkWorkspaceToolError(error.code, {\n        applied: error.applied,\n        ...(error.appliedEtag === undefined\n          ? {}\n          : { appliedEtag: error.appliedEtag }),\n      });\n    if (error instanceof DOMException && error.name === 'AbortError')\n      throw new AiSdkWorkspaceToolError('ABORTED');\n    throw new AiSdkWorkspaceToolError('PROVIDER');\n  }\n}\n\n/** Typed extension seam for host-only metadata; preserves generic byte validation. */\nexport function createAiSdkCatalogFileEditSchemas(maxWriteBytes = 8192) {\n  const content = textSchema(maxWriteBytes);\n  return {\n    append: z.strictObject({ path, expectedEtag: etag, content }),\n    edit: z.strictObject({\n      path,\n      expectedEtag: etag,\n      oldText: content.refine((text) => text.length > 0),\n      newText: content,\n    }),\n  };\n}\n\n/** Generic durable-file tools. Provider upload controls are a separate capability. */\nexport function createAiSdkFileWorkflowTools<Receipt>(\n  options: CreateAiSdkFileWorkflowToolsOptions<Receipt>,\n): ToolSet {\n  const { workflow } = options;\n  const tools: ToolSet = {};\n  const content = textSchema(\n    Math.min(options.maxChunkBytes ?? 8192, workflow.limits.maxChunkBytes),\n  );\n  const approval = options.requireApproval ?? true;\n  if (workflow.allows('read'))\n    Object.assign(tools, {\n      workspace_list_file_drafts: tool({\n        description:\n          'List durable drafts. Resume open drafts at their current UTF-8 byte size; use nextOffset for pagination.',\n        inputSchema: z.strictObject(page),\n        execute: (input, context) =>\n          safe(() => workflow.list({ ...input, signal: context.abortSignal })),\n      }),\n      workspace_read_file_draft: tool({\n        description: `Read a draft window of at most ${workflow.limits.maxReadBytes} UTF-8 bytes. Continue with nextOffset, which is a byte position at a Unicode boundary.`,\n        inputSchema: z.strictObject({ draftId: identity, ...page }),\n        execute: (input, context) =>\n          safe(() => workflow.read({ ...input, signal: context.abortSignal })),\n      }),\n      workspace_list_file_draft_parts: tool({\n        description:\n          'List bounded chunk integrity receipts for resumption. Each receipt contains its byte offset, size, and SHA-256.',\n        inputSchema: z.strictObject({ draftId: identity, ...page }),\n        execute: (input, context) =>\n          safe(() => workflow.parts({ ...input, signal: context.abortSignal })),\n      }),\n    } satisfies ToolSet);\n  if (workflow.allows('write'))\n    Object.assign(tools, {\n      workspace_begin_file_draft: tool({\n        strict: false,\n        needsApproval: approval,\n        description:\n          'Begin a durable text draft without changing a visible file. Omit expectedEtag to create a new path; supply the exact current ETag to replace. Use drafts for substantial content and resume interrupted drafts.',\n        inputSchema: z.strictObject({ path, expectedEtag: etag.optional() }),\n        execute: (input, context) =>\n          safe(() =>\n            workflow.begin({\n              ...input,\n              text: true,\n              idempotencyKey:\n                options.idempotencyKey?.(context.toolCallId) ??\n                context.toolCallId,\n              signal: context.abortSignal,\n            }),\n          ),\n      }),\n      workspace_append_file_draft: tool({\n        needsApproval: approval,\n        description:\n          'Append a bounded UTF-8 chunk at the draft’s returned byte size. Replaying identical bytes at the same offset is safe; different bytes or a stale offset fail.',\n        inputSchema: z.strictObject({\n          draftId: identity,\n          offset,\n          content: content.refine((text) => text.length > 0),\n        }),\n        execute: (input, context) =>\n          safe(() =>\n            workflow.append({\n              draftId: input.draftId,\n              offset: input.offset,\n              bytes: new TextEncoder().encode(input.content),\n              signal: context.abortSignal,\n            }),\n          ),\n      }),\n      workspace_cancel_file_draft: tool({\n        needsApproval: approval,\n        description:\n          'Cancel an unfinished draft without changing a visible file. A committed draft cannot be cancelled.',\n        inputSchema: z.strictObject({ draftId: identity }),\n        execute: (input, context) =>\n          safe(() =>\n            workflow.cancel({ ...input, signal: context.abortSignal }),\n          ),\n      }),\n    } satisfies ToolSet);\n  if (workflow.allows('commit'))\n    tools.workspace_commit_files = tool({\n      strict: false,\n      needsApproval: approval,\n      description: `Atomically commit 1–${workflow.limits.maxCommitFiles} distinct completed drafts. Supply exact byte sizes. Optional SHA-256 must be known, never invented. A stale head rolls the whole batch back; replay returns stored receipts.`,\n      inputSchema: z.strictObject({\n        drafts: z\n          .array(\n            z.strictObject({\n              draftId: identity,\n              size: offset,\n              sha256: z\n                .string()\n                .regex(/^[0-9a-f]{64}$/u)\n                .optional(),\n            }),\n          )\n          .min(1)\n          .max(workflow.limits.maxCommitFiles),\n      }),\n      execute: (input, context) =>\n        safe(async () => ({\n          items: await workflow.commit({\n            ...input,\n            signal: context.abortSignal,\n          }),\n        })),\n    });\n  return Object.freeze(tools);\n}\n\n/** Catalog-backed alternative to the existing raw-workspace tool factory. */\nexport function createAiSdkCatalogFileTools<Receipt>(\n  options: CreateAiSdkCatalogFileToolsOptions<Receipt>,\n): ToolSet {\n  const { catalog } = options;\n  const tools: ToolSet = {};\n  const content = textSchema(\n    Math.min(options.maxWriteBytes ?? 8192, catalog.limits.maxWriteBytes),\n  );\n  const editSchemas = createAiSdkCatalogFileEditSchemas(\n    Math.min(options.maxWriteBytes ?? 8192, catalog.limits.maxWriteBytes),\n  );\n  const approval = options.requireApproval ?? true;\n  const commandId = options.commandId ?? ((toolCallId: string) => toolCallId);\n  if (catalog.allows('read'))\n    Object.assign(tools, {\n      workspace_list: tool({\n        strict: false,\n        description:\n          'List authorized file catalog entries. Paths are mount-relative. Continue with nextOffset.',\n        inputSchema: z.strictObject({\n          directory: z.string().optional(),\n          ...page,\n        }),\n        execute: (input, context) =>\n          safe(() => catalog.list({ ...input, signal: context.abortSignal })),\n      }),\n      workspace_stat: tool({\n        description:\n          'Read a file identity, ETag, size and content type without loading its body.',\n        inputSchema: z.strictObject({ path }),\n        execute: (input, context) =>\n          safe(() => catalog.stat({ ...input, signal: context.abortSignal })),\n      }),\n      workspace_search: tool({\n        description:\n          'Search file paths by literal substring. Continue with nextOffset even when a page has no matches.',\n        inputSchema: z.strictObject({\n          query: z.string().min(1).max(256),\n          ...page,\n        }),\n        execute: (input, context) =>\n          safe(() => catalog.search({ ...input, signal: context.abortSignal })),\n      }),\n      workspace_read_file: tool({\n        strict: false,\n        description: `Read at most ${catalog.limits.maxReadBytes} UTF-8 bytes. offset/nextOffset are byte positions at Unicode boundaries. Continue with nextOffset and the same expectedEtag.`,\n        inputSchema: z.strictObject({\n          path,\n          expectedEtag: etag.optional(),\n          ...page,\n        }),\n        execute: (input, context) =>\n          safe(() =>\n            catalog.readWindow({ ...input, signal: context.abortSignal }),\n          ),\n      }),\n      workspace_search_content: tool({\n        strict: false,\n        description: `Search literal text in one exact file revision. Scan at most ${catalog.limits.maxSearchScanBytes} bytes per call. Continue with nextOffset and the same expectedEtag.`,\n        inputSchema: z.strictObject({\n          path,\n          expectedEtag: etag,\n          query: z.string().min(1).max(256),\n          ...page,\n        }),\n        execute: (input, context) =>\n          safe(() =>\n            catalog.searchContent({ ...input, signal: context.abortSignal }),\n          ),\n      }),\n    } satisfies ToolSet);\n  if (catalog.allows('write'))\n    Object.assign(tools, {\n      workspace_write_file: tool({\n        strict: false,\n        needsApproval: approval,\n        description:\n          'Create or conditionally replace a small UTF-8 file. Omit expectedEtag to create; supply the exact current ETag to replace. Use durable drafts for substantial content.',\n        inputSchema: z.strictObject({\n          path,\n          expectedEtag: etag.optional(),\n          content,\n        }),\n        execute: (input, context) =>\n          safe<unknown>(() =>\n            catalog.write({\n              ...input,\n              commandId: commandId(context.toolCallId),\n              signal: context.abortSignal,\n            }),\n          ),\n      }),\n      workspace_append_file: tool({\n        needsApproval: approval,\n        description:\n          'Append a bounded UTF-8 chunk to one exact file revision. Pass the latest ETag; retry identity prevents duplicate appends. Durable drafts support large generation.',\n        inputSchema: editSchemas.append,\n        execute: (input, context) =>\n          safe<unknown>(() =>\n            catalog.edit({\n              path: input.path,\n              expectedEtag: input.expectedEtag,\n              change: { kind: 'append', text: input.content },\n              commandId: commandId(context.toolCallId),\n              signal: context.abortSignal,\n            }),\n          ),\n      }),\n      workspace_edit_file: tool({\n        needsApproval: approval,\n        description:\n          'Replace one exact unique text span at the latest expectedEtag. oldText must match exactly once. The result carries the next revision receipt.',\n        inputSchema: editSchemas.edit,\n        execute: (input, context) =>\n          safe<unknown>(() =>\n            catalog.edit({\n              path: input.path,\n              expectedEtag: input.expectedEtag,\n              change: {\n                kind: 'replace',\n                oldText: input.oldText,\n                newText: input.newText,\n              },\n              commandId: commandId(context.toolCallId),\n              signal: context.abortSignal,\n            }),\n          ),\n      }),\n    } satisfies ToolSet);\n  return Object.freeze(tools);\n}\n"]}

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

@@ -0,0 +1,91 @@
+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'];
+export type AiSdkWorkspaceToolName = (typeof AI_SDK_WORKSPACE_TOOL_NAMES)[number];
+export type AiSdkWorkspaceMutationToolName = Extract<AiSdkWorkspaceToolName, 'workspace_write_file' | 'workspace_copy_file' | 'workspace_move_file' | 'workspace_delete_file'>;
+/**
+ * Approval policy for mutation tools. An omitted entry defaults to requiring
+ * 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;
+}
+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;
+    /**
+     * Optional tighter read ceiling. Values above the workspace ceiling are
+     * clamped; the model cannot choose or raise this value.
+     */
+    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. This option is
+     * valid only when mutationMode is conditional.
+     */
+    mapCreateConflict?: AiSdkWorkspaceCreateConflictMapper<CreateConflictResult>;
+}
+export type AiSdkWorkspaceToolErrorCode = StorageErrorCodeValue;
+export interface AiSdkWorkspaceToolErrorOptions {
+    /** True when the failed operation may already have committed. */
+    readonly applied?: boolean;
+    /** Canonical ETag of the committed object, when the provider returned one. */
+    readonly appliedEtag?: string;
+}
+/**
+ * Safe error exposed at the AI tool boundary. It deliberately carries no
+ * provider error, storage key, mount prefix, store name, or cause. Applied
+ * reconciliation metadata is retained so callers do not blindly retry a
+ * mutation that may already have committed.
+ */
+export declare class AiSdkWorkspaceToolError extends Error {
+    readonly code: AiSdkWorkspaceToolErrorCode;
+    readonly applied?: true;
+    readonly appliedEtag?: string;
+    constructor(code: AiSdkWorkspaceToolErrorCode, options?: AiSdkWorkspaceToolErrorOptions);
+}
+export interface AiSdkWorkspaceFileResult {
+    kind: 'file';
+    path: string;
+    name: string;
+    size: number;
+    contentType: string;
+    etag?: string;
+    lastModified?: string;
+}
+export interface AiSdkWorkspaceDirectoryResult {
+    kind: 'directory';
+    path: string;
+    name: string;
+}
+export type AiSdkWorkspaceEntryResult = AiSdkWorkspaceFileResult | AiSdkWorkspaceDirectoryResult;
+export interface AiSdkWorkspaceTextFileResult extends AiSdkWorkspaceFileResult {
+    text: string;
+}
+export interface AiSdkWorkspacePageResult {
+    entries: AiSdkWorkspaceEntryResult[];
+    cursor?: string;
+}
+/**
+ * Creates Vercel AI SDK tools backed only by a mounted StorageWorkspace.
+ *
+ * A tool is omitted unless the workspace grants its required permission.
+ * 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, 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

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