@visulima/storage 1.0.0-alpha.25 → 1.0.0-alpha.27

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

@@ -0,0 +1,113 @@
+import { F as Files } from "../../packem_shared/index.d-DotjipuX.js";
+import { C as CopyFileInput, D as DeleteFileInput, a as DownloadFileInput, G as GetFileMetadataInput, b as GetFileUrlInput, L as ListFilesInput, S as SignUploadUrlInput, U as UploadFileInput, F as FileToolName, A as ApprovalConfig, c as FileReadToolName } from "../../packem_shared/approval.d-CMAYH9GF.js";
+export { type d as FileWriteToolName } from "../../packem_shared/approval.d-CMAYH9GF.js";
+import { Tool } from 'ai';
+import { e as executors } from "../../packem_shared/executors.d-UtkeCbk1.js";
+import "../../packem_shared/storage.d-Cr6f2lac.js";
+import 'node:stream';
+import 'node:crypto';
+import 'node:http';
+import 'lru-cache';
+import 'zod';
+/**
+* Common options accepted by every write-tool factory.
+*/
+interface ToolOptions {
+  needsApproval?: boolean;
+}
+/**
+* Per-tool overrides for customizing AI SDK `tool()` properties without
+* changing the underlying implementation. Core properties (`execute`,
+* `inputSchema`, `outputSchema`) are intentionally excluded — those drive
+* the tool's behavior and contract and shouldn't be patched at this layer.
+*/
+type ToolOverrides = Partial<Pick<Tool, "description" | "needsApproval" | "onInputAvailable" | "onInputDelta" | "onInputStart" | "providerOptions" | "toModelOutput">>;
+type ListFilesOutput = Awaited<ReturnType<typeof executors.listFiles>>;
+type GetFileMetadataOutput = Awaited<ReturnType<typeof executors.getFileMetadata>>;
+type DownloadFileOutput = Awaited<ReturnType<typeof executors.downloadFile>>;
+type GetFileUrlOutput = Awaited<ReturnType<typeof executors.getFileUrl>>;
+type UploadFileOutput = Awaited<ReturnType<typeof executors.uploadFile>>;
+type DeleteFileOutput = Awaited<ReturnType<typeof executors.deleteFile>>;
+type CopyFileOutput = Awaited<ReturnType<typeof executors.copyFile>>;
+type SignUploadUrlOutput = Awaited<ReturnType<typeof executors.signUploadUrl>>;
+declare const listFiles: (files: Files) => Tool<ListFilesInput, ListFilesOutput>;
+declare const getFileMetadata: (files: Files) => Tool<GetFileMetadataInput, GetFileMetadataOutput>;
+declare const downloadFile: (files: Files) => Tool<DownloadFileInput, DownloadFileOutput>;
+declare const getFileUrl: (files: Files) => Tool<GetFileUrlInput, GetFileUrlOutput>;
+declare const uploadFile: (files: Files, {
+  needsApproval
+}?: ToolOptions) => Tool<UploadFileInput, UploadFileOutput>;
+declare const deleteFile: (files: Files, {
+  needsApproval
+}?: ToolOptions) => Tool<DeleteFileInput, DeleteFileOutput>;
+declare const copyFile: (files: Files, {
+  needsApproval
+}?: ToolOptions) => Tool<CopyFileInput, CopyFileOutput>;
+declare const signUploadUrl: (files: Files, {
+  needsApproval
+}?: ToolOptions) => Tool<SignUploadUrlInput, SignUploadUrlOutput>;
+interface FileToolsOptions {
+  /**
+  * The configured `Files` instance the tools will operate against.
+  * Each tool delegates to the methods on this instance.
+  */
+  files: Files;
+  /**
+  * Per-tool overrides for customizing tool behavior (description, title,
+  * needsApproval, etc.) without changing the underlying implementation.
+  * `execute` and `inputSchema` cannot be overridden.
+  */
+  overrides?: Partial<Record<FileToolName, ToolOverrides>>;
+  /**
+  * When `true`, write tools (`uploadFile`, `deleteFile`, `copyFile`,
+  * `signUploadUrl`) are omitted entirely. The model cannot mutate the
+  * bucket regardless of approval configuration.
+  */
+  readOnly?: boolean;
+  /**
+  * Approval gating for write tools. Defaults to `true` (all writes
+  * require approval). See {@link ApprovalConfig}.
+  */
+  requireApproval?: ApprovalConfig;
+}
+interface FileTools {
+  copyFile: ReturnType<typeof copyFile>;
+  deleteFile: ReturnType<typeof deleteFile>;
+  downloadFile: ReturnType<typeof downloadFile>;
+  getFileMetadata: ReturnType<typeof getFileMetadata>;
+  getFileUrl: ReturnType<typeof getFileUrl>;
+  listFiles: ReturnType<typeof listFiles>;
+  signUploadUrl: ReturnType<typeof signUploadUrl>;
+  uploadFile: ReturnType<typeof uploadFile>;
+}
+type ReadOnlyFileTools = Pick<FileTools, FileReadToolName>;
+/**
+* Create a set of visulima/storage tools for the Vercel AI SDK.
+*
+* Write operations require user approval by default. Control globally or
+* per-tool via `requireApproval`, or strip writes entirely with
+* `readOnly: true`.
+* @example
+* ```ts
+* import { Files } from "@visulima/storage";
+* import { S3Storage } from "@visulima/storage/provider/aws";
+* import { createFileTools } from "@visulima/storage/ai/sdk";
+* import { generateText } from "ai";
+*
+* const files = new Files({ adapter: new S3Storage({ bucket: "uploads" }) });
+*
+* const result = await generateText({
+*   model,
+*   tools: createFileTools({ files }),
+*   prompt: "Find every CSV under reports/ and summarize the latest one.",
+* });
+* ```
+*/
+declare function createFileTools(options: FileToolsOptions & {
+  readOnly: true;
+}): ReadOnlyFileTools;
+declare function createFileTools(options: FileToolsOptions & {
+  readOnly?: false | undefined;
+}): FileTools;
+declare function createFileTools(options: FileToolsOptions): FileTools | ReadOnlyFileTools;
+export { type ApprovalConfig, type FileReadToolName, type FileToolName, FileTools, FileToolsOptions, ReadOnlyFileTools, type ToolOptions, type ToolOverrides, copyFile, createFileTools, deleteFile, downloadFile, getFileMetadata, getFileUrl, listFiles, signUploadUrl, uploadFile };

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

