@onesi/genesis 0.0.1-stage → 0.2.0

package/dist/minds-agent.js

@@ -0,0 +1,233 @@
+import { envelopeExtrasValid, ENVELOPE_EXTRA_FIELDS, GenesisError } from './errors.js';
+export const mindsAgentOperations = ['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 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}$/;
+const EVENT_TYPES = ['Conversation', 'Command', 'Query', 'Document', 'Error', 'Success', 'Learning', 'Decision', 'Action', 'Context', 'Knowledge'];
+/** Safe metadata from a failed agent-memory call; never contains credentials or proof bytes. */
+export class MindsAgentError extends GenesisError {
+    dpopNonce;
+    constructor(init) {
+        super(init);
+        this.dpopNonce = init.dpopNonce;
+    }
+}
+const row = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const exact = (value, required, optional = []) => required.every(key => Object.hasOwn(value, key))
+    && Object.keys(value).every(key => required.includes(key) || optional.includes(key));
+const bytes = (value) => new TextEncoder().encode(value).length;
+const text = (value, max) => typeof value === 'string' && value.length > 0 && bytes(value) <= max
+    && !/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/.test(value);
+const date = (value) => text(value, 128) && /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d+)?(?:Z|[+-]\d\d:\d\d)$/.test(value) && Number.isFinite(Date.parse(value));
+const eventType = (value) => typeof value === 'string' && EVENT_TYPES.includes(value);
+function validEvent(value) {
+    if (!row(value) || !exact(value, ['id', 'content', 'timestamp'], ['event_type', 'summary', 'tags']))
+        return false;
+    return text(value.id, 36) && UUID4.test(value.id) && text(value.content, 16_000) && !!value.content.trim() && date(value.timestamp)
+        && (value.event_type === undefined || eventType(value.event_type))
+        && (value.summary == null || typeof value.summary === 'string' && bytes(value.summary) <= 2_000)
+        && (value.tags === undefined || Array.isArray(value.tags) && value.tags.length <= 16 && value.tags.every(tag => text(tag, 80)));
+}
+// Stored events have additional normalized metadata. Validate the producer's
+// stable required fields without reducing its returned event to the input DTO.
+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 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: 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 (!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))))
+        throw fail(0, 'invalid_request');
+    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');
+    const headerEntries = Object.entries(options.headers ?? {});
+    if (headerEntries.length > 1 || headerEntries.some(([name, value]) => name.toLowerCase() !== 'dpop' || !text(value, 16_384) || /[^\x21-\x7e]|,/.test(value)))
+        throw fail(0, 'invalid_request');
+    const body = read ? undefined : JSON.stringify(input.body);
+    if (body !== undefined && bytes(body) > 65_536)
+        throw fail(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 = () => { };
+        const cancelled = new Promise((_, reject) => {
+            abort = () => reject(fail(0, 'transport_error'));
+            controller.signal.addEventListener('abort', abort, { once: true });
+        });
+        try {
+            controller.signal.throwIfAborted();
+            let pending;
+            try {
+                pending = work();
+            }
+            catch (error) {
+                pending = Promise.reject(error);
+            }
+            return await Promise.race([cancelled, pending]);
+        }
+        finally {
+            controller.signal.removeEventListener('abort', abort);
+        }
+    }
+    try {
+        const credential = await bounded(options.credential);
+        controller.signal.throwIfAborted();
+        if (!text(credential, 16_384) || /[^\x21-\x7e]|,/.test(credential))
+            throw fail(401, 'unauthenticated');
+        const response = await bounded(() => {
+            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] } : {}), ...(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');
+                }
+                return response;
+            });
+        });
+        const reader = response.body?.getReader();
+        if (!reader)
+            throw fail(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 fail(response.status, 'invalid_response');
+                chunks.push(next.value);
+            }
+        }
+        finally {
+            controller.signal.removeEventListener('abort', stop);
+            stop();
+            try {
+                reader.releaseLock();
+            }
+            catch { /* cancellation owns pending read */ }
+        }
+        const data = new Uint8Array(size);
+        let offset = 0;
+        for (const chunk of chunks) {
+            data.set(chunk, offset);
+            offset += chunk.length;
+        }
+        let value;
+        try {
+            value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(data));
+        }
+        catch {
+            throw fail(response.status, 'invalid_response');
+        }
+        if (!response.ok) {
+            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') {
+                // 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)))
+            throw fail(response.status, 'invalid_response');
+        return Response.json(value, { status: 200, headers: { 'cache-control': 'private, no-store' } });
+    }
+    catch (error) {
+        if (error instanceof MindsAgentError)
+            throw error;
+        throw fail(0, 'transport_error');
+    }
+    finally {
+        clearTimeout(timer);
+        controller.abort();
+        options.signal?.removeEventListener('abort', cancel);
+    }
+}
+export function mindsAgentModule(client) {
+    const validOptions = (value) => row(value) && exact(value, [], ['group', 'dpopProof', 'signal']);
+    const init = (options) => {
+        if (!validOptions(options))
+            throw new MindsAgentError({ status: 0, type: 'invalid_request', message: 'Unknown agent memory option.' });
+        return { signal: options.signal, ...(options.dpopProof === undefined ? {} : { headers: { dpop: options.dpopProof } }) };
+    };
+    const query = (mind, options) => ({ mind, ...(options.group === undefined ? {} : { group: options.group }) });
+    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)),
+        }
+    };
+}