Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

11.5 KB
Raw Blame
/**
 * Server-backed task machinery shared by `run`, `chat`, `input` and `logs -f`.
 *
 * A task is driven entirely by the server; the CLI subscribes to the Session's SSE
 * stream FIRST (so nothing is missed), POSTs the task, then consumes frames until the
 * `task_state` flip back to idle:
 *   - default-event frames are OmniMessages, fed straight into StreamRenderer.handle —
 *     the same protocol core streams, so rendering is unchanged;
 *   - `server_event` frames carry `task_state` (end detection; the first event on a
 *     fresh subscription is an authoritative snapshot), `approval_request` (the [Y/n]
 *     prompt → POST /approvals/:toolCallId) and the goal progress events.
 *
 * Reconnects ride Last-Event-ID: the stream keeps the last seen frame id and reopens
 * with it on a dropped connection; `resync_required` (buffer evicted) prints a dim
 * notice — the messages endpoint still holds the full history for `penguin logs`.
 */
import { isEventMessage, isHookContinue, isHookInput, isModelMessage } from "@adelie/core";
import type { ApprovalDecision, OmniMessage, ToolCallPayload } from "@adelie/core";
import type { GoalServerEvent } from "@adelie/server/api";
import { ServerClient } from "./client.js";
import type { SseFrame } from "./client.js";
import { dim, humanizeTokens } from "./render.js";
import type { StreamRenderer } from "./render.js";
import type { Messages } from "./i18n.js";

/** Server events the watcher understands (structural subset of the server's ServerEvent union). */
interface ServerEventFrame {
  type: string;
  state?: "idle" | "running" | "compacting";
  toolCall?: OmniMessage<ToolCallPayload>;
  origin?: string[];
}

/** The server's goal_finished event: how the goal ended and its counters (the server maps the goal hook's stop event to it). */
type GoalFinishedEvent = Extract<GoalServerEvent, { type: "goal_finished" }>;

/** How a goal ended plus its counters, as the server's goal_finished event reports them. */
export interface GoalOutcome {
  outcome: GoalFinishedEvent["outcome"];
  /** Rounds actually run (the wrap-up round counts). */
  rounds: number;
  tokensUsed: number;
}

/**
 * A Session's SSE subscription with Last-Event-ID reconnects. `next()` yields frames
 * across reconnects; `close()` ends it. A subscription that drops MID-TASK reconnects
 * up to `MAX_RECONNECTS` times with a short backoff (the counter resets whenever a
 * frame actually arrives); a still-failing stream throws to the consumer.
 */
export class SessionStream {
  private lastEventId: string | undefined;
  private closed = false;
  private readonly abort = new AbortController();
  private iterator: AsyncGenerator<SseFrame> | null = null;
  private attempts = 0;

  private static readonly MAX_RECONNECTS = 5;

  constructor(
    private readonly client: ServerClient,
    private readonly sessionId: string,
    private readonly t: Messages,
  ) {}

  close(): void {
    this.closed = true;
    this.abort.abort();
  }

  /** The next frame, reconnecting through connection drops; null once closed. */
  async next(): Promise<SseFrame | null> {
    for (;;) {
      if (this.closed) return null;
      if (this.iterator === null) {
        this.iterator = this.client.sse(`/api/sessions/${this.sessionId}/stream`, {
          ...(this.lastEventId !== undefined ? { lastEventId: this.lastEventId } : {}),
          signal: this.abort.signal,
        });
      }
      try {
        const { done, value } = await this.iterator.next();
        if (done) {
          // Server closed the stream (restart/shutdown): treat like a drop and retry.
          this.iterator = null;
          await this.backoff();
          continue;
        }
        this.attempts = 0;
        if (value.id !== undefined) this.lastEventId = value.id;
        return value;
      } catch (err) {
        if (this.closed) return null;
        this.iterator = null;
        await this.backoff(err);
      }
    }
  }

