gbs-add-block 2.1.0 → 2.3.0

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

@@ -0,0 +1,169 @@
+/*
+ * The vocabulary an agent-operable component shares with its callers.
+ *
+ * Four things are kept apart on purpose, because they change for different
+ * reasons and at different times:
+ *
+ *   OperationDefinition  what a component knows how to do        (static, from the passport)
+ *   RuntimeContract      what this instance can do, right now    (per instance, per render)
+ *   Intent               what the caller is asking for           (untrusted input)
+ *   OperationExecutor    how this instance actually performs it  (per application)
+ *
+ * The last one is the reason this file exists. An operation must not be
+ * welded to an imperative handle: a grid performs `filter` by calling
+ * `GridApi.setFilter`, while a controlled component would perform its
+ * equivalent by calling the host's `onChange`. Same operation, same schema,
+ * different executor. Nothing here mentions either.
+ */
+
+// ---------------------------------------------------------------- JSON Schema
+
+/**
+ * The slice of JSON Schema this library emits and checks. Deliberately small:
+ * it is what a constrained decoder and a validator both need, and no more.
+ */
+export interface JsonSchema {
+  $schema?: string;
+  title?: string;
+  description?: string;
+  type?: JsonSchemaType | readonly JsonSchemaType[];
+  const?: unknown;
+  enum?: readonly unknown[];
+  properties?: Readonly<Record<string, JsonSchema>>;
+  required?: readonly string[];
+  additionalProperties?: boolean | JsonSchema;
+  items?: JsonSchema;
+  minItems?: number;
+  maxItems?: number;
+  minLength?: number;
+  maxLength?: number;
+  minimum?: number;
+  maximum?: number;
+  pattern?: string;
+  oneOf?: readonly JsonSchema[];
+  anyOf?: readonly JsonSchema[];
+  default?: unknown;
+  examples?: readonly unknown[];
+}
+
+export type JsonSchemaType =
+  | "object"
+  | "array"
+  | "string"
+  | "number"
+  | "integer"
+  | "boolean"
+  | "null";
+
+// ----------------------------------------------------------------- operations
+
+/**
+ * One thing a component can be asked to do. This is the static half of the
+ * contract and mirrors the component's `passport.json` `operations` block.
+ */
+export interface OperationDefinition {
+  readonly name: string;
+  readonly summary: string;
+  /** JSON Schema for the operation's input, minus the `action` discriminator. */
+  readonly input?: JsonSchema;
+  /** Plain-language consequences, for a confirmation prompt. */
+  readonly effects?: readonly string[];
+  /** Whether undoing it is a matter of restoring the previous state. */
+  readonly reversible: boolean;
+  /** Leaves the page: downloads, prints, writes to the clipboard. */
+  readonly requiresConfirmation?: boolean;
+  /**
+   * The imperative method that happens to back this operation, when one does.
+   * Metadata only — never required. An operation performed through host state
+   * has no API method, and that is a normal case, not a gap.
+   */
+  readonly apiMethod?: string;
+}
+
+export interface ExecutionContext<TContract = unknown> {
+  readonly contract: TContract;
+  /** Report what would happen and change nothing. */
+  readonly dryRun: boolean;
+  readonly signal?: AbortSignal;
+}
+
+/**
+ * How one instance performs one operation.
+ *
+ * Implementations close over whatever they need — an imperative handle, a
+ * state setter, a transport — and the rest of the pipeline never learns which.
+ */
+export interface OperationExecutor<TInput, TContract = unknown, TResult = void> {
+  readonly operation: string;
+  /** Set only when `execute` really does call that method. */
+  readonly apiMethod?: string;
+  execute(input: TInput, context: ExecutionContext<TContract>): TResult | Promise<TResult>;
+}
+
+/**
+ * An executor in a heterogeneous registry. `never` as the input type is sound
+ * here: a function taking a specific input is assignable to one taking
+ * `never`, so concrete executors slot in without a cast. Callers cast at the
+ * point of dispatch, where the validator has already proved the shape.
+ */
+export type RegisteredExecutor<TContract = unknown> = OperationExecutor<never, TContract, unknown>;
+
+export type ExecutorRegistry<TContract = unknown> = ReadonlyMap<string, RegisteredExecutor<TContract>>;
+
+// ----------------------------------------------------------------- validation
+
+export type ValidationLayer =
+  | "schema"
+  | "reference"
+  | "coercion"
+  | "policy"
+  | "plausibility";
+
+export interface ValidationIssue {
+  layer: ValidationLayer;
+  /** Stable, machine-readable. Messages may be reworded; codes may not. */
+  code: string;
+  message: string;
+  /** JSON pointer-ish path into the intent, when the issue has a location. */
+  path?: string;
+  suggestion?: string;
+}
+
+/** Something the caller should see and agree to before the command runs. */
+export interface ConfirmRequest {
+  code: string;
+  message: string;
+}
+
+export type ValidationResult<TCommand> =
+  | {
+      ok: true;
+      command: TCommand;
+      /** Non-blocking: coercions applied, plausibility notes. */
+      warnings: ValidationIssue[];
+      confirm: ConfirmRequest | null;
+    }
+  | {
+      ok: false;
+      /** The issue that stopped it, flattened for display. */
+      reason: string;
+      code: string;
+      layer: ValidationLayer;
+      suggestion?: string;
+      issues: ValidationIssue[];
+    };
+
+export const ok = <T>(
+  command: T,
+  warnings: ValidationIssue[] = [],
+  confirm: ConfirmRequest | null = null,
+): ValidationResult<T> => ({ ok: true, command, warnings, confirm });
+
+export const fail = <T>(issue: ValidationIssue, issues: ValidationIssue[] = []): ValidationResult<T> => ({
+  ok: false,
+  reason: issue.message,
+  code: issue.code,
+  layer: issue.layer,
+  ...(issue.suggestion ? { suggestion: issue.suggestion } : {}),
+  issues: issues.length > 0 ? issues : [issue],
+});

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

