broapp 0.1.0 → 0.3.0

package/src/host/app.ts

@@ -16,6 +16,7 @@ import type { BridgeStream } from '@brobridgejs/core';
 
 import type {
   AnyContract,
+  Effect,
   OperationInput,
   OperationName,
   OperationOutput,
@@ -23,10 +24,18 @@ import type {
   StreamName,
   StreamParams,
 } from '../shared/contract.ts';
-import { splitRoute } from '../shared/contract.ts';
-import { PublicError } from '../shared/errors.ts';
+import { assertNoReservedRoutes, effectOf, splitRoute } from '../shared/contract.ts';
+import {
+  INTERNAL_ERROR_MESSAGE,
+  isPublicBridgeError,
+  isPublicError,
+  PublicError,
+} from '../shared/errors.ts';
 import { encodeEvent } from '../shared/ndjson.ts';
-import { ValidationError } from '../shared/schema.ts';
+import { isValidationError } from '../shared/schema.ts';
+
+import { createGate } from './gate.ts';
+import type { Channel, Envelope, ExecutionMode, Gate } from './gate.ts';
 
 /**
  * What an operation handler is told about its caller.
@@ -41,6 +50,14 @@ import { ValidationError } from '../shared/schema.ts';
 export interface CallContext {
   /** The route name, for logging. */
   readonly route: string;
+  /** Correlates this call with the gate's record and any approval it needed. */
+  readonly requestId: string;
+  /** Who asked, as the adapter that received the request said so. */
+  readonly channel: Channel;
+  /** Free text naming the caller: 'tab', 'ai:<runId>', 'mcp:<client>'. */
+  readonly caller: string;
+  /** `preview` means the data directory is a copy and nothing may leave the machine. */
+  readonly mode: ExecutionMode;
 }
 
 /** A unary operation implementation. */
@@ -81,6 +98,12 @@ export interface HostLogger {
 /** Options for {@link createHostApp}. */
 export interface HostAppOptions {
   readonly logger?: HostLogger;
+  /**
+   * The gate every call passes. An application that does not supply one gets a
+   * live gate for an unreleased application: the policy still applies, there is
+   * simply nothing recording it and no release to bind an approval to.
+   */
+  readonly gate?: Gate;
 }
 
 /** A contract with implementations attached, ready to mount on a bridge. */
@@ -97,18 +120,66 @@ 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.
+   *
+   * The envelope is required, and required to be built by the adapter making
+   * the call rather than passed through from whatever asked it to. That is
+   * what stops a model from invoking an operation as the user.
+   */
+  invoke<K extends OperationName<C>>(
+    name: K,
+    input: unknown,
+    envelope: Envelope,
+  ): 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;
+  /** The gate this application's calls pass through. */
+  readonly gate: Gate;
 }
 