  private async backoff(err?: unknown): Promise<void> {
    this.attempts += 1;
    if (this.attempts > SessionStream.MAX_RECONNECTS) {
      const detail = err instanceof Error ? err.message : String(err ?? "connection lost");
      throw new Error(this.t.client.streamLost(detail));
    }
    await new Promise((resolve) => setTimeout(resolve, 300 * this.attempts));
  }

  /**
   * Consumes frames until the initial `task_state` snapshot arrives (the first event of
   * every subscription) and returns its state — the authoritative "is it running"
   * answer callers branch on before POSTing.
   */
  async waitReady(): Promise<"idle" | "running" | "compacting"> {
    for (;;) {
      const frame = await this.next();
      if (frame === null) throw new Error(this.t.client.streamLost("closed before ready"));
      if (frame.event !== "server_event") continue;
      const ev = JSON.parse(frame.data) as ServerEventFrame;
      if (ev.type === "task_state" && ev.state !== undefined) return ev.state;
    }
  }
}

export interface WatchTaskOptions {
  client: ServerClient;
  sessionId: string;
  t: Messages;
  /** Renders the stream; omit for `--json` runs (messages are still parsed for text collection). */
  renderer?: StreamRenderer;
  /**
   * Answers an `approval_request` (the [Y/n] prompt); the decision is POSTed back.
   * Absent = the request is left pending untouched — a passive watcher (the poll form,
   * `--json` collectors) must never decide another surface's approvals.
   */
  approvalPrompt?: (tc: OmniMessage<ToolCallPayload>) => Promise<ApprovalDecision>;
  /** Goal mode: receives the dim round/summary lines (same rhythm as the core-direct loop had); a minimal sink so --json can swallow them. */
  goal?: { out: { write(text: string): unknown } };
  /** Collects main-session assistant text (complete messages) for `--json` output. */
  onAssistantText?: (text: string) => void;
  /**
   * `--timeout` soft-yield deadline (epoch ms): once it passes, the watch detaches
   * cleanly and reports `timedOut` — the exec_command yield-window semantics, applied to
   * the wait rather than the task. The task keeps running server-side; nothing is
   * aborted. Absent = wait indefinitely.
   */
  deadlineMs?: number;
}

/** Result of one watched task. */
export interface WatchTaskResult {
  /** The task ended with a main-session abort event (user interrupt / LLM failure). */
  aborted: boolean;
  /** The `deadlineMs` budget expired before the task ended: the watch detached, the task runs on. */
  timedOut: boolean;
  /** Goal-mode outcome (absent when the stream ended before the terminal event). */
  goal?: GoalOutcome;
}

/**
 * One frame, racing the soft-yield deadline: "timeout" once `deadlineMs` passes. The
 * losing `stream.next()` stays pending against the stream's internal iterator — the
 * caller detaches by closing the stream, which settles it. Shared by watchTask and
 * `logs -f`.
 */
export async function nextFrameOrDeadline(
  stream: SessionStream,
  deadlineMs: number | undefined,
): Promise<SseFrame | null | "timeout"> {
  if (deadlineMs === undefined) return stream.next();
  const remaining = deadlineMs - Date.now();
  if (remaining <= 0) return "timeout";
  let timer: ReturnType<typeof setTimeout> | undefined;
  const expiry = new Promise<"timeout">((resolve) => {
    timer = setTimeout(() => resolve("timeout"), remaining);
  });
  try {
    return await Promise.race([stream.next(), expiry]);
  } finally {
    clearTimeout(timer);
  }
}

/**
 * Consumes the stream until the task ends (`task_state` returns to idle). Call it AFTER
 * `waitReady()` and after POSTing the task/steer — every `task_state` seen here is a
 * flip, so the first `idle` is the end.
 */
