@stigmer/ink 0.0.88

package/src/app/SessionApp.tsx

@@ -0,0 +1,74 @@
+import React from "react";
+import { Box, Text } from "ink";
+import type { TokenProvider } from "@stigmer/sdk";
+import { InkStigmerProvider } from "../provider.js";
+import { createNodeClient, type NodeClientConfig } from "@stigmer/sdk/node";
+import { SessionView } from "./SessionView.js";
+
+/** Props for {@link SessionApp}. */
+export interface SessionAppProps {
+  /** Session ID to display and converse in. */
+  readonly sessionId: string;
+  /** Organization slug for creating follow-up executions. */
+  readonly org: string;
+  /** Stigmer API server URL. */
+  readonly baseUrl: string;
+  /** Static API key for authentication. */
+  readonly apiKey?: string;
+  /** Dynamic token provider for authentication. */
+  readonly getAccessToken?: TokenProvider;
+}
+
+/**
+ * Self-contained top-level Ink application for viewing and
+ * interacting with a Stigmer agent session in the terminal.
+ *
+ * Creates a Node.js-compatible Stigmer client, wraps in
+ * `InkStigmerProvider`, and renders a {@link SessionView}.
+ *
+ * This is the highest-level component — platform builders who
+ * need more control should compose {@link InkStigmerProvider},
+ * {@link SessionView}, or the individual components directly.
+ *
+ * @example
+ * ```tsx
+ * import { render } from "ink";
+ * import { SessionApp } from "@stigmer/ink";
+ *
+ * render(
+ *   <SessionApp
+ *     sessionId="ses-abc123"
+ *     org="my-org"
+ *     baseUrl="https://api.stigmer.ai"
+ *     apiKey={process.env.STIGMER_API_KEY}
+ *   />
+ * );
+ * ```
+ */
+export function SessionApp({
+  sessionId,
+  org,
+  baseUrl,
+  apiKey,
+  getAccessToken,
+}: SessionAppProps) {
+  const clientConfig: NodeClientConfig = { baseUrl, apiKey, getAccessToken };
+
+  const client = React.useMemo(
+    () => createNodeClient(clientConfig),
+    [baseUrl, apiKey, getAccessToken],
+  );
+
+  return (
+    <InkStigmerProvider client={client}>
+      <Box flexDirection="column">
+        <Box paddingLeft={1} paddingBottom={1}>
+          <Text dimColor>
+            Session {sessionId} · {org}
+          </Text>
+        </Box>
+        <SessionView sessionId={sessionId} org={org} />
+      </Box>
+    </InkStigmerProvider>
+  );
+}

package/src/app/SessionView.tsx

