The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import { |
| 2 | isOrchestrationV2WorkActive, |
| 3 | OrchestrationV2CommandOutputError, |
| 4 | type OrchestrationV2CommandOutputFrame, |
| 5 | type OrchestrationV2SubscribeCommandOutputInput, |
| 6 | type OrchestrationV2TurnItem, |
| 7 | } from "@t3tools/contracts"; |
| 8 | import { |
| 9 | appendTerminalOutput, |
| 10 | EMPTY_TERMINAL_OUTPUT, |
| 11 | normalizeTerminalOutput, |
| 12 | type TerminalOutputState, |
| 13 | TERMINAL_OUTPUT_TAIL_CHARS, |
| 14 | terminalOutputResumeText, |
| 15 | } from "@t3tools/shared/terminalOutput"; |
| 16 | import { commandItemOutput } from "@t3tools/shared/commandOutput"; |
| 17 | import * as Cause from "effect/Cause"; |
| 18 | import * as Clock from "effect/Clock"; |
| 19 | import * as Context from "effect/Context"; |
| 20 | import * as Effect from "effect/Effect"; |
| 21 | import * as Layer from "effect/Layer"; |
| 22 | import * as Queue from "effect/Queue"; |
| 23 | import * as Schema from "effect/Schema"; |
| 24 | import * as Stream from "effect/Stream"; |
| 25 | |
| 26 | import * as EventSink from "./EventSink.ts"; |
| 27 | import * as ProjectionStore from "./ProjectionStore.ts"; |
| 28 | |
| 29 | /** Output bypasses orchestration events; expanded rows receive tails, coalesced appends, then persisted output. */ |
| 30 | |
| 31 | /** Fastest a subscriber receives frames while output flows. */ |
| 32 | const COMMAND_OUTPUT_FRAME_INTERVAL_MS = 100; |
| 33 | /** After a subscriber falls behind and is sent the whole tail, it waits this long. */ |
| 34 | const COMMAND_OUTPUT_REPLACE_INTERVAL_MS = 500; |
| 35 | /** Raw text a subscriber may accumulate before it is sent the tail instead. */ |
| 36 | const COMMAND_OUTPUT_MAX_APPEND_CHARS = 16 * 1024; |
| 37 | /** Evict the least recently written command beyond this limit. */ |
| 38 | const MAX_LIVE_COMMANDS = 64; |
| 39 | /** Retain finished tails for settlements that omit output. */ |
| 40 | const MAX_FINISHED_COMMANDS = 16; |
| 41 | const MAX_FINAL_SOURCE_CHARS = TERMINAL_OUTPUT_TAIL_CHARS * 4; |
| 42 | |
| 43 | interface Subscriber { |
| 44 | pendingAppend: string; |
| 45 | needsReplace: boolean; |
| 46 | /** `needsReplace` was caused by the subscriber falling behind. */ |
| 47 | overflowed: boolean; |
| 48 | readonly wake: Queue.Queue<void>; |
| 49 | } |
| 50 | |
| 51 | export type CommandOutputTarget = OrchestrationV2SubscribeCommandOutputInput; |
| 52 | |
| 53 | export interface CommandOutputHubShape { |
| 54 | readonly append: (input: CommandOutputTarget & { readonly chunk: string }) => Effect.Effect<void>; |
| 55 | /** Retains the tail briefly for settlements without output; otherwise rows use persisted output. */ |
| 56 | readonly finish: (input: CommandOutputTarget) => Effect.Effect<void>; |
| 57 | readonly subscribe: ( |
| 58 | input: CommandOutputTarget, |
| 59 | ) => Stream.Stream<OrchestrationV2CommandOutputFrame, OrchestrationV2CommandOutputError>; |
| 60 | } |
| 61 | |
| 62 | export class CommandOutputHub extends Context.Service<CommandOutputHub, CommandOutputHubShape>()( |
| 63 | "t3/orchestration-v2/CommandOutputHub", |
| 64 | ) {} |
| 65 | |
| 66 | const isCommandOutputError = Schema.is(OrchestrationV2CommandOutputError); |
| 67 | |
| 68 | function commandKey(target: CommandOutputTarget): string { |
| 69 | return `${target.threadId}\u0000${target.itemId}`; |
| 70 | } |
| 71 | |
| 72 | function persistedCommandOutput(output: string | undefined): { |
| 73 | readonly text: string; |
| 74 | readonly truncated: boolean; |
| 75 | } { |
| 76 | if (output === undefined) return { text: "", truncated: false }; |
| 77 | let source = output; |
| 78 | if (output.length > MAX_FINAL_SOURCE_CHARS) { |
| 79 | // Cut at a newline to avoid splitting escape sequences. |
| 80 | source = output.slice(output.length - MAX_FINAL_SOURCE_CHARS); |
| 81 | const newline = source.indexOf("\n"); |
| 82 | if (newline !== -1 && newline + 1 < source.length) source = source.slice(newline + 1); |
| 83 | } |
| 84 | const normalized = normalizeTerminalOutput(source); |
| 85 | return { |
| 86 | text: normalized.text, |
| 87 | truncated: normalized.truncated || source.length !== output.length, |
| 88 | }; |
| 89 | } |
| 90 | |
| 91 | function setBounded<V>( |
| 92 | map: Map<string, V>, |
| 93 | key: string, |
| 94 | value: V, |
| 95 | max: number, |
| 96 | onEvict?: (key: string) => void, |
| 97 | ): void { |
| 98 | map.delete(key); |
| 99 | map.set(key, value); |
| 100 | if (map.size <= max) return; |
| 101 | const oldest = map.keys().next().value!; |
| 102 | map.delete(oldest); |
| 103 | onEvict?.(oldest); |
| 104 | } |
| 105 | |
| 106 | export const make = Effect.gen(function* () { |
| 107 | const eventSink = yield* EventSink.EventSinkV2; |
| 108 | const projections = yield* ProjectionStore.ProjectionStoreV2; |
| 109 | const tails = new Map<string, TerminalOutputState>(); |
| 110 | const finished = new Map<string, TerminalOutputState>(); |
| 111 | const subscribers = new Map<string, Set<Subscriber>>(); |
| 112 | |
| 113 | const wakeAll = (key: string, chunk: string) => |
| 114 | Effect.forEach( |
| 115 | subscribers.get(key) ?? [], |
| 116 | (subscriber) => { |
| 117 | if (!subscriber.needsReplace) { |
| 118 | subscriber.pendingAppend += chunk; |
| 119 | if (subscriber.pendingAppend.length > COMMAND_OUTPUT_MAX_APPEND_CHARS) { |
| 120 | subscriber.needsReplace = true; |
| 121 | subscriber.overflowed = true; |
| 122 | subscriber.pendingAppend = ""; |
| 123 | } |
| 124 | } |
| 125 | return Queue.offer(subscriber.wake, undefined); |
| 126 | }, |
| 127 | { discard: true }, |
| 128 | ); |
| 129 | |
| 130 | const append: CommandOutputHubShape["append"] = ({ chunk, ...target }) => |
| 131 | Effect.suspend(() => { |
| 132 | if (chunk.length === 0) return Effect.void; |
| 133 | const key = commandKey(target); |
| 134 | const tail = appendTerminalOutput(tails.get(key) ?? EMPTY_TERMINAL_OUTPUT, chunk); |
| 135 | setBounded(tails, key, tail, MAX_LIVE_COMMANDS, (oldest) => { |
| 136 | // Eviction invalidates viewers' state; resync on their next frame. |
| 137 | for (const subscriber of subscribers.get(oldest) ?? []) { |
| 138 | subscriber.needsReplace = true; |
| 139 | subscriber.pendingAppend = ""; |
| 140 | } |
| 141 | }); |
| 142 | return wakeAll(key, chunk); |
| 143 | }); |
| 144 | |
| 145 | const finish: CommandOutputHubShape["finish"] = (target) => |
| 146 | Effect.sync(() => { |
| 147 | const key = commandKey(target); |
| 148 | const tail = tails.get(key); |
| 149 | if (tail === undefined) return; |
| 150 | tails.delete(key); |
| 151 | setBounded(finished, key, tail, MAX_FINISHED_COMMANDS); |
| 152 | }); |
| 153 | |
| 154 | const subscribe: CommandOutputHubShape["subscribe"] = (target) => |
| 155 | Stream.unwrap( |
| 156 | Effect.gen(function* () { |
| 157 | const key = commandKey(target); |
| 158 | const wake = yield* Queue.sliding<void>(1); |
| 159 | const subscriber: Subscriber = { |
| 160 | pendingAppend: "", |
| 161 | needsReplace: true, |
| 162 | overflowed: false, |
| 163 | wake, |
| 164 | }; |
| 165 | // Subscribe before reading to avoid losing intervening chunks. |
| 166 | const keySubscribers = subscribers.get(key) ?? new Set<Subscriber>(); |
| 167 | keySubscribers.add(subscriber); |
| 168 | subscribers.set(key, keySubscribers); |
| 169 | yield* Effect.addFinalizer(() => |
| 170 | Effect.sync(() => { |
| 171 | keySubscribers.delete(subscriber); |
| 172 | if (keySubscribers.size === 0 && subscribers.get(key) === keySubscribers) { |
| 173 | subscribers.delete(key); |
| 174 | } |
| 175 | }), |
| 176 | ); |
| 177 | |
| 178 | // Persisted items provide settlement and final output; snapshot-only providers (ACP, Pi) also stream here. |
| 179 | let snapshotOutput: string | undefined; |
| 180 | let lost: Cause.Cause<unknown> | undefined; |
| 181 | let settled: Extract<OrchestrationV2TurnItem, { type: "command_execution" }> | undefined; |
| 182 | const observe = (item: OrchestrationV2TurnItem | undefined) => |
| 183 | Effect.suspend(() => { |
| 184 | if (item === undefined || item.type !== "command_execution") return Effect.void; |
| 185 | if (!isOrchestrationV2WorkActive(item.status)) { |
| 186 | settled = item; |
| 187 | } else if (item.output !== undefined && item.output !== snapshotOutput) { |
| 188 | snapshotOutput = item.output; |
| 189 | } else { |
| 190 | return Effect.void; |
| 191 | } |
| 192 | subscriber.needsReplace = true; |
| 193 | return Queue.offer(wake, undefined); |
| 194 | }); |
| 195 | const fromSequence = yield* eventSink.latestSequence({ threadId: target.threadId }); |
| 196 | yield* eventSink |
| 197 | .stream({ |
| 198 | threadId: target.threadId, |
| 199 | afterSequence: fromSequence, |
| 200 | eventType: "turn-item.updated", |
| 201 | }) |
| 202 | .pipe( |
| 203 | Stream.runForEach((stored) => |
| 204 | stored.event.type === "turn-item.updated" && stored.event.payload.id === target.itemId |
| 205 | ? observe(stored.event.payload) |
| 206 | : Effect.void, |
| 207 | ), |
| 208 | // A lost event stream cannot settle the row; end with an error. |
| 209 | Effect.catchCause((cause) => |
| 210 | Effect.sync(() => { |
| 211 | lost = cause; |
| 212 | }).pipe(Effect.andThen(Queue.offer(wake, undefined))), |
| 213 | ), |
| 214 | Effect.forkScoped, |
| 215 | ); |
| 216 | const item = yield* projections.getTurnItem(target); |
| 217 | // Non-command rows would hold output subscriptions open forever. |
| 218 | if (item === null || item.type !== "command_execution") { |
| 219 | return yield* new OrchestrationV2CommandOutputError({ |
| 220 | threadId: target.threadId, |
| 221 | message: "No such command.", |
| 222 | }); |
| 223 | } |
| 224 | yield* observe(item); |
| 225 | yield* Queue.offer(wake, undefined); |
| 226 | |
| 227 | let lastFrameAt: number | undefined; |
| 228 | let throttle = COMMAND_OUTPUT_FRAME_INTERVAL_MS; |
| 229 | const nextFrame = Effect.gen(function* (): Effect.fn.Return< |
| 230 | OrchestrationV2CommandOutputFrame, |
| 231 | OrchestrationV2CommandOutputError |
| 232 | > { |
| 233 | yield* Queue.take(wake); |
| 234 | if (lost !== undefined) { |
| 235 | return yield* new OrchestrationV2CommandOutputError({ |
| 236 | threadId: target.threadId, |
| 237 | message: "Lost the thread's event stream.", |
| 238 | cause: Cause.squash(lost), |
| 239 | }); |
| 240 | } |
| 241 | const now = yield* Clock.currentTimeMillis; |
| 242 | if (lastFrameAt !== undefined && now - lastFrameAt < throttle) { |
| 243 | yield* Effect.sleep(throttle - (now - lastFrameAt)); |
| 244 | } |
| 245 | lastFrameAt = yield* Clock.currentTimeMillis; |
| 246 | throttle = COMMAND_OUTPUT_FRAME_INTERVAL_MS; |
| 247 | const tail = tails.get(key) ?? finished.get(key); |
| 248 | if (settled !== undefined) { |
| 249 | if (settled.output === undefined && tail !== undefined) { |
| 250 | return { |
| 251 | kind: "replace", |
| 252 | text: tail.text, |
| 253 | truncated: tail.truncated, |
| 254 | running: false, |
| 255 | }; |
| 256 | } |
| 257 | return { |
| 258 | kind: "replace", |
| 259 | ...persistedCommandOutput(commandItemOutput(settled)), |
| 260 | running: false, |
| 261 | }; |
| 262 | } |
| 263 | if (subscriber.needsReplace || tail === undefined) { |
| 264 | if (subscriber.overflowed) throttle = COMMAND_OUTPUT_REPLACE_INTERVAL_MS; |
| 265 | subscriber.needsReplace = false; |
| 266 | subscriber.overflowed = false; |
| 267 | subscriber.pendingAppend = ""; |
| 268 | if (tail === undefined) { |
| 269 | return { kind: "replace", ...persistedCommandOutput(snapshotOutput), running: true }; |
| 270 | } |
| 271 | // Include terminal state so clients interpret later appends identically. |
| 272 | return { |
| 273 | kind: "replace", |
| 274 | text: terminalOutputResumeText(tail), |
| 275 | truncated: tail.truncated, |
| 276 | running: true, |
| 277 | }; |
| 278 | } |
| 279 | const text = subscriber.pendingAppend; |
| 280 | subscriber.pendingAppend = ""; |
| 281 | return { kind: "append", text, truncated: tail.truncated, running: true }; |
| 282 | }); |
| 283 | return Stream.fromEffectRepeat(nextFrame).pipe( |
| 284 | Stream.filter((frame) => frame.kind !== "append" || frame.text.length > 0), |
| 285 | Stream.takeUntil((frame) => !frame.running), |
| 286 | ); |
| 287 | }).pipe( |
| 288 | Effect.mapError((cause) => |
| 289 | isCommandOutputError(cause) |
| 290 | ? cause |
| 291 | : new OrchestrationV2CommandOutputError({ |
| 292 | threadId: target.threadId, |
| 293 | message: "Failed to read command output.", |
| 294 | cause, |
| 295 | }), |
| 296 | ), |
| 297 | ), |
| 298 | ); |
| 299 | |
| 300 | return CommandOutputHub.of({ append, finish, subscribe }); |
| 301 | }); |
| 302 | |
| 303 | export const layer: Layer.Layer< |
| 304 | CommandOutputHub, |
| 305 | never, |
| 306 | EventSink.EventSinkV2 | ProjectionStore.ProjectionStoreV2 |
| 307 | > = Layer.effect(CommandOutputHub, make); |