@nestm/storage 0.1.0-alpha.10 → 0.1.0-alpha.12

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @nestm/storage
 
+## 0.1.0-alpha.12
+
+### Patch Changes
+
+- 009a0ed: Add optional `/crypto` encrypted staged content coordination over FileCipherEngine, with host-owned addressing, AAD, persistence and reference-protected cleanup. Preserve detached metadata preparation, exact physical acknowledgements, immutable ETag reads, authenticated ranges and cancellation. Trusted staged writers can reserve an identity before metadata preparation with `writeReserved`.
+
+## 0.1.0-alpha.11
+
+### Minor Changes
+
+- 9c5f230: Add framework-neutral durable file workflows with immutable integrity-checked
+  staged bodies, bounded UTF-8 reads/search, idempotent chunk appends, and explicit
+  host transaction ports for atomic multi-file head commits. Add protected catalog
+  and draft capabilities and generic tools in the existing optional AI SDK entrypoint.
+
+  Add a browser-safe bytes entrypoint for verified upload resumption and UTF-8
+  chunk boundaries. Preserve the default memory driver with native conditional
+  create/replace/read/delete, evaluated atomically after body consumption, and
+  canonical SHA-256 ETags. Memory remains volatile and process-local.
+
 ## 0.1.0-alpha.10
 
 ### Minor Changes

package/README.md

@@ -375,6 +375,159 @@ materialize the workspace into a per-session container or VM, mount only that
 directory, run the harness there, and synchronize reviewed changes back through
 `StorageWorkspace`. A working directory alone is not a sandbox.
 
