@mrclrchtr/supi-review 7.3.1 → 8.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (119) hide show
  1. package/README.md +4 -0
  2. package/node_modules/@mrclrchtr/supi-agent-runtime/README.md +11 -1
  3. package/node_modules/@mrclrchtr/supi-agent-runtime/node_modules/@mrclrchtr/supi-core/package.json +1 -1
  4. package/node_modules/@mrclrchtr/supi-agent-runtime/node_modules/@mrclrchtr/supi-core/src/config/config.ts +110 -0
  5. package/node_modules/@mrclrchtr/supi-agent-runtime/node_modules/@mrclrchtr/supi-core/src/config.ts +6 -1
  6. package/node_modules/@mrclrchtr/supi-agent-runtime/node_modules/@mrclrchtr/supi-core/src/settings/settings-schema.ts +2 -1
  7. package/node_modules/@mrclrchtr/supi-agent-runtime/package.json +7 -3
  8. package/node_modules/@mrclrchtr/supi-agent-runtime/src/api.ts +37 -1
  9. package/node_modules/@mrclrchtr/supi-agent-runtime/src/lifecycle-trace.ts +5 -2
  10. package/node_modules/@mrclrchtr/supi-agent-runtime/src/run.ts +237 -35
  11. package/node_modules/@mrclrchtr/supi-agent-runtime/src/session/agent-run-registry-types.ts +95 -0
  12. package/node_modules/@mrclrchtr/supi-agent-runtime/src/session/agent-run-registry.ts +372 -0
  13. package/node_modules/@mrclrchtr/supi-agent-runtime/src/session/transcript-format.ts +184 -0
  14. package/node_modules/@mrclrchtr/supi-agent-runtime/src/session/transcript-store.ts +284 -0
  15. package/node_modules/@mrclrchtr/supi-agent-runtime/src/types.ts +30 -4
  16. package/node_modules/@mrclrchtr/supi-agent-runtime/src/ui/agents-command.ts +206 -0
  17. package/node_modules/@mrclrchtr/supi-agent-runtime/src/ui/agents-overlay-data.ts +100 -0
  18. package/node_modules/@mrclrchtr/supi-agent-runtime/src/ui/agents-overlay-render.ts +167 -0
  19. package/node_modules/@mrclrchtr/supi-agent-runtime/src/ui/agents-overlay.ts +398 -0
  20. package/node_modules/@mrclrchtr/supi-agent-runtime/src/ui/agents-run-list.ts +95 -0
  21. package/node_modules/@mrclrchtr/supi-agent-runtime/src/ui/agents-run-switcher.ts +29 -0
  22. package/node_modules/@mrclrchtr/supi-agent-runtime/src/ui/agents-run-viewer-input.ts +69 -0
  23. package/node_modules/@mrclrchtr/supi-agent-runtime/src/ui/agents-run-viewer-render.ts +246 -0
  24. package/node_modules/@mrclrchtr/supi-agent-runtime/src/ui/agents-run-viewer.ts +400 -0
  25. package/node_modules/@mrclrchtr/supi-agent-runtime/src/ui/agents-run-viewport.ts +112 -0
  26. package/node_modules/@mrclrchtr/supi-agent-runtime/src/ui/agents-steering-input.ts +50 -0
  27. package/node_modules/@mrclrchtr/supi-agent-runtime/src/ui/agents-transcript-context.ts +56 -0
  28. package/node_modules/@mrclrchtr/supi-agent-runtime/src/ui/agents-transcript-pane.ts +386 -0
  29. package/node_modules/@mrclrchtr/supi-agent-runtime/src/ui/agents-transcript-payload.ts +66 -0
  30. package/node_modules/@mrclrchtr/supi-agent-runtime/src/ui/agents-transcript.ts +380 -0
  31. package/node_modules/@mrclrchtr/supi-code-intelligence/README.md +6 -6
  32. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-code-runtime/package.json +1 -1
  33. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-code-runtime/src/api.ts +1 -1
  34. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-code-runtime/src/query-result.ts +22 -4
  35. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-core/package.json +1 -1
  36. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-core/src/config/config.ts +110 -0
  37. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-core/src/config.ts +6 -1
  38. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-core/src/settings/settings-schema.ts +2 -1
  39. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/README.md +29 -6
  40. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-code-runtime/package.json +1 -1
  41. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-code-runtime/src/api.ts +1 -1
  42. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-code-runtime/src/query-result.ts +22 -4
  43. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-core/package.json +1 -1
  44. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-core/src/config/config.ts +110 -0
  45. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-core/src/config.ts +6 -1
  46. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-core/src/settings/settings-schema.ts +2 -1
  47. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/package.json +3 -3
  48. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/src/api.ts +25 -3
  49. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/src/client/client-diagnostic-host.ts +2 -1
  50. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/src/client/client-diagnostic-refresh.ts +5 -2
  51. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/src/client/client-diagnostics.ts +39 -6
  52. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/src/client/client-document-sync.ts +82 -12
  53. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/src/client/client-semantic-input-barrier.ts +28 -5
  54. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/src/client/client.ts +606 -30
  55. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/src/config/capabilities.ts +9 -0
  56. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/src/config/config.ts +69 -8
  57. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/src/config/operation-support.ts +196 -0
  58. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/src/config/server-config.ts +15 -0
  59. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/src/config/types.ts +9 -1
  60. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/src/manager/manager-project-info.ts +2 -0
  61. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/src/manager/manager-workspace-symbol.ts +31 -2
  62. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/src/manager/manager.ts +72 -2
  63. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/src/provider/lsp-refactor-provider.ts +9 -43
  64. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/src/provider/refactor-planning.ts +102 -50
  65. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/src/provider/semantic-edit-normalizer.ts +49 -3
  66. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/src/session/runtime-controller.ts +78 -18
  67. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/src/session/runtime-registry.ts +46 -2
  68. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/src/session/workspace-lsp-runtime.ts +14 -0
  69. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/src/workspace-path-policy.ts +30 -4
  70. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/package.json +1 -1
  71. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/src/api.ts +1 -1
  72. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/src/query-result.ts +22 -4
  73. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-core/package.json +1 -1
  74. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-core/src/config/config.ts +110 -0
  75. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-core/src/config.ts +6 -1
  76. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-core/src/settings/settings-schema.ts +2 -1
  77. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-tree-sitter/package.json +3 -3
  78. package/node_modules/@mrclrchtr/supi-code-intelligence/package.json +5 -5
  79. package/node_modules/@mrclrchtr/supi-code-intelligence/src/analysis/capability/capability-warnings.ts +64 -25
  80. package/node_modules/@mrclrchtr/supi-code-intelligence/src/analysis/health/server-status.ts +23 -1
  81. package/node_modules/@mrclrchtr/supi-code-intelligence/src/analysis/health/signals.ts +1 -0
  82. package/node_modules/@mrclrchtr/supi-code-intelligence/src/analysis/search/ast-scan.ts +42 -8
  83. package/node_modules/@mrclrchtr/supi-code-intelligence/src/analysis/search/pattern.ts +4 -0
  84. package/node_modules/@mrclrchtr/supi-code-intelligence/src/config.ts +64 -34
  85. package/node_modules/@mrclrchtr/supi-code-intelligence/src/extension.ts +29 -10
  86. package/node_modules/@mrclrchtr/supi-code-intelligence/src/headless.ts +1 -0
  87. package/node_modules/@mrclrchtr/supi-code-intelligence/src/session/find-types.ts +2 -1
  88. package/node_modules/@mrclrchtr/supi-code-intelligence/src/session/find-workflow.ts +5 -0
  89. package/node_modules/@mrclrchtr/supi-code-intelligence/src/session/health-types.ts +3 -0
  90. package/node_modules/@mrclrchtr/supi-code-intelligence/src/session/health-workflow.ts +10 -1
  91. package/node_modules/@mrclrchtr/supi-code-intelligence/src/session/session.ts +34 -2
  92. package/node_modules/@mrclrchtr/supi-code-intelligence/src/substrate/lsp/lifecycle.ts +2 -0
  93. package/node_modules/@mrclrchtr/supi-code-intelligence/src/substrate/lsp/recovery.ts +3 -3
  94. package/node_modules/@mrclrchtr/supi-code-intelligence/src/substrate/lsp/settings.ts +191 -108
  95. package/node_modules/@mrclrchtr/supi-code-intelligence/src/substrate/workspace-provider-host.ts +50 -12
  96. package/node_modules/@mrclrchtr/supi-code-intelligence/src/tool/code_find/markdown.ts +12 -0
  97. package/node_modules/@mrclrchtr/supi-code-intelligence/src/tool/code_find/render.ts +20 -0
  98. package/node_modules/@mrclrchtr/supi-code-intelligence/src/tool/code_find/result.ts +3 -0
  99. package/node_modules/@mrclrchtr/supi-code-intelligence/src/tool/code_health/markdown.ts +3 -0
  100. package/node_modules/@mrclrchtr/supi-code-intelligence/src/tool/code_health/result.ts +3 -1
  101. package/node_modules/@mrclrchtr/supi-code-intelligence/src/tool/result/types.ts +3 -1
  102. package/node_modules/@mrclrchtr/supi-code-intelligence/src/ui/status-command.ts +54 -6
  103. package/node_modules/@mrclrchtr/supi-code-intelligence/src/ui/status-overlay.ts +5 -0
  104. package/node_modules/@mrclrchtr/supi-core/package.json +1 -1
  105. package/node_modules/@mrclrchtr/supi-core/src/config/config.ts +110 -0
  106. package/node_modules/@mrclrchtr/supi-core/src/config.ts +6 -1
  107. package/node_modules/@mrclrchtr/supi-core/src/settings/settings-schema.ts +2 -1
  108. package/package.json +4 -4
  109. package/src/review.ts +5 -2
  110. package/src/tool/review_run/child-session.ts +29 -7
  111. package/src/tool/review_run/execute.ts +6 -1
  112. package/src/tool/review_run/execution.ts +6 -0
  113. package/src/tool/review_run/register.ts +3 -1
  114. package/src/tool/review_run/runner.ts +40 -0
  115. package/src/tool/review_run/spec.ts +2 -0
  116. package/src/tool/review_run/workflow.ts +7 -1
  117. package/src/tui/review-command.ts +74 -3
  118. package/src/types.ts +5 -0
  119. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/src/config/lsp-settings.ts +0 -22
