@zq-silk/yui 2.3.0 → 2.4.0

package/dist/runtime/codexNativeAccess.js

@@ -0,0 +1,175 @@
+import { isDeepStrictEqual } from "node:util";
+import { unknownAgentRunConfiguration } from "./agentRunConfiguration.js";
+import { CodexPreSubmissionError } from "./codexAppServerRuntime.js";
+const READS = new Set([
+    "config/read", "configRequirements/read", "model/list", "collaborationMode/list",
+    "experimentalFeature/list", "skills/list", "hooks/list", "mcpServerStatus/list", "account/read",
+    "account/rateLimits/read", "modelProvider/capabilities/read", "permissionProfile/list",
+    "thread/read", "thread/turns/list", "thread/items/list", "thread/goal/get"
+]);
+const REQUESTS = new Set([
+    "item/commandExecution/requestApproval", "item/fileChange/requestApproval",
+    "item/tool/requestUserInput", "item/permissions/requestApproval", "mcpServer/elicitation/request"
+]);
+/** A view of one existing connection, never another Thread or durable input queue.
+ * Both the native TUI and Web answer the original server request on this transport. */
+export function createCodexNativeAccess(threadId, initialized, channel, openingMessages = [], initialConfiguration) {
+    const pending = new Map();
+    const listeners = new Set();
+    let configuration = initialConfiguration;
+    let observedAt = new Date().toISOString();
+    const observed = () => typeof configuration?.model !== "string"
+        ? unknownAgentRunConfiguration("No confirmed native model response. Reconnect to restore the fixed launch configuration.")
+        : {
+            status: "observed", observedAt,
+            handshake: { status: "unsupported", reason: "Model reported by Codex thread/start or thread/resume; not a capability handshake." },
+            requested: [],
+            axes: [{ key: "model", category: "model", current: { status: "observed", value: configuration.model }, offered: [] }]
+        };
+    const observe = (message) => {
+        const params = message.params;
+        if (params?.threadId !== threadId)
+            return;
+        if ((typeof message.id === "string" || typeof message.id === "number")
+            && typeof message.method === "string" && REQUESTS.has(message.method)
+            && (typeof params.turnId === "string"
+                || (message.method === "mcpServer/elicitation/request" && params.turnId == null))) {
+            pending.set(message.id, { id: message.id, method: message.method,
+                threadId, turnId: typeof params.turnId === "string" ? params.turnId : null, params });
+        }
+        if (message.method === "serverRequest/resolved")
+            pending.delete(params.requestId);
+        if (message.method === "turn/completed") {
+            const turn = params.turn;
+            for (const [id, request] of pending)
+                if (request.turnId === turn?.id)
+                    pending.delete(id);
+        }
+        for (const listener of listeners)
+            listener(message);
+    };
+    for (const message of openingMessages)
+        observe(message);
+    channel.onMessage(observe);
+    return {
+        initialized,
+        get attached() { return listeners.size > 0; },
+        get requests() { return [...pending.values()]; },
+        get runConfiguration() { return observed(); },
+        async setModel(model) {
+            try {
+                if (!model.trim() || model.length > 200 || model.includes("\0"))
+                    throw new Error("Invalid model.");
+                const read = await channel.request("thread/read", { threadId, includeTurns: false });
+                const thread = read.thread;
+                if (thread?.id !== threadId || thread.status?.type !== "idle") {
+                    throw new Error("Model switching requires a confirmed idle Thread.");
+                }
+            }
+            catch (error) {
+                throw new CodexPreSubmissionError(error instanceof Error ? error.message : "Native idle state is unavailable.");
+            }
+            // No fork/start, account, permission or Role-default mutation. Do not
+            // preserve an old observation if the native mutation becomes uncertain.
+            configuration = undefined;
+            const result = await channel.request("thread/resume", { threadId, model, excludeTurns: true });
+            if (result.thread?.id !== threadId || result.model !== model) {
+                throw new Error("Native model adoption was not confirmed; inspect before another change.");
+            }
+            configuration = result;
+            observedAt = new Date().toISOString();
+        },
+        async read(method, params) {
+            // TUI startup attaches to the already opened Thread without resuming it
+            // with new options or changing the Host's configured execution boundary.
+            if (method === "thread/resume") {
+                if (params.threadId !== threadId)
+                    throw new Error("Select the existing Session; new/forked Threads are not supported here.");
+                const page = params.initialTurnsPage;
+                configuration = await channel.request("thread/resume", { threadId,
+                    ...(typeof params.excludeTurns === "boolean" ? { excludeTurns: params.excludeTurns } : {}),
+                    ...(page ? { initialTurnsPage: { ...page, limit: Math.min(40, typeof page.limit === "number" && page.limit > 0 ? page.limit : 40) } } : {}) });
+                observedAt = new Date().toISOString();
+                return configuration;
+            }
+            if (!READS.has(method))
+                throw new Error(`Native operation is not available in managed access: ${method}.`);
+            if (method.startsWith("thread/") && params.threadId !== threadId) {
+                throw new Error("Native read targets a different Thread.");
+            }
+            // Native TUI owns its hydration protocol (legacy TUI can explicitly ask
+            // for full turns). Web history remains independently bounded/paginated.
+            return channel.request(method, method === "thread/turns/list" || method === "thread/items/list"
+                ? { ...params, limit: Math.min(40, typeof params.limit === "number" && params.limit > 0 ? params.limit : 40) }
+                : params);
+        },
+        validateTurn(params) {
+            if (!configuration)
+                throw new Error("Native TUI has not attached to the existing Thread.");
+            for (const [key, source] of Object.entries({
+                model: "model", cwd: "cwd", runtimeWorkspaceRoots: "runtimeWorkspaceRoots",
+                approvalPolicy: "approvalPolicy", approvalsReviewer: "approvalsReviewer",
+                effort: "reasoningEffort", collaborationMode: "collaborationMode"
+            })) {
+                if (params[key] != null && !isDeepStrictEqual(params[key], configuration[source])) {
+                    throw new Error(`Native ${key} differs from the managed Session; change it through Yui configuration.`);
+                }
+            }
+            for (const key of ["sandboxPolicy", "permissions", "environments", "toolOutput", "additionalContext", "outputSchema", "disabledPluginIds", "serviceTierForTurn", "summary", "personality", "cyberAccessProgram"]) {
+                if (params[key] != null)
+                    throw new Error(`Native ${key} overrides are not supported in managed access.`);
+            }
+            if (params.serviceTier != null && params.serviceTier !== (configuration.serviceTier ?? "default")) {
+                throw new Error("Native service tier differs from the managed Session.");
+            }
+        },
+        async respond(id, expectedThread, turnId, result) {
+            const request = pending.get(id);
+            if (!request || request.threadId !== expectedThread || request.turnId !== turnId) {
+                throw new Error("Native request is no longer pending for this exact Thread and Turn.");
+            }
+            validateNativeResponse(request, result);
+            // Claim before awaiting transport. A lost send acknowledgement is unknown,
+            // not permission for another entry to repeat a possibly applied answer.
+            pending.delete(id);
+            await channel.send({ id, result });
+        },
+        events(listener) { listeners.add(listener); return () => { listeners.delete(listener); }; }
+    };
+}
+function validateNativeResponse(request, result) {
+    if (!result || typeof result !== "object" || Array.isArray(result))
+        throw new Error("Missing native response.");
+    if (request.method === "mcpServer/elicitation/request") {
+        if (!["accept", "decline", "cancel"].includes(String(result.action))
+            || (result.action !== "accept" && result.content != null)) {
+            throw new Error("Invalid native MCP elicitation response.");
+        }
+    }
+    else if (request.method === "item/tool/requestUserInput") {
+        const answers = result.answers;
+        const questions = request.params.questions;
+        if (!answers || typeof answers !== "object" || Array.isArray(answers) || !Array.isArray(questions)) {
+            throw new Error("Native question requires answers keyed by question id.");
+        }
+        const ids = questions.map(q => q.id);
+        if (Object.keys(answers).some(id => !ids.includes(id))
+            || ids.some(id => {
+                if (typeof id !== "string")
+                    return true;
+                const answer = answers[id];
+                return !Array.isArray(answer?.answers) || answer.answers.some(value => typeof value !== "string");
+            })) {
+            throw new Error("Native answers do not match the original questions.");
+        }
+    }
+    else if (request.method === "item/permissions/requestApproval") {
+        // Web currently exposes decline only; richer native grants remain the TUI's
+        // protocol responsibility. Never infer broad grants from an accept button.
+        if (!result.permissions || typeof result.permissions !== "object")
+            throw new Error("Missing native permissions response.");
+    }
+    else if (!["accept", "acceptForSession", "decline", "cancel"].includes(String(result.decision))) {
+        throw new Error("Invalid native approval decision.");
+    }
+}

