gbs-add-block 2.0.4 → 2.3.0

package/source/beta-components/shared/core/agent/history.ts

@@ -0,0 +1,120 @@
+/*
+ * Undo by snapshot, not by inverse.
+ *
+ * Writing an inverse for every operation means writing it again for every
+ * operation added later, and getting it wrong once is a corrupted document.
+ * When the state is small and serialisable — which is the precondition for a
+ * component to be agent-operable at all — storing it whole is both cheaper to
+ * maintain and exactly correct.
+ *
+ * The history never reads or writes state itself; it is handed `read` and
+ * `write` and knows nothing about what is in there.
+ */
+
+export interface SnapshotEntry<S> {
+  /** Human-readable, for an audit trail: "Filter Revenue greater than 100000". */
+  label: string;
+  before: S;
+  after: S;
+  at: number;
+}
+
+export interface SnapshotHistoryOptions<S> {
+  read(): S;
+  write(snapshot: S): void;
+  /** Entries kept. Older ones fall off the back. Default 50. */
+  limit?: number;
+  /** Injected in tests so entries are comparable. Defaults to `Date.now`. */
+  now?(): number;
+}
+
+export interface SnapshotHistory<S> {
+  /**
+   * Snapshots, runs `apply`, snapshots again, and records the pair. A run that
+   * leaves the state untouched records nothing, so a no-op never costs an undo.
+   *
+   * An `apply` that returns a promise is awaited before the second snapshot is
+   * taken, so an operation that finishes asynchronously is still recorded with
+   * the state it actually produced.
+   */
+  record<R>(label: string, apply: () => R): R;
+  undo(): boolean;
+  redo(): boolean;
+  canUndo(): boolean;
+  canRedo(): boolean;
+  /** Oldest first. The entry at `index() - 1` is the one `undo` would reverse. */
+  entries(): readonly SnapshotEntry<S>[];
+  index(): number;
+  clear(): void;
+  subscribe(listener: () => void): () => void;
+}
+
+export function createSnapshotHistory<S>(options: SnapshotHistoryOptions<S>): SnapshotHistory<S> {
+  const { read, write, limit = 50, now = Date.now } = options;
+  let entries: SnapshotEntry<S>[] = [];
+  let index = 0;
+  const listeners = new Set<() => void>();
+
+  const notify = () => {
+    for (const listener of listeners) listener();
+  };
+
+  return {
+    record(label, apply) {
+      const before = read();
+
+      const commit = () => {
+        const after = read();
+        if (Object.is(before, after)) return;
+        // A new branch discards whatever redo was holding.
+        entries = [...entries.slice(0, index), { label, before, after, at: now() }];
+        if (entries.length > limit) entries = entries.slice(entries.length - limit);
+        index = entries.length;
+        notify();
+      };
+
+      const result = apply();
+      if (result instanceof Promise) {
+        return result.then((value) => {
+          commit();
+          return value;
+        }) as typeof result;
+      }
+      commit();
+      return result;
+    },
+
+    undo() {
+      if (index === 0) return false;
+      index -= 1;
+      write(entries[index].before);
+      notify();
+      return true;
+    },
+
+    redo() {
+      if (index >= entries.length) return false;
+      write(entries[index].after);
+      index += 1;
+      notify();
+      return true;
+    },
+
+    canUndo: () => index > 0,
+    canRedo: () => index < entries.length,
+    entries: () => entries,
+    index: () => index,
+
+    clear() {
+      if (entries.length === 0) return;
+      entries = [];
+      index = 0;
+      notify();
+    },
+
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+  };
+}

package/source/beta-components/shared/core/agent/index.ts