@@ -0,0 +1 @@
+var d=Object.defineProperty;var t=(e,l)=>d(e,"name",{value:l,configurable:!0});import{r as c}from"../../packem_shared/approval-BBeX3o4E.js";import{W as f}from"../../packem_shared/executors-DG6hGtvm.js";import{uploadFile as u,signUploadUrl as g,listFiles as v,getFileUrl as m,getFileMetadata as O,downloadFile as U,deleteFile as b,copyFile as j}from"../../packem_shared/listFiles-BtP6VnUp.js";var y=Object.defineProperty,p=t((e,l)=>y(e,"name",{value:l,configurable:!0}),"r");function T({files:e,overrides:l,readOnly:n=!1,requireApproval:F=!0}){const o=p(r=>({needsApproval:c(r,F)}),"approval"),i={copyFile:j(e,o("copyFile")),deleteFile:b(e,o("deleteFile")),downloadFile:U(e),getFileMetadata:O(e),getFileUrl:m(e),listFiles:v(e),signUploadUrl:g(e,o("signUploadUrl")),uploadFile:u(e,o("uploadFile"))};if(l){for(const[r,a]of Object.entries(l))if(r in i&&a){const s=r;Object.assign(i,{[s]:{...i[s],...a}})}}return n?Object.fromEntries(Object.entries(i).filter(([r])=>!f.has(r))):i}t(T,"createFileTools");p(T,"createFileTools");export{j as copyFile,T as createFileTools,b as deleteFile,U as downloadFile,O as getFileMetadata,m as getFileUrl,v as listFiles,g as signUploadUrl,u as uploadFile};

package/dist/ai/claude/index.d.ts

