@opengeni/react 0.1.0

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@opengeni/react",
+  "version": "0.1.0",
+  "description": "React hooks and styled components for OpenGeni: live session streaming, chat composer, message timeline, session status, and fleet views — token-themed (CSS variables), dark-first, built on Tailwind v4 + Radix + Motion.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./styles.css": "./styles/index.css",
+    "./tokens.css": "./styles/tokens.css"
+  },
+  "files": [
+    "dist",
+    "src",
+    "styles"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsup",
+    "demo": "vite dev demo --port 3100",
+    "demo:build": "vite build demo"
+  },
+  "dependencies": {
+    "@opengeni/sdk": "^0.1.0",
+    "clsx": "^2.1.1",
+    "lucide-react": "^1.8.0",
+    "motion": "^12.0.0",
+    "radix-ui": "^1.4.3",
+    "tailwind-merge": "^3.5.0"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@fontsource-variable/inter": "^5.2.8",
+    "@fontsource-variable/jetbrains-mono": "^5.2.8",
+    "@happy-dom/global-registrator": "^20.10.2",
+    "@tailwindcss/vite": "^4.2.4",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.1",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "tailwindcss": "^4.2.4",
+    "tsup": "^8.5.0",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.9"
+  }
+}

package/src/approvals.ts

@@ -0,0 +1,86 @@
+import type { SessionEvent } from "@opengeni/sdk";
+
+/* ----------------------------------------------------------------------------
+   Pending-approvals projection
+
+   `session.requiresAction` events live forever in the durable log, so a
+   console that replays the log from sequence 0 must not render every
+   historical approval as actionable. `projectPendingApprovals` folds the
+   ordered event log into the approvals that are still undecided *now*:
+
+   - `session.requiresAction` replaces the pending set with the payload's
+     approvals (the producer always emits the full currently-pending set, so
+     re-emission after a worker re-dispatch cannot duplicate cards);
+   - `user.approvalDecision` subtracts the decided approval;
+   - the owning turn finishing (`turn.completed`/`turn.failed`/
+     `turn.cancelled`) clears the set — whatever was pending died with the
+     turn. A `turn.cancelled` for a *different* turn (deleting a queued turn
+     while the session waits on an approval) leaves the set alone.
+
+   Pure function — same events in, same approvals out — so approve-then-reload
+   projects to an empty set instead of a zombie Approve button.
+   -------------------------------------------------------------------------- */
+
+export type PendingApproval = {
+  /** The id to send back via `user.approvalDecision` (`approvalId`). */
+  id: string;
+  /** Tool/function name awaiting the decision. */
+  name: string;
+  arguments?: unknown;
+  /** The raw approval entry from the `session.requiresAction` payload. */
+  raw?: unknown;
+};
+
+/** The approvals carried by one `session.requiresAction` payload. */
+export function approvalsFromRequiresAction(payload: unknown): PendingApproval[] {
+  const approvals = payload && typeof payload === "object" ? (payload as { approvals?: unknown }).approvals : undefined;
+  if (!Array.isArray(approvals)) {
+    return [];
+  }
+  return approvals.map((approval, index) => {
+    const raw = (approval && typeof approval === "object" ? approval : {}) as Record<string, unknown>;
+    const rawItem = raw.rawItem && typeof raw.rawItem === "object" ? raw.rawItem as Record<string, unknown> : {};
+    return {
+      id: String(raw.id ?? raw.callId ?? rawItem.callId ?? index),
+      name: String(raw.name ?? "approval"),
+      arguments: raw.arguments,
+      raw: approval,
+    };
+  });
+}
+
+/** The approvals still awaiting a decision after replaying `events` in order. */
+export function projectPendingApprovals(events: SessionEvent[]): PendingApproval[] {
+  let pending: PendingApproval[] = [];
+  let owningTurnId: string | null = null;
+  for (const event of events) {
+    switch (event.type) {
+      case "session.requiresAction": {
+        pending = approvalsFromRequiresAction(event.payload);
+        owningTurnId = event.turnId ?? null;
+        break;
+      }
+      case "user.approvalDecision": {
+        const payload = event.payload && typeof event.payload === "object" ? event.payload as { approvalId?: unknown } : {};
+        if (typeof payload.approvalId === "string") {
+          pending = pending.filter((approval) => approval.id !== payload.approvalId);
+        }
+        break;
+      }
+      case "turn.completed":
+      case "turn.failed":
+      case "turn.cancelled": {
+        // Scope clearing to the turn that raised the approvals when both
+        // sides carry a turn id; clear conservatively when either is unknown.
+        if (owningTurnId === null || event.turnId == null || event.turnId === owningTurnId) {
+          pending = [];
+          owningTurnId = null;
+        }
+        break;
+      }
+      default:
+        break;
+    }
+  }
+  return pending;
+}

