@vybestack/llxprt-code 0.10.0 → 0.11.0-nightly.260728.ffaa8d5d7

package/src/zed-integration/zed-stream-batcher.ts

@@ -0,0 +1,236 @@
+/**
+ * @license
+ * Copyright 2025 Vybestack LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * StreamBatcher batches live streaming text/thought chunks from the agent turn
+ * and flushes them to the ACP client as agent_message_chunk / agent_thought_chunk
+ * session/update notifications on a short interval, routing every chunk through
+ * the session's EmojiFilter (with blocked-response handling and a trailing
+ * buffer flush).
+ *
+ * Extracted from zedIntegration.ts into its own module so the integration file
+ * stays within the max-lines complexity budget; focused behavior is exercised by
+ * zed-stream-batcher.test.ts and prompt integration coverage.
+ */
+
+import type * as acp from '@agentclientprotocol/sdk';
+import { type EmojiFilter, DebugLogger } from '@vybestack/llxprt-code-core';
+
+// 100ms balances streaming latency (users see text quickly) with throughput
+// (fewer, larger ACP notifications). Tuned for local stdio transport; not
+// configurable because the ACP protocol expects near-real-time streaming.
+const BATCH_INTERVAL_MS = 100;
+
+/**
+ * The message emitted (as an agent_message_chunk) when the EmojiFilter blocks a
+ * streamed response in error mode (FINDING E2). Exported so tests reference this
+ * single source of truth instead of duplicating the literal, keeping the wire
+ * text and its assertions in lockstep. Intentionally hardcoded — not i18n'd
+ * because the ACP protocol requires deterministic, locale-independent status.
+ */
+export const STREAM_BLOCKED_MESSAGE =
+  '[Error: Response blocked due to emoji detection]';
+
+export class StreamBatcher {
+  private pendingChunks: Array<{ kind: 'text' | 'thought'; text: string }> = [];
+  private batchTimer: ReturnType<typeof setTimeout> | null = null;
+  private flushChain: Promise<void> = Promise.resolve();
+  private disposed = false;
+  private readonly logger: DebugLogger;
+
+  constructor(
+    private readonly emojiFilter: EmojiFilter,
+    private readonly sendUpdate: (update: acp.SessionUpdate) => Promise<void>,
+    logger?: DebugLogger,
+  ) {
+    // Injectable for testability; defaults to the shared zed-integration
+    // namespace so the otherwise-silent flush-chain / per-chunk failures
+    // (FINDING F4/F17) are diagnosable.
+    this.logger =
+      logger ?? new DebugLogger('llxprt:zed-integration:stream-batcher');
+  }
+
+  append(text: string, isThought: boolean): void {
+    if (this.disposed) {
+      return;
+    }
+    const filterResult = isThought
+      ? this.emojiFilter.filterText(text)
+      : this.emojiFilter.filterStreamChunk(text);
+    if (filterResult.blocked) {
+      // filterText() is stateless, so a blocked thought must not clear partial
+      // text held by filterStreamChunk() for a later streaming boundary.
+      if (!isThought) {
+        const residual = this.emojiFilter.flushBuffer();
+        if (residual.length > 0) {
+          this.appendPendingChunk('text', residual);
+        }
+      }
+      // FINDING E1: clear any pending batch timer BEFORE building the blocked
+      // chain (exactly as flush() does). Otherwise a timer armed by a prior
+      // normal chunk survives and later fires its own flush() — appending a
+      // SECOND doFlush()+flushEmojiBuffer chain that races the blocked-path
+      // chain, re-flushing already-flushed content after the error message. The
+      // blocked path here already flushes the residual + queued chunks, so the
+      // timer has nothing left to do.
+      if (this.batchTimer !== null) {
+        clearTimeout(this.batchTimer);
+        this.batchTimer = null;
+      }
+      const pending = this.flushChain
+        .then(() => this.doFlush())
+        .then(() =>
+          this.sendUpdate({
+            sessionUpdate: isThought
+              ? 'agent_thought_chunk'
+              : 'agent_message_chunk',
+            content: {
+              type: 'text',
+              text: STREAM_BLOCKED_MESSAGE,
+            },
+          }),
+        );
+      this.flushChain = this.settleChainLink(pending);
+      return;
+    }
+    const filteredText =
+      typeof filterResult.filtered === 'string' ? filterResult.filtered : '';
+    if (filteredText.length === 0) {
+      return;
+    }
+    this.appendPendingChunk(isThought ? 'thought' : 'text', filteredText);
+    this.batchTimer ??= setTimeout(() => {
+      this.batchTimer = null;
+      void this.flush().catch(() => undefined);
+    }, BATCH_INTERVAL_MS);
+  }
+
+  async flush(): Promise<void> {
+    if (this.batchTimer !== null) {
+      clearTimeout(this.batchTimer);
+      this.batchTimer = null;
+    }
+    // try/finally so the trailing emoji-buffer flush runs even if a future
+    // doFlush change introduces a rejection path — the residual filter content
+    // must never be stranded behind a failed chunk send.
+    const pending = this.flushChain.then(async () => {
+      try {
+        await this.doFlush();
+      } finally {
+        await this.flushEmojiBuffer();
+      }
+    });
+    this.flushChain = this.settleChainLink(pending);
+    await pending;
+  }
+
+  /**
+   * Clears any pending batch timer and drops buffered chunks so no timer fires
+   * after the owning prompt completes/aborts (FINDING F9), and marks the batcher
+   * disposed so a late {@link append} after the turn ends is a silent no-op
+   * (nothing new can enter the flush chain). Idempotent and safe to call after
+   * {@link flush}; it does NOT emit, so any pending chunks must be flushed first
+   * (the prompt path flushes then disposes). An in-flight flush is not aborted:
+   * chunks it already detached may finish sending while the chain settles.
+   */
+  dispose(): void {
+    this.disposed = true;
+    if (this.batchTimer !== null) {
+      clearTimeout(this.batchTimer);
+      this.batchTimer = null;
+    }
+    this.pendingChunks = [];
+    // Drop residual streaming state without emitting after the prompt boundary.
+    // The batcher/filter are per-prompt, but draining here also makes disposal
+    // complete if that ownership model changes later.
+    this.emojiFilter.flushBuffer();
+  }
+
+  private async flushEmojiBuffer(): Promise<void> {
+    // A dispose() that raced an in-flight chain link means the prompt is over:
+    // do not re-queue residual filter content past the turn boundary. (The
+    // standard prompt pattern — await flush() in try, dispose() in finally —
+    // never hits this: dispose only runs after the flush chain link settled.)
+    if (this.disposed) {
+      return;
+    }
+    const remaining = this.emojiFilter.flushBuffer();
+    if (remaining.length === 0) {
+      return;
+    }
+    this.appendPendingChunk('text', remaining);
+    await this.doFlush();
+  }
+
+  private appendPendingChunk(kind: 'text' | 'thought', text: string): void {
+    const lastChunk = this.pendingChunks.at(-1);
+    if (lastChunk?.kind === kind) {
+      lastChunk.text += text;
+      return;
+    }
+    this.pendingChunks.push({ kind, text });
+  }
+
+  private async doFlush(): Promise<void> {
+    const chunks = this.pendingChunks;
+    this.pendingChunks = [];
+    let firstError: unknown = null;
+    let lastError: unknown = null;
+    let failureCount = 0;
+    // FINDING F4: iterate a detached local copy and CONTINUE past a per-chunk
+    // send failure so a single rejecting sendUpdate does not drop every later
+    // chunk. The injected sendUpdate is best-effort today (Session.sendUpdate
+    // swallows), so this cannot reject in practice — but the injected contract
+    // is not guaranteed, so no chunk is silently lost if it ever does. The first
+    // and last distinct errors are collected + logged (not rethrown) to keep
+    // the flushChain intact.
+    for (const chunk of chunks) {
+      try {
+        await this.sendUpdate({
+          sessionUpdate:
+            chunk.kind === 'thought'
+              ? 'agent_thought_chunk'
+              : 'agent_message_chunk',
+          content: { type: 'text', text: chunk.text },
+        });
+      } catch (error) {
+        failureCount += 1;
+        if (firstError === null) {
+          firstError = error;
+        }
+        lastError = error;
+      }
+    }
+    if (firstError !== null) {
+      const firstMsg =
+        firstError instanceof Error ? firstError.message : String(firstError);
+      const lastMsg =
+        lastError instanceof Error ? lastError.message : String(lastError);
+      this.logger.debug(
+        () =>
+          `doFlush: ${failureCount} chunk update(s) failed to send; the remaining chunks were still attempted (no chunk dropped). First error: ${firstMsg}${
+            lastMsg !== firstMsg ? `. Last error: ${lastMsg}` : ''
+          }`,
+      );
+    }
+  }
+
+  /**
+   * Terminates a flush-chain link so a rejection cannot poison the serialized
+   * chain for subsequent appends, while still surfacing the swallowed error via
+   * the logger (FINDING F17) instead of discarding it silently.
+   */
+  private settleChainLink(pending: Promise<void>): Promise<void> {
+    return pending.catch((error: unknown) => {
+      this.logger.debug(
+        () =>
+          `flush chain link failed (swallowed to keep the batch chain alive): ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+      );
+    });
+  }
+}

package/src/zed-integration/zed-terminal-manager.ts

@@ -0,0 +1,416 @@
+/**
+ * @license
+ * Copyright 2026 Vybestack LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as path from 'node:path';
+import type * as acp from '@agentclientprotocol/sdk';
+import type { DebugLogger } from '@vybestack/llxprt-code-core';
+import {
+  getShellConfiguration,
+  isWithinRoot,
+} from '@vybestack/llxprt-code-core';
+import type { AgentToolCall } from '@vybestack/llxprt-code-agents';
+import type {
+  ShellExecutionResult,
+  ShellOutputEvent,
+} from '@vybestack/llxprt-code-tools';
+
+const OUTPUT_POLL_INTERVAL_MS = 100;
+const APPROXIMATE_BYTES_PER_TOKEN = 4;
+const KILL_GRACE_PERIOD_MS = 5000;
+
+type SendUpdateFn = (update: acp.SessionUpdate) => Promise<void>;
+
+interface PendingShellCall {
+  readonly id: string;
+  readonly command: string;
+  readonly cwd: string;
+}
+
+interface ActiveTerminal {
+  readonly handle: acp.TerminalHandle;
+  readonly command: string;
+  readonly cwd: string;
+  toolCallId: string | undefined;
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export class TerminalManager {
+  private readonly pendingCalls: PendingShellCall[] = [];
+  private readonly activeTerminals = new Set<ActiveTerminal>();
+
+  constructor(
+    private readonly sessionId: string,
+    private readonly connection: acp.AgentSideConnection,
+    private readonly targetDir: string,
+    private readonly sendUpdate: SendUpdateFn,
+    private readonly logger: DebugLogger,
+    private readonly maxOutputTokens?: number,
+  ) {}
+
+  static isShellToolCall(
+    call: AgentToolCall,
+    kind: string | undefined,
+  ): boolean {
+    return kind === 'execute' && typeof call.args['command'] === 'string';
+  }
+
+  async observeToolCall(call: AgentToolCall): Promise<void> {
+    const command = readCommand(call);
+    if (command === null) {
+      return;
+    }
+    const pending: PendingShellCall = {
+      id: call.id,
+      command,
+      cwd: resolveCallCwd(call, this.targetDir),
+    };
+    const active = [...this.activeTerminals].find(
+      (terminal) =>
+        terminal.toolCallId === undefined &&
+        terminal.cwd === pending.cwd &&
+        commandsMatch(terminal.command, pending.command),
+    );
+    if (active === undefined) {
+      this.pendingCalls.push(pending);
+      return;
+    }
+    active.toolCallId = pending.id;
+    try {
+      await this.sendTerminalUpdate(active);
+    } catch (error) {
+      active.toolCallId = undefined;
+      throw error;
+    }
+  }
+
+  completeToolCall(toolCallId: string): void {
+    const pendingIndex = this.pendingCalls.findIndex(
+      (pending) => pending.id === toolCallId,
+    );
+    if (pendingIndex >= 0) {
+      this.pendingCalls.splice(pendingIndex, 1);
+    }
+    for (const terminal of this.activeTerminals) {
+      if (terminal.toolCallId === toolCallId) {
+        terminal.toolCallId = undefined;
+      }
+    }
+  }
+
+  async executeShellCommand(
+    command: string,
+    cwd: string,
+    onOutput: (event: ShellOutputEvent) => void,
+    signal: AbortSignal,
+  ): Promise<ShellExecutionResult> {
+    if (signal.aborted) {
+      return abortedResult();
+    }
+    if (command.trim().length === 0) {
+      throw new Error('Shell command must not be empty');
+    }
+    const shell = getShellConfiguration();
+    const handle = await this.connection.createTerminal({
+      command: shell.executable,
+      args: [...shell.argsPrefix, command],
+      cwd,
+      sessionId: this.sessionId,
+      ...(this.maxOutputTokens === undefined
+        ? {}
+        : {
+            outputByteLimit: this.maxOutputTokens * APPROXIMATE_BYTES_PER_TOKEN,
+          }),
+    });
+    const active: ActiveTerminal = {
+      handle,
+      command,
+      cwd,
+      toolCallId: undefined,
+    };
+    let registered = false;
+    try {
+      active.toolCallId = this.claimPendingCall(command, cwd);
+      this.activeTerminals.add(active);
+      registered = true;
+      if (active.toolCallId !== undefined) {
+        await this.sendTerminalUpdate(active);
+      }
+      return await this.waitForTerminal(active, onOutput, signal);
+    } catch (error) {
+      if (this.activeTerminals.delete(active) || !registered) {
+        await this.killAndRelease(active);
+      }
+      throw error;
+    } finally {
+      if (this.activeTerminals.delete(active)) {
+        await this.release(active);
+      }
+    }
+  }
+
+  async settleAll(): Promise<void> {
+    this.pendingCalls.splice(0);
+    const terminals = [...this.activeTerminals];
+    this.activeTerminals.clear();
+    await Promise.allSettled(terminals.map((t) => this.killAndRelease(t)));
+  }
+
+  private claimPendingCall(command: string, cwd: string): string | undefined {
+    const index = this.pendingCalls.findIndex(
+      (pending) =>
+        pending.cwd === cwd && commandsMatch(command, pending.command),
+    );
+    if (index < 0) {
+      return undefined;
+    }
+    return this.pendingCalls.splice(index, 1)[0]?.id;
+  }
+
+  private async sendTerminalUpdate(active: ActiveTerminal): Promise<void> {
+    if (active.toolCallId === undefined) {
+      return;
+    }
+    await this.sendUpdate({
+      sessionUpdate: 'tool_call_update',
+      toolCallId: active.toolCallId,
+      status: 'in_progress',
+      content: [{ type: 'terminal', terminalId: active.handle.id }],
+    });
+  }
+
+  private async waitForTerminal(
+    active: ActiveTerminal,
+    onOutput: (event: ShellOutputEvent) => void,
+    signal: AbortSignal,
+  ): Promise<ShellExecutionResult> {
+    let exit: acp.WaitForTerminalExitResponse | undefined;
+    let exitError: unknown;
+    const exitPromise = active.handle
+      .waitForExit()
+      .then((result) => {
+        exit = result;
+      })
+      .catch((error: unknown) => {
+        exitError = error;
+      });
+    let previousOutput = '';
+    let killed = false;
+    let killDeadline = 0;
+    let done = false;
+    while (!done) {
+      if (signal.aborted && !killed) {
+        killed = true;
+        killDeadline = Date.now() + KILL_GRACE_PERIOD_MS;
+        await this.kill(active);
+      }
+      done =
+        exit !== undefined ||
+        exitError !== undefined ||
+        (killed && Date.now() >= killDeadline);
+      if (!done) {
+        const pollDelay = delay(OUTPUT_POLL_INTERVAL_MS);
+        try {
+          await Promise.race([exitPromise, pollDelay.promise]);
+        } finally {
+          pollDelay.cancel();
+        }
+        let current: acp.TerminalOutputResponse;
+        try {
+          current = await active.handle.currentOutput();
+        } catch (error) {
+          this.logger.debug(
+            () => `Terminal output poll failed: ${errorMessage(error)}`,
+          );
+          throw error;
+        }
+        const chunk = outputDelta(
+          previousOutput,
+          current.output,
+          current.truncated,
+        );
+        if (chunk !== '') {
+          onOutput({ type: 'data', chunk });
+        }
+        previousOutput = current.output;
+      }
+    }
+    if (exitError === undefined) {
+      previousOutput = await this.pollFinalOutput(
+        active,
+        previousOutput,
+        onOutput,
+      );
+    }
+    if (exitError !== undefined) {
+      throw exitError;
+    }
+    return {
+      output: previousOutput,
+      exitCode: exit?.exitCode ?? null,
+      signal: exit?.signal ?? null,
+      error: null,
+      aborted: signal.aborted,
+      pid: undefined,
+    };
+  }
+
+  private async pollFinalOutput(
+    active: ActiveTerminal,
+    previousOutput: string,
+    onOutput: (event: ShellOutputEvent) => void,
+  ): Promise<string> {
+    try {
+      const final = await withTimeout(
+        active.handle.currentOutput(),
+        OUTPUT_POLL_INTERVAL_MS * 5,
+      );
+      if (final === undefined) {
+        return previousOutput;
+      }
+      const chunk = outputDelta(previousOutput, final.output, final.truncated);
+      if (chunk !== '') {
+        onOutput({ type: 'data', chunk });
+      }
+      return final.output;
+    } catch (error) {
+      this.logger.debug(
+        () => `Terminal post-exit output poll failed: ${errorMessage(error)}`,
+      );
+      return previousOutput;
+    }
+  }
+
+  private async killAndRelease(active: ActiveTerminal): Promise<void> {
+    await this.kill(active);
+    await this.release(active);
+  }
+
+  private async kill(active: ActiveTerminal): Promise<void> {
+    try {
+      await active.handle.kill();
+    } catch (error) {
+      this.logger.debug(() => `Terminal kill failed: ${errorMessage(error)}`);
+    }
+  }
+
+  private async release(active: ActiveTerminal): Promise<void> {
+    try {
+      await active.handle.release();
+    } catch (error) {
+      this.logger.debug(
+        () => `Terminal release failed: ${errorMessage(error)}`,
+      );
+    }
+  }
+}
+
+function readCommand(call: AgentToolCall): string | null {
+  const command = call.args['command'];
+  return typeof command === 'string' && command.trim() !== '' ? command : null;
+}
+
+function resolveCallCwd(call: AgentToolCall, targetDir: string): string {
+  const dirPath = call.args['dir_path'];
+  const directory = call.args['directory'];
+  let value = '';
+  if (typeof dirPath === 'string') {
+    value = dirPath;
+  } else if (typeof directory === 'string') {
+    value = directory;
+  }
+  if (value === '') {
+    return targetDir;
+  }
+  const resolved = path.isAbsolute(value)
+    ? path.resolve(value)
+    : path.resolve(targetDir, value);
+  if (!isWithinRoot(resolved, targetDir)) {
+    throw new Error(
+      `Shell tool cwd resolves outside the session root: ${value}`,
+    );
+  }
+  return resolved;
+}
+
+function commandsMatch(preparedCommand: string, rawCommand: string): boolean {
+  // ShellExecutionService wraps commands to capture their exit code. Match only
+  // that exact prefix so terminal updates attach to the originating raw command.
+  const trimmed = rawCommand.trim();
+  if (preparedCommand === trimmed) {
+    return true;
+  }
+  const terminated =
+    trimmed.endsWith('&') || trimmed.endsWith(';') ? trimmed : `${trimmed};`;
+  return preparedCommand.startsWith(`{ ${terminated} }; __code=$?;`);
+}
+
+function abortedResult(): ShellExecutionResult {
+  return {
+    output: '',
+    exitCode: null,
+    signal: null,
+    error: null,
+    aborted: true,
+    pid: undefined,
+  };
+}
+
+function outputDelta(
+  previous: string,
+  current: string,
+  truncated: boolean,
+): string {
+  if (current.startsWith(previous)) {
+    return current.slice(previous.length);
+  }
+  if (!truncated) {
+    return current;
+  }
+  for (
+    let overlap = Math.min(previous.length, current.length);
+    overlap > 0;
+    overlap--
+  ) {
+    if (previous.endsWith(current.slice(0, overlap))) {
+      return current.slice(overlap);
+    }
+  }
+  return current;
+}
+
+async function withTimeout<T>(
+  promise: Promise<T>,
+  milliseconds: number,
+): Promise<T | undefined> {
+  const timeout = delay(milliseconds);
+  try {
+    return await Promise.race([promise, timeout.promise.then(() => undefined)]);
+  } finally {
+    timeout.cancel();
+  }
+}
+
+function delay(milliseconds: number): {
+  promise: Promise<void>;
+  cancel: () => void;
+} {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const promise = new Promise<void>((resolve) => {
+    timer = setTimeout(resolve, milliseconds);
+  });
+  return {
+    promise,
+    cancel: () => {
+      if (timer !== undefined) {
+        clearTimeout(timer);
+        timer = undefined;
+      }
+    },
+  };
+}