@@ -0,0 +1,177 @@
+import { SdkMcpToolDefinition, CanUseTool, McpSdkServerConfigWithInstance } from '@anthropic-ai/claude-agent-sdk';
+import { F as Files } from "../../packem_shared/index.d-DotjipuX.js";
+import { T as TOOL_SCHEMAS, F as FileToolName, A as ApprovalConfig } from "../../packem_shared/approval.d-CMAYH9GF.js";
+export { type c as FileReadToolName, type d as FileWriteToolName } from "../../packem_shared/approval.d-CMAYH9GF.js";
+import "../../packem_shared/storage.d-Cr6f2lac.js";
+import 'node:stream';
+import 'node:crypto';
+import 'node:http';
+import 'lru-cache';
+import 'zod';
+/**
+* MCP tool annotations as accepted by `tool()` and exposed on
+* `SdkMcpToolDefinition`. Re-derived from the SDK rather than imported from
+* `@modelcontextprotocol/sdk` directly to avoid taking on a second peer
+* dependency.
+*/
+type ToolAnnotations = NonNullable<SdkMcpToolDefinition["annotations"]>;
+/**
+* Per-tool overrides for `createClaudeFileTools`. `name`, `inputSchema`, and
+* `handler` are intentionally not overridable — the contract that drives tool
+* behavior should not be patched at this layer.
+*/
+interface ClaudeToolOverrides {
+  annotations?: ToolAnnotations;
+  description?: string;
+}
+interface ClaudeWriteToolOptions {
+  annotations?: ToolAnnotations;
+}
+type ListFilesShape = (typeof TOOL_SCHEMAS.listFiles.input)["shape"];
+type GetFileMetadataShape = (typeof TOOL_SCHEMAS.getFileMetadata.input)["shape"];
+type DownloadFileShape = (typeof TOOL_SCHEMAS.downloadFile.input)["shape"];
+type GetFileUrlShape = (typeof TOOL_SCHEMAS.getFileUrl.input)["shape"];
+type UploadFileShape = (typeof TOOL_SCHEMAS.uploadFile.input)["shape"];
+type DeleteFileShape = (typeof TOOL_SCHEMAS.deleteFile.input)["shape"];
+type CopyFileShape = (typeof TOOL_SCHEMAS.copyFile.input)["shape"];
+type SignUploadUrlShape = (typeof TOOL_SCHEMAS.signUploadUrl.input)["shape"];
+declare const claudeListFiles: (files: Files) => SdkMcpToolDefinition<ListFilesShape>;
+declare const claudeGetFileMetadata: (files: Files) => SdkMcpToolDefinition<GetFileMetadataShape>;
+declare const claudeDownloadFile: (files: Files) => SdkMcpToolDefinition<DownloadFileShape>;
+declare const claudeGetFileUrl: (files: Files) => SdkMcpToolDefinition<GetFileUrlShape>;
+declare const claudeUploadFile: (files: Files, {
+  annotations
+}?: ClaudeWriteToolOptions) => SdkMcpToolDefinition<UploadFileShape>;
+declare const claudeDeleteFile: (files: Files, {
+  annotations
+}?: ClaudeWriteToolOptions) => SdkMcpToolDefinition<DeleteFileShape>;
+declare const claudeCopyFile: (files: Files, {
+  annotations
+}?: ClaudeWriteToolOptions) => SdkMcpToolDefinition<CopyFileShape>;
+declare const claudeSignUploadUrl: (files: Files, {
+  annotations
+}?: ClaudeWriteToolOptions) => SdkMcpToolDefinition<SignUploadUrlShape>;
+interface ClaudeFileToolsOptions {
+  /**
+  * The configured `Files` instance the tools will operate against.
+  */
+  files: Files;
+  /**
+  * Per-tool overrides for `description` / `annotations` without touching
+  * the underlying handler or input schema.
+  */
+  overrides?: Partial<Record<FileToolName, ClaudeToolOverrides>>;
+  /**
+  * When `true`, write tools (`uploadFile`, `deleteFile`, `copyFile`,
+  * `signUploadUrl`) are omitted from the MCP server. The model cannot
+  * mutate the bucket regardless of approval configuration.
+  */
+  readOnly?: boolean;
+  /**
+  * Approval gating reflected by {@link ClaudeFileTools.needsApproval} and
+  * the bundled {@link ClaudeFileTools.canUseTool}. Defaults to `true`
+  * (every write requires approval). Pass `false` to disable, or an object
+  * keyed by write-tool name for fine-grained control.
+  */
+  requireApproval?: ApprovalConfig;
+  /**
+  * Name of the in-process MCP server that wraps these tools. Affects the
+  * `mcp__&lt;server-name>__&lt;tool-name>` strings the agent uses to address
+  * each tool. Defaults to `"files"`.
+  */
+  serverName?: string;
+  /**
+  * MCP server `version` metadata. Defaults to `"1.0.0"`.
+  */
+  serverVersion?: string;
+}
+interface ClaudeFileTools {
+  /**
+  * Pass into `query({ options: { allowedTools: tools.allowedTools } })`.
+  * Each entry is of the form `mcp__&lt;serverName>__&lt;toolName>`.
+  */
+  allowedTools: string[];
+  /**
+  * Ready-made `canUseTool` callback. Allows reads unconditionally, allows
+  * writes whose `needsApproval` resolves to `false`, denies the rest with
+  * a `"requires approval"` message. Pass directly into `query()`, or
+  * compose your own using {@link ClaudeFileTools.needsApproval}.
+  */
+  canUseTool: CanUseTool;
+  /**
+  * Pass into `query({ options: { mcpServers: tools.mcpServers } })`.
+  */
+  mcpServers: Record<string, McpSdkServerConfigWithInstance>;
+  /**
+  * Whether the named tool is approval-gated under the configured
+  * `requireApproval`. Accepts both bare names (`"uploadFile"`) and the
+  * MCP-prefixed form (`"mcp__files__uploadFile"`). Read tools and unknown
+  * names return `false`.
+  */
+  needsApproval: (toolName: string) => boolean;
+  /**
+  * The raw SDK MCP server instance — same value as
+  * `mcpServers[serverName]`. Exposed for callers that want to compose it
+  * into a larger `mcpServers` map.
+  */
+  server: McpSdkServerConfigWithInstance;
+  /**
+  * The MCP server name used in the `mcp__&lt;server>__*` prefix.
+  */
+  serverName: string;
+}
+/**
+* Create storage tools shaped for the Claude Agent SDK
+* (`@anthropic-ai/claude-agent-sdk`).
+*
+* The Claude Agent SDK consumes tools by way of an in-process MCP server +
+* an `allowedTools` allow-list + a `canUseTool` approval callback. The
+* returned bundle gives you all three, plus the raw server instance and a
+* `needsApproval()` helper if you want to wire your own `canUseTool`.
+* @example
+* ```ts
+* import { query } from "@anthropic-ai/claude-agent-sdk";
+* import { Files } from "@visulima/storage";
+* import { S3Storage } from "@visulima/storage/provider/aws";
+* import { createClaudeFileTools } from "@visulima/storage/ai/claude";
+*
+* const files = new Files({ adapter: new S3Storage({ bucket: "uploads" }) });
+* const tools = createClaudeFileTools({ files });
+*
+* for await (const message of query({
+*   prompt: "List my files.",
+*   options: {
+*     mcpServers: tools.mcpServers,
+*     allowedTools: tools.allowedTools,
+*     canUseTool: tools.canUseTool,
+*   },
+* })) {
+*   // handle messages
+* }
+* ```
+* @example Read-only agent
+* ```ts
+* createClaudeFileTools({ files, readOnly: true })
+* ```
+* @example Granular approval
+* ```ts
+* createClaudeFileTools({
+*   files,
+*   requireApproval: {
+*     copyFile: false,
+*     deleteFile: true,
+*     signUploadUrl: true,
+*     uploadFile: false,
+*   },
+* })
+* ```
+*/
+declare const createClaudeFileTools: ({
+  files,
+  overrides,
+  readOnly,
+  requireApproval,
+  serverName,
+  serverVersion
+}: ClaudeFileToolsOptions) => ClaudeFileTools;
+export { type ApprovalConfig, ClaudeFileTools, ClaudeFileToolsOptions, type ClaudeToolOverrides, type ClaudeWriteToolOptions, type FileToolName, type ToolAnnotations, claudeCopyFile, claudeDeleteFile, claudeDownloadFile, claudeGetFileMetadata, claudeGetFileUrl, claudeListFiles, claudeSignUploadUrl, claudeUploadFile, createClaudeFileTools };

