@onesi/genesis 0.2.3 → 0.2.5

package/README.md

@@ -3,7 +3,7 @@
 The TypeScript SDK for OneOS. One typed client for every Genesis service, through the Genesis API at `https://os.one.ml/api`.
 
 ```sh
-npm install @onesi/genesis@0.2.3
+npm install @onesi/genesis@0.2.5
 ```
 
 ```ts

package/dist/boxes.d.ts

@@ -3,7 +3,7 @@ import type { OperationInput as In } from './types.js';
 /** Boxes (mail, docs, files, sheets, slides, calendar, identity, MCP): one method per operation, grouped as the
  * Boxes resource tree. Path parameters come first, then the body, then query options, then an optional
  * idempotency key on the operations that take one. Operations that stream or download bytes return the raw Response;
- * uploads take a FormData body. GET needs boxes:read, everything else boxes:write. Generated from the Boxes spec. */
+ * uploads take a FormData body. GET needs boxes:read, everything else boxes:write; mail domain administration needs boxes:admin. Generated from the Boxes spec. */
 export declare function boxesModule(client: GenesisClient): {
     mail: {
         addresses: {

package/dist/boxes.js

@@ -2,7 +2,7 @@ import { idempotencyHeaders } from './idempotency.js';
 /** Boxes (mail, docs, files, sheets, slides, calendar, identity, MCP): one method per operation, grouped as the
  * Boxes resource tree. Path parameters come first, then the body, then query options, then an optional
  * idempotency key on the operations that take one. Operations that stream or download bytes return the raw Response;
- * uploads take a FormData body. GET needs boxes:read, everything else boxes:write. Generated from the Boxes spec. */
+ * uploads take a FormData body. GET needs boxes:read, everything else boxes:write; mail domain administration needs boxes:admin. Generated from the Boxes spec. */
 export function boxesModule(client) {
     return {
         mail: {

package/dist/client.d.ts

@@ -25,8 +25,15 @@ export interface GenesisOptions {
     headers?: Record<string, string>;
     userAgent?: string;
 }
+/**
+ * Redact URL userinfo from an error's message, stack and cause chain (bounded). If the error is frozen or any of
+ * those properties cannot be rewritten, return a new sanitized Error instead of the original.
+ */
+export declare function scrubError(e: unknown, depth?: number): unknown;
 export declare class GenesisClient {
-    readonly baseUrl: string;
+    /** The configured gateway root, kept without userinfo so it is safe to log or print. */
+    get baseUrl(): string;
+    private readonly root;
     readonly routing: 'gateway' | 'direct';
     private readonly opts;
     private readonly fetchImpl;
@@ -34,6 +41,16 @@ export declare class GenesisClient {
     constructor(opts?: GenesisOptions);
     static operations: Readonly<Record<OperationId, OperationMeta>>;
     static services: import("./types.js").ServiceMeta[];
+    /** This client's one read of the selected context's Hives binding (cleared on failure). */
+    private hivesBinding?;
+    /**
+     * The Hives project id (prj_…) for a Hives project argument. A prj_… id is returned unchanged. Omitted, or the
+     * Genesis pr_… id of the selected context's project, it resolves to the Hives project bound to that selection
+     * (`hives_get_context_project`, read at most once per client); otherwise a GenesisError says how to find the prj_… id.
+     */
+    hivesProjectId(project_id?: string, init?: {
+        signal?: AbortSignal;
+    }): Promise<string>;
     /** Resolve the credential: explicit apiKey > token > env GENESIS_API_KEY > GENESIS_TOKEN > provider. */
     credential(): Promise<string | undefined>;
     /** Build the URL for an operation (exposed for tests and `--dry-run`). */

package/dist/client.js

@@ -8,10 +8,11 @@ import { blindsOperationKey, blindsOwnerTransport, isBlindsOwnerOperation } from
 import { isHivesObjectUpload, hivesObjectBody, hivesContentType, isHivesResourceOperation, resourceError, resourceErrorFromResponse } from './hives-resources-transport.js';
 import { operationTable, services } from './generated/operations.js';
 import { GenesisError } from './errors.js';
-import { requireSecureUrl } from './urls.js';
+import { requireSecureUrl, redactUserinfo, stripUserinfo } from './urls.js';
 import { iamDirectoryFailure, isIamDirectoryOperation } from './iam-directory.js';
 import { validateHivesInvocation, hivesFunctionResponseHeaders, hivesFunctionMetadata, hivesOperationError } from './hives-functions.js';
 import { validateHivesEnvironment, validateHivesEnvironmentNames, hivesEnvironmentSetNames, hivesEnvironmentMetadata, hivesEnvironmentReveal } from './hives-environment.js';
+import { hivesProjectIdRefusal, isGenesisProjectId, isHivesProjectOperation, resolveHivesProjectId } from './hives-project.js';
 import { RUNNER_SELF_GRANT_OPERATION, snapshotRunnerSelfGrant, runnerGrantResponse, runnerGrantTransportError } from './runner-grant.js';
 /** The Genesis API gateway. `https://console.life.one/api` remains an alias for the same gateway. */
 export const DEFAULT_BASE_URL = 'https://os.one.ml/api';
