@tai42/api-client 16.0.0 → 16.0.1

package/dist/client/settings-schema-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-schema-client.js","sourceRoot":"","sources":["../../src/client/settings-schema-client.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,OAAO,KAAK,CAAC,MAAM,YAAY,CAAC;AAGhC,MAAM,UAAU,oBAAoB,CAAC,CAAY;IAC/C,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IAClB,OAAO;QACL,iBAAiB,EAAE,CAAC,MAAoB,EAAE,EAAE,CAC1C,GAAG,CAAC,6BAA6B,EAAE,CAAC,CAAC,cAAc,EAAE,EAAE,MAAM,EAAE,CAAC;KACnE,CAAC;AACJ,CAAC"}

package/dist/client/states-client.d.ts

@@ -0,0 +1,471 @@
+/** State declaration, record, template and consumer sub-client. */
+import * as s from '../schemas';
+import type { Transport } from './transport';
+/**
+ * The client-facing write body for a state declaration (`PUT /api/states/{name}`), the
+ * wire shape of `tai42_contract.states.StateDeclaration` minus the platform-computed
+ * `effective_schema`/`regimes` (those are read-only, refused on a write). `schema` is the
+ * `TemplatedText | dict` union: an inline JSON-schema object, or a stored template reference
+ * (`id` + render `kwargs`) the platform renders to the schema. `retention_days` is `null` to
+ * keep records forever.
+ */
+export interface StateDeclarationBody {
+    readonly name: string;
+    readonly description?: string;
+    readonly schema: s.TemplatedText | Record<string, unknown>;
+    readonly subject_kinds: readonly string[];
+    readonly default_subject_kind: string;
+    readonly retention_days?: number | null;
+}
+/**
+ * A state-template document write body (`PUT /api/state-templates/{name}`, the platform half).
+ * `schema` is the `TemplatedText | dict` union — an inline fragment schema, or a stored
+ * template reference the platform renders to the fragment.
+ */
+export interface StateTemplateBody {
+    readonly name: string;
+    readonly description?: string;
+    readonly parameters?: Record<string, unknown>;
+    readonly schema: s.TemplatedText | Record<string, unknown>;
+    readonly regimes?: Record<string, unknown>[];
+    readonly declarations?: Record<string, unknown> | null;
+    readonly trace?: Record<string, unknown>;
+}
+/** A template attach / re-attach body (`PUT|PATCH /api/states/{name}/attachments/{template}`). */
+export interface StateAttachmentBody {
+    readonly path?: string[];
+    readonly parameters?: Record<string, unknown>;
+    readonly declarations?: Record<string, unknown>;
+    readonly options?: Record<string, unknown>;
+}
+/** The four-part subject a record route addresses in its path. */
+export interface StateSubjectRef {
+    readonly target_kind: string;
+    readonly target_name: string;
+    readonly kind: string;
+    readonly key: string;
+}
+/** A keyset page request: an optional size and the opaque cursor a prior page returned. */
+export interface StatePageQuery {
+    readonly limit?: number;
+    readonly cursor?: string;
+}
+export declare function statesClient(t: Transport): {
+    listStates: (signal?: AbortSignal) => Promise<{
+        default_subject_kind: string;
+        description: string;
+        effective_schema: Record<string, unknown> | null;
+        name: string;
+        regimes: Record<string, unknown>[] | null;
+        retention_days: number | null;
+        subject_kinds: string[];
+        updated_at: string | null;
+        schema?: Record<string, unknown> | {
+            content?: string | undefined;
+            id?: string | undefined;
+            kwargs?: Record<string, unknown> | undefined;
+        } | undefined;
+    }[]>;
+    getState: (name: string, signal?: AbortSignal) => Promise<{
+        default_subject_kind: string;
+        description: string;
+        effective_schema: Record<string, unknown> | null;
+        name: string;
+        regimes: Record<string, unknown>[] | null;
+        retention_days: number | null;
+        subject_kinds: string[];
+        updated_at: string | null;
+        attachments: {
+            template: string;
+            path: string[];
+            parameters: Record<string, unknown>;
+            declarations: Record<string, unknown>;
+        }[];
+        schema?: Record<string, unknown> | {
+            content?: string | undefined;
+            id?: string | undefined;
+            kwargs?: Record<string, unknown> | undefined;
+        } | undefined;
+    }>;
+    putState: (name: string, body: StateDeclarationBody) => Promise<{
+        default_subject_kind: string;
+        description: string;
+        effective_schema: Record<string, unknown> | null;
+        name: string;
+        regimes: Record<string, unknown>[] | null;
+        retention_days: number | null;
+        subject_kinds: string[];
+        updated_at: string | null;
+        attachments: {
+            template: string;
+            path: string[];
+            parameters: Record<string, unknown>;
+            declarations: Record<string, unknown>;
+        }[];
+        schema?: Record<string, unknown> | {
+            content?: string | undefined;
+            id?: string | undefined;
+            kwargs?: Record<string, unknown> | undefined;
+        } | undefined;
+    }>;
+    deleteState: (name: string) => Promise<{
+        name: string;
+        deleted: true;
+    }>;
+    getStateStats: (name: string, signal?: AbortSignal) => Promise<{
+        records: number;
+        per_field: Record<string, number>;
+        per_kind: Record<string, number>;
+        consumers: number;
+    }>;
+    listStateAttachments: (name: string, signal?: AbortSignal) => Promise<{
+        template: string;
+        path: string[];
+        parameters: Record<string, unknown>;
+        declarations: Record<string, unknown>;
+    }[]>;
+    getStateAttachment: (name: string, template: string, signal?: AbortSignal) => Promise<{
+        template: string;
+        path: string[];
+        parameters: Record<string, unknown>;
+        declarations: Record<string, unknown>;
+    }>;
+    attachStateTemplate: (name: string, template: string, body: StateAttachmentBody) => Promise<{
+        attached: true;
+        state: string;
+        template: string;
+    }>;
+    patchStateAttachment: (name: string, template: string, body: StateAttachmentBody) => Promise<{
+        updated: true;
+        state: string;
+        template: string;
+    }>;
+    detachStateTemplate: (name: string, template: string) => Promise<{
+        detached: true;
+        state: string;
+        template: string;
+    }>;
+    listStateSubjects: (name: string, params: {
+        kind?: string;
+    } & StatePageQuery, signal?: AbortSignal) => Promise<{
+        subjects: {
+            subject: {
+                target_kind: "tool" | "agent";
+                target_name: string;
+                kind: string;
+                key: string;
+            };
+            updated_at: number;
+        }[];
+        next_cursor: string | null;
+    }>;
+    searchStateRecords: (name: string, body: {
+        filters: Record<string, unknown>;
+    } & StatePageQuery, signal?: AbortSignal) => Promise<{
+        matches: {
+            subject: {
+                target_kind: "tool" | "agent";
+                target_name: string;
+                kind: string;
+                key: string;
+            };
+            updated_at: number;
+        }[];
+        next_cursor: string | null;
+    }>;
+    getStateRecord: (name: string, subject: StateSubjectRef, signal?: AbortSignal) => Promise<{
+        state: string;
+        subject: {
+            target_kind: "tool" | "agent";
+            target_name: string;
+            kind: string;
+            key: string;
+        };
+        data: Record<string, unknown>;
+        seq: number;
+        canonical_subject: {
+            target_kind: "tool" | "agent";
+            target_name: string;
+            kind: string;
+            key: string;
+        };
+        folded_from: {
+            target_kind: "tool" | "agent";
+            target_name: string;
+            kind: string;
+            key: string;
+        }[];
+    } | null>;
+    putStateRecord: (name: string, subject: StateSubjectRef, data: Record<string, unknown>) => Promise<{
+        state: string;
+        subject: {
+            target_kind: "tool" | "agent";
+            target_name: string;
+            kind: string;
+            key: string;
+        };
+        data: Record<string, unknown>;
+        seq: number;
+        canonical_subject: {
+            target_kind: "tool" | "agent";
+            target_name: string;
+            kind: string;
+            key: string;
+        };
+        folded_from: {
+            target_kind: "tool" | "agent";
+            target_name: string;
+            kind: string;
+            key: string;
+        }[];
+    }>;
+    patchStateRecord: (name: string, subject: StateSubjectRef, data: Record<string, unknown>) => Promise<{
+        state: string;
+        subject: {
+            target_kind: "tool" | "agent";
+            target_name: string;
+            kind: string;
+            key: string;
+        };
+        data: Record<string, unknown>;
+        seq: number;
+        canonical_subject: {
+            target_kind: "tool" | "agent";
+            target_name: string;
+            kind: string;
+            key: string;
+        };
+        folded_from: {
+            target_kind: "tool" | "agent";
+            target_name: string;
+            kind: string;
+            key: string;
+        }[];
+    }>;
+    applyStateRecord: (name: string, subject: StateSubjectRef, ops: readonly Record<string, unknown>[]) => Promise<{
+        applied: boolean;
+        data: Record<string, unknown> | null;
+        seq: number | null;
+        skipped: Record<string, unknown>[];
+    }>;
+    evalTemplateJq: (name: string, subject: StateSubjectRef, jqName: string, params?: Record<string, unknown>, signal?: AbortSignal) => Promise<{
+        name: string;
+        purpose: "input";
+        value: unknown;
+    }>;
+    applyTemplateJq: (name: string, subject: StateSubjectRef, jqName: string, body?: {
+        input?: unknown;
+        op_id?: string;
+    }) => Promise<{
+        name: string;
+        applied: boolean;
+        data: Record<string, unknown> | null;
+        seq: number | null;
+        skipped: Record<string, unknown>[];
+    }>;
+    deleteStateRecord: (name: string, subject: StateSubjectRef) => Promise<{
+        erased: true;
+    }>;
+    foldStateRecord: (name: string, subject: StateSubjectRef, into: StateSubjectRef, mode: "switch" | "merge") => Promise<{
+        mode: "switch" | "merge";
+        from: {
+            kind: string;
+            key: string;
+        };
+        into: {
+            kind: string;
+            key: string;
+        };
+        already: boolean;
+        flattened: number;
+    }>;
+    listStateWrites: (name: string, subject: StateSubjectRef, params?: StatePageQuery, signal?: AbortSignal) => Promise<{
+        items: {
+            seq: number;
+            at: string;
+            origin: {
+                consumer: string | null;
+                meta: Record<string, unknown> | null;
+                run_id: string | null;
+                op_id: string | null;
+                door: string;
+                actor: string | null;
+                turn_id: string | null;
+                inbound_id: string | null;
+            };
+            paths: (string | number)[][];
+        }[];
+        next_cursor: string | null;
+    }>;
+    stateConsumers: (name: string, signal?: AbortSignal) => Promise<{
+        kind: string;
+        name: string | null;
+        detail: string | null;
+        link: {
+            token: string | null;
+            plugin_path: string | null;
+            search: Record<string, unknown> | null;
+        } | null;
+        unavailable: string | null;
+    }[]>;
+    listStateTemplates: (signal?: AbortSignal) => Promise<{
+        declarations: {
+            check: {
+                content?: string | undefined;
+                id?: string | undefined;
+                kwargs?: Record<string, unknown> | undefined;
+            } | null;
+            schema: Record<string, unknown>;
+        } | null;
+        description: string;
+        kind: "state-template";
+        name: string;
+        parameters: Record<string, unknown>;
+        reconcile: {
+            close: {
+                content?: string | undefined;
+                id?: string | undefined;
+                kwargs?: Record<string, unknown> | undefined;
+            };
+            orphans: {
+                content?: string | undefined;
+                id?: string | undefined;
+                kwargs?: Record<string, unknown> | undefined;
+            };
+            resolutions: {
+                content?: string | undefined;
+                id?: string | undefined;
+                kwargs?: Record<string, unknown> | undefined;
+            };
+        } | null;
+        regimes: Record<string, unknown>[];
+        template_jq: Record<string, {
+            description: string;
+            jq: {
+                content?: string | undefined;
+                id?: string | undefined;
+                kwargs?: Record<string, unknown> | undefined;
+            };
+            params: string[];
+            purpose: "input" | "update";
+            reads: string[][];
+            writes: string[][];
+        }> | null;
+        trace: Record<string, unknown>;
+        attached_to: number;
+        shipped_default: boolean;
+        schema?: Record<string, unknown> | {
+            content?: string | undefined;
+            id?: string | undefined;
+            kwargs?: Record<string, unknown> | undefined;
+        } | undefined;
+    }[]>;
+    getStateTemplate: (name: string, signal?: AbortSignal) => Promise<{
+        declarations: {
+            check: {
+                content?: string | undefined;
+                id?: string | undefined;
+                kwargs?: Record<string, unknown> | undefined;
+            } | null;
+            schema: Record<string, unknown>;
+        } | null;
+        description: string;
+        kind: "state-template";
+        name: string;
+        parameters: Record<string, unknown>;
+        reconcile: {
+            close: {
+                content?: string | undefined;
+                id?: string | undefined;
+                kwargs?: Record<string, unknown> | undefined;
+            };
+            orphans: {
+                content?: string | undefined;
+                id?: string | undefined;
+                kwargs?: Record<string, unknown> | undefined;
+            };
+            resolutions: {
+                content?: string | undefined;
+                id?: string | undefined;
+                kwargs?: Record<string, unknown> | undefined;
+            };
+        } | null;
+        regimes: Record<string, unknown>[];
+        template_jq: Record<string, {
+            description: string;
+            jq: {
+                content?: string | undefined;
+                id?: string | undefined;
+                kwargs?: Record<string, unknown> | undefined;
+            };
+            params: string[];
+            purpose: "input" | "update";
+            reads: string[][];
+            writes: string[][];
+        }> | null;
+        trace: Record<string, unknown>;
+        schema?: Record<string, unknown> | {
+            content?: string | undefined;
+            id?: string | undefined;
+            kwargs?: Record<string, unknown> | undefined;
+        } | undefined;
+    }>;
+    putStateTemplate: (name: string, body: StateTemplateBody, replace?: boolean) => Promise<{
+        declarations: {
+            check: {
+                content?: string | undefined;
+                id?: string | undefined;
+                kwargs?: Record<string, unknown> | undefined;
+            } | null;
+            schema: Record<string, unknown>;
+        } | null;
+        description: string;
+        kind: "state-template";
+        name: string;
+        parameters: Record<string, unknown>;
+        reconcile: {
+            close: {
+                content?: string | undefined;
+                id?: string | undefined;
+                kwargs?: Record<string, unknown> | undefined;
+            };
+            orphans: {
+                content?: string | undefined;
+                id?: string | undefined;
+                kwargs?: Record<string, unknown> | undefined;
+            };
+            resolutions: {
+                content?: string | undefined;
+                id?: string | undefined;
+                kwargs?: Record<string, unknown> | undefined;
+            };
+        } | null;
+        regimes: Record<string, unknown>[];
+        template_jq: Record<string, {
+            description: string;
+            jq: {
+                content?: string | undefined;
+                id?: string | undefined;
+                kwargs?: Record<string, unknown> | undefined;
+            };
+            params: string[];
+            purpose: "input" | "update";
+            reads: string[][];
+            writes: string[][];
+        }> | null;
+        trace: Record<string, unknown>;
+        schema?: Record<string, unknown> | {
+            content?: string | undefined;
+            id?: string | undefined;
+            kwargs?: Record<string, unknown> | undefined;
+        } | undefined;
+    }>;
+    deleteStateTemplate: (name: string) => Promise<{
+        name: string;
+        deleted: true;
+    }>;
+    pruneStateRetention: () => Promise<{
+        pruned: Record<string, number>;
+    }>;
+};
+//# sourceMappingURL=states-client.d.ts.map