package/dist/runtime/controlledCodexTui.js

@@ -0,0 +1,116 @@
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { once } from "node:events";
+import WebSocket, { WebSocketServer } from "ws";
+import { localCodexTuiEnvironment } from "./codexInteractiveHost.js";
+/** The TUI is a view of the Host-owned connection. It cannot launch, fork,
+ * reconfigure, or submit outside the Host's existing input admission. */
+export async function openControlledCodexTui(payload, threadId, access, input) {
+    const baseArgs = JSON.parse(payload.environment.YUI_AGENT_BASE_ARGS ?? "[]");
+    if (!Array.isArray(baseArgs) || baseArgs.some(arg => typeof arg !== "string"))
+        throw new Error("Invalid Codex base arguments.");
+    const token = randomBytes(32).toString("hex");
+    const server = new WebSocketServer({
+        host: "127.0.0.1", port: 0, maxPayload: 1024 * 1024, perMessageDeflate: false,
+        verifyClient: (info) => info.req.headers.authorization === `Bearer ${token}`
+    });
+    let socket;
+    let closed = false;
+    let markReady;
+    let failReady;
+    const ready = new Promise((resolve, reject) => { markReady = resolve; failReady = reject; });
+    void ready.catch(() => { });
+    const unsubscribe = access.events(message => {
+        if (socket?.readyState === WebSocket.OPEN)
+            socket.send(JSON.stringify(message));
+    });
+    server.on("connection", client => {
+        if (socket || closed) {
+            client.close(1008, "TUI already attached.");
+            return;
+        }
+        socket = client;
+        client.on("error", input.onError);
+        client.on("message", (bytes, binary) => {
+            void (async () => {
+                if (binary)
+                    throw new Error("Expected native JSON request.");
+                const message = JSON.parse(bytes.toString());
+                const id = message.id;
+                if (typeof id !== "number" && typeof id !== "string")
+                    return; // notifications
+                try {
+                    if (message.method === undefined) {
+                        const request = access.requests.find(request => request.id === id);
+                        if (!request)
+                            throw new Error("Native request is no longer pending.");
+                        await input.respond(id, request.turnId, message.result);
+                        return;
+                    }
+                    const method = String(message.method), params = (message.params ?? {});
+                    if (method === "turn/start")
+                        access.validateTurn(params);
+                    const result = method === "initialize" ? access.initialized
+                        : ["turn/start", "turn/steer", "turn/interrupt"].includes(method) ? await input.mutate(method, params)
+                            : await access.read(method, params);
+                    if (client.readyState === WebSocket.OPEN)
+                        client.send(JSON.stringify({ id, result }));
+                    if (method === "thread/resume") {
+                        markReady();
+                        for (const request of access.requests)
+                            client.send(JSON.stringify({
+                                id: request.id, method: request.method, params: request.params
+                            }));
+                    }
+                }
+                catch (error) {
+                    if (client.readyState === WebSocket.OPEN)
+                        client.send(JSON.stringify({
+                            id, error: { code: -32600, message: error instanceof Error ? error.message : String(error) }
+                        }));
+                }
+            })().catch(input.onError);
+        });
+    });
+    try {
+        await once(server, "listening");
+    }
+    catch (error) {
+        unsubscribe();
+        server.close();
+        throw error;
+    }
+    const address = server.address();
+    if (!address || typeof address === "string")
+        throw new Error("Native TUI relay did not bind.");
+    const child = spawn(payload.command, [...baseArgs,
+        "--remote", `ws://127.0.0.1:${address.port}`, "--remote-auth-token-env", "YUI_CODEX_REMOTE_AUTH_TOKEN",
+        "resume", threadId], {
+        cwd: payload.cwd, stdio: "inherit",
+        env: { ...localCodexTuiEnvironment(payload.environment), YUI_CODEX_REMOTE_AUTH_TOKEN: token }
+    });
+    const close = () => {
+        if (closed)
+            return;
+        closed = true;
+        unsubscribe();
+        socket?.terminate();
+        server.close();
+        child.kill("SIGTERM");
+    };
+    server.on("error", input.onError);
+    child.on("error", error => { failReady(error); input.onError(error); close(); input.onExit(); });
+    child.once("exit", () => { failReady(new Error("Native TUI exited before attachment.")); close(); input.onExit(); });
+    const deadline = setTimeout(() => failReady(new Error("Native TUI did not attach to the selected Thread.")), 10_000);
+    try {
+        await ready;
+    }
+    catch (error) {
+        close();
+        throw error;
+    }
+    finally {
+        clearTimeout(deadline);
+    }
+    return { close };
+}

