broapp 0.1.0 → 0.3.0

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. */
@@ -94,8 +116,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_]*$/;
 
@@ -122,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`);
@@ -132,3 +169,63 @@ 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 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 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`,
+      );
+    }
+  }
+}

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;
+}

package/src/shared/errors.ts

@@ -80,6 +80,60 @@ export class PublicError extends Error {
   }
 }
 
+/**
+ * True when `error` is a {@link PublicError}, including one from another copy
+ * of this module.
+ *
+ * `instanceof` is not enough, and the reason is architectural rather than
+ * pedantic. An Autoapp release bundles its own copy of `broapp`, while the
+ * child runtime that supervises it has the copy compiled into the launcher —
+ * so a `PublicError` thrown by the gate in one and caught by `runOperation` in
+ * the other is a different class object with the same shape. Reducing it to
+ * "internal error" would silently turn every deliberate refusal, the preview
+ * policy's included, into a mystery.
+ *
+ * The check is deliberately narrow: the name, and a `code` from the known set.
+ * Nothing an untrusted value could set by accident.
+ */
+export function isPublicError(error: unknown): error is PublicError {
+  // No `instanceof PublicError` fast path. It would be true for one of the two
+  // copies and false for the other, and a check whose answer depends on which
+  // bundle asked is the bug this function exists to fix — including in the
+  // reader's mind, the next time somebody copies this shape.
+  if (!(error instanceof Error) || error.name !== 'PublicError') return false;
+  const code: unknown = (error as { code?: unknown }).code;
+  return typeof code === 'string' && (PUBLIC_CODES as readonly string[]).includes(code);
+}
+
+/**
+ * True when `error` is a {@link BroappError}, including one from another copy
+ * of this module.
+ *
+ * Same reason as {@link isPublicError}. `fromTransportError` is shared code:
+ * the browser calls it inside one bundle, and the Autoapp child runtime calls
+ * it on an error that came out of a release's own bundle.
+ */
+function isBroappError(error: unknown): error is BroappError {
+  if (!(error instanceof Error) || error.name !== 'BroappError') return false;
+  const code: unknown = (error as { code?: unknown }).code;
+  return typeof code === 'string' && (PUBLIC_CODES as readonly string[]).includes(code);
+}
+
+/**
+ * True when `error` is Brobridge's cancellation, from any copy of Brobridge.
+ *
+ * A release bundles its own, so the class identity is not shared. `ErrorCode`
+ * is a set of string constants rather than a symbol, which is what makes the
+ * value comparison meaningful across copies.
+ */
+function isCancelled(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    error.name === 'BridgeError' &&
+    (error as { code?: unknown }).code === ErrorCode.CANCELLED
+  );
+}
+
 /** The message every unhandled host failure becomes, on both sides. */
 export const INTERNAL_ERROR_MESSAGE = 'The application could not complete that operation.';
 
