broapp 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "broapp",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "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/adapter.ts

@@ -61,7 +61,7 @@ export interface ProviderAdapter {
   models(config: AdapterConfig, signal: AbortSignal): Promise<BroappModel[]>;
   /** Cheapest possible proof the config works. Must reject with {@link AdapterError}. */
   test(config: AdapterConfig, signal: AbortSignal): Promise<void>;
-  /** The AI SDK model. Only `broapp/ai/host` calls this. */
+  /** The AI SDK model. Only `broapp/ai/host` calls this; other host code asks `Ai.model()`. */
   model(config: AdapterConfig, modelId: string): LanguageModel;
 }
 

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

@@ -10,6 +10,7 @@
  * `mount` has an implementation for every route in the contract, which it
  * insists on.
  */
+import type { LanguageModel } from 'ai';
 import type { Bridge } from 'brobridge';
 
 // Imported from the host entry point rather than from `host/app.ts` directly:
@@ -18,7 +19,7 @@ import type { Bridge } from 'brobridge';
 // browser target polyfills `node:fs`, so the file stores alone would not stop
 // this code from being bundled into a page.
 import { createPendingApprovals, createReservedHostApp } from '../../host/index.ts';
-import type { HostApp, HostLogger } from '../../host/app.ts';
+import type { HostApp, HostLogger, StreamSink } from '../../host/app.ts';
 import { publicError } from '../../shared/errors.ts';
 import { aiContract, type AiContract } from '../shared/contract.ts';
 import type { ProviderInfo } from '../shared/types.ts';
@@ -26,10 +27,66 @@ import type { ProviderInfo } from '../shared/types.ts';
 import { AdapterError, toPublicError, type AdapterConfig, type ProviderAdapter } from './adapter.ts';
 import { createRegistry, type Registry } from './registry.ts';
 import { runChat, type RunDeps } from './run.ts';
+import type { ChatEvent } from './run-types.ts';
 import { createFileSecretStore, createMemorySecretStore } from './secrets.ts';
 import { createSettingsStore } from './settings.ts';
 import { openThreads, type ThreadStore } from './threads.ts';
-import { GUARDED, type AiContextProviders, type AiTool } from './tool.ts';
+import { GUARDED, type AiContextProviders, type AiTool, type ContextDocument } from './tool.ts';
+
+/** How a turn went, beyond whether it ended well. */
+export interface RunEndDetail {
+  readonly usage?: { readonly inputTokens: number; readonly outputTokens: number };
+  /** Tool round trips the turn made. */
+  readonly steps: number;
+  readonly ms: number;
+}
+
+/**
+ * What one turn was given, after the budget. Documents are exactly what the
+ * model saw.
+ *
+ * Reported before the model is called, so a listener can write down the turn's
+ * inputs with the identity they had then rather than reconstruct them later
+ * from settings that may since have changed.
+ */
+export interface DeliveredContext {
+  readonly system: string;
+  readonly documents: readonly ContextDocument[];
+  /** The person's message for this turn, which the system prompt does not carry. */
+  readonly message: string;
+  /** The provider and model the turn was sent to. */
+  readonly model: { readonly provider: string; readonly id: string };
+}
+
+/** One turn run in-process by {@link Ai.turn}. */
+export interface InProcessTurn {
+  readonly runId: string;
+  readonly message: string;
+  /** The model for this turn, within the configured provider. */
+  readonly modelId?: string;
+}
+
+/** How {@link Ai.turn} is answered and stopped. */
+export interface InProcessTurnOptions {
+  /**
+   * The answer to each question the gate asks during the turn.
+   *
+   * 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.
+   */
+  readonly answer: (question: { readonly tool: string; readonly input: unknown }) => boolean;
+  /** Aborting it cancels the turn, as a browser's cancel would. */
+  readonly signal?: AbortSignal;
+  readonly onEvent?: (event: ChatEvent) => void;
+}
+
+/** How an in-process turn ended, and everything it emitted. */
+export interface InProcessTurnResult {
+  readonly status: 'succeeded' | 'failed' | 'cancelled';
+  readonly events: readonly ChatEvent[];
+  /** The reason a turn that could not start gave, such as no provider being set up. */
+  readonly error?: string;
+}
 
 /** What the application is, in the words a model is given. */
 export interface AiAppDescription {
@@ -75,7 +132,16 @@ export interface CreateAiOptions {
     runId: string,
     status: 'succeeded' | 'failed' | 'cancelled',
     summary: string,
+    detail?: RunEndDetail,
   ) => void;
+  /**
+   * Called once per turn, after the context budget and before the model, with
+   * what the model is about to be given.
+   *
+   * A hook that throws is logged and ignored: recording a turn is never a
+   * reason to fail it.
+   */
+  readonly onContext?: (runId: string, delivered: DeliveredContext) => void;
 }
 
 /**
@@ -104,8 +170,29 @@ export interface Ai {
   readonly activeStreams: number;
   /** For tests, and for applications that read settings on the host. */
   readonly registry: Registry;
