@panelwave/mcp 0.0.0-stage → 0.1.0

package/dist/remote.d.ts

@@ -0,0 +1,79 @@
+import { Client, type CallToolResult, type FetchLike, type ReadResourceResult, type Resource, type Tool, type Transport, type VersionNegotiationOptions } from '@modelcontextprotocol/client';
+/** A resource template as `resources/templates/list` returns it. */
+export type RemoteResourceTemplate = {
+    uriTemplate: string;
+    name: string;
+    [key: string]: unknown;
+};
+export interface RemoteProxyOptions {
+    url: string;
+    token: string;
+    version: string;
+    /** Transport override (tests: an in-memory pair). Default: Streamable HTTP with the bearer header. */
+    transportFactory?: () => Transport;
+    /** fetch override for the default Streamable HTTP transport. */
+    fetch?: FetchLike;
+    versionNegotiation?: VersionNegotiationOptions;
+    /** Called after the remote tool list changed (and was re-read). */
+    onToolsChanged?: () => void;
+    /** Called after the remote resource list changed. */
+    onResourcesChanged?: () => void;
+    log?: (message: string) => void;
+    /** Per-request timeout; reset on every progress notification. Default 5 min. */
+    requestTimeoutMs?: number;
+    /** Hard cap for one tool call including progress resets. Default 30 min. */
+    maxCallMs?: number;
+}
+export interface CallOptions {
+    signal?: AbortSignal;
+    onprogress?: (p: {
+        progress: number;
+        total?: number;
+        message?: string;
+    }) => void;
+}
+/**
+ * Mirrors the hosted PanelWave MCP server: tools/list (names untouched),
+ * tools/call, resources/list, resources/templates/list and resources/read.
+ * Connects lazily and reconnects after transport failures, so the bridge
+ * starts (and its local tools work) even while the remote is unreachable.
+ */
+export declare class RemoteProxy {
+    private readonly opts;
+    private client?;
+    private connecting?;
+    private toolCache?;
+    instructions?: string;
+    serverVersion?: {
+        name: string;
+        version: string;
+    };
+    /** Called after the remote tool list changed (the bridge re-announces it downstream). */
+    onToolsChanged?: () => void;
+    /** Called after the remote resource list changed. */
+    onResourcesChanged?: () => void;
+    constructor(opts: RemoteProxyOptions);
+    private log;
+    get connected(): boolean;
+    /** Connect (once); concurrent callers share the attempt, a failure is retried by the next call. */
+    connect(): Promise<Client>;
+    private transport;
+    private open;
+    /**
+     * Transport-level failures become BridgeErrors (UNAUTHENTICATED /
+     * UPSTREAM_UNAVAILABLE) and drop the connection; JSON-RPC errors from the
+     * remote pass through unchanged.
+     */
+    private mapFailure;
+    private drop;
+    private withClient;
+    /** All remote tools (every page), cached until the remote signals list_changed. */
+    listTools(): Promise<Tool[]>;
+    /** Whether `name` is a known remote tool (from the last listing). */
+    hasTool(name: string): boolean;
+    callTool(name: string, args: Record<string, unknown> | undefined, opts?: CallOptions): Promise<CallToolResult>;
+    listResources(): Promise<Resource[]>;
+    listResourceTemplates(): Promise<RemoteResourceTemplate[]>;
+    readResource(uri: string, signal?: AbortSignal): Promise<ReadResourceResult>;
+    close(): Promise<void>;
+}

package/dist/remote.js

