@gizmo-ai/client 0.2.2

package/src/subscribe.ts

@@ -0,0 +1,87 @@
+/**
+ * SSE Subscription
+ *
+ * Opens an EventSource to the agent's stream endpoint, maintains local state,
+ * applies JSON Patches (RFC 6902), and calls back with the full patched state
+ * plus the triggering event.
+ */
+
+import { applyPatch } from "fast-json-patch";
+import type {
+  SSEEvent,
+  InitialStateEvent,
+  StateUpdateEvent,
+  ExecutionStatusEvent,
+  HeartbeatEvent,
+  CustomEvent,
+  SubscribeCallback,
+  SubscribeOptions,
+  Unsubscribe,
+} from "./types.ts";
+
+/**
+ * Subscribe to an agent's SSE stream.
+ *
+ * Maintains a local state object, applies incoming patches, and fires
+ * the callback with a consistent snapshot after every event.
+ *
+ * @returns An unsubscribe function that closes the EventSource.
+ */
+export function subscribe(
+  baseUrl: string,
+  callback: SubscribeCallback,
+  options?: SubscribeOptions,
+): Unsubscribe {
+  const endpoint = options?.endpoint ?? "/events";
+  const url = `${baseUrl}${endpoint}`;
+
+  const slices: Record<string, unknown> = {};
+  const es = new EventSource(url);
+
+  // state.initial — set full local state
+  es.addEventListener("state.initial", (e: MessageEvent) => {
+    const event: InitialStateEvent = JSON.parse(e.data);
+    // Reset and populate slices
+    for (const key of Object.keys(slices)) delete slices[key];
+    Object.assign(slices, event.slices);
+    callback({ slices: { ...slices }, event });
+  });
+
+  // state.update — apply patches or full value replacement
+  es.addEventListener("state.update", (e: MessageEvent) => {
+    const event: StateUpdateEvent = JSON.parse(e.data);
+
+    if (event.patches && event.patches.length > 0) {
+      const current = slices[event.slice] ?? {};
+      const cloned = structuredClone(current);
+      const result = applyPatch(cloned, event.patches);
+      slices[event.slice] = result.newDocument;
+    } else if ("value" in event) {
+      slices[event.slice] = event.value;
+    }
+
+    callback({ slices: { ...slices }, event });
+  });
+
+  // execution.status — fire callback, no state mutation
+  es.addEventListener("execution.status", (e: MessageEvent) => {
+    const event: ExecutionStatusEvent = JSON.parse(e.data);
+    callback({ slices: { ...slices }, event });
+  });
+
+  // heartbeat — fire callback, no state mutation
+  es.addEventListener("heartbeat", (e: MessageEvent) => {
+    const event: HeartbeatEvent = JSON.parse(e.data);
+    callback({ slices: { ...slices }, event });
+  });
+
+  // custom-event — fire callback, no state mutation
+  es.addEventListener("custom-event", (e: MessageEvent) => {
+    const event: CustomEvent = JSON.parse(e.data);
+    callback({ slices: { ...slices }, event });
+  });
+
+  return () => {
+    es.close();
+  };
+}

package/src/types.ts