+  /**
+   * The configured model, for host code that needs one outside a chat turn.
+   *
+   * Resolved the same way a turn resolves it, so a caller is told "AI is not
+   * set up yet" in the same words, and always a model instance — never a
+   * string the AI SDK would send to its gateway.
+   */
+  model(override?: { readonly modelId?: string }): Promise<LanguageModel>;
+  /**
+   * Run one chat turn in this process, without a bridge or a browser.
+   *
+   * For scripts that drive the engineer themselves, such as a replay. It is
+   * the `ai.chat` route's own loop — the same tools, gate, context providers
+   * and hooks — with a sink that collects the events instead of writing them to
+   * a socket, and `answer` standing where the person's click would.
+   */
+  turn(turn: InProcessTurn, options: InProcessTurnOptions): Promise<InProcessTurnResult>;
 }
 
+/** How long an in-process answer waits for its question to be registered. */
+const ANSWER_ATTEMPTS = 200;
+const ANSWER_INTERVAL_MS = 5;
+
 /** How long a provider is given to answer a listing or a connection test. */
 const PROVIDER_TIMEOUT_MS = 20_000;
 
@@ -215,6 +302,7 @@ export function createAi(options: CreateAiOptions): Ai {
     confirmTimeoutMs: options.confirmTimeoutMs ?? DEFAULT_CONFIRM_TIMEOUT_MS,
     approvals,
     ...(options.onRunEnd === undefined ? {} : { onRunEnd: options.onRunEnd }),
+    ...(options.onContext === undefined ? {} : { onContext: options.onContext }),
     logger: options.logger ?? console,
   };
 
@@ -262,5 +350,79 @@ export function createAi(options: CreateAiOptions): Ai {
       return host.activeStreams;
     },
     registry,