package/dist/ai/claude/index.js

@@ -0,0 +1 @@
+var _=Object.defineProperty;var u=(l,a)=>_(l,"name",{value:a,configurable:!0});import{createSdkMcpServer as b}from"@anthropic-ai/claude-agent-sdk";import{r as h}from"../../packem_shared/approval-BBeX3o4E.js";import{W as y}from"../../packem_shared/executors-DG6hGtvm.js";import{claudeUploadFile as O,claudeSignUploadUrl as S,claudeListFiles as w,claudeGetFileUrl as A,claudeGetFileMetadata as E,claudeDownloadFile as M,claudeDeleteFile as W,claudeCopyFile as $}from"../../packem_shared/claudeListFiles-DAezbKEi.js";var j=Object.defineProperty,o=u((l,a)=>j(l,"name",{value:a,configurable:!0}),"r");const C="files",D="1.0.0",v=o(l=>y.has(l),"isWriteTool"),I=o(({files:l,overrides:a,readOnly:m=!1,requireApproval:f=!0,serverName:s=C,serverVersion:F=D})=>{const t={copyFile:$(l),deleteFile:W(l),downloadFile:M(l),getFileMetadata:E(l),getFileUrl:A(l),listFiles:w(l),signUploadUrl:S(l),uploadFile:O(l)};if(a){for(const[e,r]of Object.entries(a))if(e in t&&r){const c=e;t[c]={...t[c],...r}}}const i=Object.entries(t).filter(([e])=>!(m&&v(e))),n=`mcp__${s}__`,T=o(e=>e.startsWith(n)?e.slice(n.length):e,"stripPrefix"),U=new Set(i.map(([e])=>e)),p=o(e=>{const r=T(e);return!U.has(r)||!v(r)?!1:h(r,f)},"needsApproval"),g=o((e,r)=>Promise.resolve(p(e)?{behavior:"deny",message:`Tool "${e}" requires approval.`}:{behavior:"allow",updatedInput:r}),"canUseTool"),d=b({name:s,tools:i.map(([,e])=>e),version:F});return{allowedTools:i.map(([e])=>`${n}${e}`),canUseTool:g,mcpServers:{[s]:d},needsApproval:p,server:d,serverName:s}},"createClaudeFileTools");export{$ as claudeCopyFile,W as claudeDeleteFile,M as claudeDownloadFile,E as claudeGetFileMetadata,A as claudeGetFileUrl,w as claudeListFiles,S as claudeSignUploadUrl,O as claudeUploadFile,I as createClaudeFileTools};

package/dist/ai/openai/index.d.ts