@@ -0,0 +1,164 @@
+import React, { useState } from "react";
+import { Box, Text, useInput } from "ink";
+import Spinner from "ink-spinner";
+import { useSessionConversation, resolvedSubject, PENDING_SUBJECT } from "@stigmer/react";
+import { MessageThread } from "../components/MessageThread.js";
+import { TodoList } from "../components/TodoList.js";
+import { FollowUpInput } from "../components/FollowUpInput.js";
+import { UsageWidget } from "../components/UsageWidget.js";
+import { ExecutionProgress } from "../components/ExecutionProgress.js";
+
+/** Props for {@link SessionView}. */
+export interface SessionViewProps {
+  /** Session ID to display and converse in. */
+  readonly sessionId: string;
+  /** Organization slug for creating follow-up executions. */
+  readonly org: string;
+}
+
+/**
+ * Full-featured session conversation view for the terminal.
+ *
+ * Uses the headless {@link useSessionConversation} hook from
+ * `@stigmer/react` to manage the complete conversation lifecycle,
+ * then renders the thread and input using Ink terminal components.
+ *
+ * This is the main composition component that platform builders
+ * drop into their Ink apps for a complete agent conversation UI.
+ *
+ * @example
+ * ```tsx
+ * import { InkStigmerProvider, createNodeClient, SessionView } from "@stigmer/ink";
+ *
+ * const client = createNodeClient({ baseUrl: "...", apiKey: "..." });
+ *
+ * render(
+ *   <InkStigmerProvider client={client}>
+ *     <SessionView sessionId="ses-xxx" org="my-org" />
+ *   </InkStigmerProvider>
+ * );
+ * ```
+ */
+export function SessionView({ sessionId, org }: SessionViewProps) {
+  const conv = useSessionConversation(sessionId, org);
+  const [expandTools, setExpandTools] = useState(false);
+
+  useInput((input, key) => {
+    if (key.ctrl && input === "o") {
+      setExpandTools((e) => !e);
+    }
+  });
+
+  if (conv.isLoading) {
+    return (
+      <Box gap={1} paddingLeft={1}>
+        <Text color="cyan">
+          <Spinner type="dots" />
+        </Text>
+        <Text>Loading session...</Text>
+      </Box>
+    );
+  }
+
+  if (conv.loadError) {
+    return (
+      <Box flexDirection="column" paddingLeft={1}>
+        <Text color="red" bold>
+          Failed to load session
+        </Text>
+        <Text color="red">{conv.loadError.message}</Text>
+      </Box>
+    );
+  }
+
+  const allExecutions = [
+    ...conv.completedExecutions,
+    ...(conv.activeStreamExecution ? [conv.activeStreamExecution] : []),
+  ];
+
+  const activeTodos = conv.activeStreamExecution?.status?.todos;
+  const contextInfo = conv.activeStreamExecution?.status?.contextInfo;
+  const summarizationCount = contextInfo?.summarizationEvents?.length ?? 0;
+
+  const subject = resolvedSubject(conv.session?.spec?.subject);
+
+  return (
+    <Box flexDirection="column">
+      {subject && subject !== PENDING_SUBJECT && (
+        <Box paddingLeft={1} marginBottom={1}>
+          <Text dimColor bold>{subject}</Text>
+        </Box>
+      )}
+
+      {conv.isConnecting && (
+        <Box gap={1} paddingLeft={1}>
+          <Text color="cyan">
+            <Spinner type="dots" />
+          </Text>
+          <Text dimColor>Connecting to stream...</Text>
+        </Box>
+      )}
+
+      {conv.streamError && (
+        <Box flexDirection="column" paddingLeft={1} marginBottom={1}>
+          <Box gap={1}>
+            <Text color="yellow" bold>Stream disconnected</Text>
+            <Text dimColor>— reconnecting...</Text>
+          </Box>
+          <Text color="red" dimColor>{conv.streamError.message}</Text>
+        </Box>
+      )}
+
+      {conv.activePhase != null && conv.activePhase !== 0 && (
+        <ExecutionProgress phase={conv.activePhase} />
+      )}
+
+      <MessageThread
+        executions={conv.completedExecutions}
+        activeStreamExecution={conv.activeStreamExecution}
+        pendingUserMessage={conv.pendingUserMessage}
+        onApprovalSubmit={conv.submitApproval}
+        submittingApprovalIds={conv.submittingApprovalIds}
+        expandToolCalls={expandTools}
+      />
+
+      {summarizationCount > 0 && (
+        <Box paddingLeft={1} marginTop={1}>
+          <Text dimColor>
+            Context compacted ({summarizationCount} {summarizationCount === 1 ? "event" : "events"}, {Math.round(contextInfo!.utilizationPercent)}% utilization)
+          </Text>
+        </Box>
+      )}
+
+      {activeTodos && Object.keys(activeTodos).length > 0 && (
+        <Box marginTop={1} paddingLeft={1}>
+          <TodoList todos={activeTodos} />
+        </Box>
+      )}
+
+      {conv.approvalError && (
+        <Box paddingLeft={1}>
+          <Text color="red">
+            Approval error: {conv.approvalError.message}
+          </Text>
+        </Box>
+      )}
+
+      {conv.sendError && (
+        <Box paddingLeft={1}>
+          <Text color="red">
+            Send error: {conv.sendError.message}
+          </Text>
+        </Box>
+      )}
+
+      <UsageWidget executions={allExecutions} />
+
+      <FollowUpInput
+        onSubmit={(message) => conv.sendFollowUp(message)}
+        isSubmitting={conv.isSending}
+        disabled={!conv.canSendFollowUp}
+      />
+    </Box>
+  );
+}

package/src/cli/stigmer-ink.tsx

