@stigmer/react 3.1.0 → 3.1.2

package/src/invitation/index.ts

@@ -1,16 +1,16 @@
-export { useOrgInvitations } from "./useOrgInvitations";
-export type { UseOrgInvitationsReturn } from "./useOrgInvitations";
-export { useCreateInvitation } from "./useCreateInvitation";
-export type { UseCreateInvitationReturn } from "./useCreateInvitation";
-export { useRevokeInvitation } from "./useRevokeInvitation";
-export type { UseRevokeInvitationReturn } from "./useRevokeInvitation";
-export { useInvitationPreview } from "./useInvitationPreview";
-export type { UseInvitationPreviewReturn } from "./useInvitationPreview";
-export { useRedeemInvitation } from "./useRedeemInvitation";
-export type { UseRedeemInvitationReturn } from "./useRedeemInvitation";
-export { InvitationCreatedAlert } from "./InvitationCreatedAlert";
-export type { InvitationCreatedAlertProps } from "./InvitationCreatedAlert";
-export { InvitationManager } from "./InvitationManager";
-export type { InvitationManagerProps } from "./InvitationManager";
-export { InvitationRedemption } from "./InvitationRedemption";
-export type { InvitationRedemptionProps } from "./InvitationRedemption";
+export { useOrgInvitations } from "./useOrgInvitations.js";
+export type { UseOrgInvitationsReturn } from "./useOrgInvitations.js";
+export { useCreateInvitation } from "./useCreateInvitation.js";
+export type { UseCreateInvitationReturn } from "./useCreateInvitation.js";
+export { useRevokeInvitation } from "./useRevokeInvitation.js";
+export type { UseRevokeInvitationReturn } from "./useRevokeInvitation.js";
+export { useInvitationPreview } from "./useInvitationPreview.js";
+export type { UseInvitationPreviewReturn } from "./useInvitationPreview.js";
+export { useRedeemInvitation } from "./useRedeemInvitation.js";
+export type { UseRedeemInvitationReturn } from "./useRedeemInvitation.js";
+export { InvitationCreatedAlert } from "./InvitationCreatedAlert.js";
+export type { InvitationCreatedAlertProps } from "./InvitationCreatedAlert.js";
+export { InvitationManager } from "./InvitationManager.js";
+export type { InvitationManagerProps } from "./InvitationManager.js";
+export { InvitationRedemption } from "./InvitationRedemption.js";
+export type { InvitationRedemptionProps } from "./InvitationRedemption.js";

package/src/invitation/useCreateInvitation.ts

@@ -3,8 +3,8 @@
 import { useCallback, useState } from "react";
 import type { InvitationInput } from "@stigmer/sdk";
 import type { Invitation } from "@stigmer/protos/ai/stigmer/iam/invitation/v1/api_pb";
