strands-darwin 0.0.32 → 0.0.34

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 (117) hide show
  1. package/README.md +3 -1
  2. package/README.zh-CN.md +3 -1
  3. package/dist/src/agent/background-delegation.d.ts +69 -11
  4. package/dist/src/agent/background-delegation.js +156 -28
  5. package/dist/src/agent/background-delegation.js.map +1 -1
  6. package/dist/src/agent/cache-miss.d.ts +143 -0
  7. package/dist/src/agent/cache-miss.js +182 -0
  8. package/dist/src/agent/cache-miss.js.map +1 -0
  9. package/dist/src/agent/compact.d.ts +28 -0
  10. package/dist/src/agent/compact.js +34 -0
  11. package/dist/src/agent/compact.js.map +1 -1
  12. package/dist/src/agent/context-breakdown.d.ts +109 -0
  13. package/dist/src/agent/context-breakdown.js +116 -0
  14. package/dist/src/agent/context-breakdown.js.map +1 -0
  15. package/dist/src/agent/instructions.d.ts +1 -1
  16. package/dist/src/agent/instructions.js.map +1 -1
  17. package/dist/src/agent/permission-rules.d.ts +81 -2
  18. package/dist/src/agent/permission-rules.js +226 -6
  19. package/dist/src/agent/permission-rules.js.map +1 -1
  20. package/dist/src/agent/permission.d.ts +116 -2
  21. package/dist/src/agent/permission.js +201 -26
  22. package/dist/src/agent/permission.js.map +1 -1
  23. package/dist/src/agent/prompt-cache.d.ts +12 -3
  24. package/dist/src/agent/prompt-cache.js +12 -3
  25. package/dist/src/agent/prompt-cache.js.map +1 -1
  26. package/dist/src/agent/runtime.d.ts +141 -1
  27. package/dist/src/agent/runtime.js +259 -13
  28. package/dist/src/agent/runtime.js.map +1 -1
  29. package/dist/src/agent/task-terminal-delivery.d.ts +43 -0
  30. package/dist/src/agent/task-terminal-delivery.js +115 -0
  31. package/dist/src/agent/task-terminal-delivery.js.map +1 -0
  32. package/dist/src/agents/child-recipe.d.ts +9 -1
  33. package/dist/src/agents/child-recipe.js +2 -0
  34. package/dist/src/agents/child-recipe.js.map +1 -1
  35. package/dist/src/agents/dispatch-registry.d.ts +18 -0
  36. package/dist/src/agents/dispatch-registry.js +2 -0
  37. package/dist/src/agents/dispatch-registry.js.map +1 -1
  38. package/dist/src/agents/retained-children.d.ts +101 -0
  39. package/dist/src/agents/retained-children.js +101 -0
  40. package/dist/src/agents/retained-children.js.map +1 -0
  41. package/dist/src/agents/subagent-tool.d.ts +56 -1
  42. package/dist/src/agents/subagent-tool.js +148 -10
  43. package/dist/src/agents/subagent-tool.js.map +1 -1
  44. package/dist/src/agents/workflow-tool.d.ts +2 -0
  45. package/dist/src/agents/workflow-tool.js +1 -1
  46. package/dist/src/agents/workflow-tool.js.map +1 -1
  47. package/dist/src/cli-doctor.js +3 -1
  48. package/dist/src/cli-doctor.js.map +1 -1
  49. package/dist/src/cli-main.js +14 -3
  50. package/dist/src/cli-main.js.map +1 -1
  51. package/dist/src/commands/custom-commands.js +5 -4
  52. package/dist/src/commands/custom-commands.js.map +1 -1
  53. package/dist/src/config.d.ts +57 -6
  54. package/dist/src/config.js +43 -16
  55. package/dist/src/config.js.map +1 -1
  56. package/dist/src/headless-protocol.d.ts +1 -1
  57. package/dist/src/headless-runner.js +7 -2
  58. package/dist/src/headless-runner.js.map +1 -1
  59. package/dist/src/hooks/tool-hooks.js +10 -6
  60. package/dist/src/hooks/tool-hooks.js.map +1 -1
  61. package/dist/src/skills/builtin/self-evolution-research/SKILL.md +14 -1
  62. package/dist/src/skills/prompt.d.ts +17 -0
  63. package/dist/src/skills/prompt.js +20 -0
  64. package/dist/src/skills/prompt.js.map +1 -1
  65. package/dist/src/tools/background-bash.d.ts +11 -2
  66. package/dist/src/tools/background-bash.js +11 -5
  67. package/dist/src/tools/background-bash.js.map +1 -1
  68. package/dist/src/tools/background-tail.d.ts +1 -0
  69. package/dist/src/tools/background-tail.js +2 -1
  70. package/dist/src/tools/background-tail.js.map +1 -1
  71. package/dist/src/tools/background-wait-contract.d.ts +7 -0
  72. package/dist/src/tools/background-wait-contract.js +17 -0
  73. package/dist/src/tools/background-wait-contract.js.map +1 -1
  74. package/dist/src/trajectory/record.d.ts +212 -2
  75. package/dist/src/trajectory/record.js +138 -0
  76. package/dist/src/trajectory/record.js.map +1 -1
  77. package/dist/src/trajectory/replay.d.ts +34 -1
  78. package/dist/src/trajectory/replay.js +148 -4
  79. package/dist/src/trajectory/replay.js.map +1 -1
  80. package/dist/src/trajectory/resume-recap.js +10 -3
  81. package/dist/src/trajectory/resume-recap.js.map +1 -1
  82. package/dist/src/trajectory/spend.d.ts +14 -1
  83. package/dist/src/trajectory/spend.js +40 -6
  84. package/dist/src/trajectory/spend.js.map +1 -1
  85. package/dist/src/trajectory/writer.d.ts +57 -6
  86. package/dist/src/trajectory/writer.js +141 -9
  87. package/dist/src/trajectory/writer.js.map +1 -1
  88. package/dist/src/tui/App.d.ts +8 -4
  89. package/dist/src/tui/App.js +302 -55
  90. package/dist/src/tui/App.js.map +1 -1
  91. package/dist/src/tui/background-tool-presentation.js +2 -2
  92. package/dist/src/tui/background-tool-presentation.js.map +1 -1
  93. package/dist/src/tui/context-format.d.ts +16 -0
  94. package/dist/src/tui/context-format.js +41 -0
  95. package/dist/src/tui/context-format.js.map +1 -1
  96. package/dist/src/tui/prompt-queue.d.ts +52 -8
  97. package/dist/src/tui/prompt-queue.js +68 -8
  98. package/dist/src/tui/prompt-queue.js.map +1 -1
  99. package/dist/src/tui/status-format.d.ts +35 -16
  100. package/dist/src/tui/status-format.js +67 -8
  101. package/dist/src/tui/status-format.js.map +1 -1
  102. package/dist/src/tui/subagent-format.d.ts +8 -0
  103. package/dist/src/tui/subagent-format.js +24 -1
  104. package/dist/src/tui/subagent-format.js.map +1 -1
  105. package/dist/src/tui/task-wake.d.ts +75 -0
  106. package/dist/src/tui/task-wake.js +201 -0
  107. package/dist/src/tui/task-wake.js.map +1 -0
  108. package/dist/src/tui/terminal-notify.d.ts +40 -0
  109. package/dist/src/tui/terminal-notify.js +136 -0
  110. package/dist/src/tui/terminal-notify.js.map +1 -0
  111. package/dist/src/tui/terminal-title.d.ts +94 -0
  112. package/dist/src/tui/terminal-title.js +121 -0
  113. package/dist/src/tui/terminal-title.js.map +1 -0
  114. package/dist/src/tui/turn-state.d.ts +10 -1
  115. package/dist/src/tui/turn-state.js +17 -1
  116. package/dist/src/tui/turn-state.js.map +1 -1
  117. package/package.json +1 -1
