@mrclrchtr/supi-review 7.3.0 → 7.4.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 (58) hide show
  1. package/README.md +4 -0
  2. package/node_modules/@mrclrchtr/supi-agent-runtime/README.md +10 -0
  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/package.json +7 -3
  5. package/node_modules/@mrclrchtr/supi-agent-runtime/src/api.ts +37 -1
  6. package/node_modules/@mrclrchtr/supi-agent-runtime/src/run.ts +151 -21
  7. package/node_modules/@mrclrchtr/supi-agent-runtime/src/session/agent-run-registry-types.ts +95 -0
  8. package/node_modules/@mrclrchtr/supi-agent-runtime/src/session/agent-run-registry.ts +372 -0
  9. package/node_modules/@mrclrchtr/supi-agent-runtime/src/session/transcript-format.ts +184 -0
  10. package/node_modules/@mrclrchtr/supi-agent-runtime/src/session/transcript-store.ts +284 -0
  11. package/node_modules/@mrclrchtr/supi-agent-runtime/src/types.ts +22 -0
  12. package/node_modules/@mrclrchtr/supi-agent-runtime/src/ui/agents-command.ts +206 -0
  13. package/node_modules/@mrclrchtr/supi-agent-runtime/src/ui/agents-overlay-data.ts +78 -0
  14. package/node_modules/@mrclrchtr/supi-agent-runtime/src/ui/agents-overlay-render.ts +167 -0
  15. package/node_modules/@mrclrchtr/supi-agent-runtime/src/ui/agents-overlay.ts +400 -0
  16. package/node_modules/@mrclrchtr/supi-agent-runtime/src/ui/agents-run-list.ts +95 -0
  17. package/node_modules/@mrclrchtr/supi-agent-runtime/src/ui/agents-run-switcher.ts +29 -0
  18. package/node_modules/@mrclrchtr/supi-agent-runtime/src/ui/agents-run-viewer-input.ts +69 -0
  19. package/node_modules/@mrclrchtr/supi-agent-runtime/src/ui/agents-run-viewer-render.ts +246 -0
  20. package/node_modules/@mrclrchtr/supi-agent-runtime/src/ui/agents-run-viewer.ts +400 -0
  21. package/node_modules/@mrclrchtr/supi-agent-runtime/src/ui/agents-run-viewport.ts +112 -0
  22. package/node_modules/@mrclrchtr/supi-agent-runtime/src/ui/agents-steering-input.ts +50 -0
  23. package/node_modules/@mrclrchtr/supi-agent-runtime/src/ui/agents-transcript-context.ts +56 -0
  24. package/node_modules/@mrclrchtr/supi-agent-runtime/src/ui/agents-transcript-pane.ts +386 -0
  25. package/node_modules/@mrclrchtr/supi-agent-runtime/src/ui/agents-transcript-payload.ts +66 -0
  26. package/node_modules/@mrclrchtr/supi-agent-runtime/src/ui/agents-transcript.ts +380 -0
  27. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-code-runtime/package.json +1 -1
  28. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-core/package.json +1 -1
  29. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-code-runtime/package.json +1 -1
  30. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-core/package.json +1 -1
  31. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/node_modules/ignore/index.js +25 -6
  32. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/node_modules/ignore/legacy.js +22 -6
  33. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/node_modules/ignore/package.json +1 -1
  34. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/node_modules/vscode-jsonrpc/lib/common/connection.js +2 -2
  35. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/node_modules/vscode-jsonrpc/lib/node/main.d.ts +1 -0
  36. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/node_modules/vscode-jsonrpc/lib/node/main.js +7 -0
  37. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/node_modules/vscode-jsonrpc/package.json +2 -2
  38. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/node_modules/vscode-languageserver-protocol/lib/common/protocol.inlayHint.d.ts +2 -2
  39. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/node_modules/vscode-languageserver-protocol/lib/common/protocol.inlineCompletion.d.ts +2 -2
  40. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/node_modules/vscode-languageserver-protocol/lib/common/protocol.inlineValue.d.ts +2 -2
  41. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/node_modules/vscode-languageserver-protocol/package.json +4 -4
  42. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/node_modules/vscode-languageserver-types/package.json +2 -2
  43. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-lsp/package.json +3 -3
  44. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/package.json +1 -1
  45. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-core/package.json +1 -1
  46. package/node_modules/@mrclrchtr/supi-code-intelligence/node_modules/@mrclrchtr/supi-tree-sitter/package.json +3 -3
  47. package/node_modules/@mrclrchtr/supi-code-intelligence/package.json +5 -5
  48. package/node_modules/@mrclrchtr/supi-core/package.json +1 -1
  49. package/package.json +4 -4
  50. package/src/review.ts +5 -2
  51. package/src/tool/review_run/child-session.ts +29 -7
  52. package/src/tool/review_run/execute.ts +6 -1
  53. package/src/tool/review_run/execution.ts +6 -0
  54. package/src/tool/review_run/register.ts +3 -1
  55. package/src/tool/review_run/runner.ts +40 -0
  56. package/src/tool/review_run/workflow.ts +7 -1
  57. package/src/tui/review-command.ts +74 -3
  58. package/src/types.ts +5 -0
