broapp 0.1.0 → 0.2.0

package/src/ai/shared/types.ts

@@ -0,0 +1,87 @@
+/**
+ * The types the browser sees.
+ *
+ * Everything here is shared code: it names what the AI layer exchanges over
+ * the bridge and nothing about how a provider is reached. No file in this
+ * directory may import the AI SDK packages — the browser bundle follows these
+ * imports, and the page's CSP forbids it from talking to a provider anyway.
+ *
+ * The fields are not marked `readonly`. These interfaces must be *identical*
+ * to what `Infer` derives from the contract in `contract.ts`, which
+ * `types.check.ts` asserts at compile time; a `readonly` here would make the
+ * two types merely compatible instead, and the drift check would stop
+ * catching drift.
+ */
+
+/** A model a provider offers, as the browser sees it. */
+export interface BroappModel {
+  provider: string;
+  modelId: string;
+  label: string;
+  capabilities: {
+    tools: boolean;
+    vision: boolean;
+    structuredOutput: boolean;
+  };
+}
+
+/** A provider compiled into this application, as the browser sees it. */
+export interface ProviderInfo {
+  id: string;
+  label: string;
+  /** True when requests stay on this machine with the current settings. */
+  local: boolean;
+  needs: { apiKey: boolean; baseUrl: 'required' | 'optional' | 'none' };
+  defaultBaseUrl: string | null;
+}
+
+/** What the settings route returns. Never contains the key itself. */
+export interface AiSettings {
+  provider: string | null;
+  modelId: string | null;
+  baseUrl: string | null;
+  hasKey: boolean;
+  /** Last four characters of the key, for the UI to show which key is set. */
+  keyHint: string | null;
+  /** False means the key is held in memory only and forgotten on exit. */
+  remember: boolean;
+  /** True when provider and model are both set and the provider's needs are met. */
+  configured: boolean;
+}
+
+/** How much ceremony a tool call needs before it runs. */
+export type ToolPermission = 'read' | 'confirm';
+
+/** One turn of prior conversation the browser sends back with each message. */
+export interface ChatTurn {
+  role: 'user' | 'assistant';
+  content: string;
+}
+
+/**
+ * One event on the `ai.chat` stream. Flat on purpose: the `s` validator has
+ * no unions, so the discriminant is `type` and the other fields are
+ * optional. Which fields are present for which type:
+ *
+ *   text        text
+ *   tool-call   callId, tool, input, permission
+ *   confirm     callId, tool, input          (waits for ai.chat.confirm)
+ *   tool-result callId, tool, output, denied?
+ *   usage       inputTokens, outputTokens
+ *   done        —
+ *   error       code, message
+ */
+export interface ChatEvent {
+  type: 'text' | 'tool-call' | 'confirm' | 'tool-result' | 'usage' | 'done' | 'error';
+  text?: string;
+  callId?: string;
+  tool?: string;
+  input?: unknown;
+  output?: unknown;
+  denied?: boolean;
+  permission?: ToolPermission;
+  inputTokens?: number;
+  outputTokens?: number;
+  code?: string;
+  message?: string;
+}

package/src/host/app.ts

@@ -23,8 +23,8 @@ import type {
   StreamName,
   StreamParams,
 } from '../shared/contract.ts';
-import { splitRoute } from '../shared/contract.ts';
-import { PublicError } from '../shared/errors.ts';
+import { assertNoReservedRoutes, splitRoute } from '../shared/contract.ts';
+import { INTERNAL_ERROR_MESSAGE, isPublicBridgeError, PublicError } from '../shared/errors.ts';
 import { encodeEvent } from '../shared/ndjson.ts';
 import { ValidationError } from '../shared/schema.ts';
 
@@ -97,16 +97,48 @@ export interface HostApp<C extends AnyContract> {
    * a developer is present to see it.
    */
   mount(bridge: Bridge): void;
+  /**
+   * Run one operation directly, without the bridge. Input is validated and
+   * output is checked exactly as for a call from the browser, and the same
+   * error boundary applies. This is how the AI layer lets a model call an
+   * application's operations as tools.
+   *
+   * A route that is a stream, or one no handler implements, is a programming
+   * error rather than a call failure, so it throws `TypeError` at the call
+   * site instead of rejecting.
+   */
+  invoke<K extends OperationName<C>>(name: K, input: unknown): Promise<OperationOutput<C, K>>;
   /** Abort every stream this app currently has open. Called during shutdown. */
   abortAll(reason: string): void;
   /** How many streams are running right now. */
   readonly activeStreams: number;
 }
 
