@unifedev/thread-pages 0.3.2 → 1.0.3

package/src/config/settings.ts

@@ -0,0 +1,82 @@
+import type { BbPluginApi } from "@get-bb/plugin-sdk";
+import { DEFAULT_AGENT_INSTRUCTION } from "../agent/instruction.ts";
+import { DEFAULT_PAGE_SEED } from "../agent/seed/seed.ts";
+
+/**
+ * The five settings and nothing more. spec 07
+ *
+ * Read live: a change applies to the next request without a restart (R7.5).
+ * Neither the seed nor the instruction ever touches an existing page (R7.1).
+ */
+export interface Settings {
+  readonly agentInstructions: boolean;
+  readonly agentInstructionText: string;
+  readonly pageSeedHtml: string;
+  readonly workingLabel: string;
+  readonly homeSessionId: string;
+}
+
+export const DEFAULT_WORKING_LABEL = "Working — this is the last saved version";
+
+export interface LiveSettings {
+  current(): Settings;
+  set(values: Partial<{ [K in keyof Settings]: Settings[K] | null }>): Promise<Settings>;
+}
+
+export async function defineSettings(bb: BbPluginApi): Promise<LiveSettings> {
+  const handle = bb.settings.define({
+    agentInstructions: {
+      type: "boolean",
+      label: "Agent instructions",
+      description: "Inject the standing Thread Pages instruction into every eligible new session.",
+      default: false,
+    },
+    agentInstructionText: {
+      type: "string",
+      label: "Agent instruction text",
+      description: "What eligible new sessions receive when Agent instructions is on. Changing it affects future sessions only.",
+      experimental_multiline: true,
+      default: DEFAULT_AGENT_INSTRUCTION,
+    },
+    pageSeedHtml: {
+      type: "string",
+      label: "New-page seed",
+      description: "The complete HTML a new page starts from. {{TITLE}} is replaced, escaped. Existing pages are never rewritten.",
+      experimental_multiline: true,
+      default: DEFAULT_PAGE_SEED,
+    },
+    workingLabel: {
+      type: "string",
+      label: "Working indicator text",
+      description: "Shown in the page header while the owning session is mid-turn. Blank hides the indicator.",
+      default: DEFAULT_WORKING_LABEL,
+    },
+    homeSessionId: {
+      type: "string",
+      label: "Home page session",
+      description: "The session whose page is home; every other page links back to it. Set with `bb thread-page home`.",
+      default: "",
+    },
+  });
+  let current = normalize(await handle.get());
+  handle.onChange((next) => {
+    current = normalize(next);
+  });
+  return {
+    current: () => current,
+    async set(values) {
+      current = normalize(await handle.experimental_set(values));
+      return current;
+    },
+  };
+}
+
+function normalize(values: { agentInstructions: boolean; agentInstructionText: string; pageSeedHtml: string; workingLabel: string; homeSessionId: string }): Settings {
+  return {
+    agentInstructions: values.agentInstructions === true,
+    agentInstructionText: values.agentInstructionText,
+    pageSeedHtml: values.pageSeedHtml,
+    workingLabel: values.workingLabel.trim(),
+    homeSessionId: values.homeSessionId.trim(),
+  };
+}

package/src/domain/capabilities/contract.ts

@@ -0,0 +1,48 @@
+import type { JsonValue, Validation } from "../json/strict-json.ts";
+
+/**
+ * What every capability declares. spec R5.1
+ *
+ * A spec is pure: it names the capability, classes its effect, and validates
+ * its parameters and its result. Execution and confirmation wording live in
+ * the server-side handler, which is the only place with host access.
+ */
+/**
+ * `reader-state` changes only what the reader sees about a session — its
+ * read mark — never the session's work; it is not confirmed. spec R5.7a
+ */
+export const EFFECT_CLASSES = ["read", "own-session-write", "cross-session-write", "destructive", "navigation", "device", "reader-state"] as const;
+export type EffectClass = (typeof EFFECT_CLASSES)[number];
+
+/** Effects that must be confirmed in trusted chrome. spec R5.7 */
+export const CONFIRMED_EFFECTS: ReadonlySet<EffectClass> = new Set(["cross-session-write", "destructive", "device"]);
+
+export interface CapabilityDoc {
+  /** One paragraph on the parameters, for the guide. */
+  readonly params: string;
+  /** One paragraph on the result, for the guide. */
+  readonly result: string;
+  /** Anything an author must know: refusals, defaults, confirmation wording. */
+  readonly notes?: string;
+}
+
+export interface CapabilitySpec<Params = unknown, Result = unknown> {
+  readonly method: string;
+  readonly description: string;
+  readonly effect: EffectClass;
+  readonly confirmed: boolean;
+  /** `false` means the contract exists but the host does not implement it: `unknown_method`. spec R5.6 */
+  readonly implemented: boolean;
+  readonly validateParams: (value: JsonValue | undefined) => Validation<Params>;
+  readonly validateResult: (value: unknown) => Validation<Result>;
+  readonly doc: CapabilityDoc;
+}
+
+export type AnyCapabilitySpec = CapabilitySpec<any, any>;
+
+/** What `context.get` reports about one capability. spec R5.9 */
+export interface CapabilityDescriptor {
+  readonly method: string;
+  readonly effect: EffectClass;
+  readonly confirmation: "none" | "required";
+}

