@stigmer/react 3.12.6 → 3.12.8

package/src/session/facets/primitives.tsx

@@ -0,0 +1,169 @@
+"use client";
+
+// Shared visual vocabulary for the session-panel facets (Config / Changes /
+// Artifacts / Usage): one dense, VS Code-style row-and-section language so the
+// facets read as one surface instead of three eras of styling. The Artifacts
+// facet's `ArtifactRowView` set the idiom — compact rows, quiet metadata,
+// hover/focus-revealed actions — and these primitives carry it to the
+// non-file-list facets. All visual properties flow through `--stgm-*`
+// tokens (DD-005).
+
+import { cn } from "@stigmer/theme";
+
+/**
+ * A titled facet section: uppercase micro-heading over flush content.
+ * `count` renders the "(N)" suffix the retired inspector used; `annotation`
+ * renders a normal-case, muted trailing note (e.g. "next message only").
+ */
+export function FacetSection({
+  heading,
+  count,
+  annotation,
+  children,
+}: {
+  readonly heading: string;
+  readonly count?: number;
+  readonly annotation?: string;
+  readonly children: React.ReactNode;
+}) {
+  return (
+    <section className="stg:flex stg:flex-col stg:gap-1">
+      <h3 className="stg:px-2 stg:text-[0.65rem] stg:font-semibold stg:uppercase stg:tracking-wider stg:text-muted-foreground">
+        {heading}
+        {count != null && count > 0 && (
+          <span className="stg:ml-1 stg:text-muted-foreground-faint">({count})</span>
+        )}
+        {annotation && (
+          <span className="stg:ml-1 stg:font-normal stg:normal-case stg:tracking-normal stg:text-muted-foreground-faint">
+            ({annotation})
+          </span>
+        )}
+      </h3>
+      {children}
+    </section>
+  );
+}
+
+/**
+ * One dense, non-interactive facet row: leading content, optional
+ * right-aligned metadata, and hover/focus-revealed trailing actions
+ * (the `group` the actions' reveal keys on). Interactive rows (whole-row
+ * buttons) build on {@link FACET_ROW_BUTTON} instead.
+ */
+export function FacetRow({
+  children,
+  meta,
+  actions,
+  className,
+}: {
+  readonly children: React.ReactNode;
+  /** Right-aligned quiet metadata (counts, sizes, values). */
+  readonly meta?: React.ReactNode;
+  /** Hover/focus-revealed trailing controls — siblings, never nested. */
+  readonly actions?: React.ReactNode;
+  readonly className?: string;
+}) {
+  return (
+    <div
+      className={cn(
+        "stg:group stg:flex stg:items-center stg:gap-2 stg:px-2 stg:py-1 stg:text-xs",
+        className,
+      )}
+    >
+      <span className="stg:flex stg:min-w-0 stg:flex-1 stg:items-center stg:gap-2 stg:text-foreground">
+        {children}
+      </span>
+      {meta && (
+        <span className="stg:shrink-0 stg:text-[0.65rem] stg:text-muted-foreground">
+          {meta}
+        </span>
+      )}
+      {actions}
+    </div>
+  );
+}
+
+/**
+ * Class string for a whole-row interactive facet action (the
+ * `ArtifactRowView` open-button idiom): dense row metrics plus hover and
+ * focus-visible treatments. A string constant (not a component) so callers
+ * keep their own element type and extra classes.
+ */
+export const FACET_ROW_BUTTON = cn(
+  "stg:flex stg:w-full stg:min-w-0 stg:items-center stg:gap-2 stg:px-2 stg:py-1 stg:text-left stg:text-xs stg:text-muted-foreground stg:transition-colors",
+  "stg:hover:bg-muted stg:hover:text-foreground",
+  "stg:focus-visible:outline-none stg:focus-visible:ring-2 stg:focus-visible:ring-inset stg:focus-visible:ring-ring",
+  "stg:disabled:pointer-events-none stg:disabled:opacity-50",
+);
+
+/**
+ * Hover/focus-revealed remove control for a {@link FacetRow} — the
+ * `ArtifactRowView` download-button reveal pattern applied to removal.
+ * Always reachable by keyboard (focus reveals it without hover).
+ */
+export function FacetRemoveButton({
+  onClick,
+  label,
+}: {
+  readonly onClick: () => void;
+  readonly label: string;
+}) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      aria-label={label}
+      className={cn(
+        "stg:flex stg:shrink-0 stg:items-center stg:text-muted-foreground stg:opacity-0 stg:transition-opacity",
+        "stg:group-hover:opacity-100 stg:focus-visible:opacity-100",
+        "stg:hover:text-destructive",
+        "stg:focus-visible:outline-none stg:focus-visible:ring-2 stg:focus-visible:ring-inset stg:focus-visible:ring-ring",
+      )}
+    >
+      <FacetXIcon />
+    </button>
+  );
+}
+
+/** Muted empty-state line for a facet section with nothing to list. */
+export function FacetEmptyHint({ children }: { readonly children: React.ReactNode }) {
+  return (
+    <p className="stg:px-2 stg:text-xs stg:text-muted-foreground-faint">{children}</p>
+  );
+}
+
+/**
+ * A key→value config row ("Harness  Native"): muted label left, value
+ * right — the dense inverse of a definition list, sized like every other
+ * facet row. `children` is the value; pass a control (e.g. a Switch) for
+ * interactive config rows.
+ */
+export function FacetKeyValueRow({
+  label,
+  labelId,
+  children,
+}: {
+  readonly label: string;
+  /** Optional id for the label span — point a control's `aria-labelledby` here. */
+  readonly labelId?: string;
+  readonly children: React.ReactNode;
+}) {
+  return (
+    <div className="stg:flex stg:items-center stg:justify-between stg:gap-2 stg:px-2 stg:py-1 stg:text-xs">
+      <span id={labelId} className="stg:shrink-0 stg:text-muted-foreground">
+        {label}
+      </span>
+      <span className="stg:flex stg:min-w-0 stg:items-center stg:gap-1.5 stg:truncate stg:text-foreground">
+        {children}
+      </span>
+    </div>
+  );
+}
+
+function FacetXIcon() {
+  return (
+    <svg width="14" height="14" viewBox="0 0 14 14" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <path d="M4 4L10 10M10 4L4 10" />
+    </svg>
+  );
+}

