narraeon 0.1.0

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

@@ -0,0 +1,183 @@
+import { errorDescription, } from "../model/AiFailureLog.js";
+/**
+ * Run every follow-up declared by the frozen play preset exactly once after the
+ * main model exchange has fully settled.
+ *
+ * Each request is `prefix + its own prompt` — the prompt replaces rather than
+ * appends, so all requests share one identical stable prefix (the main chain
+ * itself) and stay invisible to each other. Results only reach the artifact
+ * store; nothing here is written back into the chain transcript, so the next
+ * player message follows the narrative directly.
+ *
+ * Follow-ups run strictly after Authority has accepted the exchange. A failure
+ * here cannot damage committed world state: it is recorded, the remaining
+ * requests still run, and the chain returns to the player either way.
+ */
+export async function runPlayFollowupRequests(input) {
+    if (input.followups.length === 0)
+        return { outcomes: [] };
+    await input.artifacts.beginOperation(input.context);
+    await input.artifacts.markCoreCommitted(input.context, input.head);
+    await input.artifacts.beginExtension(input.context);
+    const prefix = structuredClone(input.prefix);
+    const outcomes = [];
+    const completed = [];
+    let failure;
+    for (const followup of input.followups) {
+        if (input.signal?.aborted === true) {
+            failure ??= "The follow-up request was cancelled.";
+            break;
+        }
+        const outcome = await runOne(input, followup, prefix);
+        outcomes.push(outcome);
+        input.observer?.onOutcome?.(outcome);
+        if (outcome.failure === undefined)
+            completed.push(followup.id);
+        else
+            failure ??= outcome.failure;
+    }
+    const extension = failure === undefined
+        ? await input.artifacts.completeExtension(input.context.operationId, completed)
+        : await input.artifacts.failExtension(input.context.operationId, "recovery_required", failure, completed);
+    return { outcomes, extension };
+}
+async function runOne(input, followup, prefix) {
+    const outcome = {
+        id: followup.id,
+        displayName: followup.displayName,
+        text: "",
+        toolCalls: [],
+    };
+    const requestContext = {
+        ...input.context,
+        requestId: followup.id,
+        requestAttempt: 1,
+        maxArtifactBytes: followup.maxArtifactBytes,
+        declarations: structuredClone(followup.artifacts),
+    };
+    let responseDiagnostics;
+    try {
+        await input.artifacts.beginRequestAttempt(requestContext);
+        const response = await input.modelHost.exchange({
+            bootstrap: structuredClone(input.bootstrap),
+            tools: structuredClone(followup.tools),
+            toolUniverse: structuredClone(followup.tools),
+            allowedTools: [...followup.allowedTools],
+            toolStrategy: input.toolStrategy,
+            // The prompt replaces the previous followup's prompt instead of being
+            // appended after it: every request sees exactly the main-chain prefix.
+            appended: [
+                ...structuredClone(prefix),
+                {
+                    kind: "prompt_delta",
+                    logicalMessages: structuredClone(followup.logicalMessages),
+                },
+            ],
+            requestId: followup.id,
+            operationId: input.context.operationId,
+            requestAttempt: 1,
+            exchange: 1,
+            maxOutputTokens: input.maxOutputTokens,
+        });
+        responseDiagnostics = response.diagnostics;
+        if (response.diagnostics !== undefined)
+            await input.failureLog?.recordExchangeIfActive(response.diagnostics);
+        outcome.text = response.text ?? "";
+        if (response.reasoningContent !== undefined)
+            outcome.reasoning = response.reasoningContent;
+        if (response.usage !== undefined)
+            outcome.usage = {
+                inputTokens: response.usage.inputTokens,
+                outputTokens: response.usage.outputTokens,
+            };
+        // One request, one pass: tool results are recorded for the trace but never
+        // fed back for another exchange.
+        for (const call of response.toolCalls ?? []) {
+            const result = await executeArtifactCall(input, requestContext, call);
+            outcome.toolCalls.push({
+                callId: call.id,
+                name: call.name,
+                arguments: structuredClone(call.arguments),
+                ok: result.ok,
+                markdown: result.markdown,
+            });
+        }
+        const failedTools = outcome.toolCalls.filter(({ ok }) => !ok);
+        if (failedTools.length > 0 && response.diagnostics !== undefined)
+            await input.failureLog?.recordFailure({
+                exchange: response.diagnostics,
+                failures: [
+                    {
+                        kind: "tool_execution",
+                        message: `The artifact tool for follow-up request ${followup.id} was rejected.`,
+                        details: { calls: structuredClone(failedTools) },
+                    },
+                ],
+            });
+        const missing = followup.artifacts
+            .filter(({ required }) => required)
+            .filter(({ name }) => !outcome.toolCalls.some(({ ok, arguments: args }) => ok && args?.output === name))
+            .map(({ name }) => name);
+        if (missing.length > 0)
+            outcome.failure = `Follow-up request ${followup.id} did not submit required artifacts: ${missing.join(", ")}`;
+        if (outcome.failure !== undefined && response.diagnostics !== undefined)
+            await input.failureLog?.recordFailure({
+                exchange: response.diagnostics,
+                failures: [
+                    {
+                        kind: "format_validation",
+                        message: outcome.failure,
+                        details: { missing },
+                    },
+                ],
+            });
+        else if (failedTools.length === 0 && response.diagnostics !== undefined)
+            await input.failureLog?.resolve({
+                exchange: response.diagnostics,
+                message: `Follow-up request ${followup.id} recovered during a later model exchange.`,
+            });
+    }
+    catch (error) {
+        outcome.failure =
+            error instanceof Error
+                ? error.message
+                : `Follow-up request ${followup.id} failed.`;
+        if (responseDiagnostics !== undefined)
+            await input.failureLog?.recordFailure({
+                exchange: responseDiagnostics,
+                failures: [
+                    {
+                        kind: "runtime_post_processing",
+                        message: outcome.failure,
+                        error: errorDescription(error),
+                    },
+                ],
+            });
+    }
+    return outcome;
+}
+async function executeArtifactCall(input, context, call) {
+    if (call.name !== "artifact_emit" && call.name !== "artifact_clear")
+        return {
+            ok: false,
+            markdown: `# Runtime tool rejected\n\nThe follow-up request did not provide ${call.name}.`,
+        };
+    const args = call.arguments;
+    if (typeof args !== "object" ||
+        args === null ||
+        Array.isArray(args) ||
+        typeof args.output !== "string")
+        return {
+            ok: false,
+            markdown: "# Runtime argument error\n\nThe artifact tool requires an output name.",
+        };
+    const output = args.output;
+    return call.name === "artifact_emit"
+        ? input.artifacts.emit({
+            context,
+            output,
+            payload: args.payload,
+            toolCallId: call.id,
+        })
+        : input.artifacts.clear({ context, output, toolCallId: call.id });
+}

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

