@phren/cli 0.3.11 → 0.3.13

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 (182) hide show
  1. package/dist/bridge/account-usage.d.ts +124 -0
  2. package/dist/bridge/account-usage.js +258 -0
  3. package/dist/bridge/agent-hook-stores.d.ts +3 -0
  4. package/dist/bridge/agent-hook-stores.js +5 -0
  5. package/dist/bridge/agent-hooks.d.ts +162 -5
  6. package/dist/bridge/agent-hooks.js +682 -49
  7. package/dist/bridge/approval-summary.d.ts +16 -0
  8. package/dist/bridge/approval-summary.js +133 -0
  9. package/dist/bridge/authority-command.d.ts +20 -0
  10. package/dist/bridge/authority-command.js +120 -0
  11. package/dist/bridge/authority.d.ts +223 -0
  12. package/dist/bridge/authority.js +231 -0
  13. package/dist/bridge/claude-account-setup.d.ts +14 -0
  14. package/dist/bridge/claude-account-setup.js +69 -0
  15. package/dist/bridge/claude-accounts.d.ts +49 -0
  16. package/dist/bridge/claude-accounts.js +195 -0
  17. package/dist/bridge/code-routes.js +2 -2
  18. package/dist/bridge/codex-app-server.d.ts +144 -0
  19. package/dist/bridge/codex-app-server.js +319 -0
  20. package/dist/bridge/codex-auth-refresh.d.ts +33 -0
  21. package/dist/bridge/codex-auth-refresh.js +71 -0
  22. package/dist/bridge/codex-hook-trust.d.ts +27 -0
  23. package/dist/bridge/codex-hook-trust.js +237 -0
  24. package/dist/bridge/codex-question-reply.d.ts +16 -0
  25. package/dist/bridge/codex-question-reply.js +57 -0
  26. package/dist/bridge/codex-review-mode.d.ts +10 -0
  27. package/dist/bridge/codex-review-mode.js +74 -0
  28. package/dist/bridge/codex-servers.d.ts +217 -0
  29. package/dist/bridge/codex-servers.js +636 -0
  30. package/dist/bridge/command.js +97 -4
  31. package/dist/bridge/computer-identity.d.ts +75 -0
  32. package/dist/bridge/computer-identity.js +166 -0
  33. package/dist/bridge/conductor-group.d.ts +91 -8
  34. package/dist/bridge/conductor-group.js +105 -9
  35. package/dist/bridge/conductor-role.d.ts +94 -0
  36. package/dist/bridge/conductor-role.js +176 -0
  37. package/dist/bridge/conductor-sets.d.ts +20 -0
  38. package/dist/bridge/conductor-sets.js +59 -0
  39. package/dist/bridge/dispatch-command.d.ts +3 -0
  40. package/dist/bridge/dispatch-command.js +82 -12
  41. package/dist/bridge/dispatch-returns.d.ts +128 -19
  42. package/dist/bridge/dispatch-returns.js +371 -54
  43. package/dist/bridge/dispatch.d.ts +128 -3
  44. package/dist/bridge/dispatch.js +303 -42
  45. package/dist/bridge/fanouts.d.ts +7 -1
  46. package/dist/bridge/fanouts.js +39 -4
  47. package/dist/bridge/folder-trust.d.ts +56 -0
  48. package/dist/bridge/folder-trust.js +195 -0
  49. package/dist/bridge/grants.d.ts +22 -1
  50. package/dist/bridge/grants.js +57 -9
  51. package/dist/bridge/hand-off-queue.d.ts +74 -0
  52. package/dist/bridge/hand-off-queue.js +235 -0
  53. package/dist/bridge/hand-off.d.ts +30 -10
  54. package/dist/bridge/hand-off.js +79 -46
  55. package/dist/bridge/harness-status.d.ts +11 -0
  56. package/dist/bridge/harness-status.js +32 -0
  57. package/dist/bridge/harnesses.d.ts +39 -0
  58. package/dist/bridge/harnesses.js +65 -0
  59. package/dist/bridge/health.d.ts +2 -0
  60. package/dist/bridge/health.js +1 -1
  61. package/dist/bridge/herdr.d.ts +11 -2
  62. package/dist/bridge/herdr.js +98 -23
  63. package/dist/bridge/hook-fast.d.ts +4 -0
  64. package/dist/bridge/hook-fast.js +68 -0
  65. package/dist/bridge/install.d.ts +16 -1
  66. package/dist/bridge/install.js +102 -21
  67. package/dist/bridge/launch-brief.d.ts +96 -0
  68. package/dist/bridge/launch-brief.js +164 -0
  69. package/dist/bridge/model-switch.d.ts +3 -0
  70. package/dist/bridge/model-switch.js +17 -1
  71. package/dist/bridge/models.d.ts +8 -4
  72. package/dist/bridge/models.js +24 -8
  73. package/dist/bridge/mux-wire.d.ts +9 -0
  74. package/dist/bridge/mux-wire.js +19 -0
  75. package/dist/bridge/opencode-pane-server.d.ts +113 -0
  76. package/dist/bridge/opencode-pane-server.js +332 -0
  77. package/dist/bridge/opencode-panes.d.ts +111 -0
  78. package/dist/bridge/opencode-panes.js +295 -0
  79. package/dist/bridge/pane-accounts.d.ts +8 -0
  80. package/dist/bridge/pane-accounts.js +46 -0
  81. package/dist/bridge/pane-status.d.ts +12 -0
  82. package/dist/bridge/pane-status.js +50 -1
  83. package/dist/bridge/prompt-startup.d.ts +5 -0
  84. package/dist/bridge/prompt-startup.js +24 -0
  85. package/dist/bridge/protocol.d.ts +5 -0
  86. package/dist/bridge/protocol.js +4 -0
  87. package/dist/bridge/push.d.ts +11 -4
  88. package/dist/bridge/push.js +27 -4
  89. package/dist/bridge/questions.d.ts +37 -2
  90. package/dist/bridge/questions.js +158 -15
  91. package/dist/bridge/resources.d.ts +9 -3
  92. package/dist/bridge/resources.js +24 -8
  93. package/dist/bridge/schedule-format.d.ts +2 -0
  94. package/dist/bridge/schedule-format.js +3 -0
  95. package/dist/bridge/schedule-launch.d.ts +2 -1
  96. package/dist/bridge/schedule-launch.js +27 -53
  97. package/dist/bridge/schedule-watch.d.ts +24 -1
  98. package/dist/bridge/schedule-watch.js +89 -2
  99. package/dist/bridge/server-launch.d.ts +22 -5
  100. package/dist/bridge/server-launch.js +238 -32
  101. package/dist/bridge/server-overview.d.ts +10 -3
  102. package/dist/bridge/server-overview.js +32 -15
  103. package/dist/bridge/server-pane-routes.d.ts +3 -0
  104. package/dist/bridge/server-pane-routes.js +150 -18
  105. package/dist/bridge/server-routes.d.ts +11 -0
  106. package/dist/bridge/server-routes.js +214 -36
  107. package/dist/bridge/server-stream.d.ts +2 -0
  108. package/dist/bridge/server-stream.js +22 -8
  109. package/dist/bridge/server.d.ts +6 -1
  110. package/dist/bridge/server.js +58 -13
  111. package/dist/bridge/session-activity.d.ts +93 -0
  112. package/dist/bridge/session-activity.js +139 -0
  113. package/dist/bridge/session-rename.d.ts +48 -0
  114. package/dist/bridge/session-rename.js +190 -0
  115. package/dist/bridge/session-servers.js +2 -2
  116. package/dist/bridge/settings-switch.d.ts +60 -0
  117. package/dist/bridge/settings-switch.js +287 -0
  118. package/dist/bridge/speech-voice.d.ts +55 -0
  119. package/dist/bridge/speech-voice.js +132 -0
  120. package/dist/bridge/speech.d.ts +70 -11
  121. package/dist/bridge/speech.js +169 -41
  122. package/dist/bridge/stalls.d.ts +22 -0
  123. package/dist/bridge/stalls.js +57 -0
  124. package/dist/bridge/sudo.d.ts +209 -0
  125. package/dist/bridge/sudo.js +501 -0
  126. package/dist/bridge/terminal-herdr.js +9 -3
  127. package/dist/bridge/terminal-tmux.d.ts +15 -3
  128. package/dist/bridge/terminal-tmux.js +103 -13
  129. package/dist/bridge/terminal.d.ts +27 -4
  130. package/dist/bridge/terminal.js +8 -1
  131. package/dist/bridge/transcript-claude.d.ts +4 -0
  132. package/dist/bridge/transcript-claude.js +186 -16
  133. package/dist/bridge/transcript-codex.d.ts +0 -2
  134. package/dist/bridge/transcript-codex.js +29 -4
  135. package/dist/bridge/transcript-preview.d.ts +1 -0
  136. package/dist/bridge/transcript-preview.js +24 -4
  137. package/dist/bridge/transcripts.d.ts +15 -2
  138. package/dist/bridge/transcripts.js +47 -16
  139. package/dist/bridge/turn-records.d.ts +85 -0
  140. package/dist/bridge/turn-records.js +143 -0
  141. package/dist/bridge/uploads.d.ts +3 -0
  142. package/dist/bridge/uploads.js +14 -0
  143. package/dist/bridge/usage.d.ts +56 -10
  144. package/dist/bridge/usage.js +190 -45
  145. package/dist/bridge-hook.mjs +27975 -20636
  146. package/dist/cli/claude-unmanaged.d.ts +12 -0
  147. package/dist/cli/claude-unmanaged.js +105 -0
  148. package/dist/cli/schedules.js +2 -1
  149. package/dist/cli/session-start.js +10 -1
  150. package/dist/cli/session-stop.js +9 -1
  151. package/dist/cli-registry.js +31 -6
  152. package/dist/data/task-receipts.d.ts +19 -0
  153. package/dist/data/task-receipts.js +68 -0
  154. package/dist/data/tasks.js +4 -1
  155. package/dist/generated/memory-ui-graph.browser.js +63 -63
  156. package/dist/graph-core/model.js +24 -3
  157. package/dist/graph-core/types.d.ts +4 -1
  158. package/dist/graph-core/types.js +1 -0
  159. package/dist/init/init-preset.js +7 -3
  160. package/dist/init/init-uninstall.js +2 -11
  161. package/dist/init/teardown.d.ts +3 -0
  162. package/dist/init/teardown.js +47 -0
  163. package/dist/link/context.js +21 -9
  164. package/dist/mcp/plugin-mode.js +1 -1
  165. package/dist/memory-ui-graph.runtime.js +63 -63
  166. package/dist/modules/code-package.d.ts +1 -0
  167. package/dist/modules/code-package.js +36 -7
  168. package/dist/modules/registry.js +17 -16
  169. package/dist/profile-store.d.ts +6 -0
  170. package/dist/profile-store.js +25 -1
  171. package/dist/shell/graph/glyphs.js +4 -0
  172. package/dist/shell/graph/graph-view.js +2 -0
  173. package/dist/status.js +7 -1
  174. package/dist/sync/task-claim.js +3 -2
  175. package/dist/task/lifecycle.js +25 -4
  176. package/dist/test-global-setup.js +5 -0
  177. package/dist/tools/dispatch.js +52 -4
  178. package/dist/tools/tasks.js +10 -1
  179. package/package.json +1 -1
  180. package/plugins/opencode/phren-transcript.js +87 -4
  181. package/starter/global/AGENTS.md +4 -0
  182. package/starter/global/skills/conductor/SKILL.md +51 -4