@@ -105,7 +159,7 @@ export class BroappError extends Error {
  * for a user to read.
  */
 export function fromTransportError(error: unknown): BroappError {
-  if (error instanceof BroappError) return error;
+  if (isBroappError(error)) return error;
   const message = error instanceof Error ? error.message : '';
   if (message.startsWith(MARKER)) {
     const space = message.indexOf(' ');
@@ -118,12 +172,22 @@ export function fromTransportError(error: unknown): BroappError {
       );
     }
   }
-  if (error instanceof BridgeError && error.code === ErrorCode.CANCELLED) {
+  if (isCancelled(error)) {
     return new BroappError('rejected', 'The operation was cancelled.', error);
   }
   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,11 +5,19 @@
  * 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,
+  effectOf,
+  mergeContracts,
+  RESERVED_GROUPS,
+  splitRoute,
+} from './contract.ts';
 export type {
   AnyContract,
   Contract,
   ContractShape,
+  Effect,
   ShapeOf,
   OperationInput,
   OperationName,
@@ -21,16 +29,19 @@ export type {
   StreamSpec,
 } from './contract.ts';
 
-export { s, ValidationError } from './schema.ts';
-export type { Infer, Issue, Result, Schema } from './schema.ts';
+export { isValidationError, s, ValidationError } from './schema.ts';
+export type { Infer, InferObject, Issue, JsonSchema, Result, Schema } from './schema.ts';
 
 export {
   BroappError,
   INTERNAL_ERROR_MESSAGE,
   PublicError,
   fromTransportError,
+  isPublicError,
   publicError,
 } from './errors.ts';
 export type { PublicErrorCode } from './errors.ts';
 
 export { encodeEvent, MAX_EVENT_BYTES, NdjsonDecoder } from './ndjson.ts';
+
+export { countdown, isUrgent, remainingMs, URGENT_MS } from './countdown.ts';

package/src/shared/schema.ts

@@ -35,6 +35,22 @@ export class ValidationError extends Error {
   }
 }
 
+/**
+ * True when `error` is a {@link ValidationError}, including one from another
+ * copy of this module.
+ *
+ * `instanceof` is not enough for the same reason it is not enough for
+ * `PublicError`: an Autoapp release bundles its own copy of `broapp`, so a
+ * schema built in one bundle and parsed by code in another throws a different
+ * class object with the same shape. Reducing that to "invalid input" with no
+ * message would tell a caller nothing about what was actually wrong.
+ */
+export function isValidationError(error: unknown): error is ValidationError {
+  return (
+    error instanceof Error && error.name === 'ValidationError' && Array.isArray((error as { issues?: unknown }).issues)
+  );
+}
+
 function formatPath(path: IssuePath): string {
   let out = '';
   for (const segment of path) {
@@ -49,6 +65,15 @@ export type Result<T> =
   | { readonly ok: true; readonly value: T }
   | { readonly ok: false; readonly issues: readonly Issue[] };
 
+/**
+ * A JSON Schema document, as a plain object.
+ *
+ * Broapp emits a draft 2020-12 subset — enough for a language model provider
+ * to describe a tool's arguments, and nothing more. It is deliberately not a
+ * typed tree: every consumer so far hands it straight to a provider as JSON.
+ */
+export type JsonSchema = Record<string, unknown>;
+
 /** A runtime schema for one JSON value. */
 export interface Schema<T> {
   /** Discriminates a Broapp schema from a foreign one at runtime. */
@@ -57,6 +82,8 @@ export interface Schema<T> {
   check(value: unknown, path?: IssuePath): Result<T>;
   /** Validate, or throw {@link ValidationError}. */
   parse(value: unknown): T;
+  /** A JSON Schema (draft 2020-12 subset) describing what `parse` accepts. */
+  toJsonSchema(): JsonSchema;
   /** Phantom marker; never present at runtime. */
   readonly _type?: T;
 }
@@ -64,7 +91,28 @@ export interface Schema<T> {
 /** The TypeScript type a schema accepts. */
 export type Infer<S> = S extends Schema<infer T> ? T : never;
 
-function schema<T>(kind: string, check: (value: unknown, path: IssuePath) => Result<T>): Schema<T> {
+/** Collapse an intersection back into one object type, keeping `?` modifiers. */
+type Flatten<T> = { [K in keyof T]: T[K] };
+
+/**
+ * What an object schema accepts.
+ *
+ * A field wrapped in `s.optional` may be left out entirely, so its key is
+ * optional here rather than merely admitting `undefined`. Without this an
+ * `s.optional` field would still have to be spelled out at every construction
+ * site, which is the opposite of what the wrapper says.
+ */
+export type InferObject<F> = Flatten<
+  { [K in keyof F as undefined extends Infer<F[K]> ? never : K]: Infer<F[K]> } & {
+    [K in keyof F as undefined extends Infer<F[K]> ? K : never]?: Infer<F[K]>;
+  }
+>;
+
+function schema<T>(
+  kind: string,
+  check: (value: unknown, path: IssuePath) => Result<T>,
+  toJsonSchema: () => JsonSchema,
+): Schema<T> {
   const self: Schema<T> = {
     kind,
     check: (value, path = []) => check(value, path),
@@ -73,10 +121,25 @@ function schema<T>(kind: string, check: (value: unknown, path: IssuePath) => Res
       if (outcome.ok) return outcome.value;
       throw new ValidationError(outcome.issues);
     },
+    toJsonSchema,
   };
   return self;
 }
 
+/**
+ * Assemble a JSON Schema object, dropping every keyword whose option was not
+ * given. An explicit `minLength: undefined` disappears from `JSON.stringify`
+ * but is still a key at runtime, and a provider that enumerates keywords would
+ * see it — so the key is never created in the first place.
+ */
+function keywords(entries: Record<string, unknown>): JsonSchema {
+  const out: JsonSchema = {};
+  for (const [key, value] of Object.entries(entries)) {
+    if (value !== undefined) out[key] = value;
+  }
+  return out;
+}
+
 function fail<T = never>(path: IssuePath, message: string): Result<T> {
   return { ok: false, issues: [{ path, message }] };
 }
@@ -118,7 +181,15 @@ export const s = {
         if (!anchored.test(value)) return fail(path, 'does not match the required format');
       }
       return { ok: true, value };
-    });
+    },
+      () =>
+        keywords({
+          type: 'string',
+          minLength: options.min,
+          maxLength: options.max,
+          pattern: options.pattern?.source,
+        }),
+    );
   },
 
   number(options: NumberOptions = {}): Schema<number> {
@@ -134,30 +205,46 @@ export const s = {
         return fail(path, `expected <= ${String(options.max)}`);
       }
       return { ok: true, value };
-    });
+    },
+      () =>
+        keywords({
+          type: options.int === true ? 'integer' : 'number',
+          minimum: options.min,
+          maximum: options.max,
+        }),
+    );
   },
 
   boolean(): Schema<boolean> {
-    return schema('boolean', (value, path) =>
-      typeof value === 'boolean' ? { ok: true, value } : fail(path, 'expected a boolean'),
+    return schema(
+      'boolean',
+      (value, path) =>
+        typeof value === 'boolean' ? { ok: true, value } : fail(path, 'expected a boolean'),
+      () => ({ type: 'boolean' }),
     );
   },
 
   literal<const T extends string | number | boolean>(expected: T): Schema<T> {
-    return schema('literal', (value, path) =>
-      value === expected
-        ? { ok: true, value: expected }
-        : fail(path, `expected ${JSON.stringify(expected)}`),
+    return schema(
+      'literal',
+      (value, path) =>
+        value === expected
+          ? { ok: true, value: expected }
+          : fail(path, `expected ${JSON.stringify(expected)}`),
+      () => ({ const: expected }),
     );
   },
 
   /** A closed set of string values. */
   enum<const T extends readonly string[]>(values: T): Schema<T[number]> {
     const allowed = new Set<string>(values);
-    return schema('enum', (value, path) =>
-      typeof value === 'string' && allowed.has(value)
-        ? { ok: true, value: value as T[number] }
-        : fail(path, `expected one of ${values.map((v) => JSON.stringify(v)).join(', ')}`),
+    return schema(
+      'enum',
+      (value, path) =>
+        typeof value === 'string' && allowed.has(value)
+          ? { ok: true, value: value as T[number] }
+          : fail(path, `expected one of ${values.map((v) => JSON.stringify(v)).join(', ')}`),
+      () => ({ type: 'string', enum: [...values] }),
     );
   },
 
@@ -178,7 +265,15 @@ export const s = {
         else issues.push(...outcome.issues);
       }
       return issues.length > 0 ? { ok: false, issues } : { ok: true, value: out };
-    });
+    },
+      () =>
+        keywords({
+          type: 'array',
+          items: item.toJsonSchema(),
+          minItems: options.min,
+          maxItems: options.max,
+        }),
+    );
   },
 
   /**
@@ -188,9 +283,7 @@ export const s = {
    * handler contains only what the schema named, so a property smuggled in by
    * a caller cannot reach application code by accident.
    */
