@onesi/genesis 0.0.1-stage → 0.1.13

package/dist/minds.js

@@ -0,0 +1,193 @@
+import { GenesisError } from './errors.js';
+import { mindsAgentModule } from './minds-agent.js';
+import { mindsOwnerModule } from './minds-owner.js';
+export const mindsOperations = ['minds_listMinds', 'minds_getMind', 'minds_getUsage', 'minds_createMind', 'minds_resumeMind', 'minds_stopMind', 'minds_insertEpisodicMemory', 'minds_getEpisodicMemory', 'minds_updateEpisodicMemory', 'minds_searchMemory'];
+export const isMindsOperation = (id) => mindsOperations.includes(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 writes = new Set(['minds_createMind', 'minds_resumeMind', 'minds_stopMind', 'minds_insertEpisodicMemory', 'minds_updateEpisodicMemory']);
+// Match the native gateway's RFC3339/calendar and nanosecond window bounds.
+function usageInstant(value) {
+    if (typeof value !== 'string' || value.length > 40)
+        return undefined;
+    const match = /^(\d{4})-(\d\d)-(\d\d)[Tt](\d\d):(\d\d):(\d\d)(?:\.(\d{1,9}))?([Zz]|([+-])(\d\d):(\d\d))$/.exec(value);
+    if (!match)
+        return undefined;
+    const [, year, month, day, hour, minute, second, fraction, zone, sign, offsetHour, offsetMinute] = match;
+    const [y, mo, d, h, mi, s] = [year, month, day, hour, minute, second].map(Number);
+    if (mo < 1 || mo > 12 || d < 1 || d > 31 || h > 23 || mi > 59 || s > 59
+        || (zone.toUpperCase() !== 'Z' && (Number(offsetHour) > 23 || Number(offsetMinute) > 59)))
+        return undefined;
+    const parsed = new Date(0);
+    parsed.setUTCFullYear(y, mo - 1, d);
+    parsed.setUTCHours(h, mi, s, 0);
+    if (parsed.getUTCFullYear() !== y || parsed.getUTCMonth() !== mo - 1 || parsed.getUTCDate() !== d)
+        return undefined;
+    const offset = zone.toUpperCase() === 'Z' ? 0 : (Number(offsetHour) * 60 + Number(offsetMinute)) * (sign === '+' ? 1 : -1);
+    return BigInt(parsed.getTime() - offset * 60_000) * 1000000n + BigInt((fraction ?? '').padEnd(9, '0'));
+}
+/** One dispatch only. Creation retains its operation key; episodic insertion returns a storage UUID distinct from event.id. */
+export async function mindsTransport(options) {
+    const id = options.operationId, input = options.input, write = writes.has(id);
+    let dispatchAttempted = false;
+    const error = (status, type, code, unknownOutcome = false) => new GenesisError({ status, type, code, operationId: id,
+        message: status === 403 ? 'Minds requires an admitted original human One account session with a Console Sandbox selection.'
+            : write ? 'Minds write was not confirmed. Preserve the lifecycle/create key or reconcile memory before an explicit retry.' : 'Minds request was not confirmed.',
+        ...(write && (unknownOutcome || dispatchAttempted && (status === 0 || status >= 500 || type === 'invalid_response')) ? { body: { outcome: 'unknown' } } : {}) });
+    const fields = id === 'minds_getUsage' ? ['from', 'to'] : id === 'minds_listMinds' ? ['after', 'limit'] : id === 'minds_getMind' ? ['mind_id'] : id === 'minds_updateEpisodicMemory' ? ['mind', 'storage_id', 'body'] : ['minds_resumeMind', 'minds_stopMind'].includes(id) ? ['mind_id', 'body']
+        : id === 'minds_createMind' ? ['body'] : id === 'minds_getEpisodicMemory' ? ['mind', 'storage_id'] : ['mind', 'body'];
+    if (options.routing !== 'gateway' || !isMindsOperation(id) || Object.keys(input).some(key => !fields.includes(key)))
+        throw error(0, 'invalid_request');
+    if (id === 'minds_getUsage') {
+        const from = usageInstant(input.from), to = usageInstant(input.to);
+        if (from === undefined || to === undefined || to <= from || to - from > 93n * 86400n * 1000000000n)
+            throw error(0, 'invalid_request');
+    }
+    for (const key of ['mind', 'mind_id', 'storage_id', 'after'])
+        if (input[key] !== undefined && (typeof input[key] !== 'string' || !uuid.test(input[key])))
+            throw error(0, 'invalid_request');
+    if (id === 'minds_updateEpisodicMemory') {
+        const body = input.body;
+        if (typeof input.mind !== 'string' || input.mind.length !== 36 || typeof input.storage_id !== 'string' || input.storage_id.length !== 36
+            || !body || typeof body !== 'object' || Array.isArray(body) || Object.keys(body).sort().join() !== 'content,event_id'
+            || typeof body.event_id !== 'string' || body.event_id.length !== 36 || !uuid.test(body.event_id)
+            || typeof body.content !== 'string' || !body.content.trim() || body.content.length > 16_000)
+            throw error(0, 'invalid_request');
+    }
+    if (id === 'minds_createMind') {
+        const body = input.body;
+        if (!uuid4.test(options.headers?.['idempotency-key'] ?? '') || !/^[a-f0-9]{64}$/.test(options.headers?.['x-genesis-minds-creation-context'] ?? '')
+            || !body || typeof body !== 'object' || Array.isArray(body) || typeof body.name !== 'string'
+            || Object.keys(body).some(key => !['name', 'plan', 'profile_id'].includes(key))
+            || (body.plan !== undefined && body.plan !== 'free' && body.plan !== 'pro')
+            || (body.profile_id !== undefined && (typeof body.profile_id !== 'string' || !['F1', 'D1', 'D2'].includes(body.profile_id) || (body.plan !== 'pro' && body.profile_id !== 'F1'))))
+            throw error(0, 'invalid_request');
+    }
+    if (id === 'minds_resumeMind' || id === 'minds_stopMind') {
+        const body = input.body;
+        if (!uuid4.test(options.headers?.['idempotency-key'] ?? '') || !body || typeof body !== 'object' || Array.isArray(body)
+            || Object.keys(body).some(key => !(id === 'minds_resumeMind' ? ['expected_generation', 'wake_reason'] : ['expected_generation']).includes(key))
+            || (body.wake_reason !== undefined && (typeof body.wake_reason !== 'string' || !['manual', 'scheduled_job', 'webhook', 'memory_consolidation', 'activity'].includes(body.wake_reason)))
+            || !Number.isSafeInteger(body.expected_generation) || body.expected_generation < 1
+            || body.expected_generation >= Number.MAX_SAFE_INTEGER)
+            throw error(0, 'invalid_request');
+    }
+    const controller = new AbortController(), cancel = () => controller.abort(options.signal?.reason);
+    options.signal?.addEventListener('abort', cancel, { once: true });
+    if (options.signal?.aborted)
+        cancel();
+    const timer = setTimeout(() => controller.abort(), 35_000);
+    async function bounded(work) {
+        controller.signal.throwIfAborted();
+        let abort = () => { };
+        try {
+            return await Promise.race([work(), new Promise((_, reject) => { abort = () => reject(error(0, 'transport_error')); controller.signal.addEventListener('abort', abort, { once: true }); })]);
+        }
+        finally {
+            controller.signal.removeEventListener('abort', abort);
+        }
+    }
+    try {
+        const credential = await bounded(options.credential);
+        controller.signal.throwIfAborted();
+        if (!credential)
+            throw error(401, 'unauthenticated');
+        const body = Object.hasOwn(input, 'body') ? JSON.stringify(input.body) : undefined;
+        if (body !== undefined && new TextEncoder().encode(body).length > 65_536)
+            throw error(0, 'invalid_request');
+        const response = await bounded(() => {
+            dispatchAttempted = true;
+            return options.fetch(options.url, { method: id === 'minds_updateEpisodicMemory' ? 'PUT' : ['minds_listMinds', 'minds_getMind', 'minds_getUsage', 'minds_getEpisodicMemory'].includes(id) ? 'GET' : 'POST',
+                headers: { authorization: `Bearer ${credential}`, accept: 'application/json', ...(body === undefined ? {} : { 'content-type': 'application/json' }),
+                    ...(['minds_resumeMind', 'minds_stopMind'].includes(id) ? { 'idempotency-key': options.headers['idempotency-key'] } : {}),
+                    ...(id === 'minds_createMind' ? { 'idempotency-key': options.headers['idempotency-key'], 'x-genesis-minds-creation-context': options.headers['x-genesis-minds-creation-context'] } : {}) },
+                ...(body === undefined ? {} : { body }), signal: controller.signal, redirect: 'error', cache: 'no-store' }).then(result => {
+                if (controller.signal.aborted) {
+                    void result.body?.cancel().catch(() => { });
+                    throw error(0, 'transport_error');
+                }
+                return result;
+            });
+        });
+        const reader = response.body?.getReader();
+        if (!reader)
+            throw error(response.status, 'invalid_response');
+        const chunks = [];
+        let size = 0;
+        const stop = () => { void reader.cancel().catch(() => { }); };
+        controller.signal.addEventListener('abort', stop, { once: true });
+        try {
+            for (;;) {
+                const next = await bounded(() => reader.read());
+                if (next.done)
+                    break;
+                size += next.value.length;
+                if (size > 2 * 1024 * 1024)
+                    throw error(response.status, 'invalid_response');
+                chunks.push(next.value);
+            }
+        }
+        finally {
+            controller.signal.removeEventListener('abort', stop);
+            stop();
+            try {
+                reader.releaseLock();
+            }
+            catch { /* cancellation owns a pending read */ }
+        }
+        const bytes = new Uint8Array(size);
+        let offset = 0;
+        for (const chunk of chunks) {
+            bytes.set(chunk, offset);
+            offset += chunk.length;
+        }
+        let value;
+        try {
+            value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+        }
+        catch {
+            throw error(response.status, 'invalid_response');
+        }
+        if (!response.ok) {
+            const row = value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+            const detail = row && Object.hasOwn(row, 'error') && row.error && typeof row.error === 'object' && !Array.isArray(row.error)
+                ? row.error : undefined;
+            const code = detail && Object.hasOwn(detail, 'code') && typeof detail.code === 'string' ? detail.code : undefined;
+            const unknownOutcome = ['minds_resumeMind', 'minds_stopMind'].includes(id) && response.status === 401 && code === 'SELECTION_EXPIRED'
+                && detail !== undefined && Object.hasOwn(detail, 'outcome') && detail.outcome === 'unknown';
+            throw error(response.status, 'minds_error', code, unknownOutcome);
+        }
+        if (['minds_createMind', 'minds_resumeMind', 'minds_stopMind'].includes(id) && response.status !== 202)
+            throw error(response.status, 'invalid_response');
+        return Response.json(value, { status: response.status, headers: { 'cache-control': 'no-store' } });
+    }
+    catch (cause) {
+        if (cause instanceof GenesisError)
+            throw cause;
+        throw error(0, 'transport_error');
+    }
+    finally {
+        clearTimeout(timer);
+        controller.abort();
+        options.signal?.removeEventListener('abort', cancel);
+    }
+}
+export function mindsModule(client) {
+    return {
+        ...mindsOwnerModule(client),
+        agent: mindsAgentModule(client),
+        list: (query = {}, options = {}) => client.request('minds_listMinds', query, options),
+        get: (mind_id, options = {}) => client.request('minds_getMind', { mind_id }, options),
+        usage: (window, options = {}) => client.request('minds_getUsage', window, options),
+        create: (name, options) => client.request('minds_createMind', { body: { name, ...(options.plan === undefined ? {} : { plan: options.plan }), ...(options.profileId === undefined ? {} : { profile_id: options.profileId }) } }, { signal: options.signal,
+            headers: { 'idempotency-key': options.idempotencyKey, 'x-genesis-minds-creation-context': options.contextSha256 } }),
+        resume: (mind_id, expected_generation, options) => client.request('minds_resumeMind', { mind_id, body: { expected_generation, ...(options.wakeReason === undefined ? {} : { wake_reason: options.wakeReason }) } }, { signal: options.signal, headers: { 'idempotency-key': options.idempotencyKey } }),
+        stop: (mind_id, expected_generation, options) => client.request('minds_stopMind', { mind_id, body: { expected_generation } }, { signal: options.signal, headers: { 'idempotency-key': options.idempotencyKey } }),
+        memory: {
+            insert: (mind, event, options = {}) => client.request('minds_insertEpisodicMemory', { mind, body: { event } }, options),
+            get: (mind, storage_id, options = {}) => client.request('minds_getEpisodicMemory', { mind, storage_id }, options),
+            update: (mind, storage_id, body, options = {}) => client.request('minds_updateEpisodicMemory', { mind, storage_id, body }, options),
+            search: (mind, text, limit = 20, options = {}) => client.request('minds_searchMemory', { mind, body: { text, limit } }, options),
+        },
+    };
+}

package/dist/relays-enrollment.d.ts

@@ -0,0 +1,33 @@
+import type { GenesisClient } from './client.js';
+export declare const isRelaysEnrollmentOperation: (id: string) => id is "relays_getEnrollment" | "relays_enroll";
+/** Read status or send one explicit bodyless enrollment. No inferred tenant or mutation replay. */
+export declare function relaysEnrollmentTransport(options: {
+    operationId: string;
+    input: Record<string, unknown>;
+    routing: string;
+    url: string;
+    credential: () => Promise<string | undefined>;
+    fetch: typeof fetch;
+    signal?: AbortSignal;
+}): Promise<Response>;
+export declare function relaysEnrollment(client: GenesisClient): {
+    get: (options?: {
+        signal?: AbortSignal;
+    }) => Promise<{
+        state: "ready" | "not_enrolled";
+        organizationId: string;
+        projectId: string;
+        workspaceId: string;
+        resourceEnvironment: "sandbox";
+    }>;
+    activate: (options?: {
+        signal?: AbortSignal;
+    }) => Promise<{
+        state: "ready";
+        organizationId: string;
+        projectId: string;
+        workspaceId: string;
+        resourceEnvironment: "sandbox";
+        created: boolean;
+    }>;
+};

package/dist/relays-enrollment.js

@@ -0,0 +1,115 @@
+import { GenesisError } from './errors.js';
+export const isRelaysEnrollmentOperation = (id) => id === 'relays_getEnrollment' || id === 'relays_enroll';
+const nativeId = (value, prefix) => typeof value === 'string'
+    && value.startsWith(prefix) && /^[A-Za-z0-9_-]{1,128}$/.test(value.slice(prefix.length));
+/** Read status or send one explicit bodyless enrollment. No inferred tenant or mutation replay. */
+export async function relaysEnrollmentTransport(options) {
+    const write = options.operationId === 'relays_enroll';
+    const error = (status, type) => new GenesisError({ status, type, operationId: options.operationId,
+        message: 'Relays enrollment was not confirmed. Read enrollment status before explicitly trying another activation.' });
+    if (options.routing !== 'gateway' || !options.input || typeof options.input !== 'object'
+        || Array.isArray(options.input) || Object.keys(options.input).length)
+        throw error(0, 'invalid_request');
+    const controller = new AbortController();
+    const cancel = () => controller.abort(options.signal?.reason);
+    options.signal?.addEventListener('abort', cancel, { once: true });
+    if (options.signal?.aborted)
+        cancel();
+    const timer = setTimeout(() => controller.abort(), 20_000);
+    async function bounded(promise) {
+        controller.signal.throwIfAborted();
+        let abort = () => { };
+        try {
+            return await Promise.race([promise, new Promise((_, reject) => {
+                    abort = () => reject(error(0, 'transport_error'));
+                    controller.signal.addEventListener('abort', abort, { once: true });
+                })]);
+        }
+        finally {
+            controller.signal.removeEventListener('abort', abort);
+        }
+    }
+    try {
+        controller.signal.throwIfAborted();
+        const credential = await bounded(options.credential());
+        controller.signal.throwIfAborted();
+        if (!credential)
+            throw error(401, 'unauthenticated');
+        const response = await bounded(options.fetch(options.url, { method: write ? 'POST' : 'GET',
+            headers: { authorization: `Bearer ${credential}`, accept: 'application/json' },
+            redirect: 'error', cache: 'no-store', signal: controller.signal }).then(response => {
+            if (controller.signal.aborted) {
+                void response.body?.cancel().catch(() => { });
+                throw error(0, 'transport_error');
+            }
+            return response;
+        }));
+        if (!(response.status === 200 || write && response.status === 201)) {
+            void response.body?.cancel().catch(() => { });
+            throw error(response.status, 'enrollment_unconfirmed');
+        }
+        if (!response.body || !/^application\/json(?:;|$)/i.test(response.headers.get('content-type') ?? '')) {
+            void response.body?.cancel().catch(() => { });
+            throw error(0, 'invalid_response');
+        }
+        const reader = response.body.getReader(), chunks = [];
+        let size = 0;
+        const stop = () => { void reader.cancel().catch(() => { }); };
+        controller.signal.addEventListener('abort', stop, { once: true });
+        try {
+            for (;;) {
+                const next = await bounded(reader.read());
+                if (next.done)
+                    break;
+                size += next.value.length;
+                if (size > 8192)
+                    throw error(0, 'invalid_response');
+                chunks.push(next.value);
+            }
+        }
+        finally {
+            controller.signal.removeEventListener('abort', stop);
+            stop();
+            try {
+                reader.releaseLock();
+            }
+            catch { /* cancelled read */ }
+        }
+        const bytes = new Uint8Array(size);
+        let offset = 0;
+        for (const chunk of chunks) {
+            bytes.set(chunk, offset);
+            offset += chunk.length;
+        }
+        let value;
+        try {
+            value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+        }
+        catch {
+            throw error(0, 'invalid_response');
+        }
+        const fields = ['state', 'organizationId', 'projectId', 'workspaceId', 'resourceEnvironment', ...(write ? ['created'] : [])];
+        if (!value || Array.isArray(value) || Object.keys(value).length !== fields.length || Object.keys(value).some(k => !fields.includes(k))
+            || !nativeId(value.organizationId, 'o_') || !nativeId(value.projectId, 'pr_') || !nativeId(value.workspaceId, 'w_')
+            || value.resourceEnvironment !== 'sandbox' || !['ready', ...(write ? [] : ['not_enrolled'])].includes(String(value.state))
+            || write && value.created !== (response.status === 201))
+            throw error(0, 'invalid_response');
+        return Response.json(value, { status: response.status, headers: { 'cache-control': 'no-store' } });
+    }
+    catch (e) {
+        if (e instanceof GenesisError)
+            throw e;
+        throw error(0, 'transport_error');
+    }
+    finally {
+        clearTimeout(timer);
+        controller.abort();
+        options.signal?.removeEventListener('abort', cancel);
+    }
+}
+export function relaysEnrollment(client) {
+    return {
+        get: (options = {}) => client.request('relays_getEnrollment', {}, options),
+        activate: (options = {}) => client.request('relays_enroll', {}, options),
+    };
+}

package/dist/runner-grant.d.ts

@@ -0,0 +1,10 @@
+import { GenesisError } from './errors.js';
+import type { components } from './generated/schema.js';
+export type RunnerSelfExecutionGrantInput = components['schemas']['Iam.RunnerSelfExecutionGrantRequest'];
+export type RunnerSelfExecutionGrant = components['schemas']['Iam.RunnerSelfExecutionGrant'];
+export declare const RUNNER_SELF_GRANT_OPERATION: "iam_runnerSelfExecutionGrant";
+/** Copy only primitive data descriptors before any asynchronous credential call. */
+export declare function snapshotRunnerSelfGrant(args: Record<string, unknown>, routing: string): RunnerSelfExecutionGrantInput;
+export declare function runnerGrantTransportError(): GenesisError;
+/** A bounded closed response; no arbitrary upstream body reaches CLI or MCP. */
+export declare function runnerGrantResponse(res: Response, input: RunnerSelfExecutionGrantInput): Promise<Response>;

package/dist/runner-grant.js

@@ -0,0 +1,133 @@
+import { GenesisError } from './errors.js';
+export const RUNNER_SELF_GRANT_OPERATION = 'iam_runnerSelfExecutionGrant';
+const requestKeys = ['schemaVersion', 'requestId', 'operationId', 'organizationId', 'projectId', 'platformId', 'workspaceId', 'fleetId', 'resourceEnvironment', 'expiresAtMs'];
+const receiptKeys = ['id', 'principal_id', 'organization_id', 'project_id', 'platform_id', 'workspace_id', 'environmentId', 'role_ids', 'permissions', 'expires_at', 'created_at'];
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const match = (p, v) => typeof v === 'string' && p.exec(v)?.[0] === v;
+const native = (v, prefix) => match(new RegExp('^' + prefix + '[A-Za-z0-9_]{1,32}$'), v);
+const instant = (v) => typeof v === 'number' && Number.isSafeInteger(v) && v > 0;
+function exact(v, keys) {
+    return !!v && typeof v === 'object' && !Array.isArray(v) && Object.keys(v).length === keys.length && keys.every(k => Object.hasOwn(v, k));
+}
+const invalid = () => new TypeError('Runner self-execution permission requires the exact ordinary-human Sandbox selection, operation, request correlation and finite expiry');
+/** Copy only primitive data descriptors before any asynchronous credential call. */
+export function snapshotRunnerSelfGrant(args, routing) {
+    if (routing !== 'gateway' || !exact(args, ['body']) || Reflect.ownKeys(args).length !== 1)
+        throw invalid();
+    const descriptor = Object.getOwnPropertyDescriptor(args, 'body');
+    if (!descriptor || !('value' in descriptor))
+        throw invalid();
+    const body = descriptor.value;
+    if (!exact(body, requestKeys) || ![Object.prototype, null].includes(Object.getPrototypeOf(body)) || Reflect.ownKeys(body).length !== requestKeys.length)
+        throw invalid();
+    const copy = {};
+    for (const key of requestKeys) {
+        const d = Object.getOwnPropertyDescriptor(body, key);
+        if (!d || !('value' in d) || !d.enumerable || (d.value !== null && !['string', 'number'].includes(typeof d.value)))
+            throw invalid();
+        copy[key] = d.value;
+    }
+    const now = Date.now();
+    if (copy.schemaVersion !== 1 || !match(uuid, copy.requestId) || !match(uuid, copy.operationId)
+        || !native(copy.organizationId, 'o_') || !native(copy.projectId, 'pr_') || !native(copy.workspaceId, 'w_')
+        || copy.platformId !== 'pf_console' || copy.fleetId !== null || copy.resourceEnvironment !== 'sandbox'
+        || !instant(copy.expiresAtMs) || copy.expiresAtMs <= now || copy.expiresAtMs > now + 1_800_000)
+        throw invalid();
+    return Object.freeze(copy);
+}
+function closedJson(raw) {
+    const value = JSON.parse(raw);
+    const stack = [];
+    for (const token of raw.match(/"(?:\\.|[^"\\])*"|[{}\[\],:]|true|false|null|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/g) ?? []) {
+        const frame = stack.at(-1);
+        if (token === '{' || token === '[')
+            stack.push({ object: token === '{', key: token === '{', keys: new Set() });
+        else if (token === '}' || token === ']')
+            stack.pop();
+        else if (token === ',' && frame?.object)
+            frame.key = true;
+        else if (token === ':' && frame?.object)
+            frame.key = false;
+        else if (token.startsWith('"') && frame?.object && frame.key) {
+            const key = JSON.parse(token);
+            if (frame.keys.has(key))
+                throw invalid();
+            frame.keys.add(key);
+        }
+        else if (/^-?\d/.test(token) && !/^-?(?:0|[1-9]\d*)$/.test(token))
+            throw invalid();
+    }
+    return value;
+}
+const errorRows = [
+    [400, 'INVALID_ARGUMENT', 'invalid Runner self-execution grant request', 'invalid_runner_self_execution_grant_request'],
+    [400, 'INVALID_ARGUMENT', 'Runner self-execution grant expiry is out of bounds', 'runner_self_execution_grant_expiry_out_of_bounds'],
+    [401, 'UNAUTHENTICATED', 'Runner self-execution authority inactive', 'runner_self_execution_grant_inactive'],
+    [403, 'PERMISSION_DENIED', 'Runner self-execution authority denied', 'runner_self_execution_grant_denied'],
+    [409, 'CONFLICT', 'Runner self-execution grant operation conflict', 'runner_self_execution_grant_conflict'],
+    [409, 'CONFLICT', 'Runner self-execution grant replay is stale', 'runner_self_execution_grant_replay_stale'],
+    [503, 'PROVIDER_UNAVAILABLE', 'Runner self-execution grant unavailable', 'runner_self_execution_grant_unavailable'],
+];
+function uncertain(status, message) {
+    return new GenesisError({ status, type: 'runner_grant_uncertain', operationId: RUNNER_SELF_GRANT_OPERATION, message });
+}
+export function runnerGrantTransportError() {
+    return uncertain(0, 'Runner permission response was lost. Retry the same operation, scope and expiry with fresh request correlation.');
+}
+/** A bounded closed response; no arbitrary upstream body reaches CLI or MCP. */
+export async function runnerGrantResponse(res, input) {
+    let value;
+    try {
+        if (res.redirected || res.headers.get('content-type')?.split(';')[0].trim().toLowerCase() !== 'application/json')
+            throw invalid();
+        const reader = res.body?.getReader();
+        const chunks = [];
+        let size = 0;
+        if (reader) {
+            try {
+                while (true) {
+                    const next = await reader.read();
+                    if (next.done)
+                        break;
+                    size += next.value.byteLength;
+                    if (size > 8192) {
+                        await reader.cancel();
+                        throw invalid();
+                    }
+                    chunks.push(next.value);
+                }
+            }
+            finally {
+                reader.releaseLock();
+            }
+        }
+        const bytes = new Uint8Array(size);
+        let offset = 0;
+        for (const chunk of chunks) {
+            bytes.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        value = closedJson(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+    }
+    catch {
+        throw uncertain(res.status, 'Runner permission could not be confirmed. Retry the same operation, scope and expiry with fresh request correlation.');
+    }
+    if (res.status !== 200) {
+        if (exact(value, ['code', 'message', 'details']) && exact(value.details, ['schemaVersion', 'reason']) && value.details.schemaVersion === 1) {
+            const details = value.details;
+            const row = errorRows.find(r => r[0] === res.status && r[1] === value.code && r[2] === value.message && r[3] === details.reason);
+            if (row)
+                throw new GenesisError({ status: res.status, type: 'runner_grant_denied', code: row[1], operationId: RUNNER_SELF_GRANT_OPERATION, message: row[2], body: value });
+        }
+        throw uncertain(res.status, 'Runner permission is unavailable or unconfirmed. Retry the same operation, scope and expiry with fresh request correlation.');
+    }
+    if (!exact(value, receiptKeys) || !match(/^g_[0-7][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{25}$/, value.id)
+        || !native(value.principal_id, 'h_') || value.organization_id !== input.organizationId || value.project_id !== input.projectId
+        || value.platform_id !== input.platformId || value.workspace_id !== input.workspaceId || value.environmentId !== input.resourceEnvironment
+        || !Array.isArray(value.role_ids) || value.role_ids.length !== 0 || !Array.isArray(value.permissions)
+        || value.permissions.length !== 1 || value.permissions[0] !== 'runner.tasks.execute'
+        || value.expires_at !== input.expiresAtMs || input.expiresAtMs <= Date.now() || !instant(value.created_at) || value.created_at >= input.expiresAtMs) {
+        throw uncertain(502, 'Runner returned an unqualified permission receipt. Retry the same operation, scope and expiry to reconcile it.');
+    }
+    return Response.json(value, { status: 200, headers: { 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff' } });
+}

package/dist/runner.d.ts

@@ -0,0 +1,68 @@
+import type { GenesisClient } from './client.js';
+import type { components } from './generated/schema.js';
+import { type RunnerSelfExecutionGrantInput } from './runner-grant.js';
+type Schemas = components['schemas'];
+export type RunnerStartInput = Schemas['Runner.StartInput'];
+export type RunnerSnapshot = Schemas['Runner.Snapshot'];
+export type RunnerCatalog = Schemas['Runner.Catalog'];
+export type RunnerEvent = Schemas['Runner.Event'];
+export type RunnerProviderResult = Schemas['Runner.ProviderResult'];
+export type RunnerRequestOptions = {
+    signal?: AbortSignal;
+};
+/** Runner routes use the Genesis client's credential; the backend owns org/subject scoping. */
+export declare function runnerModule(client: GenesisClient): Readonly<{
+    permission: Readonly<{
+        grant: (input: RunnerSelfExecutionGrantInput, opts?: RunnerRequestOptions) => Promise<{
+            id: string;
+            principal_id: string;
+            organization_id: string;
+            project_id: string;
+            platform_id: "pf_console";
+            workspace_id: string;
+            environmentId: "sandbox";
+            role_ids: unknown[];
+            permissions: "runner.tasks.execute"[];
+            expires_at: number;
+            created_at: number;
+        }>;
+    }>;
+    catalog: (opts?: RunnerRequestOptions) => Promise<{
+        workspaces: {
+            key: components["schemas"]["Runner.SafeOpaqueRef"];
+            label: string;
+        }[];
+        routes: {
+            routeId: components["schemas"]["Runner.SafeOpaqueRef"];
+            kind: "external-harness" | "internal-model";
+            name: string;
+            via: string;
+            state: "synthetic" | "bound" | "unbound";
+            default: boolean;
+        }[];
+    }>;
+    jobs: Readonly<{
+        list: (opts?: RunnerRequestOptions) => Promise<{
+            jobs: components["schemas"]["Runner.Snapshot"][];
+        }>;
+        start: (input: RunnerStartInput, opts?: RunnerRequestOptions) => Promise<{
+            jobId: components["schemas"]["Runner.SafeOpaqueRef"];
+            snapshot: components["schemas"]["Runner.Snapshot"];
+        }>;
+        get: (jobId: string, opts?: RunnerRequestOptions) => Promise<{
+            snapshot: components["schemas"]["Runner.Snapshot"];
+        }>;
+        events: (jobId: string, afterSeq?: number, opts?: RunnerRequestOptions) => Promise<{
+            events: components["schemas"]["Runner.Event"][];
+            nextAfterSeq: number;
+            hasMore: boolean;
+        }>;
+        result: (jobId: string, opts?: RunnerRequestOptions) => Promise<{
+            result: components["schemas"]["Runner.ProviderResult"];
+        }>;
+        cancel: (jobId: string, opts?: RunnerRequestOptions) => Promise<{
+            snapshot: components["schemas"]["Runner.Snapshot"];
+        }>;
+    }>;
+}>;
+export {};