package/src/client.ts

@@ -0,0 +1,52 @@
+import type { OpenGeniClient } from "@opengeni/sdk";
+
+/**
+ * The slice of `OpenGeniClient` the hooks depend on. Structural, so apps can
+ * pass the real SDK client, a proxy-backed client that routes through their
+ * own API, or a scripted client in tests/demos.
+ */
+export type SessionClientLike = Pick<
+  OpenGeniClient,
+  // Sessions, events, composer
+  | "getSession"
+  | "listSessions"
+  | "sendMessage"
+  | "steerMessage"
+  | "interrupt"
+  | "sendApprovalDecision"
+  | "streamEvents"
+  // Turn queue
+  | "listTurns"
+  | "updateQueuedTurn"
+  | "reorderQueuedTurns"
+  | "deleteQueuedTurn"
+  // Goal
+  | "getGoal"
+  | "updateGoal"
+  // Operator context controls (/clear, /compact)
+  | "clearSessionContext"
+  | "compactSessionContext"
+  // Scheduled tasks
+  | "listScheduledTasks"
+  // Files (upload + download-url minting for attachments)
+  | "uploadFile"
+  | "getFile"
+  | "createFileDownloadUrl"
+  // Environments
+  | "listEnvironments"
+  | "createEnvironment"
+  | "updateEnvironment"
+  | "deleteEnvironment"
+  | "setEnvironmentVariable"
+  | "deleteEnvironmentVariable"
+  // Packs
+  | "listPacks"
+  | "registerPack"
+  | "enablePack"
+  | "deletePack"
+  // Workspaces + billing
+  | "listWorkspaces"
+  | "createWorkspace"
+  | "updateWorkspace"
+  | "getBillingUsage"
+>;

package/src/commands/index.ts

@@ -0,0 +1,17 @@
+export type {
+  CommandContext,
+  CommandResult,
+  Notice,
+  SlashArg,
+  SlashCommand,
+} from "./types";
+export {
+  argHint,
+  defaultCommands,
+  filterCommands,
+  firstMissingRequiredArg,
+  hasPermission,
+  matchCommand,
+  parseCommandLine,
+} from "./registry";
+export type { ParsedCommandLine } from "./registry";

package/src/commands/registry.ts