package/src/domain/capabilities/index.ts

@@ -0,0 +1,10 @@
+import { createRegistry } from "./registry.ts";
+import { ALL_CAPABILITIES } from "./specs.ts";
+
+export * from "./contract.ts";
+export * from "./protocol.ts";
+export * from "./registry.ts";
+export * from "./specs.ts";
+
+/** The registry the host serves: every spec, with `implemented` deciding the roster. */
+export const capabilityRegistry = createRegistry(ALL_CAPABILITIES);

package/src/domain/capabilities/protocol.ts

@@ -0,0 +1,112 @@
+import { boundedMessage, isBridgeErrorCode, PageError, type BridgeErrorCode } from "../errors.ts";
+import { isMethodName, isRequestId, isRevision } from "../ids.ts";
+import { isJsonObject, validateJson, type JsonValue } from "../json/strict-json.ts";
+import { LIMITS } from "../limits.ts";
+import type { CapabilityRegistry } from "./registry.ts";
+import type { AnyCapabilitySpec } from "./contract.ts";
+
+/**
+ * The bridge protocol: what a page sends over the port and what it gets back.
+ * Version 1. spec R3.9, R4.28, R5.38
+ */
+export const BRIDGE_PROTOCOL_VERSION = 1 as const;
+
+export interface BridgeRequest {
+  readonly v: 1;
+  readonly id: string;
+  readonly method: string;
+  readonly params: JsonValue;
+  readonly pageRevision: string;
+}
+
+export interface BridgeSuccess {
+  readonly v: 1;
+  readonly id: string;
+  readonly ok: true;
+  readonly result: JsonValue;
+}
+
+export interface BridgeFailure {
+  readonly v: 1;
+  readonly id: string;
+  readonly ok: false;
+  readonly error: { readonly code: BridgeErrorCode; readonly message: string };
+}
+
+export type BridgeResponse = BridgeSuccess | BridgeFailure;
+
+/** What the shell receives from `POST /bridge`. */
+export type BridgeTransport =
+  | { readonly response: BridgeResponse; readonly navigate?: NavigationDirective }
+  | { readonly confirm: { readonly requestId: string; readonly summary: string; readonly challenge: string } };
+
+/** A host-validated destination the trusted shell navigates to. spec R5.29–R5.34 */
+export type NavigationDirective =
+  | { readonly kind: "page"; readonly url: string }
+  | { readonly kind: "host"; readonly url: string }
+  | { readonly kind: "external"; readonly url: string };
+
+export function decodeBridgeRequest(input: unknown): BridgeRequest {
+  const checked = validateJson(input);
+  if (!checked.ok) {
+    const tooLarge = checked.issues.some((issue) => issue.code === "too_large");
+    throw new PageError(tooLarge ? "request_too_large" : "invalid_request", tooLarge ? "Bridge request is too large" : "Bridge request is not strict JSON");
+  }
+  const value = checked.value;
+  if (!isJsonObject(value)) throw new PageError("invalid_request", "Bridge request must be an object");
+  const keys = Object.keys(value).sort().join(",");
+  if (keys !== "id,method,pageRevision,params,v") throw new PageError("invalid_request", "Bridge request has the wrong shape");
+  if (value.v !== BRIDGE_PROTOCOL_VERSION) throw new PageError("unsupported_version", "Unsupported bridge protocol version");
+  if (!isRequestId(value.id)) throw new PageError("invalid_request", "Invalid request id");
+  if (!isMethodName(value.method)) throw new PageError("invalid_request", "Invalid method name");
+  if (!isRevision(value.pageRevision)) throw new PageError("invalid_request", "Invalid page revision");
+  return { v: 1, id: value.id, method: value.method, params: value.params as JsonValue, pageRevision: value.pageRevision };
+}
+
+export function safeRequestId(value: unknown): string {
+  return isRequestId(value) ? value : "invalid";
+}
+
+export function failure(id: unknown, code: BridgeErrorCode, message: string): BridgeFailure {
+  return { v: 1, id: safeRequestId(id), ok: false, error: { code, message: boundedMessage(message) } };
+}
+
+export function failureFromError(id: unknown, error: unknown): BridgeFailure {
+  if (PageError.is(error) && isBridgeErrorCode(error.code)) return failure(id, error.code, error.message);
+  return failure(id, "handler_error", "Could not execute the page action.");
+}
+
+export interface ResolvedInvocation<Params = unknown> {
+  readonly request: BridgeRequest;
+  readonly spec: AnyCapabilitySpec;
+  readonly params: Params;
+}
+
+/**
+ * Looks a request up in the registry and validates its parameters. Stale
+ * revisions are refused before the method is even looked at. spec R2.13
+ */
+export function resolveInvocation(request: BridgeRequest, registry: CapabilityRegistry, currentRevision: string): ResolvedInvocation {
+  if (request.pageRevision !== currentRevision) throw new PageError("stale_page", "This page changed; reload it before responding.");
+  const spec = registry.get(request.method);
+  if (!spec || !spec.implemented) throw new PageError("unknown_method", `Unknown capability: ${request.method}`);
+  const params = spec.validateParams(request.params);
+  if (!params.ok) {
+    const first = params.issues[0];
+    throw new PageError("invalid_params", `Invalid parameters for ${spec.method}${first ? ` at ${first.path}: ${first.message}` : ""}`);
+  }
+  return { request, spec, params: params.value };
+}
+
+/** Projects a handler result through the spec's validator into a response. spec R5.3 */
+export function completeInvocation(invocation: ResolvedInvocation, result: unknown): BridgeResponse {
+  const projected = invocation.spec.validateResult(result);
+  if (!projected.ok) return failure(invocation.request.id, "invalid_result", `Invalid result for ${invocation.spec.method}`);
+  const json = validateJson(projected.value);
+  if (!json.ok) return failure(invocation.request.id, "invalid_result", `Result for ${invocation.spec.method} is not strict JSON`);
+  const response: BridgeSuccess = { v: 1, id: invocation.request.id, ok: true, result: json.value };
+  if (Buffer.byteLength(JSON.stringify(response), "utf8") > LIMITS.capabilityPayloadBytes) {
+    return failure(invocation.request.id, "response_too_large", "Bridge response is too large");
+  }
+  return response;
+}

