@opengeni/react 1.4.2 → 1.4.5-canary.37458084490001

package/src/testing/session-scenarios.ts

@@ -0,0 +1,326 @@
+// Deterministic session scenarios for visual harnesses (web dev gallery and native lab).
+// They use the same durable event shapes a live session produces, so every renderer
+// replays identical input through the official projection with no model calls.
+import type { SessionEvent } from "@opengeni/sdk";
+
+export type LabScenarioId = "answer" | "working" | "needs-you" | "history" | "failure" | "long";
+
+export interface LabScenario {
+  id: LabScenarioId;
+  title: string;
+  events: SessionEvent[];
+  /** Whether the session is currently running a turn. */
+  running: boolean;
+}
+
+function recorder(sessionId: string) {
+  const events: SessionEvent[] = [];
+  let clock = Date.parse("2026-10-03T09:00:00Z");
+  const push = (type: string, payload: unknown, turnId: string | null, advanceMs = 2_000) => {
+    clock += advanceMs;
+    events.push({
+      id: `${sessionId}-evt-${events.length + 1}`,
+      workspaceId: "lab-workspace",
+      sessionId,
+      sequence: events.length + 1,
+      type,
+      payload,
+      turnId,
+      occurredAt: new Date(clock).toISOString(),
+    } as SessionEvent);
+  };
+  const tool = (
+    turnId: string,
+    id: string,
+    name: string,
+    args: unknown,
+    output?: unknown,
+    durationMs = 3_000,
+  ) => {
+    push("agent.toolCall.created", { id, name, arguments: args }, turnId, 800);
+    if (output !== undefined) push("agent.toolCall.output", { id, output }, turnId, durationMs);
+  };
+  return { events, push, tool };
+}
+
+function answer(): LabScenario {
+  const r = recorder("lab-answer");
+  const t = "turn-answer";
+  r.push(
+    "user.message",
+    { text: "What's the difference between a retry and a resume for a failed run?" },
+    t,
+  );
+  r.push("turn.started", {}, t, 400);
+  r.push(
+    "agent.reasoning.delta",
+    { text: "The user wants a crisp conceptual distinction, with an example." },
+    t,
+    1_500,
+  );
+  const text = [
+    "**Retry** starts the failed step again from its last durable checkpoint. **Resume** continues the whole run from where it paused, keeping everything already done.",
+    "",
+    "### When to use which",
+    "",
+    "- **Retry** when a single step failed for a transient reason (timeout, rate limit).",
+    "- **Resume** when the run was *waiting* — for an approval, an answer, or capacity.",
+    "",
+    "```bash",
+    "opengeni sessions retry 7f3c --step build",
+    "```",
+    "",
+    "Neither replays side effects that already succeeded.",
+  ].join("\n");
+  r.push("agent.message.delta", { text }, t, 2_500);
+  r.push("agent.message.completed", { text }, t, 300);
+  r.push("turn.completed", { output: text }, t, 200);
+  return { id: "answer", title: "Quick answer", events: r.events, running: false };
+}
+
+function working(): LabScenario {
+  const r = recorder("lab-working");
+  const t = "turn-working";
+  r.push(
+    "user.message",
+    {
+      text: "The checkout tests started failing after the currency change. Can you find out why and fix it?",
+    },
+    t,
+  );
+  r.push("turn.started", {}, t, 400);
+  r.push(
+    "agent.reasoning.delta",
+    { text: "Start by reproducing the failure, then narrow to the currency formatting path." },
+    t,
+    1_800,
+  );
+  r.tool(
+    t,
+    "c1",
+    "exec_command",
+    { cmd: "bun test checkout" },
+    "3 failed, 41 passed\n✗ formats totals in NOK\n✗ rounds VAT per line\n✗ shows discount",
+    6_000,
+  );
+  r.tool(
+    t,
+    "c2",
+    "search_files",
+    { query: "formatCurrency(" },
+    "src/money/format.ts:12\nsrc/checkout/summary.tsx:48\nsrc/checkout/line.tsx:31",
+  );
+  r.push(
+    "agent.message.delta",
+    {
+      text: "Found it: the currency change switched to minor units, but the summary still divides by 100.",
+      phase: "commentary",
+    },
+    t,
+    1_200,
+  );
+  r.push(
+    "agent.message.completed",
+    {
+      text: "Found it: the currency change switched to minor units, but the summary still divides by 100.",
+      phase: "commentary",
+    },
+    t,
+    200,
+  );
+  r.tool(t, "c3", "apply_patch", { path: "src/checkout/summary.tsx" }, "Updated 1 file (+3 −5)");
+  r.tool(t, "c4", "exec_command", { cmd: "bun test checkout" });
+  return { id: "working", title: "Working", events: r.events, running: true };
+}
+
+function needsYou(): LabScenario {
+  const r = recorder("lab-needs-you");
+  const t = "turn-needs-you";
+  r.push("user.message", { text: "Ship the fix to the preview environment and tell the team." }, t);
+  r.push("turn.started", {}, t, 400);
+  r.tool(t, "n1", "exec_command", { cmd: "bun run build" }, "Build completed in 41s", 8_000);
+  r.tool(t, "n2", "list_channels", { query: "release" }, "#releases, #release-ops");
+  r.push(
+    "agent.toolCall.created",
+    {
+      id: "n3",
+      name: "deploy_preview",
+      arguments: { environment: "preview", ref: "fix/checkout-minor-units" },
+    },
+    t,
+    900,
+  );
+  r.push(
+    "session.requiresAction",
+    {
+      approvals: [
+        {
+          id: "n3",
+          name: "deploy_preview",
+          arguments: { environment: "preview", ref: "fix/checkout-minor-units" },
+        },
+      ],
+    },
+    t,
+    300,
+  );
+  r.push(
+    "session.humanInput.requested",
+    {
+      request: {
+        id: "hi-1",
+        allowSkip: true,
+        questions: [
+          {
+            id: "channel",
+            kind: "single_select",
+            prompt: "Where should I announce the preview?",
+            label: "Announcement",
+            required: true,
+            options: [
+              { id: "releases", label: "#releases", description: "Team-wide release notes" },
+              { id: "release-ops", label: "#release-ops", description: "Operators only" },
+            ],
+          },
+        ],
+      },
+    },
+    t,
+    300,
+  );
+  return { id: "needs-you", title: "Needs you", events: r.events, running: true };
+}
+
+function history(): LabScenario {
+  const r = recorder("lab-history");
+  const a = "turn-h1";
+  r.push("user.message", { text: "Summarise yesterday's support tickets." }, a);
+  r.push("turn.started", {}, a, 400);
+  r.tool(a, "h1", "search_tickets", { since: "yesterday" }, "38 tickets", 4_000);
+  r.tool(a, "h2", "read_ticket", { id: "T-1182" }, "Customer cannot export invoices to PDF");
+  r.tool(a, "h3", "read_ticket", { id: "T-1190" }, "Login loop on Android 15");
+  const summary =
+    "38 tickets yesterday. The two themes:\n\n1. **PDF export** fails for invoices with attachments (11 tickets).\n2. **Android login loop** after the last release (7 tickets).\n\nEverything else was routine.";
+  r.push("agent.message.delta", { text: summary }, a, 2_000);
+  r.push("agent.message.completed", { text: summary }, a, 200);
+  r.push("turn.completed", { output: summary }, a, 200);
+  const b = "turn-h2";
+  r.push(
+    "user.message",
+    { text: "Open an issue for the Android one and assign it to mobile." },
+    b,
+    60_000,
+  );
+  r.push("turn.started", {}, b, 400);
+  r.tool(
+    b,
+    "h4",
+    "create_issue",
+    { title: "Android login loop after release", team: "mobile" },
+    "Error: tracker token expired",
+    2_000,
+  );
+  r.push(
+    "turn.failed",
+    { error: "The issue tracker connection needs to be reauthorized." },
+    b,
+    400,
+  );
+  const c = "turn-h3";
+  r.push("user.message", { text: "Reconnected. Try again." }, c, 30_000);
+  r.push("turn.started", {}, c, 400);
+  r.tool(
+    c,
+    "h5",
+    "create_issue",
+    { title: "Android login loop after release", team: "mobile" },
+    "Created MOB-412",
+    2_000,
+  );
+  const done = "Created **MOB-412** and assigned it to the mobile team.";
+  r.push("agent.message.delta", { text: done }, c, 1_000);
+  r.push("agent.message.completed", { text: done }, c, 200);
+  r.push("turn.completed", { output: done }, c, 200);
+  return { id: "history", title: "History", events: r.events, running: false };
+}
+
+function failure(): LabScenario {
+  const r = recorder("lab-failure");
+  const t = "turn-failure";
+  r.push("user.message", { text: "Deploy the latest build to staging." }, t);
+  r.push("turn.started", {}, t, 400);
+  r.tool(t, "f1", "exec_command", { cmd: "bun run build" }, "Build completed in 38s", 7_000);
+  r.tool(
+    t,
+    "f2",
+    "exec_command",
+    { cmd: "deploy --env staging" },
+    "error: staging cluster unreachable (connection refused after 3 attempts)",
+    4_000,
+  );
+  r.push(
+    "turn.failed",
+    { error: "The staging cluster refused the connection. Nothing was deployed." },
+    t,
+    400,
+  );
+  return { id: "failure", title: "Failure", events: r.events, running: false };
+}
+
+function longContent(): LabScenario {
+  const r = recorder("lab-long");
+  const t = "turn-long";
+  const question = [
+    "Here is the incident timeline from the on-call channel. Please turn it into a short postmortem with a summary, impact, root cause, a table of the timeline and the follow-ups.",
+    "",
+    "09:02 alerts fire for elevated 5xx on the checkout API; 09:05 on-call acknowledges; 09:11 rollback of release 412 starts; 09:19 error rate back to baseline; 09:40 root cause identified as a missing index after the orders migration; 10:15 index added and release 412 redeployed.",
+  ].join("\n");
+  r.push("user.message", { text: question }, t);
+  r.push("turn.started", {}, t, 400);
+  r.push(
+    "agent.reasoning.delta",
+    { text: "Structure it as a standard postmortem with a timeline table." },
+    t,
+    1_500,
+  );
+  const text = [
+    "## Postmortem: checkout 5xx after release 412",
+    "",
+    "**Summary.** For 17 minutes the checkout API returned elevated server errors after release 412. Rolling back restored service; the fix shipped the same morning.",
+    "",
+    "**Impact.** Roughly 6% of checkout attempts failed between 09:02 and 09:19. No orders were lost, but some customers had to retry.",
+    "",
+    "**Root cause.** The orders migration in release 412 dropped and recreated a table without its `customer_id` index, so a hot query fell back to a sequential scan and timed out under load.",
+    "",
+    "### Timeline",
+    "",
+    "| Time | Event |",
+    "| --- | --- |",
+    "| 09:02 | Alerts fire for elevated 5xx on checkout |",
+    "| 09:05 | On-call acknowledges |",
+    "| 09:11 | Rollback of release 412 starts |",
+    "| 09:19 | Error rate back to baseline |",
+    "| 09:40 | Missing index identified |",
+    "| 10:15 | Index added, release 412 redeployed |",
+    "",
+    "### Follow-ups",
+    "",
+    "1. Add a migration check that fails when an index disappears.",
+    "2. Alert on query latency, not only error rate.",
+    "3. Document the rollback runbook link in the alert itself.",
+    "",
+    "```sql",
+    "CREATE INDEX CONCURRENTLY orders_customer_id_idx ON orders (customer_id);",
+    "```",
+    "",
+    "> Rollback was the right first move: it bought time to find the cause without pressure.",
+  ].join("\n");
+  r.push("agent.message.delta", { text }, t, 3_000);
+  r.push("agent.message.completed", { text }, t, 300);
+  r.push("turn.completed", { output: text }, t, 200);
+  return { id: "long", title: "Long content", events: r.events, running: false };
+}
+
+export function labScenarios(): LabScenario[] {
+  return [answer(), working(), needsYou(), history(), failure(), longContent()];
+}

