narraeon 0.7.10 → 0.8.0

package/dist/node/runtime/model/GoogleHopJournal.js

@@ -0,0 +1,90 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, readdir, rename, rm, writeFile, } from "node:fs/promises";
+import { join } from "node:path";
+import { isSafeGoogleHop, withGoogleHop } from "./GoogleRequestPreview.js";
+const pendingWrites = new Map();
+const pendingSnapshots = new Map();
+function ownerDirectory(root, owner) {
+    return join(root, createHash("sha256").update(owner).digest("hex"));
+}
+/** Each hop has its own file, so unrelated exchanges never overwrite one another. */
+export function writeGoogleHop(root, owner, hop, retained = () => Promise.resolve(true)) {
+    if (!isSafeGoogleHop(hop))
+        throw new Error("Unsafe Google hop evidence");
+    const directory = ownerDirectory(root, owner);
+    const path = join(directory, `${hop.exchange}-${hop.attempt}-${hop.hop}.json`);
+    const snapshot = JSON.stringify(hop);
+    pendingSnapshots.set(path, structuredClone(hop));
+    const previous = pendingWrites.get(path) ?? Promise.resolve();
+    const pending = previous
+        .catch(() => undefined)
+        .then(async () => {
+        if (!(await retained()))
+            return;
+        const temporary = `${path}.${randomUUID()}.tmp`;
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        try {
+            await writeFile(temporary, `${snapshot}\n`, { mode: 0o600 });
+            if (!(await retained()))
+                return;
+            await rename(temporary, path);
+            if (!(await retained()))
+                await rm(root, { recursive: true, force: true });
+        }
+        finally {
+            await rm(temporary, { force: true });
+            if (!(await retained()))
+                await rm(root, { recursive: true, force: true });
+        }
+    });
+    pendingWrites.set(path, pending);
+    void pending
+        .finally(() => {
+        if (pendingWrites.get(path) === pending) {
+            pendingWrites.delete(path);
+            pendingSnapshots.delete(path);
+        }
+    })
+        .catch(() => undefined);
+    return pending;
+}
+/** Corrupt optional evidence is omitted without affecting the underlying request. */
+export async function readGoogleHops(root, owner, wire) {
+    const directory = ownerDirectory(root, owner);
+    const names = await readdir(directory).catch(() => []);
+    let result = wire;
+    for (const name of names
+        .filter((name) => /^[1-9]\d*-[1-9]\d*-[1-9]\d*\.json$/u.test(name))
+        .sort()) {
+        try {
+            const hop = JSON.parse(await readFile(join(directory, name), "utf8"));
+            if (`${hop.exchange}-${hop.attempt}-${hop.hop}.json` !== name)
+                continue;
+            const existing = result.googleHops?.find((item) => item.exchange === hop.exchange &&
+                item.attempt === hop.attempt &&
+                item.hop === hop.hop);
+            if (existing !== undefined && existing.status !== "attempted")
+                continue;
+            result = withGoogleHop(result, hop);
+        }
+        catch {
+            // A single damaged diagnostic cannot prevent the request from loading.
+        }
+    }
+    for (const [path, hop] of pendingSnapshots)
+        if (path.startsWith(`${directory}/`)) {
+            try {
+                const existing = wire.googleHops?.find((item) => item.exchange === hop.exchange &&
+                    item.attempt === hop.attempt &&
+                    item.hop === hop.hop);
+                if (existing === undefined || existing.status === "attempted")
+                    result = withGoogleHop(result, hop);
+            }
+            catch {
+                // Invalid pending evidence is treated like a damaged diagnostic file.
+            }
+        }
+    if (result.googleHops !== undefined)
+        result.googleHops.sort((a, b) => a.exchange - b.exchange || a.attempt - b.attempt || a.hop - b.hop);
+    return result;
+}

package/dist/node/runtime/model/GoogleInteractionsStream.js