package/README.md CHANGED
@@ -28,6 +28,10 @@ This package is beta software. Its interfaces can change.
28
28
 
29
29
  Changes to **Agent tools** apply immediately. Turning this setting off removes the agent start and audit tools from the active tool set. The output tool and the commands stay available.
30
30
 
31
+ ## Shared `/agents` viewer
32
+
33
+ When this package is loaded, each Reviewer Session appears in the runtime-owned `/agents` viewer with its status and human-only transcript. The runtime keeps that transcript until the containing PI session ends. It does so even when Review audit is off. A Local Reviewer Replay remains a separate Review-owned artifact with its own seven-day retention. Stopping one Reviewer Run does not stop its sibling tasks.
34
+
31
35
  ## Review input
32
36
 
33
37
  `review_run` has one flat input. It has `target`, optional top-level `paths`, optional `sharedContext`, and one to four `tasks`.
@@ -38,3 +38,13 @@ Agent Runs share the containing process's permissions and external sandbox; cont
38
38
  A package can add a bounded same-session continuation for a required structured result. The caller supplies declarative steps through `continuation.resolveNext()`. Each step specifies a prompt, an exact active-tool set, a thinking level, and an optional pre-authorized model. The runtime performs all prompts, model switches, tool changes, usage snapshots, cancellation checks, and final disposal.
39
39
 
40
40
  Continuation can start only after Pi accepts the initial prompt. It can handle `missing-completion` and an accepted `unexpected-runner-failure`. It does not run after creation, readiness, preflight, cancellation, or timeout failures. `AgentRunSessionView` and `AgentRunHandle` remain control-free. The runtime disposes the owned session one time after the final outcome.
41
+
42
+ ## Shared `/agents` viewer
43
+
44
+ Agent and Review call `registerAgentsCommand(pi)` from the public API. The helper finds one shared registry for the containing Pi runtime through `pi.events`. Bundled runtime copies use the same registry and register one `/agents` command for that runtime. The runtime package does not register itself as a Pi extension.
45
+
46
+ The runtime owns temporary human-only transcripts for registered runs until the containing session ends. This retention is separate from Review audit settings. Agent can supply optional Profile and Profile Diagnostics pages; the runtime does not own Agent Profile policy. Steering is available only while the initial prompt is active. Stop affects only the selected run.
47
+
48
+ In Conversation or Details, Alt+Left and Alt+Right cycle through the filtered runs in the current Agents or Reviews section. The viewer keeps the current view. Esc returns to the run list.
49
+
50
+ `startRegisteredAgentRun()` returns one handle. `stop()` waits for bounded Agent Run disposal, not transcript writes. `result` resolves after final transcript writes finish. A storage failure marks the transcript incomplete and does not change the Agent Run outcome. Without a registry, the runtime does not create a transcript. A closed registry stops the run.
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mrclrchtr/supi-core",
3
- "version": "7.3.0",
3
+ "version": "7.4.0",
4
4
  "description": "Shared settings, configuration, reporting, and session infrastructure",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mrclrchtr/supi-agent-runtime",
