gloomberb 0.13.1 → 0.13.2

package/src/plugins/builtin/cloud/askg/manifest.ts

@@ -0,0 +1,314 @@
+import type { PaneFunctionCatalog } from "../../../../cli/pane-functions/catalog";
+import { stableStringify } from "../../../../remote/revision";
+import {
+  REMOTE_OPERATIONS,
+  REMOTE_RESOURCES,
+  remoteOperationDescriptors,
+  remoteOperationToolName,
+} from "../../../../remote/schema";
+import type { RemoteControlRequest } from "../../../../remote/types";
+import type {
+  HeadlessPaneDefinition,
+  PaneDef,
+  PaneTemplateDef,
+} from "../../../../types/plugin";
+import {
+  TOOL_NAME_PATTERN,
+  type ClientToolManifest,
+  type ClientToolManifestSource,
+  type JsonValue,
+  type ToolManifestArgument,
+  type ToolManifestColumn,
+  type ToolManifestOption,
+} from "./protocol";
+
+export const HEADLESS_TOOL_TIMEOUT_MS = 30_000;
+export const REMOTE_TOOL_TIMEOUT_MS = 10_000;
+export const REMOTE_RESOURCE_TOOL_NAME = "app.get_resource";
+
+const TOOL_NAME_REGEX = new RegExp(TOOL_NAME_PATTERN);
+
+function compareText(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+export interface SkippedToolManifest {
+  source: ClientToolManifestSource;
+  token: string;
+  reason: string;
+}
+
+export interface ASKGClientManifest {
+  tools: ClientToolManifest[];
+  manifestHash: string;
+  skipped: SkippedToolManifest[];
+}
+
+interface ManifestCandidate {
+  token: string;
+  identity: string;
+  manifest: ClientToolManifest;
+}
+
+export type RemoteToolBinding =
+  | { kind: "operation"; operation: string }
+  | { kind: "resource" };
+
+function projectArgument(argument: HeadlessPaneDefinition["argument"]): ToolManifestArgument {
+  return { ...argument };
+}
+
+function projectOptions(options: HeadlessPaneDefinition["options"]): ToolManifestOption[] {
+  return options.map(({
+    settingKey: _settingKey,
+    pluginState: _pluginState,
+    values,
+    aliases,
+    ...option
+  }) => ({
+    ...option,
+    ...(aliases ? { aliases: [...aliases] } : {}),
+    ...(values ? {
+      values: values.map((value) => ({
+        ...value,
+        ...(value.aliases ? { aliases: [...value.aliases] } : {}),
+      })),
+    } : {}),
+  }));
+}
+
+function projectColumns(columns: HeadlessPaneDefinition["columns"]): ToolManifestColumn[] | undefined {
+  if (!columns) return undefined;
+  return columns.map(({ format: _format, ...column }) => ({ ...column }));
+}
+
+function headlessManifest(
+  token: string,
+  title: string,
+  description: string,
+  definition: HeadlessPaneDefinition,
+): ClientToolManifest {
+  const columns = projectColumns(definition.columns);
+  return {
+    name: token.toLowerCase(),
+    source: "headless",
+    title,
+    description,
+    writeTier: "read",
+    shape: definition.shape,
+    argument: projectArgument(definition.argument),
+    options: projectOptions(definition.options),
+    ...(columns ? { columns } : {}),
+    confirm: "never",
+    timeoutMs: HEADLESS_TOOL_TIMEOUT_MS,
+  };
+}
+
+function definitionFor(template: PaneTemplateDef, pane: PaneDef): HeadlessPaneDefinition | undefined {
+  return template.headless ?? pane.headless;
+}
+
+function headlessCandidates(registry: PaneFunctionCatalog): ManifestCandidate[] {
+  const candidates: ManifestCandidate[] = [];
+  const templatedPaneIds = new Set<string>();
+
+  const templates = [...registry.paneTemplates.values()]
+    .sort((left, right) => compareText(left.id, right.id));
+  for (const template of templates) {
+    const pane = registry.panes.get(template.paneId);
+    if (!pane) continue;
+    templatedPaneIds.add(pane.id);
+    const definition = definitionFor(template, pane);
+    if (!definition) continue;
+    const token = template.shortcut?.prefix ?? template.id;
+    candidates.push({
+      token,
+      identity: `template:${template.id}`,
+      manifest: headlessManifest(token, template.label, template.description, definition),
+    });
+  }
+
+  const panes = [...registry.panes.values()]
+    .sort((left, right) => compareText(left.id, right.id));
+  for (const pane of panes) {
+    if (templatedPaneIds.has(pane.id) || !pane.headless) continue;
+    candidates.push({
+      token: pane.id,
+      identity: `pane:${pane.id}`,
+      manifest: headlessManifest(
+        pane.id,
+        pane.name,
+        `Read data from the ${pane.name} pane.`,
+        pane.headless,
+      ),
+    });
+  }
+
+  return candidates;
+}
+
+function remoteCandidates(): ManifestCandidate[] {
+  const descriptors = remoteOperationDescriptors();
+  const operationsByName = new Map(
+    REMOTE_OPERATIONS.map((operation) => [remoteOperationToolName(operation.id), operation]),
+  );
+  const candidates = descriptors.map((descriptor): ManifestCandidate => ({
+    token: descriptor.name,
+    identity: `operation:${operationsByName.get(descriptor.name)?.id ?? descriptor.name}`,
+    manifest: {
+      name: descriptor.name,
+      source: "remote-op",
+      title: descriptor.title,
+      description: descriptor.description,
+      writeTier: descriptor.writeTier,
+      inputSchema: descriptor.inputSchema,
+      confirm: descriptor.writeTier === "user-data" || descriptor.writeTier === "broker"
+        ? "always"
+        : "never",
+      timeoutMs: REMOTE_TOOL_TIMEOUT_MS,
+    },
+  }));
+
+  candidates.push({
+    token: REMOTE_RESOURCE_TOOL_NAME,
+    identity: "resource:get",
+    manifest: {
+      name: REMOTE_RESOURCE_TOOL_NAME,
+      source: "remote-op",
+      title: "App: Get resource",
+      description: `Read a registered in-process app resource. Available resources: ${REMOTE_RESOURCES.map(({ uri }) => uri).join(", ")}.`,
+      writeTier: "read",
+      inputSchema: {
+        type: "object",
+        properties: {
+          resource: {
+            type: "string",
+            minLength: 1,
+            description: "Registered resource URI, such as app://snapshot or app://pane-state/{paneId}.",
+          },
+        },
+        required: ["resource"],
+        additionalProperties: false,
+      },
+      confirm: "never",
+      timeoutMs: REMOTE_TOOL_TIMEOUT_MS,
+    },
+  });
+
+  return candidates;
+}
+
+function compareManifests(left: ClientToolManifest, right: ClientToolManifest): number {
+  return compareText(left.name, right.name) || compareText(left.source, right.source);
+}
+
+function filterCandidates(candidates: ManifestCandidate[]): {
+  tools: ClientToolManifest[];
+  skipped: SkippedToolManifest[];
+} {
+  const skipped: SkippedToolManifest[] = [];
+  const valid: ManifestCandidate[] = [];
+
+  for (const candidate of candidates.sort((left, right) => (
+    compareText(left.manifest.name, right.manifest.name)
+    || compareText(left.identity, right.identity)
+  ))) {
+    if (!TOOL_NAME_REGEX.test(candidate.manifest.name)) {
+      skipped.push({
+        source: candidate.manifest.source,
+        token: candidate.token,
+        reason: `Lowercased token "${candidate.manifest.name}" does not match ${TOOL_NAME_PATTERN}.`,
+      });
+      continue;
+    }
+    valid.push(candidate);
+  }
+
+  const counts = new Map<string, number>();
+  for (const candidate of valid) {
+    counts.set(candidate.manifest.name, (counts.get(candidate.manifest.name) ?? 0) + 1);
+  }
+
+  const tools: ClientToolManifest[] = [];
+  for (const candidate of valid) {
+    if ((counts.get(candidate.manifest.name) ?? 0) > 1) {
+      skipped.push({
+        source: candidate.manifest.source,
+        token: candidate.token,
+        reason: `Duplicate tool name "${candidate.manifest.name}" from ${candidate.identity}.`,
+      });
+      continue;
+    }
+    tools.push(candidate.manifest);
+  }
+
+  return {
+    tools: tools.sort(compareManifests),
+    skipped: skipped.sort((left, right) => (
+      compareText(left.token, right.token) || compareText(left.source, right.source)
+    )),
+  };
+}
+
+export function buildASKGToolManifests(registry: PaneFunctionCatalog): {
+  tools: ClientToolManifest[];
+  skipped: SkippedToolManifest[];
+} {
+  return filterCandidates([
+    ...headlessCandidates(registry),
+    ...remoteCandidates(),
+  ]);
+}
+
+function bytesToHex(bytes: Uint8Array): string {
+  return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+export async function hashASKGToolManifests(tools: readonly ClientToolManifest[]): Promise<string> {
+  const sorted = [...tools].sort(compareManifests);
+  const digest = await globalThis.crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(stableStringify(sorted)),
+  );
+  return `sha256:${bytesToHex(new Uint8Array(digest))}`;
+}
+
+export async function buildASKGClientManifest(
+  registry: PaneFunctionCatalog,
+): Promise<ASKGClientManifest> {
+  const { tools, skipped } = buildASKGToolManifests(registry);
+  return {
+    tools,
+    manifestHash: await hashASKGToolManifests(tools),
+    skipped,
+  };
+}
+
+export function resolveRemoteToolBinding(name: string): RemoteToolBinding | null {
+  if (name === REMOTE_RESOURCE_TOOL_NAME) return { kind: "resource" };
+  const operation = REMOTE_OPERATIONS.find((entry) => remoteOperationToolName(entry.id) === name);
+  return operation ? { kind: "operation", operation: operation.id } : null;
+}
+
+function resourcePatternMatches(pattern: string, value: string): boolean {
+  const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const regex = new RegExp(`^${escaped.replace(/\\\{[^}]+\\\}/g, "[^/]+")}$`);
+  return regex.test(value);
+}
+
+export function remoteRequestForTool(
+  binding: RemoteToolBinding,
+  args: Record<string, JsonValue>,
+): RemoteControlRequest {
+  if (binding.kind === "operation") {
+    return { type: "call", operation: binding.operation, input: args };
+  }
+  const resource = args.resource;
+  if (typeof resource !== "string" || resource.length === 0) {
+    throw new Error(`${REMOTE_RESOURCE_TOOL_NAME} requires a resource URI.`);
+  }
+  if (!REMOTE_RESOURCES.some(({ uri }) => resourcePatternMatches(uri, resource))) {
+    throw new Error(`Unknown remote resource "${resource}".`);
+  }
+  return { type: "get", resource };
+}

package/src/plugins/builtin/cloud/askg/protocol.test.ts

@@ -7,6 +7,7 @@ import {
   type ASKGSessionStartRequest,
   type ASKGSessionStartResponse,
   type ASKGSseEvent,
+  type ClientToolManifest,
   type ToolManifest,
   type ToolResultPayload,
 } from "./protocol";
@@ -17,7 +18,7 @@ function jsonRoundTrip<T>(value: T): T {
 
 function projectHeadlessDefinition(
   definition: HeadlessPaneDefinition,
-): ToolManifest {
+): ClientToolManifest {
   const options = definition.options.map(({ settingKey: _settingKey, pluginState: _pluginState, ...option }) => option);
   const columns = definition.columns?.map(({ format: _format, ...column }) => column);
   return {
@@ -37,7 +38,7 @@ function projectHeadlessDefinition(
 
 describe("ASKG protocol", () => {
   test("round-trips session negotiation, a manifest, every event, and a tool result", () => {
-    const manifest: ToolManifest = {
+    const manifest: ClientToolManifest = {
       name: "layout.place_pane",
       source: "remote-op",
       title: "Place pane",

package/src/plugins/builtin/cloud/askg/protocol.ts

@@ -19,7 +19,7 @@ export const ASKG_PROTOCOL_VERSION = 1;
 export const MAX_TOOL_RESULT_BYTES = 262_144;
 
 /** Source form for valid tool names advertised to ASKG. */
-export const TOOL_NAME_PATTERN = "^[a-z][a-z0-9_.]{2,48}$";
+export const TOOL_NAME_PATTERN = "^[a-z0-9][a-z0-9_.]{0,47}$";
 
 /** JSON value accepted on the ASKG wire. */
 export type JsonValue =
@@ -37,7 +37,16 @@ export type WriteTier = RemoteWriteTier;
 export type ASKGClientKind = "tui" | "desktop" | "web";
 
 /** Origin of an advertised client tool. */
-export type ToolManifestSource = "headless" | "remote-op";
+/**
+ * Origin of a tool. This client only ever advertises "headless" and
+ * "remote-op"; "server" describes the tools the platform runs itself and
+ * reports back in `serverTools`, so a session response can describe its whole
+ * tool surface.
+ */
+export type ToolManifestSource = "headless" | "remote-op" | "server";
+
+/** The subset this client is allowed to advertise at session start. */
+export type ClientToolManifestSource = Exclude<ToolManifestSource, "server">;
 
 /** Headless result shapes supported by the tool timeline. */
 export type ToolManifestShape = HeadlessPaneShape;
@@ -67,6 +76,8 @@ export type ToolInputSchemaType = RemoteJsonSchemaType;
 export type ToolInputSchema = RemoteJsonSchema;
 
 /** Client or server tool metadata negotiated when a session starts. */
+export type ClientToolManifest = ToolManifest & { source: ClientToolManifestSource };
+
 export interface ToolManifest {
   /** Lowercase stable identifier matching TOOL_NAME_PATTERN. */
   name: string;
@@ -102,7 +113,8 @@ export interface ASKGSessionStartRequest {
   protocolVersion: typeof ASKG_PROTOCOL_VERSION;
   client: ASKGClientDescriptor;
   context: ASKGSessionContext;
-  tools: ToolManifest[];
+  /** A client may only advertise tools it executes itself. */
+  tools: ClientToolManifest[];
   manifestHash: string;
 }
 
@@ -196,7 +208,7 @@ export interface ASKGToolExecutedEvent extends ASKGEventBase {
   turnId: string;
   toolCallId: string;
   name: string;
-  source: ToolManifestSource | "server";
+  source: ToolManifestSource;
   status: ToolResultStatus;
   summary: ToolExecutionSummary;
 }

package/src/plugins/builtin/cloud/askg/undo.test.ts

@@ -0,0 +1,44 @@
+import { expect, test } from "bun:test";
+import { applyJsonPatch } from "../../../../remote/json-patch";
+import { revisionFor } from "../../../../remote/revision";
+import type { RemoteControlResponse } from "../../../../remote/types";
+import type { JsonValue } from "./protocol";
+import { ASKGUndoManager, type InProcessRemoteControlHandler } from "./undo";
+
+test("restores reversible pane state only when it has not changed again", async () => {
+  const resource = "app://pane-state/chart%3Amain";
+  const values = new Map<string, JsonValue>([[resource, { cursor: 1, mode: "price" }]]);
+  const handler: InProcessRemoteControlHandler = async (request): Promise<RemoteControlResponse> => {
+    if (request.type === "get") {
+      const value = values.get(request.resource) ?? {};
+      return { ok: true, data: value, rev: revisionFor(value) };
+    }
+    if (request.type === "patch") {
+      const current = values.get(request.resource) ?? {};
+      if (request.expectRev && request.expectRev !== revisionFor(current)) {
+        return { ok: false, error: { code: "revision_mismatch", message: "Revision mismatch." } };
+      }
+      const next = applyJsonPatch(current, request.patch) as JsonValue;
+      values.set(request.resource, next);
+      return { ok: true, data: next, rev: revisionFor(next) };
+    }
+    return { ok: false, error: { code: "unsupported", message: "Unsupported request." } };
+  };
+  const undo = new ASKGUndoManager(handler, { tokenFactory: () => "undo-1" });
+  const prepared = await undo.prepare("pane.setState", { paneId: "chart:main", patch: { cursor: 2 } });
+  expect(prepared).not.toBeNull();
+  values.set(resource, { cursor: 2, mode: "price", transient: true });
+  const token = await undo.commit(prepared!);
+
+  expect(token).toBe("undo-1");
+  expect((await undo.undo(token!)).status).toBe("ok");
+  expect(values.get(resource)).toEqual({ cursor: 1, mode: "price" });
+
+  const second = await undo.prepare("pane.setState", { paneId: "chart:main", patch: { cursor: 3 } });
+  values.set(resource, { cursor: 3, mode: "price" });
+  const secondToken = await undo.commit(second!);
+  values.set(resource, { cursor: 4, mode: "price" });
+  const denied = await undo.undo(secondToken!);
+  expect(denied.status).toBe("denied");
+  expect(denied.note).toContain("changed after the tool call");
+});