broapp 0.2.0 → 0.3.0

package/src/host/gate.ts

@@ -0,0 +1,380 @@
+/**
+ * The execution gate.
+ *
+ * One place decides whether a call runs. Every path into an application's
+ * operations — a click in the browser, a model's tool call, an external agent
+ * over MCP, a workflow step — arrives here with an envelope saying who is
+ * asking, and leaves with a record saying what happened. There is no second
+ * door: an adapter that does not call `guard` is a bug, not a shortcut.
+ *
+ * The policy is deliberately three rows and no configuration language. What
+ * makes it trustworthy is not its expressiveness but where the inputs come
+ * from: the `channel` is set by the trusted adapter that received the request
+ * and never read out of model output, tool arguments or anything a browser
+ * sent. A model cannot claim to be the user, because nothing it can write is
+ * consulted when the channel is chosen.
+ */
+import { createHash } from 'node:crypto';
+
+import type { Effect } from '../shared/contract.ts';
+import { INTERNAL_ERROR_MESSAGE, isPublicError, publicError } from '../shared/errors.ts';
+
+import type { HostLogger } from './app.ts';
+
+/** Who is asking. Set by an adapter, never by the thing being adapted. */
+export type Channel = 'user' | 'ai' | 'mcp' | 'workflow';
+/** `preview` runs against a copy of the data, so nothing may leave the machine. */
+export type ExecutionMode = 'live' | 'preview';
+/** How the gate answered. */
+export type Decision = 'allowed' | 'confirmed' | 'denied' | 'refused';
+/** How the call itself ended, once it was allowed to start. */
+export type Outcome = 'succeeded' | 'failed' | 'cancelled';
+/** What the policy says about one (channel, effect, mode). */
+export type PolicyVerdict = 'allow' | 'confirm' | 'refuse';
+
+/**
+ * Who is asking, on behalf of what, and how the answer may be obtained.
+ *
+ * Built by the trusted adapter that received the request — the bridge
+ * handler, the AI runner, the MCP adapter, the workflow runner — and never
+ * from anything a model, a browser or an MCP client sent. That is the whole
+ * basis of the policy: a model cannot claim to be the user.
+ */
+export interface Envelope {
+  /** Unique per request. Correlates the question, the answer and the record. */
+  readonly requestId: string;
+  readonly channel: Channel;
+  /** Free text for records: 'tab', 'ai:<runId>', 'mcp:<client>', 'workflow:<id>'. */
+  readonly caller: string;
+  /** May only tighten the gate's default: `preview` wins over `live`. */
+  readonly mode?: ExecutionMode;
+  readonly signal?: AbortSignal;
+  /** Who to ask when the policy says `confirm`. Absent means nobody, so denied. */
+  readonly approver?: Approver;
+  /**
+   * The effect an adapter resolved for a route the contract leaves silent.
+   *
+   * It fills a gap and never widens one: a route that declares an effect keeps
+   * it, whatever an adapter says. The AI layer's allow list is the reason this
+   * exists — an operation named under `read` there is a read tool even though
+   * an undeclared route is `write` everywhere else, and the gate has to be told
+   * the same thing the model was.
+   */
+  readonly effectHint?: Effect;
+}
+
+/** One decision to make: an envelope plus the route it is about. */
+export interface GuardRequest extends Envelope {
+  readonly route: string;
+  readonly effect: Effect;
+  /** Already validated by the contract. Shown to the approver and hashed. */
+  readonly input: unknown;
+}
+
+/** What a person is asked, and what their answer has to name to count. */
+export interface ApprovalQuestion {
+  readonly requestId: string;
+  readonly channel: Channel;
+  readonly caller: string;
+  readonly appId: string;
+  readonly releaseId: string;
+  readonly route: string;
+  readonly effect: Effect;
+  readonly input: unknown;
+  readonly argumentsHash: string;
+  /** When the gate started considering this call. */
+  readonly askedAt: number;
+  /**
+   * When an unanswered question stops waiting.
+   *
+   * Carried on the question rather than left to the asker so that every place
+   * a person is shown one — a strip in a tab, a card in a chat, an MCP
+   * client's own dialogue — can say how long they have without knowing which
+   * gate asked or how it was configured. A question with no visible deadline
+   * is one people answer after it has already been refused.
+   */
+  readonly expiresAt: number;
+}
+
+/** Somewhere a question can be put to a person. */
+export interface Approver {
+  /**
+   * Ask a person. Resolves `true` only for an approval that names this
+   * question. Must resolve `false` when `signal` aborts.
+   */
+  ask(question: ApprovalQuestion, signal: AbortSignal): Promise<boolean>;
+}
+
+/** What the gate writes down about one decision, whatever it was. */
+export interface ExecutionRecord extends ApprovalQuestion {
+  readonly mode: ExecutionMode;
+  readonly decision: Decision;
+  readonly outcome?: Outcome;
+  /**
+   * What the call returned, present only when it succeeded.
+   *
+   * A recorder that keeps this can show a person what actually happened, and
+   * can draft a workflow from a run that worked. It is host-controlled output,
+   * not something a caller supplied — but a recorder that persists it is
+   * storing application data and owns whatever redaction that needs.
+   */
+  readonly output?: unknown;
+  /** A sentence safe to show. Never a stack, never a secret. */
+  readonly error?: string;
+  readonly startedAt: number;
+  readonly endedAt: number;
+}
+
+/** Where records go. A run store, a log, or nothing. */
+export interface Recorder {
+  record(record: ExecutionRecord): void;
+}
+
+/** Options for {@link createGate}. */
+export interface GateOptions {
+  readonly appId: string;
+  readonly releaseId: string;
+  readonly recorder?: Recorder;
+  /** Default 120_000. */
+  readonly confirmTimeoutMs?: number;
+  /** Default 'live'. A preview child passes 'preview'. */
+  readonly mode?: ExecutionMode;
+  readonly logger?: HostLogger;
+}
+
+/** The one door. */
+export interface Gate {
+  readonly appId: string;
+  readonly releaseId: string;
+  readonly mode: ExecutionMode;
+  /** True while the gate is holding back everything that changes anything. */
+  readonly paused: boolean;
+  /**
+   * Stop admitting work that changes anything.
+   *
+   * For draining before an update: the application goes on answering questions
+   * while it is being replaced, and stops accepting new writes. `reason` is
+   * shown to whoever asked, so it should say what is happening rather than
+   * that something went wrong.
+   */
+  pause(reason: string): void;
+  /** Admit everything again. */
+  resume(): void;
+  /**
+   * Decide, ask if needed, record, run.
+   *
+   * Throws `PublicError` with code `rejected` when the policy refuses or a
+   * person declines, times out or the request is cancelled while waiting.
+   * `run` is called at most once and only after an allow or a confirmed
+   * approval.
+   */
+  guard<T>(request: GuardRequest, run: (signal: AbortSignal) => Promise<T>): Promise<T>;
+}
+
+/** How long a question waits when the gate is not told otherwise. */
+const DEFAULT_CONFIRM_TIMEOUT_MS = 120_000;
+
+/**
+ * The whole v1 policy. Pure, exported so the table can be tested row by row.
+ *
+ * Read for anybody, always: nothing changes, so there is nothing to approve.
+ * The owner's own click is allowed to write, because the owner is who the
+ * application belongs to. Every other channel is an agent acting on their
+ * behalf and asks first. `preview` refuses `external` outright for everyone:
+ * a preview runs against a copy of the data, and a copy of the data is not a
+ * copy of the world — a message sent from a preview is sent for real.
+ */
+export function decide(channel: Channel, effect: Effect, mode: ExecutionMode): PolicyVerdict {
+  if (mode === 'preview' && effect === 'external') return 'refuse';
+  if (effect === 'read') return 'allow';
+  if (channel === 'user') return 'allow';
+  return 'confirm';
+}
+
+/**
+ * Canonical JSON (object keys sorted at every depth) hashed with sha256, hex,
+ * first 32 characters.
+ *
+ * Sorting is what makes the hash an identity rather than a formatting
+ * accident: the question a person was shown and the answer they gave have to
+ * be about the same arguments, and two encoders of the same object must not
+ * disagree about that.
+ */
+export function argumentsHash(input: unknown): string {
+  return createHash('sha256').update(canonicalJson(input)).digest('hex').slice(0, 32);
+}
+
+/**
+ * JSON with every object's keys in sorted order, at every depth.
+ *
+ * Exported because more than one thing needs the same answer to "are these two
+ * values the same value": the gate, for an approval, and Autoapp's release
+ * identity, for a contract. Two sorters would eventually disagree.
+ */
+export function canonicalJson(value: unknown): string {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null';
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  const entries = Object.entries(value as Record<string, unknown>)
+    .filter(([, member]) => member !== undefined)
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  return `{${entries.map(([key, member]) => `${JSON.stringify(key)}:${canonicalJson(member)}`).join(',')}}`;
+}
+
+/** A signal that never aborts, for a request that brought none. */
+function neverAborts(): AbortSignal {
+  return new AbortController().signal;
+}
+
+/** Build the gate one application runs behind. */
+export function createGate(options: GateOptions): Gate {
+  const logger: HostLogger = options.logger ?? console;
+  const confirmTimeoutMs = options.confirmTimeoutMs ?? DEFAULT_CONFIRM_TIMEOUT_MS;
+  const gateMode: ExecutionMode = options.mode ?? 'live';
+  const recorder = options.recorder;
+  /** The reason writes are being held back, or `null` when they are not. */
+  let pausedReason: string | null = null;
+
+  /**
+   * Write one record.
+   *
+   * A recorder that throws is a broken diagnostic, not a reason to fail the
+   * user's call, so the throw stops here and is logged instead.
+   */
+  function write(record: ExecutionRecord): void {
+    if (recorder === undefined) return;
+    try {
+      recorder.record(record);
+    } catch (cause) {
+      logger.error(
+        `[broapp] the execution recorder failed for ${record.route}: ${String(cause instanceof Error ? (cause.stack ?? cause.message) : cause)}`,
+      );
+    }
+  }
+
+  const gate: Gate = {
+    appId: options.appId,
+    releaseId: options.releaseId,
+    mode: gateMode,
+
+    get paused() {
+      return pausedReason !== null;
+    },
+
+    pause(reason: string) {
+      pausedReason = reason;
+    },
+
+    resume() {
+      pausedReason = null;
+    },
+
+    async guard<T>(request: GuardRequest, run: (signal: AbortSignal) => Promise<T>): Promise<T> {
+      // A pause is not a decision about this call — it is the application
+      // declining to be asked at all for a moment — so nothing is recorded and
+      // the code is `unavailable` rather than `rejected`. Reads still run: a
+      // draining application that stopped answering questions would look
+      // broken to whoever is still looking at it.
+      if (pausedReason !== null && request.effect !== 'read') {
+        throw publicError.unavailable(pausedReason);
+      }
+
+      // Either side may tighten to `preview`; neither may loosen back. A live
+      // gate asked to preview obeys, and a preview gate handed `live` in an
+      // envelope stays a preview.
+      const mode: ExecutionMode =
+        gateMode === 'preview' || request.mode === 'preview' ? 'preview' : 'live';
+      const at = Date.now();
+      const question: ApprovalQuestion = {
+        requestId: request.requestId,
+        channel: request.channel,
+        caller: request.caller,
+        appId: gate.appId,
+        releaseId: gate.releaseId,
+        route: request.route,
+        effect: request.effect,
+        input: request.input,
+        argumentsHash: argumentsHash(request.input),
+        // Filled in for every call, not only the ones that ask. A record of an
+        // allowed call carries the window it would have had, which costs two
+        // numbers and saves a reader working out whether one was even offered.
+        askedAt: at,
+        expiresAt: at + confirmTimeoutMs,
+      };
+
+      const verdict = decide(request.channel, request.effect, mode);
+      if (verdict === 'refuse') {
+        write({ ...question, mode, decision: 'refused', startedAt: at, endedAt: Date.now() });
+        throw publicError.rejected(`${request.route} is not allowed in preview`);
+      }
+
+      let decision: Decision = 'allowed';
+      if (verdict === 'confirm') {
+        const approver = request.approver;
+        if (approver === undefined) {
+          write({ ...question, mode, decision: 'denied', startedAt: at, endedAt: Date.now() });
+          throw publicError.rejected(`${request.route} needs approval and nobody can give it`);
+        }
+        // The question's own deadline is separate from the request's: a person
+        // who never answers must not hold a tool call open forever, and a
+        // cancelled request must stop asking.
+        const asking = new AbortController();
+        const timer = setTimeout(() => asking.abort(new Error('the question timed out')), confirmTimeoutMs);
+        const relay = (): void => asking.abort(new Error('the request was cancelled'));
+        request.signal?.addEventListener('abort', relay, { once: true });
+        if (request.signal?.aborted === true) relay();
+        let approved: boolean;
+        try {
+          approved = await approver.ask(question, asking.signal);
+        } finally {
+          clearTimeout(timer);
+          request.signal?.removeEventListener('abort', relay);
+        }
+        if (!approved) {
+          const cancelled = request.signal?.aborted === true;
+          write({
+            ...question,
+            mode,
+            decision: 'denied',
+            ...(cancelled ? { outcome: 'cancelled' as const } : {}),
+            startedAt: at,
+            endedAt: Date.now(),
+          });
+          throw publicError.rejected(`${request.route} was not approved`);
+        }
+        decision = 'confirmed';
+      }
+
+      const signal = request.signal ?? neverAborts();
+      const startedAt = Date.now();
+      try {
+        const value = await run(signal);
+        write({
+          ...question,
+          mode,
+          decision,
+          outcome: 'succeeded',
+          output: value,
+          startedAt,
+          endedAt: Date.now(),
+        });
+        return value;
+      } catch (cause) {
+        // A `PublicError` was written for whoever is watching and keeps its
+        // words. Anything else may name a path, a query or a token, so the
+        // record gets the same fixed sentence the browser would have seen.
+        write({
+          ...question,
+          mode,
+          decision,
+          outcome: signal.aborted ? 'cancelled' : 'failed',
+          error: isPublicError(cause) ? cause.message : INTERNAL_ERROR_MESSAGE,
+          startedAt,
+          endedAt: Date.now(),
+        });
+        throw cause;
+      }
+    },
+  };
+
+  return gate;
+}