@@ -0,0 +1,46 @@
+/*
+ * The component-agnostic half of the agent runtime. Nothing here knows about
+ * a grid, a date picker, or React.
+ */
+
+export type {
+  ConfirmRequest,
+  ExecutionContext,
+  ExecutorRegistry,
+  JsonSchema,
+  JsonSchemaType,
+  OperationDefinition,
+  OperationExecutor,
+  RegisteredExecutor,
+  ValidationIssue,
+  ValidationLayer,
+  ValidationResult,
+} from "./types";
+export { fail, ok } from "./types";
+export { checkSchema, type SchemaIssue } from "./schema";
+export {
+  createSnapshotHistory,
+  type SnapshotEntry,
+  type SnapshotHistory,
+  type SnapshotHistoryOptions,
+} from "./history";
+export { parseQuantity, type ParseQuantityOptions, type Quantity } from "./numbers";
+export {
+  buildToolInputSchema,
+  registerAgentTool,
+  webmcpAvailable,
+  type ModelContext,
+  type ProjectableAgent,
+  type ProjectedCommand,
+  type ProjectedOutcome,
+  type RegisterAgentToolOptions,
+  type RegistrationResult,
+  type ToolCallLog,
+  type ToolResultPayload,
+} from "./webmcp";
+export type {
+  AgentAdapter,
+  AgentProposalRequest,
+  AskOutcome,
+  AskPhase,
+} from "./adapter";

package/source/beta-components/shared/core/agent/numbers.ts

