@bastani/atomic 0.8.27 → 0.8.28-alpha.1

package/CHANGELOG.md

@@ -2,12 +2,34 @@
 
 ## [Unreleased]
 
+## [0.8.28-alpha.1] - 2026-06-09
+
+### Changed
+
+- Changed Atomic compaction to be verbatim-only across manual `/compact`, automatic threshold/overflow compaction, SDK/RPC compaction, and extension-triggered compaction. All compaction now records validated `context_compaction` deletion targets and rebuilds active context with retained transcript content verbatim and unchanged. Retained file paths, exact commands, error strings, and line numbers are never paraphrased or rewritten.
+- Changed compaction extension hooks (`session_before_compact`, `session_compact`) to receive verbatim context-compaction preparations/results and allow cancellation or locally validated deletion requests instead of custom generated summaries. The before-compact hook now yields `ContextCompactionPreparation` and accepts `{ cancel: true }` or `{ deletionRequest }` returns; the after-compact hook now receives `ContextCompactionResult` and `contextCompactionEntry`.
+- Changed the verbatim compaction critical-overflow recovery prompt to evict in an explicit priority order when context still exceeds the token budget after compaction: removable reasoning traces are evicted first, then removable user/custom/summary context. Existing safety/retention rules (recent entries, unresolved errors, failed commands, and at least one task-bearing entry) are preserved ([#1308](https://github.com/bastani-inc/atomic/issues/1308)).
+
+### Fixed
+
+- Fixed `AgentSession.prompt` surfacing the confusing `No API key found for undefined` error when a model never resolved to a real provider (for example an unknown/unresolved model id reaching the prompt path as a bare string). The prompt path now fails fast with a clear `Unknown model: "<id>" did not resolve to an available provider` message, and `No API key found` guidance no longer renders a literal `undefined` provider.
+
+### Removed
+
+- Removed the legacy summary-compaction runtime path, summary prompts, `CompactionEntry` active-context injection, `CompactionSummaryMessage` active message type, custom compaction instructions (`CompactOptions.customInstructions`, RPC `compact.customInstructions`, `/compact [instructions]`), `compaction.keepRecentTokens` setting, summary-compaction public exports (`CompactionResult`, `CompactionPreparation`, `appendCompaction()`, `prepareCompaction()`, `generateSummary()`, summary `compact()`), and summary-compaction docs and examples. Historical `type:"compaction"` JSONL lines on disk are inert and are not injected into active LLM context.
+
 ## [0.8.27] - 2026-06-08
 
 ### Fixed
 
 - Fixed `/compact` and auto-compaction regressions by removing the native `better-sqlite3` dependency from transcript-bound deletion tools and preserving the currently selected reasoning level for the compaction planner ([#1310](https://github.com/bastani-inc/atomic/issues/1310)).
 
+## [0.8.27-alpha.1] - 2026-06-08
+
+### Fixed
+
+- Fixed `/compact` and auto-compaction regressions by removing the native `better-sqlite3` dependency from transcript-bound deletion tools and preserving the currently selected reasoning level for the compaction planner ([#1310](https://github.com/bastani-inc/atomic/issues/1310)).
+
 ## [0.8.26] - 2026-06-08
 
 ### Added

package/dist/builtin/intercom/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/intercom",
-  "version": "0.8.27",
+  "version": "0.8.28-alpha.1",
   "private": true,
   "description": "Atomic extension providing a private coordination channel between parent and child agent sessions. Fork of: https://github.com/nicobailon/pi-intercom",
   "contributors": [

package/dist/builtin/mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/mcp",
-  "version": "0.8.27",
+  "version": "0.8.28-alpha.1",
   "private": true,
   "description": "Atomic extension that adapts MCP (Model Context Protocol) servers into the coding agent. Fork of: https://github.com/nicobailon/pi-mcp-adapter",
   "contributors": [
@@ -50,7 +50,7 @@
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.2",
     "@modelcontextprotocol/sdk": "^1.25.1",
-    "open": "^10.2.0",
+    "open": "^11.0.0",
     "typebox": "^1.1.24",
     "zod": "^3.25.0 || ^4.0.0"
   }

package/dist/builtin/subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/subagents",
-  "version": "0.8.27",
+  "version": "0.8.28-alpha.1",
   "private": true,
   "description": "Atomic extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification. Fork of: https://github.com/nicobailon/pi-subagents",
   "contributors": [

package/dist/builtin/web-access/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/web-access",
-  "version": "0.8.27",
+  "version": "0.8.28-alpha.1",
   "private": true,
   "description": "Atomic extension for web search, URL fetching, GitHub repo cloning, PDF/video extraction. Fork of: https://github.com/nicobailon/pi-web-access",
   "contributors": [

package/dist/builtin/workflows/CHANGELOG.md

@@ -6,6 +6,20 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.8.28-alpha.1] - 2026-06-09
+
+### Added
+
+- Added workflow `ctx.ui.custom<T>(factory, options?)` for graph-visible custom TUI human-in-the-loop prompts. Custom prompts create `awaiting_input` prompt nodes, reuse the stage UI broker/attached stage chat component path, expose the same real TUI/theme/keybinding/component types as Atomic extension custom UI, participate in live-memory prompt replay through hashed custom identities, keep labels display-only/outside replay identity, honor prompt/run abort signals, and reject clearly in headless/unavailable UI modes. Iteration 1 supports inline graph rendering; `overlay: true` and non-TUI `workflow send` answers for arbitrary custom widget results return clear unsupported errors rather than silently degrading ([#1309](https://github.com/bastani-inc/atomic/issues/1309)).
+
+### Changed
+
+- Changed workflow transcript introspection to return `sessionFile`/`transcriptPath` metadata with a lazy-read prompt by default when a transcript path exists, while keeping bounded inline previews behind explicit `tail`/`limit` requests and falling back to a small preview when no path is available ([#1314](https://github.com/bastani-inc/atomic/issues/1314)).
+
+### Fixed
+
+- Fixed a workflow kill/abort race that could crash the entire CLI with a process-level uncaught exception (for example `No API key found for ...`). When a workflow was killed mid-prompt, the executor's `raceAbort` left the already-in-flight stage prompt promise unobserved; its later rejection escaped every workflow error boundary and became an unhandled rejection. `raceAbort` now always observes the in-flight promise in the already-aborted branch so a killed run can no longer orphan a rejecting prompt.
+
 ## [0.8.27] - 2026-06-08
 
 ### Changed

package/dist/builtin/workflows/README.md

@@ -139,7 +139,9 @@ export default defineWorkflow("review-and-merge")
   .compile();
 ```
 
-Human input is runtime-only: call `ctx.ui.input`, `ctx.ui.confirm`, `ctx.ui.select`, or `ctx.ui.editor` at the point where the workflow actually needs a decision. No builder-level declaration is required or supported.
+Human input is runtime-only: call `ctx.ui.input`, `ctx.ui.confirm`, `ctx.ui.select`, `ctx.ui.editor`, or `ctx.ui.custom<T>` at the point where the workflow actually needs a decision. No builder-level declaration is required or supported.
+
+`ctx.ui.custom<T>(factory, options?)` mounts an arbitrary focused TUI component in the attached workflow graph/stage UI and resolves with the value passed to `done(value)`. The factory uses the same real TUI/theme/keybinding/component types as Atomic extension `ctx.ui.custom`. Use `options.label` for a safe display-only graph/status label and `options.replayIdentity` (do not include secrets) when the widget's semantics can change without the callsite changing; label text is not part of replay identity. Custom widget prompts require an interactive workflow graph; they are not answerable through non-TUI `workflow send` in iteration 1. Inline graph rendering is supported; `overlay: true` is rejected clearly because nested workflow graph overlays are not safely supported yet.
 
 ### Example 4 — Compose workflows
 
@@ -458,11 +460,11 @@ Tradeoff: `Type.Unsafe<T>()` does not deeply validate at runtime — it trusts t
 
 Input overrides are bare `key=value` tokens (no leading `--`). Values are JSON-parsed when possible, so numbers, booleans, and quoted strings work as expected (e.g. `count=3`, `flag=true`, `prompt="multi word value"`). A whole-object override can be passed as a single JSON token (e.g. `{"prompt":"...","count":3}`). Runtime validation is strict: unknown input keys, missing required values, type mismatches, and invalid `select` choices fail before a named workflow run starts.
 
-Workflows always run as **background tasks** in interactive sessions — the chat editor stays free while a run executes. Press **F2** (or `/workflow connect <run-id>`) to attach to the live graph viewer; HIL prompts (`ctx.ui.input/confirm/select/editor`) appear as awaiting-input graph nodes. Press Enter on the node to answer locally, never as a modal dialog over the chat. Human input is detected when those runtime `ctx.ui.*` calls execute; workflows no longer have a declaration-time HIL flag.
+Workflows always run as **background tasks** in interactive sessions — the chat editor stays free while a run executes. Press **F2** (or `/workflow connect <run-id>`) to attach to the live graph viewer; HIL prompts (`ctx.ui.input/confirm/select/editor/custom`) appear as awaiting-input graph nodes. Press Enter on the node to answer locally, never as a modal dialog over the chat. Human input is detected when those runtime `ctx.ui.*` calls execute; workflows no longer have a declaration-time HIL flag.
 
 Nested `ctx.workflow(...)` calls are displayed as an expanded graph within the top-level run. `/workflow status` and run pickers list only top-level user-launched workflows, not implementation-owned child runs. The `workflow` tool's `stages`, `stage`, `transcript`, `send`, `pause`, `interrupt`, and `resume` actions can still target visible child stage ids, prefixes, or names from the expanded graph; Atomic routes the control action to the owning nested run internally. (`stages`, `stage`, `transcript`, and `send` are `workflow` tool actions, not `/workflow` slash subcommands; the slash command exposes `connect`, `attach`, `pause`, `list`, `status`, `interrupt`, `kill`, `resume`, `reload`, and `inputs`.)
 
-Prompt answer replay is live-memory only. `StageSnapshot.promptAnswerState` reports whether continuation can replay a prompt answer (`available`), must ask again because the private ledger entry is gone (`unavailable`), or must ask again because multiple matching prompt nodes are ambiguous (`ambiguous`). Raw answers stay in a private `PromptAnswerRecord` ledger, are never serialized to snapshots or persistence, and remain resident in memory until the answer is cleared, the run is removed, or the store is cleared. Replay keys include prompt kind, message text, select choices, input/editor initial value, and hashed author callsite, so changing any of those inputs may intentionally re-ask on continuation. Empty `ctx.ui.select(..., [])` calls throw before creating a prompt node.
+Prompt answer replay is live-memory only. `StageSnapshot.promptAnswerState` reports whether continuation can replay a prompt answer (`available`), must ask again because the private ledger entry is gone (`unavailable`), or must ask again because multiple matching prompt nodes are ambiguous (`ambiguous`). Raw answers stay in a private `PromptAnswerRecord` ledger, are never serialized to snapshots or persistence, and remain resident in memory until the answer is cleared, the run is removed, or the store is cleared. Replay keys include prompt kind, message text, select choices, input/editor initial value, custom prompt identity hash, and hashed author callsite, so changing any of those inputs may intentionally re-ask on continuation. Empty `ctx.ui.select(..., [])` calls throw before creating a prompt node. Arbitrary custom-widget answers cannot be supplied with `workflow send`; focus the `custom` awaiting-input node in the interactive graph instead.
 
 ### `workflow` tool (LLM-callable)
 
@@ -471,7 +473,7 @@ Prompt answer replay is live-memory only. `StageSnapshot.promptAnswerState` repo
 ```json
 {
   "name": "workflow",
-  "description": "Run named workflows or direct one-off task/tasks/chain workflows; discover with list/get/inputs, inspect status/stages/stage details, send prompt answers or steering, pause/resume/interrupt/kill runs, and reload workflow resources. For large stage handoffs, write context to files/artifacts, pass paths via reads, and prompt downstream agents to 'Read the file at <path>...' instead of injecting large previous text. For transcripts, prefer status/stages/stage to get sessionFile/transcriptPath, quote the exact path without rewriting separators (Windows backslashes are valid), search it with rg/grep, and read small ranges; transcript defaults to at most 5 recent entries and explicit tail/limit overrides that preview.",
+  "description": "Run named workflows or direct one-off task/tasks/chain workflows; discover with list/get/inputs, inspect status/stages/stage details, send prompt answers or steering, pause/resume/interrupt/kill runs, and reload workflow resources. For large stage handoffs, write context to files/artifacts, pass paths via reads, and prompt downstream agents to 'Read the file at <path>...' instead of injecting large previous text. For transcripts, prefer status/stages/stage to get sessionFile/transcriptPath, quote the exact path without rewriting separators (Windows backslashes are valid), then search it with rg/grep and read small ranges; transcript is path-only by default when sessionFile/transcriptPath exists, explicit tail/limit returns bounded previews, and missing transcript paths fall back to a small preview.",
   "parameters": {
     "workflow": "string (optional) — workflow ID or normalized name",
     "inputs": "object (optional) — key/value map of workflow inputs",
@@ -480,9 +482,9 @@ Prompt answer replay is live-memory only. `StageSnapshot.promptAnswerState` repo
     "stageId": "optional stage id, prefix, or name for stage-scoped actions; cannot be combined with all:true",
     "statusFilter": "optional stages filter: pending/running/awaiting_input/paused/blocked/completed/failed/skipped/all",
     "format": "optional agent-facing output format: text or json",
-    "limit": "transcript-only explicit maximum number of recent entries; omitted with tail omitted uses the default 5-entry preview plus metadata/path",
+    "limit": "transcript-only explicit maximum number of recent entries; omitted with tail omitted uses the path-only default when sessionFile/transcriptPath exists",
     "tail": "transcript-only explicit last-N entry count; overrides limit for quick recent-context checks",
-    "includeToolOutput": "transcript-only flag for explicit snapshot tool-event output; prefer rg/grep on the exact quoted sessionFile/transcriptPath for large outputs",
+    "includeToolOutput": "transcript-only flag for inlined snapshot preview/fallback tool-event output; does not bypass the path-only default; prefer rg/grep on the exact quoted sessionFile/transcriptPath for large outputs",
     "text": "optional string payload for send/resume; explicit empty text answers pending prompts",
     "response": "optional structured payload for answering pending prompts; explicit empty response is valid",
     "message": "optional string payload for send/resume when text is not provided",
@@ -506,8 +508,8 @@ Prompt answer replay is live-memory only. `StageSnapshot.promptAnswerState` repo
 
 - **`renderCall`** — renders a compact workflow call summary in the chat scroll.
 - **`renderResult`** — renders the result or dispatch banner; live progress continues through the widget and graph viewer. Named workflow runs are background-oriented.
-- **`transcript`** — reference-first with a small preview by default: use `status`, `stages`, or `stage` to identify the stage and its `sessionFile`/`transcriptPath`, quote the exact path without changing platform separators (for example, preserve Windows backslashes), then search that file with `rg`/`grep` for targeted terms and read only small surrounding ranges. Text results include JSON-escaped `sessionFileJson`/`transcriptPathJson` lines for copy-safe path literals plus up to 5 recent entries by default. Passing explicit `tail` or `limit` overrides that preview for quick context checks. A registered live stage handle is used when one exists, even before live messages arrive; otherwise the action falls back to stored stage snapshots. Snapshot entries are ordered chronologically before `tail`/`limit` is applied, with terminal result/error entries kept after tool entries when timestamps are missing or tied. `includeToolOutput` applies to snapshot tool-event results; live session transcripts may not expose tool output.
-- **`send`** — answers pending stage prompts only when `text`, `response`, or `message` is present; an explicit empty string is a valid answer, while an omitted payload is a no-op. `delivery: "auto"` answers pending prompts first, then resumes paused stages, steers streaming stages, or queues a follow-up.
+- **`transcript`** — path-only by default when a transcript file exists: use `status`, `stages`, or `stage` to identify the stage and its `sessionFile`/`transcriptPath`, quote the exact path without changing platform separators (for example, preserve Windows backslashes), then search that file with `rg`/`grep` for targeted terms and read only small surrounding ranges. Default text results include JSON-escaped `sessionFileJson`/`transcriptPathJson` lines for copy-safe path literals plus a `lazyReadPrompt`, with `entries: not inlined` so transcript bodies and tool outputs stay out of model context. Passing explicit `tail` or `limit` opts into a bounded inline preview for quick context checks. If no transcript path is available, the action falls back to a bounded preview of up to 5 recent entries with a `fallbackNote`. A registered live stage handle is used when one exists, even before live messages arrive; otherwise the action falls back to stored stage snapshots. Snapshot entries are ordered chronologically before `tail`/`limit` is applied, with terminal result/error entries kept after tool entries when timestamps are missing or tied. `includeToolOutput` applies only to inlined snapshot previews or no-path fallback previews; live session transcripts may not expose tool output.
+- **`send`** — answers pending primitive/structured stage prompts only when `text`, `response`, or `message` is present; an explicit empty string is a valid answer, while an omitted payload is a no-op. Arbitrary `ctx.ui.custom<T>` widget prompts require the interactive workflow graph and return a clear unsupported message when targeted through `send`. `delivery: "auto"` answers pending prompts first, then resumes paused stages, steers streaming stages, or queues a follow-up.
 - **`reload`** — refreshes workflow resources directly in-process instead of queuing a literal `/workflow reload` chat follow-up.
 
 ### F2 keyboard shortcut
@@ -520,7 +522,7 @@ Press **F2** while a workflow is running to open the DAG overlay for the active
 
 For interactive use, run workflows through `/workflow <name> [key=value ...]` or let the LLM call the `workflow` tool. In non-interactive (`-p` / `--print` / `--mode json`) sessions, `/workflow <name> key=value` and LLM calls to the `workflow` tool remain available for deterministic workflows. The input picker and graph picker are disabled, top-level `ctx.ui.*` is unavailable, and stage child sessions exclude `ask_user_question`. Named workflow dispatch waits for the terminal run snapshot before returning.
 
-Because human input is runtime-only and workflows no longer carry a declaration-time HIL marker, headless dispatch does not reject a workflow just because its source contains `ctx.ui.*`. If you copy the HIL example above into a non-interactive session, it can pass dispatch and then fail when execution reaches the prompt with an error such as `atomic-workflows: HIL ctx.ui.confirm is unavailable because Atomic runtime did not provide a UI adapter` (the primitive name varies). Run those workflows interactively, or guard/remove runtime `ctx.ui.*` calls before using headless mode.
+Because human input is runtime-only and workflows no longer carry a declaration-time HIL marker, headless dispatch does not reject a workflow just because its source contains `ctx.ui.*`. If you copy the HIL example above into a non-interactive session, it can pass dispatch and then fail when execution reaches the prompt with an error such as `atomic-workflows: HIL ctx.ui.confirm is unavailable because Atomic runtime did not provide a UI adapter` (the primitive name varies, including `ctx.ui.custom`). Run those workflows interactively, or guard/remove runtime `ctx.ui.*` calls before using headless mode.
 
 For library or package authoring, define reusable workflows with the builder and export the compiled definition. Hand-written objects with `__piWorkflow: true` are rejected by discovery and composition; `defineWorkflow(...).compile()` is the public authoring surface. Standalone TypeScript workflow packages can import `defineWorkflow` and `Type` from `@bastani/workflows` directly with no local `.d.ts` file or `declare module` shim. The former imperative `runWorkflow` object-form API is removed; use compiled workflow definitions with the exported `run()` / registry helpers for programmatic execution.
 

package/dist/builtin/workflows/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/workflows",
-  "version": "0.8.27",
+  "version": "0.8.28-alpha.1",
   "private": true,
   "description": "Atomic extension for multi-stage workflow authoring and execution.",
   "contributors": [

package/dist/builtin/workflows/src/authoring.d.ts

@@ -57,7 +57,7 @@ export declare const Type: Omit<typeof TypeboxType, "Any" | "Array" | "BigInt" |
     Void(): TVoid;
 };
 export type { Static, TSchema } from "typebox";
-export type { AgentSessionAdapter, CompleteAdapter, CompleteStageOpts, GitWorktreeSetupOptions, GitWorktreeSetupResult, PromptAdapter, PromptOptions, ResolvedInputs, RunResult, RunStatus, StageAdapters, StageStatus, StageOptions, StageContext, StageSnapshot, StageExecutionMeta, StageMcpOptions, StageOutputOptions, StagePromptOptions, StageSessionCreateOptions, StageSessionCreateResult, StageSessionRuntime, WorkflowAction, WorkflowArtifact, WorkflowChainOptions, WorkflowChainStep, WorkflowChildResult, WorkflowContextMode, WorkflowControlEvent, WorkflowCustomToolDefinition, WorkflowDetails, WorkflowDetailsMode, WorkflowDetailsStatus, WorkflowDirectOptions, WorkflowDirectTaskItem, WorkflowExecutionMode, WorkflowExecutionPolicy, WorkflowInputBindings, WorkflowInputSchema, WorkflowInputSchemaMap, WorkflowInputValues, WorkflowIntercomSummary, WorkflowMaxOutput, WorkflowMcpPort, WorkflowModelAttempt, WorkflowModelCatalogPort, WorkflowModelFallbackFields, WorkflowModelInfo, WorkflowModelUsage, WorkflowModelValue, WorkflowOutputMode, WorkflowOutputSchema, WorkflowOutputSchemaMap, WorkflowOutputValues, WorkflowParallelChainStep, WorkflowParallelOptions, WorkflowPersistencePort, WorkflowProgressSummary, WorkflowRunChildOptions, WorkflowRunOutput, WorkflowRuntimeConfig, WorkflowSerializableObject, WorkflowSerializablePrimitive, WorkflowSerializableValue, WorkflowSharedTaskDefaults, WorkflowTaskContext, WorkflowTaskContextInput, WorkflowTaskOptions, WorkflowTaskResult, WorkflowTaskSessionFields, WorkflowTaskSessionOptions, WorkflowTaskStep, WorkflowThinkingLevel, WorkflowUIAdapter, WorkflowUIContext, WorkflowWorktreeInputBinding, } from "./shared/authoring-contract.js";
+export type { AgentSessionAdapter, CompleteAdapter, CompleteStageOpts, GitWorktreeSetupOptions, GitWorktreeSetupResult, PromptAdapter, PromptOptions, ResolvedInputs, RunResult, RunStatus, StageAdapters, StageStatus, StageOptions, StageContext, StageSnapshot, StageExecutionMeta, StageMcpOptions, StageOutputOptions, StagePromptOptions, StageSessionCreateOptions, StageSessionCreateResult, StageSessionRuntime, WorkflowAction, WorkflowArtifact, WorkflowChainOptions, WorkflowChainStep, WorkflowChildResult, WorkflowContextMode, WorkflowControlEvent, WorkflowCustomToolDefinition, WorkflowCustomUiComponent, WorkflowCustomUiFactory, WorkflowCustomUiKeybindings, WorkflowCustomUiOptions, WorkflowCustomUiOverlayHandle, WorkflowCustomUiOverlayOptions, WorkflowCustomUiTheme, WorkflowCustomUiTui, WorkflowDetails, WorkflowDetailsMode, WorkflowDetailsStatus, WorkflowDirectOptions, WorkflowDirectTaskItem, WorkflowExecutionMode, WorkflowExecutionPolicy, WorkflowInputBindings, WorkflowInputSchema, WorkflowInputSchemaMap, WorkflowInputValues, WorkflowIntercomSummary, WorkflowMaxOutput, WorkflowMcpPort, WorkflowModelAttempt, WorkflowModelCatalogPort, WorkflowModelFallbackFields, WorkflowModelInfo, WorkflowModelUsage, WorkflowModelValue, WorkflowOutputMode, WorkflowOutputSchema, WorkflowOutputSchemaMap, WorkflowOutputValues, WorkflowParallelChainStep, WorkflowParallelOptions, WorkflowPersistencePort, WorkflowProgressSummary, WorkflowRunChildOptions, WorkflowRunOutput, WorkflowRuntimeConfig, WorkflowSerializableObject, WorkflowSerializablePrimitive, WorkflowSerializableValue, WorkflowSharedTaskDefaults, WorkflowTaskContext, WorkflowTaskContextInput, WorkflowTaskOptions, WorkflowTaskResult, WorkflowTaskSessionFields, WorkflowTaskSessionOptions, WorkflowTaskStep, WorkflowThinkingLevel, WorkflowUIAdapter, WorkflowUIContext, WorkflowWorktreeInputBinding, } from "./shared/authoring-contract.js";
 import type * as AuthoringContract from "./shared/authoring-contract.js";
 import type { GitWorktreeSetupOptions, GitWorktreeSetupResult, ResolvedInputs, RunResult, RunStatus, StageSnapshot, WorkflowDefinition as WorkflowContractDefinition, WorkflowDetails, WorkflowDirectOptions, WorkflowDirectTaskItem, WorkflowExecutionPolicy, WorkflowInputValues, WorkflowOutputValues, WorkflowSerializableObject, WorkflowChainStep } from "./shared/authoring-contract.js";
 declare const workflowDefinitionBrand: unique symbol;
@@ -118,13 +118,16 @@ export interface StageNode extends WorkflowSerializableObject {
     readonly parentIds: readonly string[];
 }
 export type NoticeLevel = "info" | "warning" | "error";
-export type PromptKind = "input" | "confirm" | "select" | "editor";
+export type PromptKind = "input" | "confirm" | "select" | "editor" | "custom";
+export type CustomPromptIdentitySource = "caller" | "factory" | "callsite";
 export interface PendingPrompt extends WorkflowSerializableObject {
     readonly id: string;
     readonly kind: PromptKind;
     readonly message: string;
     readonly choices?: readonly string[];
     readonly initial?: string;
+    readonly customIdentityHash?: string;
+    readonly customIdentitySource?: CustomPromptIdentitySource;
     readonly createdAt: number;
 }
 export interface ToolEvent {

package/dist/builtin/workflows/src/extension/background-ui-adapter.ts

@@ -36,8 +36,10 @@ import type {
 } from "../shared/store-types.js";
 import type { WorkflowUIAdapter } from "../shared/types.js";
 
+type BackgroundPromptKind = Exclude<PromptKind, "custom">;
+
 interface PromptDescriptor {
-  readonly kind: PromptKind;
+  readonly kind: BackgroundPromptKind;
   readonly message: string;
   readonly choices?: readonly string[];
   readonly initial?: string;

package/dist/builtin/workflows/src/extension/hil-answer-notifications.ts

@@ -76,7 +76,6 @@ export function installWorkflowHilAnswerNotifications(
   if (typeof send !== "function") return () => undefined;
 
   const state = options.state ?? createWorkflowHilAnswerNotificationState();
-  let previousSnapshot = options.store.snapshot();
 
   const emitOnce = (details: WorkflowHilAnswerNoticeDetails): void => {
     const key = answerNoticeKey(details.runId, details.stageId, details.promptId, details.promptKind);
@@ -86,23 +85,21 @@ export function installWorkflowHilAnswerNotifications(
     sendHilAnswerNotice(send, details);
   };
 
-  const inspectSimplePromptAnswers = (snapshot: StoreSnapshot): void => {
-    for (const previousRun of previousSnapshot.runs) {
-      const currentRun = snapshot.runs.find((run) => run.id === previousRun.id);
-      if (currentRun === undefined) continue;
-
-      for (const previousStage of previousRun.stages) {
-        const answeredPrompt = simplePromptAnswer(previousStage, currentRun);
-        if (answeredPrompt === undefined) continue;
-        const answerRecord = options.store.getStagePromptAnswer(currentRun.id, answeredPrompt.stage.id);
-        if (answerRecord?.answerSource === "workflow_tool") continue;
-        emitOnce(makeSimplePromptAnswerNotice(currentRun, answeredPrompt.stage, answeredPrompt.prompt, answerRecord?.value));
+  const inspectWorkflowPromptAnswers = (snapshot: StoreSnapshot): void => {
+    for (const currentRun of snapshot.runs) {
+      for (const currentStage of currentRun.stages) {
+        const prompt = workflowPromptAnswerCandidate(currentStage);
+        if (prompt === undefined) continue;
+        const answerRecord = options.store.getStagePromptAnswer(currentRun.id, currentStage.id);
+        if (answerRecord === undefined) continue;
+        if (answerRecord.promptId !== prompt.id) continue;
+        if (answerRecord.answerSource === "workflow_tool") continue;
+        emitOnce(makeSimplePromptAnswerNotice(currentRun, currentStage, prompt, answerRecord.value, answerRecord.answeredAt));
       }
     }
-    previousSnapshot = snapshot;
   };
 
-  const unsubscribeStore = options.store.subscribe(inspectSimplePromptAnswers);
+  const unsubscribeStore = options.store.subscribe(inspectWorkflowPromptAnswers);
   const unsubscribeBroker = options.stageUiBroker?.onStagePromptResolved((event) => {
     if (event.answerSource === "workflow_tool") return;
     const answeredStage = findStageSnapshot(options.store.snapshot(), event.runId, event.stageId);
@@ -180,17 +177,11 @@ function sendHilAnswerNotice(
   }
 }
 
-function simplePromptAnswer(
-  previousStage: StageSnapshot,
-  currentRun: RunSnapshot,
-): { stage: StageSnapshot; prompt: PendingPrompt } | undefined {
-  const prompt = previousStage.pendingPrompt;
+function workflowPromptAnswerCandidate(stage: StageSnapshot): PendingPrompt | undefined {
+  const prompt = stage.promptFootprint;
   if (prompt === undefined) return undefined;
-  const currentStage = currentRun.stages.find((stage) => stage.id === previousStage.id);
-  if (currentStage === undefined) return undefined;
-  if (currentStage.pendingPrompt !== undefined) return undefined;
-  if (currentStage.promptAnswerState !== "available") return undefined;
-  return { stage: currentStage, prompt };
+  if (stage.promptAnswerState !== "available") return undefined;
+  return prompt;
 }
 
 function findStageSnapshot(
@@ -215,6 +206,7 @@ function makeSimplePromptAnswerNotice(
   stage: StageSnapshot,
   prompt: PendingPrompt,
   answer: unknown,
+  answeredAt: number,
 ): WorkflowHilAnswerNoticeDetails {
   return {
     kind: "hil_answered",
@@ -226,7 +218,7 @@ function makeSimplePromptAnswerNotice(
     promptId: prompt.id,
     promptKind: prompt.kind,
     promptMessage: truncateAnswerSnippet(prompt.message),
-    answeredAt: Date.now(),
+    answeredAt,
     answerAvailable: true,
     answerIncluded: true,
     answerSummary: formatAnswerSummary(answer),

package/dist/builtin/workflows/src/extension/index.ts

@@ -129,7 +129,7 @@ export const WORKFLOW_TOOL_DESCRIPTION =
   "For large stage handoffs, write context to files/artifacts, pass paths via reads, and prompt downstream agents to 'Read the file at <path>...' instead of injecting large previous text. " +
   "For transcripts, prefer status/stages/stage to get sessionFile/transcriptPath, " +
   "quote the exact path without rewriting separators (Windows backslashes are valid), " +
-  "search it with rg/grep, and read small ranges; transcript defaults to at most 5 recent entries and explicit tail/limit overrides that preview.";
+  "then search it with rg/grep and read small ranges; transcript is path-only by default when sessionFile/transcriptPath exists, explicit tail/limit returns bounded previews, and missing transcript paths fall back to a small preview.";
 
 // ---------------------------------------------------------------------------
 // Minimal ExtensionAPI structural types
@@ -644,8 +644,10 @@ function renderTranscriptToolContent(
   if (result.transcriptPath) lines.push(`transcriptPathJson: ${JSON.stringify(result.transcriptPath)}`);
   if (result.entryCount !== undefined) lines.push(`availableEntries: ${result.entryCount}`);
   if (result.entryLimit !== undefined) lines.push(`entryLimit: ${result.entryLimit}`);
+  if (result.lazyReadPrompt) lines.push(`lazyReadPrompt: ${result.lazyReadPrompt}`);
+  if (result.fallbackNote) lines.push(`fallbackNote: ${result.fallbackNote}`);
   if (result.entries.length === 0) {
-    lines.push("entries: none");
+    lines.push(result.inlineMode === "path_only" || result.lazyReadPrompt ? "entries: not inlined" : "entries: none");
     return lines.join("\n");
   }
   lines.push("entries:");
@@ -702,6 +704,10 @@ function renderStagesToolContent(
       lines.push("inputRequest:");
       lines.push(JSON.stringify(stage.inputRequest, null, 2));
     }
+    if (stage.promptFootprint !== undefined) {
+      lines.push("promptFootprint:");
+      lines.push(JSON.stringify(stage.promptFootprint, null, 2));
+    }
   });
   return lines.join("\n");
 }
@@ -800,6 +806,7 @@ type WorkflowStageSummary = {
   awaitingInputSince?: number;
   pendingPrompt?: StageSnapshot["pendingPrompt"];
   inputRequest?: StageSnapshot["inputRequest"];
+  promptFootprint?: StageSnapshot["promptFootprint"];
 };
 
 type WorkflowTranscriptEntry = {
@@ -842,6 +849,9 @@ function summarizeStage(stage: StageSnapshot): WorkflowStageSummary {
     inputRequest: stage.inputRequest === undefined
       ? undefined
       : structuredClone(stage.inputRequest),
+    promptFootprint: stage.promptFootprint === undefined
+      ? undefined
+      : structuredClone(stage.promptFootprint),
   };
 }
 
@@ -854,6 +864,12 @@ type TranscriptEntrySelection = {
   entryLimit?: number;
 };
 
+type WorkflowTranscriptResult = Extract<WorkflowToolResult, { action: "transcript" }>;
+
+function isTranscriptPreviewExplicit(args: WorkflowToolArgs): boolean {
+  return args.tail !== undefined || args.limit !== undefined;
+}
+
 function requestedTranscriptEntryLimit(args: WorkflowToolArgs): number {
   const raw = args.tail ?? args.limit;
   if (raw === undefined) return DEFAULT_TRANSCRIPT_LIMIT;
@@ -891,6 +907,80 @@ function selectTranscriptEntries(
   };
 }
 
+function transcriptLazyReadPrompt(path: string): string {
+  return `Transcript not inlined to protect context. Read it lazily from ${path} with your file read tools (read small ranges; rg/grep for targeted lookups).`;
+}
+
+function transcriptFallbackNote(limit: number): string {
+  return `No transcript file path is available for this stage; falling back to a bounded inline preview of up to ${limit} recent ${limit === 1 ? "entry" : "entries"}.`;
+}
+
+/**
+ * Shape a transcript tool result, keeping the context-safe path-only default
+ * the cheap hot path for the large runs #1314 protects against.
+ *
+ * `buildEntries` is a thunk so the default case (a transcript file path exists
+ * and no explicit `tail`/`limit` was requested) never materializes entry bodies
+ * just to discard them. Only the caller-provided `entryCount` is needed for the
+ * advisory count, which matches what `buildEntries()` would yield. The thunk is
+ * invoked solely for the explicit-preview and no-path fallback branches.
+ */
+function shapeTranscriptResult(input: {
+  runId: string;
+  stageId: string;
+  source: "live" | "snapshot";
+  entryCount: number;
+  buildEntries: () => readonly WorkflowTranscriptEntry[];
+  args: WorkflowToolArgs;
+  sessionId?: string | undefined;
+  sessionFile?: string | undefined;
+  transcriptPath?: string | undefined;
+}): WorkflowTranscriptResult {
+  // `transcriptPath` already falls back to `sessionFile`, so it is the single
+  // resolved path the agent should lazily read.
+  const transcriptPath = input.transcriptPath ?? input.sessionFile;
+  if (transcriptPath !== undefined && !isTranscriptPreviewExplicit(input.args)) {
+    const result: WorkflowTranscriptResult = {
+      action: "transcript",
+      runId: input.runId,
+      stageId: input.stageId,
+      source: input.source,
+      entries: [],
+      // `truncated` here means "more transcript exists on disk than was inlined"
+      // (everything, since the default inlines nothing), not "an explicit limit
+      // clipped results". It only drives the cosmetic "(truncated)" notice
+      // suffix; no consumer re-fetches on it.
+      truncated: input.entryCount > 0,
+      entryCount: input.entryCount,
+      entryLimit: 0,
+      lazyReadPrompt: transcriptLazyReadPrompt(transcriptPath),
+      inlineMode: "path_only",
+    };
+    if (input.sessionId !== undefined) result.sessionId = input.sessionId;
+    if (input.sessionFile !== undefined) result.sessionFile = input.sessionFile;
+    result.transcriptPath = transcriptPath;
+    return result;
+  }
+
+  const limited = selectTranscriptEntries(input.buildEntries(), input.args);
+  const result: WorkflowTranscriptResult = {
+    action: "transcript",
+    runId: input.runId,
+    stageId: input.stageId,
+    source: input.source,
+    entries: limited.entries,
+    truncated: limited.truncated,
+    entryCount: limited.entryCount,
+    entryLimit: limited.entryLimit,
+    inlineMode: transcriptPath === undefined ? "fallback_preview" : "preview",
+  };
+  if (input.sessionId !== undefined) result.sessionId = input.sessionId;
+  if (input.sessionFile !== undefined) result.sessionFile = input.sessionFile;
+  if (transcriptPath !== undefined) result.transcriptPath = transcriptPath;
+  if (transcriptPath === undefined) result.fallbackNote = transcriptFallbackNote(limited.entryLimit ?? DEFAULT_TRANSCRIPT_LIMIT);
+  return result;
+}
+
 function messageText(content: MessageLike["content"]): string | undefined {
   if (typeof content === "string") return content;
   if (!Array.isArray(content)) return undefined;
@@ -1463,33 +1553,40 @@ export function makeExecuteWorkflowTool(
         if (liveHandle !== undefined) {
           const sessionFile = liveHandle.sessionFile ?? snapshot?.sessionFile;
           const sessionId = liveHandle.sessionId ?? snapshot?.sessionId;
-          const limited = selectTranscriptEntries(
-            liveHandle.messages.map((m) => transcriptEntryFromMessage(m as MessageLike)),
-            args,
-          );
-          return {
-            action: "transcript",
+          return shapeTranscriptResult({
             runId: stageRunId,
             stageId: stage.stageId,
             source: "live",
-            ...limited,
+            entryCount: liveHandle.messages.length,
+            buildEntries: () =>
+              liveHandle.messages.map((m) => transcriptEntryFromMessage(m as MessageLike)),
+            args,
             sessionId,
             sessionFile,
             transcriptPath: sessionFile,
-          };
+          });
         }
-        const fallback = snapshotTranscriptEntries(snapshot, args.includeToolOutput === true);
-        const limited = selectTranscriptEntries(fallback, args);
-        return {
-          action: "transcript",
+        const snapshotSessionFile = snapshot?.sessionFile;
+        const includeSnapshotOutput = args.includeToolOutput === true && (
+          isTranscriptPreviewExplicit(args) || snapshotSessionFile === undefined
+        );
+        // Cheap count matches `snapshotTranscriptEntries(...).length` (one entry
+        // per tool event plus the optional terminal result/error entries)
+        // without building bodies for the path-only default.
+        const snapshotEntryCount = (snapshot?.toolEvents?.length ?? 0)
+          + (snapshot?.result !== undefined ? 1 : 0)
+          + (snapshot?.error !== undefined ? 1 : 0);
+        return shapeTranscriptResult({
           runId: stageRunId,
           stageId: stage.stageId,
           source: "snapshot",
-          ...limited,
+          entryCount: snapshotEntryCount,
+          buildEntries: () => snapshotTranscriptEntries(snapshot, includeSnapshotOutput),
+          args,
           sessionId: snapshot?.sessionId,
-          sessionFile: snapshot?.sessionFile,
-          transcriptPath: snapshot?.sessionFile,
-        };
+          sessionFile: snapshotSessionFile,
+          transcriptPath: snapshotSessionFile,
+        });
       }
 
       case "send": {
@@ -1543,6 +1640,24 @@ export function makeExecuteWorkflowTool(
             ok ? `Answered input request ${brokerPrompt.id}.` : `No matching pending input request ${brokerPrompt.id}.`,
           );
         }
+        const customPrompt = snapshot?.status === "awaiting_input" && snapshot.promptFootprint?.kind === "custom"
+          ? snapshot.promptFootprint
+          : undefined;
+        const targetsCustomPrompt =
+          customPrompt !== undefined &&
+          (args.promptId === undefined || args.promptId === customPrompt.id) &&
+          (requestedDelivery === "answer" ||
+            args.promptId !== undefined ||
+            requestedDelivery === "auto");
+        if (targetsCustomPrompt && customPrompt !== undefined) {
+          return workflowSendResult(
+            stageRunId,
+            stage.stageId,
+            "answer",
+            "noop",
+            `Custom UI prompt ${customPrompt.id} requires the interactive workflow graph; arbitrary ctx.ui.custom<T> results cannot be answered through workflow send.`,
+          );
+        }
         const targetsPrompt =
           requestedDelivery === "answer" ||
           args.promptId !== undefined ||

package/dist/builtin/workflows/src/extension/render-result.ts

@@ -110,11 +110,13 @@ type StageListItem = {
   awaitingInputSince?: number;
   pendingPrompt?: PendingPrompt;
   inputRequest?: StageInputRequest;
+  promptFootprint?: PendingPrompt;
 };
 type StageListResult = { action: "stages"; runId: string; filter: string; stages: StageListItem[]; error?: string };
 type StageDetailItem = StageSnapshot & { transcriptPath?: string };
 type StageDetailResult = { action: "stage"; runId: string; stage?: StageDetailItem; error?: string };
 type TranscriptEntry = { role: string; text?: string; toolName?: string; output?: string; timestamp?: number };
+type TranscriptInlineMode = "path_only" | "preview" | "fallback_preview";
 type TranscriptResult = {
   action: "transcript";
   runId: string;
@@ -127,6 +129,9 @@ type TranscriptResult = {
   sessionId?: string;
   sessionFile?: string;
   transcriptPath?: string;
+  lazyReadPrompt?: string;
+  fallbackNote?: string;
+  inlineMode?: TranscriptInlineMode;
 };
 type SendResult = { action: "send"; runId: string; stageId: string; delivery: string; status: "ok" | "noop"; message: string };
 type PauseResult = { action: "pause"; runId: string; status: string; message: string };
@@ -213,7 +218,7 @@ function renderNotice(
 const TRANSCRIPT_NOTICE_ENTRY_LIMIT = 5;
 const TRANSCRIPT_NOTICE_CHAR_LIMIT = 240;
 
-function transcriptNoticeText(entries: readonly TranscriptEntry[]): string {
+function transcriptEntriesNoticeText(entries: readonly TranscriptEntry[]): string {
   if (entries.length === 0) return "no transcript entries";
   const shown = entries.slice(0, TRANSCRIPT_NOTICE_ENTRY_LIMIT);
   const text = shown
@@ -225,6 +230,21 @@ function transcriptNoticeText(entries: readonly TranscriptEntry[]): string {
   return fitLine(`${text}${entrySuffix}`, TRANSCRIPT_NOTICE_CHAR_LIMIT);
 }
 
+function transcriptNoticeText(result: TranscriptResult): string {
+  if ((result.inlineMode === "path_only" || result.lazyReadPrompt !== undefined) && result.entries.length === 0) {
+    const path = result.transcriptPath ?? result.sessionFile ?? "transcript file";
+    const count = result.entryCount === undefined
+      ? ""
+      : ` (${result.entryCount} ${result.entryCount === 1 ? "entry" : "entries"})`;
+    return fitLine(`not inlined; read ${path}${count}`, TRANSCRIPT_NOTICE_CHAR_LIMIT);
+  }
+  const entriesText = transcriptEntriesNoticeText(result.entries);
+  if (result.inlineMode === "fallback_preview" || result.fallbackNote !== undefined) {
+    return fitLine(`no session file; preview: ${entriesText}`, TRANSCRIPT_NOTICE_CHAR_LIMIT);
+  }
+  return entriesText;
+}
+
 export function renderResult(result: WorkflowToolResult, opts?: RenderResultOpts): string {
   const partial = opts?.isPartial === true;
   const themed = opts?.plain !== true;
@@ -350,7 +370,7 @@ export function renderResult(result: WorkflowToolResult, opts?: RenderResultOpts
 
     case "transcript": {
       const r = result as TranscriptResult;
-      const text = transcriptNoticeText(r.entries);
+      const text = transcriptNoticeText(r);
       const suffix = r.truncated ? " (truncated)" : "";
       return renderNotice("WORKFLOW TRANSCRIPT", `${r.runId}/${r.stageId.slice(0, 12)} ${r.source}: ${text}${suffix}`, opts, themed);
     }