broapp 0.4.3 → 0.4.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "broapp",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "type": "module",
   "description": "Build tooling and runtime for local applications made of a Bun host, a browser UI, and a Brobridge connection between them",
   "license": "MIT",

package/src/ai/host/create-ai.ts

@@ -39,6 +39,8 @@ export interface RunEndDetail {
   /** Tool round trips the turn made. */
   readonly steps: number;
   readonly ms: number;
+  /** The model the turn was sent to; absent when the turn ended before one was resolved. */
+  readonly modelId?: string;
 }
 
 /**
@@ -165,6 +167,13 @@ export interface CreateAiOptions {
    * reason to fail it.
    */
   readonly onContext?: (runId: string, delivered: DeliveredContext) => void;
+  /**
+   * Called after each completed model step of a turn, with the tokens its
+   * completed steps have used so far: what a running turn has cost, before
+   * `onRunEnd` says what it cost in all. A hook that throws is logged and
+   * ignored, like the others.
+   */
+  readonly onUsageSoFar?: (runId: string, soFar: { inputTokens: number; outputTokens: number }) => void;
 }
 
 /**
@@ -334,6 +343,7 @@ export function createAi(options: CreateAiOptions): Ai {
     approvals,
     ...(options.onRunEnd === undefined ? {} : { onRunEnd: options.onRunEnd }),
     ...(options.onContext === undefined ? {} : { onContext: options.onContext }),
+    ...(options.onUsageSoFar === undefined ? {} : { onUsageSoFar: options.onUsageSoFar }),
     transcripts: {
       save: (runId, messages) => {
         threadStore().saveTranscript(runId, messages);

package/src/ai/host/run.ts

@@ -75,6 +75,13 @@ export interface RunDeps {
   ) => void;
   /** Called once per turn with what the model is about to be given. */
   readonly onContext?: (runId: string, delivered: DeliveredContext) => void;
