gloomberb 0.12.0 → 0.13.2

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

@@ -0,0 +1,286 @@
+// Wire declarations are mirrored in gloomberb-platform/server/src/services/askg/types.ts.
+import type {
+  HeadlessPaneArgumentDef,
+  HeadlessPaneColumn,
+  HeadlessPaneOptionDef,
+  HeadlessPaneOptionValue,
+  HeadlessPaneShape,
+} from "../../../../types/headless";
+import type {
+  RemoteJsonSchema,
+  RemoteJsonSchemaType,
+  RemoteWriteTier,
+} from "../../../../remote/types";
+
+/** Major version of the ASKG client and server wire contract. */
+export const ASKG_PROTOCOL_VERSION = 1;
+
+/** Maximum accepted JSON-encoded client tool result size. */
+export const MAX_TOOL_RESULT_BYTES = 262_144;
+
+/** Source form for valid tool names advertised to ASKG. */
+export const TOOL_NAME_PATTERN = "^[a-z0-9][a-z0-9_.]{0,47}$";
+
+/** JSON value accepted on the ASKG wire. */
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+/** Safety tier applied before a client tool is executed. */
+export type WriteTier = RemoteWriteTier;
+
+/** Runtime that opened an ASKG session. */
+export type ASKGClientKind = "tui" | "desktop" | "web";
+
+/** Origin of an advertised client tool. */
+/**
+ * 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;
+
+/** Headless argument kinds understood by the manifest compiler. */
+export type ToolManifestArgumentKind = HeadlessPaneArgumentDef["kind"];
+
+/** Serializable headless argument declaration. */
+export type ToolManifestArgument = HeadlessPaneArgumentDef;
+
+/** Values accepted by a headless enum option. */
+export type ToolManifestOptionValue = HeadlessPaneOptionValue;
+
+/** Headless option types understood by the manifest compiler. */
+export type ToolManifestOptionType = HeadlessPaneOptionDef["type"];
+
+/** Serializable headless option declaration. */
+export type ToolManifestOption = Omit<HeadlessPaneOptionDef, "settingKey" | "pluginState">;
+
+/** Serializable headless column declaration. */
+export type ToolManifestColumn = Omit<HeadlessPaneColumn, "format">;
+
+/** JSON Schema primitive types accepted for remote operation inputs. */
+export type ToolInputSchemaType = RemoteJsonSchemaType;
+
+/** JSON Schema accepted by a remote operation tool. */
+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;
+  source: ToolManifestSource;
+  title: string;
+  description: string;
+  writeTier: WriteTier;
+  shape?: ToolManifestShape;
+  argument?: ToolManifestArgument;
+  options?: ToolManifestOption[];
+  columns?: ToolManifestColumn[];
+  inputSchema?: ToolInputSchema;
+  confirm: "never" | "always";
+  timeoutMs: number;
+}
+
+/** Client identity included in a session negotiation. */
+export interface ASKGClientDescriptor {
+  kind: ASKGClientKind;
+  version: string;
+}
+
+/** Terminal context supplied to the model at session start. */
+export interface ASKGSessionContext {
+  query?: string;
+  symbol?: string;
+  paneId?: string;
+  layout?: JsonValue;
+}
+
+/** Request used to negotiate tools and limits for an ASKG session. */
+export interface ASKGSessionStartRequest {
+  protocolVersion: typeof ASKG_PROTOCOL_VERSION;
+  client: ASKGClientDescriptor;
+  context: ASKGSessionContext;
+  /** A client may only advertise tools it executes itself. */
+  tools: ClientToolManifest[];
+  manifestHash: string;
+}
+
+/** Per-user and per-turn limits returned by the platform. */
+export interface ASKGLimits {
+  requestsPerMinute: number;
+  turnsPerDay: number;
+  turnsRemainingToday: number;
+  maxToolCallsPerTurn: number;
+  turnWallClockMs: number;
+  clientToolTimeoutMs: number;
+}
+
+/** Client tool rejected during session negotiation. */
+export interface ASKGRejectedTool {
+  name: string;
+  reason: string;
+}
+
+/** Successful ASKG session negotiation response. */
+export interface ASKGSessionStartResponse {
+  protocolVersion: typeof ASKG_PROTOCOL_VERSION;
+  sessionId: string;
+  manifestHash: string;
+  serverTools: ToolManifest[];
+  acceptedTools: string[];
+  rejectedTools: ASKGRejectedTool[];
+  limits: ASKGLimits;
+  tier: string;
+  model: string;
+  promptVersion: string;
+  expiresAt: string;
+}
+
+/** Shared fields carried by every turn stream event. */
+export interface ASKGEventBase {
+  seq: number;
+}
+
+/** Announces the session and turn attached to this stream. */
+export interface ASKGSessionEvent extends ASKGEventBase {
+  type: "session";
+  sessionId: string;
+  turnId: string;
+  model: string;
+  promptVersion: string;
+}
+
+/** Appends model text to the visible answer. */
+export interface ASKGTextDeltaEvent extends ASKGEventBase {
+  type: "text-delta";
+  turnId: string;
+  delta: string;
+}
+
+/** Delegates one negotiated tool call to the client. */
+export interface ASKGToolCallEvent extends ASKGEventBase {
+  type: "tool-call";
+  turnId: string;
+  toolCallId: string;
+  name: string;
+  args: Record<string, JsonValue>;
+  writeTier: WriteTier;
+  requiresConfirmation: boolean;
+  preview: JsonValue;
+  timeoutMs: number;
+  expiresAt: string;
+}
+
+/** Compact result information suitable for the tool timeline. */
+export interface ToolExecutionSummary {
+  rowCount?: number;
+  elapsedMs: number;
+  truncated: boolean;
+  note?: string;
+  sample?: JsonValue;
+}
+
+/** Status returned by either a server or client tool execution. */
+export type ToolResultStatus =
+  | "ok"
+  | "error"
+  | "denied"
+  | "timeout"
+  | "partial"
+  | "cancelled";
+
+/** Reports a completed server tool or an accepted client execution. */
+export interface ASKGToolExecutedEvent extends ASKGEventBase {
+  type: "tool-executed";
+  turnId: string;
+  toolCallId: string;
+  name: string;
+  source: ToolManifestSource;
+  status: ToolResultStatus;
+  summary: ToolExecutionSummary;
+}
+
+/** Confirms that one client tool result was accepted by the turn loop. */
+export interface ASKGToolResultAckEvent extends ASKGEventBase {
+  type: "tool-result-ack";
+  turnId: string;
+  toolCallId: string;
+}
+
+/** Stable error codes that clients can handle without parsing text. */
+export type ASKGErrorCode =
+  | "rate_limited"
+  | "daily_turn_cap"
+  | "tool_budget_exhausted"
+  | "turn_timeout"
+  | "model_usage_limit"
+  | "model_unavailable"
+  | "internal";
+
+/** Reports a recoverable or terminal session or turn failure. */
+export interface ASKGErrorEvent extends ASKGEventBase {
+  type: "error";
+  turnId?: string;
+  code: ASKGErrorCode;
+  message: string;
+  retryable: boolean;
+  retryAfterMs?: number;
+}
+
+/** Token accounting emitted when the model provider supplies it. */
+export interface ASKGUsageEvent extends ASKGEventBase {
+  type: "usage";
+  turnId: string;
+  inputTokens?: number;
+  outputTokens?: number;
+  totalTokens?: number;
+  estimated: boolean;
+}
+
+/** Reason a turn stream stopped. */
+export type ASKGDoneReason = "complete" | "cancelled" | "error" | "timeout";
+
+/** Terminates a turn stream. */
+export interface ASKGDoneEvent extends ASKGEventBase {
+  type: "done";
+  turnId: string;
+  reason: ASKGDoneReason;
+}
+
+/** Event payloads emitted over the ASKG turn SSE stream. */
+export type ASKGSseEvent =
+  | ASKGSessionEvent
+  | ASKGTextDeltaEvent
+  | ASKGToolCallEvent
+  | ASKGToolExecutedEvent
+  | ASKGToolResultAckEvent
+  | ASKGErrorEvent
+  | ASKGUsageEvent
+  | ASKGDoneEvent;
+
+/** Client result posted for one delegated tool call. */
+export interface ToolResultPayload {
+  turnId: string;
+  toolCallId: string;
+  status: ToolResultStatus;
+  result?: JsonValue;
+  rowCount?: number;
+  truncated: boolean;
+  elapsedMs: number;
+  note?: string;
+  rev?: string;
+  undoToken?: string;
+}

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");
+});

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

