@optima-chat/agentic-sdk 0.11.0 → 0.12.0

package/dist/hooks/use-workspace-files.d.ts

@@ -0,0 +1,18 @@
+import type { ChatError, UploadResult } from '../types.js';
+import type { DeleteOptions, UploadOptions, WorkspaceFile } from '../workspace/types.js';
+export interface UseWorkspaceFilesOptions {
+    path?: string;
+    includeStats?: boolean;
+    /** Auto-fetch on mount and on path/includeStats change. Defaults to true. */
+    autoLoad?: boolean;
+}
+export interface UseWorkspaceFilesResult {
+    files: WorkspaceFile[];
+    loading: boolean;
+    error: ChatError | null;
+    refresh: () => Promise<void>;
+    upload: (files: File[], options?: UploadOptions) => Promise<UploadResult[]>;
+    deleteFile: (path: string, options?: DeleteOptions) => Promise<void>;
+}
+export declare function useWorkspaceFiles(options?: UseWorkspaceFilesOptions): UseWorkspaceFilesResult;
+//# sourceMappingURL=use-workspace-files.d.ts.map

package/dist/hooks/use-workspace-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-workspace-files.d.ts","sourceRoot":"","sources":["../../src/hooks/use-workspace-files.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EACb,aAAa,EACd,MAAM,uBAAuB,CAAC;AAE/B,MAAM,WAAW,wBAAwB;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;IACxB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,MAAM,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,OAAO,CAAC,EAAE,aAAa,KAAK,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAC5E,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACtE;AAaD,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE,wBAA6B,GACrC,uBAAuB,CAkDzB"}

package/dist/hooks/use-workspace-files.js