package/dist/runtime/publicReply.js

@@ -0,0 +1,23 @@
+export function foldPublicReply(previous, nativeSessionId, method, params) {
+    if (params.threadId !== nativeSessionId)
+        return previous;
+    if (method === "turn/started")
+        return undefined;
+    if (typeof params.turnId !== "string")
+        return previous;
+    if (method === "item/agentMessage/delta" && typeof params.itemId === "string" && typeof params.delta === "string") {
+        const same = previous?.id === params.itemId && previous.turnId === params.turnId;
+        const text = (same ? previous.text : "") + params.delta;
+        return { nativeSessionId, turnId: params.turnId, id: params.itemId,
+            text: text.slice(0, 6000), truncated: text.length > 6000 || !!(same && previous.truncated) };
+    }
+    if ((method === "item/started" || method === "item/completed")
+        && params.item !== null && typeof params.item === "object") {
+        const item = params.item;
+        if (item.type === "agentMessage" && typeof item.id === "string" && typeof item.text === "string") {
+            return { nativeSessionId, turnId: params.turnId, id: item.id,
+                text: item.text.slice(0, 6000), truncated: item.text.length > 6000 };
+        }
+    }
+    return previous;
+}

package/dist/runtime/runtimeObservation.js

@@ -15,6 +15,11 @@ export function isRuntimeTokenEvidence(observation) {
                 && (observation.payload.observationQuality === "partial"
                     || observation.payload.observationQuality === "unavailable")));
 }