+  /**
+   * Called after each model step completes, with what the turn's completed
+   * steps have used so far. Not the SDK's `onStepEnd`, which this layer
+   * already hands to `streamText`: this is the turn's running subtotal, for
+   * somebody who wants to say what a turn has cost before it ends.
+   */
+  readonly onUsageSoFar?: (runId: string, soFar: { inputTokens: number; outputTokens: number }) => void;
   /**
    * The turn transcripts. Absent, every history turn is text and nothing is
    * written, which is exactly the layer before transcripts existed.
@@ -85,7 +92,31 @@ export interface RunDeps {
 /** What a turn counts as it goes, for {@link RunEndDetail}. */
 interface TurnTally {
   steps: number;
-  usage?: { inputTokens: number; outputTokens: number };
+  /**
+   * The turn's usage. The SDK's total when the turn reached `finish`;
+   * otherwise the sum of the steps that completed, marked `partial`, because
+   * the step in flight when it stopped used tokens nobody reported.
+   */
+  usage?: { inputTokens: number; outputTokens: number; partial?: true };
+  /** Model steps that completed, and what they reported, added as each ends. */
+  stepsEnded: number;
+  stepInput: number;
+  stepOutput: number;
+  /** The model the turn was sent to, once it is resolved. */
+  modelId?: string;
+}
+
+/**
+ * What the completed steps of a turn that did not finish add up to, or
+ * nothing when no step completed.
+ *
+ * A turn cut short by a time limit, a stop or an error never sees `finish`,
+ * and so never sees the total. Counting it as zero made a turn that ran for
+ * twenty minutes look free; this is what is known, and says it is not all.
+ */
+function partialUsage(tally: TurnTally): TurnTally['usage'] {
+  if (tally.stepsEnded === 0) return undefined;
+  return { inputTokens: tally.stepInput, outputTokens: tally.stepOutput, partial: true };
 }
 
 /**
@@ -311,6 +342,85 @@ function boundMessage(message: ResponseMessage, limits: HistoryLimits): ModelMes
   return { ...message, content } as ModelMessage;
 }
 
+/** The line a partial turn opens with, saying how many of its calls are not there. */
+function omittedMarker(calls: number): string {
+  return `[${String(calls)} earlier tool calls of this turn are not shown]`;
+}
+
+/** The tool-call ids an assistant message makes, or the tool-result ids a tool message answers. */
+function partIds(message: ModelMessage, type: 'tool-call' | 'tool-result'): string[] {
+  if (!Array.isArray(message.content)) return [];
+  return (message.content as readonly unknown[])
+    .filter((part): part is { type: string; toolCallId: string } => isRecord(part) && part['type'] === type && typeof part['toolCallId'] === 'string')
+    .map((part) => part.toolCallId);
+}
+
+/**
+ * A transcript cut into groups: each assistant message with the tool messages
+ * that answer it. A group is complete when every call it makes has a result
+ * in it and every result answers one of its calls; `null` marks a group that
+ * is not, which no suffix may reach past.
+ */
+function groupsOf(messages: readonly ModelMessage[]): ({ messages: ModelMessage[]; calls: number } | null)[] {
+  const groups: { messages: ModelMessage[] }[] = [];
+  for (const message of messages) {
+    if (message.role === 'assistant') groups.push({ messages: [message] });
+    else {
+      const current = groups[groups.length - 1];
+      // A result with no assistant before it answers nothing that is kept.
+      if (current === undefined) groups.push({ messages: [message] });
+      else current.messages.push(message);
+    }
+  }
+  return groups.map((group) => {
+    const [head, ...answers] = group.messages;
+    if (head === undefined || head.role !== 'assistant') return null;
+    const calls = partIds(head, 'tool-call');
+    const results = answers.flatMap((message) => (message.role === 'tool' ? partIds(message, 'tool-result') : [null]));
+    const answered = new Set(results);
+    const complete =
+      results.length === calls.length && calls.every((id) => answered.has(id)) && results.every((id) => id !== null && calls.includes(id));
+    return complete ? { messages: group.messages, calls: calls.length } : null;
+  });
+}
+
+/** The first assistant message of a suffix, opening with the marker as its first text part. */
+function withMarker(messages: readonly ModelMessage[], marker: string): ModelMessage[] {
+  const [first, ...rest] = messages;
+  if (first === undefined || first.role !== 'assistant') return [...messages];
+  const text = { type: 'text' as const, text: marker };
+  const content = typeof first.content === 'string' ? [text, { type: 'text' as const, text: first.content }] : [text, ...first.content];
+  return [{ ...first, content } as ModelMessage, ...rest];
+}
+
+/**
+ * The newest complete groups of a turn too long to expand whole, or `null`
+ * when not even its closing words and one group with a call fit in `room`.
+ *
+ * Kept newest first, whole groups only, so a call never arrives without its
+ * result or a result without its call. The first kept assistant message says
+ * how many earlier calls are not shown, and the marker counts toward `room`.
+ */
+function newestGroups(bounded: readonly ModelMessage[], room: number): ModelMessage[] | null {
+  const groups = groupsOf(bounded);
+  const totalCalls = groups.reduce((sum, group) => sum + (group?.calls ?? 0), 0);
+  let best: ModelMessage[] | null = null;
+  let kept: ModelMessage[] = [];
+  let keptCalls = 0;
+  for (let index = groups.length - 1; index >= 0; index -= 1) {
+    const group = groups[index];
+    if (group === null || group === undefined) break;
+    kept = [...group.messages, ...kept];
+    keptCalls += group.calls;
+    // The closing words alone are not worth a partial turn: it needs a call.
+    if (keptCalls === 0) continue;
+    const candidate = withMarker(kept, omittedMarker(totalCalls - keptCalls));
+    if (JSON.stringify(candidate).length > room) break;
+    best = candidate;
+  }
+  return best;
+}
+
 /**
  * History as the model is given it.
  *
@@ -318,8 +428,13 @@ function boundMessage(message: ResponseMessage, limits: HistoryLimits): ModelMes
  * transcript the host holds is replaced by that transcript — its own tool calls
  * and results, bounded — while fewer than `limits.turns` have been and the total
  * stays under `limits.totalChars`. The first turn that would cross the total
- * stays text, and so does every turn older than it. Every other turn is its text,
- * exactly as before. User turns keep their place.
+ * gives its newest complete calls instead, as many as fit what is left, under a
+ * line saying how many earlier ones are not shown; if not even one call and its
+ * result fit, it stays text. Either way it is the last turn expanded, and every
+ * turn older than it is text. 12j expanded a turn whole or not at all, and
+ * measured that a turn of twenty calls or so is 60,000 to 145,000 characters
+ * after bounds: the long turns were exactly the ones that came back as words.
+ * Every other turn is its text, exactly as before. User turns keep their place.
  */
 export function expandHistory(
   history: readonly ChatTurn[],
@@ -347,7 +462,14 @@ export function expandHistory(
     const chars = JSON.stringify(bounded).length;
     if (total + chars > limits.totalChars) {
       full = true;
-      segments.push(text);
+      const partial = newestGroups(bounded, limits.totalChars - total);
+      if (partial === null) {
+        segments.push(text);
+        continue;
+      }
+      total += JSON.stringify(partial).length;
+      expanded += 1;
+      segments.push(partial);
       continue;
     }
     total += chars;
@@ -661,7 +783,7 @@ export async function runChat(
   // or a run store is left with something that looks like it is still running.
   let ended = false;
   const started = Date.now();
-  const tally: TurnTally = { steps: 0 };
+  const tally: TurnTally = { steps: 0, stepsEnded: 0, stepInput: 0, stepOutput: 0 };
   const recorder = new TranscriptRecorder();
   const transcript = new TranscriptWriter(params.runId, deps);
   // A turn that never reaches `finish` — stopped, failed, or cut off by the
@@ -677,12 +799,15 @@ export async function runChat(
   const end = (status: 'succeeded' | 'failed' | 'cancelled'): void => {
     if (ended) return;
     ended = true;
+    // A turn that never reached `finish` still leaves its record what it knows.
+    tally.usage ??= partialUsage(tally);
     const onRunEnd = deps.onRunEnd;
     if (onRunEnd === undefined) return;
     const detail: RunEndDetail = {
       steps: tally.steps,
       ms: Date.now() - started,
       ...(tally.usage === undefined ? {} : { usage: tally.usage }),
+      ...(tally.modelId === undefined ? {} : { modelId: tally.modelId }),
     };
     safely(deps.logger, 'onRunEnd', () =>
       onRunEnd(params.runId, status, params.message.slice(0, SUMMARY_CHARS), detail),
@@ -745,6 +870,9 @@ async function runTurn(
   // after the provider and key checks, so the vision check below and the model
   // instance built later both follow it without a second code path.
   const resolved = await deps.registry.resolve({ modelId: params.modelId });
+  // Known here and nowhere later: a listener writing down what the turn used
+  // is told which model used it, not left to guess from settings since changed.
+  tally.modelId = resolved.modelId;
 
   // Both checks come before anything is emitted, so a turn that cannot carry
   // its images fails as a whole rather than half-answering.
@@ -808,11 +936,27 @@ async function runTurn(
     onChunk: ({ chunk }) => {
       if (chunk.type === 'text-delta') recorder.wrote(chunk.text);
     },
-    onStepEnd: (step) => recorder.stepEnded(step.response.messages),
+    onStepEnd: (step) => {
+      recorder.stepEnded(step.response.messages);
+      // Per step, as the step ends: the only usage a turn that does not reach
+      // `finish` will ever have.
+      tally.stepsEnded += 1;
+      tally.stepInput += step.usage.inputTokens ?? 0;
+      tally.stepOutput += step.usage.outputTokens ?? 0;
+      const onUsageSoFar = deps.onUsageSoFar;
+      if (onUsageSoFar !== undefined) {
+        const soFar = { inputTokens: tally.stepInput, outputTokens: tally.stepOutput };
+        safely(deps.logger, 'onUsageSoFar', () => onUsageSoFar(params.runId, soFar));
+      }
+    },
   });
 
   for await (const part of result.fullStream) {
-    if (sink.signal.aborted) return;
+    // Stopped: the sink is closed, so the subtotal goes to the run record only.
+    if (sink.signal.aborted) {
+      tally.usage ??= partialUsage(tally);
+      return;
+    }
     switch (part.type) {
       case 'text-delta':
         await sink.emit({ type: 'text', text: part.text });
@@ -837,7 +981,14 @@ async function runTurn(
         await sink.emit({ type: 'done' });
         break;
       }
-      case 'error':
+      case 'error': {
+        // The sink is still open, so what the completed steps used is said,
+        // marked as not the whole, before the error that ends the turn.
+        const partial = partialUsage(tally);
+        if (partial !== undefined) {
+          tally.usage = partial;
+          await sink.emit({ type: 'usage', ...partial });
+        }
         await sink.emit({
           type: 'error',
           code: 'provider',
@@ -847,6 +998,7 @@ async function runTurn(
         // settled here too.
         end('failed');
         return;
+      }
       case 'tool-error': {
         // `execute` never throws, so this means the SDK failed before the tool
         // ran — a malformed call, usually. The browser still needs a result
@@ -861,6 +1013,7 @@ async function runTurn(
         break;
       }
       case 'abort':
+        tally.usage ??= partialUsage(tally);
         end('cancelled');
         return;
       default:

package/src/ai/shared/contract.ts

@@ -128,6 +128,9 @@ const chatEvent = s.object({
   expiresAt: s.optional(s.number()),
   inputTokens: s.optional(s.number()),
   outputTokens: s.optional(s.number()),
+  // On `usage`: true when the turn did not finish, so these are the steps that
+  // completed and not the whole. Absent on a finished turn's total.
+  partial: s.optional(s.boolean()),
   code: s.optional(s.string()),
   message: s.optional(s.string()),
 });

package/src/ai/shared/types.ts

@@ -127,7 +127,8 @@ export interface StoredMessage {
  *   confirm     callId, tool, input, requestId, releaseId, argumentsHash,
  *               expiresAt                    (waits for ai.chatConfirm)
  *   tool-result callId, tool, output, denied?
- *   usage       inputTokens, outputTokens
+ *   usage       inputTokens, outputTokens, partial? (true: the turn did not
+ *               finish, and these are only its completed steps)
  *   done        —
  *   error       code, message
  */
@@ -148,6 +149,8 @@ export interface ChatEvent {
   expiresAt?: number;
   inputTokens?: number;
   outputTokens?: number;
+  /** On `usage`: the turn did not finish, so this is a subtotal, not the whole. */
+  partial?: boolean;
   code?: string;
   message?: string;
 }