broapp 0.4.2 → 0.4.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "broapp",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "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",
@@ -49,9 +49,9 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@brobridgejs/client": "^0.2.1",
-    "@brobridgejs/core": "^0.2.1",
-    "brobridge": "^0.2.1"
+    "@brobridgejs/client": "^0.2.2",
+    "@brobridgejs/core": "^0.2.2",
+    "brobridge": "^0.2.2"
   },
   "peerDependencies": {
     "react": ">=18",

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

@@ -71,6 +71,18 @@ export interface InProcessTurn {
   readonly history?: readonly ChatTurn[];
 }
 
+/** One question put to an in-process turn's stand-in. */
+export interface InProcessQuestion {
+  readonly tool: string;
+  readonly input: unknown;
+  /** The approval table's key, `<runId>:<callId>`. */
+  readonly requestId: string;
+  /** The call the question is about, as `ai.chatConfirm` names it with the run id. */
+  readonly callId: string;
+  /** When the question stops waiting, when the gate said. */
+  readonly expiresAt?: number;
+}
+
 /** How {@link Ai.turn} is answered and stopped. */
 export interface InProcessTurnOptions {
   /**
@@ -78,8 +90,14 @@ export interface InProcessTurnOptions {
    *
    * The caller is the person's stand-in, so it decides exactly as the person
    * would have: the gate still asks, and still records the answer.
+   *
+   * `'defer'` answers nothing. The question stays in the approval table for
+   * somebody else to answer by its request id, over `ai.chatConfirm` as a
+   * person in a chat would, and the gate's own window still ends it. That is
+   * for a stand-in that answers some questions itself and brings the rest to a
+   * person: whoever answers, each question is answered once.
    */
-  readonly answer: (question: { readonly tool: string; readonly input: unknown }) => boolean;
+  readonly answer: (question: InProcessQuestion) => boolean | 'defer';
   /** Aborting it cancels the turn, as a browser's cancel would. */
   readonly signal?: AbortSignal;
   readonly onEvent?: (event: ChatEvent) => void;
@@ -398,7 +416,14 @@ export function createAi(options: CreateAiOptions): Ai {
             // The gate's request id is `<runId>:<callId>`, which is what an
             // event without one would have named.
             const requestId = event.requestId ?? `${turn.runId}:${event.callId}`;
-            void settle(requestId, turnOptions.answer({ tool: event.tool ?? '', input: event.input }));
+            const answer = turnOptions.answer({
+              tool: event.tool ?? '',
+              input: event.input,
+              requestId,
+              callId: event.callId ?? '',
+              ...(event.expiresAt === undefined ? {} : { expiresAt: event.expiresAt }),
+            });
+            if (answer !== 'defer') void settle(requestId, answer);
           }
           return Promise.resolve();
         },

package/src/ai/host/index.ts

@@ -12,6 +12,7 @@ export type {
   AiAppDescription,
   CreateAiOptions,
   DeliveredContext,
+  InProcessQuestion,
   InProcessTurn,
   InProcessTurnOptions,
   InProcessTurnResult,

package/src/ai/host/run.ts

@@ -85,7 +85,29 @@ 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;
+}
+
+/**
+ * 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 };
 }
 
 /**
@@ -288,14 +310,22 @@ function boundOutput(output: unknown, max: number): unknown {
   return { type: 'text', value: cut(json, max) };
 }
 
-/** One transcript message with every tool input and output bounded. */
+/**
+ * One transcript message with every tool input and output bounded.
+ *
+ * A cut input stays an object, `{ truncated: "<head><omitted N chars>" }`,
+ * rather than becoming the string itself: an OpenAI-compatible provider sends
+ * a call's input as its `arguments`, and Ollama refuses a whole request whose
+ * arguments are not a JSON object ("invalid tool call arguments"). The first
+ * 12j evaluation lost a turn to exactly that.
+ */
 function boundMessage(message: ResponseMessage, limits: HistoryLimits): ModelMessage {
   if (!Array.isArray(message.content)) return message;
   const content = (message.content as readonly unknown[]).map((part) => {
     if (!isRecord(part)) return part;
     if (part['type'] === 'tool-call') {
       const json = JSON.stringify(part['input']) ?? '';
-      return json.length <= limits.inputChars ? part : { ...part, input: cut(json, limits.inputChars) };
+      return json.length <= limits.inputChars ? part : { ...part, input: { truncated: cut(json, limits.inputChars) } };
     }
     if (part['type'] === 'tool-result') return { ...part, output: boundOutput(part['output'], limits.outputChars) };
     return part;
@@ -303,6 +333,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.
  *
@@ -310,8 +419,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[],
@@ -339,7 +453,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;
@@ -653,7 +774,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
@@ -669,6 +790,8 @@ 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 = {
@@ -800,11 +923,22 @@ 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;
+    },
   });
 
   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 });
@@ -829,7 +963,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',
@@ -839,6 +980,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
@@ -853,6 +995,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;
 }

package/src/host/runtime.ts

@@ -76,6 +76,15 @@ export interface RunningApp {
    * looking attached for that whole minute.
    */
   readonly attached: boolean;
+  /**
+   * A fresh address for this application, carrying a new one-time launch token.
+   *
+   * Brobridge mints the token; each address works once and expires on the
+   * bridge's launch-token lifetime. Call it on the host's own decision — a
+   * person's click in an authenticated tab, a local process that already holds
+   * a credential — never because a browser asked. Do not log the result.
+   */
+  launchUrl(): string;
 }
 
 const POLL_INTERVAL_MS = 1_000;
@@ -215,5 +224,6 @@ export async function startApp(options: StartAppOptions): Promise<RunningApp> {
     get attached() {
       return isAttached();
     },
+    launchUrl: () => bridge.launchUrl(),
   };
 }