@volter/world-core 3.0.37 → 3.0.39

package/dist/src/managed-database.js

@@ -43,39 +43,6 @@ export class EngineDatabaseError extends Error {
 export class EngineUnavailableError extends Error {
     constructor(message) { super(message); this.name = 'EngineUnavailableError'; }
 }
-/** The transaction-local setting every batch a handler makes carries: the World clock at the call (ctx.occurredAt). */
-export const WORLD_CLOCK_SETTING = 'volter.world_clock';
-/** The World clock inside the database, for the schemas a vendor lays (its migrations stamp rows with Postgres's
- *  `now()`, which reads the wall clock): `volter.now()`, the World clock the batch set or the wall clock where none is
- *  set, and every column default in `schemas` that reads `now()` or `CURRENT_TIMESTAMP` (alone or inside an expression,
- *  GoTrue's `timezone('utc', now())`) rewritten to read it. Run after the schemas are laid; running it again changes
- *  nothing. A trigger or function that calls `now()` itself is the pack's to redefine. */
-export function worldClockSql(schemas) {
-    const list = schemas.map((s) => `'${s.replace(/'/g, "''")}'`).join(', ');
-    return `CREATE SCHEMA IF NOT EXISTS volter;
-CREATE OR REPLACE FUNCTION volter.now() RETURNS timestamptz LANGUAGE sql STABLE AS $fn$
-  SELECT coalesce(nullif(current_setting('${WORLD_CLOCK_SETTING}', true), '')::timestamptz, pg_catalog.now())
-$fn$;
-GRANT USAGE ON SCHEMA volter TO PUBLIC;
-GRANT EXECUTE ON FUNCTION volter.now() TO PUBLIC;
-DO $do$
-DECLARE d record; rewritten text;
-BEGIN
-  FOR d IN
-    SELECT n.nspname AS schema, c.relname AS tbl, a.attname AS col, pg_get_expr(ad.adbin, ad.adrelid) AS expr
-    FROM pg_attrdef ad
-    JOIN pg_class c ON c.oid = ad.adrelid
-    JOIN pg_namespace n ON n.oid = c.relnamespace
-    JOIN pg_attribute a ON a.attrelid = ad.adrelid AND a.attnum = ad.adnum
-    WHERE n.nspname IN (${list}) AND c.relkind IN ('r', 'p')
-      AND pg_get_expr(ad.adbin, ad.adrelid) ~* '(^|[^.[:alnum:]_])(now\\(\\)|current_timestamp)'
-  LOOP
-    rewritten := regexp_replace(d.expr, '(^|[^.[:alnum:]_])(now\\(\\)|current_timestamp)', '\\1volter.now()', 'gi');
-    EXECUTE format('ALTER TABLE %I.%I ALTER COLUMN %I SET DEFAULT %s', d.schema, d.tbl, d.col, rewritten);
-  END LOOP;
-END
-$do$;`;
-}
 /** Quote an identifier the way Postgres's quote_ident does for a name that needs it. */
 export function quoteIdent(name) {
     return `"${name.replace(/"/g, '""')}"`;
@@ -228,14 +195,13 @@ function settingsStatement(settings) {
     return { text: `SELECT ${calls.join(', ')}`, values };
 }
 /** The World's Postgres at `url` (the runtime's binding, never the environment); with `readOnly`, every transaction is
- *  READ ONLY whatever the batch asks (a read-only twin or request: Postgres itself refuses a write, 25006); with `clock`,
- *  every batch carries the World clock as `volter.world_clock`. */
+ *  READ ONLY whatever the batch asks (a read-only twin or request: Postgres itself refuses a write, 25006). */
 export function managedDatabase(url, options = {}) {
     return {
         bound: true,
+        url,
         async batch(batch) {
-            // the World clock at the call, which volter.now() and the defaults worldClockSql rewrote read
-            const set = settingsStatement({ ...(options.clock !== undefined ? { [WORLD_CLOCK_SETTING]: options.clock } : {}), ...(batch.settings ?? {}) });
+            const set = settingsStatement(batch.settings ?? {});
             const head = [
                 { text: batch.readOnly || options.readOnly ? 'BEGIN READ ONLY' : 'BEGIN' },
                 ...(batch.role === undefined ? [] : [{ text: `SET LOCAL ROLE ${quoteIdent(batch.role)}` }]),
@@ -268,6 +234,41 @@ export function managedDatabase(url, options = {}) {
         },
     };
 }
+/** The World's Postgres at `url` as one connection held until `end()`. */
+export async function databaseSession(url) {
+    const { Pool } = await loadDriver();
+    const pool = new Pool({ connectionString: url, max: 1, idleTimeoutMillis: 0, connectionTimeoutMillis: 10_000 });
+    pool.on('error', () => { });
+    let client;
+    try {
+        client = await pool.connect();
+    }
+    catch (error) {
+        await pool.end().catch(() => { });
+        throw new EngineUnavailableError(`the World's Postgres is not answering: ${error.message}`);
+    }
+    // every value as the wire carries it: a row an array of texts, no type parsed
+    const raw = { getTypeParser: () => (value) => value };
+    return {
+        async query(text, values) {
+            try {
+                const answer = (await client.query({ text, ...(values === undefined ? {} : { values }), rowMode: 'array', types: raw }));
+                return (Array.isArray(answer) ? answer : [answer]).map((r) => ({
+                    fields: (r.fields ?? []).map((f) => f.name),
+                    rows: r.rows ?? [],
+                    command: [r.command ?? '', r.command === 'INSERT' ? '0' : '', r.rowCount ?? ''].filter((part) => part !== '').join(' '),
+                }));
+            }
+            catch (error) {
+                throw asDatabaseError(error);
+            }
+        },
+        async end() {
+            client.release();
+            await pool.end().catch(() => { });
+        },
+    };
+}
 /** A handler's database when the World binds none: every use is the refusal naming what to add. */
 export function unboundDatabase(service) {
     const refuse = () => {

package/dist/src/multipart.d.ts

@@ -1,11 +1,29 @@
-/** One part: its field name (possibly empty), its filename when it is a file, its media type as sent, its bytes. */
 export type MultipartPart = {
     name: string;
     filename: string | null;
     type: string | null;
     body: Uint8Array;
 };
-/** The boundary a `multipart/form-data` content type names, or null (not multipart, or no boundary). */
+export type MultipartFramedPart = MultipartPart & {
+    headers: Uint8Array;
+    leading: Uint8Array;
+    separator: Uint8Array;
+    trailing: Uint8Array;
+};
+export type MultipartEnvelope = {
+    complete: boolean;
+    preamble: Uint8Array;
+    epilogue: Uint8Array;
+    delimiters: Uint8Array[];
+    parts: MultipartFramedPart[];
+};
+/** The boundary named by any multipart media type. */
 export declare function multipartBoundary(contentType: string | null | undefined): string | null;
-/** The parts of a body delimited by `boundary`, in order; a malformed tail ends the reading. */
+/** Used both by the byte reader and by consumers guarding placeholder spans within a part. */
+export declare function multipartDelimiterPattern(boundary: string): string;
+/** Infer only a boundary with a corresponding closing line; Content-Type remains authoritative when supplied. */
+export declare function inferMultipartBoundary(bytes: Uint8Array): string | null;
+/** Raw MIME framing and interpreted parts. A malformed tail ends reading and leaves `complete` false. */
+export declare function multipartEnvelope(bytes: Uint8Array, boundary: string): MultipartEnvelope;
+/** The request's parts, in order, using the same framing reader as wire comparison. */
 export declare function multipartParts(bytes: Uint8Array, boundary: string): MultipartPart[];

package/dist/src/multipart.js

@@ -1,51 +1,125 @@
-// A multipart/form-data body's parts, read from its bytes (RFC 7578): the one reading every pack's uploads go through.
-// A runtime's own form parser is not used: Bun's drops a part whose field name is empty, which a browser's or
-// supabase-js's Blob upload sends. Dependency-free and side-effect free (a browser bundle imports it).
-/** The boundary a `multipart/form-data` content type names, or null (not multipart, or no boundary). */
+// The one MIME multipart reader for requests and published examples. Dependency-free, side-effect-free and
+// byte-preserving: a browser bundle imports it, and empty field names and binary uploads must survive reading.
+/** The boundary named by any multipart media type. */
 export function multipartBoundary(contentType) {
-    if (!contentType || !/^multipart\/form-data/i.test(contentType))
+    if (!contentType || !/^multipart\//i.test(contentType))
         return null;
-    const hit = /boundary=(?:"([^"]+)"|([^;\s]+))/i.exec(contentType);
+    const hit = /\bboundary\s*=\s*(?:"([^"]+)"|([^;\s]+))/i.exec(contentType);
     return hit ? (hit[1] ?? hit[2]) : null;
 }
-function indexOf(haystack, needle, from) {
-    outer: for (let i = from; i <= haystack.length - needle.length; i += 1) {
-        for (let j = 0; j < needle.length; j += 1)
-            if (haystack[i + j] !== needle[j])
-                continue outer;
-        return i;
+function byteLines(bytes) {
+    const lines = [];
+    for (let at = 0; at < bytes.length;) {
+        let end = at;
+        while (end < bytes.length && bytes[end] !== 13 && bytes[end] !== 10)
+            end++;
+        const after = end === bytes.length ? end : end + (bytes[end] === 13 && bytes[end + 1] === 10 ? 2 : 1);
+        lines.push({ at, end, after });
+        at = after;
     }
-    return -1;
+    return lines;
 }
-/** The parts of a body delimited by `boundary`, in order; a malformed tail ends the reading. */
-export function multipartParts(bytes, boundary) {
-    const encoder = new TextEncoder();
+/** Used both by the byte reader and by consumers guarding placeholder spans within a part. */
+export function multipartDelimiterPattern(boundary) {
+    const literal = boundary.replace(/[.*+?^$(){}|[\]\\]/g, '\\$&');
+    // Include malformed whitespace-before-close lines in the guard: they cannot be hidden in a value either.
+    return '(?:^|(?<=[\\r\\n]))--' + literal + '(?:--|[ \\t]+--)?[ \\t]*(?=\\r\\n|\\n|\\r|$)';
+}
+/** Infer only a boundary with a corresponding closing line; Content-Type remains authoritative when supplied. */
+export function inferMultipartBoundary(bytes) {
     const decoder = new TextDecoder();
-    const delimiter = encoder.encode(`--${boundary}`);
-    const blank = encoder.encode('\r\n\r\n');
-    const parts = [];
-    let at = indexOf(bytes, delimiter, 0);
-    while (at >= 0) {
-        const start = at + delimiter.length;
-        // `--` after the delimiter closes the body
-        if (bytes[start] === 0x2d && bytes[start + 1] === 0x2d)
-            break;
-        const headerEnd = indexOf(bytes, blank, start);
-        if (headerEnd < 0)
-            break;
-        const next = indexOf(bytes, delimiter, headerEnd + 4);
-        if (next < 0)
+    const lines = byteLines(bytes).map(({ at, end }) => decoder.decode(bytes.subarray(at, end)));
+    for (const line of lines) {
+        if (!line.startsWith('--'))
+            continue;
+        const boundary = line.slice(2).replace(/[ \t]+$/, '');
+        if (boundary && lines.some((closing) => closing.replace(/[ \t]+$/, '') === '--' + boundary + '--'))
+            return boundary;
+    }
+    return null;
+}
+/** Read MIME fields once, unfolding continuations for interpretation while retaining raw bytes in the envelope. */
+function mimeHeaders(raw) {
+    const fields = new Map();
+    let previous;
+    for (const line of new TextDecoder().decode(raw).split(/\r\n|\n|\r/)) {
+        if (!line)
+            continue;
+        if (/^[ \t]/.test(line)) {
+            if (!previous)
+                return undefined;
+            fields.set(previous, fields.get(previous) + ' ' + line.trim());
+        }
+        else {
+            const field = /^([^\s:]+):[ \t]*(.*)$/.exec(line);
+            if (!field)
+                return undefined;
+            previous = field[1].toLowerCase();
+            fields.set(previous, field[2].trim());
+        }
+    }
+    return fields;
+}
+/** Raw MIME framing and interpreted parts. A malformed tail ends reading and leaves `complete` false. */
+export function multipartEnvelope(bytes, boundary) {
+    const empty = new Uint8Array();
+    const result = { complete: false, preamble: bytes.slice(), epilogue: empty, delimiters: [], parts: [] };
+    const lines = byteLines(bytes);
+    const decoder = new TextDecoder();
+    const prefix = '--' + boundary;
+    const hits = [];
+    for (const line of lines) {
+        const text = decoder.decode(bytes.subarray(line.at, line.end));
+        if (!text.startsWith(prefix))
+            continue;
+        const suffix = text.slice(prefix.length);
+        const closing = /^--[ \t]*$/.test(suffix);
+        const valid = closing || /^[ \t]*$/.test(suffix);
+        if (!valid && !/^[ \t]+--[ \t]*$/.test(suffix))
+            continue;
+        hits.push({ ...line, closing, valid });
+        if (closing || !valid)
             break;
-        const head = decoder.decode(bytes.subarray(start, headerEnd));
-        const disposition = /content-disposition:[^\r\n]*/i.exec(head)?.[0] ?? '';
-        parts.push({
+    }
+    if (!hits.length)
+        return result;
+    result.preamble = bytes.slice(0, hits[0].at);
+    result.delimiters = hits.map(({ at, end }) => bytes.slice(at, end));
+    for (let i = 0; i < hits.length - 1; i++) {
+        const current = hits[i];
+        const next = hits[i + 1];
+        if (!current.valid || current.closing || current.after === current.end || !next.valid)
+            return result;
+        const headerLines = lines.filter((line) => line.at >= current.after && line.at < next.at);
+        const blank = headerLines.find((line) => line.at === line.end);
+        if (!blank)
+            return result;
+        const previous = headerLines.find((line) => line.after === blank.at);
+        const headersEnd = previous?.end ?? blank.at;
+        const headers = bytes.slice(current.after, headersEnd);
+        const fields = mimeHeaders(headers);
+        if (!fields)
+            return result;
+        const beforeNext = lines.find((line) => line.after === next.at);
+        // The line break immediately before a delimiter belongs to framing, never to the uploaded bytes.
+        const bodyEnd = Math.max(blank.after, beforeNext?.end ?? next.at);
+        const disposition = fields.get('content-disposition') ?? '';
+        result.parts.push({
             name: /\bname="([^"]*)"/i.exec(disposition)?.[1] ?? '',
             filename: /\bfilename="([^"]*)"/i.exec(disposition)?.[1] ?? null,
-            type: /content-type:\s*([^\r\n]+)/i.exec(head)?.[1]?.trim() ?? null,
-            // the CRLF before the next delimiter is the delimiter's, not the part's
-            body: bytes.slice(headerEnd + 4, next - 2),
+            type: fields.get('content-type')?.trim() ?? null,
+            body: bytes.slice(blank.after, bodyEnd), headers,
+            leading: bytes.slice(current.end, current.after), separator: bytes.slice(headersEnd, blank.after),
+            trailing: bytes.slice(bodyEnd, next.at),
         });
-        at = next;
     }
-    return parts;
+    const last = hits.at(-1);
+    result.complete = last.valid && last.closing;
+    if (result.complete)
+        result.epilogue = bytes.slice(last.end);
+    return result;
+}
+/** The request's parts, in order, using the same framing reader as wire comparison. */
+export function multipartParts(bytes, boundary) {
+    return multipartEnvelope(bytes, boundary).parts.map(({ name, filename, type, body }) => ({ name, filename, type, body }));
 }

package/dist/src/observe.d.ts

@@ -35,6 +35,9 @@ export type Completed = string | {
     type: string;
     field: string;
     within: string[];
+} | {
+    type: string;
+    ids: string[];
 };
 /** Fold a collected batch: one `observeResources` per service, `complete` applied to each. */
 export declare function foldObservations(observations: Observation[], opts?: {

package/dist/src/observe.js

@@ -147,11 +147,15 @@ function foldResources(service, resources, opts) {
         }
         for (const c of opts.complete ?? []) {
             const type = typeof c === 'string' ? c : c.type;
-            const within = typeof c === 'string' ? undefined : new Set(c.within);
+            const within = typeof c === 'string' || !('within' in c) ? undefined : new Set(c.within);
+            // subjects read one by one (a refresh of the known): only those read are whole, an unseen one is gone
+            const ids = typeof c !== 'string' && 'ids' in c ? new Set(c.ids) : undefined;
             for (const s of tree.values()) {
                 if (s.type !== type || seen.has(`${s.type}:${s.id}`) || s.fields.deleted === true)
                     continue;
-                if (within && typeof c !== 'string' && !within.has(String(s.fields[c.field])))
+                if (within && typeof c !== 'string' && 'field' in c && !within.has(String(s.fields[c.field])))
+                    continue;
+                if (ids && !ids.has(s.id))
                     continue;
                 if (append({ type: s.type, id: s.id }, { deleted: true }))
                     report.removed += 1;

package/dist/src/openai-wire.d.ts

@@ -9,6 +9,7 @@ export type WireTurn = {
         arguments: Row;
     }>;
     reasoning?: string | null;
+    reasoningDetails?: Row[];
     finishReason?: string;
 };
 /** Tokens, estimated at about four characters a token: a twin's count, not a tokenizer's. */
@@ -51,6 +52,7 @@ export declare function chatCompletion(s: ChatShape): Row;
  *  vendor sends first (OpenRouter's `: OPENROUTER PROCESSING`). */
 export declare function chatCompletionSSE(s: ChatShape & {
     comment?: string;
+    separateUsageChunk?: boolean;
 }): string;
 /** A V4 call's options as the chat completions request they mean: its prompt as messages, its tools, tool choice,
  *  response format and output limit; so the chat stub and the wire's scenario read it. */
@@ -79,6 +81,8 @@ export type ResponsesShape = {
     /** ids for the output items: the message, the reasoning, each function call and its call id */
     itemId: (kind: 'msg' | 'rs' | 'fc' | 'call', i: number) => string;
     extra?: Row;
+    /** Vendor defaults; explicit request values win, including nullable gateway defaults. */
+    defaults?: Row;
 };
 /** A Responses object (`object: response`, `status: completed`): its output items (the reasoning when there is some,
  *  the message with its output text, or function calls) and its usage. */
@@ -105,4 +109,16 @@ export declare function wireRequest(body: Row): WireRequest;
  *  operation whose request is another wire's (a gateway's Anthropic Messages surface: anthropicWire's
  *  `messagesWireRequest`), so one scenario scripts every surface's turns alike. */
 export declare function scenario(vendor: string, operations: string[], faultBody: (status: number, message: string | undefined) => unknown, readers?: Record<string, (body: Row) => WireRequest>): PackScenario<WireRequest>;
+/** An admitted generation that fails: partial JSON or actual Chat Completions error frames.
+ * The pack supplies its error envelope/type; the shared wire owns the SDK framing. */
+export declare function chatCompletionFailure(s: {
+    id: string;
+    model: string;
+    created: number;
+    error: Row;
+    text?: string;
+    extra?: Row;
+}, stream: boolean): Row | string;
+/** Responses generation failures keep the response's canonical fields and native error code. */
+export declare function responsesFailure(response: Row, stream: boolean, event?: string): Row | string;
 export {};

package/dist/src/openai-wire.js

@@ -58,7 +58,7 @@ function chatParts(s) {
 export function chatCompletion(s) {
     const p = chatParts(s);
     const field = s.reasoningField ?? 'reasoning';
-    const message = { role: 'assistant', content: p.text, refusal: null, ...(p.reasoning ? { [field]: p.reasoning } : {}), ...(p.calls.length ? { tool_calls: p.calls } : {}) };
+    const message = { role: 'assistant', content: p.text, refusal: null, ...(p.reasoning ? { [field]: p.reasoning } : {}), ...(s.turn.reasoningDetails ? { reasoning_details: s.turn.reasoningDetails } : {}), ...(p.calls.length ? { tool_calls: p.calls } : {}) };
     return {
         id: s.id, ...(s.extra ?? {}), model: s.model, object: 'chat.completion', created: s.created,
         choices: [{ index: 0, message, logprobs: null, finish_reason: p.finish, ...(s.nativeFinish ? { native_finish_reason: p.finish } : {}) }], usage: p.usage,
@@ -70,18 +70,19 @@ export function chatCompletion(s) {
 export function chatCompletionSSE(s) {
     const p = chatParts(s);
     const field = s.reasoningField ?? 'reasoning';
-    const chunk = (delta, last) => `data: ${JSON.stringify({
+    const chunk = (delta, last, usage = last) => `data: ${JSON.stringify({
         id: s.id, ...((last ? s.extra : s.interimExtra ?? s.extra) ?? {}), model: s.model, object: 'chat.completion.chunk', created: s.created,
         choices: [{ index: 0, delta, logprobs: null, finish_reason: last ? p.finish : null, ...(s.nativeFinish ? { native_finish_reason: last ? p.finish : null } : {}) }],
-        ...(last ? { usage: p.usage } : {}),
+        ...(usage ? { usage: p.usage } : {}),
     })}\n\n`;
     const half = p.text ? Math.ceil(p.text.length / 2) : 0;
     return [
         ...(s.comment ? [`: ${s.comment}\n\n`] : []),
-        ...(p.reasoning ? [chunk({ role: 'assistant', content: '', [field]: p.reasoning }, false)] : []),
+        ...(p.reasoning || s.turn.reasoningDetails ? [chunk({ role: 'assistant', content: '', ...(p.reasoning ? { [field]: p.reasoning } : {}), ...(s.turn.reasoningDetails ? { reasoning_details: s.turn.reasoningDetails } : {}) }, false)] : []),
         ...(p.text ? [chunk({ role: 'assistant', content: p.text.slice(0, half) }, false), ...(p.text.length > half ? [chunk({ content: p.text.slice(half) }, false)] : [])] : []),
         ...(p.calls.length ? [chunk({ role: 'assistant', content: null, tool_calls: p.calls.map((c, i) => ({ index: i, ...c })) }, false)] : []),
-        chunk({}, true),
+        chunk(s.separateUsageChunk ? { role: 'assistant', content: '' } : {}, true, !s.separateUsageChunk),
+        ...(s.separateUsageChunk ? [chunk({ role: 'assistant', content: '' }, true, true)] : []),
         'data: [DONE]\n\n',
     ].join('');
 }
@@ -195,6 +196,7 @@ export function responsesStubTurn(body, label) {
  *  the message with its output text, or function calls) and its usage. */
 export function responsesAnswer(s) {
     const b = s.body;
+    const defaultOf = (field, fallback) => s.defaults && Object.hasOwn(s.defaults, field) ? s.defaults[field] : fallback;
     let text = s.turn.text ?? null;
     const max = typeof b.max_output_tokens === 'number' ? b.max_output_tokens : undefined;
     let incomplete = null;
@@ -214,10 +216,10 @@ export function responsesAnswer(s) {
         id: s.id, object: 'response', created_at: s.createdAt, status: incomplete ? 'incomplete' : 'completed', ...(s.extra ?? {}),
         error: null, incomplete_details: incomplete, instructions: b.instructions ?? null, max_output_tokens: max ?? null, model: s.model, output,
         parallel_tool_calls: b.parallel_tool_calls ?? true, previous_response_id: b.previous_response_id ?? null,
-        reasoning: { effort: obj(b.reasoning).effort ?? null, summary: obj(b.reasoning).summary ?? null }, store: b.store ?? true,
-        temperature: b.temperature ?? 1, text: b.text ?? { format: { type: 'text' } }, tool_choice: b.tool_choice ?? 'auto', tools: b.tools ?? [], top_p: b.top_p ?? 1,
+        reasoning: { effort: obj(b.reasoning).effort ?? null, summary: obj(b.reasoning).summary ?? null }, store: b.store ?? defaultOf('store', true),
+        temperature: b.temperature ?? defaultOf('temperature', 1), text: b.text ?? { format: { type: 'text' } }, tool_choice: b.tool_choice ?? 'auto', tools: b.tools ?? [], top_p: b.top_p ?? defaultOf('top_p', 1),
         usage: { input_tokens: input, input_tokens_details: { cached_tokens: 0 }, output_tokens: out + reasoningTokens, output_tokens_details: { reasoning_tokens: reasoningTokens }, total_tokens: input + out + reasoningTokens },
-        metadata: b.metadata ?? {},
+        metadata: b.metadata ?? defaultOf('metadata', {}),
     };
 }
 /** A Responses object streamed: the events the wire sends (`response.created`, `response.in_progress`, each output
@@ -243,7 +245,14 @@ export function responsesSSE(s) {
             events.push({ type: 'response.function_call_arguments.done', item_id: item.id, output_index: i, arguments: item.arguments });
         }
         else {
-            events.push({ type: 'response.output_item.added', output_index: i, item });
+            // announced empty, as a message item is: an SDK's accumulator appends each summary part the events below add
+            events.push({ type: 'response.output_item.added', output_index: i, item: { ...item, summary: [], status: 'in_progress' } });
+            for (const [n, summary] of arr(item.summary).entries()) {
+                events.push({ type: 'response.reasoning_summary_part.added', item_id: item.id, output_index: i, summary_index: n, part: { type: 'summary_text', text: '' } });
+                events.push({ type: 'response.reasoning_summary_text.delta', item_id: item.id, output_index: i, summary_index: n, delta: summary.text });
+                events.push({ type: 'response.reasoning_summary_text.done', item_id: item.id, output_index: i, summary_index: n, text: summary.text });
+                events.push({ type: 'response.reasoning_summary_part.done', item_id: item.id, output_index: i, summary_index: n, part: summary });
+            }
         }
         events.push({ type: 'response.output_item.done', output_index: i, item });
     }
@@ -254,18 +263,19 @@ export function responsesSSE(s) {
 export const forbidsTools = (choice) => choice === 'none' || obj(choice).type === 'none';
 /** The turn a scenario's decision scripts (`respond`: text, toolCalls, reasoning, finishReason), or undefined. */
 export function scenarioTurn(decision) {
-    if (!decision || decision.kind !== 'handler')
+    if (!decision || decision.kind !== 'handler' || decision.fault?.kind === 'generation')
         return undefined;
     const r = obj(decision.respond);
     return {
         ...(typeof r.text === 'string' ? { text: r.text } : {}),
         ...(r.toolCalls !== undefined ? { toolCalls: (Array.isArray(r.toolCalls) ? r.toolCalls : [r.toolCalls]) } : {}),
         ...(typeof r.reasoning === 'string' ? { reasoning: r.reasoning } : {}),
+        ...(Array.isArray(r.reasoningDetails) ? { reasoningDetails: r.reasoningDetails } : {}),
         ...(typeof r.finishReason === 'string' ? { finishReason: r.finishReason } : {}),
     };
 }
 const nonEmpty = (v) => typeof v === 'string' && v.length > 0;
-const RESPOND_KEYS = new Set(['text', 'toolCalls', 'reasoning', 'finishReason']);
+const RESPOND_KEYS = new Set(['text', 'toolCalls', 'reasoning', 'reasoningDetails', 'finishReason']);
 /** A request as the scenario reads it: its model, its text, its last user text, the tools it offers and the tool
  *  results it ends with, from a chat completion's messages or a Responses input. */
 export function wireRequest(body) {
@@ -306,13 +316,15 @@ export function scenario(vendor, operations, faultBody, readers = {}) {
         },
         validateRespond: (respond) => {
             if (typeof respond !== 'object' || respond === null || Array.isArray(respond))
-                return 'respond is an object { text?, toolCalls?, reasoning?, finishReason? }';
+                return 'respond is an object { text?, toolCalls?, reasoning?, reasoningDetails?, finishReason? }';
             const r = respond;
             for (const k of Object.keys(r))
                 if (!RESPOND_KEYS.has(k))
                     return `respond: unknown key "${k}" (valid: ${[...RESPOND_KEYS].join(', ')})`;
             if (r.text !== undefined && typeof r.text !== 'string')
                 return 'respond.text is a string';
+            if (r.reasoningDetails !== undefined && (!Array.isArray(r.reasoningDetails) || r.reasoningDetails.some((d) => !d || typeof d !== 'object' || Array.isArray(d))))
+                return 'respond.reasoningDetails is an array of JSON objects';
             if (r.reasoning !== undefined && typeof r.reasoning !== 'string')
                 return 'respond.reasoning is a string';
             for (const c of r.toolCalls === undefined ? [] : Array.isArray(r.toolCalls) ? r.toolCalls : [r.toolCalls]) {
@@ -335,3 +347,22 @@ export function scenario(vendor, operations, faultBody, readers = {}) {
     };
     return { adapter, operations, request };
 }
+/** An admitted generation that fails: partial JSON or actual Chat Completions error frames.
+ * The pack supplies its error envelope/type; the shared wire owns the SDK framing. */
+export function chatCompletionFailure(s, stream) {
+    const common = { id: s.id, model: s.model, created: s.created, ...s.extra };
+    if (!stream)
+        return { ...common, object: 'chat.completion', choices: [{ index: 0, message: { role: 'assistant', content: s.text ?? '' }, finish_reason: 'error', error: s.error }] };
+    const frames = [];
+    if (s.text)
+        frames.push({ ...common, object: 'chat.completion.chunk', choices: [{ index: 0, delta: { role: 'assistant', content: s.text }, finish_reason: null }] });
+    frames.push({ ...common, object: 'chat.completion.chunk', choices: [{ index: 0, delta: { content: '' }, finish_reason: 'error' }], error: s.error });
+    return frames.map((f) => `data: ${JSON.stringify(f)}\n\n`).join('') + 'data: [DONE]\n\n';
+}
+/** Responses generation failures keep the response's canonical fields and native error code. */
+export function responsesFailure(response, stream, event = 'response.failed') {
+    if (!stream)
+        return response;
+    const data = event === 'response.failed' ? { type: event, response } : { type: event, error: response.error };
+    return `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+}

package/dist/src/pack-fetch.d.ts

@@ -1,8 +1,9 @@
 import { type DerivedManifest, type Handler, type HandlerContext, type VendorManifest } from './derived-core.js';
-import { type DerivedFetch, type DerivedOwner, type DerivedSurface, type Workspace, type BoardFrame } from './derived.js';
+import { type DerivedFetch, type DerivedSurface, type BoardFrame } from './derived.js';
 import { type PackScenarioAdapter } from './scenario.js';
 import type { ApplicationStandIn } from './events.js';
 import { type SocketEngine } from './sockets.js';
+import type { WebSocketUpgrade } from './serve-http.js';
 import { type GraphqlPart } from './graphql-wire.js';
 /** What a pack declares and writes, and nothing it assembles itself. */
 export type PackParts = {
@@ -59,6 +60,7 @@ export type LanePart = {
         draws?: (url: string) => boolean;
         /** the hosts the lane's built content screens name: its vendor's router sends `<base>/@<host>/` there */
         contentHosts?: ReadonlyArray<string>;
+        upgrade?: WebSocketUpgrade;
     };
     manifest: {
         doors?: ReadonlyArray<{
@@ -79,9 +81,5 @@ export type PackFetchOptions = {
     /** the application a walk stands in for (a life's `application` answers): this fetch's `ctx.ask` is answered by it */
     application?: ApplicationStandIn;
 };
-/** A pack's HTTP surface, as the kernel serves it from the pack's parts. */
 export declare function createPackFetch(parts: PackParts, options?: PackFetchOptions): DerivedFetch;
-export declare function createVendorFetch(manifest: VendorManifest, lanes: Record<string, LanePart>): ((request: Request) => Promise<Response>) & {
-    owners: () => Record<string, DerivedOwner>;
-    workspaces: () => Workspace[];
-};
+export declare function createVendorFetch(manifest: VendorManifest, lanes: Record<string, LanePart>): DerivedFetch;