@@ -21,23 +22,75 @@ const ENDLESS_STREAMS = {
     hives_stream_logs: 'genesis.hives.logs.stream() or genesis.hives.logs.window()',
     hives_stream_deployment_logs: 'hivesSseWindow(await genesis.raw(...))',
 };
+const SCRUB_DEPTH = 5;
+/**
+ * Redact URL userinfo from an error's message, stack and cause chain (bounded). If the error is frozen or any of
+ * those properties cannot be rewritten, return a new sanitized Error instead of the original.
+ */
+export function scrubError(e, depth = 0) {
+    if (typeof e === 'string')
+        return redactUserinfo(e);
+    if (!(e instanceof Error))
+        return e;
+    if (depth >= SCRUB_DEPTH)
+        return undefined;
+    const message = redactUserinfo(String(e.message));
+    const stack = typeof e.stack === 'string' ? redactUserinfo(e.stack) : e.stack;
+    const hasCause = 'cause' in e;
+    const cause = hasCause ? scrubError(e.cause, depth + 1) : undefined;
+    if (message === e.message && stack === e.stack && cause === e.cause)
+        return e;
+    try {
+        if (Object.isFrozen(e))
+            throw e;
+        Object.defineProperty(e, 'message', { value: message, writable: true, configurable: true, enumerable: false });
+        Object.defineProperty(e, 'stack', { value: stack, writable: true, configurable: true, enumerable: false });
+        if (hasCause)
+            Object.defineProperty(e, 'cause', { value: cause, writable: true, configurable: true, enumerable: false });
+        if (e.message === message && e.stack === stack && (!hasCause || e.cause === cause))
+            return e;
+    }
+    catch { /* fall through to a fresh error */ }
+    const fresh = new (e instanceof TypeError ? TypeError : Error)(message, hasCause ? { cause } : undefined);
+    fresh.name = redactUserinfo(String(e.name));
+    fresh.stack = stack;
+    return fresh;
+}
 export class GenesisClient {
-    baseUrl;
+    /** The configured gateway root, kept without userinfo so it is safe to log or print. */
+    get baseUrl() { return stripUserinfo(this.root); }
+    root;
     routing;
     opts;
     fetchImpl;
     get contextFetch() { return this.fetchImpl; }
     constructor(opts = {}) {
         this.opts = opts;
-        this.baseUrl = requireSecureUrl(opts.baseUrl ?? env.GENESIS_BASE_URL ?? DEFAULT_BASE_URL, 'baseUrl').replace(/\/+$/, '');
+        this.root = requireSecureUrl(opts.baseUrl ?? env.GENESIS_BASE_URL ?? DEFAULT_BASE_URL, 'baseUrl').replace(/\/+$/, '');
         this.routing = opts.routing ?? (env.GENESIS_ROUTING === 'direct' ? 'direct' : 'gateway');
         const f = opts.fetch ?? globalThis.fetch;
         if (!f)
             throw new Error('No fetch available; pass options.fetch');
-        this.fetchImpl = f.bind(globalThis);
+        // fetch errors can quote the request URL (and its userinfo); scrub them before they surface.
+        this.fetchImpl = ((input, init) => f.call(globalThis, input, init).catch((e) => { throw scrubError(e); }));
     }
     static operations = operationTable;
     static services = services;
+    /** This client's one read of the selected context's Hives binding (cleared on failure). */
+    hivesBinding;
+    /**
+     * The Hives project id (prj_…) for a Hives project argument. A prj_… id is returned unchanged. Omitted, or the
+     * Genesis pr_… id of the selected context's project, it resolves to the Hives project bound to that selection
+     * (`hives_get_context_project`, read at most once per client); otherwise a GenesisError says how to find the prj_… id.
+     */
+    async hivesProjectId(project_id, init = {}) {
+        return resolveHivesProjectId(project_id, () => {
+            const read = this.hivesBinding ??= this.request('hives_get_context_project', {}, { signal: init.signal });
+            read.catch(() => { if (this.hivesBinding === read)
+                this.hivesBinding = undefined; });
+            return read;
+        });
+    }
     /** Resolve the credential: explicit apiKey > token > env GENESIS_API_KEY > GENESIS_TOKEN > provider. */
     async credential() {
         return this.opts.apiKey ?? this.opts.token ?? env.GENESIS_API_KEY ?? env.GENESIS_TOKEN ?? (await this.opts.credentials?.());
@@ -68,7 +121,7 @@ export class GenesisClient {
             p = fill(op.upstream.path);
         }
         else {
-            base = this.baseUrl;
+            base = this.root;
             p = fill(op.path);
         }
         const qs = new URLSearchParams();
@@ -147,6 +200,9 @@ export class GenesisClient {
     }
     /** Raw Response. Completed Hives guest responses retain their actual status, including non-2xx. */
     async raw(operationId, input = {}, init = {}) {
+        // A Genesis pr_… id where Hives wants its own prj_… id would only be a remote 404: refuse it before any request.
+        if (isGenesisProjectId(input.project_id) && isHivesProjectOperation(operationTable[operationId]))
+            throw hivesProjectIdRefusal(input.project_id, operationId);
         if (!isIamDirectoryOperation(operationId))
             return this.dispatch(operationId, input, init);
         // The gateway binds the organization context itself. A refusal is only explained here; the client never changes a session or its context.
@@ -189,7 +245,7 @@ export class GenesisClient {
         const url = this.url(operationId, input);
         const headers = {
             accept: 'application/json',
-            'user-agent': this.opts.userAgent ?? '@onesi/genesis/0.2.3',
+            'user-agent': this.opts.userAgent ?? '@onesi/genesis/0.2.5',
             ...this.opts.headers, ...init.headers,
         };
         if (op.service === 'blinds' && !['GET', 'HEAD', 'OPTIONS'].includes(op.method))

package/dist/errors.d.ts

@@ -1,3 +1,7 @@
+/** An error body is read to at most this many bytes, before any parsing or redaction; the rest is dropped. */
+export declare const ERROR_BODY_READ_LIMIT: number;
+/** Read at most `limit` bytes of a response body as text, cancelling the stream once the limit is reached. */
+export declare function readCappedText(res: Response, limit?: number): Promise<string>;
 /** Normalized error for every Genesis service (gateway `{error:{type,message}}`, IAM `{error,error_description}`, Relays `{error}`, Foundry/OpenAI shape). */
 export declare class GenesisError extends Error {
     readonly status: number;

package/dist/errors.js

@@ -1,4 +1,33 @@
 import { authorizationCode, redactErrorBody } from './redact.js';
+/** An error body is read to at most this many bytes, before any parsing or redaction; the rest is dropped. */
+export const ERROR_BODY_READ_LIMIT = 64 * 1024;
+/** Read at most `limit` bytes of a response body as text, cancelling the stream once the limit is reached. */
+export async function readCappedText(res, limit = ERROR_BODY_READ_LIMIT) {
+    const reader = res.body?.getReader();
+    if (!reader)
+        return (await res.text()).slice(0, limit);
+    const decoder = new TextDecoder();
+    let text = '';
+    let bytes = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            const room = limit - bytes;
+            text += decoder.decode(value.byteLength > room ? value.subarray(0, room) : value, { stream: true });
+            bytes += Math.min(value.byteLength, room);
+            if (bytes >= limit) {
+                void reader.cancel().catch(() => { });
+                break;
+            }
+        }
+        return text + decoder.decode();
+    }
+    finally {
+        reader.releaseLock?.();
+    }
+}
 /** Normalized error for every Genesis service (gateway `{error:{type,message}}`, IAM `{error,error_description}`, Relays `{error}`, Foundry/OpenAI shape). */
 export class GenesisError extends Error {
     status;
@@ -16,7 +45,7 @@ export class GenesisError extends Error {
         this.body = init.body;
     }
     static async fromResponse(res, operationId) {
-        const text = await res.text().catch(() => '');
+        const text = await readCappedText(res).catch(() => '');
         let body = text;
         try {
             body = text ? JSON.parse(text) : undefined;

package/dist/fleets.d.ts

@@ -141,7 +141,10 @@ export declare function fleetsModule(client: GenesisClient): {
             model: string;
             updated_at?: number;
         }>;
-        set: (api_key: string) => Promise<{
+        /** `model` (optional) must be a model Foundry lists for the key; omit it for the Fleets default. */
+        set: (api_key: string, options?: {
+            model?: string;
+        }) => Promise<{
             connected: boolean;
             model: string;
             updated_at?: number;

package/dist/fleets.js

@@ -26,6 +26,11 @@ function validateKey(apiKey) {
         throw invalid('fleets_setConnection', 'Foundry key must contain 1–4096 UTF-8 bytes without CR, LF or NUL.');
     }
 }
+function validateModel(model) {
+    if (typeof model !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$/.test(model)) {
+        throw invalid('fleets_setConnection', 'Model must be a Foundry model id of 1–128 characters (letters, digits, . _ : / -).');
+    }
+}
 const instanceId = (value, operation) => {
     if (typeof value !== 'string' || !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value)) {
         throw invalid(operation, 'Invalid Fleets instance ID.');
@@ -160,9 +165,12 @@ export function fleetsModule(client) {
         },
         connection: {
             get: () => client.request('fleets_getConnection', {}),
-            set: async (api_key) => {
+            /** `model` (optional) must be a model Foundry lists for the key; omit it for the Fleets default. */
+            set: async (api_key, options = {}) => {
                 validateKey(api_key);
-                return client.request('fleets_setConnection', { body: { api_key } });
+                if (options.model !== undefined)
+                    validateModel(options.model);
+                return client.request('fleets_setConnection', { body: { api_key, ...(options.model !== undefined ? { model: options.model } : {}) } });
             },
             delete: () => client.request('fleets_deleteConnection', {}),
         },

package/dist/foundry.d.ts

@@ -266,7 +266,8 @@ export declare function foundryModule(client: GenesisClient): {
             [key: string]: unknown;
         }>;
     };
-    /** OpenRouter-style generation lookup by request id; content and feedback need Foundry `admin` (refused today). */
+    /** OpenRouter-style generation lookup by request id, retained content and feedback for your own generations (not billed).
+     * Feedback requires an idempotency key (8-128 characters of A-Z a-z 0-9 _ . : -); reuse it to retry. */
     generation: {
         get: (id: string) => Promise<{
             data: {
@@ -286,7 +287,7 @@ export declare function foundryModule(client: GenesisClient): {
         content: (id: string) => Promise<{
             [key: string]: unknown;
         }>;
-        feedback: (body: In<"foundry_submitGenerationFeedback">["body"]) => Promise<{
+        feedback: (body: In<"foundry_submitGenerationFeedback">["body"], idempotencyKey: string) => Promise<{
             [key: string]: unknown;
         }>;
     };

package/dist/foundry.js

@@ -85,11 +85,12 @@ export function foundryModule(client) {
             status: (workload_id) => client.request('foundry_getWorkloadStatus', { workload_id }),
             terminate: (workload_id) => client.request('foundry_terminateWorkload', { workload_id }),
         },
-        /** OpenRouter-style generation lookup by request id; content and feedback need Foundry `admin` (refused today). */
+        /** OpenRouter-style generation lookup by request id, retained content and feedback for your own generations (not billed).
+         * Feedback requires an idempotency key (8-128 characters of A-Z a-z 0-9 _ . : -); reuse it to retry. */
         generation: {
             get: (id) => client.request('foundry_getGeneration', { id }),
             content: (id) => client.request('foundry_getGenerationContent', { id }),
-            feedback: (body) => client.request('foundry_submitGenerationFeedback', { body }),
+            feedback: async (body, idempotencyKey) => client.request('foundry_submitGenerationFeedback', { body }, { headers: idempotencyHeaders('foundry_submitGenerationFeedback', idempotencyKey) }),
         },
         batches: {
             create: (body) => client.request('foundry_createBatch', { body }),