@@ -0,0 +1,148 @@
+#!/usr/bin/env tsx
+
+import React from "react";
+import { Readable } from "node:stream";
+import { render } from "ink";
+import { SessionApp } from "../app/SessionApp.js";
+
+interface CliConfig {
+  sessionId: string;
+  org: string;
+  baseUrl: string;
+  apiKey?: string;
+}
+
+function parseArgs(argv: string[]): CliConfig | null {
+  const args = argv.slice(2);
+  const config: Partial<CliConfig> = {};
+
+  for (let i = 0; i < args.length; i++) {
+    switch (args[i]) {
+      case "--session":
+      case "-s":
+        config.sessionId = args[++i];
+        break;
+      case "--org":
+      case "-o":
+        config.org = args[++i];
+        break;
+      case "--base-url":
+      case "-u":
+        config.baseUrl = args[++i];
+        break;
+      case "--api-key":
+      case "-k":
+        config.apiKey = args[++i];
+        break;
+      case "--help":
+      case "-h":
+        printUsage();
+        process.exit(0);
+      default:
+        if (args[i].startsWith("-")) {
+          console.error(`Unknown option: ${args[i]}`);
+          printUsage();
+          process.exit(1);
+        }
+    }
+  }
+
+  config.baseUrl ??= process.env.STIGMER_BASE_URL;
+  config.apiKey ??= process.env.STIGMER_API_KEY;
+
+  if (!config.sessionId || !config.org || !config.baseUrl) {
+    return null;
+  }
+
+  return config as CliConfig;
+}
+
+async function readStdinJson(): Promise<CliConfig | null> {
+  if (process.stdin.isTTY) return null;
+
+  return new Promise((resolve) => {
+    let data = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => (data += chunk));
+    process.stdin.on("end", () => {
+      try {
+        const parsed = JSON.parse(data);
+        if (parsed.sessionId && parsed.org && parsed.baseUrl) {
+          resolve(parsed as CliConfig);
+        } else {
+          resolve(null);
+        }
+      } catch {
+        resolve(null);
+      }
+    });
+    setTimeout(() => resolve(null), 1000);
+  });
+}
+
+function printUsage(): void {
+  console.log(`
+stigmer-ink — Terminal session viewer for the Stigmer platform
+
+Usage:
+  stigmer-ink --session <id> --org <slug> [options]
+  echo '{"sessionId":"...","org":"...","baseUrl":"..."}' | stigmer-ink
+
+Options:
+  -s, --session <id>    Session ID (required)
+  -o, --org <slug>      Organization slug (required)
+  -u, --base-url <url>  Stigmer API URL (or STIGMER_BASE_URL env)
+  -k, --api-key <key>   API key (or STIGMER_API_KEY env)
+  -h, --help            Show this help message
+
+Environment:
+  STIGMER_BASE_URL      Default API server URL
+  STIGMER_API_KEY       Default API key
+`);
+}
+
+async function main() {
+  let config = parseArgs(process.argv);
+
+  if (!config) {
+    config = await readStdinJson();
+  }
+
+  if (!config) {
+    console.error(
+      "Error: --session, --org, and --base-url are required.\n" +
+        "Run with --help for usage information.",
+    );
+    process.exit(1);
+  }
+
+  const isTTY = Boolean(process.stdin.isTTY);
+  const stdin = isTTY
+    ? process.stdin
+    : new Readable({ read() {} }) as unknown as NodeJS.ReadStream;
+
+  const instance = render(
+    <SessionApp
+      sessionId={config.sessionId}
+      org={config.org}
+      baseUrl={config.baseUrl}
+      apiKey={config.apiKey}
+    />,
+    { stdin, exitOnCtrlC: isTTY, debug: !isTTY },
+  );
+
+  const cleanup = () => {
+    instance.unmount();
+    process.exit(0);
+  };
+
+  process.on("SIGINT", cleanup);
+  process.on("SIGTERM", cleanup);
+
+  await instance.waitUntilExit();
+}
+
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});

package/src/components/ApprovalPrompt.tsx