3
- "version": "7.3.0",
3
+ "version": "7.4.0",
4
4
  "description": "SuPi Agent Run runtime — neutral lifecycle management for in-process pi sessions",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -28,11 +28,12 @@
28
28
  "!__tests__"
29
29
  ],
30
30
  "dependencies": {
31
- "@mrclrchtr/supi-core": "7.3.0"
31
+ "@mrclrchtr/supi-core": "7.4.0"
32
32
  },
33
33
  "peerDependencies": {
34
34
  "@earendil-works/pi-ai": "*",
35
- "@earendil-works/pi-coding-agent": "*"
35
+ "@earendil-works/pi-coding-agent": "*",
36
+ "@earendil-works/pi-tui": "*"
36
37
  },
37
38
  "peerDependenciesMeta": {
38
39
  "@earendil-works/pi-ai": {
@@ -40,6 +41,9 @@
40
41
  },
41
42
  "@earendil-works/pi-coding-agent": {
42
43
  "optional": true
44
+ },
45
+ "@earendil-works/pi-tui": {
46
+ "optional": true
43
47
  }
44
48
  },
45
49
  "main": "src/api.ts",
@@ -12,7 +12,28 @@ export type {
12
12
  AgentRunRequestAuth,
13
13
  } from "./provider-authority.ts";
14
14
  export { createAgentRunProviderAuthority } from "./provider-authority.ts";