package/dist/client/states-client.d.ts.map

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

package/dist/client/states-client.js

@@ -0,0 +1,144 @@
+/** State declaration, record, template and consumer sub-client. */
+import * as s from '../schemas';
+import { encodeSegment } from '../http';
+/**
+ * The subject-addressed record path: `/api/states/{name}/records/{target_kind}/
+ * {target_name}/{kind}/{key}` — four path segments, each percent-encoded, so a key
+ * carrying a slash or a colon never escapes its segment.
+ */
+function stateRecordPath(name, subject) {
+    return (`/api/states/${encodeSegment(name)}/records/` +
+        `${encodeSegment(subject.target_kind)}/${encodeSegment(subject.target_name)}/` +
+        `${encodeSegment(subject.kind)}/${encodeSegment(subject.key)}`);
+}
+/**
+ * Encode a template jq's declared params as JSON query values: the record `template-jq`
+ * route reads each `?<param>=<json>` as a JSON-decoded argument, so a string, number,
+ * array or object round-trips faithfully. An `undefined` value is dropped (an
+ * omitted optional param).
+ */
+function encodeJqParams(params) {
+    if (params === undefined)
+        return undefined;
+    const query = {};
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined)
+            continue;
+        query[key] = JSON.stringify(value);
+    }
+    return query;
+}
+/** State declaration CRUD: list, read, upsert, delete and stats of a state document. */
+function stateDeclarationMethods(t) {
+    const { req } = t;
+    return {
+        // A state is a declared JSON document, one per subject. The list is the
+        // management population; a single state read composes the declaration with its
+        // effective schema, regimes and attachments. Every record route addresses its subject
+        // as four percent-encoded path segments (see `stateRecordPath`).
+        listStates: (signal) => req('/api/states', s.stateList, { signal }),
+        getState: (name, signal) => req(`/api/states/${encodeSegment(name)}`, s.stateDetail, { signal }),
+        // A plain declaration upsert — no `replace` flag. With records present the server
+        // accepts additive schema changes and refuses with a 409 any change that removes or
+        // alters an existing field, or a subject-kind removal that would strand records.
+        putState: (name, body) => req(`/api/states/${encodeSegment(name)}`, s.stateDetail, {
+            method: 'PUT',
+            body,
+        }),
+        deleteState: (name) => req(`/api/states/${encodeSegment(name)}`, s.stateDeleted, { method: 'DELETE' }),
+        getStateStats: (name, signal) => req(`/api/states/${encodeSegment(name)}/stats`, s.stateStats, { signal }),
+    };
+}
+/** Template attachments on a state: list, read, attach, re-attach and detach. */
+function stateAttachmentMethods(t) {
+    const { req } = t;
+    return {
+        listStateAttachments: (name, signal) => req(`/api/states/${encodeSegment(name)}/attachments`, s.stateAttachmentList, { signal }),
+        getStateAttachment: (name, template, signal) => req(`/api/states/${encodeSegment(name)}/attachments/${encodeSegment(template)}`, s.stateAttachment, { signal }),
+        attachStateTemplate: (name, template, body) => req(`/api/states/${encodeSegment(name)}/attachments/${encodeSegment(template)}`, s.stateAttached, { method: 'PUT', body }),
+        patchStateAttachment: (name, template, body) => req(`/api/states/${encodeSegment(name)}/attachments/${encodeSegment(template)}`, s.stateAttachmentUpdated, { method: 'PATCH', body }),
+        detachStateTemplate: (name, template) => req(`/api/states/${encodeSegment(name)}/attachments/${encodeSegment(template)}`, s.stateDetached, { method: 'DELETE' }),
+    };
+}
+/** Record reads and writes: subject listing, content search, and per-subject CRUD. */
+function stateRecordMethods(t) {
+    const { req } = t;
+    return {
+        listStateSubjects: (name, params, signal) => req(`/api/states/${encodeSegment(name)}/subjects`, s.subjectPage, {
+            signal,
+            query: { kind: params.kind, limit: params.limit, cursor: params.cursor },
+        }),
+        // The content search body is a single JSONB containment document (`filters`); the
+        // server refuses an empty one, so the UI validates a non-empty object first.
+        searchStateRecords: (name, body, signal) => req(`/api/states/${encodeSegment(name)}/records/search`, s.recordSearchPage, {
+            method: 'POST',
+            body,
+            signal,
+        }),
+        // A subject with no document yet reads as `null` (a 200 `{data: null}`, the record
+        // page's Create path) — never an error, so the schema is nullable.
+        getStateRecord: (name, subject, signal) => req(stateRecordPath(name, subject), s.stateRecord.nullable(), { signal }),
+        putStateRecord: (name, subject, data) => req(stateRecordPath(name, subject), s.stateRecord, { method: 'PUT', body: data }),
+        patchStateRecord: (name, subject, data) => req(stateRecordPath(name, subject), s.stateRecord, { method: 'PATCH', body: data }),
+        applyStateRecord: (name, subject, ops) => req(`${stateRecordPath(name, subject)}/deltas`, s.applyResult, {
+            method: 'POST',
+            body: { ops },
+        }),
+    };
+}
+/** Record operations on a subject: template-jq eval/apply, delete, fold, write log, consumers. */
+function stateRecordOpMethods(t) {
+    const { req } = t;
+    return {
+        // Evaluate a template jq over the subject: each declared param is JSON-encoded into
+        // the query string (`?<param>=<json>`); the response is `{name, purpose, value}`. An
+        // `attachment.name` jq is percent-encoded as one path segment.
+        evalTemplateJq: (name, subject, jqName, params, signal) => req(`${stateRecordPath(name, subject)}/template-jq/${encodeSegment(jqName)}`, s.templateJqResult, { signal, query: encodeJqParams(params) }),
+        // Apply an `update`-purpose template jq to the subject: `input` is the jq's argument,
+        // `op_id` its idempotency key (a replay is a no-op). The jq lands its op batch through
+        // the apply chokepoint. An `attachment.name` jq is percent-encoded as one path segment.
+        applyTemplateJq: (name, subject, jqName, body) => req(`${stateRecordPath(name, subject)}/template-jq/${encodeSegment(jqName)}`, s.templateJqApplyResult, { method: 'POST', body: body ?? {} }),
+        deleteStateRecord: (name, subject) => req(stateRecordPath(name, subject), s.recordErased, { method: 'DELETE' }),
+        // `mode` is required server-side (`switch` drops, `merge` combines); the fold returns
+        // a report, not the surviving record.
+        foldStateRecord: (name, subject, into, mode) => req(`${stateRecordPath(name, subject)}/fold`, s.stateFoldReport, {
+            method: 'POST',
+            body: { into, mode },
+        }),
+        listStateWrites: (name, subject, params, signal) => req(`${stateRecordPath(name, subject)}/writes`, s.writesPage, {
+            signal,
+            query: { limit: params?.limit, cursor: params?.cursor },
+        }),
+        stateConsumers: (name, signal) => req(`/api/states/${encodeSegment(name)}/consumers`, s.stateConsumers, { signal }),
+    };
+}
+/** State-template documents and retention: list, read, upsert, delete, prune. */
+function stateTemplateMethods(t) {
+    const { req } = t;
+    return {
+        listStateTemplates: (signal) => req('/api/state-templates', s.stateTemplateList, { signal }),
+        getStateTemplate: (name, signal) => req(`/api/state-templates/${encodeSegment(name)}`, s.stateTemplateDocument, { signal }),
+        putStateTemplate: (name, body, replace) => req(`/api/state-templates/${encodeSegment(name)}`, s.stateTemplateDocument, {
+            method: 'PUT',
+            body,
+            query: replace === true ? { replace: 'true' } : undefined,
+        }),
+        deleteStateTemplate: (name) => req(`/api/state-templates/${encodeSegment(name)}`, s.stateTemplateDeleted, {
+            method: 'DELETE',
+        }),
+        pruneStateRetention: () => req('/api/state-retention/prune', s.stateRetentionPruned, { method: 'POST', body: {} }),
+    };
+}
+export function statesClient(t) {
+    // Declaration emit prepends each spread group's members, so the groups are
+    // spread in reverse of their public order to keep the surface declaration →
+    // attachments → records → record-ops → templates.
+    return {
+        ...stateTemplateMethods(t),
+        ...stateRecordOpMethods(t),
+        ...stateRecordMethods(t),
+        ...stateAttachmentMethods(t),
+        ...stateDeclarationMethods(t),
+    };
+}
+//# sourceMappingURL=states-client.js.map