@@ -0,0 +1,217 @@
+/*
+ * Reading a number the way a person wrote it.
+ *
+ * "1 lakh", "₹1,00,000", "20%", "1.5k", "(2,400)" all denote numbers, and a
+ * language model should not be the thing that converts them — it will be
+ * confidently wrong about crore once in a while, and there is no way to tell
+ * which time. This is deterministic code with a test for every form it claims
+ * to read, which is what the coercion layer of the validator is for.
+ *
+ * Indian digit grouping (1,00,000) needs no special case: grouping separators
+ * are stripped wholesale, so 1,00,000 and 100,000 land on the same number.
+ */
+
+export interface Quantity {
+  value: number;
+  /** The written form carried a percent sign or the word "percent". */
+  percent: boolean;
+  /** ISO code for the currency marker found, if any. */
+  currency: string | null;
+  /** The scale word that was applied, e.g. "lakh". Null when none was. */
+  scale: string | null;
+}
+
+const CURRENCY_SYMBOLS: Record<string, string> = {
+  "₹": "INR", // ₹
+  $: "USD",
+  "€": "EUR", // €
+  "£": "GBP", // £
+  "¥": "JPY", // ¥
+};
+
+const CURRENCY_WORDS: Record<string, string> = {
+  inr: "INR",
+  rs: "INR",
+  rupee: "INR",
+  rupees: "INR",
+  usd: "USD",
+  dollar: "USD",
+  dollars: "USD",
+  eur: "EUR",
+  euro: "EUR",
+  euros: "EUR",
+  gbp: "GBP",
+  pound: "GBP",
+  pounds: "GBP",
+};
+
+/**
+ * Scale words, longest first so "crores" is consumed before "cr" can match a
+ * prefix of it.
+ */
+const SCALES: ReadonlyArray<readonly [string, number]> = [
+  ["crores", 1e7],
+  ["crore", 1e7],
+  ["cr", 1e7],
+  ["lakhs", 1e5],
+  ["lakh", 1e5],
+  ["lacs", 1e5],
+  ["lac", 1e5],
+  ["billion", 1e9],
+  ["billions", 1e9],
+  ["bn", 1e9],
+  ["million", 1e6],
+  ["millions", 1e6],
+  ["mn", 1e6],
+  ["thousand", 1e3],
+  ["thousands", 1e3],
+  ["hundred", 1e2],
+  ["hundreds", 1e2],
+  ["k", 1e3],
+  ["m", 1e6],
+  ["b", 1e9],
+];
+
+const PERCENT_WORDS = ["percent", "percentage", "pct", "pc"];
+
+/*
+ * Numbers written as words.
+ *
+ * "Revenue above one crore" is a sentence people type, and it used to fail
+ * here — which was worse than it sounds, because the layer above tells a model
+ * to pass quantities through *exactly as written* rather than convert them. So
+ * the model did as it was told and the conversion it had been relieved of
+ * simply never happened.
+ *
+ * Deliberately bounded: cardinals up to ninety-nine, and the scale words
+ * already in `SCALES` do the rest ("five hundred", "ten lakh", "two crore").
+ * `a`/`an` are left out — "a crore" is natural Indian English, but mapping a
+ * bare article to 1 would turn any stray "a" into a number, and silently
+ * reading junk as 1 is worse than refusing it.
+ */
+const ONES: Record<string, number> = {
+  zero: 0, one: 1, two: 2, three: 3, four: 4, five: 5, six: 6, seven: 7,
+  eight: 8, nine: 9, ten: 10, eleven: 11, twelve: 12, thirteen: 13,
+  fourteen: 14, fifteen: 15, sixteen: 16, seventeen: 17, eighteen: 18,
+  nineteen: 19,
+};
+
+const TENS: Record<string, number> = {
+  twenty: 20, thirty: 30, forty: 40, fifty: 50,
+  sixty: 60, seventy: 70, eighty: 80, ninety: 90,
+};
+
+/** Replaces number words with digits, so the rest of the parser sees digits. */
+function digitiseWords(text: string): string {
+  const tens = Object.keys(TENS).join("|");
+  const ones = Object.keys(ONES).join("|");
+
+  return text
+    // Compounds first: "twenty five" and "twenty-five" are one number.
+    .replace(new RegExp(`\\b(${tens})[\\s-](${ones})\\b`, "g"), (_, ten, one) =>
+      String(TENS[ten] + ONES[one]),
+    )
+    .replace(new RegExp(`\\b(${tens})\\b`, "g"), (word) => String(TENS[word]))
+    .replace(new RegExp(`\\b(${ones})\\b`, "g"), (word) => String(ONES[word]));
+}
+
+export interface ParseQuantityOptions {
+  /** Which character separates the fractional part. Default `"."`. */
+  decimal?: "." | ",";
+}
+
+/**
+ * Reads a written quantity, or returns null when the text is not one.
+ *
+ * Null means "this is not a number", which the caller should surface as a
+ * validation failure rather than silently coercing to 0 or NaN.
+ */
+export function parseQuantity(
+  input: string | number,
+  options: ParseQuantityOptions = {},
+): Quantity | null {
+  if (typeof input === "number") {
+    return Number.isFinite(input)
+      ? { value: input, percent: false, currency: null, scale: null }
+      : null;
+  }
+
+  let text = digitiseWords(input.trim().toLowerCase());
+  if (text === "") return null;
+
+  let negative = false;
+  // Accountants' parentheses.
+  if (text.startsWith("(") && text.endsWith(")")) {
+    negative = true;
+    text = text.slice(1, -1).trim();
+  }
+
+  let currency: string | null = null;
+  for (const [symbol, code] of Object.entries(CURRENCY_SYMBOLS)) {
+    if (text.includes(symbol)) {
+      currency = code;
+      text = text.split(symbol).join(" ");
+    }
+  }
+
+  let percent = false;
+  if (text.includes("%")) {
+    percent = true;
+    text = text.split("%").join(" ");
+  }
+
+  // Split off alphabetic words so currency and scale can be matched exactly
+  // rather than by substring, which would see "lakh" inside "lakhsomething".
+  const words = text.match(/[a-z.]+/g) ?? [];
+  for (const word of words) {
+    const bare = word.replace(/\.$/, "");
+    if (CURRENCY_WORDS[bare]) {
+      currency ??= CURRENCY_WORDS[bare];
+      text = text.replace(word, " ");
+    } else if (PERCENT_WORDS.includes(bare)) {
+      percent = true;
+      text = text.replace(word, " ");
+    }
+  }
+
+  let scale: string | null = null;
+  let multiplier = 1;
+  for (const [word, factor] of SCALES) {
+    // Either a separate word, or glued to the digits as in "1.5k".
+    const pattern = new RegExp(`(^|[\\s\\d.])${word}\\s*$`);
+    if (pattern.test(text)) {
+      scale = word;
+      multiplier = factor;
+      text = text.replace(new RegExp(`${word}\\s*$`), " ");
+      break;
+    }
+  }
+
+  const decimal = options.decimal ?? ".";
+  let digits = text.replace(/\s+/g, "");
+  if (digits.startsWith("-")) {
+    negative = true;
+    digits = digits.slice(1);
+  } else if (digits.startsWith("+")) {
+    digits = digits.slice(1);
+  }
+
+  if (decimal === ",") {
+    digits = digits.split(".").join("");
+    digits = digits.replace(",", ".");
+  } else {
+    digits = digits.split(",").join("");
+  }
+
+  if (digits === "" || !/^\d*\.?\d*$/.test(digits) || !/\d/.test(digits)) return null;
+
+  const magnitude = Number(digits);
+  if (!Number.isFinite(magnitude)) return null;
+
+  const value = (negative ? -1 : 1) * magnitude * multiplier;
+  // Scaling by 1e5 and friends drifts in binary floating point; the inputs are
+  // human-written, so rounding back to a sane precision is the honest answer.
+  const rounded = multiplier === 1 ? value : Number(value.toPrecision(15));
+
+  return { value: rounded, percent, currency, scale };
+}