-  object<F extends Record<string, Schema<unknown>>>(
-    fields: F,
-  ): Schema<{ [K in keyof F]: Infer<F[K]> }> {
+  object<F extends Record<string, Schema<unknown>>>(fields: F): Schema<InferObject<F>> {
     const entries = Object.entries(fields);
     return schema('object', (value, path) => {
       if (typeof value !== 'object' || value === null || Array.isArray(value)) {
@@ -208,30 +301,50 @@ export const s = {
       }
       return issues.length > 0
         ? { ok: false, issues }
-        : { ok: true, value: out as { [K in keyof F]: Infer<F[K]> } };
-    });
+        : { ok: true, value: out as InferObject<F> };
+    },
+      () => ({
+        type: 'object',
+        properties: Object.fromEntries(entries.map(([key, field]) => [key, field.toJsonSchema()])),
+        // An optional field is one the object may leave out, so optionality is
+        // expressed here rather than inside the field's own schema.
+        required: entries.filter(([, field]) => field.kind !== 'optional').map(([key]) => key),
+        additionalProperties: false,
+      }),
+    );
   },
 
   /** A value that may be absent or `undefined`. */
   optional<T>(inner: Schema<T>): Schema<T | undefined> {
-    return schema<T | undefined>('optional', (value, path) =>
-      value === undefined ? { ok: true, value: undefined } : inner.check(value, path),
+    return schema<T | undefined>(
+      'optional',
+      (value, path) => (value === undefined ? { ok: true, value: undefined } : inner.check(value, path)),
+      // JSON Schema has no "optional" keyword; the enclosing object omits the
+      // key from `required` instead.
+      () => inner.toJsonSchema(),
     );
   },
 
   /** A value that may be `null`. */
   nullable<T>(inner: Schema<T>): Schema<T | null> {
-    return schema<T | null>('nullable', (value, path) =>
-      value === null ? { ok: true, value: null } : inner.check(value, path),
+    return schema<T | null>(
+      'nullable',
+      (value, path) => (value === null ? { ok: true, value: null } : inner.check(value, path)),
+      () => ({ anyOf: [inner.toJsonSchema(), { type: 'null' }] }),
     );
   },
 
   /** Nothing at all. The input type of an operation that takes no argument. */
   void(): Schema<void> {
-    return schema('void', (value, path) =>
-      value === undefined || value === null
-        ? { ok: true, value: undefined }
-        : fail(path, 'expected no value'),
+    return schema(
+      'void',
+      (value, path) =>
+        value === undefined || value === null
+          ? { ok: true, value: undefined }
+          : fail(path, 'expected no value'),
+      // A provider that asks for a tool's arguments wants an object, and an
+      // operation that takes nothing takes an empty one.
+      () => ({ type: 'object', properties: {}, additionalProperties: false }),
     );
   },
 
@@ -243,6 +356,6 @@ export const s = {
    * data is untrusted.
    */
   unknown(): Schema<unknown> {
-    return schema('unknown', (value) => ({ ok: true, value }));
+    return schema('unknown', (value) => ({ ok: true, value }), () => ({}));
   },
 } as const;