export async function watchTask(
  stream: SessionStream,
  opts: WatchTaskOptions,
): Promise<WatchTaskResult> {
  const { t, renderer } = opts;
  let aborted = false;
  let timedOut = false;
  let outcome: GoalOutcome | undefined;
  let round = 0;
  // Set by a stop hook's `continue` event, spent by the input that follows it.
  let continued = false;
  let segmentStartedAt = Date.now();
  // Approval prompts serialize on a promise chain: concurrent requests (parent +
  // subagent) must not interleave their Q&A on one stdin.
  let promptChain: Promise<unknown> = Promise.resolve();

  const answerApproval = (ev: ServerEventFrame): void => {
    const tc = ev.toolCall;
    if (tc === undefined || opts.approvalPrompt === undefined) return;
    const prompt = opts.approvalPrompt;
    const run = async (): Promise<void> => {
      let decision: ApprovalDecision = "deny";
      renderer?.beginUserPrompt(tc);
      try {
        decision = await prompt(tc);
      } finally {
        // The decision line renders before the screen unlocks, keeping
        // call → prompt → result adjacent (same contract as the core-direct loop).
        renderer?.noteApprovalDecision(tc, decision);
        renderer?.endUserPrompt();
      }
      try {
        await opts.client.request(
          "POST",
          `/api/sessions/${opts.sessionId}/approvals/${encodeURIComponent(tc.payload.tool_call_id)}`,
          { decision },
        );
      } catch {
        // Already decided (abort converged it) or the run ended: nothing to do.
      }
    };
    promptChain = promptChain.then(run, run);
  };

  for (;;) {
    const frame = await nextFrameOrDeadline(stream, opts.deadlineMs);
    if (frame === "timeout") {
      timedOut = true;
      break;
    }
    if (frame === null) break;
    if (frame.event === "server_event") {
      const ev = JSON.parse(frame.data) as ServerEventFrame;
      if (ev.type === "task_state" && ev.state === "idle") break;
      if (ev.type === "approval_request") answerApproval(ev);
      if (ev.type === "goal_finished") {
        const finished = ev as unknown as GoalFinishedEvent;
        outcome = { outcome: finished.outcome, rounds: finished.rounds, tokensUsed: finished.used };
      }
      if (ev.type === "resync_required") {
        renderer?.printLine(dim(t.client.streamResynced()));
      }
      continue;
    }
    if (frame.event !== undefined) continue; // unknown named events: skip
    const msg = JSON.parse(frame.data) as OmniMessage;
    if (isEventMessage(msg) && msg.payload.type === "abort" && (msg.origin?.length ?? 0) === 0) {
      aborted = true;
    }
    if (opts.goal) {
      // A hook's input is a round boundary: round 1's protocol message (sent right behind
      // the objective), then every stop-hook continue, each announced by the hook's
      // `continue` event — the same rule as the server's goal_round events. Any other
      // harness-stamped input is another package's user_prompt context, not a round.
      if (isHookContinue(msg)) continued = true;
      if (isHookInput(msg) && (round === 0 || continued)) {
        continued = false;
        if (round > 0) renderer?.endTask(Date.now() - segmentStartedAt);
        round++;
        segmentStartedAt = Date.now();
        opts.goal.out.write(`${dim(t.goalRound(round))}\n`);
      }
    }
    if (opts.onAssistantText && (msg.origin?.length ?? 0) === 0 && isModelMessage(msg)) {
      const p = msg.payload as { type?: string; role?: string; text?: string };
      if (p.type === "text" && p.role !== "user" && typeof p.text === "string") {
        opts.onAssistantText(p.text);
      }
    }
    renderer?.handle(msg);
  }
  // Settle any prompt still in flight (the run ended while a question was open).
  await promptChain.catch(() => undefined);
  renderer?.endTask(Date.now() - segmentStartedAt);
  if (opts.goal && outcome) {
    opts.goal.out.write(
      `${dim(t.goalFinished(outcome.outcome, outcome.rounds, humanizeTokens(outcome.tokensUsed)))}\n`,
    );
  }
  return { aborted, timedOut, ...(outcome !== undefined ? { goal: outcome } : {}) };
}