package/src/domain/capabilities/registry.ts

@@ -0,0 +1,48 @@
+import { isMethodName } from "../ids.ts";
+import { CONFIRMED_EFFECTS, EFFECT_CLASSES, type AnyCapabilitySpec, type CapabilityDescriptor } from "./contract.ts";
+
+export interface CapabilityRegistry {
+  get(method: string): AnyCapabilitySpec | undefined;
+  list(): readonly AnyCapabilitySpec[];
+  /** The roster a page may discover: implemented capabilities only. spec R5.9 */
+  descriptors(): readonly CapabilityDescriptor[];
+}
+
+/**
+ * Builds a registry and enforces the invariants no capability may break:
+ * unique, well-formed names; a known effect class; confirmation exactly where
+ * the effect class demands it (navigation may go either way). spec R5.7, R5.8
+ */
+export function createRegistry(specs: readonly AnyCapabilitySpec[]): CapabilityRegistry {
+  const byMethod = new Map<string, AnyCapabilitySpec>();
+  for (const spec of specs) {
+    if (!isMethodName(spec.method)) throw new TypeError(`Invalid capability name: ${spec.method}`);
+    if (byMethod.has(spec.method)) throw new TypeError(`Duplicate capability: ${spec.method}`);
+    if (!EFFECT_CLASSES.includes(spec.effect)) throw new TypeError(`Invalid effect for ${spec.method}`);
+    if (CONFIRMED_EFFECTS.has(spec.effect) && !spec.confirmed) {
+      throw new TypeError(`${spec.method} has a ${spec.effect} effect and must be confirmed`);
+    }
+    if ((spec.effect === "read" || spec.effect === "own-session-write" || spec.effect === "reader-state") && spec.confirmed) {
+      throw new TypeError(`${spec.method} is a ${spec.effect} and must not be confirmed`);
+    }
+    if (typeof spec.description !== "string" || spec.description.trim().length === 0 || spec.description.length > 240) {
+      throw new TypeError(`Invalid description for ${spec.method}`);
+    }
+    byMethod.set(spec.method, Object.freeze({ ...spec }));
+  }
+  const list = Object.freeze([...byMethod.values()]);
+  const descriptors = Object.freeze(
+    list
+      .filter((spec) => spec.implemented)
+      .map((spec): CapabilityDescriptor => ({
+        method: spec.method,
+        effect: spec.effect,
+        confirmation: spec.confirmed ? "required" : "none",
+      })),
+  );
+  return Object.freeze({
+    get: (method: string) => byMethod.get(method),
+    list: () => list,
+    descriptors: () => descriptors,
+  });
+}