package/dist/client/states-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"states-client.js","sourceRoot":"","sources":["../../src/client/states-client.ts"],"names":[],"mappings":"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"}

package/dist/client/storage-client.d.ts

@@ -0,0 +1,40 @@
+import type { Transport } from './transport';
+/**
+ * Body for a storage upload (POST `/api/storage/resources`). Exactly ONE of
+ * `content_text` (stored verbatim) or `content_base64` (a base64 string decoded to
+ * bytes) supplies the content for `id`; uploading an existing id overwrites it
+ * (provider passthrough semantics).
+ */
+export interface StorageUploadBody {
+    readonly id: string;
+    readonly content_text?: string;
+    readonly content_base64?: string;
+}
+export declare function storageClient(t: Transport): {
+    getStorageInfo: (signal?: AbortSignal) => Promise<{
+        present: boolean;
+        provider: string | null;
+        module: string | null;
+    }>;
+    listStorageResources: (signal?: AbortSignal) => Promise<{
+        resources: string[];
+    }>;
+    statStorageResource: (id: string, signal?: AbortSignal) => Promise<{
+        id: string;
+        content_type: string | null;
+    }>;
+    downloadStorageResource: (id: string, signal?: AbortSignal) => Promise<Blob>;
+    uploadStorageResource: (body: StorageUploadBody) => Promise<{
+        id: string;
+        stored: true;
+    }>;
+    deleteStorageResource: (id: string) => Promise<{
+        id: string;
+        deleted: true;
+    }>;
+    deleteStorageDir: (path: string) => Promise<{
+        dir: string;
+        deleted: true;
+    }>;
+};
+//# sourceMappingURL=storage-client.d.ts.map