package/src/timeline/activity-rail.tsx

@@ -1,4 +1,5 @@
 import { KnowledgeReceiptRow } from "./knowledge-receipt";
+import { workerRowTitle } from "./platform-activity-presentation";
 import { AnimatePresence, motion, useReducedMotion } from "motion/react";
 import { GenieLoading } from "./genie-loading";
 import { StartupDispatchDetails } from "./startup-dispatch-details";
@@ -264,7 +265,9 @@ function ActivityNoteRow({ item }: { item: AgentMessageItem }) {
         {renderText ? (
           renderText(item.text, item)
         ) : (
-          <Markdown streaming={item.streaming}>{item.text}</Markdown>
+          <Markdown softLineBreaks streaming={item.streaming}>
+            {item.text}
+          </Markdown>
         )}
       </div>
     </div>
@@ -457,22 +460,7 @@ function WorkerRow({
   const running = item.status === "running";
   const failed = item.status === "failed";
   const cancelled = item.status === "cancelled";
-  const title =
-    item.action === "spawn"
-      ? running
-        ? "Spawning worker"
-        : failed
-          ? "Worker spawn failed"
-          : cancelled
-            ? "Worker interrupted"
-            : "Worker spawned"
-      : running
-        ? "Messaging worker"
-        : failed
-          ? "Worker message failed"
-          : cancelled
-            ? "Worker interrupted"
-            : "Worker messaged";
+  const title = workerRowTitle(item);
   if (compact) {
     return (
       <ActivityDisclosure

package/src/timeline/genie-copy.ts

@@ -0,0 +1,19 @@
+/** Decorative loading copy shared by every renderer of the preparing state. */
+export const GENIE_PREPARING_PHRASES: readonly string[] = [
+  "Polishing the lamp…",
+  "Consulting the carpet…",
+  "Untangling wishes…",
+  "Summoning a little cleverness…",
+  "Checking the fine print on infinity…",
+  "Warming up the abracadabra…",
+  "Rearranging the stars…",
+  "Negotiating with the lamp…",
+  "Dusting off a thousand years…",
+  "Wishful thinking…",
+  "Decanting a little magic…",
+  "Finding the good stardust…",
+  "Fluffing the magic carpet…",
+  "Putting a wish into motion…",
+  "A little hocus. A little pocus…",
+];
+export const GENIE_WAITING_PHRASES: readonly string[] = ["Waiting for a response…"];

package/src/timeline/genie-loading.tsx

@@ -1,5 +1,6 @@
 import { ThinkingOrb } from "thinking-orbs";
 import { useThemeType } from "../lib/use-theme-type";
+import { GENIE_PREPARING_PHRASES, GENIE_WAITING_PHRASES } from "./genie-copy";
 import { createContext, useContext, useEffect, useState, type ReactNode } from "react";
 
 export type GenieLoadingRenderProps = {
@@ -39,24 +40,18 @@ export type GenieLoadingOptions = {
 };
 export const GenieLoadingOptionsContext = createContext<GenieLoadingOptions | undefined>(undefined);
 
-const PHRASES = [
-  "Polishing the lamp…",
-  "Consulting the carpet…",
-  "Untangling wishes…",
-  "Summoning a little cleverness…",
-  "Checking the fine print on infinity…",
-  "Warming up the abracadabra…",
-  "Rearranging the stars…",
-  "Negotiating with the lamp…",
-  "Dusting off a thousand years…",
-  "Wishful thinking…",
-  "Decanting a little magic…",
-  "Finding the good stardust…",
-  "Fluffing the magic carpet…",
-  "Putting a wish into motion…",
-  "A little hocus. A little pocus…",
-];
-const WAITING_PHRASES = ["Waiting for a response…"];
+const PHRASES = GENIE_PREPARING_PHRASES;
+const WAITING_PHRASES = GENIE_WAITING_PHRASES;
+
+/**
+ * Neutral defaults for conversations embedded in another product
+ * (`SessionConversation`, `OpenGeniChat`), which should not carry Opengeni's
+ * own playful copy. The Opengeni app keeps the defaults above.
+ */
+export const EMBEDDED_GENIE_LOADING = {
+  phrases: ["Thinking…"],
+  messages: { showDetails: "Show details" },
+} as const satisfies GenieLoadingOptions;
 
 /** Decorative copy never substitutes for a failure or claims measurable progress. */
 export function GenieLoading({

package/src/timeline/index.ts

@@ -74,6 +74,7 @@ export type {
 export type {
   CreateToolRegistryOptions,
   RetainedArtifactLoader,
+  RetainedArtifactLoadOptions,
   RetainedScreenshotLoader,
   VideoArtifactPlaybackLoader,
   ToolRegistry,

package/src/timeline/notice-presentation.ts

@@ -0,0 +1,22 @@
+import type { NoticeItem } from "./types";
+
+/** An approval notice the person has since answered. */
+export function noticeIsResolvedApproval(item: Pick<NoticeItem, "text" | "resolvedAt">): boolean {
+  return Boolean(item.resolvedAt && item.text.startsWith("Approval needed"));
+}
+
+/** A resolved approval notice reads as history. */
+export function noticeDisplayText(item: Pick<NoticeItem, "text" | "resolvedAt">): string {
+  return noticeIsResolvedApproval(item) ? "You responded to this approval." : item.text;
+}
+
+/** Notice pill tone: failures stay red, an open wait keeps the waiting hue. */
+export function noticeTone(
+  item: Pick<NoticeItem, "tone" | "resolvedAt">,
+): "failed" | "waiting" | "neutral" {
+  return item.tone === "failed"
+    ? "failed"
+    : item.tone === "waiting" && !item.resolvedAt
+      ? "waiting"
+      : "neutral";
+}

package/src/timeline/patch-apply-command.tsx

@@ -0,0 +1,135 @@
+import type { RetainedArtifactReference } from "@opengeni/sdk";
+import { CheckIcon, TerminalIcon } from "lucide-react";
+import { useState } from "react";
+import { copyPendingTextToClipboard } from "../lib/clipboard";
+import type { RetainedArtifactLoader } from "./registry";
+
+export { isPatchFilename } from "./presented-image";
+
+/** POSIX single-quote one argument so the URL reaches curl unchanged. */
+function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+
+/** One command that downloads this patch and applies it in the current folder. */
+export function patchApplyCommand(url: string): string {
+  return `curl -fsSL ${shellQuote(url)} | git apply`;
+}
+
+/** "5 minutes" from the signed URL's expiry; the default download URL lifetime otherwise. */
+export function applyCommandLifetime(expiresAt: string | undefined, now = Date.now()): string {
+  const expires = expiresAt ? Date.parse(expiresAt) : Number.NaN;
+  const minutes = Number.isFinite(expires) ? Math.round((expires - now) / 60_000) : 5;
+  if (minutes <= 1) return "1 minute";
+  return `${minutes} minutes`;
+}
+
+type ApplyState =
+  | { kind: "idle" }
+  | { kind: "loading" }
+  | { kind: "copied"; lifetime: string }
+  | { kind: "manual"; command: string; lifetime: string }
+  | { kind: "unavailable" }
+  | { kind: "error" };
+
+const BUTTON_CLASS =
+  "inline-flex items-center gap-1.5 rounded-og-sm border border-og-border px-2.5 py-1.5 text-og-sm font-medium text-og-fg transition-colors hover:border-og-border-strong hover:bg-og-surface-2 disabled:cursor-wait disabled:opacity-60";
+
+/**
+ * "Copy command to apply these changes": mints the existing short-lived,
+ * authenticated download URL for this published patch (the same authority as
+ * Download) and copies `curl -fsSL '<url>' | git apply`. The URL is minted on
+ * click, so the copied command works for the URL's lifetime only.
+ */
+export function PatchApplyCommand({
+  artifact,
+  filename,
+  load,
+}: {
+  artifact: RetainedArtifactReference;
+  filename: string;
+  load: RetainedArtifactLoader | undefined;
+}) {
+  const [state, setState] = useState<ApplyState>({ kind: "idle" });
+
+  const copy = async () => {
+    if (!load) {
+      setState({ kind: "unavailable" });
+      return;
+    }
+    setState({ kind: "loading" });
+    let lifetime = "5 minutes";
+    // Start the URL request inside the click so the clipboard write may wait for it.
+    const command = load(artifact, new AbortController().signal, { prefer: "url" }).then(
+      (source) => {
+        if (!source || source instanceof Uint8Array) throw new UnavailableError();
+        lifetime = applyCommandLifetime(source.expiresAt);
+        return patchApplyCommand(source.url);
+      },
+    );
+    const copied = copyPendingTextToClipboard(command);
+    try {
+      const text = await command;
+      if (await copied) setState({ kind: "copied", lifetime });
+      else setState({ kind: "manual", command: text, lifetime });
+    } catch (failure) {
+      setState({ kind: failure instanceof UnavailableError ? "unavailable" : "error" });
+    }
+  };
+
+  const label =
+    state.kind === "loading"
+      ? "Preparing…"
+      : state.kind === "copied"
+        ? "Copied"
+        : state.kind === "error"
+          ? "Try again"
+          : "Copy command to apply these changes";
+
+  return (
+    <div className="flex min-w-0 flex-col gap-1.5">
+      <div>
+        <button
+          type="button"
+          onClick={() => void copy()}
+          disabled={state.kind === "loading"}
+          className={BUTTON_CLASS}
+        >
+          {state.kind === "copied" ? (
+            <CheckIcon className="size-3.5" aria-hidden />
+          ) : (
+            <TerminalIcon className="size-3.5" aria-hidden />
+          )}
+          {label}
+        </button>
+      </div>
+      <p className="m-0 text-og-xs leading-relaxed text-og-fg-muted" role="status">
+        {state.kind === "copied"
+          ? `Copied. Paste it in a terminal in your project folder and press Enter. The link in it expires in ${state.lifetime}.`
+          : state.kind === "manual"
+            ? `Copy this command, then run it in your project folder. The link in it expires in ${state.lifetime}.`
+            : state.kind === "unavailable"
+              ? `Download ${filename}, then run git apply ${filename} in your project folder.`
+              : state.kind === "error"
+                ? "Couldn't prepare the command. Try again, or download the file and run git apply."
+                : "Runs git apply in your project folder. Works on macOS, Linux and Git Bash."}
+      </p>
+      {state.kind === "manual" ? (
+        <input
+          readOnly
+          value={state.command}
+          aria-label="Command to apply these changes"
+          onFocus={(event) => event.currentTarget.select()}
+          className="w-full min-w-0 rounded-og-sm border border-og-border bg-og-surface-2 px-2 py-1.5 font-mono text-og-xs text-og-fg"
+        />
+      ) : null}
+    </div>
+  );
+}
+
+class UnavailableError extends Error {
+  constructor() {
+    super("A download URL is unavailable here");
+    this.name = "UnavailableError";
+  }
+}