@xemahq/ui-kernel 0.9.0 → 0.9.1

package/src/vista/vista-tools.ts

@@ -0,0 +1,220 @@
+/**
+ * The agent-facing Vista tool contract — `vista_open` / `vista_update` /
+ * `vista_close` / `vista_list` (Canopy §8.2).
+ *
+ * This module is the BROWSER-side definition of those four calls: their names,
+ * their argument shapes, their result shapes, and the dispatcher that performs
+ * them against a {@link VistaTabsController}.
+ *
+ * ── One wire contract, two projections ──────────────────────────────────────
+ * The server half lives in `canopy-api`'s `vista/vista-tool.contract.ts`. The
+ * two files are VALUE-IDENTICAL by construction — same tool names, same
+ * argument shapes, same {@link VistaToolError} members, same result envelope —
+ * and both derive the `vista_open` argument from the kernel's
+ * `VistaSurfaceSchema`, which is the single structural source of truth. They
+ * are two projections rather than one import because this package is a React
+ * UI package (a NestJS service must not depend on it) and the kernel contracts
+ * package does not yet carry the three tiny argument schemas. Consolidating
+ * them into `@xemahq/kernel-contracts/surface` is the correct end state; until
+ * then, a change to either file MUST be mirrored in the other in the same
+ * change-set, exactly like the curated `ConnectorKind` parity rule.
+ *
+ * ── How a call gets here ────────────────────────────────────────────────────
+ * Vista is a BROWSER surface: no server can render a tab. So the backend never
+ * "performs" these tools — it VALIDATES, applies its own tab projection,
+ * RELAYS the call to the browser over the EXISTING agent-session realtime
+ * channel, and returns the browser's {@link VistaToolResult} to the model
+ * verbatim. A session where no panel answers returns
+ * `{ ok: false, error: 'no-panel' }` — an explicit refusal, never a silent
+ * success.
+ *
+ * The host binds `dispatchVistaTool` to its panel's controller and feeds it the
+ * relayed `{ tool, args }`; see the host's `use-vista-tool-bridge`.
+ */
+import { VistaSurfaceSchema } from '@xemahq/kernel-contracts/surface';
+import { z } from 'zod';
+
+import type { VistaSurfacePatch, VistaTabsController } from './use-vista-tabs';
+
+/** The closed set of Vista tools. Values are the wire tool names. */
+export enum VistaToolName {
+  Open = 'vista_open',
+  Update = 'vista_update',
+  Close = 'vista_close',
+  List = 'vista_list',
+}
+
+/**
+ * `vista_open(surface) -> { tabId }`.
+ *
+ * The argument IS the kernel tab envelope — not a wrapper around it — so the
+ * JSON Schema the model is shown is exactly `VistaSurface`. `kind` is an open
+ * string on purpose: an unrecognised kind is NOT an error, it opens a tab that
+ * renders the fallback card.
+ */
+export const VistaOpenArgsSchema = VistaSurfaceSchema;
+export type VistaOpenArgs = z.infer<typeof VistaOpenArgsSchema>;
+
+/**
+ * `vista_update(tabId, …) -> { updated: true }`.
+ *
+ * Flat, and deliberately narrower than {@link VistaSurfacePatch}: `kind` and
+ * `version` are NOT patchable, because the browser has already resolved a
+ * renderer for the live tab and swapping the kind under it would strand that
+ * renderer. Close and re-open instead. Every remaining field is optional; an
+ * empty patch is a no-op, not an error.
+ */
+export const VistaUpdateArgsSchema = z.object({
+  tabId: z.string().min(1),
+  title: z.string().min(1).optional(),
+  payload: z.unknown().optional(),
+  pinned: z.boolean().optional(),
+});
+export type VistaUpdateArgs = z.infer<typeof VistaUpdateArgsSchema>;
+
+/** `vista_close(tabId) -> { closed: true }`. A pinned tab refuses to close. */
+export const VistaCloseArgsSchema = z.object({ tabId: z.string().min(1) });
+export type VistaCloseArgs = z.infer<typeof VistaCloseArgsSchema>;
+
+/** `vista_list() -> { tabs }`. No arguments. */
+export const VistaListArgsSchema = z.object({});
+export type VistaListArgs = z.infer<typeof VistaListArgsSchema>;
+
+/** Why a Vista tool call could not be performed. Closed set. */
+export enum VistaToolError {
+  /** No Vista panel answered the relay — nothing is on screen to drive. */
+  NoPanel = 'no-panel',
+  /** The arguments failed schema validation at a wire boundary. */
+  InvalidArgs = 'invalid-args',
+  /** The tool name is not a member of {@link VistaToolName}. */
+  UnknownTool = 'unknown-tool',
+  /** `tabId` names a tab that is not open. */
+  UnknownTab = 'unknown-tab',
+  /**
+   * The tab exists but refuses the operation — it is pinned (close), or it is
+   * a HOST tab whose content the host's own data flow owns (update). `detail`
+   * names which.
+   */
+  TabRefused = 'tab-refused',
+}
+
+/** The result envelope every Vista tool returns. */
+export type VistaToolResult<TValue = unknown> =
+  | { readonly ok: true; readonly value: TValue }
+  | {
+      readonly ok: false;
+      readonly error: VistaToolError;
+      readonly detail?: string;
+    };
+
+/**
+ * Wire validator for {@link VistaToolResult}. The browser's answer crosses back
+ * into the server and then into the model's context, so the server validates
+ * the ENVELOPE with this shape before relaying it on — a browser cannot inject
+ * an arbitrary object where a typed result is expected.
+ */
+export const VistaToolResultSchema: z.ZodType<VistaToolResult> = z.union([
+  z.object({ ok: z.literal(true), value: z.unknown() }),
+  z.object({
+    ok: z.literal(false),
+    error: z.nativeEnum(VistaToolError),
+    detail: z.string().optional(),
+  }),
+]) as z.ZodType<VistaToolResult>;
+
+/**
+ * Perform a relayed Vista tool call against a mounted panel's controller.
+ *
+ * Fail-fast on bad input: arguments are re-validated here (the frontend never
+ * trusts that the backend validated), and a violation returns
+ * {@link VistaToolError.InvalidArgs} naming the offending path rather than a
+ * partially-applied change. Pass `controller: null` for a document with no
+ * mounted panel — that returns {@link VistaToolError.NoPanel}.
+ */
+export function dispatchVistaTool(
+  controller: VistaTabsController | null,
+  tool: string,
+  args: unknown,
+): VistaToolResult {
+  if (controller === null) {
+    return { ok: false, error: VistaToolError.NoPanel };
+  }
+  switch (tool) {
+    case VistaToolName.Open: {
+      const parsed = VistaOpenArgsSchema.safeParse(args);
+      if (!parsed.success) return invalid(parsed.error);
+      return { ok: true, value: { tabId: controller.open(parsed.data) } };
+    }
+    case VistaToolName.Update: {
+      const parsed = VistaUpdateArgsSchema.safeParse(args);
+      if (!parsed.success) return invalid(parsed.error);
+      const { tabId, ...patch } = parsed.data;
+      const refusal = refusalFor(controller, tabId);
+      if (refusal !== null) return refusal;
+      if (!controller.update(tabId, patch as VistaSurfacePatch)) {
+        // The tab is listed but not opened-tab-owned: it is a HOST tab, and a
+        // patch to it would be overwritten by the host's next reconcile.
+        return {
+          ok: false,
+          error: VistaToolError.TabRefused,
+          detail: `Tab "${tabId}" is host-owned; its content is driven by the host, not by vista_update.`,
+        };
+      }
+      return { ok: true, value: { updated: true } };
+    }
+    case VistaToolName.Close: {
+      const parsed = VistaCloseArgsSchema.safeParse(args);
+      if (!parsed.success) return invalid(parsed.error);
+      const { tabId } = parsed.data;
+      const refusal = refusalFor(controller, tabId);
+      if (refusal !== null) return refusal;
+      if (!controller.close(tabId)) {
+        return {
+          ok: false,
+          error: VistaToolError.TabRefused,
+          detail: `Tab "${tabId}" is pinned and cannot be closed.`,
+        };
+      }
+      return { ok: true, value: { closed: true } };
+    }
+    case VistaToolName.List: {
+      const parsed = VistaListArgsSchema.safeParse(args ?? {});
+      if (!parsed.success) return invalid(parsed.error);
+      return { ok: true, value: { tabs: controller.list() } };
+    }
+    default:
+      return {
+        ok: false,
+        error: VistaToolError.UnknownTool,
+        detail: `'${tool}' is not a Vista tool.`,
+      };
+  }
+}
+
+/**
+ * `unknown-tab` when the panel does not hold `tabId` at all. Returning `null`
+ * means the tab exists and the operation may proceed.
+ */
+function refusalFor(
+  controller: VistaTabsController,
+  tabId: string,
+): VistaToolResult | null {
+  if (controller.list().some((tab) => tab.tabId === tabId)) {
+    return null;
+  }
+  return {
+    ok: false,
+    error: VistaToolError.UnknownTab,
+    detail: `No tab "${tabId}" is open.`,
+  };
+}
+
+function invalid(error: z.ZodError): VistaToolResult {
+  return {
+    ok: false,
+    error: VistaToolError.InvalidArgs,
+    detail: error.issues
+      .map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`)
+      .join('; '),
+  };
+}