@onesi/genesis 0.1.13 → 0.2.0

package/dist/instances.d.ts

@@ -1,11 +1,63 @@
 import type { GenesisClient } from './client.js';
-/** Read-only instance inventories. Each needs an interactive One account login with a selected
- * organization and project; the gateway admits nothing else on these products. */
+import type { OperationInput } from './types.js';
+/** Instance inventory and lifecycle. Each needs a One account login with a selected organization
+ * and project, or an org API key whose binding selects them. `create` needs a stable idempotency
+ * key (8-128 printable ASCII characters): reuse it to retry and the same instance is returned.
+ * `delete` runs the instance's stop action (an optional key makes the stop one replayable
+ * operation); Omega's native stop deletes the deployment. Ids are Omega deployment UUIDs. */
 export declare function rigsModule(client: GenesisClient): {
     list: () => Promise<{
         product: "rigs";
         instances: import("./index.js").components["schemas"]["Rigs.Instance"][];
     }>;
+    get: (id: string) => Promise<{
+        product: "rigs";
+        instance: import("./index.js").components["schemas"]["Rigs.Instance"];
+    }>;
+    create: (body: NonNullable<OperationInput<"rigs_createRig">["body"]>, idempotencyKey: string) => Promise<{
+        product: "rigs";
+        instance: import("./index.js").components["schemas"]["Rigs.Instance"];
+    }>;
+    delete: (id: string, idempotencyKey?: string) => Promise<{
+        ok: true;
+        product: "rigs";
+        id: string;
+        capability: "stop";
+        result: {
+            ok?: boolean;
+            capability?: string;
+            status?: string;
+            completed?: boolean;
+            pending?: boolean;
+            bridge?: boolean;
+        };
+    }>;
+    /** `{capability, args}`; the key is required for every capability but `stop`. */
+    action: (id: string, body: NonNullable<OperationInput<"rigs_actOnRig">["body"]>, idempotencyKey?: string) => Promise<{
+        ok: boolean;
+        product: string;
+        id: string;
+        capability: string;
+        result?: {
+            [key: string]: unknown;
+        } | null;
+    } & {
+        [key: string]: unknown;
+    }>;
+    term: (id: string) => Promise<{
+        product: string;
+        id: string;
+        kind?: string;
+        credentials: {
+            url?: string;
+            token?: string;
+            expires_in?: number | string;
+        } & {
+            [key: string]: unknown;
+        };
+    } & {
+        [key: string]: unknown;
+    }>;
 };
 export declare function panesModule(client: GenesisClient): {
     list: () => Promise<{
@@ -14,6 +66,61 @@ export declare function panesModule(client: GenesisClient): {
     } & {
         [key: string]: unknown;
     }>;
+    get: (id: string) => Promise<{
+        product: "panes";
+        instance: import("./index.js").components["schemas"]["Panes.Instance"];
+    } & {
+        [key: string]: unknown;
+    }>;
+    create: (body: NonNullable<OperationInput<"panes_createPane">["body"]>, idempotencyKey: string) => Promise<{
+        product: "panes";
+        instance: import("./index.js").components["schemas"]["Panes.Instance"];
+    } & {
+        [key: string]: unknown;
+    }>;
+    delete: (id: string, idempotencyKey?: string) => Promise<{
+        ok: true;
+        product: "panes";
+        id: string;
+        capability: "stop";
+        result?: {
+            [key: string]: unknown;
+        };
+        accepted?: boolean;
+        completed?: boolean;
+        pending?: boolean;
+        status?: string;
+    } & {
+        [key: string]: unknown;
+    }>;
+    /** `{capability, args}`; the key is required for every capability but `stop`. */
+    action: (id: string, body: NonNullable<OperationInput<"panes_actOnPane">["body"]>, idempotencyKey?: string) => Promise<{
+        ok: boolean;
+        product: string;
+        id: string;
+        capability: string;
+        result?: {
+            [key: string]: unknown;
+        } | null;
+    } & {
+        [key: string]: unknown;
+    }>;
+    term: (id: string) => Promise<{
+        product: string;
+        id: string;
+        kind?: string;
+        credentials: {
+            url?: string;
+            token?: string;
+            expires_in?: number | string;
+        } & {
+            [key: string]: unknown;
+        };
+    } & {
+        [key: string]: unknown;
+    }>;
+    /** The screenshot image as a raw Response (PNG or JPEG). */
+    screenshot: (id: string, artifactId: string) => Promise<unknown>;
 };
 export declare function shellsModule(client: GenesisClient): {
     list: () => Promise<{
@@ -22,4 +129,72 @@ export declare function shellsModule(client: GenesisClient): {
     } & {
         [key: string]: unknown;
     }>;
+    get: (id: string) => Promise<{
+        product: "shells";
+        instance: import("./index.js").components["schemas"]["Shells.Instance"];
+    } & {
+        [key: string]: unknown;
+    }>;
+    create: (body: NonNullable<OperationInput<"shells_createShell">["body"]>, idempotencyKey: string) => Promise<{
+        product: "shells";
+        instance: import("./index.js").components["schemas"]["Shells.Instance"];
+    } & {
+        [key: string]: unknown;
+    }>;
+    delete: (id: string, idempotencyKey?: string) => Promise<{
+        ok: true;
+        product: "shells";
+        id: string;
+        capability: "stop";
+        result?: {
+            [key: string]: unknown;
+        };
+        cambium?: unknown;
+    } & {
+        [key: string]: unknown;
+    }>;
+    /** `{capability, args}`; the key is required for every capability but `stop`. */
+    action: (id: string, body: NonNullable<OperationInput<"shells_actOnShell">["body"]>, idempotencyKey?: string) => Promise<{
+        ok: boolean;
+        product: string;
+        id: string;
+        capability: string;
+        result?: {
+            [key: string]: unknown;
+        } | null;
+    } & {
+        [key: string]: unknown;
+    }>;
+    term: (id: string) => Promise<{
+        product: string;
+        id: string;
+        kind?: string;
+        credentials: {
+            url?: string;
+            token?: string;
+            expires_in?: number | string;
+        } & {
+            [key: string]: unknown;
+        };
+    } & {
+        [key: string]: unknown;
+    }>;
+    /** One-shot exec; a repeat with the same key and body replays the stored result. */
+    exec: (id: string, body: NonNullable<OperationInput<"shells_execShell">["body"]>, idempotencyKey: string) => Promise<{
+        ok: true;
+        product: "shells";
+        id: string;
+        result: {
+            exitCode: number | null;
+            encoding: "base64";
+            stdout: string;
+            stderr: string;
+            truncated: {
+                stdout?: boolean;
+                stderr?: boolean;
+            };
+            timedOut: boolean;
+            durationMs: number;
+        };
+    }>;
 };

package/dist/instances.js

@@ -1,11 +1,43 @@
-/** Read-only instance inventories. Each needs an interactive One account login with a selected
- * organization and project; the gateway admits nothing else on these products. */
+import { idempotencyHeaders } from './idempotency.js';
+/** Instance inventory and lifecycle. Each needs a One account login with a selected organization
+ * and project, or an org API key whose binding selects them. `create` needs a stable idempotency
+ * key (8-128 printable ASCII characters): reuse it to retry and the same instance is returned.
+ * `delete` runs the instance's stop action (an optional key makes the stop one replayable
+ * operation); Omega's native stop deletes the deployment. Ids are Omega deployment UUIDs. */
 export function rigsModule(client) {
-    return { list: () => client.request('rigs_listRigs') };
+    return {
+        list: () => client.request('rigs_listRigs'),
+        get: (id) => client.request('rigs_getRig', { id }),
+        create: (body, idempotencyKey) => client.request('rigs_createRig', { body }, { headers: idempotencyHeaders('rigs_createRig', idempotencyKey) }),
+        delete: (id, idempotencyKey) => client.request('rigs_deleteRig', { id }, { headers: idempotencyHeaders('rigs_deleteRig', idempotencyKey) }),
+        /** `{capability, args}`; the key is required for every capability but `stop`. */
+        action: (id, body, idempotencyKey) => client.request('rigs_actOnRig', { id, body }, { headers: idempotencyHeaders('rigs_actOnRig', idempotencyKey) }),
+        term: (id) => client.request('rigs_openRigTerm', { id }),
+    };
 }
 export function panesModule(client) {
-    return { list: () => client.request('panes_listPanes') };
+    return {
+        list: () => client.request('panes_listPanes'),
+        get: (id) => client.request('panes_getPane', { id }),
+        create: (body, idempotencyKey) => client.request('panes_createPane', { body }, { headers: idempotencyHeaders('panes_createPane', idempotencyKey) }),
+        delete: (id, idempotencyKey) => client.request('panes_deletePane', { id }, { headers: idempotencyHeaders('panes_deletePane', idempotencyKey) }),
+        /** `{capability, args}`; the key is required for every capability but `stop`. */
+        action: (id, body, idempotencyKey) => client.request('panes_actOnPane', { id, body }, { headers: idempotencyHeaders('panes_actOnPane', idempotencyKey) }),
+        term: (id) => client.request('panes_openPaneTerm', { id }),
+        /** The screenshot image as a raw Response (PNG or JPEG). */
+        screenshot: (id, artifactId) => client.request('panes_getPaneScreenshotData', { id, artifactId }),
+    };
 }
 export function shellsModule(client) {
-    return { list: () => client.request('shells_listShells') };
+    return {
+        list: () => client.request('shells_listShells'),
+        get: (id) => client.request('shells_getShell', { id }),
+        create: (body, idempotencyKey) => client.request('shells_createShell', { body }, { headers: idempotencyHeaders('shells_createShell', idempotencyKey) }),
+        delete: (id, idempotencyKey) => client.request('shells_deleteShell', { id }, { headers: idempotencyHeaders('shells_deleteShell', idempotencyKey) }),
+        /** `{capability, args}`; the key is required for every capability but `stop`. */
+        action: (id, body, idempotencyKey) => client.request('shells_actOnShell', { id, body }, { headers: idempotencyHeaders('shells_actOnShell', idempotencyKey) }),
+        term: (id) => client.request('shells_openShellTerm', { id }),
+        /** One-shot exec; a repeat with the same key and body replays the stored result. */
+        exec: (id, body, idempotencyKey) => client.request('shells_execShell', { id, body }, { headers: idempotencyHeaders('shells_execShell', idempotencyKey) }),
+    };
 }

package/dist/minds-agent.d.ts

@@ -1,6 +1,9 @@
 import type { GenesisClient } from './client.js';
 import { GenesisError } from './errors.js';
 export declare const mindsAgentOperations: readonly ["minds_agentInsertEpisodicMemory", "minds_agentGetEpisodicMemory", "minds_agentSearchMemory"];
+/** Agent Mind creation: an approved agent-create token with DPoP, default-off at the gateway (MINDS_AGENT_CREATE_ENABLED). */
+export declare const mindsAgentCreateOperations: readonly ["minds_agentCreateMind", "minds_agentGetCreateOperation"];
+export declare const isMindsAgentCreateOperation: (id: string) => boolean;
 export declare const isMindsAgentOperation: (id: string) => boolean;
 declare const EVENT_TYPES: readonly ["Conversation", "Command", "Query", "Document", "Error", "Success", "Learning", "Decision", "Action", "Context", "Knowledge"];
 type Row = Record<string, unknown>;
@@ -12,6 +15,18 @@ export interface MindsAgentEventInput {
     summary?: string | null;
     tags?: string[];
 }
+export interface MindsAgentCreateInput {
+    /** "Sandbox" or "Sandbox <label>", at most 80 characters. */
+    name: string;
+    approvalId: string;
+    approvalVersion: number;
+    /** Persisted UUID4 for this creation; also the idempotency key and the status lookup id. */
+    operationId: string;
+}
+export interface MindsAgentCreateOptions {
+    dpopProof: string;
+    signal?: AbortSignal;
+}
 export interface MindsAgentOptions {
     /** Omit for the agent's private namespace; group authority is checked by the controller. */
     group?: string;
@@ -38,6 +53,19 @@ export declare function mindsAgentTransport(options: {
     signal?: AbortSignal;
 }): Promise<Response>;
 export declare function mindsAgentModule(client: GenesisClient): {
+    /** Free/F1 Sandbox only; the fixed spec is the only shape the gateway admits. */
+    create: (input: MindsAgentCreateInput, options: MindsAgentCreateOptions) => Promise<{
+        mind_id: string;
+        status: string;
+    } & {
+        [key: string]: unknown;
+    }>;
+    createStatus: (operation_id: string, options: MindsAgentCreateOptions) => Promise<{
+        mind_id: string;
+        status: string;
+    } & {
+        [key: string]: unknown;
+    }>;
     memory: {
         insert: (mind: string, event: MindsAgentEventInput, options?: MindsAgentOptions) => Promise<{
             id: string;

package/dist/minds-agent.js

@@ -1,6 +1,9 @@
 import { envelopeExtrasValid, ENVELOPE_EXTRA_FIELDS, GenesisError } from './errors.js';
 export const mindsAgentOperations = ['minds_agentInsertEpisodicMemory', 'minds_agentGetEpisodicMemory', 'minds_agentSearchMemory'];
-export const isMindsAgentOperation = (id) => mindsAgentOperations.includes(id);
+/** Agent Mind creation: an approved agent-create token with DPoP, default-off at the gateway (MINDS_AGENT_CREATE_ENABLED). */
+export const mindsAgentCreateOperations = ['minds_agentCreateMind', 'minds_agentGetCreateOperation'];
+export const isMindsAgentCreateOperation = (id) => mindsAgentCreateOperations.includes(id);
+export const isMindsAgentOperation = (id) => mindsAgentOperations.includes(id) || isMindsAgentCreateOperation(id);
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 const UUID4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
 const GROUP = /^agp_[0-7][0-9A-HJKMNP-TV-Z]{25}$/;
@@ -35,24 +38,43 @@ function validStoredEvent(value) {
     return row(value) && text(value.id, 36) && UUID.test(value.id) && text(value.content, 1_000_000)
         && date(value.timestamp) && eventType(value.event_type) && Array.isArray(value.tags) && value.tags.every(tag => typeof tag === 'string');
 }
+function validCreation(value) {
+    if (!row(value) || !exact(value, ['schemaVersion', 'approvalId', 'approvalVersion', 'operationId', 'spec']) || value.schemaVersion !== 1
+        || typeof value.approvalId !== 'string' || !UUID4.test(value.approvalId) || typeof value.operationId !== 'string' || !UUID4.test(value.operationId)
+        || !Number.isSafeInteger(value.approvalVersion) || Number(value.approvalVersion) < 1)
+        return false;
+    const spec = value.spec, capacity = row(spec) ? spec.capacity : undefined;
+    return row(spec) && row(capacity) && exact(spec, ['name', 'region', 'plan', 'capacity', 'services'])
+        && exact(capacity, ['profile_id', 'cpus', 'memory_mb', 'volume_size_gb']) && typeof spec.name === 'string' && spec.name.trim() === spec.name
+        && [...spec.name].length <= 80 && (spec.name === 'Sandbox' || spec.name.startsWith('Sandbox ')) && !/[\u0000-\u001f\u007f-\u009f]/.test(spec.name)
+        && spec.region === 'us-central1-a' && spec.plan === 'free' && capacity.profile_id === 'F1' && capacity.cpus === 1 && capacity.memory_mb === 512
+        && capacity.volume_size_gb === 1 && JSON.stringify(spec.services) === '["kv","memory"]';
+}
 /** A single agent request: no human context selection, credential exchange or automatic retry. */
 export async function mindsAgentTransport(options) {
     const { operationId: id, input } = options;
-    const write = id === 'minds_agentInsertEpisodicMemory', read = id === 'minds_agentGetEpisodicMemory';
+    const create = id === 'minds_agentCreateMind', status = id === 'minds_agentGetCreateOperation', creation = create || status;
+    const write = id === 'minds_agentInsertEpisodicMemory' || create, read = id === 'minds_agentGetEpisodicMemory' || status;
     let dispatched = false;
     const fail = (status, type, details = {}) => new MindsAgentError({
         status, type, operationId: id, code: details.code, requestId: details.requestId, dpopNonce: details.dpopNonce,
-        message: 'Agent memory request was not confirmed. Inspect the error before an explicit retry.',
+        message: creation ? (details.code === 'SERVICE_UNAVAILABLE' ? 'Agent Mind creation is not enabled on this gateway (MINDS_AGENT_CREATE_ENABLED).'
+            : 'Agent Mind creation was not confirmed. Read the operation status with the same operationId before an explicit retry.')
+            : 'Agent memory request was not confirmed. Inspect the error before an explicit retry.',
         ...(details.unknown || write && dispatched && (status === 0 || status >= 500 || type === 'invalid_response' && status >= 200 && status < 300)
             ? { body: { outcome: 'unknown' } } : {}),
     });
+    if (creation && (options.routing !== 'gateway' || !exact(input, status ? ['operation_id'] : ['body'])
+        || (status ? typeof input.operation_id !== 'string' || !UUID4.test(input.operation_id) : !validCreation(input.body))
+        || !options.headers || !Object.keys(options.headers).some(name => name.toLowerCase() === 'dpop')))
+        throw fail(0, 'invalid_request');
     const fields = read ? ['mind', 'storage_id'] : ['mind', 'body'];
-    if (options.routing !== 'gateway' || !isMindsAgentOperation(id) || !exact(input, fields, ['group'])
+    if (!creation && (options.routing !== 'gateway' || !isMindsAgentOperation(id) || !exact(input, fields, ['group'])
         || typeof input.mind !== 'string' || !UUID.test(input.mind)
         || input.group !== undefined && (typeof input.group !== 'string' || !GROUP.test(input.group))
-        || read && (typeof input.storage_id !== 'string' || !UUID.test(input.storage_id)))
+        || read && (typeof input.storage_id !== 'string' || !UUID.test(input.storage_id))))
         throw fail(0, 'invalid_request');
-    if (!read && (!row(input.body) || (write ? !exact(input.body, ['event']) || !validEvent(input.body.event)
+    if (!creation && !read && (!row(input.body) || (write ? !exact(input.body, ['event']) || !validEvent(input.body.event)
         : !exact(input.body, ['text'], ['limit']) || !text(input.body.text, 1_000) || !input.body.text.trim()
             || input.body.limit !== undefined && (!Number.isInteger(input.body.limit) || Number(input.body.limit) < 1 || Number(input.body.limit) > 100))))
         throw fail(0, 'invalid_request');
@@ -98,7 +120,7 @@ export async function mindsAgentTransport(options) {
             dispatched = true;
             return options.fetch(options.url, { method: read ? 'GET' : 'POST', redirect: 'error', cache: 'no-store', signal: controller.signal,
                 headers: { authorization: `Bearer ${credential}`, accept: 'application/json', ...(body === undefined ? {} : { 'content-type': 'application/json' }),
-                    ...(headerEntries.length ? { dpop: headerEntries[0][1] } : {}) }, ...(body === undefined ? {} : { body }) }).then(response => {
+                    ...(headerEntries.length ? { dpop: headerEntries[0][1] } : {}), ...(create ? { 'idempotency-key': input.body.operationId } : {}) }, ...(body === undefined ? {} : { body }) }).then(response => {
                 if (controller.signal.aborted) {
                     void response.body?.cancel().catch(() => { });
                     throw fail(0, 'transport_error');
@@ -149,14 +171,23 @@ export async function mindsAgentTransport(options) {
             if (!row(value) || !exact(value, ['error']) || !row(value.error) || !exact(value.error, ['code', 'request_id'], ['outcome', ...ENVELOPE_EXTRA_FIELDS]) || !envelopeExtrasValid(value.error)
                 || !text(value.error.code, 128) || !/^[A-Z][A-Z0-9_]*$/.test(value.error.code)
                 || !text(value.error.request_id, 256) || /[^\x21-\x7e]/.test(value.error.request_id)
-                || value.error.outcome !== undefined && value.error.outcome !== 'unknown')
+                || value.error.outcome !== undefined && value.error.outcome !== 'unknown') {
+                // Controller refusals pass through the agent-create route verbatim; keep the status, never invent a code.
+                if (creation)
+                    throw fail(response.status, 'minds_agent_error', { unknown: create && response.status >= 500 });
                 throw fail(response.status, 'invalid_response');
+            }
             const nonce = response.headers.get('dpop-nonce');
             if (value.error.code === 'DPOP_NONCE_REQUIRED' && (response.status !== 401 || !nonce || !/^[A-Za-z0-9_-]{1,512}$/.test(nonce)))
                 throw fail(response.status, 'invalid_response');
             throw fail(response.status, 'minds_agent_error', { code: value.error.code, requestId: value.error.request_id,
                 ...(value.error.code === 'DPOP_NONCE_REQUIRED' ? { dpopNonce: nonce } : {}), unknown: write && value.error.outcome === 'unknown' });
         }
+        if (creation) {
+            if (response.status !== (create ? 202 : 200) || !row(value) || typeof value.mind_id !== 'string' || !UUID.test(value.mind_id) || typeof value.status !== 'string')
+                throw fail(response.status, 'invalid_response');
+            return Response.json(value, { status: response.status, headers: { 'cache-control': 'private, no-store' } });
+        }
         if (response.status !== 200 || (write ? !row(value) || !exact(value, ['id']) || !text(value.id, 36) || !UUID.test(value.id)
             : read ? !row(value) || !exact(value, ['item']) || value.item !== null && !validStoredEvent(value.item)
                 : !Array.isArray(value) || value.length > Number(input.body.limit ?? 20) || !value.every(validStoredEvent)))
@@ -182,9 +213,21 @@ export function mindsAgentModule(client) {
         return { signal: options.signal, ...(options.dpopProof === undefined ? {} : { headers: { dpop: options.dpopProof } }) };
     };
     const query = (mind, options) => ({ mind, ...(options.group === undefined ? {} : { group: options.group }) });
-    return { memory: {
+    const proof = (options) => {
+        if (!row(options) || !exact(options, ['dpopProof'], ['signal']) || typeof options.dpopProof !== 'string')
+            throw new MindsAgentError({ status: 0, type: 'invalid_request', message: 'Agent Mind creation requires an explicit DPoP proof.' });
+        return { signal: options.signal, headers: { dpop: options.dpopProof } };
+    };
+    return {
+        /** Free/F1 Sandbox only; the fixed spec is the only shape the gateway admits. */
+        create: (input, options) => client.request('minds_agentCreateMind', { body: { schemaVersion: 1,
+                approvalId: input.approvalId, approvalVersion: input.approvalVersion, operationId: input.operationId,
+                spec: { name: input.name, region: 'us-central1-a', plan: 'free', capacity: { profile_id: 'F1', cpus: 1, memory_mb: 512, volume_size_gb: 1 }, services: ['kv', 'memory'] } } }, proof(options)),
+        createStatus: (operation_id, options) => client.request('minds_agentGetCreateOperation', { operation_id }, proof(options)),
+        memory: {
             insert: (mind, event, options = {}) => client.request('minds_agentInsertEpisodicMemory', { ...query(mind, options), body: { event } }, init(options)),
             get: (mind, storage_id, options = {}) => client.request('minds_agentGetEpisodicMemory', { ...query(mind, options), storage_id }, init(options)),
             search: (mind, text, limit = 20, options = {}) => client.request('minds_agentSearchMemory', { ...query(mind, options), body: { text, limit } }, init(options)),
-        } };
+        }
+    };
 }