@@ -0,0 +1,139 @@
+import React, { useState } from "react";
+import { Box, Text, useInput } from "ink";
+import type { PendingApproval } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
+import { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+/** Props for {@link ApprovalPrompt}. */
+export interface ApprovalPromptProps {
+  /** The pending approval request to render. */
+  readonly pendingApproval: PendingApproval;
+  /** Called when the user selects an action. */
+  readonly onSubmit: (action: ApprovalAction) => void;
+  /** Disables input while an approval submission is in flight. */
+  readonly isSubmitting?: boolean;
+}
+
+interface ActionOption {
+  readonly label: string;
+  readonly action: ApprovalAction;
+  readonly color: string;
+  readonly shortcut: string;
+}
+
+const OPTIONS: readonly ActionOption[] = [
+  {
+    label: "Approve",
+    action: ApprovalAction.APPROVE,
+    color: "green",
+    shortcut: "y",
+  },
+  {
+    label: "Reject",
+    action: ApprovalAction.REJECT,
+    color: "red",
+    shortcut: "n",
+  },
+  {
+    label: "Skip",
+    action: ApprovalAction.SKIP,
+    color: "yellow",
+    shortcut: "s",
+  },
+];
+
+/**
+ * HITL approval prompt for tool call authorization.
+ *
+ * Displays the tool name and args preview, then presents
+ * Approve/Reject/Skip options navigable via arrow keys or
+ * shortcut keys (y/n/s). Press Enter to confirm the highlighted
+ * selection.
+ */
+export function ApprovalPrompt({
+  pendingApproval,
+  onSubmit,
+  isSubmitting = false,
+}: ApprovalPromptProps) {
+  const [selectedIndex, setSelectedIndex] = useState(0);
+
+  useInput(
+    (input, key) => {
+      if (isSubmitting) return;
+
+      if (key.upArrow || key.leftArrow) {
+        setSelectedIndex((i) => (i > 0 ? i - 1 : OPTIONS.length - 1));
+      } else if (key.downArrow || key.rightArrow) {
+        setSelectedIndex((i) => (i < OPTIONS.length - 1 ? i + 1 : 0));
+      } else if (key.return) {
+        onSubmit(OPTIONS[selectedIndex].action);
+      } else {
+        const shortcutMatch = OPTIONS.findIndex(
+          (o) => o.shortcut === input.toLowerCase(),
+        );
+        if (shortcutMatch >= 0) {
+          onSubmit(OPTIONS[shortcutMatch].action);
+        }
+      }
+    },
+  );
+
+  const serverSlug = pendingApproval.mcpServerSlug;
+  const toolLabel = serverSlug
+    ? `${serverSlug}/${pendingApproval.toolName}`
+    : pendingApproval.toolName;
+
+  return (
+    <Box
+      flexDirection="column"
+      paddingLeft={2}
+      paddingTop={1}
+      paddingBottom={1}
+      borderStyle="round"
+      borderColor="yellow"
+    >
+      <Box gap={1}>
+        <Text color="yellow" bold>
+          ⚠ Approval required
+        </Text>
+        {pendingApproval.fromSubAgent && (
+          <Text dimColor>
+            via {pendingApproval.subAgentSubject || pendingApproval.subAgentName}
+          </Text>
+        )}
+      </Box>
+
+      <Box paddingLeft={2} marginTop={1} flexDirection="column">
+        <Box gap={1}>
+          <Text dimColor>Tool:</Text>
+          <Text bold>{toolLabel}</Text>
+        </Box>
+        {pendingApproval.argsPreview && (
+          <Box gap={1}>
+            <Text dimColor>Args:</Text>
+            <Text wrap="truncate-end">{pendingApproval.argsPreview}</Text>
+          </Box>
+        )}
+      </Box>
+
+      <Box gap={2} marginTop={1} paddingLeft={2}>
+        {OPTIONS.map((opt, idx) => (
+          <Text
+            key={opt.shortcut}
+            color={idx === selectedIndex ? opt.color : undefined}
+            dimColor={idx !== selectedIndex}
+            bold={idx === selectedIndex}
+          >
+            {idx === selectedIndex ? "▸ " : "  "}
+            [{opt.shortcut}] {opt.label}
+          </Text>
+        ))}
+      </Box>
+
+      {isSubmitting && (
+        <Box paddingLeft={2} marginTop={1}>
+          <Text dimColor>Submitting...</Text>
+        </Box>
+      )}
+    </Box>
+  );
+}

package/src/components/ExecutionProgress.tsx

@@ -0,0 +1,75 @@
+import React from "react";
+import { Box, Text } from "ink";
+import Spinner from "ink-spinner";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+/** Props for {@link ExecutionProgress}. */
+export interface ExecutionProgressProps {
+  /** Current execution phase. */
+  readonly phase: ExecutionPhase;
+}
+
+interface PhaseDisplay {
+  readonly label: string;
+  readonly color?: string;
+  readonly showSpinner: boolean;
+}
+
+const PHASE_DISPLAY: ReadonlyMap<ExecutionPhase, PhaseDisplay> = new Map([
+  [ExecutionPhase.EXECUTION_PENDING, { label: "Pending", showSpinner: true }],
+  [
+    ExecutionPhase.EXECUTION_IN_PROGRESS,
+    { label: "Running", color: "yellow", showSpinner: true },
+  ],
+  [
+    ExecutionPhase.EXECUTION_COMPLETED,
+    { label: "Completed", color: "green", showSpinner: false },
+  ],
+  [
+    ExecutionPhase.EXECUTION_FAILED,
+    { label: "Failed", color: "red", showSpinner: false },
+  ],
+  [
+    ExecutionPhase.EXECUTION_CANCELLED,
+    { label: "Cancelled", showSpinner: false },
+  ],
+  [
+    ExecutionPhase.EXECUTION_TERMINATED,
+    { label: "Terminated", color: "red", showSpinner: false },
+  ],
+  [
+    ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL,
+    { label: "Waiting for approval", color: "yellow", showSpinner: false },
+  ],
+  [ExecutionPhase.EXECUTION_PAUSED, { label: "Paused", showSpinner: false }],
+]);
+
+/**
+ * Displays the current execution phase as a compact terminal badge.
+ *
+ * Shows a spinner for active phases (pending, in-progress) and
+ * static indicators for terminal phases.
+ *
+ * Renders nothing for unspecified phases.
+ */
+export function ExecutionProgress({ phase }: ExecutionProgressProps) {
+  const display = PHASE_DISPLAY.get(phase);
+  if (!display) return null;
+
+  return (
+    <Box gap={1} paddingLeft={1}>
+      {display.showSpinner ? (
+        <Text color={display.color ?? "cyan"}>
+          <Spinner type="dots" />
+        </Text>
+      ) : (
+        <Text color={display.color}>
+          {phase === ExecutionPhase.EXECUTION_COMPLETED ? "✓" : "●"}
+        </Text>
+      )}
+      <Text color={display.color} dimColor={!display.color}>
+        {display.label}
+      </Text>
+    </Box>
+  );
+}

package/src/components/FollowUpInput.tsx

@@ -0,0 +1,70 @@
+import React, { useState } from "react";
+import { Box, Text, useStdin } from "ink";
+import TextInput from "ink-text-input";
+
+/** Props for {@link FollowUpInput}. */
+export interface FollowUpInputProps {
+  /** Called when the user submits a message (Enter key). */
+  readonly onSubmit: (message: string) => void;
+  /** Shows a "sending" indicator and disables input. */
+  readonly isSubmitting?: boolean;
+  /** Disables the input entirely. */
+  readonly disabled?: boolean;
+  /** Placeholder text. Default: "Reply..." */
+  readonly placeholder?: string;
+}
+
+/**
+ * Terminal text input for sending follow-up messages in a session.
+ *
+ * Renders a single-line text input with a submit hint. Press Enter
+ * to submit, Ctrl+C to exit the application.
+ */
+export function FollowUpInput({
+  onSubmit,
+  isSubmitting = false,
+  disabled = false,
+  placeholder = "Reply...",
+}: FollowUpInputProps) {
+  const [value, setValue] = useState("");
+  const { isRawModeSupported } = useStdin();
+  const isDisabled = disabled || isSubmitting || !isRawModeSupported;
+
+  const handleSubmit = (input: string) => {
+    const trimmed = input.trim();
+    if (!trimmed) return;
+    onSubmit(trimmed);
+    setValue("");
+  };
+
+  if (isDisabled) {
+    return (
+      <Box paddingLeft={1} paddingTop={1}>
+        <Text dimColor>
+          {isSubmitting ? "Sending..." : placeholder}
+        </Text>
+      </Box>
+    );
+  }
+
+  return (
+    <Box paddingLeft={1} paddingTop={1} flexDirection="column">
+      <Box gap={1}>
+        <Text color="cyan" bold>
+          ❯
+        </Text>
+        <TextInput
+          value={value}
+          onChange={setValue}
+          onSubmit={handleSubmit}
+          placeholder={placeholder}
+        />
+      </Box>
+      <Box paddingLeft={2}>
+        <Text dimColor>
+          Enter to send · Ctrl+C to exit
+        </Text>
+      </Box>
+    </Box>
+  );
+}