+/** Both money and tokens survive activity compaction; only tokens feed token metrics. */
+export function isRuntimeUsageEvidence(observation) {
+    return isRuntimeTokenEvidence(observation)
+        || (observation.kind === "activity.observed" && observation.payload.cost !== undefined);
+}
 const KINDS = [
     "host.observed",
     "session.started",
@@ -296,6 +301,11 @@ function normalizePayload(kind, input) {
     const observerSource = input.observerSource === undefined
         ? undefined
         : normalizeObserverSource(input.observerSource);
+    const cost = input.cost === undefined ? undefined : normalizeCost(input.cost);
+    if (cost !== undefined && (kind !== "activity.observed"
+        || (cost.semantics === "request" && input.activityId === undefined))) {
+        throw new Error("Cost requires activity.observed and a stable request activityId.");
+    }
     if (kind === "turn.failed" && input.failure === undefined) {
         throw new Error("run.failed requires normalized failure evidence.");
     }
@@ -376,6 +386,7 @@ function normalizePayload(kind, input) {
                     ...input.usage,
                     semantics: input.usage.semantics ?? "cumulative-session"
                 }) }),
+        ...(cost === undefined ? {} : { cost }),
         ...(observerSource === undefined ? {} : { observerSource }),
         ...(input.sourceId === undefined
             ? {}
@@ -434,6 +445,43 @@ function normalizePayload(kind, input) {
         ...(input.goalTokenBudget === undefined ? {} : { goalTokenBudget: input.goalTokenBudget })
     });
 }