@@ -0,0 +1,205 @@
+import { T as TOOL_SCHEMAS, F as FileToolName, A as ApprovalConfig, c as FileReadToolName } from "../../packem_shared/approval.d-CMAYH9GF.js";
+export { type d as FileWriteToolName } from "../../packem_shared/approval.d-CMAYH9GF.js";
+import { UnknownContext, FunctionTool } from '@openai/agents';
+import { F as Files } from "../../packem_shared/index.d-DotjipuX.js";
+import { e as executors } from "../../packem_shared/executors.d-UtkeCbk1.js";
+import 'zod';
+import "../../packem_shared/storage.d-Cr6f2lac.js";
+import 'node:stream';
+import 'node:crypto';
+import 'node:http';
+import 'lru-cache';
+/**
+* Per-tool overrides for `createResponsesFileTools`. `name`, `parameters`, and
+* `type` are intentionally not overridable — the contract that drives tool
+* behavior should not be patched at this layer.
+*/
+interface ResponsesToolOverrides {
+  description?: string;
+  strict?: boolean;
+}
+/**
+* Per-tool overrides for `createAgentsFileTools`. `name`, `parameters`,
+* `execute`, and `strict` are intentionally not overridable — the contract
+* that drives tool behavior should not be patched at this layer.
+*/
+interface AgentsToolOverrides {
+  description?: string;
+  needsApproval?: boolean;
+}
+type ListFilesOutput = Awaited<ReturnType<typeof executors.listFiles>>;
+type GetFileMetadataOutput = Awaited<ReturnType<typeof executors.getFileMetadata>>;
+type DownloadFileOutput = Awaited<ReturnType<typeof executors.downloadFile>>;
+type GetFileUrlOutput = Awaited<ReturnType<typeof executors.getFileUrl>>;
+type UploadFileOutput = Awaited<ReturnType<typeof executors.uploadFile>>;
+type DeleteFileOutput = Awaited<ReturnType<typeof executors.deleteFile>>;
+type CopyFileOutput = Awaited<ReturnType<typeof executors.copyFile>>;
+type SignUploadUrlOutput = Awaited<ReturnType<typeof executors.signUploadUrl>>;
+type ListFilesParameters = typeof TOOL_SCHEMAS.listFiles.input;
+type GetFileMetadataParameters = typeof TOOL_SCHEMAS.getFileMetadata.input;
+type DownloadFileParameters = typeof TOOL_SCHEMAS.downloadFile.input;
+type GetFileUrlParameters = typeof TOOL_SCHEMAS.getFileUrl.input;
+type UploadFileParameters = typeof TOOL_SCHEMAS.uploadFile.input;
+type DeleteFileParameters = typeof TOOL_SCHEMAS.deleteFile.input;
+type CopyFileParameters = typeof TOOL_SCHEMAS.copyFile.input;
+type SignUploadUrlParameters = typeof TOOL_SCHEMAS.signUploadUrl.input;
+declare const agentsListFiles: (files: Files) => FunctionTool<UnknownContext, ListFilesParameters, ListFilesOutput>;
+declare const agentsGetFileMetadata: (files: Files) => FunctionTool<UnknownContext, GetFileMetadataParameters, GetFileMetadataOutput>;
+declare const agentsDownloadFile: (files: Files) => FunctionTool<UnknownContext, DownloadFileParameters, DownloadFileOutput>;
+declare const agentsGetFileUrl: (files: Files) => FunctionTool<UnknownContext, GetFileUrlParameters, GetFileUrlOutput>;
+declare const agentsUploadFile: (files: Files, {
+  needsApproval
+}?: {
+  needsApproval?: boolean;
+}) => FunctionTool<UnknownContext, UploadFileParameters, UploadFileOutput>;
+declare const agentsDeleteFile: (files: Files, {
+  needsApproval
+}?: {
+  needsApproval?: boolean;
+}) => FunctionTool<UnknownContext, DeleteFileParameters, DeleteFileOutput>;
+declare const agentsCopyFile: (files: Files, {
+  needsApproval
+}?: {
+  needsApproval?: boolean;
+}) => FunctionTool<UnknownContext, CopyFileParameters, CopyFileOutput>;
+declare const agentsSignUploadUrl: (files: Files, {
+  needsApproval
+}?: {
+  needsApproval?: boolean;
+}) => FunctionTool<UnknownContext, SignUploadUrlParameters, SignUploadUrlOutput>;
+interface AgentsFileTools {
+  copyFile: ReturnType<typeof agentsCopyFile>;
+  deleteFile: ReturnType<typeof agentsDeleteFile>;
+  downloadFile: ReturnType<typeof agentsDownloadFile>;
+  getFileMetadata: ReturnType<typeof agentsGetFileMetadata>;
+  getFileUrl: ReturnType<typeof agentsGetFileUrl>;
+  listFiles: ReturnType<typeof agentsListFiles>;
+  signUploadUrl: ReturnType<typeof agentsSignUploadUrl>;
+  uploadFile: ReturnType<typeof agentsUploadFile>;
+}
+type ReadOnlyAgentsFileTools = Pick<AgentsFileTools, FileReadToolName>;
+interface AgentsFileToolsOptions {
+  files: Files;
+  overrides?: Partial<Record<FileToolName, AgentsToolOverrides>>;
+  readOnly?: boolean;
+  requireApproval?: ApprovalConfig;
+}
+/**
+* Create a set of storage tools shaped for the OpenAI Agents SDK (`@openai/agents`).
+*
+* Returns a record keyed by tool name — spread `Object.values()` into
+* `new Agent({ tools })`. Write tools require approval by default.
+* @example
+* ```ts
+* import { Agent, run } from "@openai/agents";
+* import { Files } from "@visulima/storage";
+* import { S3Storage } from "@visulima/storage/provider/aws";
+* import { createAgentsFileTools } from "@visulima/storage/ai/openai";
+*
+* const files = new Files({ adapter: new S3Storage({ bucket: "uploads" }) });
+* const tools = createAgentsFileTools({ files });
+*
+* const agent = new Agent({
+*   instructions: "Help the user manage their files.",
+*   name: "Files agent",
+*   tools: Object.values(tools),
+* });
+*
+* const result = await run(agent, "List my files.");
+* ```
+*/
+declare function createAgentsFileTools(options: AgentsFileToolsOptions & {
+  readOnly: true;
+}): ReadOnlyAgentsFileTools;
+declare function createAgentsFileTools(options: AgentsFileToolsOptions & {
+  readOnly?: false | undefined;
+}): AgentsFileTools;
+declare function createAgentsFileTools(options: AgentsFileToolsOptions): AgentsFileTools | ReadOnlyAgentsFileTools;
+/**
+* A function-tool definition shaped for OpenAI's Responses API. Pass an
+* array of these to `openai.responses.create({ tools })`.
+*/
+interface ResponsesFunctionTool {
+  description: string;
+  name: string;
+  parameters: Record<string, unknown>;
+  strict: boolean;
+  type: "function";
+}
+/**
+* A function call emitted by the Responses API in `response.output[]`.
+*/
+interface FunctionCallItem {
+  arguments: string;
+  call_id: string;
+  name: string;
+  type: "function_call";
+}
+/**
+* A function-call output item to append to the next `responses.create`
+* input alongside the original `function_call` item.
+*/
+interface FunctionCallOutputItem {
+  call_id: string;
+  output: string;
+  type: "function_call_output";
+}
+interface ResponsesFileTools {
+  /**
+  * Function tool definitions. Pass directly to `openai.responses.create({ tools })`.
+  */
+  definitions: ResponsesFunctionTool[];
+  /**
+  * Execute a `function_call` item from the model's `response.output[]`.
+  * Returns a `function_call_output` item ready to push into the next turn's input.
+  *
+  * Approval is **not** enforced. Check {@link ResponsesFileTools.needsApproval}
+  * first if you want a human-in-the-loop gate.
+  */
+  execute: (call: FunctionCallItem) => Promise<FunctionCallOutputItem>;
+  /**
+  * Returns whether the named tool is approval-gated under this config.
+  * Read tools always return `false`. Unknown names return `false`.
+  */
+  needsApproval: (name: string) => boolean;
+}
+interface ResponsesFileToolsOptions {
+  files: Files;
+  overrides?: Partial<Record<FileToolName, ResponsesToolOverrides>>;
+  readOnly?: boolean;
+  requireApproval?: ApprovalConfig;
+}
+/**
+* Create a set of storage tools shaped for OpenAI's Responses API (`openai.responses.create`).
+* @example
+* ```ts
+* import OpenAI from "openai";
+* import { Files } from "@visulima/storage";
+* import { S3Storage } from "@visulima/storage/provider/aws";
+* import { createResponsesFileTools } from "@visulima/storage/ai/openai";
+*
+* const client = new OpenAI();
+* const files = new Files({ adapter: new S3Storage({ bucket: "uploads" }) });
+* const ft = createResponsesFileTools({ files });
+*
+* const input: any[] = [{ role: "user", content: "List my files." }];
+* while (true) {
+*   const res = await client.responses.create({ model: "gpt-4.1", input, tools: ft.definitions });
+*   const calls = res.output.filter((o) => o.type === "function_call");
+*   if (calls.length === 0) break;
+*   for (const call of calls) {
+*     if (ft.needsApproval(call.name)) {
+*       // surface approval UX, then continue or break
+*     }
+*     input.push(call, await ft.execute(call));
+*   }
+* }
+* ```
+*/
+declare const createResponsesFileTools: ({
+  files,
+  overrides,
+  readOnly,
+  requireApproval
+}: ResponsesFileToolsOptions) => ResponsesFileTools;
+export { type AgentsFileTools, type AgentsFileToolsOptions, type AgentsToolOverrides, type ApprovalConfig, type FileReadToolName, type FileToolName, type FunctionCallItem, type FunctionCallOutputItem, type ReadOnlyAgentsFileTools, type ResponsesFileTools, type ResponsesFileToolsOptions, type ResponsesFunctionTool, type ResponsesToolOverrides, agentsCopyFile, agentsDeleteFile, agentsDownloadFile, agentsGetFileMetadata, agentsGetFileUrl, agentsListFiles, agentsSignUploadUrl, agentsUploadFile, createAgentsFileTools, createResponsesFileTools };