@@ -0,0 +1,207 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RemoteProxy = void 0;
+const client_1 = require("@modelcontextprotocol/client");
+const errors_1 = require("./errors");
+/**
+ * Mirrors the hosted PanelWave MCP server: tools/list (names untouched),
+ * tools/call, resources/list, resources/templates/list and resources/read.
+ * Connects lazily and reconnects after transport failures, so the bridge
+ * starts (and its local tools work) even while the remote is unreachable.
+ */
+class RemoteProxy {
+    opts;
+    client;
+    connecting;
+    toolCache;
+    instructions;
+    serverVersion;
+    /** Called after the remote tool list changed (the bridge re-announces it downstream). */
+    onToolsChanged;
+    /** Called after the remote resource list changed. */
+    onResourcesChanged;
+    constructor(opts) {
+        this.opts = opts;
+        this.onToolsChanged = opts.onToolsChanged;
+        this.onResourcesChanged = opts.onResourcesChanged;
+    }
+    log(message) {
+        this.opts.log?.(message);
+    }
+    get connected() {
+        return !!this.client;
+    }
+    /** Connect (once); concurrent callers share the attempt, a failure is retried by the next call. */
+    async connect() {
+        if (this.client)
+            return this.client;
+        if (!this.connecting) {
+            this.connecting = this.open().finally(() => {
+                this.connecting = undefined;
+            });
+        }
+        return this.connecting;
+    }
+    transport() {
+        if (this.opts.transportFactory)
+            return this.opts.transportFactory();
+        return new client_1.StreamableHTTPClientTransport(new URL(this.opts.url), {
+            requestInit: { headers: { Authorization: `Bearer ${this.opts.token}`, 'User-Agent': `panelwave-mcp/${this.opts.version}` } },
+            ...(this.opts.fetch ? { fetch: this.opts.fetch } : {}),
+        });
+    }
+    async open() {
+        const client = new client_1.Client({ name: 'panelwave-mcp-bridge', version: this.opts.version }, {
+            capabilities: {},
+            versionNegotiation: this.opts.versionNegotiation ?? { mode: 'auto' },
+            listChanged: {
+                tools: {
+                    onChanged: (error, items) => {
+                        if (error) {
+                            this.log(`remote tool list refresh failed: ${error.message}`);
+                            this.toolCache = undefined;
+                        }
+                        else if (items) {
+                            this.toolCache = items;
+                        }
+                        this.onToolsChanged?.();
+                    },
+                },
+                resources: {
+                    onChanged: () => this.onResourcesChanged?.(),
+                },
+            },
+        });
+        client.onclose = () => {
+            if (this.client === client) {
+                this.client = undefined;
+                this.toolCache = undefined;
+            }
+        };
+        client.onerror = (e) => this.log(`remote transport error: ${e.message}`);
+        try {
+            await client.connect(this.transport());
+        }
+        catch (e) {
+            await client.close().catch(() => undefined);
+            throw this.mapFailure(e, 'connect');
+        }
+        this.client = client;
+        this.instructions = client.getInstructions();
+        this.serverVersion = client.getServerVersion();
+        return client;
+    }
+    /**
+     * Transport-level failures become BridgeErrors (UNAUTHENTICATED /
+     * UPSTREAM_UNAVAILABLE) and drop the connection; JSON-RPC errors from the
+     * remote pass through unchanged.
+     */
+    mapFailure(e, what) {
+        if (e instanceof client_1.ProtocolError)
+            return e;
+        if (e instanceof errors_1.BridgeError)
+            return e;
+        const status = e instanceof client_1.SdkHttpError ? e.status : undefined;
+        if (e instanceof client_1.UnauthorizedError || status === 401) {
+            this.drop();
+            return new errors_1.BridgeError('UNAUTHENTICATED', 'PanelWave rejected PANELWAVE_TOKEN (expired, revoked or mistyped). Create a new personal access token in PanelWave (Profile → Connected apps & access tokens) and update the MCP client configuration.');
+        }
+        if (status === 403) {
+            return new errors_1.BridgeError('UNAUTHENTICATED', `PanelWave refused the request (HTTP 403). The token may lack the scopes this tool needs.`);
+        }
+        if (e instanceof client_1.SdkError && e.code === 'REQUEST_TIMEOUT') {
+            return new errors_1.BridgeError('UPSTREAM_UNAVAILABLE', `The PanelWave server did not answer in time (${what}). Check the job with pw_jobs_get or retry.`);
+        }
+        if (e instanceof client_1.SdkError && e.code === 'INVALID_RESULT') {
+            return new errors_1.BridgeError('INTERNAL', `The PanelWave server sent a result the bridge could not validate: ${e.message}`);
+        }
+        this.drop();
+        const reason = e instanceof Error ? e.message : String(e);
+        return new errors_1.BridgeError('UPSTREAM_UNAVAILABLE', `Cannot reach the PanelWave MCP server at ${this.opts.url} (${reason}). Local tools still work; retry in a moment.`);
+    }
+    drop() {
+        const c = this.client;
+        this.client = undefined;
+        this.toolCache = undefined;
+        void c?.close().catch(() => undefined);
+    }
+    async withClient(what, fn) {
+        const client = await this.connect();
+        try {
+            return await fn(client);
+        }
+        catch (e) {
+            throw this.mapFailure(e, what);
+        }
+    }
+    /** All remote tools (every page), cached until the remote signals list_changed. */
+    async listTools() {
+        if (this.client && this.toolCache)
+            return this.toolCache;
+        const tools = await this.withClient('tools/list', async (c) => {
+            const all = [];
+            let cursor;
+            do {
+                const page = await c.listTools(cursor ? { cursor } : undefined);
+                all.push(...page.tools);
+                cursor = page.nextCursor;
+            } while (cursor);
+            return all;
+        });
+        this.toolCache = tools;
+        return tools;
+    }
+    /** Whether `name` is a known remote tool (from the last listing). */
+    hasTool(name) {
+        return !!this.toolCache?.some((t) => t.name === name);
+    }
+    async callTool(name, args, opts = {}) {
+        // The client validates structured results against the listed output schemas — make sure it has them.
+        if (!this.toolCache || !this.client)
+            await this.listTools();
+        return this.withClient(`tools/call ${name}`, (c) => c.callTool({ name, arguments: args ?? {} }, {
+            signal: opts.signal,
+            onprogress: opts.onprogress,
+            timeout: this.opts.requestTimeoutMs ?? 5 * 60_000,
+            resetTimeoutOnProgress: true,
+            maxTotalTimeout: this.opts.maxCallMs ?? 30 * 60_000,
+        }));
+    }
+    async listResources() {
+        return this.withClient('resources/list', async (c) => {
+            if (!c.getServerCapabilities()?.resources)
+                return [];
+            const all = [];
+            let cursor;
+            do {
+                const page = await c.listResources(cursor ? { cursor } : undefined);
+                all.push(...page.resources);
+                cursor = page.nextCursor;
+            } while (cursor);
+            return all;
+        });
+    }
+    async listResourceTemplates() {
+        return this.withClient('resources/templates/list', async (c) => {
+            if (!c.getServerCapabilities()?.resources)
+                return [];
+            const all = [];
+            let cursor;
+            do {
+                const page = await c.listResourceTemplates(cursor ? { cursor } : undefined);
+                all.push(...page.resourceTemplates);
+                cursor = page.nextCursor;
+            } while (cursor);
+            return all;
+        });
+    }
+    async readResource(uri, signal) {
+        return this.withClient(`resources/read ${uri}`, (c) => c.readResource({ uri }, { signal }));
+    }
+    async close() {
+        const c = this.client;
+        this.client = undefined;
+        await c?.close().catch(() => undefined);
+    }
+}
+exports.RemoteProxy = RemoteProxy;

