@adonis-agora/agent 0.92.0 → 0.94.0

package/dist/src/agent-loop.js

@@ -1,7 +1,10 @@
 import { turnChannel } from './genui/channels.js';
 import { GenuiTurnTelemetry, observeGenuiFrames } from './genui-telemetry.js';
 import { DEFAULT_REFUSAL_REASON } from './refusal.js';
+import { rollupRunTimings, toolsWallClockMs } from './run-timings.js';
 import { observeFirstText } from './turn-timing.js';
+import { usageAttribution } from './usage-attribution.js';
+import { recordUsageRow } from './usage-ledger.js';
 export { DEFAULT_REFUSAL_REASON } from './refusal.js';
 import { createHash } from 'node:crypto';
 import { resolveActionProposalApproval } from './action-proposal-approval.js';
@@ -9,7 +12,7 @@ import { prepareActionProposal } from './action-proposal-preparation.js';
 import { actionProposalReceipt } from './action-proposal-receipt.js';
 import { danglingToolCallIds, settleDanglingToolCalls } from './dangling-tool-calls.js';
 import { detachedDelivered, detachedStarted, } from './delegation.js';
-import { publishAgentDelegated, publishAgentMessage, publishAgentRetrieved, publishAgentRunCancelled, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentToolCall, publishAgentToolRetry, spannedAgent, } from './diagnostics.js';
+import { publishAgentDelegated, publishAgentMessage, publishAgentRetrieved, publishAgentRunCancelled, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentToolCall, publishAgentToolRetry, spannedAgent, timedSpan, } from './diagnostics.js';
 import { ASK_TOOL_NAME, askInputSchema, askToolDefinition, DEFAULT_INTAKE_PREAMBLE, isHumanDecision, normalizeElicitationReply, settleElicitation, } from './elicitation.js';
 import { renderHistorySummary } from './history-window.js';
 import { buildMemoryBlock, offerMemories, REMEMBER_TOOL_NAME, rememberInputSchema, rememberToolDefinition, writeMemory, } from './memory.js';