package/dist/ai/openai/index.js

@@ -0,0 +1 @@
+import{agentsCopyFile as l,agentsDeleteFile as a,agentsDownloadFile as s,agentsGetFileMetadata as o,agentsGetFileUrl as n,agentsListFiles as i,agentsSignUploadUrl as g,agentsUploadFile as F,createAgentsFileTools as r}from"../../packem_shared/agentsListFiles-R-CnGKc4.js";import{createResponsesFileTools as d}from"../../packem_shared/createResponsesFileTools-BCep-qdO.js";export{l as agentsCopyFile,a as agentsDeleteFile,s as agentsDownloadFile,o as agentsGetFileMetadata,n as agentsGetFileUrl,i as agentsListFiles,g as agentsSignUploadUrl,F as agentsUploadFile,r as createAgentsFileTools,d as createResponsesFileTools};

package/dist/ai/tanstack/index.d.ts

@@ -0,0 +1,115 @@
+import { F as Files } from "../../packem_shared/index.d-DotjipuX.js";
+import { T as TOOL_SCHEMAS, c as FileReadToolName, F as FileToolName, A as ApprovalConfig } from "../../packem_shared/approval.d-CMAYH9GF.js";
+export { type d as FileWriteToolName } from "../../packem_shared/approval.d-CMAYH9GF.js";
+import { ServerTool } from '@tanstack/ai';
+import "../../packem_shared/storage.d-Cr6f2lac.js";
+import 'node:stream';
+import 'node:crypto';
+import 'node:http';
+import 'lru-cache';
+import 'zod';
+/**
+* Common options accepted by every write-tool factory.
+*/
+interface ToolOptions {
+  needsApproval?: boolean;
+}
+/**
+* Per-tool overrides for customizing TanStack AI `ServerTool` properties
+* without changing the underlying implementation. Core properties
+* (`execute`, `inputSchema`, `outputSchema`, `__toolSide`) are intentionally
+* excluded — those drive the tool's behavior and contract.
+*/
+type ToolOverrides = Partial<Pick<ServerTool, "description" | "lazy" | "metadata" | "needsApproval">>;
+type ListFilesParameters = typeof TOOL_SCHEMAS.listFiles.input;
+type GetFileMetadataParameters = typeof TOOL_SCHEMAS.getFileMetadata.input;
+type DownloadFileParameters = typeof TOOL_SCHEMAS.downloadFile.input;
+type GetFileUrlParameters = typeof TOOL_SCHEMAS.getFileUrl.input;
+type UploadFileParameters = typeof TOOL_SCHEMAS.uploadFile.input;
+type DeleteFileParameters = typeof TOOL_SCHEMAS.deleteFile.input;
+type CopyFileParameters = typeof TOOL_SCHEMAS.copyFile.input;
+type SignUploadUrlParameters = typeof TOOL_SCHEMAS.signUploadUrl.input;
+declare const listFiles: (files: Files) => ServerTool<ListFilesParameters, never, "listFiles">;
+declare const getFileMetadata: (files: Files) => ServerTool<GetFileMetadataParameters, never, "getFileMetadata">;
+declare const downloadFile: (files: Files) => ServerTool<DownloadFileParameters, never, "downloadFile">;
+declare const getFileUrl: (files: Files) => ServerTool<GetFileUrlParameters, never, "getFileUrl">;
+declare const uploadFile: (files: Files, {
+  needsApproval
+}?: ToolOptions) => ServerTool<UploadFileParameters, never, "uploadFile">;
+declare const deleteFile: (files: Files, {
+  needsApproval
+}?: ToolOptions) => ServerTool<DeleteFileParameters, never, "deleteFile">;
+declare const copyFile: (files: Files, {
+  needsApproval
+}?: ToolOptions) => ServerTool<CopyFileParameters, never, "copyFile">;
+declare const signUploadUrl: (files: Files, {
+  needsApproval
+}?: ToolOptions) => ServerTool<SignUploadUrlParameters, never, "signUploadUrl">;
+interface TanstackFileToolsOptions {
+  /**
+  * The configured `Files` instance the tools will operate against.
+  * Each tool delegates to the methods on this instance.
+  */
+  files: Files;
+  /**
+  * Per-tool overrides for customizing tool behavior (description,
+  * needsApproval, metadata) without changing the underlying implementation.
+  * `execute` and `inputSchema` cannot be overridden.
+  */
+  overrides?: Partial<Record<FileToolName, ToolOverrides>>;
+  /**
+  * When `true`, write tools (`uploadFile`, `deleteFile`, `copyFile`,
+  * `signUploadUrl`) are omitted entirely. The model cannot mutate the
+  * bucket regardless of approval configuration.
+  */
+  readOnly?: boolean;
+  /**
+  * Approval gating for write tools. Defaults to `true` (all writes
+  * require approval). See {@link ApprovalConfig}.
+  */
+  requireApproval?: ApprovalConfig;
+}
+interface TanstackFileTools {
+  copyFile: ReturnType<typeof copyFile>;
+  deleteFile: ReturnType<typeof deleteFile>;
+  downloadFile: ReturnType<typeof downloadFile>;
+  getFileMetadata: ReturnType<typeof getFileMetadata>;
+  getFileUrl: ReturnType<typeof getFileUrl>;
+  listFiles: ReturnType<typeof listFiles>;
+  signUploadUrl: ReturnType<typeof signUploadUrl>;
+  uploadFile: ReturnType<typeof uploadFile>;
+}
+type ReadOnlyTanstackFileTools = Pick<TanstackFileTools, FileReadToolName>;
+/**
+* Create a set of visulima/storage tools for TanStack AI.
+*
+* Each entry is a `ServerTool` built via `toolDefinition(...).server(...)`,
+* ready to be passed to `chat({ tools: [...] })` or registered with a
+* `ToolRegistry`. Write operations require user approval by default;
+* control globally or per-tool via `requireApproval`, or strip writes
+* entirely with `readOnly: true`.
+* @example
+* ```ts
+* import { Files } from "@visulima/storage";
+* import { S3Storage } from "@visulima/storage/provider/aws";
+* import { createTanstackFileTools } from "@visulima/storage/ai/tanstack";
+* import { chat } from "@tanstack/ai";
+*
+* const files = new Files({ adapter: new S3Storage({ bucket: "uploads" }) });
+* const tools = createTanstackFileTools({ files });
+*
+* const stream = chat({
+*   adapter,
+*   messages,
+*   tools: Object.values(tools),
+* });
+* ```
+*/
+declare function createTanstackFileTools(options: TanstackFileToolsOptions & {
+  readOnly: true;
+}): ReadOnlyTanstackFileTools;
+declare function createTanstackFileTools(options: TanstackFileToolsOptions & {
+  readOnly?: false | undefined;
+}): TanstackFileTools;
+declare function createTanstackFileTools(options: TanstackFileToolsOptions): ReadOnlyTanstackFileTools | TanstackFileTools;
+export { type ApprovalConfig, type FileReadToolName, type FileToolName, ReadOnlyTanstackFileTools, TanstackFileTools, TanstackFileToolsOptions, type ToolOptions, type ToolOverrides, copyFile, createTanstackFileTools, deleteFile, downloadFile, getFileMetadata, getFileUrl, listFiles, signUploadUrl, uploadFile };