package/dist/sandbox.d.ts

@@ -0,0 +1,7 @@
+export interface ResolveOptions {
+    /** Allow path segments starting with "." (dotfiles, .ssh, .git …). Default true; pw_local_read_text passes false. */
+    allowHidden?: boolean;
+}
+/** `\\server\share`, `\\?\…`, `\\.\…` (and the forward-slash spellings Windows accepts). */
+export declare function isUncOrDevicePath(p: string): boolean;
+export declare function resolveAllowed(requested: string, allowedDirs: string[], opts?: ResolveOptions): string;

package/dist/sandbox.js

@@ -0,0 +1,107 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isUncOrDevicePath = isUncOrDevicePath;
+exports.resolveAllowed = resolveAllowed;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const errors_1 = require("./errors");
+/**
+ * Path sandbox of the local tools: every path must resolve — symlinks
+ * followed — inside one of the allowed directories (PANELWAVE_ALLOWED_DIRS).
+ * Relative paths are taken relative to the first allowed directory.
+ *
+ * The containment check runs on the resolved TEXT first, before any
+ * filesystem call: on Windows even a realpath of `\\host\share\x` opens an SMB
+ * connection and sends the user's NTLM hash to that host (security review
+ * 2026-09-30). UNC and device paths (`\\?\`, `\\.\`) are refused unless an
+ * allowed directory is itself on that share. Only then are symlinks resolved
+ * and the check repeated on the real path.
+ */
+const caseInsensitive = process.platform === 'win32' || process.platform === 'darwin';
+function real(p) {
+    try {
+        return fs.realpathSync.native(p);
+    }
+    catch {
+        // Not there (yet): resolve the nearest existing parent so a symlinked
+        // parent cannot smuggle the path out of the sandbox.
+        const parent = path.dirname(p);
+        if (parent === p)
+            return p;
+        return path.join(real(parent), path.basename(p));
+    }
+}
+function norm(p) {
+    return caseInsensitive ? p.toLowerCase() : p;
+}
+function relativeInside(child, parent) {
+    const rel = path.relative(norm(parent), norm(child));
+    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel)) ? rel : undefined;
+}
+/** `\\server\share`, `\\?\…`, `\\.\…` (and the forward-slash spellings Windows accepts). */
+function isUncOrDevicePath(p) {
+    return /^[\\/]{2}/.test(p);
+}
+function outside(requested, allowedDirs) {
+    return new errors_1.BridgeError('INVALID_INPUT', `${requested} is outside the folders this bridge may read (${allowedDirs.join(', ')}). Add the folder to PANELWAVE_ALLOWED_DIRS in the MCP client configuration.`);
+}
+function resolveAllowed(requested, allowedDirs, opts = {}) {
+    if (!requested || typeof requested !== 'string')
+        throw new errors_1.BridgeError('INVALID_INPUT', 'Pass a path.');
+    if (requested.includes('\0'))
+        throw new errors_1.BridgeError('INVALID_INPUT', 'Invalid path.');
+    if (!allowedDirs.length) {
+        throw new errors_1.BridgeError('PRECONDITION_FAILED', 'No local folders are allowed. Set PANELWAVE_ALLOWED_DIRS in the MCP client configuration to use the local tools.');
+    }
+    const absolute = path.resolve(allowedDirs[0], requested);
+    // 1. Text-only containment, before touching the filesystem.
+    const unc = process.platform === 'win32' && isUncOrDevicePath(absolute);
+    const textual = allowedDirs.find((d) => relativeInside(absolute, path.resolve(d)) !== undefined);
+    if (!textual || (unc && !isUncOrDevicePath(path.resolve(textual))))
+        throw outside(requested, allowedDirs);
+    // 2. Symlinks and junctions resolved; the real path must still be inside a real allowed directory.
+    const resolved = real(absolute);
+    for (const d of allowedDirs) {
+        const rel = relativeInside(resolved, real(d));
+        if (rel === undefined)
+            continue;
+        if (opts.allowHidden === false && rel.split(/[\\/]/).some((seg) => seg.startsWith('.') && seg !== '.' && seg !== '..')) {
+            throw new errors_1.BridgeError('INVALID_INPUT', `${requested} is a hidden file or inside a hidden folder; the bridge does not read those.`);
+        }
+        return resolved;
+    }
+    throw outside(requested, allowedDirs);
+}