15
- export { startAgentRun } from "./run.ts";
15
+ export { startAgentRun, startRegisteredAgentRun } from "./run.ts";
16
+ export { AgentRunRegistry } from "./session/agent-run-registry.ts";
17
+ export type {
18
+ AgentRunDisplayConversation,
19
+ AgentRunDisplayDetails,
20
+ AgentRunDisplayEntry,
21
+ AgentRunDisplayMetadata,
22
+ AgentRunDisplayResult,
23
+ AgentRunRegistration,
24
+ AgentRunRegistryRun,
25
+ AgentRunRegistrySnapshot,
26
+ AgentRunStopResult,
27
+ } from "./session/agent-run-registry-types.ts";
28
+ export type {
29
+ AgentRunTranscriptDocument,
30
+ AgentRunTranscriptMetadata,
31
+ AgentRunTranscriptOperation,
32
+ AgentRunTranscriptSource,
33
+ AgentRunTranscriptStatus,
34
+ AgentRunTranscriptStatusSnapshot,
35
+ } from "./session/transcript-store.ts";
36
+ export { AgentRunTranscriptCapture, AgentRunTranscriptStore } from "./session/transcript-store.ts";
16
37
  export type {
17
38
  AgentRunContinuation,
18
39
  AgentRunContinuationContext,
@@ -36,8 +57,23 @@ export type {
36
57
  AgentRunToolRenderer,
37
58
  AgentSessionInputs,
38
59
  CompletionResolver,
60
+ RegisteredAgentRunHandle,
39
61
  SafeAssistantStopReason,
40
62
  SessionReadinessCheck,
41
63
  StartAgentRunOptions,
64
+ StartRegisteredAgentRunOptions,
42
65
  } from "./types.ts";
66
+ export type { RegisterAgentsCommandOptions } from "./ui/agents-command.ts";
67
+ export {
68
+ clearAgentsProfilePages,
69
+ getAgentRunRegistry,
70
+ openAgentsViewer,
71
+ registerAgentsCommand,
72
+ } from "./ui/agents-command.ts";
73
+ export type {
74
+ AgentsProfileDiagnostic,
75
+ AgentsProfilePageEntry,
76
+ AgentsProfilePages,
77
+ AgentsProfilePagesData,
78
+ } from "./ui/agents-overlay-data.ts";
43
79
  export { combineAgentRunUsage } from "./usage.ts";
@@ -1,4 +1,5 @@
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,
@@ -29,12 +30,16 @@ import type {
29
30
  AgentRunSessionView,
30
31
  AgentRunStatus,
31
32
  AgentRunSteerResult,
33
+ RegisteredAgentRunHandle,
32
34
  StartAgentRunOptions,
35
+ StartRegisteredAgentRunOptions,
33
36
  } from "./types.ts";
34
37
  import { collectAgentRunUsage } from "./usage.ts";
35
38
 
36
39
  /** Grace period for a provider abort before disposal continues. */
37
40
  export const AGENT_RUN_ABORT_GRACE_MS = 2_000;
41
+ /** Maximum wait for initial steering to settle before recovery is skipped. */
42
+ const INITIAL_STEERING_DRAIN_GRACE_MS = 2_000;
38
43
  /** Grace period for AgentSessionRuntime disposal. */
39
44
  export const AGENT_RUN_SHUTDOWN_GRACE_MS = 2_000;
40
45
  /** Maximum turns accepted from one finite continuation policy. */
@@ -95,6 +100,7 @@ export function startAgentRun<T>(options: StartAgentRunOptions<T>): AgentRunHand
95
100
  let admissionGeneration = 0;
96
101
  let fencedSession: AgentSession | undefined;
97
102
  const extensionWork = new Set<Promise<unknown>>();
103
+ const inFlightSteering = new Set<Promise<AgentRunSteerResult>>();
98
104
  let resolveSessionSetupFinished!: () => void;
99
105
  const sessionSetupDone = new Promise<void>((resolve) => {
100
106
  resolveSessionSetupFinished = resolve;
@@ -419,6 +425,7 @@ export function startAgentRun<T>(options: StartAgentRunOptions<T>): AgentRunHand
419
425
  if (event.type !== "agent_settled" || aborting || terminal || finalizing) return;
420
426
  settledEventObserved = true;
421
427
  promptActive = false;
428
+ publish();
422
429
  };
423
430
 
424
431
  const pendingMessageCount = (activeSession: AgentSession): number | undefined => {
@@ -451,6 +458,21 @@ export function startAgentRun<T>(options: StartAgentRunOptions<T>): AgentRunHand
451
458
  }
452
459
  };
453
460
 
461
+ /** Wait briefly for initial steering before starting recovery. */
462
+ const awaitInitialSteeringDrain = async (): Promise<boolean> => {
463
+ if (inFlightSteering.size === 0) return true;
464
+ const pending = [...inFlightSteering];
465
+ let timeoutId: ReturnType<typeof setTimeout> | undefined;
466
+ const drained = await Promise.race([
467
+ Promise.allSettled(pending).then(() => true),
468
+ new Promise<boolean>((resolve) => {
469
+ timeoutId = setTimeout(() => resolve(false), INITIAL_STEERING_DRAIN_GRACE_MS);
470
+ }),
471
+ ]);
472
+ if (timeoutId !== undefined) clearTimeout(timeoutId);
473
+ return drained;
474
+ };
475
+
454
476
  const authorizedContinuationModel = (model: Model<Api>): boolean =>
455
477
  [options.inputs.model, ...(options.inputs.authorizedContinuationModels ?? [])].some(
456
478
  (candidate) => candidate.provider === model.provider && candidate.id === model.id,
@@ -586,6 +608,12 @@ export function startAgentRun<T>(options: StartAgentRunOptions<T>): AgentRunHand
586
608
  return;
587
609
  }
588
610
  continuationInitialFailure ??= initialFailureCode;
611
+ const steeringDrained = await awaitInitialSteeringDrain();
612
+ if (aborting || terminal || finalizing) return;
613
+ if (!steeringDrained) {
614
+ await finishFailed(continuationInitialFailure);
615
+ return;
616
+ }
589
617
  const maximumTurns = policy.maxTurns;
590
618
  while (continuationTurn < maximumTurns && !aborting && !terminal && !finalizing) {
591
619
  const nextTurn = continuationTurn + 1;
@@ -736,6 +764,12 @@ export function startAgentRun<T>(options: StartAgentRunOptions<T>): AgentRunHand
736
764
  timeoutId = setTimeout(requestTimeout, options.timeoutMs);
737
765
  timeoutId.unref?.();
738
766
  }
767
+ const publishPromptAcceptance = (): void => {
768
+ publish();
769
+ if (cancelRequested || aborting || terminal || finalizing) {
770
+ throw new Error("Agent Run prompt canceled before acceptance");
771
+ }
772
+ };
739
773
  const onPreflight = (accepted: boolean): void => {
740
774
  settlePromptPreflight();
741
775
  if (!accepted) {
@@ -750,6 +784,7 @@ export function startAgentRun<T>(options: StartAgentRunOptions<T>): AgentRunHand
750
784
  }
751
785
  promptAccepted = true;
752
786
  promptActive = true;
787
+ publishPromptAcceptance();
753
788
  };
754
789
  try {
755
790
  const promptPromise = session.prompt(options.prompt, { preflightResult: onPreflight });
@@ -758,6 +793,7 @@ export function startAgentRun<T>(options: StartAgentRunOptions<T>): AgentRunHand
758
793
  settlePromptPreflight();
759
794
  promptPromiseSettled = true;
760
795
  promptActive = false;
796
+ publish();
761
797
  if (promptFailureCode) startPromptFailureSettlement(promptFailureCode);
762
798
  else startPromptSettlement();
763
799
  },
@@ -765,6 +801,7 @@ export function startAgentRun<T>(options: StartAgentRunOptions<T>): AgentRunHand
765
801
  settlePromptPreflight();
766
802
  promptPromiseSettled = true;
767
803
  promptActive = false;
804
+ publish();
768
805
  promptFailureCode ??= "unexpected-runner-failure";
769
806
  startPromptFailureSettlement(promptFailureCode);
770
807
  },