+function normalizeCost(input) {
+    if (input === null || typeof input !== "object"
+        || !["actual", "estimated"].includes(input.kind)
+        || !["request", "cumulative-session"].includes(input.semantics)) {
+        throw new Error("Runtime cost kind or semantics is invalid.");
+    }
+    if (!Number.isFinite(input.amount) || input.amount < 0 || input.amount > Number.MAX_SAFE_INTEGER) {
+        throw new Error("Runtime cost amount must be finite and non-negative.");
+    }
+    if (typeof input.currency !== "string" || !/^[A-Z]{3}$/u.test(input.currency)) {
+        throw new Error("Runtime cost currency requires a three-letter currency code.");
+    }
+    if (input.kind === "estimated" && input.basis === undefined) {
+        throw new Error("Estimated cost requires a price basis.");
+    }
+    const basis = input.basis;
+    if (basis !== undefined && (!Array.isArray(basis.excluded) || basis.excluded.length > 16)) {
+        throw new Error("Runtime cost basis excluded items must be a bounded list.");
+    }
+    return Object.freeze({
+        kind: input.kind, semantics: input.semantics, amount: input.amount,
+        currency: input.currency, source: costText(input.source, "Cost source"),
+        ...(basis === undefined ? {} : { basis: Object.freeze({
+                model: costText(basis.model, "Cost model"),
+                source: costText(basis.source, "Price source"),
+                version: costText(basis.version, "Price version or date"),
+                scope: costText(basis.scope, "Estimate scope"),
+                excluded: Object.freeze(basis.excluded.map(value => costText(value, "Excluded cost", 128)))
+            }) })
+    });
+}
+function costText(value, label, limit = 512) {
+    const text = requireText(value, label);
+    if (text.length > limit)
+        throw new Error(`${label} exceeds ${limit} characters.`);
+    return text;
+}
 export function runtimeObservationSemanticKey(input) {
     const fence = input.fence;
     const continuationIdentity = [

package/dist/runtime/structuredProviderHost.js

@@ -13,6 +13,8 @@ import { unsupportedAgentRunConfiguration } from "./agentRunConfiguration.js";
 import { codexAppServerErrorIsMissing, CodexAppServerRequestError, CodexAppServerRuntime, codexClientInitialization, codexGoalNotification, codexTurnInput, codexTurnOutput } from "./codexAppServerRuntime.js";
 import { JsonLineChannel, PROVIDER_MESSAGE_MAX_BYTES, terminateProcessGroup } from "./jsonLineChannel.js";
 import { PROVIDER_ACCEPT_TIMEOUT_MS } from "./runtimeDeadlines.js";
+import { foldPublicReply } from "./publicReply.js";
+import { createCodexNativeAccess } from "./codexNativeAccess.js";
 const CODEX_PROXY_HANDSHAKE_TIMEOUT_MS = 10_000;
 /**
  * These Session implementations do not expose run-configuration observations.
@@ -297,7 +299,7 @@ class CodexProxyWebSocketChannel {
             return;
         }
         const id = requestId(message.id);
-        const pending = id === undefined ? undefined : this.#pending.get(id);
+        const pending = id === undefined || message.method !== undefined ? undefined : this.#pending.get(id);
         if (pending !== undefined) {
             clearTimeout(pending.timer);
             this.#pending.delete(id);
@@ -382,6 +384,7 @@ class CodexStructuredProviderSession {
     onActivity;
     mirror;
     nativeAccountHome;
+    nativeAccess;
     #turnAttempts = new Map();
     adapterId = "codex";
     #activeTurnId;
@@ -391,6 +394,7 @@ class CodexStructuredProviderSession {
     #bufferedStarts = [];
     #bufferedTerminals = [];
     #bufferedActivities = [];
+    publicReply;
     constructor(child, exit, processInstanceId, conversationId, runtime, onStarted, onTerminal, onGoal, onInput, onActivity, mirror, nativeAccountHome) {
         this.child = child;
         this.exit = exit;
@@ -412,13 +416,16 @@ class CodexStructuredProviderSession {
         await channel.notify("initialized");
         const runtime = new CodexAppServerRuntime(channel);
         let conversationId;
+        let nativeConfiguration;
         let resumedActiveTurnId;
         let resumedTurns = [];
         if (control.mode === "new") {
-            conversationId = (await runtime.openConversation({
+            const opened = await runtime.openConversation({
                 cwd: payload.cwd,
                 ...control.codexThread
-            })).conversationId;
+            });
+            conversationId = opened.conversationId;
+            nativeConfiguration = opened.raw;
         }
         else {
             try {
@@ -427,6 +434,7 @@ class CodexStructuredProviderSession {
                     ...control.codexThread
                 });
                 conversationId = resumed.threadId;
+                nativeConfiguration = resumed.raw;
                 resumedActiveTurnId = resumed.activeTurnId;
                 resumedTurns = resumed.turns;
             }
@@ -456,6 +464,7 @@ class CodexStructuredProviderSession {
             }
         }
         const session = new CodexStructuredProviderSession(child, exit, processInstanceId, conversationId, runtime, onStarted, onTerminal, onGoal, onInput, onActivity, mirror, optionalId(initialized.codexHome));
+        session.nativeAccess = createCodexNativeAccess(conversationId, initialized, channel, openingMessages, nativeConfiguration);
         session.#activeTurnId = resumedActiveTurnId;
         const ownedTurn = control.kind === "restore" ? control.ownedTurn : undefined;
         session.#clientOwnedTurnId = ownedTurn?.turnId;
@@ -514,6 +523,8 @@ class CodexStructuredProviderSession {
         const method = typeof message.method === "string" ? message.method : "";
         const params = object(message.params) ?? {};
         const threadId = optionalId(params.threadId);
+        if (emit)
+            this.publicReply = foldPublicReply(this.publicReply, this.conversationId, method, params);
         if (threadId !== this.conversationId) {
             if (threadId === undefined && (method === "turn/started" || method === "turn/completed")) {
                 this.mirror("stderr", `Codex protocol: ${method} has no thread identity; ignored.\n`);
@@ -630,11 +641,9 @@ class CodexStructuredProviderSession {
     get activeTurnId() {
         return this.#activeTurnId;
     }
-    /**
-     * This implementation has no run-configuration observation reader.
-     */
+    /** Last model confirmation from native start/resume, with its observation time. */
     get runConfiguration() {
-        return CODEX_RUN_CONFIGURATION;
+        return this.nativeAccess?.runConfiguration ?? CODEX_RUN_CONFIGURATION;
     }
     async submitTurn(turn) {
         if (this.#activeTurnId !== undefined) {

package/dist/runtime/taskCostMetrics.js

@@ -0,0 +1,133 @@
+/** No price catalog, currency conversion, token-to-money guess, or billing claim. */
+export function projectTaskCosts(observations, inScope, workItem, missingEvidence = []) {
+    const main = observations.filter(o => o.fence.nativeSessionId !== undefined
+        && o.fence.continuationId === undefined && o.fence.parentContinuationId === undefined
+        && (o.authority === "provider-structured" || o.authority === "driver-inferred"));
+    const resource = (o) => JSON.stringify([
+        o.fence.driverId, o.fence.nativeSessionId
+    ]);
+    const sessions = new Map();
+    for (const o of main)
+        sessions.set(resource(o), [...(sessions.get(resource(o)) ?? []), o]);
+    const project = (kind) => {
+        const evidence = [];
+        const reasons = [...missingEvidence];
+        if (observations.some(o => inScope(o) && o.payload.cost?.kind === kind
+            && (o.fence.continuationId !== undefined || o.fence.parentContinuationId !== undefined))) {
+            reasons.push("child-usage-overlap-unproven");
+        }
+        for (const all of sessions.values()) {
+            if (!all.some(inScope))
+                continue;
+            const costs = all.filter(o => o.payload.cost?.kind === kind);
+            if (costs.length === 0) {
+                reasons.push("cost-unobserved");
+                continue;
+            }
+            // Different native Roles and sources cannot safely claim independent charges.
+            const overlap = new Set(all.map(o => JSON.stringify([o.fence.roleName, o.fence.agentId]))).size > 1;
+            const latest = costs.at(-1);
+            const cost = latest.payload.cost;
+            // Missing receipts can carry only a coverage boundary, with no cost.
+            const local = qualityReasons(all.filter(o => inScope(o)
+                && (o.payload.cost === undefined || o.payload.cost.kind === kind)));
+            const semantics = new Set(costs.map(o => o.payload.cost.semantics));
+            if (overlap || semantics.size > 1) {
+                evidence.push(detail(latest, null, [...local,
+                    overlap ? "native-session-role-overlap" : "cost-source-overlap"]));
+                continue;
+            }
+            if (cost.semantics === "cumulative-session") {
+                let value = null;
+                if (new Set(costs.map(o => JSON.stringify([o.payload.cost.source, o.payload.cost.currency]))).size > 1) {
+                    local.push("cost-source-overlap");
+                }
+                else if (workItem)
+                    local.push("cumulative-not-allocatable-to-work-item");
+                else if (costs.some((o, i) => i > 0
+                    && o.payload.cost.amount < costs[i - 1].payload.cost.amount)) {
+                    local.push("cost-counter-rollback");
+                }
+                else if (new Set(costs.map(o => JSON.stringify(o.payload.cost.basis))).size > 1) {
+                    local.push("cost-basis-changed");
+                }
+                else {
+                    const baseline = costs[0].payload.cost.amount;
+                    if (baseline !== 0)
+                        local.push("nonzero-session-baseline");
+                    if (baseline === 0 || costs.length > 1)
+                        value = cost.amount - baseline;
+                }
+                evidence.push(detail(latest, value, [...local, ...qualityReasons(costs)]));
+                continue;
+            }
+            // Currency and price basis can change in a request revision. Resolve
+            // identity and attribution over every version before monetary grouping.
+            const requests = new Map();
+            for (const o of costs) {
+                const id = o.payload.activityId;
+                requests.set(id, [...(requests.get(id) ?? []), o]);
+            }
+            const bases = new Map();
+            for (const request of requests.values()) {
+                if (!request.some(inScope))
+                    continue;
+                const selected = request.at(-1);
+                const conflict = new Set(request.map(o => o.payload.cost.source)).size > 1
+                    ? "cost-source-overlap"
+                    : workItem && (!request.every(inScope) || new Set(request.map(o => o.fence.runId)).size !== 1)
+                        ? "request-run-attribution-conflict" : undefined;
+                if (conflict !== undefined) {
+                    evidence.push(detail(selected, null, [...local, conflict]));
+                    continue;
+                }
+                const selectedCost = selected.payload.cost;
+                const key = JSON.stringify([selectedCost.currency, selectedCost.source, selectedCost.basis]);
+                bases.set(key, [...(bases.get(key) ?? []), selected]);
+            }
+            for (const group of bases.values()) {
+                const subtotal = group.reduce((sum, o) => sum + o.payload.cost.amount, 0);
+                evidence.push(detail(group.at(-1), safeAmount(subtotal), [...local, ...qualityReasons(group)]));
+            }
+        }
+        if (evidence.length === 0)
+            reasons.push(kind === "estimated" ? "price-unavailable" : "cost-unobserved");
+        reasons.push(...evidence.flatMap(e => e.amount.reasons));
+        const amounts = [...new Set(evidence.map(e => e.currency))].sort().flatMap(currency => {
+            const known = evidence.filter(e => e.currency === currency && e.amount.value !== null);
+            return known.length === 0 ? [] : [{
+                    ...metric(safeAmount(known.reduce((sum, e) => sum + e.amount.value, 0)), reasons), currency
+                }];
+        });
+        return {
+            status: amounts.length === 0 ? "unknown" : reasons.length ? "partial" : "known",
+            amounts, reasons: [...new Set(reasons)].sort(), evidence
+        };
+    };
+    return { scope: "observed-sources-only", actual: project("actual"), estimated: project("estimated") };
+}
+function qualityReasons(observations) {
+    return [
+        ...(observations.some(o => o.payload.observationQuality === "partial"
+            || o.payload.observationQuality === "unavailable") ? ["source-coverage-partial"] : []),
+        ...(observations.some(o => (o.payload.cost?.basis?.excluded.length ?? 0) > 0)
+            ? ["estimate-exclusions"] : [])
+    ];
+}
+function detail(o, value, reasons) {
+    const cost = o.payload.cost;
+    return {
+        nativeSessionId: o.fence.nativeSessionId, roleName: o.fence.roleName,
+        agentId: o.fence.agentId, driverId: o.fence.driverId,
+        source: cost.source, currency: cost.currency, semantics: cost.semantics,
+        ...(cost.basis === undefined ? {} : { basis: cost.basis }),
+        amount: metric(value, reasons)
+    };
+}
+function safeAmount(value) {
+    return Number.isFinite(value) && value >= 0 && value <= Number.MAX_SAFE_INTEGER ? value : null;
+}
+function metric(value, reasons) {
+    return { value, status: value === null ? "unknown" : reasons.length ? "partial" : "known",
+        reasons: [...new Set(reasons)].sort() };
+}