package/src/session/index.ts

@@ -39,6 +39,15 @@ export type {
   UseSessionConversationReturn,
 } from "./useSessionConversation.js";
 
+export { useExportTranscript } from "./useExportTranscript.js";
+export type {
+  UseExportTranscriptOptions,
+  UseExportTranscriptReturn,
+} from "./useExportTranscript.js";
+
+export { TranscriptExportMenu } from "./TranscriptExportMenu.js";
+export type { TranscriptExportMenuProps } from "./TranscriptExportMenu.js";
+
 export { useSessionArtifacts, artifactKey } from "./useSessionArtifacts.js";
 export type {
   SessionArtifactEntry,
@@ -161,6 +170,7 @@ export { SetupTab } from "./facets/index.js";
 export type {
   SetupTabProps,
   SetupTabMutationCallbacks,
+  SetupTabAutoApprove,
 } from "./facets/index.js";
 
 // Session utilities (re-exported from @stigmer/sdk)

package/src/session/useExportTranscript.ts

@@ -0,0 +1,171 @@
+"use client";
+
+import { useCallback, useMemo, useState } from "react";
+import {
+  fetchSessionTranscript,
+  resolvedSubject,
+  transcriptToJson,
+  transcriptToMarkdown,
+  type SessionTranscript,
+} from "@stigmer/sdk";
+import { toast } from "../feedback/toast.js";
+import { useStigmer } from "../hooks.js";
+import { downloadTextFile } from "../internal/download.js";
+import { generateSlug } from "../internal/slug.js";
+import { toError } from "../internal/toError.js";
+
+/** Options for {@link useExportTranscript}. */
+export interface UseExportTranscriptOptions {
+  /**
+   * Keep turns replaced by edit-and-resubmit in the export, marked as
+   * superseded. Defaults to `false` — the conversation as the viewer
+   * shows it.
+   */
+  readonly includeSuperseded?: boolean;
+}
+
+/** Return value of {@link useExportTranscript}. */
+export interface UseExportTranscriptReturn {
+  /** Copy the whole conversation as Markdown to the clipboard. */
+  readonly copyMarkdown: () => Promise<void>;
+  /** Download the whole conversation as a Markdown file. */
+  readonly downloadMarkdown: () => Promise<void>;
+  /** Download the whole conversation as a structured JSON file. */
+  readonly downloadJson: () => Promise<void>;
+  /** `true` while a transcript fetch (and offload resolution) is in flight. */
+  readonly isExporting: boolean;
+  /** The last export failure, or `null`. Cleared when a new export starts. */
+  readonly error: Error | null;
+}
+
+/**
+ * Behavior hook that exports a session's whole conversation — thinking,
+ * tool calls with offloaded outputs resolved, sub-agent turns, timestamps —
+ * as Markdown (copy or download) or structured JSON (stigmer/stigmer#814).
+ *
+ * Lazy: nothing is fetched until an action is invoked. Each action fetches
+ * the canonical transcript via `fetchSessionTranscript` (the SDK's one
+ * authoritative assembly), so every export surface produces identical
+ * content. Feedback follows the `useExportResource` convention: toasts for
+ * success/failure, plus a typed `error` for hosts that render their own.
+ *
+ * @example
+ * ```tsx
+ * const exporter = useExportTranscript(sessionId);
+ *
+ * <ActionMenu.Item onSelect={exporter.copyMarkdown}>Copy transcript</ActionMenu.Item>
+ * <ActionMenu.Item onSelect={exporter.downloadMarkdown}>Download .md</ActionMenu.Item>
+ * <ActionMenu.Item onSelect={exporter.downloadJson}>Download .json</ActionMenu.Item>
+ * ```
+ */
+export function useExportTranscript(
+  sessionId: string | null,
+  options?: UseExportTranscriptOptions,
+): UseExportTranscriptReturn {
+  const stigmer = useStigmer();
+  const includeSuperseded = options?.includeSuperseded === true;
+  const [isExporting, setIsExporting] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const fetchTranscript = useCallback((): Promise<SessionTranscript> => {
+    if (!sessionId) {
+      return Promise.reject(
+        new Error(
+          "Cannot export a transcript without a session id. Pass the session's " +
+            "id to useExportTranscript once the session exists.",
+        ),
+      );
+    }
+    return fetchSessionTranscript(stigmer, sessionId, { includeSuperseded });
+  }, [stigmer, sessionId, includeSuperseded]);
+
+  const copyMarkdown = useCallback(async (): Promise<void> => {
+    setError(null);
+    setIsExporting(true);
+    const markdown = fetchTranscript().then(
+      (t) => transcriptToMarkdown(t, { generatedAt: new Date().toISOString() }),
+    );
+    try {
+      // The transcript is fetched before it can be copied, and WebKit (the
+      // desktop app's webview) only honors clipboard writes inside the user
+      // gesture's task — a plain writeText after the await is rejected
+      // there. ClipboardItem accepts a promise, letting the write start
+      // synchronously in the gesture while the content resolves.
+      if (typeof ClipboardItem !== "undefined" && navigator.clipboard?.write) {
+        await navigator.clipboard.write([
+          new ClipboardItem({
+            "text/plain": markdown.then(
+              (text) => new Blob([text], { type: "text/plain" }),
+            ),
+          }),
+        ]);
+      } else {
+        await navigator.clipboard.writeText(await markdown);
+      }
+      toast.success("Transcript copied to clipboard");
+    } catch (e) {
+      const err = toError(e);
+      setError(err);
+      toast.error(`Couldn't copy the transcript: ${err.message}`);
+    } finally {
+      setIsExporting(false);
+    }
+  }, [fetchTranscript]);
+
+  const download = useCallback(
+    async (serialize: (t: SessionTranscript) => { content: string; extension: string; mimeType: string }): Promise<void> => {
+      setError(null);
+      setIsExporting(true);
+      try {
+        const transcript = await fetchTranscript();
+        const { content, extension, mimeType } = serialize(transcript);
+        downloadTextFile(
+          content,
+          `${transcriptFilename(transcript)}.${extension}`,
+          mimeType,
+        );
+      } catch (e) {
+        const err = toError(e);
+        setError(err);
+        toast.error(`Couldn't export the transcript: ${err.message}`);
+      } finally {
+        setIsExporting(false);
+      }
+    },
+    [fetchTranscript],
+  );
+
+  const downloadMarkdown = useCallback(
+    () =>
+      download((t) => ({
+        content: transcriptToMarkdown(t, {
+          generatedAt: new Date().toISOString(),
+        }),
+        extension: "md",
+        mimeType: "text/markdown",
+      })),
+    [download],
+  );
+
+  const downloadJson = useCallback(
+    () =>
+      download((t) => ({
+        content: JSON.stringify(transcriptToJson(t), null, 2),
+        extension: "json",
+        mimeType: "application/json",
+      })),
+    [download],
+  );
+
+  return useMemo(
+    () => ({ copyMarkdown, downloadMarkdown, downloadJson, isExporting, error }),
+    [copyMarkdown, downloadMarkdown, downloadJson, isExporting, error],
+  );
+}
+
+/** `<subject-slug>-transcript`, falling back to the session id. */
+function transcriptFilename(transcript: SessionTranscript): string {
+  const subject = resolvedSubject(transcript.session.spec?.subject);
+  const slug = subject ? generateSlug(subject).slice(0, 60) : "";
+  return `${slug || transcript.session.metadata?.id || "session"}-transcript`;
+}

package/src/session/useNewSessionFlow.ts

@@ -116,6 +116,9 @@ export interface UseNewSessionFlowOptions {
    * - model: stored per-harness choice > the account's model for the
    *   active harness (validated against the registry; a stale model
    *   silently falls through) > the harness default.
+   * - autoApprove: explicit in-session flip > the account's
+   *   `default_auto_approve` > the host's `approvalDefaults` (derived,
+   *   so a late-arriving value applies without a touched-ref effect).
    *
    * Seeded values are never persisted to localStorage — the account
    * preference keeps applying until the user decides. Ignored for the
@@ -218,6 +221,20 @@ export interface UseNewSessionFlowReturn {
   /** Session variables (per-execution secrets) manager. */
   readonly sessionVariables: UseSessionVariablesReturn;
 
+  /**
+   * Pre-arm "auto-approve tool calls" for the session this surface will
+   * create (stigmer/stigmer#816, the walk-away scenario). Seeded from the
+   * account's `default_auto_approve` preference and the host's
+   * `StigmerProvider` `approvalDefaults` (#302) — guests inherit neither;
+   * the user's explicit flip (the Config facet switch) wins from then on.
+   * Carried into the bootstrap create as `spec.auto_approve_all` — the
+   * whole-run server-side bypass — so the first run stays covered even if
+   * the user closes the tab.
+   */
+  readonly autoApproveAll: boolean;
+  /** Set the user's explicit auto-approve choice for the created session. */
+  readonly setAutoApproveAll: (value: boolean) => void;
+
   /** `true` while the create session + execution flow is in flight. */
   readonly isSubmitting: boolean;
   /** Human-readable error from the last failed submission, or `null`. */
@@ -311,13 +328,28 @@ export function useNewSessionFlow(
   const contextTarget = useExecutionTarget();
   const executionTarget = options.executionTarget ?? contextTarget;
   const adapter = useRunnerAdapter();
-  // Host approval default (#302): pre-arm auto_approve_all on the bootstrap
-  // create when the provider says so. Guests never inherit it — a share-link
-  // visitor is not the operator the host's trust judgment covers (the
-  // GUEST_HARNESS fixed-platform-policy reasoning).
+  // Auto-approve for the session about to be created (#816): derived like
+  // useSessionPageFlow's — the user's explicit flip wins, otherwise the
+  // truth is computed from its seeds:
+  //
+  //   effective = userChoice ?? (accountSeed || hostSeed)
+  //
+  // Derived rather than useState-initialized because the account preference
+  // (default_auto_approve) resolves async with whoAmI — a mount-time
+  // initializer would silently miss it (the harness seed's late-arrival
+  // problem, solved here by derivation instead of a touched-ref effect).
+  // Guests inherit neither seed — a share-link visitor is not the operator
+  // either trust judgment covers (the GUEST_HARNESS fixed-platform-policy
+  // reasoning). Carried into the bootstrap create as spec.auto_approve_all,
+  // the whole-run server-side bypass — the created run stays covered even
+  // if this tab dies before its first gate.
   const approvalDefaults = useApprovalDefaults();
+  const [autoApproveChoice, setAutoApproveAll] = useState<boolean | null>(null);
   const autoApproveAll =
-    (!isGuest && approvalDefaults?.autoApproveAll) || undefined;
+    autoApproveChoice ??
+    (!isGuest &&
+      ((accountDefaults?.autoApprove ?? false) ||
+        (approvalDefaults?.autoApproveAll ?? false)));
 
   const [harness, setHarnessRaw] = useState<HarnessOption>(() => {
     // Guests get the fixed platform policy (see GUEST_HARNESS) and never
@@ -496,7 +528,9 @@ export function useNewSessionFlow(
             ? (pinnedThinkingMode === "enabled" ? "enabled" : undefined)
             : context?.thinkingMode,
           workspaceFileRefs: context?.workspaceFileRefs,
-          autoApproveAll,
+          // Only an armed state travels; false stays off the wire (the
+          // serviceTier/thinkingMode only-explicit discipline).
+          autoApproveAll: autoApproveAll || undefined,
         };
 
         // Resolve which agent the bootstrapped session runs against: an
@@ -624,6 +658,8 @@ export function useNewSessionFlow(
     setSkillRefs,
     workspace,
     sessionVariables,
+    autoApproveAll,
+    setAutoApproveAll,
     isSubmitting,
     submitError,
     submit,

package/src/session/useSessionConversation.ts

@@ -10,6 +10,7 @@ import type { McpServerUsage as ProtoMcpServerUsage } from "@stigmer/protos/ai/s
 import type { WorkspaceEntry as ProtoWorkspaceEntry } from "@stigmer/protos/ai/stigmer/agentic/session/v1/workspace_pb";
 import type { ApiResourceReference as ProtoApiResourceReference } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
 import {
+  supersededExecutionIds,
   toSessionUpdateInput,
   type AttachmentInput,
   type EnvVarInput,
@@ -544,13 +545,11 @@ export function useSessionConversation(
     }
   }, [activeExecutionId, stream.phase, refetch]);
 
-  // Executions replaced via edit-and-resubmit. The successor carries
-  // `spec.supersedes_execution_id`; hiding the superseded turn makes the
-  // edited message read as a single corrected exchange (in-place replace).
-  // The link must also be read off the live stream copy — right after a
-  // resubmit, the successor streams before the list refetch delivers it.
-  // Display-only: the raw `executions` list (and therefore active-id
-  // resolution above) is never filtered.
+  // Executions replaced via edit-and-resubmit (the shared conversation rule —
+  // see supersededExecutionIds in @stigmer/sdk for the why). The extra id is
+  // the live stream copy's link: right after a resubmit, the successor streams
+  // before the list refetch delivers it. Display-only: the raw `executions`
+  // list (and therefore active-id resolution above) is never filtered.
   //
   // Dep is the scalar link, NOT stream.execution: the stream object changes
   // reference every frame, and rebuilding the Set per frame would hand
@@ -558,15 +557,10 @@ export function useSessionConversation(
   // memoization (DD-010).
   const streamSupersededId =
     stream.execution?.spec?.supersedesExecutionId || null;
-  const supersededIds = useMemo(() => {
-    const ids = new Set<string>();
-    for (const e of executions) {
-      const superseded = e.spec?.supersedesExecutionId;
-      if (superseded) ids.add(superseded);
-    }
-    if (streamSupersededId) ids.add(streamSupersededId);
-    return ids;
-  }, [executions, streamSupersededId]);
+  const supersededIds = useMemo(
+    () => supersededExecutionIds(executions, streamSupersededId),
+    [executions, streamSupersededId],
+  );
 
   const completedExecutions = useMemo(() => {
     return executions.filter((e) => {

package/src/session/useSessionExecutions.ts

@@ -3,9 +3,14 @@
 import { create } from "@bufbuild/protobuf";
 import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import { ListAgentExecutionsBySessionRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import { sortChronologically } from "@stigmer/sdk";
 import { useStigmer } from "../hooks.js";
 import { useFetch } from "../internal/useFetch.js";
 
+// The ordering rule lives in @stigmer/sdk with the other shared
+// conversation-assembly rules; re-exported here for existing consumers.
+export { sortChronologically };
+
 /** Options for {@link useSessionExecutions}. */
 export interface UseSessionExecutionsOptions {
   /**
@@ -71,32 +76,6 @@ export interface UseSessionExecutionsReturn {
  * const { executions } = useSessionExecutions(sessionId ?? null);
  * ```
  */
-/**
- * Returns the executions in chronological (oldest-first) order — the order
- * the conversation thread renders top-to-bottom.
- *
- * Defense-in-depth against an unordered list response: the executions ARE the
- * transcript, so a scrambled order drops the newest turns out of view (they no
- * longer sort to the bottom). The server orders this list, but the thread must
- * never depend on that alone. Resource ids are time-sortable ULIDs
- * (`aex_01k…`), so an ascending id sort is creation order without parsing
- * timestamps; entries missing an id sort last but keep a stable relative order.
- *
- * @internal Exported for testing — not part of the public API.
- */
-export function sortChronologically(
-  executions: readonly AgentExecution[],
-): AgentExecution[] {
-  return [...executions].sort((a, b) => {
-    const aId = a.metadata?.id ?? "";
-    const bId = b.metadata?.id ?? "";
-    if (aId === bId) return 0;
-    if (!aId) return 1;
-    if (!bId) return -1;
-    return aId < bId ? -1 : 1;
-  });
-}
-
 export function useSessionExecutions(
   sessionId: string | null,
   options?: UseSessionExecutionsOptions,