package/source/beta-components/shared/core/agent/schema.ts

@@ -0,0 +1,180 @@
+/*
+ * A JSON Schema checker for the subset in `types.ts`.
+ *
+ * Written rather than installed, for the same reason the rest of the library
+ * ships no dependencies: a component you copy into your project must not drag
+ * a validator in with it. The subset is small enough that the whole thing fits
+ * on one screen, and large enough to express every intent schema we generate.
+ *
+ * `oneOf` is where the care goes. A union of discriminated branches that all
+ * fail produces one useless error ("matched no branch") unless you work out
+ * which branch the caller *meant*. So branches are scored by how many of their
+ * `const` discriminators matched, and the errors reported come from the best
+ * candidate.
+ */
+
+import type { JsonSchema, JsonSchemaType } from "./types";
+
+export interface SchemaIssue {
+  path: string;
+  code: string;
+  message: string;
+}
+
+const typeOf = (value: unknown): JsonSchemaType => {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  if (typeof value === "number") return Number.isInteger(value) ? "integer" : "number";
+  if (typeof value === "string") return "string";
+  if (typeof value === "boolean") return "boolean";
+  return "object";
+};
+
+const matchesType = (value: unknown, expected: JsonSchemaType): boolean => {
+  const actual = typeOf(value);
+  if (expected === "number") return actual === "number" || actual === "integer";
+  return actual === expected;
+};
+
+const show = (value: unknown): string =>
+  typeof value === "string" ? JSON.stringify(value) : String(value);
+
+const join = (path: string, key: string | number): string =>
+  typeof key === "number" ? `${path}[${key}]` : path === "" ? key : `${path}.${key}`;
+
+/** Every `const`-valued property this schema pins, for scoring `oneOf` branches. */
+function discriminators(schema: JsonSchema): [string, unknown][] {
+  const out: [string, unknown][] = [];
+  for (const [key, child] of Object.entries(schema.properties ?? {})) {
+    if (child.const !== undefined) out.push([key, child.const]);
+  }
+  return out;
+}
+
+function scoreBranch(value: unknown, schema: JsonSchema): number {
+  if (typeOf(value) !== "object") return 0;
+  const record = value as Record<string, unknown>;
+  let score = 0;
+  for (const [key, expected] of discriminators(schema)) {
+    if (record[key] === expected) score += 1;
+  }
+  return score;
+}
+
+function checkInto(out: SchemaIssue[], value: unknown, schema: JsonSchema, path: string): void {
+  const add = (code: string, message: string, at = path) => out.push({ path: at, code, message });
+
+  if (schema.oneOf) {
+    const results = schema.oneOf.map((branch) => {
+      const issues: SchemaIssue[] = [];
+      checkInto(issues, value, branch, path);
+      return { branch, issues, score: scoreBranch(value, branch) };
+    });
+    const passing = results.filter((r) => r.issues.length === 0);
+    if (passing.length === 1) return;
+    if (passing.length > 1) {
+      add("ambiguous-union", "value matches more than one schema branch");
+      return;
+    }
+    // Prefer the branch whose discriminators matched; fall back to the nearest miss.
+    const best = results.reduce((a, b) =>
+      b.score > a.score || (b.score === a.score && b.issues.length < a.issues.length) ? b : a,
+    );
+    if (best.score === 0) {
+      add("no-matching-branch", "value does not match any permitted shape");
+      return;
+    }
+    out.push(...best.issues);
+    return;
+  }
+
+  if (schema.anyOf) {
+    const passes = schema.anyOf.some((branch) => {
+      const issues: SchemaIssue[] = [];
+      checkInto(issues, value, branch, path);
+      return issues.length === 0;
+    });
+    if (!passes) add("no-matching-branch", "value does not match any permitted shape");
+    return;
+  }
+
+  if (schema.const !== undefined && value !== schema.const) {
+    add("const", `expected ${show(schema.const)}`);
+    return;
+  }
+
+  if (schema.enum && !schema.enum.some((option) => option === value)) {
+    add("enum", `expected one of ${schema.enum.map(show).join(", ")}, got ${show(value)}`);
+    return;
+  }
+
+  if (schema.type !== undefined) {
+    const expected = Array.isArray(schema.type) ? schema.type : [schema.type];
+    if (!expected.some((t) => matchesType(value, t))) {
+      add("type", `expected ${expected.join(" or ")}, got ${typeOf(value)}`);
+      return;
+    }
+  }
+
+  if (typeof value === "number") {
+    if (schema.minimum !== undefined && value < schema.minimum)
+      add("minimum", `must be at least ${schema.minimum}`);
+    if (schema.maximum !== undefined && value > schema.maximum)
+      add("maximum", `must be at most ${schema.maximum}`);
+  }
+
+  if (typeof value === "string") {
+    if (schema.minLength !== undefined && value.length < schema.minLength)
+      add("min-length", `must be at least ${schema.minLength} characters`);
+    if (schema.maxLength !== undefined && value.length > schema.maxLength)
+      add("max-length", `must be at most ${schema.maxLength} characters`);
+    /*
+     * `pattern` compiles to a RegExp, so a catastrophic one is a denial of
+     * service. Every schema this library generates comes from a live runtime
+     * contract and carries no pattern at all. If you validate against a schema
+     * that travelled with an installed component — a passport's
+     * `operations[].input`, say — strip `pattern` first.
+     */
+    if (schema.pattern !== undefined && !new RegExp(schema.pattern).test(value))
+      add("pattern", `must match ${schema.pattern}`);
+  }
+
+  if (Array.isArray(value)) {
+    if (schema.minItems !== undefined && value.length < schema.minItems)
+      add("min-items", `needs at least ${schema.minItems} item(s)`);
+    if (schema.maxItems !== undefined && value.length > schema.maxItems)
+      add("max-items", `takes at most ${schema.maxItems} item(s)`);
+    if (schema.items) {
+      value.forEach((item, i) => checkInto(out, item, schema.items!, join(path, i)));
+    }
+    return;
+  }
+
+  if (typeOf(value) === "object") {
+    const record = value as Record<string, unknown>;
+    for (const key of schema.required ?? []) {
+      if (record[key] === undefined) add("required", `"${key}" is required`, join(path, key));
+    }
+    for (const [key, child] of Object.entries(schema.properties ?? {})) {
+      if (record[key] !== undefined) checkInto(out, record[key], child, join(path, key));
+    }
+    if (schema.additionalProperties === false) {
+      const known = new Set(Object.keys(schema.properties ?? {}));
+      for (const key of Object.keys(record)) {
+        if (!known.has(key)) add("additional-property", `"${key}" is not a known field`, join(path, key));
+      }
+    } else if (schema.additionalProperties && typeof schema.additionalProperties === "object") {
+      const known = new Set(Object.keys(schema.properties ?? {}));
+      for (const [key, item] of Object.entries(record)) {
+        if (!known.has(key)) checkInto(out, item, schema.additionalProperties, join(path, key));
+      }
+    }
+  }
+}
+
+/** Every way `value` fails `schema`. An empty array means it passed. */
+export function checkSchema(value: unknown, schema: JsonSchema): SchemaIssue[] {
+  const out: SchemaIssue[] = [];
+  checkInto(out, value, schema, "");
+  return out;
+}