@@ -0,0 +1,236 @@
+import type { Permission } from "@opengeni/sdk";
+import type { CommandContext, SlashArg, SlashCommand } from "./types";
+
+/**
+ * Parse a composer value into a command name + the rest. A command is
+ * recognized ONLY when the value's first character is "/" (the start token);
+ * anything else is plain chat and returns null.
+ *
+ * "/cl"        -> { name: "cl", rest: "", hasTrailingSpace: false }
+ * "/goal "     -> { name: "goal", rest: "", hasTrailingSpace: true }
+ * "/goal pause"-> { name: "goal", rest: "pause", hasTrailingSpace: false }
+ */
+export type ParsedCommandLine = {
+  name: string;
+  rest: string;
+  /** True when the name token is closed by a space — arg-hint mode. */
+  hasTrailingSpace: boolean;
+  args: string[];
+};
+
+export function parseCommandLine(value: string): ParsedCommandLine | null {
+  if (value[0] !== "/") {
+    return null;
+  }
+  const body = value.slice(1);
+  const firstSpace = body.indexOf(" ");
+  if (firstSpace === -1) {
+    return { name: body, rest: "", hasTrailingSpace: false, args: [] };
+  }
+  const name = body.slice(0, firstSpace);
+  const rest = body.slice(firstSpace + 1);
+  return {
+    name,
+    rest,
+    hasTrailingSpace: true,
+    args: rest.split(/\s+/).filter((token) => token.length > 0),
+  };
+}
+
+const PERMISSION_SUPERUSER: Permission = "workspace:admin";
+
+/** Whether the operator's permission set satisfies a command's gate. */
+export function hasPermission(required: Permission | undefined, permissions: Permission[]): boolean {
+  if (!required) {
+    return true;
+  }
+  return permissions.includes(required) || permissions.includes(PERMISSION_SUPERUSER);
+}
+
+/** Match a command (by name or alias) against the value. */
+export function matchCommand(commands: readonly SlashCommand[], value: string): SlashCommand | null {
+  const parsed = parseCommandLine(value);
+  if (!parsed) {
+    return null;
+  }
+  const token = parsed.name.toLowerCase();
+  return commands.find((command) => command.name === token || command.aliases?.includes(token)) ?? null;
+}
+
+type FilterCtx = Pick<CommandContext, "sessionId" | "status" | "permissions">;
+
+/**
+ * The commands visible for the current token + context. Permission-absent and
+ * `available()===false` commands are dropped entirely (a gated command is never
+ * shown, not shown-disabled). Filtering is a prefix match on name/alias.
+ */
+export function filterCommands(commands: readonly SlashCommand[], token: string, ctx: FilterCtx): SlashCommand[] {
+  const needle = token.toLowerCase();
+  return commands.filter((command) => {
+    if (!hasPermission(command.permission, ctx.permissions)) {
+      return false;
+    }
+    if (command.available && !command.available(ctx)) {
+      return false;
+    }
+    if (needle.length === 0) {
+      return true;
+    }
+    return command.name.startsWith(needle) || (command.aliases?.some((alias) => alias.startsWith(needle)) ?? false);
+  });
+}
+
+/** Render a command's arg hint for the palette footer / help, e.g. "<pause|resume>". */
+export function argHint(args: readonly SlashArg[] | undefined): string {
+  if (!args || args.length === 0) {
+    return "";
+  }
+  return args
+    .map((arg) => {
+      const label = arg.oneOf ? arg.oneOf.join("|") : arg.name;
+      return arg.required ? `<${label}>` : `[${label}]`;
+    })
+    .join(" ");
+}
+
+/** The first required arg that has not yet been supplied, if any. */
+export function firstMissingRequiredArg(command: SlashCommand, args: string[]): SlashArg | null {
+  const required = (command.args ?? []).filter((arg) => arg.required);
+  for (let i = 0; i < required.length; i += 1) {
+    const value = args[i];
+    if (value === undefined || value.length === 0) {
+      return required[i] ?? null;
+    }
+  }
+  return null;
+}
+
+function requireSession(ctx: CommandContext): string {
+  if (!ctx.sessionId) {
+    throw new Error("No active session yet — start a session first.");
+  }
+  return ctx.sessionId;
+}
+
+const hasSession = (ctx: FilterCtx): boolean => ctx.sessionId !== null;
+
+/**
+ * The default command set. Adding a command is one object literal here; the
+ * palette list, filter, arg-hint footer, and /help all render from this array.
+ * Apps concat their own commands via the ChatComposer `commands` prop.
+ */
+export const defaultCommands: readonly SlashCommand[] = [
+  {
+    name: "help",
+    aliases: ["?"],
+    description: "Show available commands.",
+    run: (_args, ctx) => {
+      ctx.openHelp();
+      return { status: "ok" };
+    },
+  },
+  {
+    name: "clear-view",
+    description: "Clear the local timeline view (this device only; no server change).",
+    run: (_args, ctx) => {
+      // clearView() reports whether the host actually wired a view-reset. If it
+      // didn't (the console surface has no resettable local timeline), reporting
+      // "Local view cleared." would be a false success — return an honest error
+      // instead so the operator isn't told something happened when nothing did.
+      const cleared = ctx.clearView();
+      if (!cleared) {
+        return { status: "error", message: "This view can't be cleared here (no local timeline to reset)." };
+      }
+      return { status: "ok", message: "Local view cleared." };
+    },
+  },
+  {
+    name: "goal",
+    description: "Pause or resume the session's goal loop.",
+    permission: "sessions:control",
+    available: hasSession,
+    args: [{ name: "action", required: true, oneOf: ["pause", "resume"], description: "pause | resume" }],
+    run: async (args, ctx) => {
+      const sessionId = requireSession(ctx);
+      const action = args[0];
+      if (action !== "pause" && action !== "resume") {
+        return { status: "error", message: "Usage: /goal pause | /goal resume" };
+      }
+      try {
+        await ctx.client.updateGoal(ctx.workspaceId, sessionId, { status: action === "pause" ? "paused" : "active" });
+        return { status: "ok", message: action === "pause" ? "Goal paused." : "Goal resumed." };
+      } catch (cause) {
+        return { status: "error", message: goalErrorMessage(cause, action) };
+      }
+    },
+  },
+  {
+    name: "compact",
+    description: "Compact the conversation context now.",
+    permission: "sessions:control",
+    available: hasSession,
+    run: async (_args, ctx) => {
+      const sessionId = requireSession(ctx);
+      try {
+        const result = await ctx.client.compactSessionContext(ctx.workspaceId, sessionId);
+        return { status: "ok", message: result.message };
+      } catch (cause) {
+        return { status: "error", message: errorMessage(cause) ?? "Could not compact context." };
+      }
+    },
+  },
+  {
+    name: "clear",
+    description: "Clear the conversation context (destructive; audit-preserved).",
+    permission: "sessions:control",
+    danger: true,
+    available: hasSession,
+    run: async (_args, ctx) => {
+      const sessionId = requireSession(ctx);
+      const confirmed = await ctx.confirm();
+      if (!confirmed) {
+        // Canceled: no error, but keep the "/clear" draft so the operator who
+        // backed out doesn't silently lose what they typed.
+        return { status: "ok", keepDraft: true };
+      }
+      try {
+        await ctx.client.clearSessionContext(ctx.workspaceId, sessionId);
+        return { status: "ok", message: "Context cleared." };
+      } catch (cause) {
+        return { status: "error", message: clearErrorMessage(cause) };
+      }
+    },
+  },
+];
+
+function errorMessage(cause: unknown): string | undefined {
+  if (cause && typeof cause === "object" && "message" in cause && typeof (cause as { message?: unknown }).message === "string") {
+    return (cause as { message: string }).message;
+  }
+  return undefined;
+}
+
+function statusCode(cause: unknown): number | undefined {
+  if (cause && typeof cause === "object" && "status" in cause && typeof (cause as { status?: unknown }).status === "number") {
+    return (cause as { status: number }).status;
+  }
+  return undefined;
+}
+
+function goalErrorMessage(cause: unknown, action: "pause" | "resume"): string {
+  const code = statusCode(cause);
+  if (code === 404) {
+    return "This session has no goal to control.";
+  }
+  if (code === 409) {
+    return action === "resume" ? "Only a paused goal can be resumed." : "Goal is already in a terminal state.";
+  }
+  return errorMessage(cause) ?? `Could not ${action} the goal.`;
+}
+
+function clearErrorMessage(cause: unknown): string {
+  if (statusCode(cause) === 409) {
+    return "Can't clear context mid-turn — stop the current turn first.";
+  }
+  return errorMessage(cause) ?? "Could not clear context.";
+}