package/dist/ai/tanstack/index.js

@@ -0,0 +1 @@
+var d=Object.defineProperty;var a=(e,l)=>d(e,"name",{value:l,configurable:!0});import{r as c}from"../../packem_shared/approval-BBeX3o4E.js";import{W as f}from"../../packem_shared/executors-DG6hGtvm.js";import{uploadFile as u,signUploadUrl as g,listFiles as v,getFileUrl as m,getFileMetadata as O,downloadFile as U,deleteFile as T,copyFile as b}from"../../packem_shared/listFiles-B6VF05d-.js";var j=Object.defineProperty,n=a((e,l)=>j(e,"name",{value:l,configurable:!0}),"i");function y({files:e,overrides:l,readOnly:p=!1,requireApproval:F=!0}){const o=n(i=>({needsApproval:c(i,F)}),"approval"),r={copyFile:b(e,o("copyFile")),deleteFile:T(e,o("deleteFile")),downloadFile:U(e),getFileMetadata:O(e),getFileUrl:m(e),listFiles:v(e),signUploadUrl:g(e,o("signUploadUrl")),uploadFile:u(e,o("uploadFile"))};if(l){for(const[i,t]of Object.entries(l))if(i in r&&t){const s=i;Object.assign(r,{[s]:{...r[s],...t}})}}return p?Object.fromEntries(Object.entries(r).filter(([i])=>!f.has(i))):r}a(y,"createTanstackFileTools");n(y,"createTanstackFileTools");export{b as copyFile,y as createTanstackFileTools,T as deleteFile,U as downloadFile,O as getFileMetadata,m as getFileUrl,v as listFiles,g as signUploadUrl,u as uploadFile};

