gloomberb 0.12.0 → 0.13.2

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

@@ -0,0 +1,153 @@
+import { describe, expect, test } from "bun:test";
+import type { PaneFunctionCatalog } from "../../../../cli/pane-functions/catalog";
+import type {
+  HeadlessPaneArgumentDef,
+  HeadlessPaneDefinition,
+  PaneDef,
+  PaneTemplateDef,
+} from "../../../../types/plugin";
+import {
+  buildASKGToolManifests,
+  hashASKGToolManifests,
+} from "./manifest";
+import type { ClientToolManifest } from "./protocol";
+
+function headless(argument: HeadlessPaneArgumentDef): HeadlessPaneDefinition<"rows"> {
+  return {
+    shape: "rows",
+    argument,
+    options: [{
+      key: "limit",
+      description: "Maximum rows.",
+      type: "integer",
+      minimum: 1,
+      maximum: 100,
+      defaultValue: 10,
+      settingKey: "limit",
+      pluginState: { pluginId: "test" },
+    }],
+    columns: [{ key: "value", header: "Value", format: String }],
+    load: () => ({ rows: [] }),
+  };
+}
+
+function pane(id: string): PaneDef {
+  return {
+    id,
+    name: id,
+    component: () => null,
+    defaultPosition: "left",
+  };
+}
+
+function template(
+  id: string,
+  paneId: string,
+  prefix: string,
+  argument: HeadlessPaneArgumentDef,
+): PaneTemplateDef {
+  return {
+    id,
+    paneId,
+    label: id,
+    description: `Read ${id}.`,
+    shortcut: { prefix, argKind: "text" },
+    headless: headless(argument),
+  };
+}
+
+function registry(templates: PaneTemplateDef[]): PaneFunctionCatalog {
+  return {
+    panes: new Map(templates.map(({ paneId }) => [paneId, pane(paneId)])),
+    paneTemplates: new Map(templates.map((entry) => [entry.id, entry])),
+    destroy() {},
+  };
+}
+
+function headlessTools(catalog: PaneFunctionCatalog): ClientToolManifest[] {
+  return buildASKGToolManifests(catalog).tools.filter(({ source }) => source === "headless");
+}
+
+describe("ASKG client manifest", () => {
+  test("projects every headless argument kind and strips renderer-only fields", () => {
+    const tools = headlessTools(registry([
+      template("none", "pane-none", "NON", { kind: "none" }),
+      template("ticker", "pane-ticker", "TIK", { kind: "ticker", placeholder: "symbol" }),
+      template("tickers", "pane-tickers", "TKS", { kind: "tickers", minimum: 2, maximum: 4 }),
+      template("symbols", "pane-symbols", "SYM", { kind: "symbol-list", optional: true }),
+      template("text", "pane-text", "TXT", { kind: "free-text", description: "Search phrase." }),
+    ]));
+
+    expect(tools.map(({ name, argument }) => [name, argument?.kind])).toEqual([
+      ["non", "none"],
+      ["sym", "symbol-list"],
+      ["tik", "ticker"],
+      ["tks", "tickers"],
+      ["txt", "free-text"],
+    ]);
+    expect(tools[0]?.options?.[0]).toEqual({
+      key: "limit",
+      description: "Maximum rows.",
+      type: "integer",
+      minimum: 1,
+      maximum: 100,
+      defaultValue: 10,
+    });
+    expect(tools[0]?.columns).toEqual([{ key: "value", header: "Value" }]);
+    expect(tools.every(({ writeTier, confirm }) => writeTier === "read" && confirm === "never")).toBe(true);
+  });
+
+  test("projects remote operation schemas and confirmation tiers", () => {
+    const { tools } = buildASKGToolManifests(registry([]));
+    const notify = tools.find(({ name }) => name === "app.notify");
+    const deleteLayout = tools.find(({ name }) => name === "layout.delete");
+
+    expect(notify).toMatchObject({
+      source: "remote-op",
+      writeTier: "ui-write",
+      confirm: "never",
+      inputSchema: { required: ["body"] },
+    });
+    expect(deleteLayout).toMatchObject({
+      source: "remote-op",
+      writeTier: "user-data",
+      confirm: "always",
+      inputSchema: { required: ["index"] },
+    });
+  });
+
+  test("hash is order-independent and changes with the surface", async () => {
+    const tools = headlessTools(registry([
+      template("valuation", "pane-valuation", "VAL", { kind: "none" }),
+      template("fear", "pane-fear", "FNG", { kind: "none" }),
+    ]));
+    const reversed = [...tools].reverse();
+    const changed = tools.map((tool, index) => index === 0
+      ? { ...tool, description: `${tool.description} Changed.` }
+      : tool);
+
+    expect(await hashASKGToolManifests(tools)).toBe(await hashASKGToolManifests(reversed));
+    expect(await hashASKGToolManifests(changed)).not.toBe(await hashASKGToolManifests(tools));
+  });
+
+  test("skips illegal and ambiguous names instead of rewriting them", () => {
+    const catalog = registry([
+      // Short and digit leading tokens are legal: the terminal's own shortcuts
+      // include N, SI and 13F, and a tool the model cannot name is a tool the
+      // model cannot use.
+      template("short", "pane-short", "N", { kind: "none" }),
+      template("numeric", "pane-numeric", "13F", { kind: "none" }),
+      template("bad", "pane-bad", "BAD/TOKEN", { kind: "none" }),
+      template("first", "pane-first", "VAL", { kind: "none" }),
+      template("second", "pane-second", "val", { kind: "none" }),
+    ]);
+    const { tools, skipped } = buildASKGToolManifests(catalog);
+
+    expect(tools.filter(({ source }) => source === "headless").map(({ name }) => name))
+      .toEqual(["13f", "n"]);
+    expect(skipped.map(({ token }) => token)).toEqual(["BAD/TOKEN", "VAL", "val"]);
+    expect(skipped.filter(({ token }) => token.toLowerCase() === "val").every(({ reason }) => (
+      reason.includes("Duplicate tool name")
+    ))).toBe(true);
+  });
+});

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