@@ -0,0 +1,124 @@
1
+ import { type NotLinkedComputer } from "./hand-off.js";
2
+ import { type HookPeer } from "./peers.js";
3
+ import { type Json } from "./protocol.js";
4
+ import { NEAR_LIMIT_LEFT, type AccountUsage, type UsageWindow } from "./usage.js";
5
+ export { NEAR_LIMIT_LEFT };
6
+ /**
7
+ * Every computer's agent usage merged by account, for a conductor choosing
8
+ * where to send work: `account_usage` and `phren dispatch usage`. Read like
9
+ * `live_sessions`: this Hook, then each linked Hook over its pinned pipe, with
10
+ * unreachable and unlinked computers listed apart.
11
+ *
12
+ * The merge follows the phone's cards: one account is one allowance whichever
13
+ * computers report it, so the freshest whole report stands. Claude and Codex
14
+ * rows merge by their account key; a Claude login with no identity
15
+ * (`claude:home:<id>`) stays per computer, since two unknown logins are not
16
+ * one account. A window whose reset time has passed says `reset` and has no
17
+ * percent, and a report older than STALE_AFTER_MS is flagged stale.
18
+ *
19
+ * `nearLimit` is information: the owner often wants quota used before it
20
+ * resets. Only `exhausted` (a window at 100% or refusing requests) rules an
21
+ * account out.
22
+ */
23
+ /** A report older than this is flagged: the Hook reads each account at most once a minute. */
24
+ export declare const STALE_AFTER_MS: number;
25
+ export interface AccountWindow {
26
+ id: string;
27
+ name: string;
28
+ usedPercent?: number;
29
+ leftPercent?: number;
30
+ resetsAt?: string;
31
+ resetsIn?: string;
32
+ /** Reset since its report: the allowance is back, but no new percent is known. */
33
+ reset?: true;
34
+ /** The service is refusing requests on this window now. */
35
+ limited?: true;
36
+ /** At 100% or refused: no quota on this window until it resets. */
37
+ exhausted?: true;
38
+ usedUSD?: number;
39
+ limitUSD?: number;
40
+ }
41
+ export interface AccountUsageRow {
42
+ /** `source` or `source|key`, as the phone keys its cards. */
43
+ id: string;
44
+ harness: string;
45
+ name: string;
46
+ /** The login's email, else the account's label, when the Hook names one. */
47
+ account?: string;
48
+ windows: AccountWindow[];
49
+ /** Least room on any window with a percent; `limited` counts as 0. */
50
+ leftPercent?: number;
51
+ /** Under 20% left on some window. Information, not a reason to avoid the account. */
52
+ nearLimit: boolean;
53
+ /** A window is at 100% or refusing requests: never dispatch to it until `availableIn`. */
54
+ exhausted: boolean;
55
+ /** When the last exhausted window resets, as "3h 10m". */
56
+ availableIn?: string;
57
+ spend?: {
58
+ amountUSD: number;
59
+ period: string;
60
+ };
61
+ updatedAt?: string;
62
+ /** How old the standing report is, as "4m" or "2d 3h". */
63
+ age?: string;
64
+ stale: boolean;
65
+ /** The computer whose report stands. */
66
+ from?: string;
67
+ /** Where it is signed in, with the Claude account id dispatch takes there. */
68
+ computers: Array<{
69
+ name: string;
70
+ account?: string;
71
+ }>;
72
+ message?: string;
73
+ }
74
+ export interface AccountUsageView {
75
+ accounts: AccountUsageRow[];
76
+ /** Harnesses no computer reported numbers for, with what each Hook said. */
77
+ noData: Array<{
78
+ harness: string;
79
+ name: string;
80
+ computers: string[];
81
+ message?: string;
82
+ }>;
83
+ /** The computers that answered, this one first. */
84
+ computers: string[];
85
+ unreachable: Array<{
86
+ computer: string;
87
+ error: string;
88
+ code?: string;
89
+ }>;
90
+ /** Registered in the store but not linked in hooks.yaml: their usage is unknown, not zero. */
91
+ notLinked: NotLinkedComputer[];
92
+ enrolled: number;
93
+ peerError?: string;
94
+ }
95
+ export interface ComputerUsage {
96
+ computer: string;
97
+ accounts: AccountUsage[];
98
+ }
99
+ export declare function ageText(ms: number): string;
100
+ /** The phone's card key, except that a Claude login with no identity stays on its own computer. */
101
+ export declare function accountIdentity(usage: AccountUsage, computer: string): string;
102
+ /** Percent used and left, with a passed reset reported as reset rather than as its old percent. */
103
+ export declare function settleWindow(window: UsageWindow, now: number): AccountWindow;
104
+ /** Least room across an account's windows, undefined when none has a percent. */
105
+ export declare function roomLeft(windows: readonly AccountWindow[]): number | undefined;
106
+ /** One row per account across every computer's report. */
107
+ export declare function mergeAccountUsage(reports: readonly ComputerUsage[], now?: number): Pick<AccountUsageView, "accounts" | "noData">;
108
+ export interface ReadAccountUsageOptions {
109
+ /** This computer's Hook; tests pass the fixture's socket. */
110
+ hook?: (route: string) => Promise<Json>;
111
+ peers?: () => Promise<{
112
+ peers: HookPeer[];
113
+ peerError?: string;
114
+ }>;
115
+ peer?: (peer: HookPeer, route: string) => Promise<Json>;
116
+ store?: string | null;
117
+ now?: number;
118
+ }
119
+ /** This Hook's usage and every linked Hook's, merged by account. */
120
+ export declare function readAccountUsage(options?: ReadAccountUsageOptions): Promise<AccountUsageView>;
121
+ /** The one-line answer a conductor reads first: how many, and which accounts are tight or stale. */
122
+ export declare function usageSummary(view: AccountUsageView): string;
123
+ /** `phren dispatch usage` without --json. */
124
+ export declare function formatAccountUsage(view: AccountUsageView): string;
@@ -0,0 +1,258 @@
1
+ import { findPhrenPath } from "../phren-paths.js";
2
+ import { HARNESS_NAMES, resetsIn, USAGE_SOURCES } from "../computers/read.js";
3
+ import { hookRequest } from "./client.js";
4
+ import { notLinkedFrom } from "./hand-off.js";
5
+ import { optionalHookPeers, peerRequest } from "./peers.js";
6
+ import { errorCode, object } from "./protocol.js";
7
+ import { NEAR_LIMIT_LEFT, windowExhausted, windowLeft } from "./usage.js";
8
+ export { NEAR_LIMIT_LEFT };
9
+ /**
10
+ * Every computer's agent usage merged by account, for a conductor choosing
11
+ * where to send work: `account_usage` and `phren dispatch usage`. Read like
12
+ * `live_sessions`: this Hook, then each linked Hook over its pinned pipe, with
13
+ * unreachable and unlinked computers listed apart.
14
+ *
15
+ * The merge follows the phone's cards: one account is one allowance whichever
16
+ * computers report it, so the freshest whole report stands. Claude and Codex
17
+ * rows merge by their account key; a Claude login with no identity
18
+ * (`claude:home:<id>`) stays per computer, since two unknown logins are not
19
+ * one account. A window whose reset time has passed says `reset` and has no
20
+ * percent, and a report older than STALE_AFTER_MS is flagged stale.
21
+ *
22
+ * `nearLimit` is information: the owner often wants quota used before it
23
+ * resets. Only `exhausted` (a window at 100% or refusing requests) rules an
24
+ * account out.
25
+ */
26
+ /** A report older than this is flagged: the Hook reads each account at most once a minute. */
27
+ export const STALE_AFTER_MS = 15 * 60_000;
28
+ /** ElevenLabs is left out: every read of it spends a request against its key's quota. */
29
+ const SOURCES = USAGE_SOURCES.join(",");
30
+ const USAGE_ROUTE = `/v1/usage?${new URLSearchParams({ sources: SOURCES, goPlan: "1", accounts: "all" })}`;
31
+ const date = (value) => value ? Date.parse(value) : NaN;
32
+ const hasData = (usage) => usage.windows.length > 0 || Boolean(usage.spend);
33
+ const newer = (a, b) => (date(b.usage.updatedAt) || 0) > (date(a.usage.updatedAt) || 0) ? b : a;
34
+ export function ageText(ms) {
35
+ const minutes = Math.max(0, Math.round(ms / 60_000));
36
+ const days = Math.floor(minutes / 1440), hours = Math.floor(minutes % 1440 / 60);
37
+ return days ? `${days}d ${hours}h` : hours ? `${hours}h ${minutes % 60}m` : `${minutes}m`;
38
+ }
39
+ /** The phone's card key, except that a Claude login with no identity stays on its own computer. */
40
+ export function accountIdentity(usage, computer) {
41
+ const key = usage.account?.key;
42
+ if (!key || key === usage.source)
43
+ return usage.source;
44
+ return key.startsWith(`${usage.source}:home:`) ? `${usage.source}|${key}@${computer}` : `${usage.source}|${key}`;
45
+ }
46
+ /** Percent used and left, with a passed reset reported as reset rather than as its old percent. */
47
+ export function settleWindow(window, now) {
48
+ const out = { id: window.id, name: window.name };
49
+ const resetAt = date(window.resetsAt);
50
+ const reset = window.reset === true || Number.isFinite(resetAt) && resetAt <= now;
51
+ const left = windowLeft(window, now);
52
+ if (reset)
53
+ out.reset = true;
54
+ else if (typeof window.usedPercent === "number")
55
+ out.usedPercent = window.usedPercent;
56
+ if (left !== undefined)
57
+ out.leftPercent = left;
58
+ if (window.resetsAt && !reset) {
59
+ out.resetsAt = window.resetsAt;
60
+ const until = resetsIn(window.resetsAt, now);
61
+ if (until)
62
+ out.resetsIn = until;
63
+ }
64
+ if (window.limited && !reset)
65
+ out.limited = true;
66
+ if (windowExhausted(window, now))
67
+ out.exhausted = true;
68
+ if (window.usedUSD !== undefined)
69
+ out.usedUSD = window.usedUSD;
70
+ if (window.limitUSD !== undefined)
71
+ out.limitUSD = window.limitUSD;
72
+ return out;
73
+ }
74
+ /** Least room across an account's windows, undefined when none has a percent. */
75
+ export function roomLeft(windows) {
76
+ const known = windows.map(w => w.leftPercent).filter((value) => value !== undefined);
77
+ return known.length ? Math.min(...known) : undefined;
78
+ }
79
+ function accountName(usage) {
80
+ const named = usage.accountName;
81
+ const label = usage.account?.label;
82
+ return usage.account?.email ?? (typeof named === "string" && named ? named : undefined)
83
+ ?? (label && label.toLowerCase() !== (HARNESS_NAMES[usage.source] ?? usage.source).toLowerCase() ? label : undefined);
84
+ }
85
+ /** One row per account across every computer's report. */
86
+ export function mergeAccountUsage(reports, now = Date.now()) {
87
+ const groups = new Map();
88
+ for (const report of reports)
89
+ for (const usage of report.accounts) {
90
+ const id = accountIdentity(usage, report.computer);
91
+ groups.set(id, [...groups.get(id) ?? [], { computer: report.computer, usage }]);
92
+ }
93
+ const accounts = [];
94
+ const empty = new Map();
95
+ for (const [id, group] of groups) {
96
+ const reporting = group.filter(item => hasData(item.usage));
97
+ if (!reporting.length) {
98
+ const entry = empty.get(group[0].usage.source) ?? { computers: [], messages: [] };
99
+ for (const item of group) {
100
+ if (!entry.computers.includes(item.computer))
101
+ entry.computers.push(item.computer);
102
+ if (item.usage.message && !entry.messages.includes(item.usage.message))
103
+ entry.messages.push(item.usage.message);
104
+ }
105
+ empty.set(group[0].usage.source, entry);
106
+ continue;
107
+ }
108
+ const source = group[0].usage.source;
109
+ // One allowance: the freshest report with windows stands whole, never mixed with another read.
110
+ const withWindows = reporting.filter(item => item.usage.windows.length);
111
+ const standing = (withWindows.length ? withWindows : reporting).reduce(newer);
112
+ const windows = standing.usage.windows.map(window => settleWindow(window, now));
113
+ const spend = mergedSpend(source, reporting);
114
+ const updated = date(standing.usage.updatedAt);
115
+ const leftPercent = roomLeft(windows);
116
+ const exhausted = windows.filter(w => w.exhausted);
117
+ const availableAt = exhausted.map(w => w.resetsAt).filter((value) => Boolean(value)).sort().at(-1);
118
+ const availableIn = availableAt ? resetsIn(availableAt, now) : undefined;
119
+ const name = accountName(standing.usage);
120
+ const computers = reporting.map(item => ({ name: item.computer, ...(source === "claude" && item.usage.account?.id ? { account: item.usage.account.id } : {}) }))
121
+ .filter((item, index, list) => list.findIndex(other => other.name === item.name && other.account === item.account) === index);
122
+ accounts.push({
123
+ id, harness: source, name: HARNESS_NAMES[source] ?? source, ...(name ? { account: name } : {}), windows,
124
+ ...(leftPercent !== undefined ? { leftPercent } : {}),
125
+ nearLimit: windows.some(w => w.limited) || leftPercent !== undefined && leftPercent < NEAR_LIMIT_LEFT,
126
+ exhausted: exhausted.length > 0, ...(availableIn ? { availableIn } : {}),
127
+ ...(spend ? { spend } : {}),
128
+ ...(standing.usage.updatedAt ? { updatedAt: standing.usage.updatedAt } : {}),
129
+ ...(Number.isFinite(updated) ? { age: ageText(now - updated) } : {}),
130
+ stale: !Number.isFinite(updated) || now - updated > STALE_AFTER_MS || windows.some(w => w.reset),
131
+ from: standing.computer, computers,
132
+ ...(standing.usage.message ? { message: standing.usage.message } : {}),
133
+ });
134
+ }
135
+ const order = (source) => { const at = USAGE_SOURCES.indexOf(source); return at < 0 ? USAGE_SOURCES.length : at; };
136
+ accounts.sort((a, b) => order(a.harness) - order(b.harness) || (a.account ?? "").localeCompare(b.account ?? "") || a.id.localeCompare(b.id));
137
+ const noData = [...empty].filter(([source]) => !accounts.some(row => row.harness === source))
138
+ .map(([source, entry]) => ({ harness: source, name: HARNESS_NAMES[source] ?? source, computers: entry.computers, ...(entry.messages[0] ? { message: entry.messages[0] } : {}) }))
139
+ .sort((a, b) => order(a.harness) - order(b.harness));
140
+ return { accounts, noData };
141
+ }
142
+ /** OpenCode's ledgers are per computer and add up; OpenRouter is one key seen from several, counted once per key. */
143
+ function mergedSpend(source, reporting) {
144
+ const spends = reporting.filter(item => item.usage.spend);
145
+ if (!spends.length)
146
+ return undefined;
147
+ const round = (value) => Math.round(value * 100) / 100;
148
+ if (source === "opencode" || source === "opencode-go") {
149
+ return { amountUSD: round(spends.reduce((sum, item) => sum + item.usage.spend.amountUSD, 0)), period: spends[0].usage.spend.period };
150
+ }
151
+ if (source === "openrouter") {
152
+ const byKey = new Map();
153
+ for (const item of spends) {
154
+ const key = item.usage.accountId ?? `computer:${item.computer}`;
155
+ const seen = byKey.get(key);
156
+ byKey.set(key, seen ? newer(seen, item) : item);
157
+ }
158
+ return { amountUSD: round([...byKey.values()].reduce((sum, item) => sum + item.usage.spend.amountUSD, 0)), period: spends[0].usage.spend.period };
159
+ }
160
+ return spends.reduce(newer).usage.spend;
161
+ }
162
+ /** This Hook's usage and every linked Hook's, merged by account. */
163
+ export async function readAccountUsage(options = {}) {
164
+ const hook = options.hook ?? (route => hookRequest(route, undefined, undefined, 30_000));
165
+ const ask = options.peer ?? ((peer, route) => peerRequest(peer, route, undefined, 20_000));
166
+ const [health, local, linked] = await Promise.all([hook("/v1/health"), hook(USAGE_ROUTE), (options.peers ?? optionalHookPeers)()]);
167
+ const here = typeof object(health.computer).name === "string" ? String(object(health.computer).name) : "this computer";
168
+ const reports = [{ computer: here, accounts: accountsOf(local) }];
169
+ const unreachable = [];
170
+ const peerNames = new Map();
171
+ await Promise.all(linked.peers.map(async (peer) => {
172
+ try {
173
+ const [usage, peerHealth] = await Promise.all([ask(peer, USAGE_ROUTE), ask(peer, "/v1/health").catch(() => ({}))]);
174
+ reports.push({ computer: peer.name, accounts: accountsOf(usage) });
175
+ const computer = object(object(peerHealth).computer);
176
+ peerNames.set(peer.name, [computer.name, ...(Array.isArray(computer.aliases) ? computer.aliases : [])].filter((name) => typeof name === "string"));
177
+ }
178
+ catch (error) {
179
+ const code = errorCode(error);
180
+ unreachable.push({ computer: peer.name, error: error instanceof Error ? error.message.slice(0, 300) : "Unreachable.", ...(code ? { code } : {}) });
181
+ }
182
+ }));
183
+ // Peers answer in any order; this computer first, then by name, so the standing report never depends on timing.
184
+ reports.sort((a, b) => a.computer === here ? -1 : b.computer === here ? 1 : a.computer.localeCompare(b.computer));
185
+ unreachable.sort((a, b) => a.computer.localeCompare(b.computer));
186
+ const store = options.store !== undefined ? options.store : findPhrenPath();
187
+ const notLinked = notLinkedFrom(store, here, linked.peers.map(peer => ({ name: peer.name, address: peer.address, names: peerNames.get(peer.name) })));
188
+ return { ...mergeAccountUsage(reports, options.now ?? Date.now()), computers: reports.map(report => report.computer), unreachable, notLinked,
189
+ enrolled: linked.peers.length, ...(linked.peerError ? { peerError: linked.peerError } : {}) };
190
+ }
191
+ function accountsOf(answer) {
192
+ return Array.isArray(answer.accounts) ? answer.accounts.filter((item) => {
193
+ const row = object(item);
194
+ return typeof row.source === "string" && Array.isArray(row.windows);
195
+ }) : [];
196
+ }
197
+ const ago = (age) => age === "0m" ? "just now" : `${age} ago`;
198
+ const title = (row) => row.account ? `${row.name} · ${row.account}` : row.name;
199
+ /** The one-line answer a conductor reads first: how many, and which accounts are tight or stale. */
200
+ export function usageSummary(view) {
201
+ const parts = [`${view.accounts.length} account${view.accounts.length === 1 ? "" : "s"} across ${view.computers.length} computer${view.computers.length === 1 ? "" : "s"}.`];
202
+ const out = view.accounts.filter(row => row.exhausted);
203
+ if (out.length)
204
+ parts.push(`Out of quota, do not dispatch to: ${out.map(row => `${title(row)}${row.availableIn ? ` (back in ${row.availableIn})` : ""}`).join("; ")}.`);
205
+ const near = view.accounts.filter(row => row.nearLimit && !row.exhausted);
206
+ if (near.length)
207
+ parts.push(`Low but usable: ${near.map(row => `${title(row)} (${row.leftPercent ?? 0}% left${tightest(row)?.resetsIn ? `, resets in ${tightest(row).resetsIn}` : ""})`).join("; ")}.`);
208
+ const limitedRows = view.accounts.filter(row => row.leftPercent !== undefined || row.exhausted);
209
+ if (limitedRows.length && limitedRows.every(row => row.exhausted))
210
+ parts.push("Every account with limits is out of quota: tell the owner before dispatching.");
211
+ const stale = view.accounts.filter(row => row.stale);
212
+ if (stale.length)
213
+ parts.push(`Stale: ${stale.map(row => `${title(row)} (${row.windows.some(w => w.reset) ? "a window reset since its report" : `reported ${row.age ? ago(row.age) : "at an unknown time"}`})`).join("; ")}.`);
214
+ if (view.unreachable.length)
215
+ parts.push(`Unreachable: ${view.unreachable.map(item => item.computer).join(", ")}.`);
216
+ if (view.notLinked.length)
217
+ parts.push(`Not linked, so not checked: ${view.notLinked.map(item => item.name).join(", ")}.`);
218
+ return parts.join(" ");
219
+ }
220
+ function tightest(row) {
221
+ return row.windows.filter(w => w.leftPercent !== undefined).sort((a, b) => a.leftPercent - b.leftPercent)[0];
222
+ }
223
+ /** `phren dispatch usage` without --json. */
224
+ export function formatAccountUsage(view) {
225
+ const lines = [`Usage by account from ${view.computers.join(", ")}`];
226
+ for (const row of view.accounts) {
227
+ const where = row.computers.map(c => c.account && c.account !== "default" ? `${c.name} (${c.account})` : c.name).join(", ");
228
+ const flags = [row.exhausted ? `out of quota${row.availableIn ? `, back in ${row.availableIn}` : ""}` : row.nearLimit ? `low, ${row.leftPercent ?? 0}% left` : row.leftPercent !== undefined ? `${row.leftPercent}% left` : "",
229
+ row.stale ? `stale${row.age ? `, reported ${ago(row.age)}` : ""}` : row.age ? ago(row.age) : ""].filter(Boolean).join("; ");
230
+ lines.push(`${title(row)} on ${where}${flags ? ` (${flags})` : ""}`);
231
+ for (const w of row.windows) {
232
+ const used = w.reset ? "reset, no new report" : w.usedPercent !== undefined ? `${w.usedPercent}% used` : w.usedUSD !== undefined ? `$${w.usedUSD.toFixed(2)}${w.limitUSD !== undefined ? ` of $${w.limitUSD.toFixed(2)}` : ""}` : "";
233
+ lines.push(` ${w.name.padEnd(30)} ${used.padEnd(22)}${w.limited ? "limited now " : ""}${w.resetsIn ? `resets in ${w.resetsIn}` : ""}`.trimEnd());
234
+ }
235
+ if (row.spend)
236
+ lines.push(` spend ${row.spend.period.replace(/_/g, " ").padEnd(24)} $${row.spend.amountUSD.toFixed(2)}`);
237
+ if (row.message)
238
+ lines.push(` ${row.message}`);
239
+ }
240
+ if (view.noData.length) {
241
+ lines.push("No numbers reported");
242
+ for (const item of view.noData)
243
+ lines.push(` ${item.name} (${item.computers.join(", ")})${item.message ? `: ${item.message}` : ""}`);
244
+ }
245
+ if (view.unreachable.length) {
246
+ lines.push("Unreachable");
247
+ for (const item of view.unreachable)
248
+ lines.push(` ${item.computer}: ${item.error}`);
249
+ }
250
+ if (view.notLinked.length) {
251
+ lines.push("Not linked, so not checked");
252
+ for (const item of view.notLinked)
253
+ lines.push(` ${item.name}${item.aliases?.length ? ` (also ${item.aliases.join(", ")})` : ""}`);
254
+ }
255
+ if (view.peerError)
256
+ lines.push(`Linked computers skipped: ${view.peerError}`);
257
+ return lines.join("\n");
258
+ }
@@ -17,6 +17,9 @@ export declare class PushBindingStore {
17
17
  consume(binding: string): PushBinding | undefined;
18
18
  /** The binding's action without spending it: a tap that opens the app. */
19
19
  peek(binding: string): PushBinding | undefined;
20
+ /** Keeps an action's bindings answerable until `expiresAt`: an ask its
21
+ * agent still lists must stay answerable from its notification. */
22
+ extendAction(action: string, expiresAt: number): void;
20
23
  dropAction(action: string): void;
21
24
  clear(): void;
22
25
  get size(): number;
@@ -42,6 +42,11 @@ export class PushBindingStore {
42
42
  const value = this.values.get(binding);
43
43
  return value && value.expiresAt > this.now() ? value : undefined;
44
44
  }
45
+ /** Keeps an action's bindings answerable until `expiresAt`: an ask its
46
+ * agent still lists must stay answerable from its notification. */
47
+ extendAction(action, expiresAt) { for (const value of this.values.values())
48
+ if (value.action === action && value.expiresAt < expiresAt)
49
+ value.expiresAt = expiresAt; }
45
50
  dropAction(action) { for (const [key, value] of this.values)
46
51
  if (value.action === action)
47
52
  this.values.delete(key); }
@@ -1,33 +1,89 @@
1
1
  import { type ModuleSnapshot } from "../modules/runtime.js";
2
- import { type ServerResponse } from "node:http";
3
2
  import { type Json, type Provider, type Target } from "./protocol.js";
4
3
  import { ToolChanges } from "./changes.js";
5
4
  import { ApprovalPushService } from "./push.js";
5
+ import { type RequestKind } from "./approval-summary.js";
6
6
  import { type DialogAnswer, type DialogQuestion } from "./claude-question-dialog.js";
7
7
  import { type TerminalChoice } from "./terminal-choice.js";
8
8
  import { ApprovalWatchLeases } from "./agent-hook-stores.js";
9
+ import { SudoBroker } from "./sudo.js";
10
+ import type { AppServerRequestId, PendingServerRequest } from "./codex-app-server.js";
11
+ import { PaneServerWatcher, type PaneAsks } from "./opencode-panes.js";
12
+ import type { PaneClient, PaneServerEntry } from "./opencode-pane-server.js";
9
13
  export { permissionPrompt, terminalChoice, visibleTerminalChoice, type TerminalChoice, type TerminalQuestion } from "./terminal-choice.js";
10
14
  export { ApprovalWatchLeases, PushBindingStore, recordedSession } from "./agent-hook-stores.js";
15
+ /** Where a held request's answer goes: the callback's HTTP response, or the
16
+ * reply to a Codex app-server request (codex-servers.ts). Either takes the
17
+ * PermissionRequest-shaped JSON; "{}" gives the request back to the terminal. */
18
+ interface HeldReply {
19
+ end(body: string): unknown;
20
+ readonly destroyed: boolean;
21
+ }
11
22
  interface Pending {
12
23
  target: Target;
13
- response: ServerResponse;
24
+ response: HeldReply;
14
25
  tool: string;
15
26
  input: unknown;
16
27
  message: string;
28
+ request: string;
29
+ requestKind: RequestKind;
17
30
  title?: string;
18
31
  choice?: TerminalChoice;
19
32
  expiresAt: string;
20
- timer: NodeJS.Timeout;
33
+ timer?: NodeJS.Timeout;
21
34
  conductor?: {
22
35
  action: "dispatch" | "hand_off";
23
36
  project?: string;
24
37
  computer?: string;
25
38
  };
39
+ /** A server request of the Hook's own Codex app-server: answered over RPC, never held on a timer. */
40
+ appServer?: {
41
+ requestId: AppServerRequestId;
42
+ answer: (result: Json) => void;
43
+ };
44
+ }
45
+ /** The approval card's tool and input for an app-server request, in the
46
+ * shapes `approvalSummary` and the phone already read for Codex's hook.
47
+ * Undefined for questions (`item/tool/requestUserInput`) and MCP
48
+ * elicitations, which stay in the pane. */
49
+ export declare function appServerApproval(request: PendingServerRequest): {
50
+ tool: string;
51
+ input: Json;
52
+ } | undefined;
53
+ /** The app-server's answer for the phone's allow or deny (T3's
54
+ * CodexSessionRuntime shapes: accept / decline, a permission grant or none). */
55
+ export declare function appServerDecision(request: PendingServerRequest, allow: boolean): Json;
56
+ /** What a dispatched worker's Hook tells the dispatching Hook it is waiting on:
57
+ * a card without the request's full message or details, which can run to 32 KB
58
+ * and cross SSH on every poll. */
59
+ export interface ForwardedApproval {
60
+ actionId: string;
61
+ tool: string;
62
+ title?: string;
63
+ request?: string;
64
+ requestKind?: RequestKind;
65
+ expiresAt?: string;
66
+ /** The pane is drawing this as a terminal dialog; the answer types its keys. */
67
+ terminal?: true;
68
+ conductor?: Pending["conductor"];
69
+ /** This Hook already pushed the request to a phone, so the dispatching Hook does not push it again. */
70
+ pushed?: true;
26
71
  }
27
72
  /** A conductor `dispatch` or `hand_off` permission ask the Hook can answer
28
73
  * itself under a standing grant, or offer the phone two grant-writing answers. */
29
74
  export declare function conductorCall(tool: string, input: unknown): Pending["conductor"] | undefined;
30
75
  export type DeliveryOutcome = "delivered" | "blocked" | "pending";
76
+ /** A phone message the Hook answered as delivered or queued, kept under the
77
+ * phone's delivery id so the phone can ask what became of it by that id.
78
+ * Holds a hash of the prompt's words, never the prompt. */
79
+ interface TrackedDelivery {
80
+ source: Provider;
81
+ session: string;
82
+ key: string;
83
+ state: "queued" | "delivered" | "blocked";
84
+ at: number;
85
+ }
86
+ export type TrackedState = TrackedDelivery["state"] | "unknown";
31
87
  /** This socket is deliberately separate from the phone's HTTP pipe. Only local
32
88
  * agent callbacks can register identities or create an approval request. */
33
89
  export declare class AgentHooks {
@@ -41,6 +97,8 @@ export declare class AgentHooks {
41
97
  * party that knows which conversation consumed the text, so it is the one
42
98
  * that can refuse it when that is not the conversation the phone meant. */
43
99
  private deliveries;
100
+ /** Phone messages by delivery id, until TRACK_MS: see `trackDelivery`. */
101
+ private tracked;
44
102
  /** The permission request a conversation is drawing in its own terminal
45
103
  * because nobody was there to hold it: what the phone shows above its
46
104
  * answer keys until the pane stops waiting. `dialog` marks a choice parsed
@@ -74,8 +132,18 @@ export declare class AgentHooks {
74
132
  * action, what an answer from the notification types. */
75
133
  private dialogPushes;
76
134
  private dialogActions;
77
- /** opencode permission asks seen on disk, by request id. */
135
+ /** Terminal dialogs offered to a dispatching Hook, by pane: the `dialog-` action minted for the dialog's current title. */
136
+ private forwardedDialogs;
137
+ /** Requests this Hook pushed to its own phone on behalf of a dispatched worker on another computer: action -> the answer to send back. */
138
+ private forwardedPushes;
139
+ /** Panes a dispatching Hook polled lately (`server\npane\nsource` -> expiry). */
140
+ private dispatchLeases;
141
+ /** opencode permission asks seen on disk or listed by a served pane, by request id. */
78
142
  private opencode;
143
+ /** Questions served OpenCode panes are asking, by question id. */
144
+ private servedQuestions;
145
+ /** One event subscription per served OpenCode pane; ticked with the Hook. */
146
+ readonly paneServers: PaneServerWatcher;
79
147
  private closed;
80
148
  private opencodeSweep?;
81
149
  private opencodeLive;
@@ -88,6 +156,11 @@ export declare class AgentHooks {
88
156
  private fanoutSeen;
89
157
  private fanoutTimer?;
90
158
  private fanoutArchiveTimer?;
159
+ /** The name the phone paired with (macOS Computer Name), for approval alerts;
160
+ * the short host name until that lookup answers. */
161
+ private computerName;
162
+ /** sudo -A requests from askpass, answered from the phone (sudo.ts). */
163
+ readonly sudo: SudoBroker;
91
164
  constructor(push?: ApprovalPushService, modules?: ModuleSnapshot | undefined);
92
165
  private approvalsDirectory;
93
166
  private scheduleOpencodeSweep;
@@ -97,6 +170,30 @@ export declare class AgentHooks {
97
170
  * forgotten. */
98
171
  sweepOpencodeApprovals(): Promise<void>;
99
172
  private readOpencodeApprovals;
173
+ /** The pane a served OpenCode ask belongs to, as the phone names it: the
174
+ * pane's place from its terminal, and the root of the asking session (a
175
+ * subagent's ask shows on the conversation the pane shows). */
176
+ private servedTarget;
177
+ /** Everything a served pane is asking right now. New asks become the same
178
+ * cards (and pushes) as the plugin's file asks; asks no longer listed were
179
+ * answered in the TUI or went away, and their cards go with them. */
180
+ servedAsks(entry: PaneServerEntry, client: PaneClient, asks: PaneAsks): Promise<void>;
181
+ /** A served pane's process is gone: nothing it asked can be answered. */
182
+ servedGone(key: string): void;
183
+ /** The question a served OpenCode pane is asking, in the shape the phone
184
+ * answers Claude's AskUserQuestion with (`/v1/questions/answer`). */
185
+ servedQuestion(target: Target): Json | undefined;
186
+ private servedClient;
187
+ /** Answers a served pane's permission ask over its own API. */
188
+ private answerServed;
189
+ /** The phone's answers to a served pane's question: the labels it chose
190
+ * (and a typed answer) per question, for exactly the questions it shows. */
191
+ answerServedQuestion(target: Target, questions: DialogQuestion[], answers: DialogAnswer[]): Promise<void>;
192
+ /** Keys the phone sends to a served OpenCode pane that its API answers
193
+ * better than the terminal: Esc declines a pending question or stops a
194
+ * working turn (`session.abort`), and a digit answers a pending
195
+ * single-question, single-choice set. False leaves the keys to the pane. */
196
+ servedKeys(target: Target, keys: readonly string[], status: string): Promise<boolean>;
100
197
  /** A session's exact pane. A recorded binding carries the full target; when
101
198
  * there is none, Herdr's explicit session identity names the pane. */
102
199
  private resolveTarget;
@@ -113,18 +210,32 @@ export declare class AgentHooks {
113
210
  * after `waitMs`: a busy agent queues typed input and submits it only when
114
211
  * its turn ends, so the record outlives the wait (up to ten minutes) and a
115
212
  * late submission to the wrong conversation is still refused. */
116
- expectDelivery(target: Target, text: string, waitMs?: number): Promise<DeliveryOutcome>;
213
+ expectDelivery(target: Target, text: string, waitMs?: number, signal?: AbortSignal): Promise<DeliveryOutcome>;
117
214
  /** A prompt Phren typed into `target` that its conversation has not submitted yet. */
118
215
  deliveryPending(target: Target, text: string): boolean;
119
216
  /** Wait again for a delivery `expectDelivery` already reported pending,
120
217
  * after the Hook pressed Enter a second time. */
121
218
  awaitLateDelivery(target: Target, text: string, waitMs?: number): Promise<DeliveryOutcome>;
219
+ /** Remember a phone message's outcome under its delivery id. A queued one
220
+ * is tracked only while its typed record still waits for the agent's hook,
221
+ * so the hook's later answer always reaches it (`settleTracked`). */
222
+ trackDelivery(id: string, target: Target, text: string, state: "queued" | "delivered"): void;
223
+ /** What became of the phone message `id` sent to `target`'s conversation:
224
+ * queued until the agent submits it, then delivered, or blocked when
225
+ * another conversation in the pane took it. Unknown when the Hook did not
226
+ * track it, it was for another conversation, or it is older than TRACK_MS. */
227
+ deliveryState(id: string, target: Target): TrackedState;
228
+ /** The oldest queued message tracked for `delivery`'s conversation with these words. */
229
+ private settleTracked;
122
230
  /** The conversation `target` just submitted `prompt`. Nothing Phren typed
123
231
  * matches: a locally typed prompt, always allowed. Otherwise the oldest
124
232
  * matching delivery decides: its own conversation consumes it; any other
125
233
  * conversation is told to drop it, so the text is never spoken to the
126
234
  * wrong agent and the phone can safely send it again. */
127
235
  private submitted;
236
+ /** The conversation's own turn events, for dispatch returns (turn-records.ts).
237
+ * A failed write never fails the agent's callback. */
238
+ private recordTurn;
128
239
  private rememberTerminalPrompt;
129
240
  /** The request the agent is showing in its terminal, if one fell through
130
241
  * in the last fifteen minutes; the caller only asks while the pane waits. */
@@ -216,13 +327,59 @@ export declare class AgentHooks {
216
327
  * hook behind it, so this is the only way it reaches a phone with phren
217
328
  * closed. Each dialog is pushed once; a pane that stops waiting drops it. */
218
329
  observeWaitingPanes(server: string, panes: Json[], resolve: (pane: Json) => Promise<Target | undefined>): Promise<void>;
330
+ /** Keeps the held asks of these dispatched panes for the dispatching Hook's
331
+ * next polls: without a phone, a watcher or push here, a worker's request
332
+ * would go straight to its terminal and only its `blocked` state would
333
+ * reach the conductor. Keyed by pane, since a worker that has not yet
334
+ * reported a conversation has no session. */
335
+ leaseDispatch(targets: readonly {
336
+ server: string;
337
+ pane: string;
338
+ source: string;
339
+ }[]): void;
340
+ private dispatchLeased;
341
+ private dropForwardedDialog;
342
+ /** What this pane's worker is waiting on, for the dispatching Hook: the held
343
+ * or app-server request, else the terminal dialog the pane draws (offered
344
+ * under a `dialog-` action the answer route accepts). */
345
+ workerApproval(target: Target): ForwardedApproval | undefined;
346
+ /** A worker's request on another computer, sent to this Hook's own phone:
347
+ * the notification's answer calls `answer`, which sends it back over the
348
+ * dispatch path. */
349
+ pushForwarded(summary: {
350
+ provider: string;
351
+ computer: string;
352
+ project?: string;
353
+ request: string;
354
+ requestKind?: RequestKind;
355
+ }, answer: (decision: "approve" | "deny") => Promise<void>): void;
219
356
  private adoptReleasedHold;
220
357
  private dropDialogPush;
358
+ /** The dialog a pane's screen shows now. Codex draws "> 1. Yes, proceed (y)"
359
+ * rows and Copilot a boxed select with a cursor row, both answered by moving
360
+ * to a row; OpenCode's prompt is one row of options whose cursor is only a
361
+ * color; the other fallbacks number rows without a key in the label. */
362
+ private screenDialog;
221
363
  /** Approve picks the dialog's yes/allow row (else its first), Deny its
222
364
  * no/deny row (else Escape), typed as the pane's own keys. */
223
365
  private answerDialog;
224
366
  private dropPushBindings;
367
+ /** A server request from one of the Hook's own Codex app-servers: an
368
+ * approval card like a held PermissionRequest, pushed the same way, but
369
+ * with no hold timer. The request stays parked in Codex until someone
370
+ * answers it, here or in the pane's TUI (`codexResolved`). */
371
+ codexRequest(target: Target, request: PendingServerRequest, answer: (result: Json) => void): void;
372
+ /** Another client (the pane's TUI) answered the request, or this one declined it. */
373
+ codexResolved(target: Target, requestId: AppServerRequestId): void;
225
374
  start(): Promise<void>;
226
375
  close(): void;
227
376
  }
377
+ /** What a Stop payload says about the turn it ends: the harness's last
378
+ * assistant message (Claude, Codex) and, from Claude Code, the background
379
+ * tasks still in flight, which will wake the conversation again when they
380
+ * finish. Absent fields are left out, so the Hook falls back to the transcript. */
381
+ export declare function stopFacts(value: Json): {
382
+ background?: number;
383
+ reply?: string;
384
+ };
228
385
  export declare function agentHook(source: Provider): Promise<void>;