@@ -773,6 +810,7 @@ export function startAgentRun<T>(options: StartAgentRunOptions<T>): AgentRunHand
773
810
  settlePromptPreflight();
774
811
  promptPromiseSettled = true;
775
812
  promptActive = false;
813
+ publish();
776
814
  promptFailureCode ??= "unexpected-runner-failure";
777
815
  startPromptFailureSettlement(promptFailureCode);
778
816
  }
@@ -904,6 +942,18 @@ export function startAgentRun<T>(options: StartAgentRunOptions<T>): AgentRunHand
904
942
  };
905
943
 
906
944
  const handle: AgentRunHandle<T> = {
945
+ get steeringAvailable() {
946
+ return (
947
+ progressState.status === "running" &&
948
+ Boolean(session) &&
949
+ promptActive &&
950
+ Boolean(session?.isStreaming) &&
951
+ !settledEventObserved &&
952
+ !terminal &&
953
+ !finalizing &&
954
+ !aborting
955
+ );
956
+ },
907
957
  result,
908
958
  subscribe(listener) {
909
959
  listeners.add(listener);
@@ -915,32 +965,34 @@ export function startAgentRun<T>(options: StartAgentRunOptions<T>): AgentRunHand
915
965
  return () => listeners.delete(listener);
916
966
  },
917
967
  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";
968
+ if (!handle.steeringAvailable || !session) return "not-running";
929
969
  const activeSession = session;
930
970
  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.
971
+ const steering = (async (): Promise<AgentRunSteerResult> => {
972
+ try {
973
+ await activeSession.steer(message);
974
+ if (
975
+ !extensionAdmissionOpen ||
976
+ admissionGeneration !== admissionAtStart ||
977
+ !handle.steeringAvailable
978
+ ) {
979
+ try {
980
+ activeSession.clearQueue();
981
+ } catch {
982
+ // Recovery waits for this write to finish before it starts.
983
+ }
984
+ return "not-running";
938
985
  }
986
+ return "accepted";
987
+ } catch {
939
988
  return "not-running";
940
989
  }
941
- return "accepted";
942
- } catch {
943
- return "not-running";
990
+ })();
991
+ inFlightSteering.add(steering);
992
+ try {
993
+ return await steering;
994
+ } finally {
995
+ inFlightSteering.delete(steering);
944
996
  }
945
997
  },