package/dist/handler/http/fetch/index.d.ts

@@ -1,16 +1,16 @@
-import { U as UploadFile, l as UploadResponse } from "../../../packem_shared/storage.d-sc8gn16g.js";
+import { U as UploadFile, K as UploadResponse } from "../../../packem_shared/storage.d-Cr6f2lac.js";
 import 'node:stream';
-import { H as Handlers, R as ResponseFile, a as ResponseList, U as UploadOptions } from "../../../packem_shared/types.d-Cor8FV54.js";
-export { type A as AsyncHandler, type B as BaseHandler, type M as MethodHandler, type b as RequestEvent, type c as UploadErrorEvent, type d as UploadEvent } from "../../../packem_shared/types.d-Cor8FV54.js";
-import { B as BaseHandlerCore } from "../../../packem_shared/tus-base.d-BX3mSWL6.js";
-export { T as TUS_RESUMABLE, a as TUS_VERSION } from "../../../packem_shared/tus-base.d-BX3mSWL6.js";
+import { H as Handlers, R as ResponseFile, a as ResponseList, U as UploadOptions } from "../../../packem_shared/types.d-BgCmSE94.js";
+export { type A as AsyncHandler, type B as BaseHandler, type M as MethodHandler, type b as RequestEvent, type c as UploadErrorEvent, type d as UploadEvent } from "../../../packem_shared/types.d-BgCmSE94.js";
+import { B as BaseHandlerCore } from "../../../packem_shared/tus-base.d-4-ZfDQwl.js";
+export { T as TUS_RESUMABLE, a as TUS_VERSION } from "../../../packem_shared/tus-base.d-4-ZfDQwl.js";
 import 'node:crypto';
 import 'node:http';
 import 'lru-cache';
 import 'node:events';
 import '@visulima/pagination';
-import "../../../packem_shared/media-transformer.d-BXjTN5Qv.js";
-import "../../../packem_shared/types.d-b0WcdT0x.js";
+import "../../../packem_shared/media-transformer.d-DK7NJncf.js";
+import "../../../packem_shared/types.d-C8eSxqX9.js";
 /**
 * Base handler for Web API Fetch platform (Request/Response).
 * Extends BaseHandlerCore with Fetch-specific request/response handling.
@@ -248,6 +248,12 @@ declare class Tus<TFile extends UploadFile> extends BaseHandlerFetch<TFile> {
   private readonly tusBase;
   constructor(options: UploadOptions<TFile>);
   /**
+  * Web API fetch entrypoint. Wraps the base implementation to ensure every TUS
+  * response — success and error alike — carries the `Tus-Resumable` header,
+  * which the protocol requires on all responses.
+  */
+  override fetch(request: Request): Promise<globalThis.Response>;
+  /**
   * Handle OPTIONS requests with TUS protocol capabilities.
   * @returns Promise resolving to ResponseFile with TUS headers
   */