+## Durable file workflows and catalog tools
+
+`@nestm/storage` owns byte mechanics and the draft state machine. The host owns
+logical file heads, authorization, persistence and transaction atomicity. No
+database, NestJS, tenant model or runtime lease is required by these contracts.
+
+| Entry point                | Exports                                                                                                                                                                                     |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@nestm/storage/core`      | `StorageStagedContentStore`, `collectStorageBytes`, `storageBytesStream`, `readStorageTextWindow`, `searchStorageText`, `applyStorageTextEdit` and their types                              |
+| `@nestm/storage/workspace` | `StorageFileWorkflow`, draft/persistence/catalog contracts, `protectStorageFileWorkflowWorkspace`, `protectStorageFileWorkflowOperation`, `getStorageFileWorkflow`, `getStorageFileCatalog` |
+| `@nestm/storage/ai-sdk`    | `createAiSdkFileWorkflowTools`, `createAiSdkCatalogFileTools`, their options and tool-name constants; existing `createAiSdkWorkspaceTools` is unchanged                                     |
+| `@nestm/storage/bytes`     | Browser-safe `sha256StorageBytes`, `verifyStorageChunkReceipt`, `trimStorageUtf8Chunk`, `encodeStorageBase64`, `isStorageUtf8Blob`                                                          |
+
+```ts
+import { StorageStagedContentStore } from '@nestm/storage/core';
+import {
+  StorageFileWorkflow,
+  protectStorageFileWorkflowWorkspace,
+} from '@nestm/storage/workspace';
+import {
+  createAiSdkCatalogFileTools,
+  createAiSdkFileWorkflowTools,
+} from '@nestm/storage/ai-sdk';
+
+// These values are supplied by the host, never by the model.
+const content = new StorageStagedContentStore({
+  client,
+  key: (scope: HostScope, payloadId) => hostBodyKey(scope, payloadId),
+});
+const workflows = new StorageFileWorkflow({ content, persistence });
+const workspace = protectStorageFileWorkflowWorkspace({
+  workspace: hostCatalogWorkspace,
+  catalog: hostCatalog,
+  workflows: workflows.mount(trustedScope, {
+    permissions: ['read', 'write', 'commit'],
+    signal: executionSignal,
+  }),
+  signal: executionSignal,
+  authorize: ({ permission, signal }) =>
+    authorizeCurrentHostScope(trustedScope, permission, signal),
+});
+const tools = {
+  ...createAiSdkCatalogFileTools({
+    catalog: workspace.catalog!,
+    commandId: (toolCallId) => hostCommandId(toolCallId),
+  }),
+  ...createAiSdkFileWorkflowTools({
+    workflow: workspace.workflows,
+    idempotencyKey: (toolCallId) => hostCommandId(toolCallId),
+  }),
+};
+```
+
+The catalog delegate implements the existing `StorageWorkspace` against the
+host's logical catalog; do not pass a raw provider-prefix workspace alongside
+an unrelated file service. `StorageFileCatalogCapability` adds opaque file IDs,
+byte windows, literal content search and idempotent small write/edit commands.
+Its `commandId` is host-scoped, stable across retries, and compared against a
+canonical request fingerprint in host persistence. The host preserves its
+additional policy when a generic edit targets a specialized file.
+
+`createAiSdkCatalogFileEditSchemas(maxWriteBytes)` exposes typed append/edit
+Zod objects used by the generic factory itself. A host can `.extend()` these
+with an optional product-only metadata field while retaining the same UTF-8
+byte rules. Delegate ordinary input to the generic tool; dispatch specialized
+input through the same leased product capability and command identity. Do not
+cast an opaque tool schema or rebuild the generic schema locally.
+
+The protector retains the lease/caller signal and reauthorizes every call.
+Create-only base grants cannot replace or edit a catalog file. Workflow
+`restrict({ permissions, mutations, limits, signal })` intersects existing
+grants/ceilings and retains parent cancellation; it never changes scope. The
+protector restricts persisted draft mutations to the base create/replace grants,
+including resumed sealed drafts and replay, without requiring a public read
+grant to perform an otherwise authorized commit. Child mounts do
+not inherit broader catalog/workflow handles. Configure both delegates with the
+same scope and compatible limits; the host catalog must enforce scan budgets
+inside its implementation. Structured extensions on the returned workspace
+are supported: owning features can attach protected product closures while
+retaining the same `.catalog` and `.workflows` members. The structural getters
+are contract checks for trusted handles, not authentication of arbitrary objects.
+These static file operations acquire no lease themselves.
+
+### Host persistence transaction
+
+Implement `StorageFileWorkflowPersistence<Scope, Receipt>.transaction(scope,
+{ permission, signal }, work)`. On **every** call (including replay and body
+preparation reads), reauthorize that intent and serialize the scope's draft and
+idempotency records across replicas. `read` admits readers; `write` and `commit`
+must enforce the host's mutation authority. The callback receives detached
+records through `findDraftByKey`, `getDraft`, `saveDraft`, `listDrafts`,
+`listParts`, `putPart` and `commitHeads`.
+
+`commitHeads` receives sorted `{ draft, body }` changes. It must compare every
+create/expected-ETag predicate and change all logical heads **in the same host
+transaction** as the subsequent committed draft records and receipts. Return
+one non-null receipt per change in the supplied order. A rejection rolls back
+all callback effects. Serial object writes or independently committed database
+calls do not satisfy this port. The package does not claim to implement database
+atomicity. See the packed consumer fixture and filesystem e2e test for executable
+minimal hosts; production hosts need their own cross-replica transaction/locking
+implementation and rollback tests.
+
+Drafts transition `open → sealed → committed` or `open/sealed → cancelled`.
+Appends accept a bounded snapshot of bytes at the exact current byte offset.
+Identical offset/size/SHA-256 replay succeeds; changed bytes or gaps conflict.
+Text chunks must contain complete valid UTF-8. Public summaries and part receipts
+omit staged body IDs and provider keys. A commit seals all requested drafts,
+streams verified chunks into immutable bodies, then commits all heads and draft
+receipts in one host transaction. Failed preparation or stale heads leave sealed
+drafts retryable/cancellable. Mixed committed/uncommitted batches conflict;
+replaying an entirely committed batch returns its stored receipts after checking
+the requested size and optional digest. Cancellation cannot undo committed heads.
+
+Check the signal before durable transaction commit. After commit, return the
+receipt even if cancellation races the response. Do not automatically retry the
+transaction callback. A lost response requires replay/reconciliation, not an
+assumption of rollback. Provider writes happen before the metadata transaction;
+failures, losing concurrent preparations, cancellations and superseded files can
+leave unreferenced bodies. Retention eligibility, reference tracking and cleanup
+scheduling remain host-owned. `StorageStagedContentStore.remove` performs an
+ETag-conditional deletion only after the host proves eligibility; it is not a
+collector and is never called automatically by the workflow.
+
+### Byte and provider guarantees
+
+Staging requires native create-only writes that return an ETag and native exact
+ETag reads; byte ranges additionally require `rangeRead`. Missing primitives
+fail with `NOT_SUPPORTED`, without an existence-check/unconditional-write or
+full-download fallback. Files SDK remains the provider, streaming, range and
+conditional-policy engine. Its multipart upload controls remain distinct from
+the host-persisted draft protocol; it does not provide atomic catalog commits.
+The bundled filesystem and memory drivers and verified native S3 profiles
+support staging. Memory stores are process-local and volatile; their conditional
+comparison/publication is synchronous after asynchronous body consumption.
+Memory publications use canonical SHA-256 ETags. Direct raw-map mutation remains
+a trusted testing escape hatch, outside protected workspace authority.
+
+Windows count UTF-8 bytes, use inclusive provider range ends and preserve BOMs.
+Offsets splitting a character and malformed/truncated UTF-8 at EOF fail. Search
+budgets include the actual requested bytes; follow `nextOffset` even on an empty
+match page. `applyStorageTextEdit` works on an already buffered string, requires a
+result byte ceiling and rejects non-unique replacement targets; it is not a
+streaming document editor. Model text appends default to 8192 bytes per call,
+clamped to the capability. Mutation tools require approval by default; hosts may
+apply an existing approval policy explicitly.
+
+The browser bytes entrypoint imports no Node, provider, NestJS or AI modules.
+`verifyStorageChunkReceipt(blob, receipt, { offset, maxBytes, signal })` verifies
+ordering, bounds and the actual local SHA-256 before returning the next offset.
+Filename/size/mtime are insufficient proof of resumed content identity. Filename
+classification, browser session storage and HTTP transport remain host policy.
+
 ## Configure named stores
 
 Use the package-owned S3 factory when applicable. For other providers, create a
@@ -1083,3 +1236,11 @@ or direct filesystem calls.
 ## License
 
 MIT
+
+## Encrypted staged content
+
+`@nestm/storage/crypto` exports `StorageEncryptedContentStore<Scope>`. Install the optional `@nestm/crypto` peer only for this entry point. The store uses a host-owned `FileCipherEngine`, object-address function, fresh AAD buffers, allowed key providers, and metadata callbacks. It prepares detached encryption metadata before uploading and completes metadata only after plaintext and ciphertext accounting agree. Reads pin physical ETags and authenticate full content or bounded frame ranges.
+
+The host authorizes reads, serializes metadata, enforces key policy and atomically proves reference eligibility before `metadata.discard` removes anything. A missing upload receipt means completion is uncertain: keep prepared cleanup inventory for a later sweep. A rejected prepare does not authorize cleanup of another writer's reservation. Engine shutdown stays with its owner. See [the standalone archive consumer](scripts/fixtures/encrypted-content-consumer.ts).
+
+`StorageStagedContentStore.writeReserved(scope, payloadId, stream, options)` accepts a fresh UUID from a trusted caller. It retains create-only semantics and returns that exact identity in the receipt; it never overwrites an existing payload. Ordinary writers continue to use `write`.

package/SECURITY.md

@@ -49,6 +49,33 @@ 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

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/index.d.ts

@@ -1,2 +1,3 @@
 export { AI_SDK_WORKSPACE_TOOL_NAMES, AiSdkWorkspaceToolError, createAiSdkWorkspaceTools, isAiSdkWorkspaceMutationToolName, type AiSdkWorkspaceApprovalConfig, type AiSdkWorkspaceCreateConflict, type AiSdkWorkspaceCreateConflictMapper, type AiSdkWorkspaceDirectoryResult, type AiSdkWorkspaceEntryResult, type AiSdkWorkspaceFileResult, type AiSdkWorkspaceMutationMode, type AiSdkWorkspaceMutationToolName, type AiSdkWorkspacePageResult, type AiSdkWorkspaceTextFileResult, type AiSdkWorkspaceToolErrorCode, type AiSdkWorkspaceToolErrorOptions, type AiSdkWorkspaceToolName, type CreateAiSdkWorkspaceToolsOptions, } from './ai-sdk-workspace-tools.js';
+export { createAiSdkFileWorkflowTools, createAiSdkCatalogFileTools, createAiSdkCatalogFileEditSchemas, AI_SDK_FILE_WORKFLOW_TOOL_NAMES, AI_SDK_CATALOG_FILE_TOOL_NAMES, type CreateAiSdkFileWorkflowToolsOptions, type CreateAiSdkCatalogFileToolsOptions, } from './ai-sdk-file-workflow-tools.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/ai-sdk/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ai-sdk/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,2BAA2B,EAC3B,uBAAuB,EACvB,yBAAyB,EACzB,gCAAgC,EAChC,KAAK,4BAA4B,EACjC,KAAK,4BAA4B,EACjC,KAAK,kCAAkC,EACvC,KAAK,6BAA6B,EAClC,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,0BAA0B,EAC/B,KAAK,8BAA8B,EACnC,KAAK,wBAAwB,EAC7B,KAAK,4BAA4B,EACjC,KAAK,2BAA2B,EAChC,KAAK,8BAA8B,EACnC,KAAK,sBAAsB,EAC3B,KAAK,gCAAgC,GACtC,MAAM,6BAA6B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ai-sdk/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,2BAA2B,EAC3B,uBAAuB,EACvB,yBAAyB,EACzB,gCAAgC,EAChC,KAAK,4BAA4B,EACjC,KAAK,4BAA4B,EACjC,KAAK,kCAAkC,EACvC,KAAK,6BAA6B,EAClC,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,0BAA0B,EAC/B,KAAK,8BAA8B,EACnC,KAAK,wBAAwB,EAC7B,KAAK,4BAA4B,EACjC,KAAK,2BAA2B,EAChC,KAAK,8BAA8B,EACnC,KAAK,sBAAsB,EAC3B,KAAK,gCAAgC,GACtC,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,4BAA4B,EAC5B,2BAA2B,EAC3B,iCAAiC,EACjC,+BAA+B,EAC/B,8BAA8B,EAC9B,KAAK,mCAAmC,EACxC,KAAK,kCAAkC,GACxC,MAAM,iCAAiC,CAAC"}

package/dist/ai-sdk/index.js

@@ -1,2 +1,3 @@
 export { AI_SDK_WORKSPACE_TOOL_NAMES, AiSdkWorkspaceToolError, createAiSdkWorkspaceTools, isAiSdkWorkspaceMutationToolName, } from './ai-sdk-workspace-tools.js';
+export { createAiSdkFileWorkflowTools, createAiSdkCatalogFileTools, createAiSdkCatalogFileEditSchemas, AI_SDK_FILE_WORKFLOW_TOOL_NAMES, AI_SDK_CATALOG_FILE_TOOL_NAMES, } from './ai-sdk-file-workflow-tools.js';
 //# sourceMappingURL=index.js.map

package/dist/ai-sdk/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ai-sdk/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,2BAA2B,EAC3B,uBAAuB,EACvB,yBAAyB,EACzB,gCAAgC,GAejC,MAAM,6BAA6B,CAAC","sourcesContent":["export {\n  AI_SDK_WORKSPACE_TOOL_NAMES,\n  AiSdkWorkspaceToolError,\n  createAiSdkWorkspaceTools,\n  isAiSdkWorkspaceMutationToolName,\n  type AiSdkWorkspaceApprovalConfig,\n  type AiSdkWorkspaceCreateConflict,\n  type AiSdkWorkspaceCreateConflictMapper,\n  type AiSdkWorkspaceDirectoryResult,\n  type AiSdkWorkspaceEntryResult,\n  type AiSdkWorkspaceFileResult,\n  type AiSdkWorkspaceMutationMode,\n  type AiSdkWorkspaceMutationToolName,\n  type AiSdkWorkspacePageResult,\n  type AiSdkWorkspaceTextFileResult,\n  type AiSdkWorkspaceToolErrorCode,\n  type AiSdkWorkspaceToolErrorOptions,\n  type AiSdkWorkspaceToolName,\n  type CreateAiSdkWorkspaceToolsOptions,\n} from './ai-sdk-workspace-tools.js';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ai-sdk/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,2BAA2B,EAC3B,uBAAuB,EACvB,yBAAyB,EACzB,gCAAgC,GAejC,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,4BAA4B,EAC5B,2BAA2B,EAC3B,iCAAiC,EACjC,+BAA+B,EAC/B,8BAA8B,GAG/B,MAAM,iCAAiC,CAAC","sourcesContent":["export {\n  AI_SDK_WORKSPACE_TOOL_NAMES,\n  AiSdkWorkspaceToolError,\n  createAiSdkWorkspaceTools,\n  isAiSdkWorkspaceMutationToolName,\n  type AiSdkWorkspaceApprovalConfig,\n  type AiSdkWorkspaceCreateConflict,\n  type AiSdkWorkspaceCreateConflictMapper,\n  type AiSdkWorkspaceDirectoryResult,\n  type AiSdkWorkspaceEntryResult,\n  type AiSdkWorkspaceFileResult,\n  type AiSdkWorkspaceMutationMode,\n  type AiSdkWorkspaceMutationToolName,\n  type AiSdkWorkspacePageResult,\n  type AiSdkWorkspaceTextFileResult,\n  type AiSdkWorkspaceToolErrorCode,\n  type AiSdkWorkspaceToolErrorOptions,\n  type AiSdkWorkspaceToolName,\n  type CreateAiSdkWorkspaceToolsOptions,\n} from './ai-sdk-workspace-tools.js';\nexport {\n  createAiSdkFileWorkflowTools,\n  createAiSdkCatalogFileTools,\n  createAiSdkCatalogFileEditSchemas,\n  AI_SDK_FILE_WORKFLOW_TOOL_NAMES,\n  AI_SDK_CATALOG_FILE_TOOL_NAMES,\n  type CreateAiSdkFileWorkflowToolsOptions,\n  type CreateAiSdkCatalogFileToolsOptions,\n} from './ai-sdk-file-workflow-tools.js';\n"]}