@@ -0,0 +1,242 @@
+import { ModelHostOutcomeUnknownError, } from "./ModelHost.js";
+import { providerStreamEvents } from "./ProviderStream.js";
+import { validGoogleInteractionsSteps } from "./ProviderExchangeState.js";
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function invalid() {
+    throw new ModelHostOutcomeUnknownError("Google Interactions stream is incomplete or cannot be preserved losslessly");
+}
+function parseLossless(source) {
+    return JSON.parse(source, (_key, value, context) => {
+        if (typeof value === "number" &&
+            (!Number.isFinite(value) ||
+                (Number.isInteger(value) && !Number.isSafeInteger(value)) ||
+                context?.source !== JSON.stringify(value)))
+            invalid();
+        return value;
+    });
+}
+/** Assemble only documented deltas; unknown shapes fail closed rather than lose native data. */
+export async function aggregateGoogleInteractions(body, onDelta, onUsage) {
+    const steps = new Map();
+    let terminal;
+    let latestUsage;
+    let created = false;
+    let lifecycleValid = true;
+    let sawStep = false;
+    let done = false;
+    for await (const event of providerStreamEvents(body, { fatalUtf8: true })) {
+        if (event.data === "[DONE]") {
+            if (terminal === undefined || done)
+                lifecycleValid = false;
+            done = true;
+            continue;
+        }
+        if (done || terminal !== undefined)
+            lifecycleValid = false;
+        let value;
+        try {
+            value = parseLossless(event.data);
+        }
+        catch {
+            invalid();
+        }
+        if (!record(value) || typeof value.event_type !== "string")
+            invalid();
+        if (!created && value.event_type !== "interaction.created")
+            lifecycleValid = false;
+        if (value.event_type === "interaction.created") {
+            if (created || sawStep || terminal !== undefined || done)
+                lifecycleValid = false;
+            created = true;
+            continue;
+        }
+        if (value.event_type === "interaction.status_update") {
+            if (terminal !== undefined)
+                invalid();
+            if (value.usage !== undefined) {
+                latestUsage = value.usage;
+                onUsage?.(value.usage);
+            }
+            continue;
+        }
+        if (value.event_type === "interaction.completed") {
+            if (terminal !== undefined || !record(value.interaction))
+                invalid();
+            terminal = value.interaction;
+            if (terminal.usage !== undefined) {
+                latestUsage = terminal.usage;
+                onUsage?.(terminal.usage);
+            }
+            continue;
+        }
+        if (terminal !== undefined ||
+            typeof value.index !== "number" ||
+            !Number.isSafeInteger(value.index) ||
+            value.index < 0)
+            invalid();
+        const index = value.index;
+        sawStep = true;
+        if (value.event_type === "step.start") {
+            if (steps.has(index) ||
+                !record(value.step) ||
+                typeof value.step.type !== "string")
+                invalid();
+            steps.set(index, {
+                step: structuredClone(value.step),
+                stopped: false,
+                args: null,
+            });
+            continue;
+        }
+        const current = steps.get(index);
+        if (current === undefined || current.stopped)
+            invalid();
+        if (value.event_type === "step.stop") {
+            if (current.args !== null) {
+                try {
+                    current.step.arguments = parseLossless(current.args);
+                }
+                catch {
+                    invalid();
+                }
+            }
+            current.stopped = true;
+            continue;
+        }
+        if (value.event_type !== "step.delta" || !record(value.delta))
+            invalid();
+        const delta = value.delta;
+        if (delta.type === "thought_signature" &&
+            current.step.type === "thought" &&
+            typeof delta.signature === "string" &&
+            Object.keys(delta).length === 2 &&
+            (current.step.signature === undefined || current.step.signature === "") &&
+            delta.signature.length > 0) {
+            current.step.signature = delta.signature;
+        }
+        else if ((delta.type === "arguments_delta" || delta.type === "arguments") &&
+            current.step.type === "function_call") {
+            const fragment = delta.type === "arguments_delta"
+                ? delta.arguments
+                : delta.partial_arguments;
+            if (typeof fragment !== "string" || Object.keys(delta).length !== 2)
+                invalid();
+            if (current.args === null &&
+                current.step.arguments !== undefined &&
+                (!record(current.step.arguments) ||
+                    Object.keys(current.step.arguments).length !== 0))
+                invalid();
+            current.args = (current.args ?? "") + fragment;
+        }
+        else if (delta.type === "text" &&
+            current.step.type === "model_output" &&
+            typeof delta.text === "string" &&
+            Object.keys(delta).length === 2) {
+            if (current.step.content === undefined)
+                current.step.content = [];
+            if (!Array.isArray(current.step.content))
+                invalid();
+            const last = current.step.content.at(-1);
+            if (record(last) &&
+                last.type === "text" &&
+                typeof last.text === "string" &&
+                Object.keys(last).length === 2)
+                last.text += delta.text;
+            else
+                current.step.content.push({ type: "text", text: delta.text });
+            onDelta?.({ kind: "text", text: delta.text });
+        }
+        else if (delta.type === "thought_summary" &&
+            current.step.type === "thought" &&
+            record(delta.content) &&
+            delta.content.type === "text" &&
+            typeof delta.content.text === "string" &&
+            Object.keys(delta).length === 2 &&
+            Object.keys(delta.content).length === 2) {
+            if (current.step.summary === undefined)
+                current.step.summary = [];
+            if (!Array.isArray(current.step.summary))
+                invalid();
+            const last = current.step.summary.at(-1);
+            if (record(last) &&
+                last.type === "text" &&
+                typeof last.text === "string" &&
+                Object.keys(last).length === 2)
+                last.text += delta.content.text;
+            else
+                current.step.summary.push(structuredClone(delta.content));
+            onDelta?.({ kind: "reasoning", text: delta.content.text });
+        }
+        else
+            invalid();
+    }
+    if (terminal === undefined ||
+        typeof terminal.status !== "string" ||
+        [...steps.values()].some((entry) => !entry.stopped))
+        invalid();
+    const ordered = [...steps.entries()].sort(([a], [b]) => a - b);
+    if (ordered.some(([index], position) => index !== position))
+        invalid();
+    return {
+        steps: ordered.map(([, entry]) => entry.step),
+        status: terminal.status,
+        usage: latestUsage,
+        continuationToken: terminal.continuation_token,
+        completeLifecycle: created && lifecycleValid,
+    };
+}
+export function projectGoogleInteractions(payload) {
+    if (payload.status !== "completed" && payload.status !== "requires_action")
+        throw new ModelHostOutcomeUnknownError(`Google Interactions returned unsupported terminal status: ${payload.status}`);
+    if (!validGoogleInteractionsSteps(payload.steps))
+        invalid();
+    const calls = [];
+    let text = "";
+    let reasoning = "";
+    for (const step of payload.steps) {
+        if (step.type === "function_call") {
+            if (typeof step.id !== "string" ||
+                !step.id ||
+                typeof step.name !== "string" ||
+                !step.name ||
+                !record(step.arguments) ||
+                calls.some((call) => call.id === step.id))
+                invalid();
+            calls.push({
+                id: step.id,
+                name: step.name,
+                arguments: structuredClone(step.arguments),
+            });
+        }
+        else if (step.type === "model_output") {
+            if (!Array.isArray(step.content))
+                invalid();
+            for (const part of step.content)
+                if (record(part) &&
+                    part.type === "text" &&
+                    typeof part.text === "string")
+                    text += part.text;
+        }
+        else if (step.type === "thought" && Array.isArray(step.summary)) {
+            for (const part of step.summary)
+                if (record(part) &&
+                    part.type === "text" &&
+                    typeof part.text === "string")
+                    reasoning += part.text;
+        }
+    }
+    if ((payload.status === "requires_action") !== calls.length > 0)
+        invalid();
+    return {
+        ...(text === "" ? {} : { text }),
+        ...(reasoning === "" ? {} : { reasoningContent: reasoning }),
+        toolCalls: calls,
+        stopReason: payload.status,
+        providerState: {
+            protocol: "google_interactions",
+            steps: structuredClone(payload.steps),
+        },
+    };
+}