@@ -0,0 +1,328 @@
+/*
+ * WebMCP projection: exposing an already-validated command boundary to
+ * whatever agent is driving the browser.
+ *
+ * This is an adapter and nothing else. It owns no schema, no semantics and no
+ * execution path. The chain stays:
+ *
+ *   component source → passport → runtime contract → intent schema
+ *     → [this file] → the component's validator → its executors → the component
+ *
+ * Nothing here knows about a grid. A component's agent satisfies
+ * `ProjectableAgent` structurally, and everything component-specific arrives
+ * through `describe` and `summarise`.
+ *
+ * Why one tool and not one per operation: the operation list is not the
+ * agent's interface — the generated intent schema is, because that is where
+ * the contract and the validation layers already meet. Twenty-one operations
+ * exposed separately would be twenty-one schemas to keep in step with a
+ * contract that already describes itself.
+ *
+ * Surface notes, each of which cost a wrong run to learn:
+ *
+ *   - It is `document.modelContext`. `navigator.modelContext` was the early
+ *     spelling and is deprecated since Chromium 150.
+ *   - Chrome hands `inputSchema` to the agent as a JSON *string*, and returns
+ *     a tool result as a JSON string. That is the browser's wire format, not
+ *     something to pre-serialise here.
+ *   - It needs `--enable-features=WebMCPTesting`, the
+ *     `chrome://flags/#enable-webmcp-testing` flag, or an origin-trial token.
+ *
+ * The specification is a Draft Community Group Report and is not on the W3C
+ * standards track, so this module is deliberately small and replaceable.
+ */
+
+import type { ConfirmRequest, JsonSchema, ValidationIssue, ValidationLayer } from "./types";
+
+// ----------------------------------------------------------- browser surface
+
+/** One command the validator accepted, in the form this projection reports. */
+export interface ProjectedCommand {
+  readonly intent: unknown;
+  readonly explain: { readonly summary: string };
+}
+
+/**
+ * What the validator answers. Mirrors the component-level execution result;
+ * a component may carry extra fields, which are ignored here.
+ */
+export type ProjectedOutcome =
+  | { status: "done"; commands: readonly ProjectedCommand[]; warnings: readonly ValidationIssue[] }
+  | {
+      status: "needs-confirmation";
+      commands: readonly ProjectedCommand[];
+      warnings: readonly ValidationIssue[];
+      confirm: ConfirmRequest;
+    }
+  | {
+      status: "rejected";
+      reason: string;
+      code: string;
+      layer: ValidationLayer;
+      suggestion?: string;
+    }
+  | { status: "clarify"; question: string; options?: readonly string[] }
+  | { status: "declined"; reason: string };
+
+/**
+ * The part of a component's agent this projection uses.
+ *
+ * Structural on purpose: a DataGrid agent, a DatePicker agent or a test double
+ * satisfies it without importing anything from here.
+ */
+export interface ProjectableAgent {
+  /** The generated per-instance schema for one intent. */
+  schema(): JsonSchema;
+  /** Validate without changing anything. */
+  validate(intent: unknown): ProjectedOutcome;
+  execute(intent: unknown, options?: { confirm?: boolean }): Promise<ProjectedOutcome>;
+}
+
+/** The slice of the WebMCP surface this projection touches. */
+export interface ModelContext {
+  registerTool(descriptor: {
+    name: string;
+    description: string;
+    inputSchema: unknown;
+    execute(input: unknown): Promise<unknown>;
+  }): void | Promise<void>;
+  getTools?(): unknown;
+  executeTool?(tool: unknown, input: unknown): Promise<unknown>;
+}
+
+declare global {
+  interface Document {
+    modelContext?: ModelContext;
+  }
+}
+
+// -------------------------------------------------------------------- result
+
+/** What the agent gets back, before the MCP content envelope is put round it. */
+export interface ToolResultPayload extends Record<string, unknown> {
+  ok: boolean;
+  status: string;
+  message: string;
+}
+
+export interface ToolCallLog {
+  readonly input: unknown;
+  readonly result: ToolResultPayload;
+}
+
+export interface RegistrationResult {
+  registered: boolean;
+  toolName: string;
+  /** Why not, when `registered` is false. Safe to show a developer. */
+  reason?: string;
+  /** The schema handed to the agent, for inspection in a test or a UI. */
+  inputSchema?: JsonSchema;
+}
+
+export interface RegisterAgentToolOptions<TAgent extends ProjectableAgent> {
+  /** The tool name the agent sees. One per page. */
+  name: string;
+  /** Natural-language description, built from the live contract. */
+  describe: (agent: TAgent) => string;
+  /** Extra fields merged into a successful result — row counts, undo state. */
+  summarise?: (agent: TAgent) => Record<string, unknown>;
+  /** How many operations may be sent in one call. Default 8. */
+  maxIntents?: number;
+  /** Description for the `intents` array itself. */
+  intentsDescription?: string;
+  /** Observe every call, for a UI log or a test. Must not throw. */
+  onCall?: (entry: ToolCallLog) => void;
+  /**
+   * Where to register. Defaults to `document.modelContext`. Supplying one is
+   * for tests and for hosts that polyfill the surface elsewhere.
+   */
+  modelContext?: ModelContext;
+}
+
+const UNAVAILABLE =
+  "document.modelContext is unavailable. Chrome needs --enable-features=WebMCPTesting, " +
+  "the chrome://flags/#enable-webmcp-testing flag, or an origin-trial token.";
+
+/**
+ * Whether this page can register WebMCP tools at all.
+ *
+ * Guards `document` rather than assuming it: this module is imported by code
+ * that also runs during server rendering, where touching `document` throws.
+ */
+export function webmcpAvailable(modelContext?: ModelContext): boolean {
+  const target = modelContext ?? (typeof document === "undefined" ? undefined : document.modelContext);
+  return typeof target?.registerTool === "function";
+}
+
+/**
+ * The tool's input schema, derived from the live contract.
+ *
+ * Not hand-written. `agent.schema()` is the generated per-instance schema, so
+ * a tool registered against a component with different columns, operators or
+ * policy advertises different arguments automatically.
+ */
+export function buildToolInputSchema(
+  agent: ProjectableAgent,
+  options: { maxIntents?: number; intentsDescription?: string } = {},
+): JsonSchema {
+  return {
+    type: "object",
+    additionalProperties: false,
+    required: ["intents"],
+    properties: {
+      intents: {
+        type: "array",
+        minItems: 1,
+        maxItems: options.maxIntents ?? 8,
+        description:
+          options.intentsDescription ??
+          "Operations to apply in order. Several filters on different fields combine with AND.",
+        items: agent.schema(),
+      },
+    },
+  };
+}
+
+/**
+ * Registers one tool, if the browser has WebMCP.
+ *
+ * `execute` runs the production pipeline and nothing else:
+ *
+ *   validate  → a refusal is returned as the validator wrote it
+ *   confirm   → anything irreversible stops here and asks, rather than running
+ *   execute   → only after validation passed
+ *
+ * There is no repair, no retry, and no path that exists only for WebMCP. An
+ * agent sending something the component cannot do gets the same refusal, with
+ * the same code and layer, that a form would have got.
+ */
+export function registerAgentTool<TAgent extends ProjectableAgent>(
+  agent: TAgent,
+  options: RegisterAgentToolOptions<TAgent>,
+): RegistrationResult {
+  const modelContext =
+    options.modelContext ?? (typeof document === "undefined" ? undefined : document.modelContext);
+
+  if (typeof modelContext?.registerTool !== "function") {
+    return { registered: false, toolName: options.name, reason: UNAVAILABLE };
+  }
+
+  const inputSchema = buildToolInputSchema(agent, options);
+
+  modelContext.registerTool({
+    name: options.name,
+    description: options.describe(agent),
+    inputSchema,
+
+    async execute(rawInput: unknown) {
+      const intents = (rawInput as { intents?: unknown } | null | undefined)?.intents;
+
+      const reply = (payload: ToolResultPayload) => {
+        try {
+          options.onCall?.({ input: rawInput, result: payload });
+        } catch {
+          /* A broken observer must not turn a good command into an error. */
+        }
+        return {
+          // MCP's content shape, so an agent reading text gets something useful…
+          content: [{ type: "text", text: payload.message }],
+          // …and the structured result for anything that wants to inspect it.
+          structuredContent: payload,
+          isError: payload.ok === false,
+        };
+      };
+
+      if (!Array.isArray(intents) || intents.length === 0) {
+        return reply({
+          ok: false,
+          status: "rejected",
+          code: "missing-intents",
+          message: '"intents" must be a non-empty array of operations.',
+        });
+      }
+
+      /* Layer one of the real pipeline. Nothing has touched the component yet. */
+      let checked: ProjectedOutcome;
+      try {
+        checked = agent.validate(intents);
+      } catch (error) {
+        return reply({
+          ok: false,
+          status: "rejected",
+          code: "validator-threw",
+          message: error instanceof Error ? error.message : String(error),
+        });
+      }
+
+      if (checked.status === "rejected") {
+        return reply({
+          ok: false,
+          status: "rejected",
+          code: checked.code,
+          layer: checked.layer,
+          suggestion: checked.suggestion,
+          message: checked.reason,
+        });
+      }
+
+      if (checked.status === "clarify") {
+        return reply({
+          ok: false,
+          status: "clarify",
+          message: checked.question,
+          options: checked.options,
+        });
+      }
+
+      if (checked.status === "declined") {
+        return reply({ ok: false, status: "declined", message: checked.reason });
+      }
+
+      if (checked.status === "needs-confirmation") {
+        /*
+         * An agent does not get to skip a confirmation a person would see. The
+         * component is left untouched and the request is handed back.
+         */
+        return reply({
+          ok: false,
+          status: "needs-confirmation",
+          code: checked.confirm.code,
+          message: checked.confirm.message,
+          explain: checked.commands.map((command) => command.explain.summary),
+        });
+      }
+
+      let run: ProjectedOutcome;
+      try {
+        run = await agent.execute(intents);
+      } catch (error) {
+        return reply({
+          ok: false,
+          status: "failed",
+          code: "executor-threw",
+          message: error instanceof Error ? error.message : String(error),
+        });
+      }
+
+      if (run.status !== "done") {
+        return reply({
+          ok: false,
+          status: run.status,
+          message:
+            "reason" in run ? run.reason : "question" in run ? run.question : run.status,
+        });
+      }
+
+      return reply({
+        ok: true,
+        status: "done",
+        message: run.commands.map((command) => command.explain.summary).join("; "),
+        applied: run.commands.map((command) => command.intent),
+        warnings: run.warnings.map((warning) => `${warning.code}: ${warning.message}`),
+        ...(options.summarise?.(agent) ?? {}),
+      });
+    },
+  });
+
+  return { registered: true, toolName: options.name, inputSchema };
+}

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