@@ -1,10 +1,12 @@
1
1
  // biome-ignore lint/style/noExcessiveLinesPerFile: the Agent Run state machine keeps lifecycle ownership auditable in one closure.
2
+ import { randomUUID } from "node:crypto";
2
3
  import type { Api, Model, Usage } from "@earendil-works/pi-ai";
3
4
  import type {
4
5
  AgentSession,
5
6
  AgentSessionEvent,
6
7
  AgentSessionRuntime,
7
8
  ExtensionRuntime,
9
+ PromptOptions,
8
10
  } from "@earendil-works/pi-coding-agent";
9
11
  import {
10
12
  createAgentSession,
@@ -29,12 +31,38 @@ import type {
29
31
  AgentRunSessionView,
30
32
  AgentRunStatus,
31
33
  AgentRunSteerResult,
34
+ RegisteredAgentRunHandle,
32
35
  StartAgentRunOptions,
36
+ StartRegisteredAgentRunOptions,
33
37
  } from "./types.ts";
34
38
  import { collectAgentRunUsage } from "./usage.ts";
35
39
 
36
40
  /** Grace period for a provider abort before disposal continues. */
37
41
  export const AGENT_RUN_ABORT_GRACE_MS = 2_000;
42
+ /** Maximum wait for initial steering to settle before recovery is skipped. */
43
+ const INITIAL_STEERING_DRAIN_GRACE_MS = 2_000;
44
+ type PromptDisposition = Parameters<NonNullable<PromptOptions["preflightResult"]>>[0];
45
+ type PromptRejectionReason =
46
+ | "handled"
47
+ | "queued"
48
+ | "threw-before-start"
49
+ | "resolved-without-disposition";
50
+ // Pi can defer a prompt after its first call resolves. Reject a late start.
51
+ const shouldRejectLatePromptStart = (state: {
52
+ disposition: PromptDisposition;
53
+ preflightClosed: boolean;
54
+ promptPromiseSettled: boolean;
55
+ promptFailureRecorded: boolean;
56
+ promptClosed: boolean;
57
+ dispositionObserved: boolean;
58
+ promptAccepted: boolean;
59
+ }): boolean =>
60
+ state.disposition === "started" &&
61
+ (state.preflightClosed ||
62
+ state.promptPromiseSettled ||
63
+ state.promptFailureRecorded ||
64
+ state.promptClosed ||
65
+ (state.dispositionObserved && !state.promptAccepted));
38
66
  /** Grace period for AgentSessionRuntime disposal. */
39
67
  export const AGENT_RUN_SHUTDOWN_GRACE_MS = 2_000;
40
68
  /** Maximum turns accepted from one finite continuation policy. */
@@ -95,6 +123,7 @@ export function startAgentRun<T>(options: StartAgentRunOptions<T>): AgentRunHand
95
123
  let admissionGeneration = 0;
96
124
  let fencedSession: AgentSession | undefined;
97
125
  const extensionWork = new Set<Promise<unknown>>();
126
+ const inFlightSteering = new Set<Promise<AgentRunSteerResult>>();
98
127
  let resolveSessionSetupFinished!: () => void;
99
128
  const sessionSetupDone = new Promise<void>((resolve) => {
100
129
  resolveSessionSetupFinished = resolve;
@@ -419,6 +448,7 @@ export function startAgentRun<T>(options: StartAgentRunOptions<T>): AgentRunHand
419
448
  if (event.type !== "agent_settled" || aborting || terminal || finalizing) return;
420
449
  settledEventObserved = true;
421
450
  promptActive = false;
451
+ publish();
422
452
  };
423
453
 
424
454
  const pendingMessageCount = (activeSession: AgentSession): number | undefined => {
@@ -451,6 +481,21 @@ export function startAgentRun<T>(options: StartAgentRunOptions<T>): AgentRunHand
451
481
  }
452
482
  };
453
483
 
484
+ /** Wait briefly for initial steering before starting recovery. */
485
+ const awaitInitialSteeringDrain = async (): Promise<boolean> => {
486
+ if (inFlightSteering.size === 0) return true;
487
+ const pending = [...inFlightSteering];
488
+ let timeoutId: ReturnType<typeof setTimeout> | undefined;
489
+ const drained = await Promise.race([
490
+ Promise.allSettled(pending).then(() => true),
491
+ new Promise<boolean>((resolve) => {
492
+ timeoutId = setTimeout(() => resolve(false), INITIAL_STEERING_DRAIN_GRACE_MS);
493
+ }),
494
+ ]);
495
+ if (timeoutId !== undefined) clearTimeout(timeoutId);
496
+ return drained;
497
+ };
498
+
454
499
  const authorizedContinuationModel = (model: Model<Api>): boolean =>
455
500
  [options.inputs.model, ...(options.inputs.authorizedContinuationModels ?? [])].some(
456
501
  (candidate) => candidate.provider === model.provider && candidate.id === model.id,
@@ -535,18 +580,31 @@ export function startAgentRun<T>(options: StartAgentRunOptions<T>): AgentRunHand
535
580
  activeSession.setThinkingLevel(step.thinkingLevel);
536
581
  const previousAssistant = latestAssistant(activeSession);
537
582
  let accepted = false;
583
+ let dispositionSeen = false;
584
+ let promptCallSettled = false;
538
585
  let promptFailed = false;
539
586
  try {
540
587
  await activeSession.prompt(step.prompt, {
541
- preflightResult: (success) => {
542
- accepted = success;
543
- if (success && (aborting || terminal || finalizing)) {
544
- throw new Error("Agent Run continuation canceled before acceptance");
588
+ preflightResult: (disposition) => {
589
+ if (
590
+ disposition === "started" &&
591
+ (promptCallSettled ||
592
+ aborting ||
593
+ terminal ||
594
+ finalizing ||
595
+ (dispositionSeen && !accepted))
596
+ ) {
597
+ throw new Error("Agent Run continuation prompt started after its preflight closed");
545
598
  }
599
+ if (dispositionSeen) return;
600
+ dispositionSeen = true;
601
+ accepted = disposition === "started";
546
602
  },
547
603
  });
548
604
  } catch {
549
605
  promptFailed = true;
606
+ } finally {
607
+ promptCallSettled = true;
550
608
  }
551
609
  try {
552
610
  await awaitSessionQuiescence(activeSession);
@@ -586,6 +644,12 @@ export function startAgentRun<T>(options: StartAgentRunOptions<T>): AgentRunHand
586
644
  return;
587
645
  }
588
646
  continuationInitialFailure ??= initialFailureCode;
647
+ const steeringDrained = await awaitInitialSteeringDrain();
648
+ if (aborting || terminal || finalizing) return;
649
+ if (!steeringDrained) {
650
+ await finishFailed(continuationInitialFailure);
651
+ return;
652
+ }
589
653
  const maximumTurns = policy.maxTurns;
590
654
  while (continuationTurn < maximumTurns && !aborting && !terminal && !finalizing) {
591
655
  const nextTurn = continuationTurn + 1;
@@ -736,28 +800,72 @@ export function startAgentRun<T>(options: StartAgentRunOptions<T>): AgentRunHand
736
800
  timeoutId = setTimeout(requestTimeout, options.timeoutMs);
737
801
  timeoutId.unref?.();
738
802
  }
739
- const onPreflight = (accepted: boolean): void => {
803
+ const promptIsClosed = (): boolean =>
804
+ cancelRequested || timeoutRequested || aborting || terminal || finalizing;
805
+ const publishPromptAcceptance = (): void => {
806
+ publish();
807
+ if (promptIsClosed()) {
808
+ throw new Error("Agent Run prompt canceled before acceptance");
809
+ }
810
+ };
811
+ const rejectBeforePromptStarted = (reason: PromptRejectionReason): void => {
812
+ promptFailureCode ??= "prompt-rejected";
813
+ if (promptIsClosed()) return;
814
+ lifecycle.recordHostMarker({ type: "prompt_rejected", reason });
815
+ };
816
+ let promptDispositionObserved = false;
817
+ // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: Check the late-start fence before changing preflight state.
818
+ const onPreflight = (disposition: PromptDisposition): void => {
819
+ const preflightClosed = promptPreflightSettled && !promptDispositionObserved;
820
+ if (
821
+ shouldRejectLatePromptStart({
822
+ disposition,
823
+ preflightClosed,
824
+ promptPromiseSettled,
825
+ promptFailureRecorded: promptFailureCode !== undefined,
826
+ promptClosed: promptIsClosed(),
827
+ dispositionObserved: promptDispositionObserved,
828
+ promptAccepted,
829
+ })
830
+ ) {
831
+ settlePromptPreflight();
832
+ throw new Error("Agent Run prompt started after its preflight closed");
833
+ }
834
+ if (promptDispositionObserved || preflightClosed) return;
835
+ promptDispositionObserved = true;
740
836
  settlePromptPreflight();
741
- if (!accepted) {
837
+ if (disposition !== "started") {
742
838
  promptActive = false;
743
- if (cancelRequested || timeoutRequested || aborting || terminal || finalizing) return;
744
- lifecycle.recordHostMarker({ type: "prompt_rejected" });
745
- promptFailureCode = "prompt-rejected";
839
+ if (promptIsClosed()) return;
840
+ rejectBeforePromptStarted(disposition);
746
841
  return;
747
842
  }
748
- if (cancelRequested || timeoutRequested || aborting || terminal || finalizing) {
843
+ if (promptIsClosed()) {
749
844
  throw new Error("Agent Run prompt canceled before acceptance");
750
845
  }
751
846
  promptAccepted = true;
752
847
  promptActive = true;
848
+ publishPromptAcceptance();
849
+ };
850
+ const handlePromptRejection = (): void => {
851
+ if (promptFailureCode) return;
852
+ if (promptAccepted) {
853
+ promptFailureCode = "unexpected-runner-failure";
854
+ } else {
855
+ rejectBeforePromptStarted("threw-before-start");
856
+ }
753
857
  };
754
858
  try {
755
859
  const promptPromise = session.prompt(options.prompt, { preflightResult: onPreflight });
756
860
  void Promise.resolve(promptPromise).then(
757
861
  () => {
862
+ if (!promptPreflightSettled && !promptAccepted) {
863
+ rejectBeforePromptStarted("resolved-without-disposition");
864
+ }
758
865
  settlePromptPreflight();
759
866
  promptPromiseSettled = true;
760
867
  promptActive = false;
868
+ publish();
761
869
  if (promptFailureCode) startPromptFailureSettlement(promptFailureCode);
762
870
  else startPromptSettlement();
763
871
  },
@@ -765,16 +873,18 @@ export function startAgentRun<T>(options: StartAgentRunOptions<T>): AgentRunHand
765
873
  settlePromptPreflight();
766
874
  promptPromiseSettled = true;
767
875
  promptActive = false;
768
- promptFailureCode ??= "unexpected-runner-failure";
769
- startPromptFailureSettlement(promptFailureCode);
876
+ publish();
877
+ handlePromptRejection();
878
+ startPromptFailureSettlement(promptFailureCode ?? "unexpected-runner-failure");
770
879
  },
771
880
  );
772
881
  } catch {
773
882
  settlePromptPreflight();
774
883
  promptPromiseSettled = true;
775
884
  promptActive = false;
776
- promptFailureCode ??= "unexpected-runner-failure";
777
- startPromptFailureSettlement(promptFailureCode);
885
+ publish();
886
+ handlePromptRejection();
887
+ startPromptFailureSettlement(promptFailureCode ?? "unexpected-runner-failure");
778
888
  }
779
889
  };
780
890
 
@@ -904,6 +1014,18 @@ export function startAgentRun<T>(options: StartAgentRunOptions<T>): AgentRunHand
904
1014
  };
905
1015
 
906
1016
  const handle: AgentRunHandle<T> = {
1017
+ get steeringAvailable() {
1018
+ return (
1019
+ progressState.status === "running" &&
1020
+ Boolean(session) &&
1021
+ promptActive &&
1022
+ Boolean(session?.isStreaming) &&
1023
+ !settledEventObserved &&
1024
+ !terminal &&
1025
+ !finalizing &&
1026
+ !aborting
1027
+ );
1028
+ },
907
1029
  result,
908
1030
  subscribe(listener) {
909
1031
  listeners.add(listener);
@@ -915,32 +1037,34 @@ export function startAgentRun<T>(options: StartAgentRunOptions<T>): AgentRunHand
915
1037
  return () => listeners.delete(listener);
916
1038
  },
917
1039
  steer: async (message): Promise<AgentRunSteerResult> => {
918
- if (
919
- progressState.status !== "running" ||
920
- !session ||
921
- !promptActive ||
922
- !session.isStreaming ||
923
- settledEventObserved ||
924
- terminal ||
925
- finalizing ||
926
- aborting
927
- )
928
- return "not-running";
1040
+ if (!handle.steeringAvailable || !session) return "not-running";
929
1041
  const activeSession = session;
930
1042
  const admissionAtStart = admissionGeneration;
931
- try {
932
- await activeSession.steer(message);
933
- if (!extensionAdmissionOpen || admissionGeneration !== admissionAtStart) {
934
- try {
935
- activeSession.clearQueue();
936
- } catch {
937
- // A late queue write is inert once the session is closing.
1043
+ const steering = (async (): Promise<AgentRunSteerResult> => {
1044
+ try {
1045
+ const disposition = await activeSession.steer(message);
1046
+ if (
1047
+ !extensionAdmissionOpen ||
1048
+ admissionGeneration !== admissionAtStart ||
1049
+ !handle.steeringAvailable
1050
+ ) {
1051
+ try {
1052
+ activeSession.clearQueue();
1053
+ } catch {
1054
+ // Recovery waits for this write to finish before it starts.
1055
+ }
1056
+ return "not-running";
938
1057
  }
1058
+ return disposition;
1059
+ } catch {
939
1060
  return "not-running";
940
1061
  }
941
- return "accepted";
942
- } catch {
943
- return "not-running";
1062
+ })();
1063
+ inFlightSteering.add(steering);
1064
+ try {
1065
+ return await steering;
1066
+ } finally {
1067
+ inFlightSteering.delete(steering);
944
1068
  }
945
1069
  },
946
1070
  stop: requestCancellation,
@@ -961,6 +1085,84 @@ export function startAgentRun<T>(options: StartAgentRunOptions<T>): AgentRunHand
961
1085
  return handle;
962
1086
  }
963
1087
 
1088
+ /**
1089
+ * Start an Agent Run with registry tracking and awaited transcript capture.
1090
+ *
1091
+ * `stop()` waits for bounded Agent Run disposal. It does not wait for transcript writes. `result`
1092
+ * resolves after the final transcript writes finish. A storage failure marks the transcript
1093
+ * incomplete and does not change the Agent Run outcome. Without a registry, no transcript is
1094
+ * created. A closed registry stops the Agent Run.
1095
+ */
1096
+ export function startRegisteredAgentRun<T>(
1097
+ options: StartRegisteredAgentRunOptions<T>,
1098
+ ): RegisteredAgentRunHandle<T> {
1099
+ const { registry, registration, transcriptSystemPrompt, ...runOptions } = options;
1100
+ const runKey = registration.metadata.runKey ?? randomUUID();
1101
+ const metadata = {
1102
+ ...registration.metadata,
1103
+ runKey,
1104
+ batchId: registration.metadata.batchId ?? "default",
1105
+ };
1106
+ const transcript = registry?.createTranscriptCapture(metadata, transcriptSystemPrompt ?? "");
1107
+ const observer = async (session: AgentRunSessionView): Promise<(() => void) | undefined> => {
1108
+ const detachTranscript = registry?.attachSession(runKey, session);
1109
+ try {
1110
+ const detachCallerObserver = await options.observer?.(session);
1111
+ if (!detachTranscript && typeof detachCallerObserver !== "function") return undefined;
1112
+ return () => {
1113
+ try {
1114
+ detachCallerObserver?.();
1115
+ } finally {
1116
+ detachTranscript?.();
1117
+ }
1118
+ };
1119
+ } catch (error) {
1120
+ try {
1121
+ detachTranscript?.();
1122
+ } catch {
1123
+ // Transcript observer cleanup cannot replace the caller observer error.
1124
+ }
1125
+ throw error;
1126
+ }
1127
+ };
1128
+ const handle = startAgentRun({ ...runOptions, observer });
1129
+ const result = handle.result.then(async (outcome) => {
1130
+ try {
1131
+ await transcript?.finish();
1132
+ } catch {
1133
+ // Transcript storage cannot change the Agent Run outcome.
1134
+ }
1135
+ return outcome;
1136
+ });
1137
+ const registeredHandle: RegisteredAgentRunHandle<T> = {
1138
+ runKey,
1139
+ get steeringAvailable() {
1140
+ return handle.steeringAvailable;
1141
+ },
1142
+ result,
1143
+ subscribe(listener) {
1144
+ return handle.subscribe(listener);
1145
+ },
1146
+ steer(message) {
1147
+ return handle.steer(message);
1148
+ },
1149
+ stop() {
1150
+ // Stop waits for bounded Agent Run disposal, not for transcript writes.
1151
+ return handle.stop();
1152
+ },
1153
+ };
1154
+ registry?.register({
1155
+ metadata,
1156
+ ...(transcript ? { transcript } : {}),
1157
+ handle: registeredHandle,
1158
+ ...(registration.getConversation ? { getConversation: registration.getConversation } : {}),
1159
+ ...(registration.getRecentActivity
1160
+ ? { getRecentActivity: registration.getRecentActivity }
1161
+ : {}),
1162
+ });
1163
+ return registeredHandle;
1164
+ }
1165
+
964
1166
  function usageFields(usage: Usage | undefined): { usage?: Usage } {
965
1167
  return usage ? { usage } : {};
966
1168
  }
@@ -0,0 +1,95 @@
1
+ import type { ModelThinkingLevel, Usage } from "@earendil-works/pi-ai";
2
+ import type { AgentRunHandle, AgentRunProgress } from "../types.ts";
3
+ import type { AgentRunTranscriptCapture, AgentRunTranscriptSource } from "./transcript-store.ts";
4
+
5
+ /** One bounded human-facing entry in a run's live conversation summary. */
6
+ export type AgentRunDisplayEntry =
7
+ | { readonly kind: "assistant"; readonly text: string }
8
+ | { readonly kind: "steering"; readonly text: string }
9
+ | {
10
+ readonly kind: "tool";
11
+ readonly toolName: string;
12
+ readonly status: "completed" | "error" | "unknown";
13
+ readonly summary?: string;
14
+ };
15
+
16
+ /** A caller-provided, bounded summary for the run viewer. */
17
+ export interface AgentRunDisplayConversation {
18
+ readonly entries: readonly AgentRunDisplayEntry[];
19
+ readonly omittedEntryCount: number;
20
+ readonly omittedCharacterCount: number;
21
+ readonly textTruncated: boolean;
22
+ }
23
+
24
+ /** Caller-owned display fields that do not change Agent Run execution or outcome. */
25
+ export interface AgentRunDisplayDetails {
26
+ readonly target?: string;
27
+ readonly batchLabel?: string;
28
+ readonly verdict?: string;
29
+ readonly findingCount?: number;
30
+ readonly blockingFindingCount?: number;
31
+ }
32
+
33
+ /** Neutral metadata for one Agent Run in the containing-session viewer. */
34
+ export interface AgentRunDisplayMetadata {
35
+ readonly runKey?: string;
36
+ readonly batchId?: string;
37
+ readonly taskId: string;
38
+ /** Short caller-owned role, such as "Agent" or "Reviewer". */
39
+ readonly kind: string;
40
+ /** Short caller-owned label, such as a Profile ID or Review Mode. */
41
+ readonly label: string;
42
+ readonly cwd: string;
43
+ readonly modelId: string;
44
+ readonly thinkingLevel: ModelThinkingLevel;
45
+ readonly tools: readonly string[];
46
+ readonly taskDescription?: string;
47
+ readonly sharedContext?: string;
48
+ readonly display?: AgentRunDisplayDetails;
49
+ readonly startedAt: number;
50
+ }
51
+
52
+ /** Parent-owned details that the runtime viewer can show without changing tool output. */
53
+ export interface AgentRunDisplayResult {
54
+ readonly finalText?: string;
55
+ readonly display?: AgentRunDisplayDetails;
56
+ readonly failureCode?: string;
57
+ readonly humanTruncated?: boolean;
58
+ readonly modelTruncated?: boolean;
59
+ }
60
+
61
+ /** Metadata and controls needed to register one active run. */
62
+ export interface AgentRunRegistration {
63
+ readonly metadata: AgentRunDisplayMetadata;
64
+ readonly transcript?: AgentRunTranscriptCapture;
65
+ readonly handle: AgentRunHandle<unknown>;
66
+ readonly getConversation?: (
67
+ queuedSteering: readonly string[],
68
+ ) => AgentRunDisplayConversation | undefined;
69
+ readonly getRecentActivity?: () => readonly string[];
70
+ }
71
+
72
+ /** One active or completed run exposed to the shared viewer. */
73
+ export interface AgentRunRegistryRun extends AgentRunDisplayMetadata {
74
+ readonly runKey: string;
75
+ readonly batchId: string;
76
+ readonly active: boolean;
77
+ readonly status: AgentRunProgress["status"];
78
+ readonly finishedAt?: number;
79
+ readonly steeringAvailable: boolean;
80
+ readonly turns: number;
81
+ readonly toolUses: number;
82
+ readonly usage?: Usage;
83
+ readonly recentActivity?: readonly string[];
84
+ readonly transcriptSource?: AgentRunTranscriptSource;
85
+ readonly conversation?: AgentRunDisplayConversation;
86
+ readonly result?: AgentRunDisplayResult;
87
+ }
88
+
89
+ /** Current session-local state for the shared run viewer. */
90
+ export interface AgentRunRegistrySnapshot {
91
+ readonly runs: readonly AgentRunRegistryRun[];
92
+ }
93
+
94
+ /** Result of one selected-run stop request. */
95
+ export type AgentRunStopResult = "accepted" | "not-running";