@gajae-code/coding-agent 0.19.3-nightly.20261030094347.41301593972.gf536b1010d4e → 0.19.3

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 (273) hide show
  1. package/CHANGELOG.md +238 -0
  2. package/dist/types/async/job-manager.d.ts +56 -18
  3. package/dist/types/cli/auth-token-file.d.ts +9 -0
  4. package/dist/types/cli/doctor/install-repairs.d.ts +1 -0
  5. package/dist/types/cli/doctor/types.d.ts +1 -0
  6. package/dist/types/cli/install-activation.d.ts +10 -1
  7. package/dist/types/cli/malloc-env-guard.d.ts +8 -0
  8. package/dist/types/cli/update-cli.d.ts +4 -1
  9. package/dist/types/config/atomic-yaml-patch.d.ts +34 -1
  10. package/dist/types/config/model-profile-activation.d.ts +40 -13
  11. package/dist/types/config/model-registry.d.ts +3 -0
  12. package/dist/types/config/models-config-schema.d.ts +4 -0
  13. package/dist/types/config/settings-schema.d.ts +49 -8
  14. package/dist/types/config/settings.d.ts +39 -5
  15. package/dist/types/config/task-delegation.d.ts +2 -0
  16. package/dist/types/extensibility/extensions/runner.d.ts +2 -0
  17. package/dist/types/extensibility/slash-commands.d.ts +14 -1
  18. package/dist/types/gjc-runtime/managed-owner-admission.d.ts +4 -12
  19. package/dist/types/gjc-runtime/managed-owner-binding.d.ts +164 -0
  20. package/dist/types/gjc-runtime/managed-owner-supervisor.d.ts +26 -33
  21. package/dist/types/gjc-runtime/owner-lifecycle-path.d.ts +21 -0
  22. package/dist/types/gjc-runtime/owner-lifecycle-root.d.ts +7 -0
  23. package/dist/types/gjc-runtime/session-state-sidecar.d.ts +8 -1
  24. package/dist/types/gjc-runtime/tmux-common.d.ts +10 -0
  25. package/dist/types/gjc-runtime/tmux-owner-isolation.d.ts +131 -5
  26. package/dist/types/gjc-runtime/tmux-sessions.d.ts +46 -0
  27. package/dist/types/gjc-runtime/ultragoal-owner-loss-recovery.d.ts +1 -1
  28. package/dist/types/harness-control-plane/session-lease.d.ts +29 -2
  29. package/dist/types/harness-control-plane/storage.d.ts +8 -0
  30. package/dist/types/main.d.ts +12 -0
  31. package/dist/types/memories/index.d.ts +7 -1
  32. package/dist/types/memories/storage.d.ts +1 -0
  33. package/dist/types/memory-backend/types.d.ts +6 -1
  34. package/dist/types/modes/components/model-selector.d.ts +11 -4
  35. package/dist/types/modes/components/notifications-settings-editor.d.ts +2 -166
  36. package/dist/types/modes/components/settings-defs.d.ts +2 -1
  37. package/dist/types/modes/components/settings-selector.d.ts +5 -2
  38. package/dist/types/modes/components/smart-routing-panel.d.ts +19 -14
  39. package/dist/types/modes/components/tool-execution.d.ts +6 -0
  40. package/dist/types/modes/controllers/goal-mode-controller.d.ts +5 -0
  41. package/dist/types/modes/controllers/selector-controller.d.ts +7 -59
  42. package/dist/types/plan-mode/state.d.ts +7 -0
  43. package/dist/types/runtime-mcp/config.d.ts +8 -0
  44. package/dist/types/runtime-mcp/manager.d.ts +43 -0
  45. package/dist/types/runtime-mcp/session-controls-grant.d.ts +7 -0
  46. package/dist/types/sdk/broker/broker.d.ts +33 -7
  47. package/dist/types/sdk/broker/lifecycle.d.ts +1 -0
  48. package/dist/types/sdk/broker/session-index.d.ts +2 -0
  49. package/dist/types/sdk/broker/session-scope.d.ts +31 -1
  50. package/dist/types/sdk/broker/spawn-authority.d.ts +19 -0
  51. package/dist/types/sdk/broker/spawn-substrate.d.ts +12 -1
  52. package/dist/types/sdk/bus/index.d.ts +5 -0
  53. package/dist/types/sdk/bus/notification-orchestration.d.ts +21 -3
  54. package/dist/types/sdk/bus/notification-service.d.ts +2 -1
  55. package/dist/types/sdk/bus/telegram-daemon-contract.d.ts +1 -1
  56. package/dist/types/sdk/cli/rows.d.ts +7 -0
  57. package/dist/types/sdk/extension-interaction.d.ts +108 -0
  58. package/dist/types/sdk/host/control/btw-ask.d.ts +19 -0
  59. package/dist/types/sdk/host/control/dispatch.d.ts +2 -0
  60. package/dist/types/sdk/host/control/index.d.ts +1 -0
  61. package/dist/types/sdk/host/control/operations.d.ts +7 -0
  62. package/dist/types/sdk/host/external-permissions.d.ts +47 -0
  63. package/dist/types/sdk/host/host.d.ts +8 -2
  64. package/dist/types/sdk/host/query/handlers.d.ts +1 -0
  65. package/dist/types/sdk/host/session-runtime.d.ts +13 -1
  66. package/dist/types/sdk/host/surface-policy.d.ts +2 -1
  67. package/dist/types/sdk/index.d.ts +11 -0
  68. package/dist/types/sdk/job-observation.d.ts +51 -0
  69. package/dist/types/sdk/lifecycle/service.d.ts +6 -1
  70. package/dist/types/sdk/notification-setup-contract.d.ts +169 -0
  71. package/dist/types/sdk/notification-setup.d.ts +54 -0
  72. package/dist/types/sdk/protocol/adapter-validation.d.ts +2 -0
  73. package/dist/types/sdk/router/session-router.d.ts +5 -0
  74. package/dist/types/sdk/routing-settings.d.ts +57 -0
  75. package/dist/types/sdk/session-list.d.ts +5 -0
  76. package/dist/types/sdk/session-recap.d.ts +50 -0
  77. package/dist/types/sdk/session.d.ts +14 -0
  78. package/dist/types/sdk/settings-catalog.d.ts +52 -0
  79. package/dist/types/sdk/workflow-gates.d.ts +9 -0
  80. package/dist/types/session/agent-session.d.ts +129 -15
  81. package/dist/types/session/client-bridge.d.ts +1 -0
  82. package/dist/types/session/internal/managed-session-storage.d.ts +6 -0
  83. package/dist/types/session/recap.d.ts +104 -0
  84. package/dist/types/session/session-manager.d.ts +51 -1
  85. package/dist/types/session/streaming-output.d.ts +9 -1
  86. package/dist/types/session/workflow-recovery-field-fence.d.ts +4 -0
  87. package/dist/types/session/yield-queue.d.ts +16 -0
  88. package/dist/types/task/executor.d.ts +2 -0
  89. package/dist/types/tools/auto-generated-guard.d.ts +8 -1
  90. package/dist/types/tools/bash.d.ts +1 -1
  91. package/dist/types/tools/grouped-file-tree.d.ts +21 -0
  92. package/dist/types/tools/image-gen.d.ts +6 -1
  93. package/dist/types/tools/index.d.ts +7 -0
  94. package/dist/types/tui/file-list.d.ts +0 -3
  95. package/dist/types/utils/gh.d.ts +5 -0
  96. package/dist/types/utils/herdr-core-status.d.ts +31 -0
  97. package/dist/types/utils/herdr-pane.d.ts +7 -0
  98. package/dist/types/utils/recap-generator.d.ts +41 -0
  99. package/dist/types/web/hardened-http.d.ts +41 -0
  100. package/dist/types/web/insane/url-guard.d.ts +2 -0
  101. package/package.json +7 -7
  102. package/scripts/generate-sdk-operation-inventory.ts +28 -1
  103. package/src/async/job-manager.ts +381 -41
  104. package/src/cli/auth-broker-cli.ts +11 -53
  105. package/src/cli/auth-gateway-cli.ts +13 -56
  106. package/src/cli/auth-token-file.ts +56 -0
  107. package/src/cli/customize-doctor.ts +40 -27
  108. package/src/cli/doctor/install-repairs.ts +36 -2
  109. package/src/cli/doctor/repairs.ts +1 -0
  110. package/src/cli/doctor/report.ts +2 -0
  111. package/src/cli/doctor/types.ts +1 -0
  112. package/src/cli/install-activation.ts +58 -1
  113. package/src/cli/malloc-env-guard.ts +11 -0
  114. package/src/cli/session-picker.ts +8 -2
  115. package/src/cli/setup-cli.ts +2 -0
  116. package/src/cli/update-cli.ts +48 -3
  117. package/src/cli-main.ts +2 -2
  118. package/src/cli-ordinary.ts +2 -2
  119. package/src/commands/harness.ts +16 -3
  120. package/src/config/atomic-yaml-patch.ts +439 -141
  121. package/src/config/machine-identity.ts +6 -2
  122. package/src/config/mcp-schema.json +1 -1
  123. package/src/config/model-profile-activation.ts +505 -248
  124. package/src/config/model-registry.ts +54 -2
  125. package/src/config/models-config-schema.ts +2 -0
  126. package/src/config/settings-schema.ts +52 -8
  127. package/src/config/settings.ts +640 -237
  128. package/src/config/task-delegation.ts +4 -1
  129. package/src/coordinator-mcp/question-gate-codec.ts +17 -5
  130. package/src/coordinator-mcp/server.ts +2 -0
  131. package/src/extensibility/extensions/runner.ts +6 -0
  132. package/src/extensibility/gjc-plugins/installer.ts +2 -1
  133. package/src/extensibility/plugins/marketplace/fetcher.ts +28 -119
  134. package/src/extensibility/slash-commands.ts +90 -16
  135. package/src/gjc-runtime/launch-tmux.ts +79 -23
  136. package/src/gjc-runtime/launch-worktree.ts +15 -3
  137. package/src/gjc-runtime/managed-owner-admission.ts +298 -212
  138. package/src/gjc-runtime/managed-owner-binding.ts +410 -0
  139. package/src/gjc-runtime/managed-owner-supervisor.ts +265 -112
  140. package/src/gjc-runtime/owner-lifecycle-path.ts +82 -0
  141. package/src/gjc-runtime/owner-lifecycle-root.ts +26 -0
  142. package/src/gjc-runtime/ralplan-current-final.ts +35 -15
  143. package/src/gjc-runtime/ralplan-runtime.ts +3 -0
  144. package/src/gjc-runtime/session-state-sidecar.ts +61 -28
  145. package/src/gjc-runtime/tmux-common.ts +28 -0
  146. package/src/gjc-runtime/tmux-owner-isolation.ts +1100 -111
  147. package/src/gjc-runtime/tmux-sessions.ts +293 -58
  148. package/src/gjc-runtime/ultragoal-change-set.ts +8 -1
  149. package/src/gjc-runtime/ultragoal-owner-loss-recovery.ts +1 -1
  150. package/src/harness-control-plane/finalize.ts +2 -0
  151. package/src/harness-control-plane/owner.ts +23 -1
  152. package/src/harness-control-plane/preserve.ts +7 -1
  153. package/src/harness-control-plane/session-lease.ts +357 -3
  154. package/src/harness-control-plane/storage.ts +61 -10
  155. package/src/hashline/execute.ts +13 -1
  156. package/src/internal-urls/docs-index.generated.ts +12 -12
  157. package/src/lsp/lspmux.ts +4 -0
  158. package/src/main.ts +44 -3
  159. package/src/master-mode/snapshot.ts +13 -1
  160. package/src/memories/index.ts +8 -1
  161. package/src/memories/storage.ts +1 -0
  162. package/src/memory-backend/types.ts +6 -1
  163. package/src/modes/acp/acp-agent.ts +28 -4
  164. package/src/modes/components/gjc-bundle-settings.ts +56 -14
  165. package/src/modes/components/model-selector.ts +98 -18
  166. package/src/modes/components/notifications-settings-editor.ts +68 -188
  167. package/src/modes/components/session-selector.ts +27 -5
  168. package/src/modes/components/settings-defs.ts +4 -10
  169. package/src/modes/components/settings-selector.ts +93 -66
  170. package/src/modes/components/smart-routing-panel.ts +363 -48
  171. package/src/modes/components/tool-execution.ts +388 -9
  172. package/src/modes/controllers/event-controller.ts +2 -1
  173. package/src/modes/controllers/extension-ui-controller.ts +2 -1
  174. package/src/modes/controllers/goal-mode-controller.ts +24 -0
  175. package/src/modes/controllers/plan-mode-controller.ts +11 -3
  176. package/src/modes/controllers/selector-controller.ts +127 -1242
  177. package/src/modes/interactive-mode.ts +44 -3
  178. package/src/modes/runtime-init.ts +2 -1
  179. package/src/modes/shared/agent-wire/approval-gate.ts +13 -2
  180. package/src/modes/shared/agent-wire/deep-interview-gate.ts +2 -4
  181. package/src/plan-mode/state.ts +17 -0
  182. package/src/prompts/system/master-mode.md +2 -0
  183. package/src/prompts/system/recap-system.md +5 -0
  184. package/src/prompts/system/system-prompt.md +5 -1
  185. package/src/prompts/tools/ask.md +4 -3
  186. package/src/runtime-mcp/config.ts +20 -1
  187. package/src/runtime-mcp/manager.ts +588 -45
  188. package/src/runtime-mcp/session-controls-grant.ts +24 -0
  189. package/src/sdk/acp/adapter.ts +14 -3
  190. package/src/sdk/broker/broker.ts +237 -23
  191. package/src/sdk/broker/lifecycle.ts +2 -0
  192. package/src/sdk/broker/session-index.ts +93 -19
  193. package/src/sdk/broker/session-scope.ts +81 -2
  194. package/src/sdk/broker/spawn-authority.ts +34 -5
  195. package/src/sdk/broker/spawn-substrate.ts +117 -18
  196. package/src/sdk/bus/chat-daemon-control.ts +2 -2
  197. package/src/sdk/bus/index.ts +77 -11
  198. package/src/sdk/bus/notification-orchestration.ts +141 -59
  199. package/src/sdk/bus/notification-service.ts +25 -23
  200. package/src/sdk/bus/telegram-daemon-contract.ts +1 -1
  201. package/src/sdk/cli/master-cli.ts +2 -2
  202. package/src/sdk/cli/rows.ts +9 -0
  203. package/src/sdk/cli/session-cli.ts +29 -4
  204. package/src/sdk/extension-interaction.ts +533 -0
  205. package/src/sdk/host/control/btw-ask.ts +49 -0
  206. package/src/sdk/host/control/dispatch.ts +12 -0
  207. package/src/sdk/host/control/index.ts +1 -0
  208. package/src/sdk/host/control/operations.ts +7 -0
  209. package/src/sdk/host/external-permissions.ts +332 -0
  210. package/src/sdk/host/host.ts +8 -2
  211. package/src/sdk/host/query/handlers.ts +9 -0
  212. package/src/sdk/host/sdk-surface-parity.test.ts +55 -1
  213. package/src/sdk/host/session-runtime.test.ts +142 -1
  214. package/src/sdk/host/session-runtime.ts +108 -28
  215. package/src/sdk/host/surface-policy.ts +11 -0
  216. package/src/sdk/index.ts +15 -0
  217. package/src/sdk/job-observation.ts +157 -0
  218. package/src/sdk/lifecycle/service.ts +15 -2
  219. package/src/sdk/notification-setup-contract.ts +181 -0
  220. package/src/sdk/notification-setup.ts +1151 -0
  221. package/src/sdk/protocol/adapter-validation.ts +6 -1
  222. package/src/sdk/protocol/operation-inventory.generated.json +239 -6
  223. package/src/sdk/protocol/operation-registry.ts +21 -3
  224. package/src/sdk/router/session-router.ts +12 -1
  225. package/src/sdk/routing-settings.ts +395 -0
  226. package/src/sdk/session-list.ts +37 -0
  227. package/src/sdk/session-recap.ts +121 -0
  228. package/src/sdk/session.ts +335 -23
  229. package/src/sdk/settings-catalog.ts +119 -0
  230. package/src/sdk/workflow-gates.ts +30 -0
  231. package/src/session/agent-session.ts +1880 -238
  232. package/src/session/client-bridge.ts +1 -1
  233. package/src/session/contribution-prep.ts +8 -1
  234. package/src/session/internal/managed-session-storage.ts +17 -3
  235. package/src/session/recap.ts +298 -0
  236. package/src/session/session-manager.ts +776 -121
  237. package/src/session/streaming-output.ts +69 -9
  238. package/src/session/workflow-recovery-field-fence.ts +27 -0
  239. package/src/session/yield-queue.ts +52 -1
  240. package/src/setup/provider-presets.json +3 -1
  241. package/src/slash-commands/builtin-registry.ts +124 -4
  242. package/src/ssh/connection-manager.ts +3 -2
  243. package/src/ssh/ssh-executor.ts +3 -0
  244. package/src/ssh/sshfs-mount.ts +5 -4
  245. package/src/task/executor.ts +3 -0
  246. package/src/task/index.ts +48 -19
  247. package/src/tools/ast-edit.ts +10 -47
  248. package/src/tools/ast-grep.ts +10 -45
  249. package/src/tools/auto-generated-guard.ts +21 -1
  250. package/src/tools/bash-allowed-prefixes.ts +2 -0
  251. package/src/tools/bash.ts +10 -4
  252. package/src/tools/bisect.ts +5 -0
  253. package/src/tools/browser/launch.ts +7 -2
  254. package/src/tools/browser/registry.ts +5 -0
  255. package/src/tools/grouped-file-tree.ts +86 -0
  256. package/src/tools/image-gen.ts +180 -174
  257. package/src/tools/index.ts +7 -0
  258. package/src/tools/json-tree.ts +2 -2
  259. package/src/tools/recipe/runners/cargo.ts +3 -0
  260. package/src/tools/recipe/runners/just.ts +3 -0
  261. package/src/tools/recipe/runners/task.ts +3 -0
  262. package/src/tools/search.ts +9 -48
  263. package/src/tools/tool-catalog.generated.ts +1 -1
  264. package/src/tui/file-list.ts +14 -3
  265. package/src/utils/gh.ts +14 -1
  266. package/src/utils/git.ts +1 -8
  267. package/src/utils/herdr-core-status.ts +156 -0
  268. package/src/utils/herdr-pane.ts +38 -26
  269. package/src/utils/recap-generator.ts +191 -0
  270. package/src/web/hardened-http.ts +183 -0
  271. package/src/web/insane/bridge.ts +2 -1
  272. package/src/web/insane/url-guard.ts +7 -2
  273. package/src/web/scrapers/youtube.ts +3 -0
