@onesi/genesis 0.1.13 → 0.2.1

package/dist/henry.d.ts

@@ -1,5 +1,55 @@
 import type { GenesisClient } from './client.js';
 import type { OperationInput } from './types.js';
+import type { components } from './generated/schema.js';
+export type HenryRun = components['schemas']['Henry.Run'];
+export type HenryRunEvent = components['schemas']['Henry.RunEvent'];
+export type HenryRunEventMessage = components['schemas']['Henry.RunEventMessage'];
+export type HenryRunStreamStatus = components['schemas']['Henry.RunStreamStatus'];
+export type HenryMessageDelivery = components['schemas']['Henry.RunMessageDelivery'];
+/** One event of a live run stream. `end` comes once the run is completed, failed or cancelled. */
+export type HenryStreamEvent = {
+    event: 'activity';
+    data: HenryRunEvent;
+} | {
+    event: 'status' | 'end';
+    data: HenryRunStreamStatus;
+} | {
+    event: 'error';
+    data: {
+        message: string;
+    };
+};
+export interface HenryStreamOptions {
+    /** Start after this activity seq (default 0: from the first event). */
+    afterSeq?: number;
+    /** Stops the stream; the iterator then returns without an error. */
+    signal?: AbortSignal;
+    /** Reconnects allowed after a stream closes without `end` (1-1000, default 100). Henry closes each stream within 120 s. */
+    maxReconnects?: number;
+    /** Reconnect when no byte (event or 15 s keepalive) arrives for this long (default 45000 ms). */
+    idleMs?: number;
+}
+/** A turn: the inputs that led to one model answer, and that answer. Its number is the `turn` to fork from to re-run it. */
+export interface HenryTurn {
+    turn: number;
+    inputs: HenryRunEventMessage[];
+    events: Pick<HenryRunEvent, 'seq' | 'at' | 'type' | 'detail'>[];
+    answer: HenryRunEventMessage;
+}
+export interface HenryReplay {
+    run_id: string;
+    status?: string;
+    turns: HenryTurn[];
+    pending: Omit<HenryTurn, 'answer'>;
+}
+/**
+ * Fold a run's events into turns. Turn N holds the inputs that led to the run's (N+1)th model answer and that answer, so
+ * forking from turn N re-runs that answer. Events after the last answer are returned as `pending`.
+ */
+export declare function foldHenryTurns(events: HenryRunEvent[]): {
+    turns: HenryTurn[];
+    pending: Omit<HenryTurn, 'answer'>;
+};
 /** Henry always derives its organization from the gateway's verified caller. */
 export declare function henryModule(client: GenesisClient): {
     config: () => Promise<{
@@ -27,9 +77,20 @@ export declare function henryModule(client: GenesisClient): {
             publicKeyBase64: string;
         }>;
     };
+    blinds: {
+        /** HTTPS request through the organization's bound Blinds machine. */
+        proxy: (body: NonNullable<OperationInput<"henry_proxyBlinds">["body"]>) => Promise<{
+            request_id?: string;
+            status: number;
+            headers: {
+                [key: string]: string;
+            };
+            body: string;
+        }>;
+    };
     runs: {
         list: (page_token?: string) => Promise<{
-            runs: import("./index.js").components["schemas"]["Henry.Run"][];
+            runs: components["schemas"]["Henry.Run"][];
             next_page_token?: string | null;
         }>;
         create: (body: NonNullable<OperationInput<"henry_createRun">["body"]>) => Promise<{
@@ -44,6 +105,8 @@ export declare function henryModule(client: GenesisClient): {
                 at: string;
                 type: string;
                 detail: string;
+                message_index?: number;
+                message_id?: string;
             }[];
             approvals: {
                 id: string;
@@ -57,6 +120,8 @@ export declare function henryModule(client: GenesisClient): {
                 code?: number;
                 receipt?: Record<string, never>;
                 usage?: Record<string, never> | null;
+                started_at?: string;
+                ended_at?: string;
             }[];
             messages: ({
                 role: string;
@@ -64,6 +129,16 @@ export declare function henryModule(client: GenesisClient): {
             } & {
                 [key: string]: unknown;
             })[];
+            trace_id?: string;
+            forked_from?: {
+                run_id: string;
+                turn: number;
+                text_sha256?: string;
+            };
+            inbox?: components["schemas"]["Henry.RunInboxMessage"][];
+            interrupt_execution?: string;
+            observatory_version?: number;
+            telemetry?: components["schemas"]["Henry.RunTelemetry"];
         }>;
         get: (run_id: string) => Promise<{
             id: string;
@@ -77,6 +152,8 @@ export declare function henryModule(client: GenesisClient): {
                 at: string;
                 type: string;
                 detail: string;
+                message_index?: number;
+                message_id?: string;
             }[];
             approvals: {
                 id: string;
@@ -90,6 +167,8 @@ export declare function henryModule(client: GenesisClient): {
                 code?: number;
                 receipt?: Record<string, never>;
                 usage?: Record<string, never> | null;
+                started_at?: string;
+                ended_at?: string;
             }[];
             messages: ({
                 role: string;
@@ -97,6 +176,32 @@ export declare function henryModule(client: GenesisClient): {
             } & {
                 [key: string]: unknown;
             })[];
+            trace_id?: string;
+            forked_from?: {
+                run_id: string;
+                turn: number;
+                text_sha256?: string;
+            };
+            inbox?: components["schemas"]["Henry.RunInboxMessage"][];
+            interrupt_execution?: string;
+            observatory_version?: number;
+            telemetry?: components["schemas"]["Henry.RunTelemetry"];
+        }>;
+        /** Page activity events: pass the previous page's next_after_seq as after_seq. */
+        events: (run_id: string, query?: {
+            after_seq?: number;
+            limit?: number;
+        }) => Promise<{
+            run_id: string;
+            status?: string;
+            events: components["schemas"]["Henry.RunEvent"][];
+            next_after_seq: number;
+            has_more: boolean;
+        }>;
+        /** Delete a finished run; active runs must be cancelled first (409). */
+        delete: (run_id: string) => Promise<{
+            run_id: string;
+            deleted: boolean;
         }>;
         command: (run_id: string, action: "pause" | "resume" | "cancel" | "input", text?: string) => Promise<{
             id: string;
@@ -110,6 +215,8 @@ export declare function henryModule(client: GenesisClient): {
                 at: string;
                 type: string;
                 detail: string;
+                message_index?: number;
+                message_id?: string;
             }[];
             approvals: {
                 id: string;
@@ -123,6 +230,8 @@ export declare function henryModule(client: GenesisClient): {
                 code?: number;
                 receipt?: Record<string, never>;
                 usage?: Record<string, never> | null;
+                started_at?: string;
+                ended_at?: string;
             }[];
             messages: ({
                 role: string;
@@ -130,6 +239,16 @@ export declare function henryModule(client: GenesisClient): {
             } & {
                 [key: string]: unknown;
             })[];
+            trace_id?: string;
+            forked_from?: {
+                run_id: string;
+                turn: number;
+                text_sha256?: string;
+            };
+            inbox?: components["schemas"]["Henry.RunInboxMessage"][];
+            interrupt_execution?: string;
+            observatory_version?: number;
+            telemetry?: components["schemas"]["Henry.RunTelemetry"];
         }>;
         approval: (run_id: string, approval_id: string, decision: "approve" | "reject") => Promise<{
             id: string;
@@ -143,6 +262,70 @@ export declare function henryModule(client: GenesisClient): {
                 at: string;
                 type: string;
                 detail: string;
+                message_index?: number;
+                message_id?: string;
+            }[];
+            approvals: {
+                id: string;
+                action: string;
+                url: string;
+                status: string;
+                requested_at: string;
+            }[];
+            phases: {
+                id?: string;
+                code?: number;
+                receipt?: Record<string, never>;
+                usage?: Record<string, never> | null;
+                started_at?: string;
+                ended_at?: string;
+            }[];
+            messages: ({
+                role: string;
+                content?: string | null;
+            } & {
+                [key: string]: unknown;
+            })[];
+            trace_id?: string;
+            forked_from?: {
+                run_id: string;
+                turn: number;
+                text_sha256?: string;
+            };
+            inbox?: components["schemas"]["Henry.RunInboxMessage"][];
+            interrupt_execution?: string;
+            observatory_version?: number;
+            telemetry?: components["schemas"]["Henry.RunTelemetry"];
+        }>;
+        /**
+         * Send a message into a run: `steer` lands before the next model call, `queue` (default) after the current turn,
+         * `interrupt` cancels the turn in flight. A completed run takes it at once and runs the next turn in this request.
+         */
+        message: (run_id: string, body: {
+            text: string;
+            delivery?: HenryMessageDelivery;
+        }) => Promise<{
+            message: components["schemas"]["Henry.RunMessageReceipt"];
+            run: components["schemas"]["Henry.Run"];
+        }>;
+        /**
+         * Start a new run from turn N of this one (0 = the original task; default the latest, which needs text). run_id is
+         * the new run's idempotency key: one is generated unless supplied, and a retry with it returns the same run.
+         */
+        fork: (run_id: string, body?: NonNullable<OperationInput<"henry_forkRun">["body"]>) => Promise<{
+            id: string;
+            task: string;
+            model: string;
+            status: "ready" | "running" | "acting" | "paused" | "awaiting_approval" | "completed" | "cancelled" | "failed" | "waiting_input";
+            created_at: string;
+            updated_at: string;
+            activity: {
+                id: string;
+                at: string;
+                type: string;
+                detail: string;
+                message_index?: number;
+                message_id?: string;
             }[];
             approvals: {
                 id: string;
@@ -156,6 +339,8 @@ export declare function henryModule(client: GenesisClient): {
                 code?: number;
                 receipt?: Record<string, never>;
                 usage?: Record<string, never> | null;
+                started_at?: string;
+                ended_at?: string;
             }[];
             messages: ({
                 role: string;
@@ -163,6 +348,22 @@ export declare function henryModule(client: GenesisClient): {
             } & {
                 [key: string]: unknown;
             })[];
+            trace_id?: string;
+            forked_from?: {
+                run_id: string;
+                turn: number;
+                text_sha256?: string;
+            };
+            inbox?: components["schemas"]["Henry.RunInboxMessage"][];
+            interrupt_execution?: string;
+            observatory_version?: number;
+            telemetry?: components["schemas"]["Henry.RunTelemetry"];
         }>;
+        /** Follow a run live: an async iterator over its stream, reconnecting with Last-Event-ID until `end`. */
+        streamEvents: (run_id: string, options?: HenryStreamOptions) => AsyncGenerator<HenryStreamEvent, any, any>;
+        /** Read every event of a run and fold them into turns (see foldHenryTurns). */
+        replay: (run_id: string, options?: {
+            signal?: AbortSignal;
+        }) => Promise<HenryReplay>;
     };
 };

package/dist/henry.js

@@ -1,4 +1,183 @@
 import { GenesisError } from './errors.js';
+const MAX_SSE_EVENT_CHARS = 4 * 1024 * 1024;
+const REPLAY_PAGE = 500;
+const MAX_REPLAY_PAGES = 2000;
+/**
+ * Fold a run's events into turns. Turn N holds the inputs that led to the run's (N+1)th model answer and that answer, so
+ * forking from turn N re-runs that answer. Events after the last answer are returned as `pending`.
+ */
+export function foldHenryTurns(events) {
+    const turns = [];
+    let current = { turn: 0, inputs: [], events: [] };
+    for (const event of events) {
+        current.events.push({ seq: event.seq, at: event.at, type: event.type, ...(event.detail === undefined ? {} : { detail: event.detail }) });
+        const message = event.message;
+        if (message?.role === 'assistant') {
+            turns.push({ ...current, answer: message });
+            current = { turn: turns.length, inputs: [], events: [] };
+        }
+        else if (message)
+            current.inputs.push(message);
+    }
+    return { turns, pending: current };
+}
+const invalid = (operationId, message) => new GenesisError({ status: 0, type: 'invalid_request', operationId, message });
+const STREAM_EVENTS = new Set(['activity', 'status', 'end', 'error']);
+/** Parse one SSE frame's lines into { event, id, data }; undefined for comments, keepalives and data-less frames. */
+function frame(lines) {
+    let event = 'message';
+    let id;
+    const data = [];
+    for (const line of lines) {
+        if (line.startsWith(':'))
+            continue;
+        const colon = line.indexOf(':');
+        const field = colon < 0 ? line : line.slice(0, colon);
+        let value = colon < 0 ? '' : line.slice(colon + 1);
+        if (value.startsWith(' '))
+            value = value.slice(1);
+        if (field === 'event')
+            event = value;
+        else if (field === 'id')
+            id = value;
+        else if (field === 'data')
+            data.push(value);
+    }
+    return data.length ? { event, ...(id === undefined ? {} : { id }), data: data.join('\n') } : undefined;
+}
+const wait = (ms, signal) => new Promise(resolve => {
+    const done = () => { clearTimeout(timer); signal?.removeEventListener('abort', done); resolve(); };
+    const timer = setTimeout(done, ms);
+    signal?.addEventListener('abort', done, { once: true });
+});
+/**
+ * Follow a run over SSE, reconnecting with Last-Event-ID after each stream closes (Henry closes one within 120 s) until
+ * `end`, the signal aborts or maxReconnects is used up. Never buffers a whole stream.
+ */
+async function* streamRunEvents(client, run_id, options = {}) {
+    const operationId = 'henry_listRunEvents';
+    const { signal } = options;
+    let last = options.afterSeq ?? 0;
+    let lastStatus;
+    if (!Number.isSafeInteger(last) || last < 0 || last > 9_999_999)
+        throw invalid(operationId, 'afterSeq must be an integer from 0 to 9999999.');
+    const maxReconnects = options.maxReconnects ?? 100;
+    if (!Number.isInteger(maxReconnects) || maxReconnects < 1 || maxReconnects > 1000)
+        throw invalid(operationId, 'maxReconnects must be an integer from 1 to 1000.');
+    const idleMs = options.idleMs ?? 45_000;
+    if (!Number.isInteger(idleMs) || idleMs < 1000 || idleMs > 300_000)
+        throw invalid(operationId, 'idleMs must be an integer from 1000 to 300000.');
+    for (let attempt = 0; attempt <= maxReconnects && !signal?.aborted; attempt++) {
+        // One connection: aborted by the caller's signal, or when the stream goes quiet for idleMs.
+        const connection = new AbortController();
+        const abort = () => connection.abort();
+        signal?.addEventListener('abort', abort, { once: true });
+        let idle;
+        const touch = () => { clearTimeout(idle); idle = setTimeout(abort, idleMs); };
+        let progressed = false;
+        try {
+            touch();
+            let response;
+            try {
+                // Exactly text/event-stream: an Accept that also allows JSON gets the paged read instead of a stream.
+                response = await client.raw(operationId, { run_id }, { signal: connection.signal, headers: { accept: 'text/event-stream', 'last-event-id': String(last) } });
+            }
+            catch (error) {
+                if (signal?.aborted)
+                    return;
+                // An HTTP answer (404, 403, 429 streams_busy...) is raised, not retried in a loop. A dropped or quiet connection is retried.
+                if (error instanceof GenesisError && error.status !== 0 && ![502, 503, 504].includes(error.status))
+                    throw error;
+                await wait(1000, signal);
+                continue;
+            }
+            const reader = response.body?.getReader();
+            if (!reader) {
+                await wait(1000, signal);
+                continue;
+            }
+            const decoder = new TextDecoder();
+            let buffer = '';
+            let lines = [];
+            let size = 0;
+            try {
+                for (;;) {
+                    let chunk;
+                    try {
+                        chunk = await reader.read();
+                    }
+                    catch {
+                        break;
+                    }
+                    if (chunk.done)
+                        break;
+                    touch();
+                    buffer += decoder.decode(chunk.value, { stream: true });
+                    let index;
+                    while ((index = buffer.search(/\r\n|\r|\n/)) >= 0) {
+                        const line = buffer.slice(0, index);
+                        buffer = buffer.slice(index + (buffer.startsWith('\r\n', index) ? 2 : 1));
+                        if (line !== '') {
+                            size += line.length;
+                            if (size > MAX_SSE_EVENT_CHARS)
+                                throw new GenesisError({ status: 0, type: 'invalid_response', operationId, message: 'Henry stream event exceeds 4 MiB.' });
+                            lines.push(line);
+                            continue;
+                        }
+                        const parsed = frame(lines);
+                        lines = [];
+                        size = 0;
+                        if (!parsed || !STREAM_EVENTS.has(parsed.event))
+                            continue;
+                        let data;
+                        try {
+                            data = JSON.parse(parsed.data);
+                        }
+                        catch {
+                            throw new GenesisError({ status: 0, type: 'invalid_response', operationId, message: 'Henry stream sent invalid JSON.' });
+                        }
+                        if (parsed.event === 'status') {
+                            // Each connection opens with the current status: report a change only.
+                            const status = data?.status;
+                            if (status === lastStatus)
+                                continue;
+                            lastStatus = status;
+                        }
+                        if (parsed.event === 'activity') {
+                            const seq = data?.seq;
+                            if (typeof seq !== 'number' || !Number.isSafeInteger(seq))
+                                throw new GenesisError({ status: 0, type: 'invalid_response', operationId, message: 'Henry stream activity has no seq.' });
+                            if (seq <= last)
+                                continue; // already yielded before a reconnect
+                            last = seq;
+                            progressed = true;
+                        }
+                        yield { event: parsed.event, data };
+                        if (parsed.event === 'end')
+                            return;
+                    }
+                    if (buffer.length > MAX_SSE_EVENT_CHARS)
+                        throw new GenesisError({ status: 0, type: 'invalid_response', operationId, message: 'Henry stream event exceeds 4 MiB.' });
+                }
+            }
+            finally {
+                void reader.cancel().catch(() => { });
+            }
+            if (signal?.aborted)
+                return;
+            // A stream that closed with nothing new waits before reconnecting, so a failing upstream is never hammered.
+            if (!progressed)
+                await wait(1000, signal);
+        }
+        finally {
+            clearTimeout(idle);
+            signal?.removeEventListener('abort', abort);
+        }
+    }
+    if (!signal?.aborted)
+        throw new GenesisError({ status: 0, type: 'stream_incomplete', operationId,
+            message: `Henry run ${run_id} did not end within ${maxReconnects} reconnects; resume with afterSeq ${last}.` });
+}
 function receiptVerificationKey(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         throw new Error('Henry returned an invalid receipt verification key.');
@@ -34,12 +213,56 @@ export function henryModule(client) {
                 }
             },
         },
+        blinds: {
+            /** HTTPS request through the organization's bound Blinds machine. */
+            proxy: (body) => client.request('henry_proxyBlinds', { body }),
+        },
         runs: {
             list: (page_token) => client.request('henry_listRuns', page_token ? { page_token } : {}),
             create: (body) => client.request('henry_createRun', { body: { ...body, run_id: body.run_id ?? globalThis.crypto.randomUUID() } }),
             get: (run_id) => client.request('henry_getRun', { run_id }),
+            /** Page activity events: pass the previous page's next_after_seq as after_seq. */
+            events: (run_id, query = {}) => client.request('henry_listRunEvents', { run_id, ...query }),
+            /** Delete a finished run; active runs must be cancelled first (409). */
+            delete: (run_id) => client.request('henry_deleteRun', { run_id }),
             command: (run_id, action, text) => client.request('henry_commandRun', { run_id, body: { action, ...(text === undefined ? {} : { text }) } }),
             approval: (run_id, approval_id, decision) => client.request('henry_decideApproval', { run_id, approval_id, body: { decision } }),
+            /**
+             * Send a message into a run: `steer` lands before the next model call, `queue` (default) after the current turn,
+             * `interrupt` cancels the turn in flight. A completed run takes it at once and runs the next turn in this request.
+             */
+            message: (run_id, body) => {
+                if (typeof body?.text !== 'string' || !body.text.trim() || body.text.length > 16000)
+                    throw invalid('henry_sendRunMessage', 'Message text must contain 1-16000 characters.');
+                return client.request('henry_sendRunMessage', { run_id, body: { text: body.text, ...(body.delivery === undefined ? {} : { delivery: body.delivery }) } });
+            },
+            /**
+             * Start a new run from turn N of this one (0 = the original task; default the latest, which needs text). run_id is
+             * the new run's idempotency key: one is generated unless supplied, and a retry with it returns the same run.
+             */
+            fork: (run_id, body = {}) => {
+                if (body.turn !== undefined && (!Number.isSafeInteger(body.turn) || body.turn < 0))
+                    throw invalid('henry_forkRun', 'turn must be a non-negative integer.');
+                return client.request('henry_forkRun', { run_id, body: { ...body, run_id: body.run_id ?? globalThis.crypto.randomUUID() } });
+            },
+            /** Follow a run live: an async iterator over its stream, reconnecting with Last-Event-ID until `end`. */
+            streamEvents: (run_id, options = {}) => streamRunEvents(client, run_id, options),
+            /** Read every event of a run and fold them into turns (see foldHenryTurns). */
+            replay: async (run_id, options = {}) => {
+                const events = [];
+                let after = 0;
+                for (let pages = 0; pages < MAX_REPLAY_PAGES; pages++) {
+                    const page = await client.request('henry_listRunEvents', { run_id, after_seq: after, limit: REPLAY_PAGE }, { signal: options.signal });
+                    events.push(...page.events);
+                    if (!page.has_more)
+                        return { run_id: page.run_id, ...(page.status === undefined ? {} : { status: page.status }), ...foldHenryTurns(events) };
+                    if (!Number.isSafeInteger(page.next_after_seq) || page.next_after_seq <= after) {
+                        throw new GenesisError({ status: 0, type: 'invalid_response', operationId: 'henry_listRunEvents', message: 'Henry events did not advance.' });
+                    }
+                    after = page.next_after_seq;
+                }
+                throw new GenesisError({ status: 0, type: 'invalid_response', operationId: 'henry_listRunEvents', message: 'Henry run has too many events to replay.' });
+            },
         },
     };
 }

package/dist/hives-cells.d.ts

@@ -1,5 +1,5 @@
 import type { GenesisClient } from './client.js';
-import { type HivesResourceOptions } from './hives-resources-transport.js';
+import { type HivesFundedWriteOptions, type HivesResourceOptions } from './hives-resources-transport.js';
 export interface HivesCorsRule {
     allowed_origins: string[];
     allowed_methods: string[];
@@ -112,16 +112,21 @@ export declare function hivesCells(client: GenesisClient): {
             continuation_token?: string;
             max_keys?: number;
         }, options?: HivesResourceOptions): Promise<HivesObjectList>;
-        put(project: string, id: string, key: string, bytes: Blob | ArrayBuffer | ArrayBufferView, options?: HivesResourceOptions & {
+        put(project: string, id: string, key: string, bytes: Blob | ArrayBuffer | ArrayBufferView, options?: HivesFundedWriteOptions & {
             content_type?: string;
         }): Promise<HivesObjectAcknowledgement>;
         remove: (project: string, id: string, key: string, options?: HivesResourceOptions) => Promise<void>;
         download: (project: string, id: string, key: string, options?: HivesResourceOptions) => Promise<Response>;
         /** Existing flat-key path compatibility; nested keys use canonical collection methods above. */
-        putFlat(project: string, id: string, key: string, bytes: Blob | ArrayBuffer | ArrayBufferView, options?: HivesResourceOptions & {
+        putFlat(project: string, id: string, key: string, bytes: Blob | ArrayBuffer | ArrayBufferView, options?: HivesFundedWriteOptions & {
             content_type?: string;
         }): Promise<HivesObjectAcknowledgement>;
         removeFlat: (project: string, id: string, key: string, options?: HivesResourceOptions) => Promise<void>;
+        /** The flat key "download" on its own static route, which shadows /objects/{key} for that key. */
+        putDownload(project: string, id: string, bytes: Blob | ArrayBuffer | ArrayBufferView, options?: HivesFundedWriteOptions & {
+            content_type?: string;
+        }): Promise<HivesObjectAcknowledgement>;
+        removeDownload: (project: string, id: string, options?: HivesResourceOptions) => Promise<void>;
     };
     presign(project: string, id: string, body: HivesPresign, options?: HivesResourceOptions): Promise<HivesPresignedUrl>;
 };

package/dist/hives-cells.js

@@ -1,4 +1,4 @@
-import { HIVES_OBJECT_BYTES, hivesResourceCall, hivesResourceId, hivesObjectBody, hivesContentType, resourceError } from './hives-resources-transport.js';
+import { HIVES_OBJECT_BYTES, hivesFundedWriteHeaders, hivesResourceCall, hivesResourceId, hivesObjectBody, hivesContentType, resourceError } from './hives-resources-transport.js';
 export function hivesObjectKey(key) {
     const bytes = new TextEncoder().encode(key);
     if (typeof key !== 'string' || !key || bytes.length > 1024 || new TextDecoder('utf-8', { fatal: true }).decode(bytes) !== key
@@ -59,7 +59,12 @@ function object(value, id) {
     hivesObjectKey(value.key);
     return Object.fromEntries(['key', 'bucket_id', 'size_bytes', 'etag', 'last_modified', 'generation', 'content_type', 'metadata', 'metadata_scope'].map(k => [k, value[k]]));
 }
-function acknowledgement(value, key, id, size) {
+function acknowledgement(answer, key, id, size) {
+    // A funded write answers with its settled storage operation receipt; the acknowledgement is its result.
+    const receipt = answer;
+    if (receipt && receipt.object !== undefined && (receipt.object !== 'storage_write_operation' || receipt.state !== 'settled'))
+        throw resourceError(0);
+    const value = (receipt?.object === undefined ? answer : receipt.result);
     if (!value || value.bucket_id !== id || value.key !== key || value.size_bytes !== size || !Number.isSafeInteger(value.size_bytes) || value.size_bytes < 0 || typeof value.etag !== 'string' || typeof value.generation !== 'string' || value.content_type !== null && typeof value.content_type !== 'string')
         throw resourceError(0);
     return { key: value.key, bucket_id: value.bucket_id, size_bytes: value.size_bytes, etag: value.etag, generation: value.generation, content_type: value.content_type };
@@ -67,6 +72,8 @@ function acknowledgement(value, key, id, size) {
 export function hivesCells(client) {
     const ids = (project_id, bucket_id) => ({ project_id: hivesResourceId(project_id), ...(bucket_id === undefined ? {} : { bucket_id: hivesResourceId(bucket_id) }) });
     const call = (id, input, options, mode = 'json', limit = 2 * 1024 * 1024) => hivesResourceCall(client, id, input, options, mode, limit, 100_000);
+    // Object writes are funded: each carries one Idempotency-Key (the caller's, or a fresh one).
+    const write = (id, input, options) => hivesResourceCall(client, id, input, options, 'json', 2 * 1024 * 1024, 100_000, undefined, { headers: hivesFundedWriteHeaders(options, id) });
     return {
         async list(project, query = {}, options) {
             if (Object.keys(query).some(k => !['page', 'per_page'].includes(k)) || query.page !== undefined && (!Number.isInteger(query.page) || query.page < 1 || query.page > 10000) || query.per_page !== undefined && (!Number.isInteger(query.per_page) || query.per_page < 1 || query.per_page > 100))
@@ -113,7 +120,7 @@ export function hivesCells(client) {
             async put(project, id, key, bytes, options = {}) {
                 const body = await hivesObjectBody(bytes);
                 const content_type = hivesContentType(options.content_type);
-                return acknowledgement(await call('hives_upload_object_by_key', { ...ids(project, id), key_base64url: hivesObjectKey(key), body, content_type }, options), key, id, body.byteLength);
+                return acknowledgement(await write('hives_upload_object_by_key', { ...ids(project, id), key_base64url: hivesObjectKey(key), body, content_type }, options), key, id, body.byteLength);
             },
             remove: (project, id, key, options) => call('hives_delete_object_by_key', { ...ids(project, id), key_base64url: hivesObjectKey(key) }, options, 'empty'),
             download: (project, id, key, options) => call('hives_download_object_by_key', { ...ids(project, id), key_base64url: hivesObjectKey(key) }, options, 'binary', HIVES_OBJECT_BYTES),
@@ -123,10 +130,16 @@ export function hivesCells(client) {
                 if (!/^[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*$/.test(key))
                     throw resourceError(0);
                 const body = await hivesObjectBody(bytes);
-                return acknowledgement(await call('hives_upload_object', { ...ids(project, id), key, body, content_type: hivesContentType(options.content_type) }, options), key, id, body.byteLength);
+                return acknowledgement(await write('hives_upload_object', { ...ids(project, id), key, body, content_type: hivesContentType(options.content_type) }, options), key, id, body.byteLength);
             },
             removeFlat: (project, id, key, options) => { hivesObjectKey(key); if (!/^[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*$/.test(key))
                 throw resourceError(0); return call('hives_delete_object', { ...ids(project, id), key }, options, 'empty'); },
+            /** The flat key "download" on its own static route, which shadows /objects/{key} for that key. */
+            async putDownload(project, id, bytes, options = {}) {
+                const body = await hivesObjectBody(bytes);
+                return acknowledgement(await write('hives_upload_object_named_download', { ...ids(project, id), body, content_type: hivesContentType(options.content_type) }, options), 'download', id, body.byteLength);
+            },
+            removeDownload: (project, id, options) => call('hives_delete_object_named_download', ids(project, id), options, 'empty'),
         },
         async presign(project, id, body, options) {
             hivesObjectKey(body.key);

package/dist/hives-environment.d.ts

@@ -1,5 +1,7 @@
 /** Environment metadata never carries stored values. Reveals are explicit. */
 export declare function validateHivesEnvironment(input: unknown): Record<string, string>;
+/** Names for DELETE /env: 1–100 distinct valid environment names. */
+export declare function validateHivesEnvironmentNames(input: unknown): string[];
 export declare function hivesEnvironmentMetadata(value: unknown, project: unknown, updated: boolean): {
     project_id: string;
     updated: {
@@ -26,3 +28,10 @@ export declare function hivesEnvironmentReveal(value: unknown, key: unknown): {
     name: string;
     value: string;
 };
+/** PUT /env answers the whole decrypted map. Keep only the submitted names it confirms; never a value. */
+export declare function hivesEnvironmentSetNames(value: unknown, project: unknown, submitted: unknown): {
+    project_id: string;
+    updated: {
+        name: string;
+    }[];
+};