@@ -0,0 +1,271 @@
+/**
+ * @gizmo-ai/client — Standalone type definitions
+ *
+ * All types are redeclared here — no imports from @gizmo-ai/server or @gizmo-ai/runtime.
+ * This keeps the client zero-coupling with the server packages.
+ */
+
+import type { Operation } from "fast-json-patch";
+
+// ============================================================================
+// Manifest
+// ============================================================================
+
+export interface GizmoManifest {
+  manifestVersion: string;
+  identity: {
+    agentId: string;
+    name: string;
+    version: string;
+    description?: string;
+    documentationUrl?: string;
+  };
+  auth?: {
+    type?: string;
+    scopes?: string[];
+  };
+  endpoints: {
+    invoke: string;
+    state: string;
+    runs: string;
+    streams: {
+      state: string;
+      actions: string;
+      events: string;
+    };
+    control?: {
+      cancel: string;
+      continue: string;
+    };
+    plugins?: Record<string, string>;
+  };
+  state: {
+    slices: string[];
+    schemaVersion: string;
+    schemaRef?: string;
+    schema?: {
+      type: "object";
+      properties: Record<string, unknown>;
+      $defs?: Record<string, unknown>;
+    };
+  };
+  actions?: {
+    publicContractsRef: string;
+  };
+  capabilities: {
+    tools?: string[];
+    skills?: Array<{
+      name: string;
+      description?: string;
+      source?: string;
+    }>;
+    models?: string[];
+    features?: string[];
+    plugins?: string[];
+  };
+}
+
+// ============================================================================
+// SSE Events
+// ============================================================================
+
+export interface InitialStateEvent {
+  type: "state.initial";
+  slices: Record<string, unknown>;
+  timestamp: number;
+}
+
+export interface StateUpdateEvent {
+  type: "state.update";
+  slice: string;
+  patches?: Operation[];
+  value?: unknown;
+  cause?: {
+    type: string;
+    id?: string;
+    payload?: unknown;
+  };
+  timestamp: number;
+}
+
+export interface ExecutionStatusEvent {
+  type: "execution.status";
+  status: "started" | "completed" | "failed" | "aborted" | "interrupted";
+  executionId?: string;
+  turnId?: string;
+  error?: string;
+  timestamp: number;
+}
+
+export interface HeartbeatEvent {
+  type: "heartbeat";
+  timestamp: number;
+}
+
+export interface CustomEvent {
+  type: "custom-event";
+  data: unknown;
+  timestamp: number;
+}
+
+export type SSEEvent =
+  | InitialStateEvent
+  | StateUpdateEvent
+  | ExecutionStatusEvent
+  | HeartbeatEvent
+  | CustomEvent;
+
+// ============================================================================
+// API Request/Response Types
+// ============================================================================
+
+export interface InvokeResponse {
+  executionId: string;
+  turnId: string;
+}
+
+export interface AbortResponse {
+  status: "aborted";
+  executionId: string;
+}
+
+export interface RunSummary {
+  executionId: string;
+  startTime: number;
+  endTime?: number;
+  status: "running" | "completed" | "failed" | "aborted";
+  actionCount: number;
+  error?: string;
+  digest?: string;
+}
+
+export interface RunDetails extends RunSummary {
+  actions: Array<{ type: string; payload?: unknown }>;
+}
+
+export interface RunsResponse {
+  runs: RunSummary[];
+}
+
+export interface RunListParams {
+  after?: number;
+  before?: number;
+  status?: "running" | "completed" | "failed" | "aborted";
+  limit?: number;
+}
+
+export interface HydrateOptions {
+  upToSeq?: number;
+  upToTurn?: number;
+  thenExecute?: string;
+  hydrateMode?: "full" | "slim";
+}
+
+export interface HydrateResponse {
+  status: "hydrated";
+  actionCount: number;
+  state: {
+    conversationLength: number;
+    loopCount: number;
+  };
+  execution?: {
+    executionId: string;
+    turnId: string;
+  };
+}
+
+export interface HealthResponse {
+  status: "ok";
+}
+
+export interface DispatchRequest {
+  type: string;
+  payload?: unknown;
+}
+
+// ============================================================================
+// Approval Types
+// ============================================================================
+
+export type ApprovalStatus = "pending" | "approved" | "rejected" | "expired";
+
+export interface Approval {
+  id: string;
+  executionId: string;
+  toolCall: {
+    name: string;
+    args: Record<string, unknown>;
+  };
+  status: ApprovalStatus;
+  requestedAt: number;
+  expiresAt?: number;
+  decidedAt?: number;
+  reason?: string;
+}
+
+export interface ApprovalsListResponse {
+  approvals: Approval[];
+}
+
+export interface ApprovalResponse {
+  approval: Approval;
+}
+
+export interface HistoryResponse {
+  history: Approval[];
+}
+
+// ============================================================================
+// Subscribe Types
+// ============================================================================
+
+export interface StateSnapshot {
+  slices: Record<string, unknown>;
+  event: SSEEvent;
+}
+
+export type SubscribeCallback = (snapshot: StateSnapshot) => void;
+
+export type Unsubscribe = () => void;
+
+export interface SubscribeOptions {
+  /** SSE endpoint path (default: "/events") */
+  endpoint?: string;
+}
+
+// ============================================================================
+// Client Types
+// ============================================================================
+
+export interface ClientOptions {
+  /** Custom fetch implementation (for testing or environments without global fetch) */
+  fetch?: typeof globalThis.fetch;
+  /** Default headers to include on every request (e.g., auth tokens) */
+  headers?: Record<string, string>;
+}
+
+export interface GizmoClient {
+  discover(): Promise<GizmoManifest>;
+  invoke(input: string): Promise<InvokeResponse>;
+  abort(): Promise<AbortResponse>;
+  state(slice?: string): Promise<unknown>;
+  subscribe(callback: SubscribeCallback, options?: SubscribeOptions): Unsubscribe;
+  health(): Promise<HealthResponse>;
+  dispatch(action: DispatchRequest): Promise<unknown>;
+
+  runs: {
+    list(params?: RunListParams): Promise<RunSummary[]>;
+    get(executionId: string): Promise<RunDetails>;
+    actions(executionId: string): Promise<RunDetails["actions"]>;
+    cancel(executionId: string): Promise<{ status: string; executionId: string }>;
+    hydrate(executionId: string, options?: HydrateOptions): Promise<HydrateResponse>;
+  };
+
+  approvals: {
+    list(): Promise<Approval[]>;
+    history(): Promise<Approval[]>;
+    get(id: string): Promise<Approval>;
+    approve(id: string, reason?: string): Promise<Approval>;
+    reject(id: string, reason?: string): Promise<Approval>;
+  };
+}