@@ -0,0 +1,533 @@
1
+ import type { ExtensionUIContext, ExtensionUIDialogOptions } from "../extensibility/extensions/types";
2
+
3
+ export type ExtensionInteractionKind = "select" | "confirm" | "input" | "editor";
4
+ export type ExtensionInteractionPurpose = "interaction" | "workflow-approval";
5
+ export type ExtensionInteractionPayload =
6
+ | { kind: "select"; title: string; options: readonly string[]; initialIndex?: number; helpText?: string }
7
+ | { kind: "confirm"; title: string; message: string }
8
+ | { kind: "input"; title: string; placeholder?: string }
9
+ | { kind: "editor"; title: string; prefill?: string; promptStyle?: boolean };
10
+
11
+ export interface ExtensionInteractionRequest {
12
+ readonly sessionId: string;
13
+ readonly requestId: string;
14
+ readonly purpose: ExtensionInteractionPurpose;
15
+ readonly payload: ExtensionInteractionPayload;
16
+ }
17
+
18
+ export type ExtensionInteractionResult =
19
+ | { status: "answered"; value: string | boolean }
20
+ | { status: "cancelled"; reason: "user" | "aborted" | "timeout" | "disposed" };
21
+
22
+ export interface ExtensionInteractionNotification {
23
+ readonly sequence: number;
24
+ readonly message: string;
25
+ readonly type: "info" | "warning" | "error";
26
+ }
27
+
28
+ export interface ExtensionInteractionState {
29
+ readonly sessionId: string;
30
+ readonly connected: boolean;
31
+ readonly disposed: boolean;
32
+ readonly revision: number;
33
+ readonly pending: readonly ExtensionInteractionRequest[];
34
+ /** Notifications are transient. Reconnect restores only the most recent notification. */
35
+ readonly lastNotification?: ExtensionInteractionNotification;
36
+ }
37
+
38
+ export interface ExtensionInteractionAddress {
39
+ sessionId: string;
40
+ connectionId: string;
41
+ requestId: string;
42
+ }
43
+
44
+ export type ExtensionInteractionErrorCode =
45
+ | "unavailable"
46
+ | "disposed"
47
+ | "wrong-session"
48
+ | "stale-connection"
49
+ | "stale-request"
50
+ | "invalid-result"
51
+ | "invalid-request"
52
+ | "terminal-only"
53
+ | "capacity-exceeded";
54
+
55
+ export class ExtensionInteractionError extends Error {
56
+ constructor(
57
+ readonly code: ExtensionInteractionErrorCode,
58
+ message: string,
59
+ readonly alternative?: string,
60
+ ) {
61
+ super(message);
62
+ this.name = "ExtensionInteractionError";
63
+ }
64
+ }
65
+
66
+ /** Admission limits reject work explicitly; pending interactions are never evicted. */
67
+ export const EXTENSION_INTERACTION_LIMITS = Object.freeze({
68
+ pending: 64,
69
+ listeners: 256,
70
+ payloadBytes: 64 * 1024,
71
+ textBytes: 64 * 1024,
72
+ selectOptions: 1024,
73
+ });
74
+
75
+ const terminalMethods = [
76
+ "onTerminalInput",
77
+ "setStatus",
78
+ "setWorkingMessage",
79
+ "setWidget",
80
+ "setFooter",
81
+ "setHeader",
82
+ "setTitle",
83
+ "custom",
84
+ "setEditorText",
85
+ "pasteToEditor",
86
+ "getEditorText",
87
+ "setEditorComponent",
88
+ "theme",
89
+ "getAllThemes",
90
+ "getTheme",
91
+ "setTheme",
92
+ "getToolsExpanded",
93
+ "setToolsExpanded",
94
+ ] as const;
95
+
96
+ interface PendingInteraction {
97
+ request: ExtensionInteractionRequest;
98
+ resolve: (result: ExtensionInteractionResult) => void;
99
+ reject: (error: unknown) => void;
100
+ cleanup: () => void;
101
+ }
102
+
103
+ /**
104
+ * A host-owned bridge, not an execution authorization provider. Keep connection IDs private
105
+ * to the admitted renderer. Hosts must dispose before awaiting session.dispose(), so shutdown
106
+ * handlers cannot wait for a departed renderer. Registered session cleanup is only an idempotent
107
+ * safety net. Dispose on session switch; never rebind an instance to a session.
108
+ * Hosts install `ui` using the existing extension/hook/tool UI initialization hooks.
109
+ */
110
+ export class ExtensionInteractionService {
111
+ readonly #sessionId: string;
112
+ #connectionId: string | undefined;
113
+ #disposed = false;
114
+ #revision = 0;
115
+ #notificationSequence = 0;
116
+ #lastNotification: ExtensionInteractionNotification | undefined;
117
+ readonly #pending = new Map<string, PendingInteraction>();
118
+ readonly #listeners = new Set<(state: ExtensionInteractionState) => void>();
119
+ readonly ui: ExtensionUIContext;
120
+
121
+ constructor(sessionId: string) {
122
+ if (typeof sessionId !== "string" || !sessionId.trim() || Buffer.byteLength(sessionId) > 1024)
123
+ throw new ExtensionInteractionError("invalid-request", "A session ID of at most 1024 bytes is required");
124
+ this.#sessionId = sessionId;
125
+ const terminal = (method: string): never => {
126
+ throw new ExtensionInteractionError(
127
+ "terminal-only",
128
+ `${method} requires a terminal renderer`,
129
+ "Use select, confirm, input, editor or notify, or provide a terminal-owned UI context",
130
+ );
131
+ };
132
+ this.ui = {
133
+ select: async (title, options, dialogOptions) => {
134
+ this.#validateDialogOptions(dialogOptions);
135
+ const result = await this.request(
136
+ {
137
+ kind: "select",
138
+ title,
139
+ options,
140
+ initialIndex: dialogOptions?.initialIndex,
141
+ helpText: dialogOptions?.helpText,
142
+ },
143
+ dialogOptions,
144
+ );
145
+ return result.status === "answered" ? (result.value as string) : undefined;
146
+ },
147
+ confirm: async (title, message, dialogOptions) => {
148
+ this.#validateDialogOptions(dialogOptions);
149
+ const result = await this.request({ kind: "confirm", title, message }, dialogOptions);
150
+ return result.status === "answered" ? (result.value as boolean) : false;
151
+ },
152
+ input: async (title, placeholder, dialogOptions) => {
153
+ this.#validateDialogOptions(dialogOptions);
154
+ const result = await this.request({ kind: "input", title, placeholder }, dialogOptions);
155
+ return result.status === "answered" ? (result.value as string) : undefined;
156
+ },
157
+ editor: async (title, prefill, dialogOptions, editorOptions) => {
158
+ this.#validateDialogOptions(dialogOptions);
159
+ const result = await this.request(
160
+ { kind: "editor", title, prefill, promptStyle: editorOptions?.promptStyle },
161
+ dialogOptions,
162
+ );
163
+ return result.status === "answered" ? (result.value as string) : undefined;
164
+ },
165
+ notify: (message, type = "info") => this.notify(message, type),
166
+ onTerminalInput: () => terminal("onTerminalInput"),
167
+ setStatus: () => terminal("setStatus"),
168
+ setWorkingMessage: () => terminal("setWorkingMessage"),
169
+ setWidget: () => terminal("setWidget"),
170
+ setFooter: () => terminal("setFooter"),
171
+ setHeader: () => terminal("setHeader"),
172
+ setTitle: () => terminal("setTitle"),
173
+ custom: async () => terminal("custom"),
174
+ setEditorText: () => terminal("setEditorText"),
175
+ pasteToEditor: () => terminal("pasteToEditor"),
176
+ getEditorText: () => terminal("getEditorText"),
177
+ setEditorComponent: () => terminal("setEditorComponent"),
178
+ get theme() {
179
+ return terminal("theme");
180
+ },
181
+ getAllThemes: async () => terminal("getAllThemes"),
182
+ getTheme: async () => terminal("getTheme"),
183
+ setTheme: async () => terminal("setTheme"),
184
+ getToolsExpanded: () => terminal("getToolsExpanded"),
185
+ setToolsExpanded: () => terminal("setToolsExpanded"),
186
+ };
187
+ }
188
+
189
+ capabilities() {
190
+ return {
191
+ portable: ["select", "confirm", "input", "editor", "notify"] as const,
192
+ available: !this.#disposed && this.#connectionId !== undefined,
193
+ unavailableReason: this.#disposed ? "disposed" : this.#connectionId ? undefined : "renderer-disconnected",
194
+ terminalOnly: terminalMethods.map(method => ({
195
+ method,
196
+ reason: "terminal-only" as const,
197
+ alternative: "Use portable interactions or a terminal-owned UI context",
198
+ })),
199
+ grantsExecutionPermission: false as const,
200
+ };
201
+ }
202
+
203
+ /** Rotates responder authority; pending requests survive transport reconnection. */
204
+ connect(): { connectionId: string; state: ExtensionInteractionState } {
205
+ this.#assertAlive();
206
+ const connectionId = crypto.randomUUID();
207
+ this.#connectionId = connectionId;
208
+ this.#changed();
209
+ return { connectionId, state: this.snapshot() };
210
+ }
211
+
212
+ disconnect(connectionId: string): void {
213
+ this.#assertConnection(connectionId);
214
+ this.#connectionId = undefined;
215
+ this.#changed();
216
+ }
217
+
218
+ snapshot(): ExtensionInteractionState {
219
+ return structuredClone({
220
+ sessionId: this.#sessionId,
221
+ connected: this.#connectionId !== undefined,
222
+ disposed: this.#disposed,
223
+ revision: this.#revision,
224
+ pending: [...this.#pending.values()].map(item => item.request),
225
+ lastNotification: this.#lastNotification,
226
+ });
227
+ }
228
+
229
+ /** Listeners observe state only, never responder credentials. Throwing listeners are removed. */
230
+ subscribe(listener: (state: ExtensionInteractionState) => void): () => void {
231
+ this.#assertAlive();
232
+ if (!this.#listeners.has(listener) && this.#listeners.size >= EXTENSION_INTERACTION_LIMITS.listeners)
233
+ throw new ExtensionInteractionError("capacity-exceeded", "Too many interaction listeners");
234
+ this.#listeners.add(listener);
235
+ return () => this.#listeners.delete(listener);
236
+ }
237
+
238
+ request(
239
+ payload: ExtensionInteractionPayload,
240
+ options: Pick<ExtensionUIDialogOptions, "signal" | "timeout" | "onTimeout"> = {},
241
+ purpose: ExtensionInteractionPurpose = "interaction",
242
+ ): Promise<ExtensionInteractionResult> {
243
+ this.#assertAvailable();
244
+ const detachedPayload = this.#detachPayload(payload);
245
+ // Cloning can invoke caller getters, which may reenter and disconnect or dispose the service.
246
+ this.#assertAvailable();
247
+ if (!["interaction", "workflow-approval"].includes(purpose)) {
248
+ throw new ExtensionInteractionError("invalid-request", "Interactions cannot grant execution permission");
249
+ }
250
+ let timeout: number | undefined;
251
+ let signal: AbortSignal | undefined;
252
+ let onTimeout: (() => void) | undefined;
253
+ let aborted = false;
254
+ const abortedGetter = Object.getOwnPropertyDescriptor(AbortSignal.prototype, "aborted")!.get!;
255
+ try {
256
+ // Each caller-controlled option is read exactly once, before the final admission check.
257
+ timeout = options.timeout;
258
+ signal = options.signal;
259
+ onTimeout = options.onTimeout;
260
+ if (signal !== undefined) aborted = abortedGetter.call(signal);
261
+ } catch {
262
+ throw new ExtensionInteractionError("invalid-request", "Invalid interaction options");
263
+ }
264
+ if (
265
+ timeout !== undefined &&
266
+ (typeof timeout !== "number" || !Number.isFinite(timeout) || timeout < 0 || timeout > 2_147_483_647)
267
+ ) {
268
+ throw new ExtensionInteractionError("invalid-request", "Timeout must be a finite nonnegative timer duration");
269
+ }
270
+ if (onTimeout !== undefined && typeof onTimeout !== "function")
271
+ throw new ExtensionInteractionError("invalid-request", "Invalid interaction options");
272
+ this.#assertAvailable();
273
+ if (aborted) return Promise.resolve({ status: "cancelled", reason: "aborted" });
274
+ if (this.#pending.size >= EXTENSION_INTERACTION_LIMITS.pending)
275
+ throw new ExtensionInteractionError("capacity-exceeded", "Too many pending interactions");
276
+ const requestId = crypto.randomUUID();
277
+ const { promise, resolve, reject } = Promise.withResolvers<ExtensionInteractionResult>();
278
+ const abort = () => this.#finish(requestId, { status: "cancelled", reason: "aborted" });
279
+ let timer: Timer | undefined;
280
+ const removeAbortListener = () => {
281
+ if (!signal) return;
282
+ try {
283
+ EventTarget.prototype.removeEventListener.call(signal, "abort", abort);
284
+ } catch {
285
+ // A host wrapper must not replace the request's settlement or admission error.
286
+ }
287
+ };
288
+ const item: PendingInteraction = {
289
+ request: { sessionId: this.#sessionId, requestId, purpose, payload: detachedPayload },
290
+ resolve,
291
+ reject,
292
+ cleanup: () => {
293
+ if (timer !== undefined) clearTimeout(timer);
294
+ removeAbortListener();
295
+ },
296
+ };
297
+ this.#pending.set(requestId, item);
298
+ if (signal) {
299
+ // Use native EventTarget methods rather than caller-overridden signal methods.
300
+ try {
301
+ EventTarget.prototype.addEventListener.call(signal, "abort", abort, { once: true });
302
+ } catch {
303
+ const removed = this.#pending.delete(requestId);
304
+ removeAbortListener();
305
+ if (!removed) return promise;
306
+ this.#changed();
307
+ throw new ExtensionInteractionError("invalid-request", "Invalid interaction signal");
308
+ }
309
+ if (!this.#pending.has(requestId)) {
310
+ // Settlement can reenter while a host wraps registration, before it actually attaches.
311
+ removeAbortListener();
312
+ return promise;
313
+ }
314
+ if (abortedGetter.call(signal)) {
315
+ abort();
316
+ return promise;
317
+ }
318
+ try {
319
+ this.#assertAvailable();
320
+ } catch (error) {
321
+ this.#pending.delete(requestId);
322
+ item.cleanup();
323
+ this.#changed();
324
+ throw error;
325
+ }
326
+ }
327
+ if (timeout !== undefined) {
328
+ timer = setTimeout(() => {
329
+ this.#finish(requestId, { status: "cancelled", reason: "timeout" }, onTimeout);
330
+ }, timeout);
331
+ }
332
+ this.#changed();
333
+ return promise;
334
+ }
335
+
336
+ respond(address: ExtensionInteractionAddress, value: string | boolean): { grantsExecutionPermission: false } {
337
+ const item = this.#lookup(address);
338
+ const payload = item.request.payload;
339
+ if (
340
+ payload.kind === "confirm"
341
+ ? typeof value !== "boolean"
342
+ : typeof value !== "string" ||
343
+ Buffer.byteLength(value) > EXTENSION_INTERACTION_LIMITS.textBytes ||
344
+ (payload.kind === "select" && !payload.options.includes(value))
345
+ ) {
346
+ throw new ExtensionInteractionError("invalid-result", "Response does not match the pending interaction");
347
+ }
348
+ this.#finish(item.request.requestId, { status: "answered", value });
349
+ return { grantsExecutionPermission: false };
350
+ }
351
+
352
+ cancel(address: ExtensionInteractionAddress): void {
353
+ const item = this.#lookup(address);
354
+ this.#finish(item.request.requestId, { status: "cancelled", reason: "user" });
355
+ }
356
+
357
+ notify(message: string, type: "info" | "warning" | "error" = "info"): void {
358
+ this.#assertAvailable();
359
+ if (
360
+ typeof message !== "string" ||
361
+ Buffer.byteLength(message) > EXTENSION_INTERACTION_LIMITS.textBytes ||
362
+ !["info", "warning", "error"].includes(type)
363
+ ) {
364
+ throw new ExtensionInteractionError("invalid-request", "Notification requires text and a supported severity");
365
+ }
366
+ this.#lastNotification = { sequence: ++this.#notificationSequence, message, type };
367
+ this.#changed();
368
+ }
369
+
370
+ dispose(): void {
371
+ if (this.#disposed) return;
372
+ this.#disposed = true;
373
+ this.#connectionId = undefined;
374
+ for (const [id, item] of this.#pending) {
375
+ this.#pending.delete(id);
376
+ item.cleanup();
377
+ item.resolve({ status: "cancelled", reason: "disposed" });
378
+ }
379
+ this.#lastNotification = undefined;
380
+ this.#changed();
381
+ this.#listeners.clear();
382
+ }
383
+
384
+ #detachPayload(input: ExtensionInteractionPayload): ExtensionInteractionPayload {
385
+ const invalid = (): never => {
386
+ throw new ExtensionInteractionError("invalid-request", "Invalid portable interaction payload");
387
+ };
388
+ let payload: ExtensionInteractionPayload;
389
+ try {
390
+ payload = structuredClone(input);
391
+ } catch {
392
+ return invalid();
393
+ }
394
+ if (!payload || typeof payload !== "object" || Array.isArray(payload)) return invalid();
395
+ const own = (key: string) => Object.hasOwn(payload, key);
396
+ if (!own("title") || typeof payload.title !== "string" || !own("kind")) return invalid();
397
+ let allowed: readonly string[] = [];
398
+ switch (payload.kind) {
399
+ case "select":
400
+ allowed = ["kind", "title", "options", "initialIndex", "helpText"];
401
+ if (
402
+ !own("options") ||
403
+ !Array.isArray(payload.options) ||
404
+ payload.options.length === 0 ||
405
+ payload.options.length > EXTENSION_INTERACTION_LIMITS.selectOptions ||
406
+ Object.keys(payload.options).length !== payload.options.length
407
+ )
408
+ return invalid();
409
+ for (let i = 0; i < payload.options.length; i++) {
410
+ if (!Object.hasOwn(payload.options, i) || typeof payload.options[i] !== "string") return invalid();
411
+ }
412
+ if (
413
+ own("initialIndex") &&
414
+ payload.initialIndex !== undefined &&
415
+ (!Number.isInteger(payload.initialIndex) ||
416
+ payload.initialIndex < 0 ||
417
+ payload.initialIndex >= payload.options.length)
418
+ )
419
+ invalid();
420
+ if (own("helpText") && payload.helpText !== undefined && typeof payload.helpText !== "string") invalid();
421
+ break;
422
+ case "confirm":
423
+ allowed = ["kind", "title", "message"];
424
+ if (!own("message") || typeof payload.message !== "string") invalid();
425
+ break;
426
+ case "input":
427
+ allowed = ["kind", "title", "placeholder"];
428
+ if (own("placeholder") && payload.placeholder !== undefined && typeof payload.placeholder !== "string")
429
+ invalid();
430
+ break;
431
+ case "editor":
432
+ allowed = ["kind", "title", "prefill", "promptStyle"];
433
+ if (own("prefill") && payload.prefill !== undefined && typeof payload.prefill !== "string") invalid();
434
+ if (own("promptStyle") && payload.promptStyle !== undefined && typeof payload.promptStyle !== "boolean")
435
+ invalid();
436
+ break;
437
+ default:
438
+ invalid();
439
+ }
440
+ // Serialize only validated own data, without invoking inherited toJSON or array iterators.
441
+ const fields: string[] = [];
442
+ for (const key of Object.keys(payload)) {
443
+ if (!allowed.includes(key)) return invalid();
444
+ const value = (payload as unknown as Record<string, unknown>)[key];
445
+ if (value === undefined) continue;
446
+ let encoded: string;
447
+ if (key === "options" && Array.isArray(value)) {
448
+ const entries: string[] = [];
449
+ for (let i = 0; i < value.length; i++) entries.push(JSON.stringify(value[i]));
450
+ encoded = `[${entries.join(",")}]`;
451
+ } else {
452
+ encoded = JSON.stringify(value)!;
453
+ }
454
+ fields.push(`${JSON.stringify(key)}:${encoded}`);
455
+ }
456
+ if (Buffer.byteLength(`{${fields.join(",")}}`) > EXTENSION_INTERACTION_LIMITS.payloadBytes) return invalid();
457
+ return payload;
458
+ }
459
+
460
+ #validateDialogOptions(options?: ExtensionUIDialogOptions): void {
461
+ if (
462
+ options?.onLeft ||
463
+ options?.onRight ||
464
+ options?.onExternalEditor ||
465
+ options?.customInput ||
466
+ options?.clarificationInput
467
+ ) {
468
+ throw new ExtensionInteractionError(
469
+ "terminal-only",
470
+ "Dialog callbacks require a terminal renderer",
471
+ "Use a follow-up portable input or select request",
472
+ );
473
+ }
474
+ }
475
+
476
+ #assertAlive(): void {
477
+ if (this.#disposed) throw new ExtensionInteractionError("disposed", "Interaction session is disposed");
478
+ }
479
+
480
+ #assertAvailable(): void {
481
+ this.#assertAlive();
482
+ if (!this.#connectionId) throw new ExtensionInteractionError("unavailable", "No admitted renderer is connected");
483
+ }
484
+
485
+ #assertConnection(connectionId: string): void {
486
+ this.#assertAlive();
487
+ if (!this.#connectionId || connectionId !== this.#connectionId)
488
+ throw new ExtensionInteractionError("stale-connection", "Renderer connection is stale");
489
+ }
490
+
491
+ #lookup(address: ExtensionInteractionAddress): PendingInteraction {
492
+ this.#assertAlive();
493
+ const { sessionId, connectionId, requestId } = address;
494
+ // Accessors may synchronously disconnect, rotate or dispose the renderer.
495
+ // Validate only after extracting the complete address, with no later caller reads.
496
+ this.#assertAlive();
497
+ if (sessionId !== this.#sessionId)
498
+ throw new ExtensionInteractionError("wrong-session", "Interaction belongs to another session");
499
+ this.#assertConnection(connectionId);
500
+ const item = this.#pending.get(requestId);
501
+ if (!item) throw new ExtensionInteractionError("stale-request", "Interaction is no longer pending");
502
+ return item;
503
+ }
504
+
505
+ #finish(requestId: string, result: ExtensionInteractionResult, onTimeout?: () => void): void {
506
+ const item = this.#pending.get(requestId);
507
+ if (!item) return;
508
+ this.#pending.delete(requestId);
509
+ item.cleanup();
510
+ try {
511
+ onTimeout?.();
512
+ item.resolve(result);
513
+ } catch (error) {
514
+ item.reject(error);
515
+ }
516
+ this.#changed();
517
+ }
518
+
519
+ #changed(): void {
520
+ const revision = ++this.#revision;
521
+ for (const listener of [...this.#listeners]) {
522
+ // A reentrant mutation already delivered a newer state. Never replay that state
523
+ // as the old event, or invoke a listener removed during another callback.
524
+ if (this.#revision !== revision) break;
525
+ if (!this.#listeners.has(listener)) continue;
526
+ try {
527
+ listener(this.snapshot());
528
+ } catch {
529
+ this.#listeners.delete(listener);
530
+ }
531
+ }
532
+ }
533
+ }
@@ -0,0 +1,49 @@
1
+ import { BTW_MAX_QUESTION_UTF8_BYTES, utf8ByteLength } from "../../../session/btw-contract";
2
+ import { BusyError } from "./dispatch";
3
+
4
+ /** Session-owned ephemeral side-question runner (`/btw`); absent when the host has none. */
5
+ export type EphemeralQuestionRunner = (question: string, signal?: AbortSignal) => Promise<string>;
6
+
7
+ /**
8
+ * Builds the `btw.ask` (C60) handler shared by both session host surfaces (the
9
+ * SDK-only runtime host and the notifications-hosted SDK server).
10
+ *
11
+ * `btw.ask` owns no turn and appends nothing to the session transcript, so it
12
+ * enforces its own single-flight admission instead of relying on turn
13
+ * admission. The registry marks the operation `fast_lane`, so dispatch never
14
+ * queues it behind the ordered per-surface chain and a second concurrent
15
+ * question reaches this guard while the first is still answering.
16
+ *
17
+ * A question outside the `/btw` contract is refused as `invalid_input`, a
18
+ * second in-flight question as the typed `busy`, and a host without the runner
19
+ * seam as `unavailable` — never by admitting side work into turn state.
20
+ */
21
+ export function createBtwAskHandler(
22
+ runner: EphemeralQuestionRunner | undefined,
23
+ ): (question: string, signal?: AbortSignal) => Promise<{ reply: string }> {
24
+ let questionInFlight = false;
25
+ return async (question, signal) => {
26
+ if (typeof question !== "string" || question.trim().length === 0)
27
+ throw Object.assign(new Error("btw.ask requires a nonempty question."), { code: "invalid_input" });
28
+ if (utf8ByteLength(question) > BTW_MAX_QUESTION_UTF8_BYTES)
29
+ throw Object.assign(
30
+ new Error(`btw.ask questions are limited to ${BTW_MAX_QUESTION_UTF8_BYTES} UTF-8 bytes.`),
31
+ { code: "invalid_input" },
32
+ );
33
+ if (!runner)
34
+ throw Object.assign(new Error("btw.ask is unavailable without an installed session seam."), {
35
+ code: "unavailable",
36
+ });
37
+ if (questionInFlight) throw new BusyError("A /btw question is already running. Wait for it to finish.");
38
+ signal?.throwIfAborted();
39
+ questionInFlight = true;
40
+ try {
41
+ const reply = await runner(question.trim(), signal);
42
+ if (typeof reply !== "string")
43
+ throw Object.assign(new Error("The /btw runner returned an invalid reply."), { code: "unavailable" });
44
+ return { reply: reply.trim() };
45
+ } finally {
46
+ questionInFlight = false;
47
+ }
48
+ };
49
+ }
@@ -21,6 +21,8 @@ export interface ControlRequest {
21
21
  expectedRevision?: string;
22
22
  idempotencyKey?: string;
23
23
  confirm?: boolean;
24
+ /** Internal request lifetime; never populated from a wire frame. */
25
+ signal?: AbortSignal;
24
26
  }
25
27
 
26
28
  export type ControlErrorCode = string;
@@ -253,6 +255,7 @@ function invoke(
253
255
  input: ControlInput,
254
256
  confirm: boolean | undefined,
255
257
  idempotencyKey: string | undefined,
258
+ signal: AbortSignal | undefined,
256
259
  ): Promise<ControlValue> | ControlValue {
257
260
  switch (operation) {
258
261
  case "turn.prompt":
@@ -318,6 +321,12 @@ function invoke(
318
321
  return surface.cycleThinking();
319
322
  case "permission_mode.set":
320
323
  return surface.setPermissionMode(input.mode);
324
+ case "permission.channel.set":
325
+ if (!surface.configurePermissionChannel) invalidInput("External permissions are unavailable.");
326
+ return surface.configurePermissionChannel(input);
327
+ case "permission.respond":
328
+ if (!surface.respondPermission) invalidInput("External permissions are unavailable.");
329
+ return surface.respondPermission(input);
321
330
  case "queue.steering_mode.set":
322
331
  return surface.setQueueMode("steering", input.mode);
323
332
  case "queue.follow_up_mode.set":
@@ -377,6 +386,8 @@ function invoke(
377
386
  return surface.retryNow();
378
387
  case "bash.background":
379
388
  return surface.backgroundBash();
389
+ case "btw.ask":
390
+ return surface.askBtw(text(input, "question"), signal);
380
391
  default:
381
392
  throw new Error("unknown operation");
382
393
  }
@@ -431,6 +442,7 @@ async function execute(surface: ControlSurface, row: Operation, request: Control
431
442
  request.input as ControlInput,
432
443
  request.confirm,
433
444
  request.idempotencyKey,
445
+ request.signal,
434
446
  ),
435
447
  };
436
448
  } catch (error) {
@@ -1,3 +1,4 @@
1
+ export { createBtwAskHandler, type EphemeralQuestionRunner } from "./btw-ask";
1
2
  export {
2
3
  BusyError,
3
4
  type ControlError,
@@ -55,6 +55,8 @@ export interface ControlSurface {
55
55
  setThinking(level: ControlValue): Promise<ControlValue> | ControlValue;
56
56
  cycleThinking(): Promise<ControlValue> | ControlValue;
57
57
  setPermissionMode(mode: ControlValue): Promise<ControlValue> | ControlValue;
58
+ configurePermissionChannel?(input: ControlInput): Promise<ControlValue> | ControlValue;
59
+ respondPermission?(input: ControlInput): ControlValue;
58
60
  setQueueMode(kind: string, mode: ControlValue): Promise<ControlValue> | ControlValue;
59
61
  runCompaction(): Promise<ControlValue> | ControlValue;
60
62
  setAutoCompaction(on: boolean): Promise<ControlValue> | ControlValue;
@@ -88,6 +90,11 @@ export interface ControlSurface {
88
90
  retryLast(): Promise<ControlValue> | ControlValue;
89
91
  retryNow(): Promise<ControlValue> | ControlValue;
90
92
  backgroundBash(): Promise<ControlValue> | ControlValue;
93
+ /**
94
+ * Ephemeral side question (`/btw`): answers from the current session context
95
+ * without owning a turn or appending anything to the session transcript.
96
+ */
97
+ askBtw(question: string, signal?: AbortSignal): Promise<ControlValue> | ControlValue;
91
98
  /** Returns the current revision for a registry revision resource. */
92
99
  /** Installed per-session registry rows. Dispatch rejects other rows before invoking a surface method. */
93
100
  installedOperations?: ReadonlySet<string>;