@@ -512,8 +515,9 @@ async function applyHistoryWindow(window, deps, input, hooks, messages, step) {
     const summary = await step('history:summarize', () => summarize(drop, ctx));
     if (summary.usage !== undefined) {
         const usage = summary.usage;
-        await step('persist:usage:history', () => deps.store.recordUsage({
+        await step('persist:usage:history', () => recordUsageRow(deps.store, {
             threadId: input.threadId,
+            ...usageAttribution(input),
             actorRef: input.actor.id,
             runId: hooks.runId,
             modelId: summary.modelId ?? deps.modelId ?? 'unknown',
@@ -727,6 +731,26 @@ const PARALLEL_TOOLS_PATCH = 'agent:parallel-tools';
  * supply.
  */
 const MESSAGE_TOOL_RESULTS_PATCH = 'agent:message-tool-results';
+/** Note a settled call's journaled execution window on its step. */
+function noteToolTiming(turn, call, journaled) {
+    if (turn.toolTimings === undefined || journaled === undefined || journaled === null)
+        return;
+    if (typeof journaled.ms !== 'number')
+        return;
+    turn.toolTimings.push({
+        toolCallId: call.id,
+        toolName: call.name,
+        ms: journaled.ms,
+        ...(typeof journaled.at === 'number' ? { at: journaled.at } : {}),
+    });
+}
+/** The execution window a persist checkpoint journals, from the outcome measured in this process. */
+function journalTiming(outcome) {
+    return {
+        ...(outcome.durationMs !== undefined ? { ms: outcome.durationMs } : {}),
+        ...(outcome.startedAt !== undefined ? { at: outcome.startedAt } : {}),
+    };
+}
 /**
  * Record the call and settle its KIND, which decides this call's control flow: an `action` suspends
  * the run on an approval signal (`tool:<runId>:<callId>`), an `agent` delegates to a child run,
@@ -1065,7 +1089,7 @@ async function invokeClaimedTool(turn, claimed, presentationOnly) {
     const invokeOptions = allowedTools === undefined ? {} : { allowedTools };
     // Set only when the step's body runs here: a checkpoint read back from the journal has no timing.
     let ranAt;
-    const timing = () => ranAt === undefined ? { replayed: true } : { durationMs: Date.now() - ranAt };
+    const timing = () => ranAt === undefined ? { replayed: true } : { durationMs: Date.now() - ranAt, startedAt: ranAt };
     try {
         const raw = await hooks.step(`tool:${call.id}`, async () => {
             ranAt = Date.now();
@@ -1226,7 +1250,7 @@ async function recordToolOutcome(turn, claimed, outcome, deciderRef = turn.input
         });
     };
     if (outcome.status === 'failed') {
-        await hooks.step(`persist:toolfail:${call.id}`, async () => {
+        const journaled = await hooks.step(`persist:toolfail:${call.id}`, async () => {
             await deps.store.updateToolCall({
                 toolCallId: call.id,
                 runId: hooks.runId,
@@ -1236,7 +1260,10 @@ async function recordToolOutcome(turn, claimed, outcome, deciderRef = turn.input
                 ...decided,
             });
             await settle();
+            // Journaled with the checkpoint that records it, so a replay counts the call's time once.
+            return journalTiming(outcome);
         });
+        noteToolTiming(turn, call, journaled);
         publishAgentToolCall({
             runId: hooks.runId,
             toolCallId: call.id,
@@ -1253,7 +1280,7 @@ async function recordToolOutcome(turn, claimed, outcome, deciderRef = turn.input
             ...(outcome.denied ? { denied: true } : {}),
         };
     }
-    await hooks.step(`persist:toolexec:${call.id}`, async () => {
+    const journaled = await hooks.step(`persist:toolexec:${call.id}`, async () => {
         await deps.store.updateToolCall({
             toolCallId: call.id,
             runId: hooks.runId,
@@ -1264,7 +1291,10 @@ async function recordToolOutcome(turn, claimed, outcome, deciderRef = turn.input
             ...decided,
         });
         await settle();
+        // Journaled with the checkpoint that records it, so a replay counts the call's time once.
+        return journalTiming(outcome);
     });
+    noteToolTiming(turn, call, journaled);
     publishAgentToolCall({
         runId: hooks.runId,
         toolCallId: call.id,
@@ -1906,8 +1936,9 @@ async function structureAnswer(args) {
                 ...(turn.modelId !== undefined ? { modelId: turn.modelId } : {}),
             };
         });
-        await hooks.step(`persist:usage:structured:${step}:${attempt}`, () => deps.store.recordUsage({
+        await hooks.step(`persist:usage:structured:${step}:${attempt}`, () => recordUsageRow(deps.store, {
             threadId: input.threadId,
+            ...usageAttribution(input),
             actorRef: input.actor.id,
             runId: hooks.runId,
             modelId: reply.modelId ?? deps.modelId ?? 'unknown',
@@ -2077,14 +2108,29 @@ export function streamErrorFrame(error, runId) {
  */
 export async function runAgentLoop(boundDeps, requested, hooks) {
     const startedAt = Date.now();
+    const clock = {};
     try {
-        return await runAgentTurn(boundDeps, requested, hooks);
+        return await runAgentTurn(boundDeps, requested, hooks, clock);
     }
     catch (error) {
-        publishRunEnded(error, requested, hooks, startedAt);
+        publishRunEnded(error, requested, hooks, startedAt, clock);
         throw error;
     }
 }
+/** The queue time the runner reports, rounded; `undefined` when it has none (or it fails). */
+async function readQueueMs(hooks) {
+    if (hooks.queueMs === undefined)
+        return undefined;
+    try {
+        const value = await hooks.queueMs();
+        return typeof value === 'number' && Number.isFinite(value)
+            ? Math.max(0, Math.round(value))
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Who and what the run is, for its terminal diagnostics. */
 function runContext(input) {
     return {
@@ -2102,22 +2148,36 @@ function runContext(input) {
  * nothing; a run whose abort signal fired was stopped; anything else failed, under the same code the
  * stream's `error` frame carries.
  */
-function publishRunEnded(error, input, hooks, startedAt) {
+function publishRunEnded(error, input, hooks, startedAt, clock) {
     if (!isReplayIntegrityError(error) && hooks.isControlFlowError?.(error) === true)
         return;
     const base = {
         runId: hooks.runId,
         threadId: input.threadId,
         durationMs: Date.now() - startedAt,
+        ...(clock.queueMs !== undefined ? { queueMs: clock.queueMs } : {}),
         ...runContext(input),
     };
     if (hooks.abortSignal?.aborted === true) {
         publishAgentRunCancelled(base);
         return;
     }
-    publishAgentRunFailed({ ...base, code: streamErrorCode(error) });
+    const timings = clock.steps !== undefined ? rollupRunTimings(clock.steps) : undefined;
+    publishAgentRunFailed({
+        ...base,
+        code: streamErrorCode(error),
+        ...(timings !== undefined
+            ? {
+                modelMs: timings.modelMs,
+                toolsMs: timings.toolsMs,
+                modelCalls: timings.modelCalls,
+                toolCalls: timings.toolCalls,
+                stepTimings: timings.steps,
+            }
+            : {}),
+    });
 }
-async function runAgentTurn(boundDeps, requested, hooks) {
+async function runAgentTurn(boundDeps, requested, hooks, clock) {
     // The persona, FIRST and only when the run names one by id: its definition is read from config
     // once and frozen in this checkpoint, so a run resumed after the persona was edited or removed
     // keeps the prompt and allow-list it started with. A run that names none spends no position here
@@ -2177,14 +2237,28 @@ async function runAgentTurn(boundDeps, requested, hooks) {
     // Open the run (turn) row FIRST — before the quota gate — so even a quota-rejected run is tracked
     // (the runner settles it `failed`). A checkpointed step so a durable replay reuses the ONE row (no
     // duplicate on resume); `run_id` is then stamped onto every message / tool call / usage row below.
-    await hooks.step('persist:run:start', () => deps.store.recordRunStart({
-        runId: hooks.runId,
-        threadId: input.threadId,
-        actor: input.actor,
-        durable: hooks.durable ?? false,
-        ...(input.agentName !== undefined ? { agentName: input.agentName } : {}),
-        ...(input.parentRunId !== undefined ? { parentRunId: input.parentRunId } : {}),
-    }));
+    //
+    // The run's queue time is read INSIDE this checkpoint and journaled with it: the body runs once per
+    // slice of a durable run, and only the first execution of this step is the moment it left the queue.
+    const opened = await hooks.step('persist:run:start', async () => {
+        const queueMs = await readQueueMs(hooks);
+        await deps.store.recordRunStart({
+            runId: hooks.runId,
+            threadId: input.threadId,
+            actor: input.actor,
+            durable: hooks.durable ?? false,
+            ...(input.agentName !== undefined ? { agentName: input.agentName } : {}),
+            ...(input.parentRunId !== undefined ? { parentRunId: input.parentRunId } : {}),
+            ...(queueMs !== undefined ? { queueMs } : {}),
+        });
+        return queueMs !== undefined ? { queueMs } : {};
+    });
+    if (typeof opened === 'object' && opened !== null && typeof opened.queueMs === 'number') {
+        clock.queueMs = opened.queueMs;
+    }
+    // Where each step's time went, filled as the steps run (or replay from their checkpoints).
+    const stepTimings = [];
+    clock.steps = stepTimings;
     if (deps.quota !== undefined) {
         const quota = deps.quota;
         const state = await hooks.step('quota:check', () => quota.check(input.actor.id, deps.day));
@@ -2351,8 +2425,9 @@ async function runAgentTurn(boundDeps, requested, hooks) {
         // placeholder faria a linha parecer precificável e sair como $0.00 — pior do que a ausência.
         if (retrieved.usage !== undefined && retrieved.usage.inputTokens > 0) {
             const embeddingUsage = retrieved.usage;
-            await hooks.step('persist:usage:embedding', () => deps.store.recordUsage({
+            await hooks.step('persist:usage:embedding', () => recordUsageRow(deps.store, {
                 threadId: input.threadId,
+                ...usageAttribution(input),
                 actorRef: input.actor.id,
                 runId: hooks.runId,
                 modelId: embeddingUsage.modelId ?? 'unknown',
@@ -2457,72 +2532,86 @@ async function runAgentTurn(boundDeps, requested, hooks) {
         // Stamped from THIS process's registry, which is the one that built `tools` for the call above —
         // and stamped INSIDE the checkpoint, so the kinds are journaled with the calls they describe
         // rather than re-derived by whatever process replays this turn.
-        let turn = await hooks.step(`llm:${i}`, async () => stampToolKinds(await spannedAgent('llm.turn', hooks.runId, { runId: hooks.runId, step: i }, async () => {
-            const incremental = gateMode === 'incremental'
-                ? createIncrementalGate({
-                    processors: outputProcessors,
-                    ctx: processorContext(i),
-                    lookbackChars: gateLookback,
-                    writer,
-                })
-                : undefined;
-            const buffer = gateMode === 'whole' ? createFrameBuffer() : undefined;
-            // Written from inside this checkpoint, like every frame the model streams, so a replay
-            // that returns the journaled turn never opens the step twice.
-            await writer.write({ t: 'event', event: { kind: 'step-start' } });
-            const announced = announcedToolCalls(incremental?.writer ?? buffer?.writer ?? writer);
-            // A tool that previews its input (genui's streaming tree) gets partial `ui` frames
-            // while the model writes its arguments. Added BELOW the observer: a preview is shown,
-            // never part of what the turn persists.
-            const previews = previewToolInputs(announced.writer, async (name, toolCallId) => tools.some((definition) => definition.name === name)
-                ? deps.registry.previewInput(name, {
-                    actor: input.actor,
-                    threadId: input.threadId,
-                    toolCallId,
-                    ...(input.agentName !== undefined ? { agentName: input.agentName } : {}),
-                    ...(input.uiCapabilities !== undefined
-                        ? { uiCapabilities: input.uiCapabilities }
-                        : {}),
-                    channel: turnChannel(input.pageContext),
-                })
-                : undefined);
-            // Reasoning and pushed UI are read off the frames INSIDE this checkpoint, so they are
-            // journaled with the turn and a replay persists the same thinking instead of none.
-            const frames = observeTurnFrames(previews.writer);
-            const result = withTurnFrames(await abortableModelCall(hooks, (signal) => deps.model.runTurn({
-                system: prompt.system,
-                messages: prompt.messages,
-                tools,
-                sink: frames.writer,
-                ...signal,
-            })), frames.summary());
-            // A provider that streams no tool frames still gets its calls announced — an outcome
-            // for a call the client never saw announced drops the whole message there.
-            await announced.announceRest(result.toolCalls, tools);
-            // Journaled with the turn, so whichever process settles the calls withdraws the same
-            // previews the stream showed.
-            const shownPreviews = previews.shown();
-            const previewed = shownPreviews.length > 0 ? { previews: shownPreviews } : {};
-            if (incremental !== undefined) {
-                await incremental.settled();
-                const refusal = incremental.rejection();
-                return {
-                    ...result,
-                    ...previewed,
-                    releasedText: incremental.released(),
-                    ...(refusal !== undefined ? { gateRejection: refusal } : {}),
-                };
-            }
-            return buffer === undefined
-                ? { ...result, ...previewed }
-                : { ...result, ...previewed, bufferedFrames: buffer.frames() };
-        }, (result) => ({
-            ...(result.modelId !== undefined ? { modelId: result.modelId } : {}),
-            inputTokens: result.usage.inputTokens,
-            outputTokens: result.usage.outputTokens,
-            textLength: result.text.length,
-            toolCalls: result.toolCalls.length,
-        })), { ...deps, actionApprovalMode: thread.actionApprovalMode ?? 'blocking' }, input, hooks));
+        let turn = await hooks.step(`llm:${i}`, async () => {
+            const timed = await timedSpan('llm.turn', hooks.runId, { runId: hooks.runId, step: i }, async () => {
+                const incremental = gateMode === 'incremental'
+                    ? createIncrementalGate({
+                        processors: outputProcessors,
+                        ctx: processorContext(i),
+                        lookbackChars: gateLookback,
+                        writer,
+                    })
+                    : undefined;
+                const buffer = gateMode === 'whole' ? createFrameBuffer() : undefined;
+                // Written from inside this checkpoint, like every frame the model streams, so a replay
+                // that returns the journaled turn never opens the step twice.
+                await writer.write({ t: 'event', event: { kind: 'step-start' } });
+                const announced = announcedToolCalls(incremental?.writer ?? buffer?.writer ?? writer);
+                // A tool that previews its input (genui's streaming tree) gets partial `ui` frames
+                // while the model writes its arguments. Added BELOW the observer: a preview is shown,
+                // never part of what the turn persists.
+                const previews = previewToolInputs(announced.writer, async (name, toolCallId) => tools.some((definition) => definition.name === name)
+                    ? deps.registry.previewInput(name, {
+                        actor: input.actor,
+                        threadId: input.threadId,
+                        toolCallId,
+                        ...(input.agentName !== undefined ? { agentName: input.agentName } : {}),
+                        ...(input.uiCapabilities !== undefined
+                            ? { uiCapabilities: input.uiCapabilities }
+                            : {}),
+                        channel: turnChannel(input.pageContext),
+                    })
+                    : undefined);
+                // Reasoning and pushed UI are read off the frames INSIDE this checkpoint, so they are
+                // journaled with the turn and a replay persists the same thinking instead of none.
+                const frames = observeTurnFrames(previews.writer);
+                const result = withTurnFrames(await abortableModelCall(hooks, (signal) => deps.model.runTurn({
+                    system: prompt.system,
+                    messages: prompt.messages,
+                    tools,
+                    sink: frames.writer,
+                    ...signal,
+                })), frames.summary());
+                // A provider that streams no tool frames still gets its calls announced — an outcome
+                // for a call the client never saw announced drops the whole message there.
+                await announced.announceRest(result.toolCalls, tools);
+                // Journaled with the turn, so whichever process settles the calls withdraws the same
+                // previews the stream showed.
+                const shownPreviews = previews.shown();
+                const previewed = shownPreviews.length > 0 ? { previews: shownPreviews } : {};
+                if (incremental !== undefined) {
+                    await incremental.settled();
+                    const refusal = incremental.rejection();
+                    return {
+                        ...result,
+                        ...previewed,
+                        releasedText: incremental.released(),
+                        ...(refusal !== undefined ? { gateRejection: refusal } : {}),
+                    };
+                }
+                return buffer === undefined
+                    ? { ...result, ...previewed }
+                    : { ...result, ...previewed, bufferedFrames: buffer.frames() };
+            }, (result) => ({
+                ...(result.modelId !== undefined ? { modelId: result.modelId } : {}),
+                inputTokens: result.usage.inputTokens,
+                outputTokens: result.usage.outputTokens,
+                textLength: result.text.length,
+                toolCalls: result.toolCalls.length,
+            }));
+            // The span's own duration rides the journaled turn, so a replay counts the call once.
+            return {
+                ...(await stampToolKinds(timed.value, { ...deps, actionApprovalMode: thread.actionApprovalMode ?? 'blocking' }, input, hooks)),
+                modelMs: Math.round(timed.durationMs),
+            };
+        });
+        const stepTiming = {
+            step: i,
+            ...(typeof turn.modelMs === 'number' ? { modelMs: turn.modelMs } : {}),
+            tools: [],
+            toolsMs: 0,
+        };
+        stepTimings.push(stepTiming);
         // The gate runs before ANYTHING downstream: before the held frames reach the subscriber, before
         // the assistant message is persisted, before this text becomes the next step's context.
         let rejection;
@@ -2576,8 +2665,9 @@ async function runAgentTurn(boundDeps, requested, hooks) {
         // `resolveModelPrice` e não `priceByModel.get`: o provider responde com o snapshot datado
         // (`gpt-4o-mini-2024-07-18`) e o operador precifica o alias (`gpt-4o-mini`). Ver o helper.
         const costUsd = resolveCostUsd(turn.usage, turn.costUsd, resolveModelPrice(priceByModel, resolvedModelId));
-        await hooks.step(`persist:usage:${i}`, () => deps.store.recordUsage({
+        await hooks.step(`persist:usage:${i}`, () => recordUsageRow(deps.store, {
             threadId: input.threadId,
+            ...usageAttribution(input),
             actorRef: input.actor.id,
             runId: hooks.runId,
             modelId: resolvedModelId,
@@ -2772,6 +2862,7 @@ async function runAgentTurn(boundDeps, requested, hooks) {
             actionApprovalMode: thread.actionApprovalMode ?? 'blocking',
             ...(skillOffer !== undefined ? { skills: skillOffer } : {}),
             ...(memoryDigest !== undefined ? { memory: memoryDigest } : {}),
+            toolTimings: [],
         };
         // A model routinely asks for several tools at once, and running them back to back makes the
         // turn cost their sum. Overlapping them is safe here because a checkpoint position is handed
@@ -2817,6 +2908,16 @@ async function runAgentTurn(boundDeps, requested, hooks) {
                 results.push(await runClaimedToolCall(turnCalls, await claimToolCall(turnCalls, call)));
             }
         }
+        // Settled, in call order: the step's tool time, parallel calls counted once.
+        const ranTools = turnCalls.toolTimings ?? [];
+        const order = new Map(turn.toolCalls.map((call, index) => [call.id, index]));
+        ranTools.sort((left, right) => (order.get(left.toolCallId) ?? 0) - (order.get(right.toolCallId) ?? 0));
+        stepTiming.tools = ranTools.map((entry) => ({
+            toolCallId: entry.toolCallId,
+            toolName: entry.toolName,
+            ms: entry.ms,
+        }));
+        stepTiming.toolsMs = toolsWallClockMs(ranTools);
         // The outputs land on the assistant message that made the calls. A reader reopening the thread
         // pairs a call with its result off THAT message, so results that only reached the tool-call
         // table leave every tool in the turn rendering as one still running.
@@ -2956,6 +3057,7 @@ async function runAgentTurn(boundDeps, requested, hooks) {
     }
     // Every text frame of the turn has gone out by now, so its time to first token is known.
     const firstTextAt = firstText.firstTextAt();
+    const timings = rollupRunTimings(stepTimings);
     // Settle the run `completed` with its rollup. Normal completion only — the loop never records a
     // failure (it doesn't catch its own crash; that's the runner's job). A checkpointed step so a
     // resumed durable replay settles the ONE row exactly once, and `recordRunEnd` is first-terminal so
@@ -2970,6 +3072,7 @@ async function runAgentTurn(boundDeps, requested, hooks) {
         ...(hasCost ? { costUsd: totalCost } : {}),
         ...(firstTextAt !== undefined ? { ttftMs: firstTextAt - turnStartedAt } : {}),
         ...(lastModelId !== undefined ? { modelId: lastModelId } : {}),
+        timings,
     }));
     await writer.end();
     publishAgentRunFinished({
@@ -2982,6 +3085,12 @@ async function runAgentTurn(boundDeps, requested, hooks) {
         ...(firstTextAt !== undefined ? { ttftMs: firstTextAt - turnStartedAt } : {}),
         ...(hasCost ? { costUsd: totalCost } : {}),
         ...(lastModelId !== undefined ? { modelId: lastModelId } : {}),
+        ...(clock.queueMs !== undefined ? { queueMs: clock.queueMs } : {}),
+        modelMs: timings.modelMs,
+        toolsMs: timings.toolsMs,
+        modelCalls: timings.modelCalls,
+        toolCalls: timings.toolCalls,
+        stepTimings: timings.steps,
         ...runContext(input),
     });
     return { text: lastText, ...(structured !== undefined ? { object: structured } : {}) };