-/** 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;
+  // An application that was not given a gate still has one. There is no
+  // ungated path into a handler, so the only question a missing option answers
+  // is what the records say, not whether the policy applies.
+  const gate: Gate =
+    options.gate ??
+    createGate({ appId: 'app', releaseId: 'unreleased', mode: 'live', logger });
   const operations = new Map<string, OperationHandler<C, never>>();
   const streams = new Map<string, StreamHandlerFor<C, never>>();
   const running = new Set<AbortController>();
@@ -120,6 +191,53 @@ 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, envelope: Envelope): 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`);
+    }
+    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.
+      //
+      // This is deliberately before the gate. A call that never had valid
+      // arguments asked nobody for anything, so there is nothing to approve and
+      // nothing worth recording.
+      throw new PublicError(
+        'invalid_input',
+        isValidationError(cause) ? cause.message : 'invalid input',
+      ).toBridgeError();
+    }
+    const context: CallContext = {
+      route,
+      requestId: envelope.requestId,
+      channel: envelope.channel,
+      caller: envelope.caller,
+      mode: gate.mode === 'preview' || envelope.mode === 'preview' ? 'preview' : 'live',
+    };
+    try {
+      const output = await gate.guard(
+        { ...envelope, route, effect: spec.effect ?? envelope.effectHint ?? 'write', input },
+        () => Promise.resolve(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,10 +253,34 @@ export function createHostApp<C extends AnyContract>(
       return app;
     },
 
+    invoke(name, input, envelope) {
+      // 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, envelope).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;
     },
 
+    gate,
+
     abortAll(reason) {
       for (const controller of running) controller.abort(new Error(reason));
     },
@@ -156,35 +298,19 @@ 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);
-          }
-        };
+        // The envelope is built here and nowhere else on this path. A tab has
+        // no way to describe itself as anything other than the user, because
+        // nothing it sends is read when this is filled in.
+        service[member] = (raw: unknown): Promise<unknown> =>
+          runOperation(route, raw, {
+            requestId: crypto.randomUUID(),
+            channel: 'user',
+            caller: 'tab',
+          });
         groups.set(group, service);
       }
       for (const [group, service] of groups) bridge.expose(group, service);
@@ -193,7 +319,7 @@ export function createHostApp<C extends AnyContract>(
         const spec = contract.streams[route];
         if (spec === undefined) continue;
         bridge.stream(route, (stream: BridgeStream, streamContext: StreamContext) =>
-          runStream(stream, streamContext, route, spec, handler, running, logger),
+          runStream(stream, streamContext, route, spec, handler, running, logger, gate),
         );
       }
     },
@@ -212,7 +338,7 @@ export function createHostApp<C extends AnyContract>(
  * accidentally undo the reduction by wrapping the message.
  */
 function wrap(cause: unknown, route: string, logger: HostLogger): unknown {
-  if (cause instanceof PublicError) return cause.toBridgeError();
+  if (isPublicError(cause)) return cause.toBridgeError();
   logger.error(`[broapp] ${route} failed: ${String(cause instanceof Error ? cause.stack ?? cause.message : cause)}`);
   return cause;
 }