package/dist/node/runtime/model/GoogleRequestPreview.js

@@ -0,0 +1,184 @@
+export function withGoogleHop(wire, hop) {
+    const hops = [...(wire.googleHops ?? [])];
+    const index = hops.findIndex((old) => old.exchange === hop.exchange &&
+        old.attempt === hop.attempt &&
+        old.hop === hop.hop);
+    if (index < 0)
+        hops.push(structuredClone(hop));
+    else
+        hops[index] = structuredClone(hop);
+    const updated = { ...wire, googleHops: hops };
+    if (!isSafeGoogleWireRequest(updated))
+        throw new Error("Unsafe Google hop evidence");
+    return updated;
+}
+export function isSafeGoogleWireRequest(value) {
+    return validWireRequest(value, true);
+}
+function validWireRequest(value, allowHops) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const record = value;
+    return (Object.keys(record).every((key) => [
+        "provider",
+        "method",
+        "endpointPath",
+        "headerNames",
+        "body",
+        "systemInstructionSources",
+        "redactedProviderContinuation",
+        ...(allowHops ? ["googleHops"] : []),
+    ].includes(key)) &&
+        record.provider === "google_interactions" &&
+        record.redactedProviderContinuation === true &&
+        record.method === "POST" &&
+        typeof record.endpointPath === "string" &&
+        (record.endpointPath === "" ||
+            /^\/(?:[A-Za-z0-9._~!$&'()*+,;=:@%/-]*\/)?interactions$/u.test(record.endpointPath)) &&
+        Array.isArray(record.headerNames) &&
+        record.headerNames.length === 3 &&
+        record.headerNames[0] === "Accept" &&
+        record.headerNames[1] === "x-goog-api-key" &&
+        record.headerNames[2] === "Content-Type" &&
+        validGooglePreviewBody(record.body) &&
+        (record.googleHops === undefined ||
+            (allowHops &&
+                Array.isArray(record.googleHops) &&
+                record.googleHops.every((hop) => validHop(hop, record.endpointPath)))) &&
+        (record.systemInstructionSources === undefined ||
+            (Array.isArray(record.systemInstructionSources) &&
+                record.systemInstructionSources.every((source) => typeof source === "object" &&
+                    source !== null &&
+                    !Array.isArray(source) &&
+                    Object.keys(source).every((key) => key === "promptId" || key === "sources") &&
+                    (!("promptId" in source) || typeof source.promptId === "string") &&
+                    "sources" in source &&
+                    Array.isArray(source.sources) &&
+                    source.sources.every((item) => typeof item === "string")))));
+}
+export function isSafeGoogleHop(value) {
+    return validHop(value);
+}
+function validHop(value, endpointPath) {
+    if (!isRecord(value) ||
+        !Object.keys(value).every((key) => [
+            "exchange",
+            "attempt",
+            "hop",
+            "tokenSupplied",
+            "status",
+            "httpStatus",
+            "usage",
+            "request",
+        ].includes(key)))
+        return false;
+    return (Number.isSafeInteger(value.exchange) &&
+        Number(value.exchange) > 0 &&
+        Number.isSafeInteger(value.attempt) &&
+        Number(value.attempt) > 0 &&
+        Number.isSafeInteger(value.hop) &&
+        Number(value.hop) > 0 &&
+        typeof value.tokenSupplied === "boolean" &&
+        [
+            "attempted",
+            "completed",
+            "requires_action",
+            "requires_continuation",
+            "failed",
+            "cancelled",
+            "incomplete",
+            "interrupted",
+            "rejected",
+        ].includes(String(value.status)) &&
+        (value.httpStatus === undefined ||
+            (Number.isSafeInteger(value.httpStatus) &&
+                Number(value.httpStatus) >= 100 &&
+                Number(value.httpStatus) <= 599)) &&
+        (value.usage === undefined ||
+            (isRecord(value.usage) &&
+                Object.entries(value.usage).every(([key, count]) => [
+                    "total_input_tokens",
+                    "total_cached_tokens",
+                    "total_thought_tokens",
+                    "total_output_tokens",
+                    "total_tool_use_tokens",
+                    "total_tokens",
+                ].includes(key) &&
+                    Number.isSafeInteger(count) &&
+                    Number(count) >= 0))) &&
+        (value.request === undefined
+            ? Number(value.hop) > 1
+            : validWireRequest(value.request, false) &&
+                isRecord(value.request) &&
+                (endpointPath === undefined ||
+                    value.request.endpointPath === endpointPath)));
+}
+function validGooglePreviewBody(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const body = value;
+    if (!Object.keys(body).every((key) => [
+        "model",
+        "store",
+        "stream",
+        "system_instruction",
+        "input",
+        "tools",
+        "generation_config",
+    ].includes(key)) ||
+        typeof body.model !== "string" ||
+        body.store !== false ||
+        body.stream !== true ||
+        (body.system_instruction !== undefined &&
+            typeof body.system_instruction !== "string") ||
+        !Array.isArray(body.input) ||
+        !isRecord(body.generation_config))
+        return false;
+    if (!Object.keys(body.generation_config).every((key) => key === "max_output_tokens" || key === "tool_choice") ||
+        typeof body.generation_config.max_output_tokens !== "number" ||
+        (body.generation_config.tool_choice !== undefined &&
+            body.generation_config.tool_choice !== "none"))
+        return false;
+    if (!body.input.every(validGooglePreviewItem))
+        return false;
+    return (body.tools === undefined ||
+        (Array.isArray(body.tools) &&
+            body.tools.every((tool) => isRecord(tool) &&
+                Object.keys(tool).every((key) => ["type", "name", "description", "parameters"].includes(key)) &&
+                tool.type === "function" &&
+                typeof tool.name === "string" &&
+                typeof tool.description === "string" &&
+                isRecord(tool.parameters))));
+}
+function validGooglePreviewItem(value) {
+    if (!isRecord(value) || typeof value.type !== "string")
+        return false;
+    if (value.type === "runtime_redacted_provider_step")
+        return Object.keys(value).length === 1;
+    if (value.type === "user_input" || value.type === "model_output")
+        return (Object.keys(value).every((key) => key === "type" || key === "content") &&
+            validTextParts(value.content));
+    if (value.type === "function_call")
+        return (Object.keys(value).every((key) => ["type", "id", "name", "arguments"].includes(key)) &&
+            typeof value.id === "string" &&
+            value.name === "runtime_load_context" &&
+            isRecord(value.arguments) &&
+            Object.keys(value.arguments).length === 0);
+    if (value.type === "function_result")
+        return (Object.keys(value).every((key) => ["type", "call_id", "name", "result", "is_error"].includes(key)) &&
+            typeof value.call_id === "string" &&
+            typeof value.name === "string" &&
+            validTextParts(value.result) &&
+            (value.is_error === undefined || value.is_error === true));
+    return false;
+}
+function validTextParts(value) {
+    return (Array.isArray(value) &&
+        value.every((part) => isRecord(part) &&
+            Object.keys(part).length === 2 &&
+            part.type === "text" &&
+            typeof part.text === "string"));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/node/runtime/model/ModelConnectionStore.js

@@ -121,6 +121,8 @@ export class ModelConnectionStore {
     async listModels(input) {
         await this.#mutationTail;
         const provider = validateProvider(input.provider);
+        if (provider === "google_interactions")
+            throw new Error("Google Interactions model discovery is unverified; enter a model ID manually");
         const baseUrl = normalizeBaseUrl(requiredTrimmed(input.baseUrl, "Base URL", 4096));
         let apiKey = normalizeOptionalApiKey(input.apiKey);
         if (apiKey === undefined && input.connectionId !== undefined) {
@@ -396,7 +398,8 @@ function toBinding(connection) {
 function validateProvider(value) {
     if (value !== "chat_completions" &&
         value !== "openai_responses" &&
-        value !== "anthropic_messages")
+        value !== "anthropic_messages" &&
+        value !== "google_interactions")
         throw new Error("Model-connection protocol is invalid");
     return value;
 }

package/dist/node/runtime/model/ProviderExchangeState.js

@@ -1 +1,44 @@
-export {};
+/** Check known structural requirements without removing unknown fields. */
+export function validGoogleInteractionsSteps(value) {
+    if (!Array.isArray(value))
+        return false;
+    const ids = new Set();
+    return value.every((step) => {
+        if (!isRecord(step) ||
+            typeof step.type !== "string" ||
+            step.type.length === 0)
+            return false;
+        if (step.type === "function_call") {
+            if (typeof step.id !== "string" ||
+                step.id.length === 0 ||
+                ids.has(step.id) ||
+                typeof step.name !== "string" ||
+                step.name.length === 0 ||
+                !isRecord(step.arguments))
+                return false;
+            ids.add(step.id);
+        }
+        if (step.type === "model_output" && !validContent(step.content))
+            return false;
+        if (step.type === "thought" &&
+            (typeof step.signature !== "string" ||
+                step.signature.length === 0 ||
+                (step.summary !== undefined && !validContent(step.summary))))
+            return false;
+        return true;
+    });
+}
+/** Empty terminal results are valid, but an assistant history item must replay steps. */
+export function validGoogleInteractionsContinuation(value) {
+    return validGoogleInteractionsSteps(value) && value.length > 0;
+}
+function validContent(value) {
+    return (Array.isArray(value) &&
+        value.every((part) => isRecord(part) &&
+            typeof part.type === "string" &&
+            part.type.length > 0 &&
+            (part.type !== "text" || typeof part.text === "string")));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/node/runtime/model/ProviderStream.js

@@ -1,6 +1,8 @@
-export async function* providerStreamEvents(body) {
+export async function* providerStreamEvents(body, options) {
     const reader = body.getReader();
-    const decoder = new TextDecoder();
+    const decoder = new TextDecoder("utf-8", {
+        fatal: options?.fatalUtf8 === true,
+    });
     let pending = "";
     let event = null;
     let data = [];

package/dist/node/runtime/play/FileNativePlayAdvanceStore.js

@@ -8,10 +8,10 @@ const LAYOUT_MARKER = "play-advance-layout.json";
  * The single in-progress play advance of a call chain, if any.
  *
  * It exists only between `begin` and `markSettled`. A marker that survives a
- * restart means the advance was interrupted; the runtime marks the chain
- * interrupted and the player retries. Released records from earlier layouts
- * never block a world from opening, and the storage upgrade removes them
- * (see `migrateLayout`).
+ * restart means the advance needs recovery: a persisted ending is retained,
+ * and an unfinished request follows its protocol's retry boundary. Released
+ * records from earlier layouts never block a world from opening; the storage
+ * upgrade removes them (see `migrateLayout`).
  */
 export class FileNativePlayAdvanceStore {
     #worldsRoot;