@@ -6,3 +6,12 @@ export { AnchoredPopover, type AnchoredPopoverProps } from "./react/Popover";
 export { placePopover, type Align, type Placement, type Side } from "./core/position";
 export * as icons from "./react/icons";
 export { version as sharedVersion } from "./version";
+
+// Agent runtime: the component-agnostic operation/validation/history layer.
+export * from "./core/agent";
+export {
+  GramproAIProvider,
+  useAgentAdapter,
+  type GramproAIProviderProps,
+} from "./react/GramproAIProvider";
+export { useAskAgent, type AskableAgent, type AskExecution, type UseAskAgent } from "./react/useAskAgent";

package/source/beta-components/shared/react/GramproAIProvider.tsx

@@ -0,0 +1,50 @@
+"use client";
+
+import { createContext, useContext, useMemo, type ReactNode } from "react";
+import type { AgentAdapter } from "../core/agent/adapter";
+
+/*
+ * Where an application plugs its own language model in.
+ *
+ * Nothing below this provider knows which one it is. A component asks the
+ * context for an adapter; if there is none, the component renders exactly as
+ * it does today and its natural-language affordance is simply absent. That is
+ * the whole opt-in: no provider, no AI, no bytes, no network.
+ */
+
+interface AIContextValue {
+  adapter: AgentAdapter | null;
+  /** Shown above the input, e.g. "Ask about these customers". */
+  placeholder?: string;
+  /** Example utterances offered as one-click suggestions. */
+  suggestions?: readonly string[];
+}
+
+const AIContext = createContext<AIContextValue>({ adapter: null });
+
+export interface GramproAIProviderProps extends AIContextValue {
+  children: ReactNode;
+}
+
+export function GramproAIProvider({
+  adapter,
+  placeholder,
+  suggestions,
+  children,
+}: GramproAIProviderProps) {
+  const value = useMemo(
+    () => ({ adapter, placeholder, suggestions }),
+    [adapter, placeholder, suggestions],
+  );
+  return <AIContext.Provider value={value}>{children}</AIContext.Provider>;
+}
+
+/**
+ * The adapter in scope, or null.
+ *
+ * Null is an ordinary case, not an error: a component asks, gets nothing, and
+ * renders without the affordance.
+ */
+export function useAgentAdapter(): AIContextValue {
+  return useContext(AIContext);
+}