package/src/domain/capabilities/schema.ts

@@ -0,0 +1,198 @@
+import { invalid, isJsonObject, pathForKey, valid, validateJson, type Issue, type JsonLimits, type JsonValue, type Validation } from "../json/strict-json.ts";
+
+/**
+ * A tiny typed schema language for capability parameters and results.
+ *
+ * Every object is exact: unknown keys are rejected, required keys must be
+ * present, optional keys may be absent (never `undefined`). Strings are
+ * bounded; numbers are integers in a range; JSON blobs carry their own
+ * limits. spec R5.2, R5.3
+ */
+export interface Schema<T> {
+  parse(value: JsonValue | undefined, path: string): Validation<T>;
+}
+
+export interface OptionalSchema<T> extends Schema<T> {
+  readonly isOptional: true;
+}
+
+/** Optional on the wire, always present after parsing. */
+export interface DefaultedSchema<T> extends OptionalSchema<T> {
+  readonly hasDefault: true;
+}
+
+export type Infer<S> = S extends Schema<infer T> ? T : never;
+
+type Shape = Record<string, Schema<unknown>>;
+type OptionalKeys<S extends Shape> = {
+  [K in keyof S]: S[K] extends DefaultedSchema<unknown> ? never : S[K] extends OptionalSchema<unknown> ? K : never;
+}[keyof S];
+type RequiredKeys<S extends Shape> = Exclude<keyof S, OptionalKeys<S>>;
+export type InferShape<S extends Shape> = { [K in RequiredKeys<S>]: Infer<S[K]> } & { [K in OptionalKeys<S>]?: Infer<S[K]> };
+
+function issues<T>(list: readonly Issue[]): Validation<T> {
+  return { ok: false, issues: list };
+}
+
+export function string(options: { min?: number; max: number; pattern?: RegExp; label?: string }): Schema<string> {
+  const label = options.label ?? "String";
+  return {
+    parse(value, path) {
+      if (typeof value !== "string") return invalid(path, `${label}: expected a string`, "invalid_type");
+      const min = options.min ?? 0;
+      if (value.length < min || value.length > options.max) {
+        return invalid(path, `${label}: length must be ${min}–${options.max}`, "too_large");
+      }
+      if (options.pattern && !options.pattern.test(value)) return invalid(path, `${label}: invalid format`);
+      return valid(value);
+    },
+  };
+}
+
+export function integer(min: number, max: number, label = "Integer"): Schema<number> {
+  return {
+    parse(value, path) {
+      if (typeof value !== "number" || !Number.isSafeInteger(value) || value < min || value > max) {
+        return invalid(path, `${label}: expected an integer from ${min} to ${max}`);
+      }
+      return valid(value);
+    },
+  };
+}
+
+export function boolean(label = "Boolean"): Schema<boolean> {
+  return {
+    parse(value, path) {
+      return typeof value === "boolean" ? valid(value) : invalid(path, `${label}: expected a boolean`, "invalid_type");
+    },
+  };
+}
+
+export function literal<const T extends readonly (string | number | boolean | null)[]>(values: T, label = "Value"): Schema<T[number]> {
+  return {
+    parse(value, path) {
+      return (values as readonly unknown[]).includes(value)
+        ? valid(value as T[number])
+        : invalid(path, `${label}: expected one of ${values.map((item) => JSON.stringify(item)).join(", ")}`);
+    },
+  };
+}
+
+export function nullable<T>(schema: Schema<T>): Schema<T | null> {
+  return {
+    parse(value, path) {
+      return value === null ? valid(null) : schema.parse(value, path);
+    },
+  };
+}
+
+export function optional<T>(schema: Schema<T>): OptionalSchema<T> {
+  return { isOptional: true, parse: (value, path) => schema.parse(value, path) };
+}
+
+/** Optional with a default applied when the key is absent. */
+export function withDefault<T>(schema: Schema<T>, fallback: T): DefaultedSchema<T> {
+  return {
+    isOptional: true,
+    hasDefault: true,
+    parse(value, path) {
+      return value === undefined ? valid(fallback) : schema.parse(value, path);
+    },
+  };
+}
+
+export function array<T>(item: Schema<T>, max: number, label = "List"): Schema<T[]> {
+  return {
+    parse(value, path) {
+      if (!Array.isArray(value)) return invalid(path, `${label}: expected a list`, "invalid_type");
+      if (value.length > max) return invalid(path, `${label}: at most ${max} items`, "too_large");
+      const out: T[] = [];
+      for (let index = 0; index < value.length; index += 1) {
+        const parsed = item.parse(value[index], `${path}[${index}]`);
+        if (!parsed.ok) return issues(parsed.issues);
+        out.push(parsed.value);
+      }
+      return valid(out);
+    },
+  };
+}
+
+export function object<S extends Shape>(shape: S, label = "Object"): Schema<InferShape<S>> {
+  const keys = Object.keys(shape);
+  const known = new Set(keys);
+  return {
+    parse(value, path) {
+      if (!isJsonObject(value)) return invalid(path, `${label}: expected an object`, "invalid_type");
+      for (const key of Object.keys(value)) {
+        if (!known.has(key)) return invalid(pathForKey(path, key), "Unknown key", "unknown_key");
+      }
+      const out: Record<string, unknown> = {};
+      for (const key of keys) {
+        const schema = shape[key] as Schema<unknown> & { isOptional?: boolean };
+        const present = Object.prototype.hasOwnProperty.call(value, key);
+        if (!present) {
+          if (schema.isOptional) {
+            // withDefault schemas yield a value for an absent key; plain optional ones do not.
+            const parsed = schema.parse(undefined, pathForKey(path, key));
+            if (parsed.ok && parsed.value !== undefined) out[key] = parsed.value;
+            continue;
+          }
+          return invalid(pathForKey(path, key), "Missing required key", "missing_key");
+        }
+        const parsed = schema.parse(value[key], pathForKey(path, key));
+        if (!parsed.ok) return issues(parsed.issues);
+        out[key] = parsed.value;
+      }
+      return valid(out as InferShape<S>);
+    },
+  };
+}
+
+/** `null`, absent, or `{}` all mean "no parameters". */
+export function noParams(): Schema<null> {
+  return {
+    parse(value, path) {
+      if (value === undefined || value === null) return valid(null);
+      if (isJsonObject(value) && Object.keys(value).length === 0) return valid(null);
+      return invalid(path, "This capability takes no parameters", "unknown_key");
+    },
+  };
+}
+
+/** Any strict JSON value within the given limits. */
+export function json(limits: JsonLimits = {}, label = "Value"): Schema<JsonValue> {
+  return {
+    parse(value, path) {
+      if (value === undefined) return invalid(path, `${label}: missing`, "missing_key");
+      const checked = validateJson(value, limits);
+      if (!checked.ok) {
+        const first = checked.issues[0];
+        return first ? invalid(path === "$" ? first.path : `${path}${first.path.slice(1)}`, first.message, first.code) : checked;
+      }
+      return checked;
+    },
+  };
+}
+
+export function union<A, B>(first: Schema<A>, second: Schema<B>, label = "Value"): Schema<A | B> {
+  return {
+    parse(value, path) {
+      const a = first.parse(value, path);
+      if (a.ok) return a;
+      const b = second.parse(value, path);
+      if (b.ok) return b;
+      return invalid(path, `${label}: did not match any accepted shape`);
+    },
+  };
+}
+
+export function refine<T>(schema: Schema<T>, check: (value: T) => string | null): Schema<T> {
+  return {
+    parse(value, path) {
+      const parsed = schema.parse(value, path);
+      if (!parsed.ok) return parsed;
+      const problem = check(parsed.value);
+      return problem ? invalid(path, problem) : parsed;
+    },
+  };
+}