@@ -0,0 +1,201 @@
1
+ /**
2
+ * Background-task wakes (SER-069): the pure projections behind "a finished
3
+ * `bash start` job wakes the agent".
4
+ *
5
+ * When a background job reaches a terminal state, the manager publishes exactly
6
+ * one immutable snapshot. Today's transcript notice tells the *user*; this module
7
+ * composes the one bounded, session-originated prompt that tells the *model* —
8
+ * delivered through the ordinary prompt queue as a distinct entry kind, drained at
9
+ * idle through `submit()`, so it is one ordinary turn (hooks, permission gate,
10
+ * trajectory barrier, `TurnComplete`) and never a mid-stream injection.
11
+ *
12
+ * Nothing here is I/O and nothing here decides *when* a wake is sent — the App
13
+ * owns the queue state machine and the runtime owns the "already delivered via
14
+ * `wait`/`status`" ledger. This module owns:
15
+ *
16
+ * - the model-facing text (`formatTaskNotification`): task id, command, state,
17
+ * exit code/signal, elapsed time and an output tail, bounded well under the
18
+ * trajectory record's field cap, in a vocabulary the model can act on;
19
+ * - the structured fields the record, the transcript row and the queue row are
20
+ * composed from (`taskNotificationFields`);
21
+ * - the one-row projections (`taskWakeQueueTag`, `formatTaskWakeNotice`) the
22
+ * queue listing and the `<Static>` transcript print, distinct from user text.
23
+ */
24
+ import { BACKGROUND_EXECUTION_FLAG, BACKGROUND_TASK_RESULT_TOOL_NAME, shortBackgroundTaskId, } from '../agent/background-delegation.js';
25
+ import { formatTaskDuration, formatTaskId, summarizeTaskCommand, taskElapsedMs } from './task-format.js';
26
+ /** Element name of the model-facing block; also the queue-entry `kind`'s vocabulary. */
27
+ export const TASK_NOTIFICATION_TAG = 'task-notification';
28
+ /** Output lines read from the end of the job's log for the wake; the model can read more with `bash output`. */
29
+ export const TASK_WAKE_TAIL_LINES = 20;
30
+ /** Per-line cap inside the wake body, by code point. */
31
+ export const TASK_WAKE_TAIL_LINE_CODE_POINTS = 400;
32
+ /** Whole-tail cap inside the wake body, by code point. */
33
+ export const TASK_WAKE_TAIL_CODE_POINTS = 2_000;
34
+ /** The command as the model sees it in the body, by code point (the notice row uses the shorter label). */
35
+ export const TASK_WAKE_COMMAND_CODE_POINTS = 400;
36
+ /** The identifying fields of one terminal snapshot; `running` is never a wake. */
37
+ export function taskNotificationFields(task) {
38
+ if (task.state === 'running')
39
+ return undefined;
40
+ return {
41
+ taskId: task.taskId,
42
+ command: task.command,
43
+ state: task.state,
44
+ exitCode: task.exitCode,
45
+ signal: task.signal,
46
+ };
47
+ }
48
+ /** End-first truncation by code point; never splits a code point. */
49
+ function capCodePoints(text, limit) {
50
+ const points = [...text];
51
+ if (points.length <= limit)
52
+ return text;
53
+ return `${points.slice(0, Math.max(0, limit - 1)).join('')}…`;
54
+ }
55
+ /**
56
+ * Body text may not close the element early: a job whose output prints the closing
57
+ * tag gets one backslash inside it, the same neutralisation the subagent report
58
+ * projection applies to framing imitation, never a removal.
59
+ */
60
+ function neutraliseClosingTag(text) {
61
+ return text.replace(new RegExp(`</${TASK_NOTIFICATION_TAG}`, 'gi'), `<\\/${TASK_NOTIFICATION_TAG}`);
62
+ }
63
+ function tailLines(tail) {
64
+ if (tail === undefined || tail.kind === 'unavailable')
65
+ return ['(output unavailable)'];
66
+ if (tail.kind === 'empty')
67
+ return ['(no output)'];
68
+ const lines = [];
69
+ let spent = 0;
70
+ // Newest lines are the ones that explain a failure; keep from the end.
71
+ for (let index = tail.lines.length - 1; index >= 0; index -= 1) {
72
+ const line = capCodePoints(tail.lines[index], TASK_WAKE_TAIL_LINE_CODE_POINTS);
73
+ const cost = [...line].length + 1;
74
+ if (spent + cost > TASK_WAKE_TAIL_CODE_POINTS)
75
+ break;
76
+ spent += cost;
77
+ lines.unshift(line);
78
+ }
79
+ const omitted = tail.lines.length - lines.length;
80
+ return omitted > 0 ? [`… ${omitted} earlier line(s) omitted`, ...lines] : lines;
81
+ }
82
+ /**
83
+ * The model-facing text of one wake. Every attribute value is manager-owned and
84
+ * character-safe (validated id, fixed state names, numbers, signal names); the
85
+ * command and output ride in the body, bounded and unable to close the element.
86
+ */
87
+ export function formatTaskNotification(task, tail, nowMs = Date.now()) {
88
+ const fields = taskNotificationFields(task) ?? {
89
+ taskId: task.taskId, command: task.command, state: 'failed', exitCode: task.exitCode, signal: task.signal,
90
+ };
91
+ const attributes = [
92
+ `task="${fields.taskId}"`,
93
+ `state="${fields.state}"`,
94
+ `exitCode="${fields.exitCode === null ? '' : fields.exitCode}"`,
95
+ `signal="${fields.signal ?? ''}"`,
96
+ `elapsed="${formatTaskDuration(taskElapsedMs(task, nowMs))}"`,
97
+ ].join(' ');
98
+ const outcome = fields.state === 'succeeded'
99
+ ? 'finished successfully'
100
+ : fields.state === 'stopped'
101
+ ? 'was stopped'
102
+ : `failed${fields.exitCode === null ? '' : ` with exit code ${fields.exitCode}`}${fields.signal === null ? '' : ` (signal ${fields.signal})`}`;
103
+ const lines = tailLines(tail);
104
+ const body = [
105
+ `A background bash job you started with \`bash start\` ${outcome}. This turn was started by that completion, not by the user.`,
106
+ `command: ${capCodePoints(fields.command.replace(/\s*\n\s*/g, ' '), TASK_WAKE_COMMAND_CODE_POINTS)}`,
107
+ `output tail (last ${lines.length} line(s); \`bash output\` with taskId "${fields.taskId}" reads the full log from your cursor):`,
108
+ ...lines,
109
+ 'If work you planned depends on this result, continue it now; otherwise reply briefly with what the result means.',
110
+ ].join('\n');
111
+ return `<${TASK_NOTIFICATION_TAG} ${attributes}>\n${neutraliseClosingTag(body)}\n</${TASK_NOTIFICATION_TAG}>`;
112
+ }
113
+ /** Exit metadata as the rows print it: `exit 1`, `signal SIGTERM`, or nothing for a clean success. */
114
+ function outcomeDetail(fields) {
115
+ const parts = [
116
+ fields.exitCode === null || (fields.state === 'succeeded' && fields.exitCode === 0)
117
+ ? undefined
118
+ : `exit ${fields.exitCode}`,
119
+ fields.signal === null ? undefined : `signal ${fields.signal}`,
120
+ ].filter((value) => value !== undefined);
121
+ return parts.length === 0 ? '' : ` (${parts.join(', ')})`;
122
+ }
123
+ /** The id as the rows print it: `bg-1a2b3c4d` for a job, the first eight UUID characters for a delegation. */
124
+ function rowTaskId(fields) {
125
+ return fields.source === 'delegation' ? shortBackgroundTaskId(fields.taskId) : formatTaskId(fields.taskId);
126
+ }
127
+ /**
128
+ * The identifying fields of one settled background delegation (SER-070): the
129
+ * delegation label the transcript row carries stands where a job's command would,
130
+ * so the queue row, the notice and the record read the same way for both sources.
131
+ * `running` is never a wake.
132
+ */
133
+ export function delegationNotificationFields(delegation, label) {
134
+ if (delegation.state === 'running')
135
+ return undefined;
136
+ return {
137
+ source: 'delegation',
138
+ taskId: delegation.taskId,
139
+ command: label,
140
+ state: delegation.state,
141
+ exitCode: null,
142
+ signal: null,
143
+ };
144
+ }
145
+ /**
146
+ * The model-facing text of one delegation wake. Deliberately **not** the report: the
147
+ * SDK's own `_deliverReady` attaches the `strands_background_task_result` pair to
148
+ * this very turn's request, so the block only says which delegation ended, how, and
149
+ * where to read the result — a second copy would double the report in context and
150
+ * make two sources of one truth.
151
+ */
152
+ export function formatDelegationNotification(delegation, label, nowMs = Date.now()) {
153
+ const fields = delegationNotificationFields(delegation, label) ?? {
154
+ taskId: delegation.taskId, command: label, state: 'failed', exitCode: null, signal: null,
155
+ };
156
+ const started = Date.parse(delegation.startedAt);
157
+ const settled = delegation.settledAt === null ? nowMs : Date.parse(delegation.settledAt);
158
+ const elapsedMs = Number.isFinite(started) && Number.isFinite(settled) ? Math.max(0, settled - started) : 0;
159
+ const attributes = [
160
+ `task="${fields.taskId}"`,
161
+ `tool="${delegation.toolName}"`,
162
+ `state="${fields.state}"`,
163
+ `elapsed="${formatTaskDuration(elapsedMs)}"`,
164
+ ].join(' ');
165
+ const body = [
166
+ `A background ${delegation.toolName} delegation you dispatched with ${BACKGROUND_EXECUTION_FLAG}: true ` +
167
+ `${fields.state === 'succeeded' ? 'finished' : 'failed'}. This turn was started by that settlement, not by the user.`,
168
+ `delegation: ${capCodePoints(fields.command.replace(/\s*\n\s*/g, ' '), TASK_WAKE_COMMAND_CODE_POINTS)}`,
169
+ `Its report is in this turn's ${BACKGROUND_TASK_RESULT_TOOL_NAME} tool result for task "${fields.taskId}" — read it there; it is not repeated here.`,
170
+ 'If work you planned depends on this result, continue it now; otherwise reply briefly with what the result means.',
171
+ ].join('\n');
172
+ return `<${TASK_NOTIFICATION_TAG} ${attributes}>\n${neutraliseClosingTag(body)}\n</${TASK_NOTIFICATION_TAG}>`;
173
+ }
174
+ /**
175
+ * The bracketed tag a queued wake row carries after the `queued ·` marker, in the
176
+ * `[image]` attachment's vocabulary: `[task bg-1a2b3c4d succeeded]`, or
177
+ * `[delegation 1a2b3c4d succeeded]` for a background `subagent`/`workflow`. A user
178
+ * cannot type it into the queue — user rows never start with `[task ` or `[delegation `.
179
+ */
180
+ export function taskWakeQueueTag(fields) {
181
+ return `[${fields.source === 'delegation' ? 'delegation' : 'task'} ${rowTaskId(fields)} ${fields.state}]`;
182
+ }
183
+ /**
184
+ * The transcript row written when a wake is actually sent — composed from the
185
+ * recorded fields only, so a replayed `taskNotification` record prints the same
186
+ * row. Deliberately a notice and not a `you>` row: the user typed nothing.
187
+ */
188
+ export function formatTaskWakeNotice(fields) {
189
+ if (fields.source === 'delegation') {
190
+ return `delegation wake · ${rowTaskId(fields)} ${fields.state} — ${summarizeTaskCommand(fields.command)} → sent to the model as this turn; the report arrives with it`;
191
+ }
192
+ return `task wake · ${formatTaskId(fields.taskId)} ${fields.state}${outcomeDetail(fields)} — ${summarizeTaskCommand(fields.command)} → sent to the model as this turn`;
193
+ }
194
+ /** The notice a wake that could not be delivered leaves behind (its turn was cancelled or failed). */
195
+ export function formatTaskWakeUndelivered(fields) {
196
+ if (fields.source === 'delegation') {
197
+ return `delegation wake · ${rowTaskId(fields)} not delivered — its turn was cancelled or failed and is not re-sent; the SDK still holds the report and attaches it to the next turn that runs`;
198
+ }
199
+ return `task wake · ${formatTaskId(fields.taskId)} not delivered — its turn was cancelled or failed and is not re-sent; the job's output is still readable via /tasks or bash output`;
200
+ }
201
+ //# sourceMappingURL=task-wake.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"task-wake.js","sourceRoot":"","sources":["../../../src/tui/task-wake.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,40 @@
1
+ /** ST — the string terminator. Never BEL here (see the header). */
2
+ export declare const TERMINAL_NOTIFY_ST = "\u001B\\";
3
+ /** Whole-text cap in code points, `…` included. */
4
+ export declare const MAX_TERMINAL_NOTIFY_CODE_POINTS = 120;
5
+ export type TerminalNotifyMoment = 'permission' | 'turn-complete';
6
+ /** Fixed bodies; `waiting for approval` is the terminal title's state word. */
7
+ export declare const TERMINAL_NOTIFY_BODY: Readonly<Record<TerminalNotifyMoment, string>>;
8
+ export interface TerminalNotifyInput {
9
+ readonly projectBasename: string;
10
+ readonly moment: TerminalNotifyMoment;
11
+ }
12
+ /**
13
+ * Removes every control character (C0, DEL, C1) and every `;`: ESC/BEL/ST would end
14
+ * or restart a sequence, and `;` is the OSC field separator.
15
+ */
16
+ export declare function sanitizeNotifyText(text: string): string;
17
+ /** `darwin · <project>` — the terminal title's own head; an empty project drops its segment. */
18
+ export declare function terminalNotifyTitle(projectBasename: string): string;
19
+ /** `darwin · <project> · <body>`, sanitized and bounded. */
20
+ export declare function formatTerminalNotification(input: TerminalNotifyInput): string;
21
+ /** `ESC ] 9 ; <text> ESC \` — OSC 9, ST-terminated. The text is sanitized again at the seam. */
22
+ export declare function terminalNotifySequence(text: string): string;
23
+ /** tmux(1) passthrough: `ESC P tmux ; <sequence, ESC doubled> ESC \`. */
24
+ export declare function wrapForTmuxPassthrough(sequence: string): string;
25
+ /** tmux exports `TMUX` into every pane; screen and a bare terminal do not set it. */
26
+ export declare function isInsideTmux(env?: NodeJS.ProcessEnv): boolean;
27
+ export interface TerminalNotifySeam {
28
+ /** `process.stdout.isTTY` in production; a pipe or file gets no sequence at all. */
29
+ readonly isTTY?: boolean;
30
+ /** Whether to wrap for tmux; production reads `TMUX` from the environment. */
31
+ readonly insideTmux?: boolean;
32
+ /** Test seam; production writes to the real stdout, never through Ink's frame path. */
33
+ readonly write?: (chunk: string) => void;
34
+ }
35
+ /**
36
+ * Writes exactly one sequence (one `write` call) when `enabled` and stdout is a
37
+ * TTY, nothing otherwise. `enabled` is the config key at call time
38
+ * (`terminalNotify`); off writes nothing and allocates nothing.
39
+ */
40
+ export declare function notifyTerminal(enabled: boolean, input: TerminalNotifyInput, seam?: TerminalNotifySeam): void;
@@ -0,0 +1,136 @@
1
+ /**
2
+ * Config-gated terminal-mediated attention notification for the interactive TUI
3
+ * driver (SER-078).
4
+ *
5
+ * One OSC notification sequence goes straight to the process's real stdout at the
6
+ * two driver-owned moments the bell already uses (`terminal-bell.ts`): a permission
7
+ * prompt being published to the screen, and a turn completing. The terminal — not
8
+ * darwin — decides whether to show a desktop toast, so there is no platform API, no
9
+ * dependency and no focus detection; the sequence reaches the local machine over
10
+ * SSH because it travels in the byte stream. Like BEL and the OSC 2 title it is a
11
+ * non-printing control sequence, never an Ink row: the frame budget, ANSI-stripped
12
+ * pty assertions, `/export` byte-stability and replay are untouched. Deliberately
13
+ * not wired anywhere else: never per frame render, never in the headless drivers
14
+ * (`-p`/structured), never for child agents, never inside lifecycle hook command
15
+ * execution. Disabled (the default) performs no write at all, so the off path stays
16
+ * byte-identical to before the feature existed.
17
+ *
18
+ * ## Sequence decision: exactly one OSC 9, ST-terminated
19
+ *
20
+ * `ESC ] 9 ; darwin · <project> · <body> ESC \` — iTerm2's "Post a notification".
21
+ * Documented by every terminal known to show it: iTerm2
22
+ * (https://iterm2.com/documentation-escape-codes.html, "Post a notification:
23
+ * `OSC 9 ; [Message content goes here] ST`"), kitty
24
+ * (https://sw.kovidgoyal.net/kitty/desktop-notifications/, "kitty also supports the
25
+ * legacy OSC 9 protocol developed by iTerm2"), Ghostty
26
+ * (https://ghostty.org/docs/vt/osc/9, "Show a desktop notification with title `t`"),
27
+ * WezTerm (https://wezterm.org/escape-sequences.html, OSC 9 "iTerm2 Show System
28
+ * Notification", `printf "\e]9;%s\e\\"`) and foot (`foot-ctlseqs(7)`, `\E] 9 ; msg
29
+ * \E\\` — "iTerm2, Desktop notification").
30
+ *
31
+ * Terminals that reuse OSC 9 for ConEmu's numbered sub-commands (`9;4` progress and
32
+ * friends) ignore a payload whose first `;`-field is not a number — which ours never
33
+ * is, it starts with `darwin`: Windows Terminal's `AdaptDispatch::DoConEmuAction`
34
+ * (src/terminal/adapter/adaptDispatch.cpp) returns before acting when
35
+ * `StringToUint(parts[0])` fails; ConEmu's `CEAnsi::WriteAnsiCode_OSC`
36
+ * (src/ConEmuHk/Ansi.cpp, `case L'9'`) only matches digit sub-IDs at `ArgSZ[2]` and
37
+ * otherwise falls to `break`; tmux's `input_osc_9` (input.c) returns unless the
38
+ * payload begins with `4`. Ghostty documents the same rule from the other side: the
39
+ * text "should not begin with a number and then a semicolon". Every other terminal
40
+ * treats an unrecognized OSC the way ECMA-48's string state requires — consume to
41
+ * ST, dispatch nothing (tmux `input_exit_osc` `default:` logs "unknown" and does
42
+ * nothing more).
43
+ *
44
+ * The terminator is ST (`ESC \`), never BEL, so the sequence cannot be mistaken for
45
+ * the bell (`verify-terminal-bell.ts` counts BELs outside OSC payloads, and this
46
+ * module must add none). OSC 777 (`ESC ] 777 ; notify ; title ; body ST`, the rxvt
47
+ * extension) was considered and omitted: every documented implementer but
48
+ * rxvt-unicode — WezTerm, Ghostty, foot — also implements OSC 9, so emitting both
49
+ * would show two toasts on exactly the terminals this is for. kitty's OSC 99 is
50
+ * omitted for the same reason (kitty and foot accept OSC 9).
51
+ *
52
+ * ## tmux
53
+ *
54
+ * tmux consumes OSC strings itself (its OSC 9 handler is the progress bar, and the
55
+ * outer terminal never sees the bytes), so inside tmux — `TMUX` set in the
56
+ * environment — the sequence is wrapped in tmux's documented passthrough DCS,
57
+ * `ESC P tmux ; <sequence with every ESC doubled> ESC \` (tmux(1) `allow-passthrough`:
58
+ * "Allow programs in the pane to bypass tmux using a terminal escape sequence
59
+ * (\ePtmux;...\e\\)"; the DCS state machine folds `ESC ESC` back to one ESC). The
60
+ * user must set `allow-passthrough on`; with it off, tmux discards the DCS and
61
+ * nothing reaches the outer terminal — still harmless.
62
+ *
63
+ * ## Payload hygiene
64
+ *
65
+ * The text is an escape-sequence payload and the project basename is user data:
66
+ * every control character (C0, DEL, C1 — covering ESC, BEL, CR/LF, and the C1 ST)
67
+ * and every `;` (the OSC field separator, and the byte that would let a name such
68
+ * as `4;1;50` masquerade as a ConEmu sub-command) is stripped before embedding, and
69
+ * the whole text is bounded at {@link MAX_TERMINAL_NOTIFY_CODE_POINTS}, end-first
70
+ * with `…`. Title vocabulary is the terminal title's (`darwin · <project>`), body
71
+ * is `waiting for approval` (the title's own state word) or `turn complete`.
72
+ */
73
+ import { TERMINAL_TITLE_APP_NAME, TERMINAL_TITLE_SEPARATOR, boundTitle, } from './terminal-title.js';
74
+ /** ST — the string terminator. Never BEL here (see the header). */
75
+ export const TERMINAL_NOTIFY_ST = '\u001B\\';
76
+ /** Whole-text cap in code points, `…` included. */
77
+ export const MAX_TERMINAL_NOTIFY_CODE_POINTS = 120;
78
+ /** Fixed bodies; `waiting for approval` is the terminal title's state word. */
79
+ export const TERMINAL_NOTIFY_BODY = Object.freeze({
80
+ permission: 'waiting for approval',
81
+ 'turn-complete': 'turn complete',
82
+ });
83
+ /**
84
+ * Removes every control character (C0, DEL, C1) and every `;`: ESC/BEL/ST would end
85
+ * or restart a sequence, and `;` is the OSC field separator.
86
+ */
87
+ export function sanitizeNotifyText(text) {
88
+ return text.replace(/\p{Cc}|;/gu, '');
89
+ }
90
+ /** `darwin · <project>` — the terminal title's own head; an empty project drops its segment. */
91
+ export function terminalNotifyTitle(projectBasename) {
92
+ const project = sanitizeNotifyText(projectBasename);
93
+ return project === '' ? TERMINAL_TITLE_APP_NAME : `${TERMINAL_TITLE_APP_NAME}${TERMINAL_TITLE_SEPARATOR}${project}`;
94
+ }
95
+ /** `darwin · <project> · <body>`, sanitized and bounded. */
96
+ export function formatTerminalNotification(input) {
97
+ const text = `${terminalNotifyTitle(input.projectBasename)}${TERMINAL_TITLE_SEPARATOR}${TERMINAL_NOTIFY_BODY[input.moment]}`;
98
+ return boundTitle(sanitizeNotifyText(text), MAX_TERMINAL_NOTIFY_CODE_POINTS);
99
+ }
100
+ /** `ESC ] 9 ; <text> ESC \` — OSC 9, ST-terminated. The text is sanitized again at the seam. */
101
+ export function terminalNotifySequence(text) {
102
+ return `\u001B]9;${sanitizeNotifyText(text)}${TERMINAL_NOTIFY_ST}`;
103
+ }
104
+ /** tmux(1) passthrough: `ESC P tmux ; <sequence, ESC doubled> ESC \`. */
105
+ export function wrapForTmuxPassthrough(sequence) {
106
+ return `\u001BPtmux;${sequence.replaceAll('\u001B', '\u001B\u001B')}${TERMINAL_NOTIFY_ST}`;
107
+ }
108
+ /** tmux exports `TMUX` into every pane; screen and a bare terminal do not set it. */
109
+ export function isInsideTmux(env = process.env) {
110
+ return (env.TMUX ?? '') !== '';
111
+ }
112
+ /**
113
+ * Writes exactly one sequence (one `write` call) when `enabled` and stdout is a
114
+ * TTY, nothing otherwise. `enabled` is the config key at call time
115
+ * (`terminalNotify`); off writes nothing and allocates nothing.
116
+ */
117
+ export function notifyTerminal(enabled, input, seam = {}) {
118
+ if (!enabled)
119
+ return;
120
+ const isTTY = seam.isTTY ?? process.stdout.isTTY === true;
121
+ if (!isTTY)
122
+ return;
123
+ const sequence = terminalNotifySequence(formatTerminalNotification(input));
124
+ const insideTmux = seam.insideTmux ?? isInsideTmux();
125
+ const write = seam.write ?? writeToStdout;
126
+ try {
127
+ write(insideTmux ? wrapForTmuxPassthrough(sequence) : sequence);
128
+ }
129
+ catch {
130
+ // A closed or broken stdout must never take down the session for a toast.
131
+ }
132
+ }
133
+ function writeToStdout(chunk) {
134
+ process.stdout.write(chunk);
135
+ }
136
+ //# sourceMappingURL=terminal-notify.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"terminal-notify.js","sourceRoot":"","sources":["../../../src/tui/terminal-notify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AACH,OAAO,EACL,uBAAuB,EACvB,wBAAwB,EACxB,UAAU,GACX,MAAM,qBAAqB,CAAC;AAE7B,mEAAmE;AACnE,MAAM,CAAC,MAAM,kBAAkB,GAAG,UAAU,CAAC;AAC7C,mDAAmD;AACnD,MAAM,CAAC,MAAM,+BAA+B,GAAG,GAAG,CAAC;AAInD,+EAA+E;AAC/E,MAAM,CAAC,MAAM,oBAAoB,GAAmD,MAAM,CAAC,MAAM,CAAC;IAChG,UAAU,EAAE,sBAAsB;IAClC,eAAe,EAAE,eAAe;CACjC,CAAC,CAAC;AAOH;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,OAAO,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;AACxC,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,mBAAmB,CAAC,eAAuB;IACzD,MAAM,OAAO,GAAG,kBAAkB,CAAC,eAAe,CAAC,CAAC;IACpD,OAAO,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC,GAAG,uBAAuB,GAAG,wBAAwB,GAAG,OAAO,EAAE,CAAC;AACtH,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,0BAA0B,CAAC,KAA0B;IACnE,MAAM,IAAI,GAAG,GAAG,mBAAmB,CAAC,KAAK,CAAC,eAAe,CAAC,GAAG,wBAAwB,GAAG,oBAAoB,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;IAC7H,OAAO,UAAU,CAAC,kBAAkB,CAAC,IAAI,CAAC,EAAE,+BAA+B,CAAC,CAAC;AAC/E,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,sBAAsB,CAAC,IAAY;IACjD,OAAO,YAAY,kBAAkB,CAAC,IAAI,CAAC,GAAG,kBAAkB,EAAE,CAAC;AACrE,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,sBAAsB,CAAC,QAAgB;IACrD,OAAO,eAAe,QAAQ,CAAC,UAAU,CAAC,QAAQ,EAAE,cAAc,CAAC,GAAG,kBAAkB,EAAE,CAAC;AAC7F,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,YAAY,CAAC,GAAG,GAAsB,OAAO,CAAC,GAAG;IAC/D,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC;AACjC,CAAC;AAWD;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,OAAgB,EAAE,KAA0B,EAAE,IAAI,GAAuB,EAAE;IACxG,IAAI,CAAC,OAAO;QAAE,OAAO;IACrB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,KAAK,IAAI,CAAC;IAC1D,IAAI,CAAC,KAAK;QAAE,OAAO;IACnB,MAAM,QAAQ,GAAG,sBAAsB,CAAC,0BAA0B,CAAC,KAAK,CAAC,CAAC,CAAC;IAC3E,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,YAAY,EAAE,CAAC;IACrD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,aAAa,CAAC;IAC1C,IAAI,CAAC;QACH,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,sBAAsB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;IAClE,CAAC;IAAC,MAAM,CAAC;QACP,0EAA0E;IAC5E,CAAC;AACH,CAAC;AAED,SAAS,aAAa,CAAC,KAAa;IAClC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;AAC9B,CAAC"}
@@ -0,0 +1,94 @@
1
+ /**
2
+ * Config-gated terminal window/tab title for the interactive TUI driver (SER-073).
3
+ *
4
+ * The title is the one surface a user sees while another tab is focused, so it
5
+ * carries the session's project and coarse state: `darwin · <project> · <state>`
6
+ * with state `idle`/`working`/`waiting for approval`, plus ` · N queued` while
7
+ * prompts wait. Fixed composition, one boolean config key (`terminalTitle`) — no
8
+ * spinner (a spinner needs a tick, and the frame-budget row forbids a new tick
9
+ * source), no model/branch/token fields, no picker.
10
+ *
11
+ * The sequence is OSC 2 (`ESC ] 2 ; <title> BEL`), written straight to the
12
+ * process's real stdout the way `terminal-bell.ts` writes BEL and `copy-command.ts`
13
+ * writes OSC 52: a non-printing control sequence, never an Ink row, so the frame
14
+ * budget, `/export` byte-stability and replay are untouched. It is written only
15
+ * when the composed title *changes* — the writer below keeps the last title — so a
16
+ * streaming turn that re-renders hundreds of frames costs one write at its start
17
+ * and one at its end. Headless drivers never reach this module.
18
+ *
19
+ * The title is an escape-sequence payload: every control character (C0, DEL, C1 —
20
+ * which covers BEL and ESC, the two bytes that could end or restart a sequence) is
21
+ * stripped from the project name before it is embedded, so a directory name can
22
+ * never inject a second sequence. The whole title is bounded at
23
+ * {@link MAX_TERMINAL_TITLE_CODE_POINTS}, truncated end-first with `…`.
24
+ *
25
+ * Restore is best-effort: the bare project basename. The xterm title stack
26
+ * (`CSI 22;0 t` / `CSI 23;0 t`) is deliberately not used — there is no source
27
+ * demonstrating that every terminal lacking it ignores it harmlessly, and a
28
+ * terminal that echoes an unknown CSI would leave garbage on the screen.
29
+ */
30
+ export declare const TERMINAL_TITLE_APP_NAME = "darwin";
31
+ export declare const TERMINAL_TITLE_SEPARATOR = " \u00B7 ";
32
+ /** Whole-title cap in code points, `…` included; tabs show far less than this. */
33
+ export declare const MAX_TERMINAL_TITLE_CODE_POINTS = 80;
34
+ export type TerminalTitleBaseState = 'idle' | 'working' | 'waiting for approval';
35
+ /** The base, plus ` · N queued` while prompts wait behind it. */
36
+ export type TerminalTitleState = TerminalTitleBaseState | `${TerminalTitleBaseState} · ${number} queued`;
37
+ export interface TerminalTitleInput {
38
+ readonly projectBasename: string;
39
+ readonly state: TerminalTitleState;
40
+ }
41
+ export interface TerminalTitleSignals {
42
+ /** A permission prompt is published to the screen (the loop is blocked on it). */
43
+ readonly permissionPending: boolean;
44
+ /** The session is busy: a turn streams, a `!` command runs, or compaction runs. */
45
+ readonly busy: boolean;
46
+ /** Entries waiting in the prompt queue. */
47
+ readonly queued: number;
48
+ }
49
+ /**
50
+ * Fixed precedence for the base: a published permission prompt outranks everything
51
+ * (the loop is waiting on the user), then a running turn, else idle. The queue is
52
+ * not a competing state but a suffix on whichever base holds — a queue waiting
53
+ * behind a running turn is exactly what a user in another tab wants to see, and
54
+ * the idle-with-queue moment (the drain has not fired yet) stays honest too.
55
+ */
56
+ export declare function deriveTerminalTitleState(signals: TerminalTitleSignals): TerminalTitleState;
57
+ /** Removes every control character (C0, DEL, C1): BEL and ESC would end or start a sequence. */
58
+ export declare function sanitizeTitleText(text: string): string;
59
+ /** End-first truncation on code points, `…` taking the last slot. */
60
+ export declare function boundTitle(title: string, cap?: number): string;
61
+ /**
62
+ * `darwin · <project> · <state>`, sanitized and bounded. A project name that is
63
+ * empty after sanitizing (the filesystem root, or a name made only of control
64
+ * characters) drops its segment rather than leaving two separators touching.
65
+ */
66
+ export declare function formatTerminalTitle(input: TerminalTitleInput): string;
67
+ /** `ESC ] 2 ; <title> BEL` — OSC 2 (window title), BEL-terminated like the OSC 52 `/copy` writes. */
68
+ export declare function terminalTitleSequence(title: string): string;
69
+ /** The best-effort restore: the bare project basename, sanitized and bounded. */
70
+ export declare function terminalTitleRestore(projectBasename: string): string;
71
+ export interface TerminalTitleWriterOptions {
72
+ /** `process.stdout.isTTY` in production; a pipe or file gets no sequence at all. */
73
+ readonly isTTY: boolean;
74
+ /** Test seam; production writes to the real stdout, never through Ink's frame path. */
75
+ readonly write?: (chunk: string) => void;
76
+ }
77
+ export interface TerminalTitleWriter {
78
+ /**
79
+ * Composes the title and writes its sequence only when it differs from the last
80
+ * one written. `enabled` is the config key at call time (`terminalTitle`); off
81
+ * writes nothing and forgets nothing.
82
+ */
83
+ show(input: TerminalTitleInput, enabled: boolean): void;
84
+ /**
85
+ * Writes the restore sequence for the last project shown, once. A writer that
86
+ * never wrote a title has nothing to restore and stays silent, so the off path
87
+ * is byte-identical to before the feature existed.
88
+ */
89
+ restore(): void;
90
+ /** What was last written (the title, not the sequence); tests and diagnostics only. */
91
+ readonly lastTitle: string | undefined;
92
+ }
93
+ /** One writer per interactive App: it owns the change-only rule and the single restore. */
94
+ export declare function createTerminalTitleWriter(options: TerminalTitleWriterOptions): TerminalTitleWriter;
@@ -0,0 +1,121 @@
1
+ /**
2
+ * Config-gated terminal window/tab title for the interactive TUI driver (SER-073).
3
+ *
4
+ * The title is the one surface a user sees while another tab is focused, so it
5
+ * carries the session's project and coarse state: `darwin · <project> · <state>`
6
+ * with state `idle`/`working`/`waiting for approval`, plus ` · N queued` while
7
+ * prompts wait. Fixed composition, one boolean config key (`terminalTitle`) — no
8
+ * spinner (a spinner needs a tick, and the frame-budget row forbids a new tick
9
+ * source), no model/branch/token fields, no picker.
10
+ *
11
+ * The sequence is OSC 2 (`ESC ] 2 ; <title> BEL`), written straight to the
12
+ * process's real stdout the way `terminal-bell.ts` writes BEL and `copy-command.ts`
13
+ * writes OSC 52: a non-printing control sequence, never an Ink row, so the frame
14
+ * budget, `/export` byte-stability and replay are untouched. It is written only
15
+ * when the composed title *changes* — the writer below keeps the last title — so a
16
+ * streaming turn that re-renders hundreds of frames costs one write at its start
17
+ * and one at its end. Headless drivers never reach this module.
18
+ *
19
+ * The title is an escape-sequence payload: every control character (C0, DEL, C1 —
20
+ * which covers BEL and ESC, the two bytes that could end or restart a sequence) is
21
+ * stripped from the project name before it is embedded, so a directory name can
22
+ * never inject a second sequence. The whole title is bounded at
23
+ * {@link MAX_TERMINAL_TITLE_CODE_POINTS}, truncated end-first with `…`.
24
+ *
25
+ * Restore is best-effort: the bare project basename. The xterm title stack
26
+ * (`CSI 22;0 t` / `CSI 23;0 t`) is deliberately not used — there is no source
27
+ * demonstrating that every terminal lacking it ignores it harmlessly, and a
28
+ * terminal that echoes an unknown CSI would leave garbage on the screen.
29
+ */
30
+ export const TERMINAL_TITLE_APP_NAME = 'darwin';
31
+ export const TERMINAL_TITLE_SEPARATOR = ' · ';
32
+ /** Whole-title cap in code points, `…` included; tabs show far less than this. */
33
+ export const MAX_TERMINAL_TITLE_CODE_POINTS = 80;
34
+ /**
35
+ * Fixed precedence for the base: a published permission prompt outranks everything
36
+ * (the loop is waiting on the user), then a running turn, else idle. The queue is
37
+ * not a competing state but a suffix on whichever base holds — a queue waiting
38
+ * behind a running turn is exactly what a user in another tab wants to see, and
39
+ * the idle-with-queue moment (the drain has not fired yet) stays honest too.
40
+ */
41
+ export function deriveTerminalTitleState(signals) {
42
+ const base = signals.permissionPending
43
+ ? 'waiting for approval'
44
+ : signals.busy
45
+ ? 'working'
46
+ : 'idle';
47
+ if (signals.queued >= 1)
48
+ return `${base}${TERMINAL_TITLE_SEPARATOR}${Math.floor(signals.queued)} queued`;
49
+ return base;
50
+ }
51
+ /** Removes every control character (C0, DEL, C1): BEL and ESC would end or start a sequence. */
52
+ export function sanitizeTitleText(text) {
53
+ return text.replace(/\p{Cc}/gu, '');
54
+ }
55
+ /** End-first truncation on code points, `…` taking the last slot. */
56
+ export function boundTitle(title, cap = MAX_TERMINAL_TITLE_CODE_POINTS) {
57
+ const points = [...title];
58
+ if (points.length <= cap)
59
+ return title;
60
+ return `${points.slice(0, Math.max(0, cap - 1)).join('')}…`;
61
+ }
62
+ /**
63
+ * `darwin · <project> · <state>`, sanitized and bounded. A project name that is
64
+ * empty after sanitizing (the filesystem root, or a name made only of control
65
+ * characters) drops its segment rather than leaving two separators touching.
66
+ */
67
+ export function formatTerminalTitle(input) {
68
+ const project = sanitizeTitleText(input.projectBasename);
69
+ const parts = project === ''
70
+ ? [TERMINAL_TITLE_APP_NAME, input.state]
71
+ : [TERMINAL_TITLE_APP_NAME, project, input.state];
72
+ return boundTitle(parts.join(TERMINAL_TITLE_SEPARATOR));
73
+ }
74
+ /** `ESC ] 2 ; <title> BEL` — OSC 2 (window title), BEL-terminated like the OSC 52 `/copy` writes. */
75
+ export function terminalTitleSequence(title) {
76
+ return `\u001B]2;${sanitizeTitleText(title)}\u0007`;
77
+ }
78
+ /** The best-effort restore: the bare project basename, sanitized and bounded. */
79
+ export function terminalTitleRestore(projectBasename) {
80
+ return terminalTitleSequence(boundTitle(sanitizeTitleText(projectBasename)));
81
+ }
82
+ /** One writer per interactive App: it owns the change-only rule and the single restore. */
83
+ export function createTerminalTitleWriter(options) {
84
+ const write = options.write ?? writeToStdout;
85
+ let lastTitle;
86
+ let lastProject;
87
+ let restored = false;
88
+ const emit = (sequence) => {
89
+ try {
90
+ write(sequence);
91
+ }
92
+ catch {
93
+ // A closed or broken stdout must never take down the session for a title.
94
+ }
95
+ };
96
+ return {
97
+ show(input, enabled) {
98
+ if (!enabled || !options.isTTY || restored)
99
+ return;
100
+ const title = formatTerminalTitle(input);
101
+ if (title === lastTitle)
102
+ return;
103
+ lastTitle = title;
104
+ lastProject = input.projectBasename;
105
+ emit(terminalTitleSequence(title));
106
+ },
107
+ restore() {
108
+ if (restored || lastTitle === undefined)
109
+ return;
110
+ restored = true;
111
+ emit(terminalTitleRestore(lastProject ?? ''));
112
+ },
113
+ get lastTitle() {
114
+ return lastTitle;
115
+ },
116
+ };
117
+ }
118
+ function writeToStdout(chunk) {
119
+ process.stdout.write(chunk);
120
+ }
121
+ //# sourceMappingURL=terminal-title.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"terminal-title.js","sourceRoot":"","sources":["../../../src/tui/terminal-title.ts"],"names":[],"mappings":"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"}
@@ -13,6 +13,7 @@ import { type PlanItem } from '../tools/update-plan.js';
13
13
  import { type BackgroundBashMode } from './background-tool-presentation.js';
14
14
  import { type ShellOutcome } from './shell-command.js';
15
15
  import { type SubagentDispatchProgress } from '../agents/dispatch-registry.js';
16
+ import type { TaskNotificationFields } from '../trajectory/record.js';
16
17
  export type HistoryItem = {
17
18
  kind: 'user';
18
19
  id: string;
@@ -189,7 +190,15 @@ export type TurnAction = {
189
190
  | ({
190
191
  type: 'shellCommand';
191
192
  output: string;
192
- } & ShellOutcome);
193
+ } & ShellOutcome)
194
+ /**
195
+ * A background-task wake was sent (SER-069): one notice row composed from the
196
+ * recorded fields only, so replaying a `taskNotification` record dispatches the
197
+ * identical action and reproduces the identical history. Not a `userInput`.
198
+ */
199
+ | ({
200
+ type: 'taskNotification';
201
+ } & TaskNotificationFields);
193
202
  export declare function turnReducer(state: TurnState, action: TurnAction): TurnState;
194
203
  /** Flattens tool result content into text for the collapsed preview. */
195
204
  export declare function previewToolResult(content: readonly unknown[]): string;