package/dist/tool.d.ts

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+/** A CallToolResult as the bridge produces it (text summary + structured data). */
+export interface LocalToolResult {
+    [key: string]: unknown;
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+}
+/** The subset of a remote CallToolResult the local tools read. */
+export interface RemoteResult {
+    content?: unknown[];
+    structuredContent?: unknown;
+    isError?: boolean;
+}
+/** Calls a tool of the hosted PanelWave server (the bridge wires this to the RemoteProxy). */
+export type RemoteCaller = (name: string, args: Record<string, unknown>, signal?: AbortSignal) => Promise<RemoteResult>;
+export interface LocalToolContext {
+    allowedDirs: string[];
+    signal?: AbortSignal;
+    /** Progress reporter — a no-op when the client did not ask for progress. */
+    progress?: (progress: number, total?: number, message?: string) => Promise<void>;
+    /** Hosted tools, for local tools that combine local files with PanelWave (uploads). */
+    callRemote?: RemoteCaller;
+}
+export interface LocalTool {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    annotations: Record<string, unknown>;
+    call(args: unknown, ctx: LocalToolContext): Promise<LocalToolResult>;
+}
+export declare const READ_ONLY: {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+};
+export declare function errorResult(e: unknown): LocalToolResult;
+/** Define a local tool: zod input/output, JSON Schemas derived, errors mapped to isError results. */
+export declare function defineLocalTool<I extends z.ZodType, O extends z.ZodType>(def: {
+    name: string;
+    title: string;
+    description: string;
+    input: I;
+    output: O;
+    annotations?: Record<string, unknown>;
+    run(args: z.output<I>, ctx: LocalToolContext): Promise<{
+        text: string;
+        data: z.input<O>;
+    }>;
+}): LocalTool;
+export declare function formatBytes(n: number): string;
+/** Run `fn` over `items` with at most `limit` in flight; results keep the input order. */
+export declare function mapLimit<T, R>(items: T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;

package/dist/tool.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.READ_ONLY = void 0;
+exports.errorResult = errorResult;
+exports.defineLocalTool = defineLocalTool;
+exports.formatBytes = formatBytes;
+exports.mapLimit = mapLimit;
+const zod_1 = require("zod");
+const errors_1 = require("./errors");
+exports.READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+function jsonSchema(schema, io) {
+    const s = zod_1.z.toJSONSchema(schema, { io, unrepresentable: 'any' });
+    delete s.$schema;
+    return s;
+}
+function errorResult(e) {
+    const err = (0, errors_1.toBridgeError)(e);
+    const body = { code: err.code, message: err.message };
+    if (err.details !== undefined)
+        body.details = err.details;
+    return { isError: true, content: [{ type: 'text', text: `${err.code}: ${err.message}` }], structuredContent: body };
+}
+function parseArgs(schema, args) {
+    const parsed = schema.safeParse(args ?? {});
+    if (parsed.success)
+        return parsed.data;
+    const issues = parsed.error.issues.slice(0, 10).map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`);
+    throw new errors_1.BridgeError('INVALID_INPUT', `Invalid arguments — ${issues.join('; ')}`, { issues });
+}
+/** Define a local tool: zod input/output, JSON Schemas derived, errors mapped to isError results. */
+function defineLocalTool(def) {
+    return {
+        name: def.name,
+        title: def.title,
+        description: def.description,
+        inputSchema: jsonSchema(def.input, 'input'),
+        outputSchema: jsonSchema(def.output, 'output'),
+        annotations: { title: def.title, ...(def.annotations ?? exports.READ_ONLY) },
+        async call(args, ctx) {
+            try {
+                const out = await def.run(parseArgs(def.input, args), ctx);
+                return { content: [{ type: 'text', text: out.text }], structuredContent: out.data };
+            }
+            catch (e) {
+                return errorResult(e);
+            }
+        },
+    };
+}
+function formatBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    if (n < 1024 * 1024 * 1024)
+        return `${(n / 1024 / 1024).toFixed(1)} MB`;
+    return `${(n / 1024 / 1024 / 1024).toFixed(2)} GB`;
+}
+/** Run `fn` over `items` with at most `limit` in flight; results keep the input order. */
+async function mapLimit(items, limit, fn) {
+    const out = new Array(items.length);
+    let next = 0;
+    const workers = Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, async () => {
+        while (next < items.length) {
+            const i = next++;
+            out[i] = await fn(items[i], i);
+        }
+    });
+    await Promise.all(workers);
+    return out;
+}

package/dist/upload.d.ts

@@ -0,0 +1,76 @@
+import { type FileKind } from './files';
+import { type RemoteCaller } from './tool';
+/** Kinds the asset library accepts. */
+export declare const UPLOADABLE_KINDS: ReadonlySet<FileKind>;
+export declare const MAX_FILES = 500;
+export declare const MAX_ATTEMPTS = 3;
+export declare function sha256File(file: string, signal?: AbortSignal): Promise<string>;
+/** Call a hosted tool and return its structured result; an isError result is re-raised with the remote code. */
+export declare function remoteData(call: RemoteCaller, name: string, args: Record<string, unknown>, signal?: AbortSignal): Promise<Record<string, unknown>>;
+export interface UploadFile {
+    /** Absolute path (inside the sandbox). */
+    abs: string;
+    /** How the caller named it (relative path or as given). */
+    display: string;
+    size: number;
+}
+export interface UploadRow {
+    path: string;
+    filename: string;
+    ok: boolean;
+    status: 'uploaded' | 'exists' | 'failed' | 'cancelled';
+    assetId?: string;
+    deduplicated: boolean;
+    kind?: string;
+    mimeType: string;
+    sizeBytes: number;
+    sha256?: string;
+    width?: number;
+    height?: number;
+    mode?: 'single' | 'multipart';
+    attempts?: number;
+    processing?: boolean;
+    warnings: string[];
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+export interface UploadOptions {
+    workId: string;
+    files: UploadFile[];
+    callRemote: RemoteCaller;
+    folderId?: string;
+    tags?: string[];
+    skipDuplicates: boolean;
+    concurrency: number;
+    signal?: AbortSignal;
+    /** Monotonic byte progress over the whole batch. */
+    onProgress?: (doneBytes: number, totalBytes: number, message: string) => void;
+    fetch?: typeof fetch;
+    /** Tests only: allow plain-http upload hosts beyond loopback. */
+    allowInsecureUploadHosts?: boolean;
+    /** Base backoff between attempts (tripled per attempt). Default 500 ms. */
+    retryDelayMs?: number;
+}
+/**
+ * Upload URLs come from the hosted server. Accept only https, or plain http to a
+ * loopback host (a local MinIO in development) — never another scheme or a
+ * plain-http host on the network (security review 2026-09-30).
+ */
+export declare function assertUploadTarget(url: string, opts?: Pick<UploadOptions, 'allowInsecureUploadHosts'>): string;
+/** Headers for the storage PUT: never credentials or hop-by-hop headers, whatever the server suggests. */
+export declare function safeUploadHeaders(headers: Record<string, string> | undefined): Record<string, string>;
+/**
+ * Upload local files into a work's asset library through the hosted tools
+ * (pw_assets_begin_upload → PUT / multipart parts → pw_assets_complete_upload).
+ * Files run `concurrency` at a time; parts of one file run in order, each read
+ * from disk just before its PUT, so memory stays at one part per file.
+ */
+export declare function uploadBatch(opts: UploadOptions): Promise<UploadRow[]>;
+/** Resolve (and create when missing) a folder path like "Chapter 1/Panels". */
+export declare function ensureFolder(call: RemoteCaller, workId: string, folderPath: string, signal?: AbortSignal): Promise<{
+    folderId: string;
+    created: boolean;
+}>;
+export declare const uploadFiles: import("./tool").LocalTool;