@onesi/genesis 0.0.1-stage → 0.2.0

package/dist/henry.d.ts

@@ -0,0 +1,369 @@
+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<{
+        credential_configured: boolean;
+        models: {
+            id: string;
+        }[];
+    }>;
+    credential: (api_key: string) => Promise<{
+        credential_configured: boolean;
+        models: {
+            id: string;
+        }[];
+    }>;
+    /** Foundry models the stored organization key can run; 409 when no key is stored. */
+    models: () => Promise<{
+        models: {
+            id: string;
+        }[];
+    }>;
+    receipts: {
+        /** Current standalone Henry public signer. Pin through trusted deployment custody before verifying a receipt. */
+        verificationKey: () => Promise<{
+            keyId: string;
+            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: components["schemas"]["Henry.Run"][];
+            next_page_token?: string | null;
+        }>;
+        create: (body: NonNullable<OperationInput<"henry_createRun">["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;
+                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"];
+        }>;
+        get: (run_id: string) => 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;
+                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"];
+        }>;
+        /** 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;
+            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;
+                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"];
+        }>;
+        approval: (run_id: string, approval_id: string, decision: "approve" | "reject") => 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;
+                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;
+                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"];
+        }>;
+        /** 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

@@ -0,0 +1,268 @@
+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.');
+    const key = value;
+    if (Object.keys(key).length !== 2 || !Object.hasOwn(key, 'keyId') || !Object.hasOwn(key, 'publicKeyBase64')
+        || typeof key.keyId !== 'string' || !key.keyId.trim() || key.keyId.length > 256 || /[\x00-\x1f\x7f]/.test(key.keyId)
+        || typeof key.publicKeyBase64 !== 'string' || key.publicKeyBase64.length !== 44
+        || !/^[A-Za-z0-9+/]{42}[AEIMQUYcgkosw048]=$/.test(key.publicKeyBase64)) {
+        throw new Error('Henry returned an invalid receipt verification key.');
+    }
+    return { keyId: key.keyId, publicKeyBase64: key.publicKeyBase64 };
+}
+/** Henry always derives its organization from the gateway's verified caller. */
+export function henryModule(client) {
+    return {
+        config: () => client.request('henry_getConfig'),
+        credential: async (api_key) => {
+            if (typeof api_key !== 'string' || !api_key || new TextEncoder().encode(api_key).byteLength > 4096 || /[\r\n\0]/.test(api_key)) {
+                throw new GenesisError({ status: 0, type: 'invalid_request', operationId: 'henry_putCredential', message: 'Foundry key must contain 1–4096 UTF-8 bytes without CR, LF or NUL.' });
+            }
+            return client.request('henry_putCredential', { body: { api_key } });
+        },
+        /** Foundry models the stored organization key can run; 409 when no key is stored. */
+        models: () => client.request('henry_listFoundryModels'),
+        receipts: {
+            /** Current standalone Henry public signer. Pin through trusted deployment custody before verifying a receipt. */
+            verificationKey: async () => {
+                try {
+                    return receiptVerificationKey(await client.request('henry_getReceiptVerificationKey'));
+                }
+                catch {
+                    throw new Error('Henry returned an invalid receipt verification key.');
+                }
+            },
+        },
+        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.' });
+            },
+        },
+    };
+}