@@ -0,0 +1,185 @@
+import { parsePlayPresetRegexAsset, toPlayPresetStructuredEditor, } from "./FileNativePlayPresetStore.js";
+/**
+ * Read-only workbench seam. It resolves the same frozen file-native binding
+ * used by PromptCompiler and FrontendExtensionBundle, but never calls a model,
+ * writes a world, or executes author JavaScript.
+ */
+export function buildPlayPresetWorkbenchSnapshot(binding) {
+    const scriptsEnabled = binding.scriptsEnabled !== false;
+    const structure = toPlayPresetStructuredEditor(binding.definition);
+    const staticErrors = [];
+    const artifactPreviews = [];
+    for (const followup of binding.definition.followups)
+        for (const declaration of followup.artifacts) {
+            const diagnostics = [];
+            let regex = [];
+            if (declaration.regex !== undefined) {
+                try {
+                    const source = binding.files[declaration.regex];
+                    if (source === undefined)
+                        throw new Error("The regex resource does not exist");
+                    regex = parsePlayPresetRegexAsset(source, declaration.regex);
+                }
+                catch (error) {
+                    const message = error instanceof Error
+                        ? error.message
+                        : "The regex resource is invalid";
+                    diagnostics.push(message);
+                    staticErrors.push({
+                        code: "regex_invalid",
+                        message,
+                        location: declaration.regex,
+                    });
+                }
+            }
+            const rawPayload = samplePayload(declaration.payloadContract, declaration.contentType);
+            const rawText = declaration.contentType === "application/json"
+                ? JSON.stringify(rawPayload, null, 2)
+                : declaration.contentType === "text/markdown"
+                    ? "# Example follow-up artifact\n\nThis is a local workbench preview sample."
+                    : declaration.contentType === "text/html"
+                        ? "<p>This is a local HTML workbench sample.</p>"
+                        : "This is a local text workbench sample.";
+            let renderer;
+            if (declaration.renderer !== undefined) {
+                const source = binding.files[declaration.renderer];
+                if (source === undefined) {
+                    const message = `Renderer resource does not exist: ${declaration.renderer}`;
+                    diagnostics.push(message);
+                    staticErrors.push({
+                        code: "renderer_missing",
+                        message,
+                        location: declaration.renderer,
+                    });
+                }
+                else {
+                    const scriptSources = (declaration.scripts ?? []).flatMap((path) => {
+                        const script = binding.files[path];
+                        if (script === undefined) {
+                            diagnostics.push(`Script resource does not exist: ${path}`);
+                            staticErrors.push({
+                                code: "script_missing",
+                                message: `Script resource does not exist: ${path}`,
+                                location: path,
+                            });
+                            return [];
+                        }
+                        return [script];
+                    });
+                    const assetSources = (declaration.assets ?? []).flatMap((path) => {
+                        const asset = binding.files[path];
+                        if (asset === undefined) {
+                            diagnostics.push(`Asset resource does not exist: ${path}`);
+                            staticErrors.push({
+                                code: "asset_missing",
+                                message: `Asset resource does not exist: ${path}`,
+                                location: path,
+                            });
+                            return [];
+                        }
+                        return [{ id: path, source: asset }];
+                    });
+                    renderer = {
+                        mode: declaration.rendererMode ?? "document",
+                        ...(declaration.rendererRevision === undefined
+                            ? {}
+                            : { revision: declaration.rendererRevision }),
+                        document: source,
+                        scripts: scriptsEnabled ? scriptSources : [],
+                        assets: assetSources,
+                        trustedLocalCode: scriptsEnabled &&
+                            (declaration.contentType === "text/html" ||
+                                (declaration.scripts?.length ?? 0) > 0),
+                    };
+                }
+            }
+            artifactPreviews.push({
+                requestId: followup.id,
+                output: declaration.name,
+                declaration: structuredClone(declaration),
+                rawPayload,
+                rawText,
+                regex,
+                ...(renderer === undefined ? {} : { renderer }),
+                activeProjection: {
+                    status: "active",
+                    channel: declaration.channel,
+                    ...(declaration.key === undefined ? {} : { key: declaration.key }),
+                    strategy: declaration.strategy,
+                    save: declaration.save,
+                },
+                clear: {
+                    supported: true,
+                    invalidation: declaration.invalidation,
+                    description: declaration.invalidation === "never"
+                        ? "Declared as never; the preview displays the policy without clearing automatically."
+                        : "clear is an explicit projection event and does not modify the raw payload.",
+                },
+                simulation: simulateArtifactProjection(declaration),
+                diagnostics,
+            });
+        }
+    return {
+        id: binding.id,
+        name: binding.name,
+        revision: binding.revision,
+        structure,
+        artifactPreviews,
+        staticErrors,
+        trustedLocalCode: artifactPreviews.some(({ renderer }) => renderer?.trustedLocalCode === true),
+        scriptsEnabled,
+    };
+}
+/**
+ * Deterministic, local-only projection preview. It mirrors the production
+ * lifecycle vocabulary without touching a world or artifact store.
+ */
+export function simulateArtifactProjection(declaration) {
+    const identity = `${declaration.name} → ${declaration.channel}${declaration.key === undefined ? "" : `/${declaration.key}`}`;
+    const invalidation = declaration.invalidation;
+    return {
+        emitted: { status: "active", identity },
+        explicitClear: { status: "cleared", identity },
+        invalidation: {
+            policy: invalidation,
+            status: invalidation === "never"
+                ? "active"
+                : invalidation === "explicit_clear"
+                    ? "cleared"
+                    : "superseded",
+            reason: invalidation === "never"
+                ? "never: no automatic invalidation event; remains active after emit."
+                : invalidation === "explicit_clear"
+                    ? "explicit_clear: becomes cleared after a clear event."
+                    : `${invalidation}: becomes superseded after the lifecycle event.`,
+        },
+    };
+}
+function samplePayload(contract, contentType) {
+    if (contract === undefined) {
+        if (contentType === "text/html")
+            return "<p>This is a local HTML workbench sample.</p>";
+        if (contentType === "text/markdown")
+            return "# Example follow-up artifact\n\nThis is a local workbench preview sample.";
+        if (contentType === "text/plain")
+            return "This is a local text workbench sample.";
+        return { sample: "workbench" };
+    }
+    switch (contract.type) {
+        case "object":
+            return Object.fromEntries(Object.entries(contract.properties ?? {})
+                .filter(([key]) => contract.required?.includes(key) ?? true)
+                .map(([key, child]) => [key, samplePayload(child)]));
+        case "array":
+            return [samplePayload(contract.items)];
+        case "string":
+            return "Example text";
+        case "number":
+        case "integer":
+            return 1;
+        case "boolean":
+            return true;
+        case "null":
+            return null;
+    }
+}