-import { useStigmer } from "../hooks";
-import { toError } from "../internal/toError";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
 
 /** Return value of {@link useCreateInvitation}. */
 export interface UseCreateInvitationReturn {

package/src/invitation/useInvitationPreview.ts

@@ -3,8 +3,8 @@
 import { create } from "@bufbuild/protobuf";
 import type { InvitationPreview } from "@stigmer/protos/ai/stigmer/iam/invitation/v1/io_pb";
 import { InvitationTokenInputSchema } from "@stigmer/protos/ai/stigmer/iam/invitation/v1/io_pb";
-import { useStigmer } from "../hooks";
-import { useFetch } from "../internal/useFetch";
+import { useStigmer } from "../hooks.js";
+import { useFetch } from "../internal/useFetch.js";
 
 /** Return value of {@link useInvitationPreview}. */
 export interface UseInvitationPreviewReturn {

package/src/invitation/useOrgInvitations.ts

@@ -3,8 +3,8 @@
 import { create } from "@bufbuild/protobuf";
 import type { Invitation } from "@stigmer/protos/ai/stigmer/iam/invitation/v1/api_pb";
 import { ListInvitationsByOrgInputSchema } from "@stigmer/protos/ai/stigmer/iam/invitation/v1/io_pb";
-import { useStigmer } from "../hooks";
-import { useFetch } from "../internal/useFetch";
+import { useStigmer } from "../hooks.js";
+import { useFetch } from "../internal/useFetch.js";
 
 /** Return value of {@link useOrgInvitations}. */
 export interface UseOrgInvitationsReturn {

package/src/invitation/useRedeemInvitation.ts

@@ -4,8 +4,8 @@ import { useCallback, useState } from "react";
 import { create } from "@bufbuild/protobuf";
 import type { Invitation } from "@stigmer/protos/ai/stigmer/iam/invitation/v1/api_pb";
 import { RedeemInvitationInputSchema } from "@stigmer/protos/ai/stigmer/iam/invitation/v1/io_pb";
-import { useStigmer } from "../hooks";
-import { toError } from "../internal/toError";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
 
 /** Return value of {@link useRedeemInvitation}. */
 export interface UseRedeemInvitationReturn {

package/src/invitation/useRevokeInvitation.ts

@@ -2,8 +2,8 @@
 
 import { useCallback, useState } from "react";
 import type { Invitation } from "@stigmer/protos/ai/stigmer/iam/invitation/v1/api_pb";
-import { useStigmer } from "../hooks";
-import { toError } from "../internal/toError";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
 
 /** Return value of {@link useRevokeInvitation}. */
 export interface UseRevokeInvitationReturn {

package/src/library/ImportResourceDialog.tsx

@@ -2,9 +2,9 @@
 
 import { useCallback, useEffect, useRef } from "react";
 import { cn } from "@stigmer/theme";
-import { toast } from "../feedback/toast";
-import { useImportResource } from "./useImportResource";
-import type { ApplyResourceResult } from "./useApplyResource";
+import { toast } from "../feedback/toast.js";
+import { useImportResource } from "./useImportResource.js";
+import type { ApplyResourceResult } from "./useApplyResource.js";
 
 // ---------------------------------------------------------------------------
 // Props

package/src/library/InstanceVisibilitySelector.tsx

@@ -4,8 +4,8 @@ import type { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/a
 import {
   VisibilitySelector,
   type VisibilitySelectorMode,
-} from "./VisibilitySelector";
-import { INSTANCE_VISIBILITY_LEVELS } from "./visibilityLevels";
+} from "./VisibilitySelector.js";
+import { INSTANCE_VISIBILITY_LEVELS } from "./visibilityLevels.js";
 
 /** Props for {@link InstanceVisibilitySelector}. */
 export interface InstanceVisibilitySelectorProps {

package/src/library/ResourceVisibilityControl.tsx

@@ -2,18 +2,18 @@
 
 import { useCallback } from "react";
 import type { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
-import { useDeploymentMode } from "../deployment-mode";
-import { PermissionGate } from "../iam-policy/PermissionGate";
-import { useSsoProvider } from "../identity-provider/useSsoProvider";
-import { VisibilityBadge, VisibilitySelector } from "./VisibilitySelector";
+import { useDeploymentMode } from "../deployment-mode.js";
+import { PermissionGate } from "../iam-policy/PermissionGate.js";
+import { useSsoProvider } from "../identity-provider/useSsoProvider.js";
+import { VisibilityBadge, VisibilitySelector } from "./VisibilitySelector.js";
 import {
   blueprintVisibilityLevels,
   INSTANCE_VISIBILITY_LEVELS,
-} from "./visibilityLevels";
+} from "./visibilityLevels.js";
 import {
   useUpdateVisibility,
   type VisibilityResourceKind,
-} from "./useUpdateVisibility";
+} from "./useUpdateVisibility.js";
 
 /**
  * Maps a {@link VisibilityResourceKind} (which mirrors the SDK method namespace,

package/src/library/ScopeToggle.tsx

@@ -2,7 +2,7 @@
 
 import { useCallback, useRef } from "react";
 import { cn } from "@stigmer/theme";
-import type { ResourceListScope } from "../search";
+import type { ResourceListScope } from "../search/index.js";
 
 /** Props for {@link ScopeToggle}. */
 export interface ScopeToggleProps {

package/src/library/VisibilityOptionRow.tsx

@@ -2,7 +2,7 @@
 
 import { forwardRef } from "react";
 import { cn } from "@stigmer/theme";
-import type { VisibilityLevelOption } from "./visibilityLevels";
+import type { VisibilityLevelOption } from "./visibilityLevels.js";
 
 /** Color treatment key shared by every visibility surface. */
 export type VisibilityTone = VisibilityLevelOption["tone"];

package/src/library/VisibilitySelector.tsx

@@ -4,19 +4,19 @@ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { Popover } from "@base-ui/react/popover";
 import { cn } from "@stigmer/theme";
 import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
-import { useStigmerPortalContainer } from "../portal-container";
-import { ConfirmDialog } from "../resource-detail/ConfirmDialog";
-import { useConfirmAction } from "../resource-detail/useConfirmAction";
+import { useStigmerPortalContainer } from "../portal-container.js";
+import { ConfirmDialog } from "../resource-detail/ConfirmDialog.js";
+import { useConfirmAction } from "../resource-detail/useConfirmAction.js";
 import {
   PROMPT_STYLES,
   VISIBILITY_CHIP_CLASS,
   VisibilityIcon,
   VisibilityOptionRow,
-} from "./VisibilityOptionRow";
+} from "./VisibilityOptionRow.js";
 import {
   visibilityOption,
   type VisibilityLevelOption,
-} from "./visibilityLevels";
+} from "./visibilityLevels.js";
 
 /** How the selector presents itself and how it confirms escalations. */
 export type VisibilitySelectorMode = "manage" | "create";

package/src/library/__tests__/detect-plan-artifact.test.ts

@@ -6,9 +6,11 @@ import {
 } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import { ExecutionArtifactSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/artifact_pb";
 import { ExecutionArtifactKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
 import {
   isPlanArtifact,
   findPlanArtifact,
+  findLatestSessionPlan,
   PLAN_ARTIFACT_NAME,
 } from "../detect-plan-artifact";
 
@@ -26,6 +28,13 @@ function executionWith(...artifacts: ReturnType<typeof artifact>[]) {
   });
 }
 
+function executionWithId(id: string, ...artifacts: ReturnType<typeof artifact>[]) {
+  return create(AgentExecutionSchema, {
+    metadata: create(ApiResourceMetadataSchema, { id }),
+    status: create(AgentExecutionStatusSchema, { artifacts }),
+  });
+}
+
 describe("isPlanArtifact", () => {
   it("is true for a FILE artifact named plan.md", () => {
     expect(isPlanArtifact(artifact({ name: PLAN_ARTIFACT_NAME }))).toBe(true);
@@ -73,3 +82,42 @@ describe("findPlanArtifact", () => {
     expect(findPlanArtifact(executionWith(artifact({ name: "report.md" })))).toBeUndefined();
   });
 });
+
+describe("findLatestSessionPlan", () => {
+  it("returns undefined when no execution published a plan", () => {
+    const execs = [
+      executionWithId("e1", artifact({ name: "report.md" })),
+      executionWithId("e2"),
+    ];
+    expect(findLatestSessionPlan(execs)).toBeUndefined();
+    expect(findLatestSessionPlan([])).toBeUndefined();
+  });
+
+  it("returns the newest plan across executions, with its execution id", () => {
+    const execs = [
+      executionWithId("e1", artifact({ name: PLAN_ARTIFACT_NAME, storageKey: "artifacts/e1/plan.md" })),
+      executionWithId("e2", artifact({ name: "notes.txt" })),
+      executionWithId("e3", artifact({ name: PLAN_ARTIFACT_NAME, storageKey: "artifacts/e3/plan.md" })),
+    ];
+
+    const plan = findLatestSessionPlan(execs);
+    expect(plan?.executionId).toBe("e3");
+    expect(plan?.artifact.storageKey).toBe("artifacts/e3/plan.md");
+  });
+
+  it("skips a newer plan-less execution and returns the older plan", () => {
+    const execs = [
+      executionWithId("e1", artifact({ name: PLAN_ARTIFACT_NAME })),
+      executionWithId("e2", artifact({ name: "data.json" })),
+    ];
+    expect(findLatestSessionPlan(execs)?.executionId).toBe("e1");
+  });
+
+  it("skips an execution whose plan artifact lacks a usable execution id", () => {
+    const execs = [
+      executionWithId("e1", artifact({ name: PLAN_ARTIFACT_NAME })),
+      executionWith(artifact({ name: PLAN_ARTIFACT_NAME })),
+    ];
+    expect(findLatestSessionPlan(execs)?.executionId).toBe("e1");
+  });
+});

package/src/library/__tests__/detect-streaming-plan.test.ts

@@ -0,0 +1,234 @@
+import { describe, it, expect } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import {
+  AgentExecutionSchema,
+  AgentExecutionStatusSchema,
+  type AgentExecution,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import {
+  AgentExecutionSpecSchema,
+  ExecutionConfigSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
+import { AgentMessageSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import {
+  ExecutionPhase,
+  InteractionMode,
+  MessageType,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { findStreamingPlan } from "../detect-streaming-plan";
+
+function makeMessage(type: MessageType, content: string) {
+  const msg = create(AgentMessageSchema);
+  msg.type = type;
+  msg.content = content;
+  return msg;
+}
+
+function makeExecution(opts: {
+  phase?: ExecutionPhase;
+  interactionMode?: InteractionMode;
+  messages?: ReturnType<typeof makeMessage>[];
+}): AgentExecution {
+  const exec = create(AgentExecutionSchema);
+
+  const spec = create(AgentExecutionSpecSchema);
+  if (opts.interactionMode !== undefined) {
+    const config = create(ExecutionConfigSchema);
+    config.interactionMode = opts.interactionMode;
+    spec.executionConfig = config;
+  }
+  exec.spec = spec;
+
+  const status = create(AgentExecutionStatusSchema);
+  status.phase = opts.phase ?? ExecutionPhase.EXECUTION_IN_PROGRESS;
+  if (opts.messages) {
+    status.messages = opts.messages;
+  }
+  exec.status = status;
+
+  return exec;
+}
+
+/** A live Plan-mode execution with the given messages — the common case. */
+function livePlanExecution(...messages: ReturnType<typeof makeMessage>[]) {
+  return makeExecution({
+    phase: ExecutionPhase.EXECUTION_IN_PROGRESS,
+    interactionMode: InteractionMode.PLAN,
+    messages,
+  });
+}
+
+describe("findStreamingPlan — mode and phase gating", () => {
+  const planMessage = makeMessage(MessageType.MESSAGE_AI, "# The Plan\n\nBody");
+
+  it("detects a plan on a live Plan-mode execution", () => {
+    const plan = findStreamingPlan(livePlanExecution(planMessage));
+    expect(plan).toBeDefined();
+    expect(plan!.messageIndex).toBe(0);
+    expect(plan!.displayText).toBe("# The Plan\n\nBody");
+  });
+
+  it("returns undefined for null/undefined executions", () => {
+    expect(findStreamingPlan(null)).toBeUndefined();
+    expect(findStreamingPlan(undefined)).toBeUndefined();
+  });
+
+  it("returns undefined for an Agent-mode execution, even with a plan-shaped message", () => {
+    const exec = makeExecution({
+      phase: ExecutionPhase.EXECUTION_IN_PROGRESS,
+      interactionMode: InteractionMode.AGENT,
+      messages: [planMessage],
+    });
+    expect(findStreamingPlan(exec)).toBeUndefined();
+  });
+
+  it("returns undefined when no interaction mode is set", () => {
+    const exec = makeExecution({
+      phase: ExecutionPhase.EXECUTION_IN_PROGRESS,
+      messages: [planMessage],
+    });
+    expect(findStreamingPlan(exec)).toBeUndefined();
+  });
+
+  it.each([
+    ExecutionPhase.EXECUTION_COMPLETED,
+    ExecutionPhase.EXECUTION_FAILED,
+    ExecutionPhase.EXECUTION_CANCELLED,
+    ExecutionPhase.EXECUTION_TERMINATED,
+  ])("returns undefined for terminal phase %s", (phase) => {
+    const exec = makeExecution({
+      phase,
+      interactionMode: InteractionMode.PLAN,
+      messages: [planMessage],
+    });
+    expect(findStreamingPlan(exec)).toBeUndefined();
+  });
+
+  it("detects during a non-terminal wait (approval gate mid-turn)", () => {
+    const exec = makeExecution({
+      phase: ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL,
+      interactionMode: InteractionMode.PLAN,
+      messages: [planMessage],
+    });
+    expect(findStreamingPlan(exec)).toBeDefined();
+  });
+});
+
+describe("findStreamingPlan — candidate selection", () => {
+  it("considers only the LAST content-bearing AI message", () => {
+    // The earlier plan-shaped message is settled narration once a later AI
+    // message exists — falling back to it would promote the wrong text.
+    const exec = livePlanExecution(
+      makeMessage(MessageType.MESSAGE_AI, "# Early heading in narration"),
+      makeMessage(MessageType.MESSAGE_AI, "Now let me check the tests."),
+    );
+    expect(findStreamingPlan(exec)).toBeUndefined();
+  });
+
+  it("skips trailing empty AI messages (extractFinalPlanText's rule)", () => {
+    const exec = livePlanExecution(
+      makeMessage(MessageType.MESSAGE_AI, "# The Plan\n\nBody"),
+      makeMessage(MessageType.MESSAGE_AI, "   "),
+    );
+    expect(findStreamingPlan(exec)?.messageIndex).toBe(0);
+  });
+
+  it("ignores non-AI message types when selecting the candidate", () => {
+    const exec = livePlanExecution(
+      makeMessage(MessageType.MESSAGE_AI, "# The Plan\n\nBody"),
+      makeMessage(MessageType.MESSAGE_THINKING, "hmm, one more thing"),
+      makeMessage(MessageType.MESSAGE_TOOL, "tool output"),
+    );
+    expect(findStreamingPlan(exec)?.messageIndex).toBe(0);
+  });
+
+  it("returns undefined when there are no messages", () => {
+    expect(findStreamingPlan(livePlanExecution())).toBeUndefined();
+  });
+});
+
+describe("findStreamingPlan — H1 convention", () => {
+  it("does not detect narration (no leading H1)", () => {
+    const exec = livePlanExecution(
+      makeMessage(MessageType.MESSAGE_AI, "Let me explore the codebase."),
+    );
+    expect(findStreamingPlan(exec)).toBeUndefined();
+  });
+
+  it("does not detect a lone '#' first token (title not started yet)", () => {
+    const exec = livePlanExecution(makeMessage(MessageType.MESSAGE_AI, "#"));
+    expect(findStreamingPlan(exec)).toBeUndefined();
+  });
+
+  it("detects the moment the H1 gains its first title character", () => {
+    const exec = livePlanExecution(makeMessage(MessageType.MESSAGE_AI, "# T"));
+    expect(findStreamingPlan(exec)?.displayText).toBe("# T");
+  });
+
+  it("does not detect an H2-led message (## is a section, not a plan title)", () => {
+    const exec = livePlanExecution(
+      makeMessage(MessageType.MESSAGE_AI, "## Notes\n\nSome section"),
+    );
+    expect(findStreamingPlan(exec)).toBeUndefined();
+  });
+
+  it("tolerates leading blank lines before the H1", () => {
+    const exec = livePlanExecution(
+      makeMessage(MessageType.MESSAGE_AI, "\n\n# The Plan\n\nBody"),
+    );
+    expect(findStreamingPlan(exec)).toBeDefined();
+  });
+});
+
+describe("findStreamingPlan — unterminated-fence tolerance", () => {
+  it("unwraps an unterminated ```markdown fence", () => {
+    const exec = livePlanExecution(
+      makeMessage(MessageType.MESSAGE_AI, "```markdown\n# The Plan\n\nBody"),
+    );
+    expect(findStreamingPlan(exec)?.displayText).toBe("# The Plan\n\nBody");
+  });
+
+  it("unwraps an unterminated ```md fence", () => {
+    const exec = livePlanExecution(
+      makeMessage(MessageType.MESSAGE_AI, "```md\n# The Plan"),
+    );
+    expect(findStreamingPlan(exec)?.displayText).toBe("# The Plan");
+  });
+
+  it("unwraps an unterminated bare ``` fence (plan surfaces are markdown by contract)", () => {
+    const exec = livePlanExecution(
+      makeMessage(MessageType.MESSAGE_AI, "```\n# The Plan"),
+    );
+    expect(findStreamingPlan(exec)?.displayText).toBe("# The Plan");
+  });
+
+  it("strips the closing fence once it streams in as the final line", () => {
+    const exec = livePlanExecution(
+      makeMessage(MessageType.MESSAGE_AI, "```markdown\n# The Plan\n\nBody\n```"),
+    );
+    expect(findStreamingPlan(exec)?.displayText).toBe("# The Plan\n\nBody");
+  });
+
+  it("keeps a code-block fence inside the plan intact", () => {
+    const content = "```markdown\n# The Plan\n\n```ts\nconst x = 1;\n```\n\nMore";
+    const exec = livePlanExecution(makeMessage(MessageType.MESSAGE_AI, content));
+    // Only the ENCLOSING fence is stripped; the ts block's fences are content.
+    expect(findStreamingPlan(exec)?.displayText).toBe(
+      "# The Plan\n\n```ts\nconst x = 1;\n```\n\nMore",
+    );
+  });
+
+  it("never unwraps a fence with another language tag (a real code block)", () => {
+    const exec = livePlanExecution(
+      makeMessage(MessageType.MESSAGE_AI, "```python\n# not a heading, a comment"),
+    );
+    expect(findStreamingPlan(exec)).toBeUndefined();
+  });
+
+  it("does not detect a fenced message whose body has no H1", () => {
+    const exec = livePlanExecution(
+      makeMessage(MessageType.MESSAGE_AI, "```\nplain fenced text"),
+    );
+    expect(findStreamingPlan(exec)).toBeUndefined();
+  });
+});

package/src/library/detect-plan-artifact.ts

@@ -2,6 +2,18 @@ import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexe
 import type { ExecutionArtifact } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/artifact_pb";
 import { ExecutionArtifactKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 
+/**
+ * The session's current plan: the published `plan.md` artifact of the most
+ * recent execution that produced one, plus the execution it belongs to
+ * (artifact content RPCs are execution-scoped).
+ */
+export interface SessionPlan {
+  /** ID of the execution that published the plan. */
+  readonly executionId: string;
+  /** The published `plan.md` artifact. */
+  readonly artifact: ExecutionArtifact;
+}
+
 /**
  * Canonical filename a Plan-mode execution publishes its plan under. Kept in
  * sync with the runner's `publishPlanArtifact` (shared/plan-artifact.ts).
@@ -41,3 +53,26 @@ export function findPlanArtifact(
   }
   return undefined;
 }
+
+/**
+ * Finds the session's LATEST plan across all executions — the plan the panel's
+ * plan document tab edits and "Build from plan" implements. Executions are
+ * scanned newest-first (the array is chronological), mirroring the thread's
+ * latest-plan-owns-the-build-action rule so every surface agrees on which
+ * plan is current.
+ *
+ * Returns `undefined` when no execution in the session published a plan.
+ */
+export function findLatestSessionPlan(
+  executions: readonly AgentExecution[],
+): SessionPlan | undefined {
+  for (let i = executions.length - 1; i >= 0; i--) {
+    const execution = executions[i];
+    const artifact = findPlanArtifact(execution);
+    const executionId = execution.metadata?.id;
+    if (artifact && executionId) {
+      return { executionId, artifact };
+    }
+  }
+  return undefined;
+}

package/src/library/detect-streaming-plan.ts

@@ -0,0 +1,108 @@
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import {
+  InteractionMode,
+  MessageType,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { isTerminalPhase } from "@stigmer/sdk";
+
+/**
+ * A plan being written by a live Plan-mode execution, detected mid-stream so
+ * the UI can promote it to a document surface (panel plan tab + compact thread
+ * card) instead of letting it dump into the chat as a giant streaming bubble.
+ */
+export interface StreamingPlan {
+  /** Index of the plan message in `execution.status.messages`. */
+  readonly messageIndex: number;
+  /**
+   * The plan text to render on document surfaces: the message content with
+   * any enclosing plan fence stripped, streaming-tolerantly (an unterminated
+   * opening fence is stripped too — see {@link findStreamingPlan}). Purely a
+   * display projection; the stored message is never mutated.
+   */
+  readonly displayText: string;
+}
+
+/**
+ * Opening line of a whole-message plan fence: ``` with no language tag, or
+ * tagged `markdown`/`md`. Any other tag (```python …) means the message opens
+ * with a genuine code block, not a wrapped plan, and is never unwrapped —
+ * mirroring `unwrapEnclosingMarkdownFence`'s tag rules.
+ */
+const OPENING_PLAN_FENCE_RE = /^(`{3,})(?:markdown|md)?[ \t]*\r?\n/;
+
+/** A streaming plan message qualifies when it opens with an `# H1` title. */
+const LEADING_H1_RE = /^#[ \t]/;
+
+/**
+ * Streaming-tolerant unwrap of a whole-message plan fence.
+ *
+ * `unwrapEnclosingMarkdownFence` deliberately no-ops until the closing fence
+ * arrives (transcripts must stay faithful while a genuine code block is still
+ * open). A plan surface can't wait: mid-stream the closing fence hasn't
+ * streamed yet, and rendering the fence as-is turns the whole live plan into
+ * one giant code block. Because Plan mode's output IS a markdown document by
+ * contract, a message that OPENS with a bare/markdown fence is a wrapped plan
+ * — so this strips the opening fence immediately and the closing fence
+ * whenever it shows up as the final line.
+ */
+function unwrapStreamingPlanFence(content: string): string {
+  const trimmed = content.trim();
+  const open = OPENING_PLAN_FENCE_RE.exec(trimmed);
+  if (!open) return content;
+  const body = trimmed.slice(open[0].length);
+  // Strip the closing fence only when it is the final line (same backtick
+  // run); a fence anywhere else belongs to a code block inside the plan.
+  const close = new RegExp(`(?:^|\\r?\\n)${open[1]}[ \\t]*$`);
+  const closeMatch = close.exec(body);
+  return closeMatch ? body.slice(0, closeMatch.index) : body;
+}
+
+/**
+ * Detects the plan a live Plan-mode execution is currently writing, or
+ * `undefined` when the execution has no recognizable plan in flight.
+ *
+ * This is the third leg of the plan convention, alongside the runner's prompt
+ * directive ("your FINAL message IS the plan, starting with a single `#`
+ * title" — `plan-mode-prompt.ts`) and the completion-time artifact detection
+ * by filename ({@link isPlanArtifact}). Completion makes the plan unambiguous
+ * (the published `plan.md` artifact); mid-stream it must be inferred, and the
+ * directive's mandated shape is the inference:
+ *
+ * - the execution runs in Plan mode and is **non-terminal** (a completed turn
+ *   is owned by the artifact path; a stopped/failed turn has no live plan),
+ * - the candidate is the **last content-bearing `MESSAGE_AI`** — the exact
+ *   selection rule the runner's `extractFinalPlanText` and the thread's
+ *   `findPlanMessageIndex` share, so all three stay in lockstep,
+ * - and that candidate opens with an `# H1` title (after tolerating an
+ *   enclosing plan fence, see {@link unwrapStreamingPlanFence}) — the shape
+ *   the directive mandates and narration essentially never has.
+ *
+ * Degradation is graceful by design: a model that ignores the directive
+ * simply streams its plan in the thread as before, and the completion-time
+ * pipeline is unaffected either way. Only the LAST content-bearing AI message
+ * is ever considered — an earlier message is settled narration, and falling
+ * back to it would promote the wrong text.
+ */
+export function findStreamingPlan(
+  execution: AgentExecution | null | undefined,
+): StreamingPlan | undefined {
+  if (
+    execution?.spec?.executionConfig?.interactionMode !== InteractionMode.PLAN
+  ) {
+    return undefined;
+  }
+  const phase = execution.status?.phase;
+  if (phase === undefined || isTerminalPhase(phase)) return undefined;
+
+  const messages = execution.status?.messages ?? [];
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    if (msg.type !== MessageType.MESSAGE_AI) continue;
+    if (msg.content.trim().length === 0) continue;
+    const displayText = unwrapStreamingPlanFence(msg.content);
+    return LEADING_H1_RE.test(displayText.trimStart())
+      ? { messageIndex: i, displayText }
+      : undefined;
+  }
+  return undefined;
+}