+    model: async (override) => {
+      const { adapter, config, modelId } = await registry.resolve(override);
+      return adapter.model(config, modelId);
+    },
+    turn: async (turn, turnOptions) => {
+      const controller = new AbortController();
+      const relay = (): void => controller.abort(turnOptions.signal?.reason);
+      turnOptions.signal?.addEventListener('abort', relay, { once: true });
+      if (turnOptions.signal?.aborted === true) relay();
+
+      const events: ChatEvent[] = [];
+      /**
+       * Answer a question once the approval table holds it.
+       *
+       * The `confirm` event is emitted, and awaited, before the run's approver
+       * registers the question, so an answer given inside `emit` would find
+       * nobody waiting. This waits for it, briefly, the way a person's click
+       * necessarily arrives later.
+       */
+      const settle = async (requestId: string, approved: boolean): Promise<void> => {
+        for (let attempt = 0; attempt < ANSWER_ATTEMPTS; attempt += 1) {
+          if (approvals.answer({ requestId, approved }) !== 'unknown') return;
+          await Bun.sleep(ANSWER_INTERVAL_MS);
+        }
+      };
+      const sink: StreamSink<ChatEvent> = {
+        signal: controller.signal,
+        sessionId: 'in-process',
+        emit(event) {
+          if (controller.signal.aborted) return Promise.reject(new Error('stream is no longer open'));
+          events.push(event);
+          turnOptions.onEvent?.(event);
+          if (event.type === 'confirm') {
+            // 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 }));
+          }
+          return Promise.resolve();
+        },
+      };
+
+      let status: InProcessTurnResult['status'] | null = null;
+      const onRunEnd = runDeps.onRunEnd;
+      try {
+        await runChat(
+          {
+            runId: turn.runId,
+            message: turn.message,
+            refs: [],
+            history: [],
+            ...(turn.modelId === undefined ? {} : { modelId: turn.modelId }),
+          },
+          sink,
+          {
+            ...runDeps,
+            // The turn's own ending is what this returns; whoever the layer
+            // was built to tell is still told.
+            onRunEnd: (runId, ended, summary, detail) => {
+              status = ended;
+              onRunEnd?.(runId, ended, summary, detail);
+            },
+          },
+        );
+        return { status: status ?? 'succeeded', events };
+      } catch (cause) {
+        // A turn that could not start — no provider set up, most often — ends
+        // failed with the sentence the browser would have been shown.
+        const error = String(cause instanceof Error ? cause.message : cause);
+        return { status: status ?? 'failed', events, error };
+      } finally {
+        turnOptions.signal?.removeEventListener('abort', relay);
+      }
+    },
   };
 }

package/src/ai/host/index.ts

@@ -7,7 +7,17 @@
  * follows this import fails loudly instead.
  */
 export { createAi } from './create-ai.ts';
-export type { Ai, AiAppDescription, CreateAiOptions } from './create-ai.ts';
+export type {
+  Ai,
+  AiAppDescription,
+  CreateAiOptions,
+  DeliveredContext,
+  InProcessTurn,
+  InProcessTurnOptions,
+  InProcessTurnResult,
+  RunEndDetail,
+} from './create-ai.ts';
+export type { ChatEvent } from './run-types.ts';
 
 export { AdapterError, isLoopbackUrl, toPublicError } from './adapter.ts';
 export type { AdapterConfig, AdapterErrorCode, ProviderAdapter } from './adapter.ts';

package/src/ai/host/run.ts

@@ -28,6 +28,7 @@ import { AdapterError } from './adapter.ts';
 import type { AdapterConfig, ProviderAdapter } from './adapter.ts';
 import type { Registry } from './registry.ts';
 import type { AiContextProviders, AiTool, ContextDocument } from './tool.ts';