package/src/host/index.ts

@@ -7,8 +7,8 @@
  */
 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.
+ * Not for applications: it skips the check that refuses Broapp's reserved
+ * route groups. Only `broapp/ai/host` and `broapp-autoapp/host` should use it.
  */
 export { createReservedHostApp } from './app.ts';
 export type {
@@ -21,6 +21,26 @@ export type {
   StreamSink,
 } from './app.ts';
 
+export { argumentsHash, canonicalJson, createGate, decide } from './gate.ts';
+export type {
+  Approver,
+  ApprovalQuestion,
+  Channel,
+  Decision,
+  Envelope,
+  ExecutionMode,
+  ExecutionRecord,
+  Gate,
+  GateOptions,
+  GuardRequest,
+  Outcome,
+  PolicyVerdict,
+  Recorder,
+} from './gate.ts';
+
+export { createPendingApprovals } from './approvals.ts';
+export type { AnswerResult, ApprovalAnswer, PendingApprovals } from './approvals.ts';
+
 export { startApp } from './runtime.ts';
 export type { LifecycleMode, RunningApp, ShutdownReason, StartAppOptions } from './runtime.ts';
 

package/src/host/paths.ts

@@ -9,7 +9,7 @@
  * it to the application.
  */
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 import { mkdirSync } from 'node:fs';
 
 /** The environment variable that overrides the resolved directory. */
@@ -31,7 +31,11 @@ export const DATA_DIR_ENV = 'BROAPP_DATA_DIR';
  */
 export function dataDir(appName: string, env: NodeJS.ProcessEnv = process.env): string {
   const override = env[DATA_DIR_ENV];
-  if (override !== undefined && override !== '') return override;
+  // Absolute, whatever was given. A relative override is convenient at a shell
+  // (`BROAPP_DATA_DIR=./run`), but paths under it are handed to child
+  // processes and to `import()`, and a relative path in an import specifier is
+  // a package name, not a file.
+  if (override !== undefined && override !== '') return resolve(override);
 
   const platform = process.platform;
   if (platform === 'win32') {

package/src/host/runtime.ts

@@ -66,6 +66,16 @@ export interface RunningApp {
   readonly done: Promise<number>;
   /** Stop it. Safe to call more than once. */
   stop(reason?: ShutdownReason): Promise<void>;
+  /**
+   * True while at least one tab is actually connected.
+   *
+   * The same question the idle logic asks, exposed for a supervisor that has to
+   * report whether anybody is looking at this application. Deliberately not
+   * "a session exists": Brobridge retains a session for a minute after its
+   * socket drops so a reconnecting tab can resume, and a closed tab would go on
+   * looking attached for that whole minute.
+   */
+  readonly attached: boolean;
 }
 
 const POLL_INTERVAL_MS = 1_000;
@@ -159,12 +169,16 @@ export async function startApp(options: StartAppOptions): Promise<RunningApp> {
     });
   }
 
+  /** Whether any endpoint is open right now. One definition, two readers. */
+  const isAttached = (): boolean =>
+    bridge.sessions.some((session) => session.endpoint.state === 'open');
+
   if (mode === 'interactive') {
     const startedAt = Date.now();
     let idleSince: number | null = null;
 
     poll = setInterval(() => {
-      const attached = bridge.sessions.some((session) => session.endpoint.state === 'open');
+      const attached = isAttached();
       const now = Date.now();
 
       if (attached) {
@@ -194,5 +208,12 @@ export async function startApp(options: StartAppOptions): Promise<RunningApp> {
     poll.unref?.();
   }
 
-  return { bridge, done, stop };
+  return {
+    bridge,
+    done,
+    stop,
+    get attached() {
+      return isAttached();
+    },
+  };
 }

package/src/shared/contract.ts

@@ -17,12 +17,28 @@
  */
 import type { Infer, Schema } from './schema.ts';
 
+/**
+ * What an operation or stream does to the world.
+ *
+ * `read` changes nothing. `write` changes data inside the application's data
+ * directory. `external` reaches outside it: the network, other files, a
+ * spawned process, mail. The gate decides from this and from who is asking
+ * whether a call runs, waits for a person, or is refused. A route that does
+ * not say is treated as `write`, which asks a person before an agent may
+ * run it and lets the owner's own click through.
+ */
+export type Effect = 'read' | 'write' | 'external';
+
+/** The three strings an `effect` may be, for validation at definition time. */
+const EFFECTS: readonly Effect[] = ['read', 'write', 'external'];
+
 /** One unary operation: JSON in, JSON out. */
 export interface OperationSpec<I = unknown, O = unknown> {
   readonly input: Schema<I>;
   readonly output: Schema<O>;
   /** Shown in generated documentation and in the developer panel. */
   readonly summary?: string;
+  readonly effect?: Effect;
 }
 
 /**
@@ -37,6 +53,12 @@ export interface StreamSpec<P = unknown, E = unknown> {
   readonly params: Schema<P>;
   readonly event: Schema<E>;
   readonly summary?: string;
+  readonly effect?: Effect;
+}
+
+/** The effect a route declares, or the conservative default. */
+export function effectOf(spec: { readonly effect?: Effect }): Effect {
+  return spec.effect ?? 'write';
 }
 
 /** The operation and stream tables an application declares. */
@@ -123,6 +145,20 @@ export function defineContract<const C extends ContractShape>(shape: C): Contrac
       );
     }
   }
+  // An `effect` that is not one of the three words would silently become the
+  // conservative default at the gate, which reads as a working declaration
+  // while meaning nothing. A typo is refused where it was written instead.
+  for (const [route, spec] of [
+    ...Object.entries(shape.operations),
+    ...Object.entries(shape.streams),
+  ] as readonly (readonly [string, { readonly effect?: unknown }])[]) {
+    const effect = spec.effect;
+    if (effect !== undefined && !(EFFECTS as readonly unknown[]).includes(effect)) {
+      throw new TypeError(
+        `route ${JSON.stringify(route)} declares effect ${JSON.stringify(effect)}, which must be "read", "write" or "external"`,
+      );
+    }
+  }
   const clash = operations.find((route) => streams.includes(route));
   if (clash !== undefined) {
     throw new TypeError(`route ${JSON.stringify(clash)} is declared as both an operation and a stream`);
@@ -166,22 +202,29 @@ export function mergeContracts<A extends AnyContract, B extends AnyContract>(
   }>;
 }
 
-/** The route group Broapp reserves for its AI layer. */
-export const RESERVED_GROUPS: readonly string[] = ['ai'];
+/**
+ * The route groups Broapp reserves for itself.
+ *
+ * `ai` belongs to the AI layer and `autoapp` to Autoapp's own host routes.
+ * Both are mounted as a second host app on the same bridge as the
+ * application's, so a name that appeared in both route tables would be
+ * unresolvable.
+ */
+export const RESERVED_GROUPS: readonly string[] = ['ai', 'autoapp'];
 
 /**
  * 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.
+ * This is not checked in `defineContract`, because Broapp's own contracts are
+ * built with `defineContract` and have to be allowed their groups. 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`,
+        `route ${JSON.stringify(route)} uses the group ${JSON.stringify(group)}, which is reserved for Broapp`,
       );
     }
   }

package/src/shared/countdown.ts

@@ -0,0 +1,36 @@
+/**
+ * How long a person has left to answer a question.
+ *
+ * Shared rather than written twice because the same countdown appears wherever
+ * an approval is shown — an approvals strip in an application's tab, a confirm
+ * card in a chat panel — and two formatters would eventually disagree about
+ * what "one minute left" looks like. It is pure arithmetic over a timestamp:
+ * nothing here decides anything, and the gate's own timer is what actually
+ * refuses a question nobody answered.
+ */
+
+/** Below this, a question is close enough to running out to say so loudly. */
+export const URGENT_MS = 60_000;
+
+/** Milliseconds until `expiresAt`, never negative. */
+export function remainingMs(expiresAt: number, now: number = Date.now()): number {
+  return Math.max(0, expiresAt - now);
+}
+
+/**
+ * The time left as `m:ss`.
+ *
+ * Rounded up, so a question with 600 ms left reads `0:01` rather than `0:00`:
+ * a countdown that says zero while the button still works is a countdown
+ * people stop believing.
+ */
+export function countdown(expiresAt: number, now: number = Date.now()): string {
+  const seconds = Math.ceil(remainingMs(expiresAt, now) / 1000);
+  return `${String(Math.floor(seconds / 60))}:${String(seconds % 60).padStart(2, '0')}`;
+}
+
+/** True while a question is nearly out of time, and false once it is out. */
+export function isUrgent(expiresAt: number, now: number = Date.now()): boolean {
+  const left = remainingMs(expiresAt, now);
+  return left > 0 && left < URGENT_MS;
+}