946
998
  stop: requestCancellation,
@@ -961,6 +1013,84 @@ export function startAgentRun<T>(options: StartAgentRunOptions<T>): AgentRunHand
961
1013
  return handle;
962
1014
  }
963
1015
 
1016
+ /**
1017
+ * Start an Agent Run with registry tracking and awaited transcript capture.
1018
+ *
1019
+ * `stop()` waits for bounded Agent Run disposal. It does not wait for transcript writes. `result`
1020
+ * resolves after the final transcript writes finish. A storage failure marks the transcript
1021
+ * incomplete and does not change the Agent Run outcome. Without a registry, no transcript is
1022
+ * created. A closed registry stops the Agent Run.
1023
+ */
1024
+ export function startRegisteredAgentRun<T>(
1025
+ options: StartRegisteredAgentRunOptions<T>,
1026
+ ): RegisteredAgentRunHandle<T> {
1027
+ const { registry, registration, transcriptSystemPrompt, ...runOptions } = options;
1028
+ const runKey = registration.metadata.runKey ?? randomUUID();
1029
+ const metadata = {
1030
+ ...registration.metadata,
1031
+ runKey,
1032
+ batchId: registration.metadata.batchId ?? "default",
1033
+ };
1034
+ const transcript = registry?.createTranscriptCapture(metadata, transcriptSystemPrompt ?? "");
1035
+ const observer = async (session: AgentRunSessionView): Promise<(() => void) | undefined> => {
1036
+ const detachTranscript = registry?.attachSession(runKey, session);
1037
+ try {
1038
+ const detachCallerObserver = await options.observer?.(session);
1039
+ if (!detachTranscript && typeof detachCallerObserver !== "function") return undefined;
1040
+ return () => {
1041
+ try {
1042
+ detachCallerObserver?.();
1043
+ } finally {
1044
+ detachTranscript?.();
1045
+ }
1046
+ };
1047
+ } catch (error) {
1048
+ try {
1049
+ detachTranscript?.();
1050
+ } catch {
1051
+ // Transcript observer cleanup cannot replace the caller observer error.
1052
+ }
1053
+ throw error;
1054
+ }
1055
+ };
1056
+ const handle = startAgentRun({ ...runOptions, observer });
1057
+ const result = handle.result.then(async (outcome) => {
1058
+ try {
1059
+ await transcript?.finish();
1060
+ } catch {
1061
+ // Transcript storage cannot change the Agent Run outcome.
1062
+ }
1063
+ return outcome;
1064
+ });
1065
+ const registeredHandle: RegisteredAgentRunHandle<T> = {
1066
+ runKey,
1067
+ get steeringAvailable() {
1068
+ return handle.steeringAvailable;
1069
+ },
1070
+ result,
1071
+ subscribe(listener) {
1072
+ return handle.subscribe(listener);
1073
+ },
1074
+ steer(message) {
1075
+ return handle.steer(message);
1076
+ },
1077
+ stop() {
1078
+ // Stop waits for bounded Agent Run disposal, not for transcript writes.
1079
+ return handle.stop();
1080
+ },
1081
+ };
1082
+ registry?.register({
1083
+ metadata,
1084
+ ...(transcript ? { transcript } : {}),
1085
+ handle: registeredHandle,
1086
+ ...(registration.getConversation ? { getConversation: registration.getConversation } : {}),
1087
+ ...(registration.getRecentActivity
1088
+ ? { getRecentActivity: registration.getRecentActivity }
1089
+ : {}),
1090
+ });
1091
+ return registeredHandle;
1092
+ }
1093
+
964
1094
  function usageFields(usage: Usage | undefined): { usage?: Usage } {
965
1095
  return usage ? { usage } : {};
966
1096
  }
@@ -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
+ acceptedSteering: 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";