@stigmer/react 3.1.1 → 3.1.3

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

@@ -3,14 +3,48 @@ import type { ExecutionArtifact } from "@stigmer/protos/ai/stigmer/agentic/agent
 import { ExecutionArtifactKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 
 /**
- * Canonical filename a Plan-mode execution publishes its plan under. Kept in
- * sync with the runner's `publishPlanArtifact` (shared/plan-artifact.ts).
+ * The session's current plan: the published plan artifact (a `*.plan.md` FILE)
+ * 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 artifact (`*.plan.md`). */
+  readonly artifact: ExecutionArtifact;
+}
+
+/**
+ * Legacy plan filename. Detection-only: {@link isPlanArtifactName} still
+ * accepts this exact name so plans published before named artifacts existed
+ * keep working. The runner never freshly emits it (a titleless plan falls back
+ * to a bare `<id>.plan.md`). Kept in sync with the runner's
+ * `PLAN_ARTIFACT_NAME` (shared/plan-artifact.ts).
  */
 export const PLAN_ARTIFACT_NAME = "plan.md";
 
 /**
- * Returns `true` when an artifact is the published plan: a FILE artifact named
- * `plan.md`.
+ * Suffix every named plan artifact carries (`<slug>_<id>.plan.md`, or a bare
+ * `<id>.plan.md` when untitled). The runner derives the slug from the plan's
+ * title and the `<id>` from its content hash; detection keys on this suffix.
+ * Kept in sync with the runner's `PLAN_ARTIFACT_SUFFIX` (shared/plan-artifact.ts)
+ * — the runner and browser SDK have disjoint module graphs, so the constant is
+ * duplicated by design, mirroring {@link PLAN_ARTIFACT_NAME}.
+ */
+export const PLAN_ARTIFACT_SUFFIX = ".plan.md";
+
+/**
+ * Returns `true` when a filename is a plan's: the legacy exact `plan.md`, or
+ * any `*.plan.md`. Accepting the legacy name keeps plans published before named
+ * artifacts existed detectable.
+ */
+export function isPlanArtifactName(name: string): boolean {
+  return name === PLAN_ARTIFACT_NAME || name.endsWith(PLAN_ARTIFACT_SUFFIX);
+}
+
+/**
+ * Returns `true` when an artifact is the published plan: a FILE artifact whose
+ * name satisfies {@link isPlanArtifactName}.
  *
  * Detection is by convention — the same lightweight, content-free approach used
  * for skill packages ({@link isSkillPackage}) — so the UI never needs an extra
@@ -20,7 +54,7 @@ export const PLAN_ARTIFACT_NAME = "plan.md";
 export function isPlanArtifact(artifact: ExecutionArtifact): boolean {
   return (
     artifact.kind === ExecutionArtifactKind.FILE &&
-    artifact.name === PLAN_ARTIFACT_NAME
+    isPlanArtifactName(artifact.name)
   );
 }
 
@@ -41,3 +75,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 the "Build" action 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;
+}

package/src/library/index.ts

@@ -26,9 +26,16 @@ export type { SkillPackageDetection } from "./detect-skill-package.js";
 
 export {
   isPlanArtifact,
+  isPlanArtifactName,
   findPlanArtifact,
+  findLatestSessionPlan,
   PLAN_ARTIFACT_NAME,
+  PLAN_ARTIFACT_SUFFIX,
 } from "./detect-plan-artifact.js";
+export type { SessionPlan } from "./detect-plan-artifact.js";
+
+export { findStreamingPlan } from "./detect-streaming-plan.js";
+export type { StreamingPlan } from "./detect-streaming-plan.js";
 
 export { useDetectSkillPackage } from "./useDetectSkillPackage.js";
 export type { UseDetectSkillPackageReturn } from "./useDetectSkillPackage.js";