@@ -0,0 +1,52 @@
+import { useCallback, useEffect, useState } from 'react';
+import { useChatContext } from '../provider/chat-context.js';
+function toChatError(err) {
+    if (err && typeof err === 'object') {
+        const anyErr = err;
+        return {
+            code: anyErr.code ?? 'UNKNOWN',
+            message: anyErr.message ?? String(err),
+        };
+    }
+    return { code: 'UNKNOWN', message: String(err) };
+}
+export function useWorkspaceFiles(options = {}) {
+    const { workspaceProvider } = useChatContext();
+    if (!workspaceProvider) {
+        throw new Error('useWorkspaceFiles requires a workspaceProvider on <ChatProvider>');
+    }
+    const { path, includeStats, autoLoad = true } = options;
+    const [files, setFiles] = useState([]);
+    const [loading, setLoading] = useState(autoLoad);
+    const [error, setError] = useState(null);
+    const refresh = useCallback(async () => {
+        setLoading(true);
+        setError(null);
+        try {
+            const next = await workspaceProvider.listFiles({ path, includeStats });
+            setFiles(next);
+        }
+        catch (err) {
+            setError(toChatError(err));
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [workspaceProvider, path, includeStats]);
+    const upload = useCallback(async (incoming, uploadOptions) => {
+        const results = await workspaceProvider.uploadFiles(incoming, uploadOptions);
+        await refresh();
+        return results;
+    }, [workspaceProvider, refresh]);
+    const deleteFile = useCallback(async (target, deleteOptions) => {
+        await workspaceProvider.deleteFile(target, deleteOptions);
+        await refresh();
+    }, [workspaceProvider, refresh]);
+    useEffect(() => {
+        if (!autoLoad)
+            return;
+        void refresh();
+    }, [autoLoad, refresh]);
+    return { files, loading, error, refresh, upload, deleteFile };
+}
+//# sourceMappingURL=use-workspace-files.js.map

package/dist/hooks/use-workspace-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-workspace-files.js","sourceRoot":"","sources":["../../src/hooks/use-workspace-files.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAwB7D,SAAS,WAAW,CAAC,GAAY;IAC/B,IAAI,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QACnC,MAAM,MAAM,GAAG,GAA0C,CAAC;QAC1D,OAAO;YACL,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,SAAS;YAC9B,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC;SACvC,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;AACnD,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,UAAoC,EAAE;IAEtC,MAAM,EAAE,iBAAiB,EAAE,GAAG,cAAc,EAAE,CAAC;IAC/C,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CACb,kEAAkE,CACnE,CAAC;IACJ,CAAC;IAED,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,QAAQ,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;IAExD,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAkB,EAAE,CAAC,CAAC;IACxD,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,QAAQ,CAAU,QAAQ,CAAC,CAAC;IAC1D,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAmB,IAAI,CAAC,CAAC;IAE3D,MAAM,OAAO,GAAG,WAAW,CAAC,KAAK,IAAI,EAAE;QACrC,UAAU,CAAC,IAAI,CAAC,CAAC;QACjB,QAAQ,CAAC,IAAI,CAAC,CAAC;QACf,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,iBAAiB,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC;YACvE,QAAQ,CAAC,IAAI,CAAC,CAAC;QACjB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;QAC7B,CAAC;gBAAS,CAAC;YACT,UAAU,CAAC,KAAK,CAAC,CAAC;QACpB,CAAC;IACH,CAAC,EAAE,CAAC,iBAAiB,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC;IAE5C,MAAM,MAAM,GAAG,WAAW,CACxB,KAAK,EAAE,QAAgB,EAAE,aAA6B,EAA2B,EAAE;QACjF,MAAM,OAAO,GAAG,MAAM,iBAAiB,CAAC,WAAW,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;QAC7E,MAAM,OAAO,EAAE,CAAC;QAChB,OAAO,OAAO,CAAC;IACjB,CAAC,EACD,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAC7B,CAAC;IAEF,MAAM,UAAU,GAAG,WAAW,CAC5B,KAAK,EAAE,MAAc,EAAE,aAA6B,EAAiB,EAAE;QACrE,MAAM,iBAAiB,CAAC,UAAU,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;QAC1D,MAAM,OAAO,EAAE,CAAC;IAClB,CAAC,EACD,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAC7B,CAAC;IAEF,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,QAAQ;YAAE,OAAO;QACtB,KAAK,OAAO,EAAE,CAAC;IACjB,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;IAExB,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;AAChE,CAAC"}

package/dist/index.d.ts

@@ -7,8 +7,11 @@ export { useQuestion } from './hooks/use-question.js';
 export { useApproval } from './hooks/use-approval.js';
 export { useSwitchConfig } from './hooks/use-switch-config.js';
 export { useProcessingConversations } from './hooks/use-processing-conversations.js';
+export { useWorkspaceFiles } from './hooks/use-workspace-files.js';
+export type { UseWorkspaceFilesOptions, UseWorkspaceFilesResult } from './hooks/use-workspace-files.js';
 export type { ChatProviderProps, ConnectionState, MessageStatus, ToolCallStatus, ChatError, Conversation, ConversationLastMessageKind, Message, MessageAttachment, ToolCall, QuestionRequest, ApprovalRequestWithId, SendMessageOptions, UploadResult, } from './types.js';
-export type { WorkspaceProvider } from './workspace/types.js';
-export { createDefaultWorkspaceProvider } from './workspace/default-provider.js';
+export type { WorkspaceProvider, WorkspaceFile, FilePreview, ShareLink, UploadProgress, AuthenticatedUploader, UploadOptions, ListOptions, DeleteOptions, } from './workspace/types.js';
+export { WorkspaceFileError } from './workspace/errors.js';
+export { createDefaultWorkspaceProvider, type DefaultWorkspaceProviderOptions, } from './workspace/default-provider.js';
 export type { ServerEvent, ClientEvent, FinishInfo, Question, ApprovalRequest, ApprovalResponse, TokenProgress, BillingError, } from '@optima-chat/gateway-protocol';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAG3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,EAAE,0BAA0B,EAAE,MAAM,yCAAyC,CAAC;AAGrF,YAAY,EACV,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,cAAc,EACd,SAAS,EACT,YAAY,EACZ,2BAA2B,EAC3B,OAAO,EACP,iBAAiB,EACjB,QAAQ,EACR,eAAe,EACf,qBAAqB,EACrB,kBAAkB,EAClB,YAAY,GACb,MAAM,YAAY,CAAC;AAGpB,YAAY,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,8BAA8B,EAAE,MAAM,iCAAiC,CAAC;AAGjF,YAAY,EACV,WAAW,EACX,WAAW,EACX,UAAU,EACV,QAAQ,EACR,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,YAAY,GACb,MAAM,+BAA+B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAG3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,EAAE,0BAA0B,EAAE,MAAM,yCAAyC,CAAC;AACrF,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACnE,YAAY,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAGxG,YAAY,EACV,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,cAAc,EACd,SAAS,EACT,YAAY,EACZ,2BAA2B,EAC3B,OAAO,EACP,iBAAiB,EACjB,QAAQ,EACR,eAAe,EACf,qBAAqB,EACrB,kBAAkB,EAClB,YAAY,GACb,MAAM,YAAY,CAAC;AAGpB,YAAY,EACV,iBAAiB,EACjB,aAAa,EACb,WAAW,EACX,SAAS,EACT,cAAc,EACd,qBAAqB,EACrB,aAAa,EACb,WAAW,EACX,aAAa,GACd,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EACL,8BAA8B,EAC9B,KAAK,+BAA+B,GACrC,MAAM,iCAAiC,CAAC;AAGzC,YAAY,EACV,WAAW,EACX,WAAW,EACX,UAAU,EACV,QAAQ,EACR,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,YAAY,GACb,MAAM,+BAA+B,CAAC"}

package/dist/index.js

@@ -9,5 +9,7 @@ export { useQuestion } from './hooks/use-question.js';
 export { useApproval } from './hooks/use-approval.js';
 export { useSwitchConfig } from './hooks/use-switch-config.js';
 export { useProcessingConversations } from './hooks/use-processing-conversations.js';
-export { createDefaultWorkspaceProvider } from './workspace/default-provider.js';
+export { useWorkspaceFiles } from './hooks/use-workspace-files.js';
+export { WorkspaceFileError } from './workspace/errors.js';
+export { createDefaultWorkspaceProvider, } from './workspace/default-provider.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,WAAW;AACX,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAE3D,QAAQ;AACR,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,EAAE,0BAA0B,EAAE,MAAM,yCAAyC,CAAC;AAsBrF,OAAO,EAAE,8BAA8B,EAAE,MAAM,iCAAiC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,WAAW;AACX,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAE3D,QAAQ;AACR,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,EAAE,0BAA0B,EAAE,MAAM,yCAAyC,CAAC;AACrF,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAiCnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EACL,8BAA8B,GAE/B,MAAM,iCAAiC,CAAC"}

package/dist/workspace/default-provider.d.ts

@@ -1,14 +1,25 @@
-import type { WorkspaceProvider } from './types.js';
+import type { AuthenticatedUploader, WorkspaceProvider } from './types.js';
+export interface DefaultWorkspaceProviderOptions {
+    /** XHR-based uploader for progress events; falls back to `authenticatedFetch` if omitted. */
+    authenticatedUploader?: AuthenticatedUploader;
+}
+type AuthFetch = (url: string, init?: RequestInit) => Promise<Response>;
 /**
- * Default WorkspaceProvider backed by the gateway's workspace endpoints.
- *
- * - `uploadFiles` POSTs each file individually to `/api/workspace/upload` as
- *   FormData (field name `file`) and expects a JSON response with a `url`
- *   field.
- * - `resolveFileUrl` returns a GET URL under `/api/workspace/files/<path>`.
- *
+ * Default WorkspaceProvider backed by the gateway's `/api/user/files/*` family.
  * Consumers with a different backend can pass their own WorkspaceProvider to
- * <ChatProvider>.
+ * `<ChatProvider>`.
+ *
+ * @param gatewayBaseUrl   Gateway origin (e.g. `https://gateway.example.com`).
+ *                         Trailing slash tolerated.
+ * @param authenticatedFetch  Bearer-token-attaching fetch (typically from
+ *                         `@optima-chat/agentic-auth`'s
+ *                         `createAuthenticatedFetch`).
+ * @param options          Optional. Pass `authenticatedUploader` (from the
+ *                         auth package's `createAuthenticatedUploader`) to get
+ *                         per-file upload progress; otherwise upload falls
+ *                         back to plain `authenticatedFetch + FormData`
+ *                         (no progress events).
  */
-export declare function createDefaultWorkspaceProvider(gatewayBaseUrl: string, authenticatedFetch: (url: string, init?: RequestInit) => Promise<Response>): WorkspaceProvider;
+export declare function createDefaultWorkspaceProvider(gatewayBaseUrl: string, authenticatedFetch: AuthFetch, options?: DefaultWorkspaceProviderOptions): WorkspaceProvider;
+export {};
 //# sourceMappingURL=default-provider.d.ts.map

package/dist/workspace/default-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"default-provider.d.ts","sourceRoot":"","sources":["../../src/workspace/default-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAGpD;;;;;;;;;;GAUG;AACH,wBAAgB,8BAA8B,CAC5C,cAAc,EAAE,MAAM,EACtB,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,GACzE,iBAAiB,CAsCnB"}
+{"version":3,"file":"default-provider.d.ts","sourceRoot":"","sources":["../../src/workspace/default-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,qBAAqB,EAOrB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAIpB,MAAM,WAAW,+BAA+B;IAC9C,6FAA6F;IAC7F,qBAAqB,CAAC,EAAE,qBAAqB,CAAC;CAC/C;AAED,KAAK,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AA+CxE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,8BAA8B,CAC5C,cAAc,EAAE,MAAM,EACtB,kBAAkB,EAAE,SAAS,EAC7B,OAAO,GAAE,+BAAoC,GAC5C,iBAAiB,CAsInB"}

package/dist/workspace/default-provider.js

@@ -1,45 +1,170 @@
+import { WorkspaceFileError } from './errors.js';
+function joinContainerPath(dir, name) {
+    return dir.endsWith('/') ? `${dir}${name}` : `${dir}/${name}`;
+}
+function toWorkspaceFile(parentPath, entry) {
+    return {
+        name: entry.name,
+        path: joinContainerPath(parentPath, entry.name),
+        size: entry.size ?? 0,
+        modifiedAt: entry.modified ?? '',
+        type: entry.type,
+        ...(entry.permissions !== undefined && { permissions: entry.permissions }),
+    };
+}
+async function asWorkspaceError(res, fallbackOp) {
+    let code = 'UNKNOWN';
+    let message = `${fallbackOp} failed: ${res.status}`;
+    try {
+        const body = (await res.json());
+        if (body.error?.code)
+            code = body.error.code;
+        if (body.error?.message)
+            message = body.error.message;
+    }
+    catch {
+        // body wasn't JSON — keep defaults
+    }
+    return new WorkspaceFileError(res.status, code, message);
+}
 /**
- * Default WorkspaceProvider backed by the gateway's workspace endpoints.
- *
- * - `uploadFiles` POSTs each file individually to `/api/workspace/upload` as
- *   FormData (field name `file`) and expects a JSON response with a `url`
- *   field.
- * - `resolveFileUrl` returns a GET URL under `/api/workspace/files/<path>`.
- *
+ * Default WorkspaceProvider backed by the gateway's `/api/user/files/*` family.
  * Consumers with a different backend can pass their own WorkspaceProvider to
- * <ChatProvider>.
+ * `<ChatProvider>`.
+ *
+ * @param gatewayBaseUrl   Gateway origin (e.g. `https://gateway.example.com`).
+ *                         Trailing slash tolerated.
+ * @param authenticatedFetch  Bearer-token-attaching fetch (typically from
+ *                         `@optima-chat/agentic-auth`'s
+ *                         `createAuthenticatedFetch`).
+ * @param options          Optional. Pass `authenticatedUploader` (from the
+ *                         auth package's `createAuthenticatedUploader`) to get
+ *                         per-file upload progress; otherwise upload falls
+ *                         back to plain `authenticatedFetch + FormData`
+ *                         (no progress events).
  */
-export function createDefaultWorkspaceProvider(gatewayBaseUrl, authenticatedFetch) {
-    const base = gatewayBaseUrl.endsWith('/')
-        ? gatewayBaseUrl.slice(0, -1)
-        : gatewayBaseUrl;
+export function createDefaultWorkspaceProvider(gatewayBaseUrl, authenticatedFetch, options = {}) {
+    const base = gatewayBaseUrl.endsWith('/') ? gatewayBaseUrl.slice(0, -1) : gatewayBaseUrl;
+    const uploader = options.authenticatedUploader;
+    function buildUrl(path, query) {
+        const qs = query
+            ? Object.entries(query)
+                .filter(([, v]) => v !== undefined)
+                .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+                .join('&')
+            : '';
+        return qs ? `${base}${path}?${qs}` : `${base}${path}`;
+    }
     return {
-        async uploadFiles(files) {
+        async uploadFiles(files, options = {}) {
+            const targetPath = options.path ?? '/home/aiuser';
+            const url = `${base}/api/user/files`;
             const results = [];
             for (const file of files) {
                 const formData = new FormData();
+                // path MUST come before file — gateway sets targetPath as it consumes parts in append order
+                formData.append('path', targetPath);
                 formData.append('file', file);
-                const res = await authenticatedFetch(`${base}/api/workspace/upload`, {
-                    method: 'POST',
-                    body: formData,
-                });
-                if (!res.ok) {
-                    throw new Error(`workspace upload failed for ${file.name}: ${res.status}`);
-                }
-                const data = (await res.json());
-                if (!data.url) {
-                    throw new Error(`workspace upload for ${file.name} did not return a url`);
+                const res = uploader
+                    ? await uploader(url, formData, options.onProgress
+                        ? (progress) => options.onProgress(file, progress)
+                        : undefined)
+                    : await authenticatedFetch(url, { method: 'POST', body: formData });
+                if (!res.ok)
+                    throw await asWorkspaceError(res, 'upload');
+                const body = (await res.json());
+                const uploaded = body.uploaded[0];
+                if (!uploaded) {
+                    throw new WorkspaceFileError(500, 'UNKNOWN', `Upload of ${file.name} returned no entries`);
                 }
                 results.push({
                     originalName: file.name,
-                    url: data.url,
+                    url: uploaded.path,
                     mediaType: file.type,
                 });
             }
             return results;
         },
-        resolveFileUrl(path) {
-            return `${base}/api/workspace/files/${encodeURIComponent(path)}`;
+        async listFiles(opts = {}) {
+            const url = buildUrl('/api/user/files', {
+                path: opts.path,
+                include_stats: opts.includeStats ? 'true' : undefined,
+            });
+            const res = await authenticatedFetch(url);
+            if (!res.ok)
+                throw await asWorkspaceError(res, 'list');
+            const body = (await res.json());
+            return body.files.map((entry) => toWorkspaceFile(body.path, entry));
+        },
+        async previewFile(path) {
+            const url = buildUrl('/api/user/files/preview', { path });
+            const res = await authenticatedFetch(url);
+            if (!res.ok)
+                throw await asWorkspaceError(res, 'preview');
+            const body = (await res.json());
+            return {
+                content: body.content,
+                mimeType: body.mimeType,
+                truncated: body.truncated ?? false,
+                ...(body['X-Original-Size'] !== undefined && { originalSize: body['X-Original-Size'] }),
+            };
+        },
+        async downloadFile(path) {
+            const url = buildUrl('/api/user/files/download', { path });
+            const res = await authenticatedFetch(url);
+            if (!res.ok)
+                throw await asWorkspaceError(res, 'download');
+            return res.blob();
+        },
+        async deleteFile(path, opts = {}) {
+            const url = buildUrl('/api/user/files', {
+                path,
+                recursive: opts.recursive ? 'true' : undefined,
+            });
+            const res = await authenticatedFetch(url, { method: 'DELETE' });
+            if (!res.ok)
+                throw await asWorkspaceError(res, 'delete');
+        },
+        async renameFile(oldPath, newPath) {
+            const res = await authenticatedFetch(`${base}/api/user/files/rename`, {
+                method: 'PUT',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ oldPath, newPath }),
+            });
+            if (!res.ok)
+                throw await asWorkspaceError(res, 'rename');
+        },
+        async makeDirectory(path) {
+            const res = await authenticatedFetch(`${base}/api/user/files/mkdir`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ path }),
+            });
+            if (!res.ok)
+                throw await asWorkspaceError(res, 'mkdir');
+        },
+        async statFile(path) {
+            const url = buildUrl('/api/user/files/stat', { path });
+            const res = await authenticatedFetch(url);
+            if (!res.ok)
+                throw await asWorkspaceError(res, 'stat');
+            const body = (await res.json());
+            // Gateway returns the basename in `name`; reconstruct full path from input.
+            return {
+                name: body.name,
+                path,
+                size: body.size ?? 0,
+                modifiedAt: body.modified ?? '',
+                type: body.type,
+                ...(body.permissions !== undefined && { permissions: body.permissions }),
+            };
+        },
+        async shareFile(path) {
+            const url = buildUrl('/api/user/files/share', { path });
+            const res = await authenticatedFetch(url, { method: 'POST' });
+            if (!res.ok)
+                throw await asWorkspaceError(res, 'share');
+            return (await res.json());
         },
     };
 }

package/dist/workspace/default-provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"default-provider.js","sourceRoot":"","sources":["../../src/workspace/default-provider.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,8BAA8B,CAC5C,cAAsB,EACtB,kBAA0E;IAE1E,MAAM,IAAI,GAAG,cAAc,CAAC,QAAQ,CAAC,GAAG,CAAC;QACvC,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAC7B,CAAC,CAAC,cAAc,CAAC;IAEnB,OAAO;QACL,KAAK,CAAC,WAAW,CAAC,KAAa;YAC7B,MAAM,OAAO,GAAmB,EAAE,CAAC;YACnC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,MAAM,QAAQ,GAAG,IAAI,QAAQ,EAAE,CAAC;gBAChC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;gBAC9B,MAAM,GAAG,GAAG,MAAM,kBAAkB,CAAC,GAAG,IAAI,uBAAuB,EAAE;oBACnE,MAAM,EAAE,MAAM;oBACd,IAAI,EAAE,QAAQ;iBACf,CAAC,CAAC;gBACH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;oBACZ,MAAM,IAAI,KAAK,CACb,+BAA+B,IAAI,CAAC,IAAI,KAAK,GAAG,CAAC,MAAM,EAAE,CAC1D,CAAC;gBACJ,CAAC;gBACD,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAqB,CAAC;gBACpD,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;oBACd,MAAM,IAAI,KAAK,CACb,wBAAwB,IAAI,CAAC,IAAI,uBAAuB,CACzD,CAAC;gBACJ,CAAC;gBACD,OAAO,CAAC,IAAI,CAAC;oBACX,YAAY,EAAE,IAAI,CAAC,IAAI;oBACvB,GAAG,EAAE,IAAI,CAAC,GAAG;oBACb,SAAS,EAAE,IAAI,CAAC,IAAI;iBACrB,CAAC,CAAC;YACL,CAAC;YACD,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,cAAc,CAAC,IAAY;YACzB,OAAO,GAAG,IAAI,wBAAwB,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC;QACnE,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"default-provider.js","sourceRoot":"","sources":["../../src/workspace/default-provider.ts"],"names":[],"mappings":"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"}

package/dist/workspace/errors.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Error raised by the default WorkspaceProvider when the gateway returns a
+ * non-2xx response. Consumers can branch on `status` (e.g. 409 = directory
+ * non-empty, 503 = signed-URL not configured) and `code` (gateway's symbolic
+ * error code) without parsing message strings.
+ */
+export declare class WorkspaceFileError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/workspace/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/workspace/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAM1D"}

package/dist/workspace/errors.js

@@ -0,0 +1,17 @@
+/**
+ * Error raised by the default WorkspaceProvider when the gateway returns a
+ * non-2xx response. Consumers can branch on `status` (e.g. 409 = directory
+ * non-empty, 503 = signed-URL not configured) and `code` (gateway's symbolic
+ * error code) without parsing message strings.
+ */
+export class WorkspaceFileError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.name = 'WorkspaceFileError';
+        this.status = status;
+        this.code = code;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/workspace/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/workspace/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAClC,MAAM,CAAS;IACf,IAAI,CAAS;IAEtB,YAAY,MAAc,EAAE,IAAY,EAAE,OAAe;QACvD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF"}

package/dist/workspace/types.d.ts

@@ -1,11 +1,78 @@
 import type { UploadResult } from '../types.js';
 /**
- * WorkspaceProvider — consumer-supplied abstraction for file upload and URL
- * resolution. The default implementation uploads to the gateway's workspace
- * endpoint, but consumers may provide their own (e.g. signed S3 uploads).
+ * A file or directory entry in the user's workspace.
+ *
+ * `path` is a container-style absolute path (e.g. `/home/aiuser/uploads/foo.txt`)
+ * — the same form the gateway accepts as `?path=`. `modifiedAt` is whatever the
+ * gateway returned in the `modified` field; consumers should treat it as opaque.
+ */
+export interface WorkspaceFile {
+    name: string;
+    path: string;
+    /** File size in bytes. For directories, this is whatever the gateway reports (typically 0 or the inode size). */
+    size: number;
+    modifiedAt: string;
+    type: 'file' | 'directory';
+    permissions?: string;
+}
+export interface FilePreview {
+    content: string;
+    mimeType: string;
+    /** True when content was truncated at the gateway's 1MB cap. */
+    truncated: boolean;
+    /** Total bytes of the underlying file. Always present when `truncated` is true (gateway pairs the two). */
+    originalSize?: number;
+}
+export interface ShareLink {
+    url: string;
+    /** ISO-8601 string, mirrors gateway response. */
+    expiresAt: string;
+    fileName: string;
+    fileSize: number;
+}
+/** Per-file upload progress, mirrors `@optima-chat/agentic-auth`'s `UploadProgress`. */
+export interface UploadProgress {
+    loaded: number;
+    total: number;
+    percentage: number;
+}
+/**
+ * Optional progress-capable uploader, structurally compatible with
+ * `createAuthenticatedUploader` from `@optima-chat/agentic-auth`. Keeping this
+ * as a structural type means the SDK does not depend on the auth package.
+ */
+export type AuthenticatedUploader = (url: string, formData: FormData, onProgress?: (progress: UploadProgress) => void) => Promise<Response>;
+export interface UploadOptions {
+    /** Target directory (defaults to `/home/aiuser`). */
+    path?: string;
+    /** Per-file progress callback. Implementations that don't track progress may ignore this option. */
+    onProgress?: (file: File, progress: UploadProgress) => void;
+}
+export interface ListOptions {
+    /** Container path to list; defaults to workspace root. */
+    path?: string;
+    /** When true, populate `size`/`modifiedAt`/`permissions` on each entry. */
+    includeStats?: boolean;
+}
+export interface DeleteOptions {
+    /** Required to delete a non-empty directory; otherwise gateway returns 409. */
+    recursive?: boolean;
+}
+/**
+ * Consumer-supplied abstraction for workspace file operations. The default
+ * implementation (`createDefaultWorkspaceProvider`) targets the gateway's
+ * `/api/user/files/*` family. Consumers can swap in their own (e.g. signed-S3)
+ * provider as long as the contract holds.
  */
 export interface WorkspaceProvider {
-    uploadFiles: (files: File[]) => Promise<UploadResult[]>;
-    resolveFileUrl: (path: string) => string;
+    uploadFiles: (files: File[], options?: UploadOptions) => Promise<UploadResult[]>;
+    listFiles: (options?: ListOptions) => Promise<WorkspaceFile[]>;
+    previewFile: (path: string) => Promise<FilePreview>;
+    downloadFile: (path: string) => Promise<Blob>;
+    deleteFile: (path: string, options?: DeleteOptions) => Promise<void>;
+    renameFile: (oldPath: string, newPath: string) => Promise<void>;
+    makeDirectory: (path: string) => Promise<void>;
+    statFile: (path: string) => Promise<WorkspaceFile>;
+    shareFile: (path: string) => Promise<ShareLink>;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/workspace/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/workspace/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IACxD,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;CAC1C"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/workspace/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,iHAAiH;IACjH,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,SAAS,EAAE,OAAO,CAAC;IACnB,2GAA2G;IAC3G,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wFAAwF;AACxF,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAClC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,QAAQ,EAClB,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,cAAc,KAAK,IAAI,KAC5C,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEvB,MAAM,WAAW,aAAa;IAC5B,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oGAAoG;IACpG,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,cAAc,KAAK,IAAI,CAAC;CAC7D;AAED,MAAM,WAAW,WAAW;IAC1B,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,+EAA+E;IAC/E,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,OAAO,CAAC,EAAE,aAAa,KAAK,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IACjF,SAAS,EAAE,CAAC,OAAO,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IAC/D,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;IACpD,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrE,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;IACnD,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;CACjD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optima-chat/agentic-sdk",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Chat core logic for Optima gateway - Provider, hooks, store, WebSocket client",
   "license": "UNLICENSED",
   "type": "module",