-/** Build the host side of a contract. */
+/**
+ * Build the host side of an application's contract.
+ *
+ * The reserved-group check lives here rather than in `defineContract` because
+ * Broapp's own AI contract is built with `defineContract` and legitimately
+ * uses the group. An application that declares `ai.*` would collide with the
+ * AI layer on the same bridge, so it is refused while a developer is watching.
+ */
 export function createHostApp<C extends AnyContract>(
   contract: C,
   options: HostAppOptions = {},
+): HostApp<C> {
+  assertNoReservedRoutes(contract);
+  return createReservedHostApp(contract, options);
+}
+
+/**
+ * Build a host app without the reserved-group check.
+ *
+ * Not for applications. `broapp/ai/host` uses it to mount the AI contract,
+ * which is the one contract allowed to own the `ai` group.
+ */
+export function createReservedHostApp<C extends AnyContract>(
+  contract: C,
+  options: HostAppOptions = {},
 ): HostApp<C> {
   const logger: HostLogger = options.logger ?? console;
   const operations = new Map<string, OperationHandler<C, never>>();
@@ -120,6 +152,40 @@ export function createHostApp<C extends AnyContract>(
     }
   }
 
+  /**
+   * One operation call, from the bridge or from {@link HostApp.invoke}.
+   *
+   * Both paths must validate the same way and fail the same way — an AI tool
+   * call is not more trusted than a browser call just because it originates
+   * inside the host — so there is one implementation and two callers.
+   */
+  async function runOperation(route: string, raw: unknown): Promise<unknown> {
+    const spec = contract.operations[route];
+    const handler = operations.get(route);
+    if (spec === undefined || handler === undefined) {
+      throw new TypeError(`operation ${JSON.stringify(route)} has no implementation`);
+    }
+    const context: CallContext = { route };
+    let input: unknown;
+    try {
+      input = spec.input.parse(raw);
+    } catch (cause) {
+      // A validation message names a field and a constraint from the contract
+      // the browser already has. It carries nothing the caller did not send,
+      // so it is safe to return and useful to see.
+      throw new PublicError(
+        'invalid_input',
+        cause instanceof ValidationError ? cause.message : 'invalid input',
+      ).toBridgeError();
+    }
+    try {
+      const output = await handler(input as never, context);
+      return spec.output.parse(output);
+    } catch (cause) {
+      throw wrap(cause, route, logger);
+    }
+  }
+
   const app: HostApp<C> = {
     operation(name, handler) {
       known('operation', name);
@@ -135,6 +201,28 @@ export function createHostApp<C extends AnyContract>(
       return app;
     },
 
+    invoke(name, input) {
+      // Structural mistakes surface synchronously: a stream is not invokable
+      // and a missing handler is a bug, and neither should look like a failed
+      // call to whatever is awaiting the result.
+      if (Object.prototype.hasOwnProperty.call(contract.streams, name)) {
+        throw new TypeError(`route ${JSON.stringify(name)} is a stream, which cannot be invoked`);
+      }
+      if (!Object.prototype.hasOwnProperty.call(contract.operations, name)) {
+        throw new TypeError(`operation ${JSON.stringify(name)} is not declared in the contract`);
+      }
+      if (!operations.has(name)) {
+        throw new TypeError(`operation ${JSON.stringify(name)} has no implementation`);
+      }
+      return runOperation(name, input).catch((cause: unknown) => {
+        // On the bridge, Brobridge reduces an unexpected failure to a fixed
+        // sentence on the way out. `invoke` has no transport to do that, and
+        // its caller is the AI layer, which may put what it is given into a
+        // transcript — so the same reduction is applied here.
+        throw isPublicBridgeError(cause) ? cause : new Error(INTERNAL_ERROR_MESSAGE);
+      }) as Promise<never>;
+    },
+
     get activeStreams() {
       return running.size;
     },
@@ -156,35 +244,11 @@ export function createHostApp<C extends AnyContract>(
       // dotted routes are collected back into groups here. This is the only
       // place the two namings meet.
       const groups = new Map<string, Record<string, unknown>>();
-      for (const [route, handler] of operations) {
+      for (const route of operations.keys()) {
         const { group, member } = splitRoute(route);
-        const spec = contract.operations[route];
-        if (spec === undefined) continue;
+        if (contract.operations[route] === undefined) continue;
         const service = groups.get(group) ?? {};
-        service[member] = async (raw: unknown): Promise<unknown> => {
-          const context: CallContext = { route };
-          let input: unknown;
-          try {
-            input = spec.input.parse(raw);
-          } catch (cause) {
-            // A validation message names a field and a constraint from the
-            // contract the browser already has. It carries nothing the caller
-            // did not send, so it is safe to return and useful to see.
-            throw new PublicError(
-              'invalid_input',
-              cause instanceof ValidationError ? cause.message : 'invalid input',
-            ).toBridgeError();
-          }
-          try {
-            const output = await (handler as OperationHandler<C, never>)(
-              input as never,
-              context,
-            );
-            return spec.output.parse(output);
-          } catch (cause) {
-            throw wrap(cause, route, logger);
-          }
-        };
+        service[member] = (raw: unknown): Promise<unknown> => runOperation(route, raw);
         groups.set(group, service);
       }
       for (const [group, service] of groups) bridge.expose(group, service);

package/src/host/index.ts

@@ -6,6 +6,11 @@
  * the import would fail loudly — which is the intended outcome.
  */
 export { createHostApp } from './app.ts';
+/**
+ * Not for applications: it skips the check that refuses the reserved `ai`
+ * route group. Only `broapp/ai/host` should use it.
+ */
+export { createReservedHostApp } from './app.ts';
 export type {
   CallContext,
   HostApp,

package/src/react/hooks.tsx

@@ -23,6 +23,7 @@ import type {
   StreamName,
   StreamParams,
 } from '../shared/contract.ts';
+import { mergeContracts } from '../shared/contract.ts';
 import { BroappError } from '../shared/errors.ts';
 import type { BridgeState, BroappClient, CreateClientOptions, Subscription } from '../client/client.ts';
 import { createClient } from '../client/client.ts';
@@ -72,6 +73,14 @@ interface ContextValue<C extends AnyContract> {
    */
   readonly ready: Promise<BroappClient<C>>;
   readonly status: ConnectionStatus;
+  /**
+   * The contract actually spoken, application plus extensions.
+   *
+   * Components below the provider read routes from here rather than from the
+   * contract they were handed, because an extension's routes exist only after
+   * the merge.
+   */
+  readonly contract: AnyContract;
 }
 
 const BroappContext = React.createContext<ContextValue<AnyContract> | null>(null);
@@ -79,6 +88,8 @@ const BroappContext = React.createContext<ContextValue<AnyContract> | null>(null
 /** Props for {@link BroappProvider}. */
 export interface BroappProviderProps<C extends AnyContract> {
   readonly contract: C;
+  /** Extra contracts to speak over the same connection, e.g. Broapp's `aiContract`. */
+  readonly extensions?: readonly AnyContract[];
   readonly options?: CreateClientOptions;
   /**
    * How long the host retains a protocol session after a disconnect. Must
@@ -106,10 +117,22 @@ function toStatus(state: BridgeState, since: number, now: number, ttlMs: number)
 /** Owns the connection for everything below it. */
 export function BroappProvider<C extends AnyContract>({
   contract,
+  extensions,
   options,
   sessionTtlMs = 60_000,
   children,
 }: BroappProviderProps<C>): React.ReactElement {
+  // Merged once and kept. Both contracts are module-level constants, and a
+  // second merge would build a second client and drop the connection.
+  const mergedRef = React.useRef<AnyContract | null>(null);
+  if (mergedRef.current === null) {
+    mergedRef.current = (extensions ?? []).reduce<AnyContract>(
+      (left, right) => mergeContracts(left, right),
+      contract,
+    );
+  }
+  const merged = mergedRef.current as C;
+
   const [client, setClient] = React.useState<BroappClient<C> | null>(null);
   const [status, setStatus] = React.useState<ConnectionStatus>({ phase: 'connecting' });
   // Created before the effect runs, so the very first render already has
@@ -143,7 +166,7 @@ export function BroappProvider<C extends AnyContract>({
     // transport event.
     let tick: ReturnType<typeof setInterval> | undefined;
 
-    void createClient(contract, options).then(
+    void createClient(merged, options).then(
       (next) => {
         if (!live) {
           void next.close();
@@ -191,8 +214,8 @@ export function BroappProvider<C extends AnyContract>({
   }, []);
 
   const value = React.useMemo<ContextValue<C>>(
-    () => ({ client, ready, status }),
-    [client, ready, status],
+    () => ({ client, ready, status, contract: merged }),
+    [client, ready, status, merged],
   );
   return (
     <BroappContext.Provider value={value as ContextValue<AnyContract>}>
@@ -212,6 +235,17 @@ export function useConnection(): ConnectionStatus {
   return useContextValue().status;
 }
 
+/**
+ * The contract actually spoken over this connection, extensions included.
+ *
+ * An extension's own hooks use it to check that they were installed — asking
+ * for a route that is not there fails at the first call otherwise, which is
+ * later and further from the mistake.
+ */
+export function useBroappContract(): AnyContract {
+  return useContextValue().contract;
+}
+
 /** The client, or `null` until the first connection settles. */
 export function useBroapp<C extends AnyContract>(): BroappClient<C> | null {
   return useContextValue<C>().client;

package/src/react/index.ts

@@ -2,6 +2,7 @@
 export {
   BroappProvider,
   useBroapp,
+  useBroappContract,
   useBroappReady,
   useConnection,
   useOperation,

package/src/shared/contract.ts

@@ -94,8 +94,9 @@ export type StreamEvent<C extends AnyContract, K extends StreamName<C>> = Infer<
 
 /**
  * A route name is `group.member`. Brobridge resolves a unary call by splitting
- * on the first `.` and looking the group up in its service registry, so both
- * halves must be present and neither may itself contain a dot.
+ * on the *last* `.` and looking the group up in its service registry, and it
+ * refuses to expose a service whose name contains a dot — so both halves must
+ * be present and neither may itself contain one.
  */
 const ROUTE_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*$/;
 
@@ -132,3 +133,56 @@ export function defineContract<const C extends ContractShape>(shape: C): Contrac
     routes: { operations, streams },
   };
 }
+
+/**
+ * Combine two contracts into one. Used in the browser so one client can
+ * speak an application's contract and Broapp's AI contract over one
+ * connection. Throws if any route name appears in both.
+ */
+export function mergeContracts<A extends AnyContract, B extends AnyContract>(
+  a: A,
+  b: B,
+): Contract<{
+  operations: ShapeOf<A>['operations'] & ShapeOf<B>['operations'];
+  streams: ShapeOf<A>['streams'] & ShapeOf<B>['streams'];
+}> {
+  // A clash is checked across all four tables, not table by table: a name that
+  // is an operation on one side and a stream on the other is just as
+  // unresolvable as a duplicate operation, because Brobridge dispatches on the
+  // route name alone.
+  const names = new Set<string>([...a.routes.operations, ...a.routes.streams]);
+  for (const route of [...b.routes.operations, ...b.routes.streams]) {
+    if (names.has(route)) throw new TypeError(`route ${JSON.stringify(route)} is declared by both contracts`);
+  }
+  const operations = { ...a.operations, ...b.operations };
+  const streams = { ...a.streams, ...b.streams };
+  return {
+    operations,
+    streams,
+    routes: { operations: Object.keys(operations), streams: Object.keys(streams) },
+  } as Contract<{
+    operations: ShapeOf<A>['operations'] & ShapeOf<B>['operations'];
+    streams: ShapeOf<A>['streams'] & ShapeOf<B>['streams'];
+  }>;
+}
+
+/** The route group Broapp reserves for its AI layer. */
+export const RESERVED_GROUPS: readonly string[] = ['ai'];
+
+/**
+ * Throws if a contract declares a route in a reserved group.
+ *
+ * This is not checked in `defineContract`, because Broapp's own AI contract is
+ * built with `defineContract` and has to be allowed the group. It is checked
+ * where an *application* contract enters the host instead.
+ */
+export function assertNoReservedRoutes(contract: AnyContract): void {
+  for (const route of [...contract.routes.operations, ...contract.routes.streams]) {
+    const { group } = splitRoute(route);
+    if (RESERVED_GROUPS.includes(group)) {
+      throw new TypeError(
+        `route ${JSON.stringify(route)} uses the group ${JSON.stringify(group)}, which is reserved for Broapp's AI layer`,
+      );
+    }
+  }
+}

package/src/shared/errors.ts

@@ -124,6 +124,16 @@ export function fromTransportError(error: unknown): BroappError {
   return new BroappError('internal', INTERNAL_ERROR_MESSAGE, error);
 }
 
+/**
+ * True when an error already carries a message written for the browser.
+ *
+ * Anything else is a host-side failure whose message may name a path, a query
+ * or a token, and must be reduced before it leaves the host.
+ */
+export function isPublicBridgeError(error: unknown): boolean {
+  return error instanceof Error && error.message.startsWith(MARKER);
+}
+
 /** Convenience constructors, so a handler reads as prose. */
 export const publicError = {
   invalidInput: (message: string): PublicError => new PublicError('invalid_input', message),

package/src/shared/index.ts

@@ -5,7 +5,13 @@
  * description and the types derived from it. That is what makes it safe for
  * the browser bundle to follow.
  */
-export { defineContract, splitRoute } from './contract.ts';
+export {
+  assertNoReservedRoutes,
+  defineContract,
+  mergeContracts,
+  RESERVED_GROUPS,
+  splitRoute,
+} from './contract.ts';
 export type {
   AnyContract,
   Contract,
@@ -22,7 +28,7 @@ export type {
 } from './contract.ts';
 
 export { s, ValidationError } from './schema.ts';
-export type { Infer, Issue, Result, Schema } from './schema.ts';
+export type { Infer, InferObject, Issue, JsonSchema, Result, Schema } from './schema.ts';
 
 export {
   BroappError,