package/src/commands/types.ts

@@ -0,0 +1,88 @@
+import type { Permission, SessionStatus } from "@opengeni/sdk";
+import type { SessionClientLike } from "../client";
+
+/**
+ * The slash-command registry. A command is a SESSION / OPERATOR control — an
+ * action on the session or the UI (clear, compact, pause the goal, show help) —
+ * NOT a structured way to talk to the agent. The human↔agent channel stays
+ * plain chat; the palette only recognizes a leading "/" and never sends a
+ * command to the model.
+ *
+ * Two kinds, modeled by where the handler does its work:
+ *  - CLIENT commands touch only the local UI (e.g. /help, /clear-view).
+ *  - SERVER commands call the API through the SDK (e.g. /clear, /compact,
+ *    /goal).
+ * Both are just `run(args, ctx)`; `ctx` exposes the client for server commands
+ * and the UI affordances (notice, openHelp, clearView, confirm) for both.
+ */
+
+/** A positional argument a command accepts after its name. */
+export type SlashArg = {
+  name: string;
+  /** Enter runs only once every required arg is present; otherwise autocompletes. */
+  required?: boolean;
+  /** Closed value set (rendered as a hint; validated by the command itself). */
+  oneOf?: readonly string[];
+  description?: string;
+};
+
+/** Transient feedback surfaced in the composer (generalized error line). */
+export type Notice = { tone: "ok" | "error"; message: string };
+
+/** Everything a command handler can reach. Assembled by the composer. */
+export type CommandContext = {
+  /** SDK-shaped client for server commands. */
+  client: SessionClientLike;
+  workspaceId: string;
+  /** Null before a session exists (server commands should guard on this). */
+  sessionId: string | null;
+  status: SessionStatus | null;
+  /** The operator's permissions on this workspace (gates command visibility). */
+  permissions: Permission[];
+  /** Surface a transient ok/error notice in the composer. */
+  notice: (notice: Notice) => void;
+  /** Open the in-composer /help panel (rendered from the registry). */
+  openHelp: () => void;
+  /**
+   * Reset only the LOCAL timeline view — no server call. Returns whether a
+   * view-reset affordance was actually wired (and thus had an effect): the host
+   * surface supplies one via the composer's `onClearView` prop, and consoles
+   * that don't (no resettable local timeline) get `false`. The /clear-view
+   * command uses this to avoid reporting a false "cleared" success on a no-op.
+   */
+  clearView: () => boolean;
+  /** Show the danger confirm bar; resolves true once the operator confirms. */
+  confirm: () => Promise<boolean>;
+};
+
+export type CommandResult = {
+  status: "ok" | "error";
+  message?: string;
+  /**
+   * Keep the composer draft instead of clearing it on an ok result. Used when a
+   * command resolves to a no-op the operator may want to retry — e.g. canceling
+   * the /clear confirm bar returns ok (no error) but must NOT wipe the typed
+   * "/clear" draft. Default false: a successful command clears the draft.
+   */
+  keepDraft?: boolean;
+};
+
+export type SlashCommand = {
+  /** Primary token after the slash (no leading "/"). */
+  name: string;
+  /** Alternate tokens that resolve to this command. */
+  aliases?: readonly string[];
+  description: string;
+  args?: readonly SlashArg[];
+  /** Required permission; the command is hidden from the palette without it. */
+  permission?: Permission;
+  /** Destructive — the palette shows a confirm bar before running. */
+  danger?: boolean;
+  /**
+   * Dynamic availability beyond the permission gate (e.g. hide a server command
+   * until a session exists). Returning false hides the command.
+   */
+  available?: (ctx: Pick<CommandContext, "sessionId" | "status" | "permissions">) => boolean;
+  /** Execute the command. Throwing is caught and surfaced as an error notice. */
+  run: (args: string[], ctx: CommandContext) => Promise<CommandResult> | CommandResult;
+};