+import type { DeliveredContext, RunEndDetail } from './create-ai.ts';
 
 /** What the run loop needs from the `Ai` that owns it. */
 export interface RunDeps {
@@ -53,7 +54,37 @@ export interface RunDeps {
    * outside the AI layer — Autoapp's run store — close the record the gate has
    * been writing steps into.
    */
-  readonly onRunEnd?: (runId: string, status: 'succeeded' | 'failed' | 'cancelled', summary: string) => void;
+  readonly onRunEnd?: (
+    runId: string,
+    status: 'succeeded' | 'failed' | 'cancelled',
+    summary: string,
+    detail?: RunEndDetail,
+  ) => void;
+  /** Called once per turn with what the model is about to be given. */
+  readonly onContext?: (runId: string, delivered: DeliveredContext) => void;
+}
+
+/** What a turn counts as it goes, for {@link RunEndDetail}. */
+interface TurnTally {
+  steps: number;
+  usage?: { inputTokens: number; outputTokens: number };
+}
+
+/**
+ * Call a listener's hook without letting it touch the turn.
+ *
+ * Both hooks exist so something outside the AI layer can write down what
+ * happened. A recorder that fails has failed at recording, not at the turn, so
+ * the failure is logged and the turn carries on exactly as it would have.
+ */
+function safely(logger: HostLogger, hook: string, call: () => void): void {
+  try {
+    call();
+  } catch (cause) {
+    logger.error(
+      `[broapp] ai ${hook} hook failed: ${String(cause instanceof Error ? cause.message : cause)}`,
+    );
+  }
 }
 
 /**
@@ -177,7 +208,10 @@ async function assembleContext(
 
   await load(params.refs);
   if (searcher !== undefined) {
-    const found = await searcher({ text: params.message, limit: SEARCH_LIMIT }, signal);
+    const found = await searcher(
+      { text: params.message, limit: SEARCH_LIMIT, runId: params.runId },
+      signal,
+    );
     await load(found.map((entry) => entry.ref));
   }
   return fitToBudget(documents, deps.contextBudgetChars);
@@ -421,13 +455,24 @@ export async function runChat(
   // browser cancelled and a turn that finished all have to close their record,
   // 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 end = (status: 'succeeded' | 'failed' | 'cancelled'): void => {
     if (ended) return;
     ended = true;
-    deps.onRunEnd?.(params.runId, status, params.message.slice(0, SUMMARY_CHARS));
+    const onRunEnd = deps.onRunEnd;
+    if (onRunEnd === undefined) return;
+    const detail: RunEndDetail = {
+      steps: tally.steps,
+      ms: Date.now() - started,
+      ...(tally.usage === undefined ? {} : { usage: tally.usage }),
+    };
+    safely(deps.logger, 'onRunEnd', () =>
+      onRunEnd(params.runId, status, params.message.slice(0, SUMMARY_CHARS), detail),
+    );
   };
   try {
-    await runTurn(params, sink, deps, end);
+    await runTurn(params, sink, deps, end, tally);
     end(sink.signal.aborted ? 'cancelled' : 'succeeded');
   } catch (cause) {
     end(sink.signal.aborted ? 'cancelled' : 'failed');
@@ -441,6 +486,7 @@ async function runTurn(
   sink: StreamSink<ChatEvent>,
   deps: RunDeps,
   end: (status: 'succeeded' | 'failed' | 'cancelled') => void,
+  tally: TurnTally,
 ): Promise<void> {
   // Throws a PublicError when nothing is configured. `runStream` in host/app.ts
   // turns that into the right thing on the wire, so it is not caught here.
@@ -473,12 +519,28 @@ async function runTurn(
     requestId.startsWith(`${params.runId}:`) ? requestId.slice(params.runId.length + 1) : requestId,
   );
 
+  // Built once and handed to both the listener and the model, so what is
+  // written down is the string that was sent rather than a second rendering of
+  // it that might differ.
+  const system = buildSystemPrompt(deps, documents);
+  const onContext = deps.onContext;
+  if (onContext !== undefined) {
+    safely(deps.logger, 'onContext', () =>
+      onContext(params.runId, {
+        system,
+        documents,
+        message: params.message,
+        model: { provider: resolved.adapter.id, id: resolved.modelId },
+      }),
+    );
+  }
+
   const result = streamText({
     // Always a model *instance*. A string here would be resolved by the AI
     // SDK's gateway, over the global fetch, to a Vercel host — see
     // reports/01-spike.md. Nothing in this layer may pass one.
     model: resolved.adapter.model(resolved.config, resolved.modelId),
-    system: buildSystemPrompt(deps, documents),
+    system,
     messages: toModelMessages(params),
     tools: buildTools(params, deps, sink, approver),
     stopWhen: stepCountIs(deps.maxSteps),
@@ -494,16 +556,23 @@ async function runTurn(
       case 'text-delta':
         await sink.emit({ type: 'text', text: part.text });
         break;
-      case 'finish':
-        await sink.emit({
-          type: 'usage',
-          // `ai` flattens the provider's nested usage object into plain
-          // numbers, either of which a provider may omit.
+      case 'tool-call':
+        // Counted here rather than in `execute`: a call the SDK rejected before
+        // it ran was still a round trip the model spent.
+        tally.steps += 1;
+        break;
+      case 'finish': {
+        // `ai` flattens the provider's nested usage object into plain
+        // numbers, either of which a provider may omit.
+        const usage = {
           inputTokens: part.totalUsage.inputTokens ?? 0,
           outputTokens: part.totalUsage.outputTokens ?? 0,
-        });
+        };
+        tally.usage = usage;
+        await sink.emit({ type: 'usage', ...usage });
         await sink.emit({ type: 'done' });
         break;
+      }
       case 'error':
         await sink.emit({
           type: 'error',
@@ -531,8 +600,8 @@ async function runTurn(
         end('cancelled');
         return;
       default:
-        // tool-call, tool-result, text-start, finish-step, reasoning, source,
-        // raw: either already emitted from `execute`, or not something the
+        // tool-result, text-start, finish-step, reasoning, source, raw:
+        // either already emitted from `execute`, or not something the
         // browser has a use for.
         break;
     }

package/src/ai/host/tool.ts

@@ -47,7 +47,8 @@ export interface GuardedToolDefinition {
   readonly description: string;
   readonly inputSchema: JsonSchema;
   readonly effect: Effect;
-  run(input: unknown, signal: AbortSignal): Promise<unknown>;
+  /** The envelope is the run loop's, never the model's; a tool may record it and must not act on its channel. */
+  run(input: unknown, signal: AbortSignal, envelope?: Envelope): Promise<unknown>;
 }
 
 /**
@@ -67,7 +68,7 @@ export function guardedTool(gate: Gate, tool: GuardedToolDefinition): GuardedToo
     effect: tool.effect,
     execute: (input, envelope) =>
       gate.guard({ ...envelope, route: tool.name, effect: tool.effect, input }, (signal) =>
-        tool.run(input, signal),
+        tool.run(input, signal, envelope),
       ),
   };
 }
@@ -88,8 +89,13 @@ export interface ContextDocument {
 
 /** Where the model's knowledge of the application's data comes from. */
 export interface AiContextProviders {
-  /** Records relevant to a query. Return refs and short snippets, not full content. */
-  search?(query: { text: string; limit: number }, signal: AbortSignal): Promise<ContextRef[]>;
+  /**
+   * Records relevant to a query. Return refs and short snippets, not full content.
+   *
+   * `runId` is the turn asking, so a provider can write down what it offered
+   * to which run. It identifies; it grants nothing.
+   */
+  search?(query: { text: string; limit: number; runId?: string }, signal: AbortSignal): Promise<ContextRef[]>;
   /** Full content for named refs. Unknown refs are skipped, not errors. */
   resolve?(refs: readonly string[], signal: AbortSignal): Promise<ContextDocument[]>;
 }

package/src/cli/main.ts

@@ -21,7 +21,7 @@ Usage:
   broapp build --page                 Build the UI document only
 
 Build options:
-  --target <id>       Compile for one target. Repeatable. Default: this machine.
+  --target <id>       Compile for one target, named <name>-<id>. Repeatable. Default: this machine, named <name>.
   --all-targets       Compile every supported target.
   --out-dir <path>    Where executables go. Default: release
   --no-minify         Keep the bundle readable.
@@ -158,6 +158,12 @@ async function main(): Promise<number> {
       name: config.binaryName,
       outDir: flags.outDir ?? config.outDir,
       targets,
+      // A binary built for a named target carries the target in its name,
+      // even when there is only one: a release workflow that asks for
+      // `--target linux-x64` is about to archive `<name>-linux-x64`, and a
+      // bare `<name>` there was the fault that emptied two releases. Only the
+      // default — this machine, nothing named — stays bare.
+      suffixTarget: flags.allTargets || flags.targets.length > 0,
       minify: flags.minify,
       bytecode: flags.bytecode && config.bytecode,
     });