@@ -0,0 +1,277 @@
+import { stableStringify } from "../../../../remote/revision";
+import type {
+  RemoteControlRequest,
+  RemoteControlResponse,
+  RemoteJsonPatchOperation,
+} from "../../../../remote/types";
+import type { JsonValue, ToolResultStatus } from "./protocol";
+
+export type InProcessRemoteControlHandler = (
+  request: RemoteControlRequest,
+) => Promise<RemoteControlResponse>;
+
+interface UndoResourceSnapshot {
+  resource: string;
+  value: JsonValue;
+}
+
+interface StoredUndoResource extends UndoResourceSnapshot {
+  expectedRev: string;
+}
+
+interface StoredUndo {
+  createdAt: number;
+  resources: StoredUndoResource[];
+}
+
+export interface PreparedUndo {
+  resources: UndoResourceSnapshot[];
+}
+
+export interface AppliedUndo {
+  status: Extract<ToolResultStatus, "ok" | "error" | "denied" | "cancelled">;
+  elapsedMs: number;
+  note?: string;
+}
+
+export interface ASKGUndoManagerOptions {
+  maxEntries?: number;
+  ttlMs?: number;
+  now?: () => number;
+  tokenFactory?: () => string;
+}
+
+const DEFAULT_MAX_ENTRIES = 50;
+const DEFAULT_TTL_MS = 10 * 60_000;
+
+const LAYOUT_UNDO_OPERATIONS = new Set([
+  "pane.setSetting",
+  "layout.gridlock",
+  "layout.closeFloating",
+  "layout.placePane",
+  "layout.setGrid",
+]);
+
+function shortReason(error: unknown): string {
+  const text = error instanceof Error ? error.message : String(error);
+  return text.replace(/\s+/g, " ").trim().slice(0, 240) || "Unknown error.";
+}
+
+function normalizeJson(value: unknown, seen = new WeakSet<object>()): JsonValue {
+  if (value == null) return null;
+  if (typeof value === "string" || typeof value === "boolean") return value;
+  if (typeof value === "number") return Number.isFinite(value) ? value : null;
+  if (typeof value === "bigint") return value.toString();
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value !== "object") return String(value);
+  if (seen.has(value)) return "[Circular]";
+  seen.add(value);
+  if (Array.isArray(value)) {
+    const result = value.map((entry) => normalizeJson(entry, seen));
+    seen.delete(value);
+    return result;
+  }
+  const result: Record<string, JsonValue> = {};
+  for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+    result[key] = normalizeJson((value as Record<string, unknown>)[key], seen);
+  }
+  seen.delete(value);
+  return result;
+}
+
+function paneStateResource(args: Record<string, JsonValue>): string | null {
+  const paneId = args.paneId;
+  return typeof paneId === "string" && paneId.length > 0
+    ? `app://pane-state/${encodeURIComponent(paneId)}`
+    : null;
+}
+
+function resourcesForOperation(
+  operation: string,
+  args: Record<string, JsonValue>,
+): string[] | null {
+  if (operation === "pane.setState") {
+    const resource = paneStateResource(args);
+    return resource ? [resource] : null;
+  }
+  if (LAYOUT_UNDO_OPERATIONS.has(operation)) return ["app://layout/current"];
+  return null;
+}
+
+function pointerSegment(value: string): string {
+  return value.replace(/~/g, "~0").replace(/\//g, "~1");
+}
+
+function isObject(value: JsonValue): value is Record<string, JsonValue> {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+
+function replacementPatch(current: JsonValue, target: JsonValue): RemoteJsonPatchOperation[] | null {
+  if (!isObject(current) || !isObject(target)) return null;
+  const patch: RemoteJsonPatchOperation[] = [];
+  const currentKeys = Object.keys(current).sort();
+  const targetKeys = Object.keys(target).sort();
+  for (const key of currentKeys) {
+    if (!(key in target)) patch.push({ op: "remove", path: `/${pointerSegment(key)}` });
+  }
+  for (const key of targetKeys) {
+    const path = `/${pointerSegment(key)}`;
+    if (!(key in current)) {
+      patch.push({ op: "add", path, value: target[key] });
+    } else if (stableStringify(current[key]) !== stableStringify(target[key])) {
+      patch.push({ op: "replace", path, value: target[key] });
+    }
+  }
+  return patch;
+}
+
+function throwIfCancelled(signal?: AbortSignal): void {
+  if (!signal?.aborted) return;
+  throw signal.reason instanceof Error ? signal.reason : new Error("Undo was cancelled.");
+}
+
+function randomToken(): string {
+  return globalThis.crypto.randomUUID();
+}
+
+export class ASKGUndoManager {
+  private readonly entries = new Map<string, StoredUndo>();
+  private readonly maxEntries: number;
+  private readonly ttlMs: number;
+  private readonly now: () => number;
+  private readonly tokenFactory: () => string;
+
+  constructor(
+    private readonly remoteHandler: InProcessRemoteControlHandler,
+    options: ASKGUndoManagerOptions = {},
+  ) {
+    this.maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    this.ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+    this.now = options.now ?? Date.now;
+    this.tokenFactory = options.tokenFactory ?? randomToken;
+  }
+
+  async prepare(
+    operation: string,
+    args: Record<string, JsonValue>,
+    signal?: AbortSignal,
+  ): Promise<PreparedUndo | null> {
+    const resources = resourcesForOperation(operation, args);
+    if (!resources) return null;
+    const snapshots: UndoResourceSnapshot[] = [];
+    for (const resource of resources) {
+      throwIfCancelled(signal);
+      const response = await this.remoteHandler({ type: "get", resource });
+      if (!response.ok) throw new Error(response.error.message);
+      snapshots.push({ resource, value: normalizeJson(response.data) });
+    }
+    return { resources: snapshots };
+  }
+
+  async commit(prepared: PreparedUndo, signal?: AbortSignal): Promise<string | null> {
+    const resources: StoredUndoResource[] = [];
+    let changed = false;
+    for (const before of prepared.resources) {
+      throwIfCancelled(signal);
+      const response = await this.remoteHandler({ type: "get", resource: before.resource });
+      if (!response.ok) throw new Error(response.error.message);
+      if (!response.rev) throw new Error(`Resource "${before.resource}" did not return a revision.`);
+      const current = normalizeJson(response.data);
+      if (stableStringify(current) !== stableStringify(before.value)) changed = true;
+      resources.push({ ...before, expectedRev: response.rev });
+    }
+    if (!changed) return null;
+
+    this.prune();
+    const token = this.tokenFactory();
+    this.entries.set(token, { createdAt: this.now(), resources });
+    while (this.entries.size > this.maxEntries) {
+      const oldest = this.entries.keys().next().value as string | undefined;
+      if (!oldest) break;
+      this.entries.delete(oldest);
+    }
+    return token;
+  }
+
+  async undo(token: string, signal?: AbortSignal): Promise<AppliedUndo> {
+    const startedAt = this.now();
+    this.prune();
+    const entry = this.entries.get(token);
+    if (!entry) {
+      return {
+        status: "denied",
+        elapsedMs: Math.max(0, this.now() - startedAt),
+        note: "Undo token is unknown or expired.",
+      };
+    }
+
+    try {
+      const currentResources: Array<{
+        snapshot: StoredUndoResource;
+        value: JsonValue;
+        rev: string;
+        patch: RemoteJsonPatchOperation[];
+      }> = [];
+      for (const snapshot of entry.resources) {
+        throwIfCancelled(signal);
+        const response = await this.remoteHandler({ type: "get", resource: snapshot.resource });
+        if (!response.ok) throw new Error(response.error.message);
+        if (!response.rev) throw new Error(`Resource "${snapshot.resource}" did not return a revision.`);
+        if (response.rev !== snapshot.expectedRev) {
+          return {
+            status: "denied",
+            elapsedMs: Math.max(0, this.now() - startedAt),
+            note: `Cannot undo because "${snapshot.resource}" changed after the tool call.`,
+          };
+        }
+        const value = normalizeJson(response.data);
+        const patch = replacementPatch(value, snapshot.value);
+        if (!patch) {
+          return {
+            status: "denied",
+            elapsedMs: Math.max(0, this.now() - startedAt),
+            note: `Cannot safely restore non-object resource "${snapshot.resource}".`,
+          };
+        }
+        currentResources.push({ snapshot, value, rev: response.rev, patch });
+      }
+
+      for (const current of currentResources) {
+        throwIfCancelled(signal);
+        if (current.patch.length === 0) continue;
+        const response = await this.remoteHandler({
+          type: "patch",
+          resource: current.snapshot.resource,
+          patch: current.patch,
+          expectRev: current.rev,
+        });
+        if (!response.ok) throw new Error(response.error.message);
+      }
+      this.entries.delete(token);
+      return {
+        status: "ok",
+        elapsedMs: Math.max(0, this.now() - startedAt),
+      };
+    } catch (error) {
+      if (signal?.aborted) {
+        return {
+          status: "cancelled",
+          elapsedMs: Math.max(0, this.now() - startedAt),
+          note: "Undo was cancelled.",
+        };
+      }
+      return {
+        status: "error",
+        elapsedMs: Math.max(0, this.now() - startedAt),
+        note: shortReason(error),
+      };
+    }
+  }
+
+  private prune(): void {
+    const cutoff = this.now() - this.ttlMs;
+    for (const [token, entry] of this.entries) {
+      if (entry.createdAt < cutoff) this.entries.delete(token);
+    }
+  }
+}