@@ -233,10 +359,15 @@ async function runStream<E>(
   stream: BridgeStream,
   streamContext: StreamContext,
   route: string,
-  spec: { params: { parse(value: unknown): unknown }; event: { parse(value: unknown): unknown } },
+  spec: {
+    params: { parse(value: unknown): unknown };
+    event: { parse(value: unknown): unknown };
+    effect?: Effect;
+  },
   handler: (params: never, sink: StreamSink<E>) => void | Promise<void>,
   running: Set<AbortController>,
   logger: HostLogger,
+  gate: Gate,
 ): Promise<void> {
   const controller = new AbortController();
   running.add(controller);
@@ -255,7 +386,7 @@ async function runStream<E>(
     running.delete(controller);
     throw new PublicError(
       'invalid_input',
-      cause instanceof ValidationError ? cause.message : 'invalid stream parameters',
+      isValidationError(cause) ? cause.message : 'invalid stream parameters',
     ).toBridgeError();
   }
 
@@ -269,7 +400,23 @@ async function runStream<E>(
   };
 
   try {
-    await handler(params as never, sink);
+    // A stream is guarded once, when it starts. Its events are the one call's
+    // output, not a series of calls, so there is nothing further to decide
+    // once the handler is running.
+    await gate.guard(
+      {
+        requestId: crypto.randomUUID(),
+        channel: 'user',
+        caller: 'tab',
+        signal: controller.signal,
+        route,
+        effect: effectOf(spec),
+        input: params,
+      },
+      async () => {
+        await handler(params as never, sink);
+      },
+    );
     if (!controller.signal.aborted) await stream.end();
   } catch (cause) {
     // A cancelled stream is not a fault: the browser asked for it, the stream

package/src/host/approvals.ts

@@ -0,0 +1,115 @@
+/**
+ * The table a waiting question and a later answer meet in.
+ *
+ * An approver has to ask somebody, and the somebody is at the other end of a
+ * route: a chat stream, a launcher tab, an MCP client's own UI. So the ask and
+ * the answer are two separate calls, and something has to hold the question in
+ * between. That is all this is — with one property that matters more than the
+ * bookkeeping.
+ *
+ * An answer must name the question it is answering. A `requestId` alone would
+ * let an answer meant for one call approve a different one that happened to be
+ * pending under the same identifier after a rebuild, or after a model changed
+ * its arguments between the question and the click. So an answer may carry the
+ * release and the arguments hash it believes it is approving, and a value that
+ * does not match the pending question is a denial, not a near miss.
+ */
+import type { HostLogger } from './app.ts';
+import type { ApprovalQuestion, Approver } from './gate.ts';
+
+/** What the route that received a person's answer passes back in. */
+export interface ApprovalAnswer {
+  readonly requestId: string;
+  readonly approved: boolean;
+  /** When given, must equal the pending question's value or the answer is a mismatch. */
+  readonly releaseId?: string;
+  readonly argumentsHash?: string;
+}
+
+/** What happened to an answer. */
+export type AnswerResult = 'accepted' | 'unknown' | 'mismatch';
+
+/** An {@link Approver} whose answers arrive later, over some other route. */
+export interface PendingApprovals extends Approver {
+  /** Called by the route that receives the person's answer. */
+  answer(answer: ApprovalAnswer): AnswerResult;
+  /**
+   * Questions currently waiting, for a UI to show. `input` is shown as-is;
+   * adapters must not put secrets in inputs.
+   */
+  readonly pending: readonly ApprovalQuestion[];
+}
+
+/** One question, and the callback that settles it. */
+interface Waiting {
+  readonly question: ApprovalQuestion;
+  settle(approved: boolean): void;
+}
+
+/** Build a pending-approval table. */
+export function createPendingApprovals(logger?: HostLogger): PendingApprovals {
+  const log: HostLogger = logger ?? console;
+  const waiting = new Map<string, Waiting>();
+
+  return {
+    ask(question: ApprovalQuestion, signal: AbortSignal): Promise<boolean> {
+      // Two questions under one identifier would make an answer ambiguous, and
+      // an ambiguous approval is the one thing this table exists to prevent.
+      // The caller chose the identifier, so a collision is its bug.
+      if (waiting.has(question.requestId)) {
+        throw new TypeError(
+          `an approval for request ${JSON.stringify(question.requestId)} is already pending`,
+        );
+      }
+      return new Promise<boolean>((resolve) => {
+        let settled = false;
+        const finish = (approved: boolean): void => {
+          if (settled) return;
+          settled = true;
+          waiting.delete(question.requestId);
+          signal.removeEventListener('abort', onAbort);
+          resolve(approved);
+        };
+        // A question nobody answers is a denial, not a hung call: the person
+        // may have closed the tab, and nothing may run unattended.
+        const onAbort = (): void => finish(false);
+        signal.addEventListener('abort', onAbort, { once: true });
+        if (signal.aborted) finish(false);
+        else waiting.set(question.requestId, { question, settle: finish });
+      });
+    },
+
+    answer(answer: ApprovalAnswer): AnswerResult {
+      const entry = waiting.get(answer.requestId);
+      // Nobody waiting covers both a stale answer and a second answer for a
+      // question that has already been settled and removed.
+      if (entry === undefined) return 'unknown';
+
+      const wrong =
+        answer.releaseId !== undefined && answer.releaseId !== entry.question.releaseId
+          ? 'releaseId'
+          : answer.argumentsHash !== undefined &&
+              answer.argumentsHash !== entry.question.argumentsHash
+            ? 'argumentsHash'
+            : null;
+      if (wrong !== null) {
+        // An answer about a different release or different arguments is not
+        // this question's answer. It is treated as a denial rather than
+        // ignored, so the caller stops waiting instead of hanging until the
+        // deadline for a question that will never be answered correctly.
+        log.warn(
+          `[broapp] an approval for ${entry.question.route} named a different ${wrong} and was refused`,
+        );
+        entry.settle(false);
+        return 'mismatch';
+      }
+
+      entry.settle(answer.approved);
+      return 'accepted';
+    },
+
+    get pending(): readonly ApprovalQuestion[] {
+      return [...waiting.values()].map((entry) => entry.question);
+    },
+  };
+}