import {
isOrchestrationV2WorkActive,
OrchestrationV2CommandOutputError,
type OrchestrationV2CommandOutputFrame,
type OrchestrationV2SubscribeCommandOutputInput,
type OrchestrationV2TurnItem,
} from "@t3tools/contracts";
import {
appendTerminalOutput,
EMPTY_TERMINAL_OUTPUT,
normalizeTerminalOutput,
type TerminalOutputState,
TERMINAL_OUTPUT_TAIL_CHARS,
terminalOutputResumeText,
} from "@t3tools/shared/terminalOutput";
import * as Cause from "effect/Cause";
import * as Clock from "effect/Clock";
import * as Context from "effect/Context";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as Queue from "effect/Queue";
import * as Schema from "effect/Schema";
import * as Stream from "effect/Stream";
import * as EventSink from "./EventSink.ts";
import * as ProjectionStore from "./ProjectionStore.ts";
/** Output bypasses orchestration events; expanded rows receive tails, coalesced appends, then persisted output. */
/** Fastest a subscriber receives frames while output flows. */
const COMMAND_OUTPUT_FRAME_INTERVAL_MS = 100;
/** After a subscriber falls behind and is sent the whole tail, it waits this long. */
const COMMAND_OUTPUT_REPLACE_INTERVAL_MS = 500;
/** Raw text a subscriber may accumulate before it is sent the tail instead. */
const COMMAND_OUTPUT_MAX_APPEND_CHARS = 16 * 1024;
/** Evict the least recently written command beyond this limit. */
const MAX_LIVE_COMMANDS = 64;
/** Retain finished tails for settlements that omit output. */
const MAX_FINISHED_COMMANDS = 16;
const MAX_FINAL_SOURCE_CHARS = TERMINAL_OUTPUT_TAIL_CHARS * 4;
interface Subscriber {
pendingAppend: string;
needsReplace: boolean;
/** `needsReplace` was caused by the subscriber falling behind. */
overflowed: boolean;
readonly wake: Queue.Queue<void>;
}
export type CommandOutputTarget = OrchestrationV2SubscribeCommandOutputInput;
export interface CommandOutputHubShape {
readonly append: (input: CommandOutputTarget & { readonly chunk: string }) => Effect.Effect<void>;
/** Retains the tail briefly for settlements without output; otherwise rows use persisted output. */
readonly finish: (input: CommandOutputTarget) => Effect.Effect<void>;
readonly subscribe: (
input: CommandOutputTarget,
) => Stream.Stream<OrchestrationV2CommandOutputFrame, OrchestrationV2CommandOutputError>;
}
export class CommandOutputHub extends Context.Service<CommandOutputHub, CommandOutputHubShape>()(
"t3/orchestration-v2/CommandOutputHub",
) {}
const isCommandOutputError = Schema.is(OrchestrationV2CommandOutputError);
function commandKey(target: CommandOutputTarget): string {
return `${target.threadId}\u0000${target.itemId}`;
}
const decodeLegacyClaudeBashResult = Schema.decodeUnknownOption(
Schema.fromJsonString(
Schema.Struct({ stdout: Schema.String, stderr: Schema.String, interrupted: Schema.Boolean }),
),
);
function legacyClaudeBashOutput(output: string): string {
if (!output.trimStart().startsWith('{"stdout"')) return output;
const parsed = decodeLegacyClaudeBashResult(output);
if (Option.isNone(parsed)) return output;
const out = parsed.value.stdout.trim().length > 0 ? parsed.value.stdout : "";
const err = parsed.value.stderr.trim().length > 0 ? parsed.value.stderr : "";
return out.length > 0 && err.length > 0 && !out.endsWith("\n") ? `${out}\n${err}` : out + err;
}
function persistedCommandOutput(output: string | undefined): {
readonly text: string;
readonly truncated: boolean;
} {
if (output === undefined) return { text: "", truncated: false };
let source = output;
if (output.length > MAX_FINAL_SOURCE_CHARS) {
// Cut at a newline to avoid splitting escape sequences.
source = output.slice(output.length - MAX_FINAL_SOURCE_CHARS);
const newline = source.indexOf("\n");
if (newline !== -1 && newline + 1 < source.length) source = source.slice(newline + 1);
}
const normalized = normalizeTerminalOutput(source);
return {
text: normalized.text,
truncated: normalized.truncated || source.length !== output.length,
};
}
function setBounded<V>(
map: Map<string, V>,
key: string,
value: V,
max: number,
onEvict?: (key: string) => void,
): void {
map.delete(key);
map.set(key, value);
if (map.size <= max) return;
const oldest = map.keys().next().value!;
map.delete(oldest);
onEvict?.(oldest);
}
export const make = Effect.gen(function* () {
const eventSink = yield* EventSink.EventSinkV2;
const projections = yield* ProjectionStore.ProjectionStoreV2;
const tails = new Map<string, TerminalOutputState>();
const finished = new Map<string, TerminalOutputState>();
const subscribers = new Map<string, Set<Subscriber>>();
const wakeAll = (key: string, chunk: string) =>
Effect.forEach(
subscribers.get(key) ?? [],
(subscriber) => {
if (!subscriber.needsReplace) {
subscriber.pendingAppend += chunk;
if (subscriber.pendingAppend.length > COMMAND_OUTPUT_MAX_APPEND_CHARS) {
subscriber.needsReplace = true;
subscriber.overflowed = true;
subscriber.pendingAppend = "";
}
}
return Queue.offer(subscriber.wake, undefined);
},
{ discard: true },
);
const append: CommandOutputHubShape["append"] = ({ chunk, ...target }) =>
Effect.suspend(() => {
if (chunk.length === 0) return Effect.void;
const key = commandKey(target);
const tail = appendTerminalOutput(tails.get(key) ?? EMPTY_TERMINAL_OUTPUT, chunk);
setBounded(tails, key, tail, MAX_LIVE_COMMANDS, (oldest) => {
// Eviction invalidates viewers' state; resync on their next frame.
for (const subscriber of subscribers.get(oldest) ?? []) {
subscriber.needsReplace = true;
subscriber.pendingAppend = "";
}
});
return wakeAll(key, chunk);
});
const finish: CommandOutputHubShape["finish"] = (target) =>
Effect.sync(() => {
const key = commandKey(target);
const tail = tails.get(key);
if (tail === undefined) return;
tails.delete(key);
setBounded(finished, key, tail, MAX_FINISHED_COMMANDS);
});
const subscribe: CommandOutputHubShape["subscribe"] = (target) =>
Stream.unwrap(
Effect.gen(function* () {
const key = commandKey(target);
const wake = yield* Queue.sliding<void>(1);
const subscriber: Subscriber = {
pendingAppend: "",
needsReplace: true,
overflowed: false,
wake,
};
// Subscribe before reading to avoid losing intervening chunks.
const keySubscribers = subscribers.get(key) ?? new Set<Subscriber>();
keySubscribers.add(subscriber);
subscribers.set(key, keySubscribers);
yield* Effect.addFinalizer(() =>
Effect.sync(() => {
keySubscribers.delete(subscriber);
if (keySubscribers.size === 0 && subscribers.get(key) === keySubscribers) {
subscribers.delete(key);
}
}),
);
// Persisted items provide settlement and final output; snapshot-only providers (ACP, Pi) also stream here.
let snapshotOutput: string | undefined;
let lost: Cause.Cause<unknown> | undefined;
let settled: Extract<OrchestrationV2TurnItem, { type: "command_execution" }> | undefined;
const observe = (item: OrchestrationV2TurnItem | undefined) =>
Effect.suspend(() => {
if (item === undefined || item.type !== "command_execution") return Effect.void;
if (!isOrchestrationV2WorkActive(item.status)) {
settled = item;
} else if (item.output !== undefined && item.output !== snapshotOutput) {
snapshotOutput = item.output;
} else {
return Effect.void;
}
subscriber.needsReplace = true;
return Queue.offer(wake, undefined);
});
const fromSequence = yield* eventSink.latestSequence({ threadId: target.threadId });
yield* eventSink
.stream({
threadId: target.threadId,
afterSequence: fromSequence,
eventType: "turn-item.updated",
})
.pipe(
Stream.runForEach((stored) =>
stored.event.type === "turn-item.updated" && stored.event.payload.id === target.itemId
? observe(stored.event.payload)
: Effect.void,
),
// A lost event stream cannot settle the row; end with an error.
Effect.catchCause((cause) =>
Effect.sync(() => {
lost = cause;
}).pipe(Effect.andThen(Queue.offer(wake, undefined))),
),
Effect.forkScoped,
);
const item = yield* projections.getTurnItem(target);
// Non-command rows would hold output subscriptions open forever.
if (item === null || item.type !== "command_execution") {
return yield* new OrchestrationV2CommandOutputError({
threadId: target.threadId,
message: "No such command.",
});
}
yield* observe(item);
yield* Queue.offer(wake, undefined);
let lastFrameAt: number | undefined;
let throttle = COMMAND_OUTPUT_FRAME_INTERVAL_MS;
const nextFrame = Effect.gen(function* (): Effect.fn.Return<
OrchestrationV2CommandOutputFrame,
OrchestrationV2CommandOutputError
> {
yield* Queue.take(wake);
if (lost !== undefined) {
return yield* new OrchestrationV2CommandOutputError({
threadId: target.threadId,
message: "Lost the thread's event stream.",
cause: Cause.squash(lost),
});
}
const now = yield* Clock.currentTimeMillis;
if (lastFrameAt !== undefined && now - lastFrameAt < throttle) {
yield* Effect.sleep(throttle - (now - lastFrameAt));
}
lastFrameAt = yield* Clock.currentTimeMillis;
throttle = COMMAND_OUTPUT_FRAME_INTERVAL_MS;
const tail = tails.get(key) ?? finished.get(key);
if (settled !== undefined) {
if (settled.output === undefined && tail !== undefined) {
return {
kind: "replace",
text: tail.text,
truncated: tail.truncated,
running: false,
};
}
const output = settled.output && legacyClaudeBashOutput(settled.output);
return { kind: "replace", ...persistedCommandOutput(output), running: false };
}
if (subscriber.needsReplace || tail === undefined) {
if (subscriber.overflowed) throttle = COMMAND_OUTPUT_REPLACE_INTERVAL_MS;
subscriber.needsReplace = false;
subscriber.overflowed = false;
subscriber.pendingAppend = "";
if (tail === undefined) {
return { kind: "replace", ...persistedCommandOutput(snapshotOutput), running: true };
}
// Include terminal state so clients interpret later appends identically.
return {
kind: "replace",
text: terminalOutputResumeText(tail),
truncated: tail.truncated,
running: true,
};
}
const text = subscriber.pendingAppend;
subscriber.pendingAppend = "";
return { kind: "append", text, truncated: tail.truncated, running: true };
});
return Stream.fromEffectRepeat(nextFrame).pipe(
Stream.filter((frame) => frame.kind !== "append" || frame.text.length > 0),
Stream.takeUntil((frame) => !frame.running),
);
}).pipe(
Effect.mapError((cause) =>
isCommandOutputError(cause)
? cause
: new OrchestrationV2CommandOutputError({
threadId: target.threadId,
message: "Failed to read command output.",
cause,
}),
),
),
);
return CommandOutputHub.of({ append, finish, subscribe });
});
export const layer: Layer.Layer<
CommandOutputHub,
never,
EventSink.EventSinkV2 | ProjectionStore.ProjectionStoreV2
> = Layer.effect(CommandOutputHub, make);