@@ -0,0 +1,190 @@
+import { describe, expect, test } from "bun:test";
+import type { HeadlessPaneDefinition } from "../../../../types/headless";
+import { marketValuationHeadless } from "../../market-valuation/headless";
+import {
+  ASKG_PROTOCOL_VERSION,
+  TOOL_NAME_PATTERN,
+  type ASKGSessionStartRequest,
+  type ASKGSessionStartResponse,
+  type ASKGSseEvent,
+  type ClientToolManifest,
+  type ToolManifest,
+  type ToolResultPayload,
+} from "./protocol";
+
+function jsonRoundTrip<T>(value: T): T {
+  return JSON.parse(JSON.stringify(value)) as T;
+}
+
+function projectHeadlessDefinition(
+  definition: HeadlessPaneDefinition,
+): ClientToolManifest {
+  const options = definition.options.map(({ settingKey: _settingKey, pluginState: _pluginState, ...option }) => option);
+  const columns = definition.columns?.map(({ format: _format, ...column }) => column);
+  return {
+    name: "market.valuation",
+    source: "headless",
+    title: "Market valuation",
+    description: "Compare whole-market valuation ratios with their history.",
+    writeTier: "read",
+    shape: definition.shape,
+    argument: definition.argument,
+    options,
+    ...(columns ? { columns } : {}),
+    confirm: "never",
+    timeoutMs: 30_000,
+  };
+}
+
+describe("ASKG protocol", () => {
+  test("round-trips session negotiation, a manifest, every event, and a tool result", () => {
+    const manifest: ClientToolManifest = {
+      name: "layout.place_pane",
+      source: "remote-op",
+      title: "Place pane",
+      description: "Move a pane to a layout region.",
+      writeTier: "ui-write",
+      inputSchema: {
+        type: "object",
+        properties: {
+          paneId: { type: "string" },
+          region: { type: "string", enum: ["left", "right", "floating"] },
+        },
+        required: ["paneId", "region"],
+        additionalProperties: false,
+      },
+      confirm: "never",
+      timeoutMs: 10_000,
+    };
+    const sessionRequest: ASKGSessionStartRequest = {
+      protocolVersion: ASKG_PROTOCOL_VERSION,
+      client: { kind: "tui", version: "0.8.0" },
+      context: {
+        query: "Compare NVDA valuation",
+        symbol: "NVDA",
+        paneId: "ticker:main",
+        layout: { id: "layout-1" },
+      },
+      tools: [manifest],
+      manifestHash: "sha256:manifest-1",
+    };
+    const sessionResponse: ASKGSessionStartResponse = {
+      protocolVersion: ASKG_PROTOCOL_VERSION,
+      sessionId: "session-1",
+      manifestHash: sessionRequest.manifestHash,
+      serverTools: [],
+      acceptedTools: [manifest.name],
+      rejectedTools: [{ name: "invalid.tool", reason: "Unknown source" }],
+      limits: {
+        requestsPerMinute: 20,
+        turnsPerDay: 300,
+        turnsRemainingToday: 299,
+        maxToolCallsPerTurn: 25,
+        turnWallClockMs: 90_000,
+        clientToolTimeoutMs: 10_000,
+      },
+      tier: "pro",
+      model: "gpt-5.6-luna",
+      promptVersion: "2026-09-04",
+      expiresAt: "2026-09-04T21:30:00.000Z",
+    };
+    const events: ASKGSseEvent[] = [
+      {
+        type: "session",
+        seq: 1,
+        sessionId: "session-1",
+        turnId: "turn-1",
+        model: "gpt-5.6-luna",
+        promptVersion: "2026-09-04",
+      },
+      { type: "text-delta", seq: 2, turnId: "turn-1", delta: "NVDA" },
+      {
+        type: "tool-call",
+        seq: 3,
+        turnId: "turn-1",
+        toolCallId: "call-1",
+        name: manifest.name,
+        args: { paneId: "chart:main", region: "right" },
+        writeTier: "ui-write",
+        requiresConfirmation: false,
+        preview: { paneId: "chart:main", region: "right", dryRun: true },
+        timeoutMs: 10_000,
+        expiresAt: "2026-09-04T21:00:10.000Z",
+      },
+      {
+        type: "tool-executed",
+        seq: 4,
+        turnId: "turn-1",
+        toolCallId: "call-server-1",
+        name: "market.quote",
+        source: "server",
+        status: "ok",
+        summary: {
+          rowCount: 1,
+          elapsedMs: 24,
+          truncated: false,
+          note: "Fresh quote",
+          sample: { symbol: "NVDA", price: 180 },
+        },
+      },
+      { type: "tool-result-ack", seq: 5, turnId: "turn-1", toolCallId: "call-1" },
+      {
+        type: "error",
+        seq: 6,
+        turnId: "turn-1",
+        code: "rate_limited",
+        message: "Try again shortly.",
+        retryable: true,
+        retryAfterMs: 1_000,
+      },
+      {
+        type: "usage",
+        seq: 7,
+        turnId: "turn-1",
+        inputTokens: 120,
+        outputTokens: 30,
+        totalTokens: 150,
+        estimated: false,
+      },
+      { type: "done", seq: 8, turnId: "turn-1", reason: "complete" },
+    ];
+    const result: ToolResultPayload = {
+      turnId: "turn-1",
+      toolCallId: "call-1",
+      status: "ok",
+      result: { moved: true },
+      rowCount: 1,
+      truncated: false,
+      elapsedMs: 12,
+      rev: "rev-2",
+      undoToken: "undo-1",
+    };
+
+    expect(new RegExp(TOOL_NAME_PATTERN).test(manifest.name)).toBe(true);
+    expect(jsonRoundTrip(manifest)).toEqual(manifest);
+    expect(jsonRoundTrip(sessionRequest)).toEqual(sessionRequest);
+    expect(jsonRoundTrip(sessionResponse)).toEqual(sessionResponse);
+    expect(events.map(jsonRoundTrip)).toEqual(events);
+    expect(jsonRoundTrip(result)).toEqual(result);
+  });
+
+  test("projects a migrated headless definition without executable fields", () => {
+    const manifest = projectHeadlessDefinition(marketValuationHeadless);
+    const serialized = JSON.stringify(manifest);
+
+    expect(new RegExp(TOOL_NAME_PATTERN).test(manifest.name)).toBe(true);
+    expect(manifest).toMatchObject({
+      source: "headless",
+      writeTier: "read",
+      shape: marketValuationHeadless.shape,
+      argument: marketValuationHeadless.argument,
+      confirm: "never",
+    });
+    expect(manifest.options).toHaveLength(marketValuationHeadless.options.length);
+    expect(serialized).not.toContain("load");
+    expect(serialized).not.toContain("settingKey");
+    expect(serialized).not.toContain("pluginState");
+    expect(serialized).not.toContain("format");
+    expect(jsonRoundTrip(manifest)).toEqual(manifest);
+  });
+});