Skip to content

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

3.1 KB
Raw Blame
/**
 * The subagents panel's auto-open tracker (pure — unit-tested in
 * test/panel-task-scope.test.ts): the current Task's first live spawn opens the panel
 * once, re-armed at each task boundary, so a manual close mid-task is respected. The chat
 * page observes the stream and applies the decision through the dock store.
 */

/**
 * Mutable tracker state, held in a ref by the chat page. `taskCount` is the number of
 * Task-starting user items observed in the session's stream (taskStartCount in
 * agent-topology.ts); an increase IS the "user started a new Task" boundary.
 */
export interface PanelTaskScope {
  sessionId: string | null;
  taskCount: number;
  /** Task ordinal (the taskCount value) whose one auto-open attempt was already consumed; null = armed. */
  autoOpenedAt: number | null;
}

export function createPanelTaskScope(): PanelTaskScope {
  return { sessionId: null, taskCount: 0, autoOpenedAt: null };
}

/**
 * Advance the tracker with one observation of the current session's stream and return whether
 * the panel should auto-open:
 *   - a live spawn in the current task → "autoOpen", at most once per task, so a manual close
 *     afterwards is respected until the next boundary;
 *   - a boundary (a Session switch, or a new Task within the session) RE-ARMS that one attempt
 *     but is never itself an action — an open panel is not closed here. Entering a
 *     session mid-run therefore auto-opens on the spawn that is already live, which reads as
 *     that spawn introducing itself;
 *   - anything else (steering, compaction, more messages in the same task) → null.
 * An observation whose stream data is another Session's (`streamSessionId`: the render right
 * after a switch, before the stream has reset for the new one) is no observation of this
 * Session at all: it neither advances the tracker nor opens anything, so the previous Session's
 * live spawn never opens the panel in the Session switched to.
 * A taskCount DECREASE is a defensive re-baseline (a resync swapped in a smaller model):
 * adopted silently, with the auto-open attempt marked consumed so a rebuild can never
 * surprise-open a panel the user closed mid-task.
 * The caller applies "autoOpen" under its own guards (not already shown); the attempt is
 * consumed here regardless, so a suppressed attempt never retriggers within the same task.
 */
export function advancePanelTaskScope(
  state: PanelTaskScope,
  obs: {
    sessionId: string | null;
    streamSessionId: string | null;
    taskCount: number;
    liveSpawn: boolean;
  },
): "autoOpen" | null {
  if (obs.streamSessionId !== obs.sessionId) return null;
  const switched = obs.sessionId !== state.sessionId;
  const rebaseline = !switched && obs.taskCount < state.taskCount;
  if (switched || obs.taskCount !== state.taskCount) {
    state.sessionId = obs.sessionId;
    state.taskCount = obs.taskCount;
    // A real boundary re-arms the auto-open; the defensive re-baseline marks it consumed.
    state.autoOpenedAt = rebaseline ? obs.taskCount : null;
  }
  if (obs.liveSpawn && state.autoOpenedAt !== state.taskCount) {
    state.autoOpenedAt = state.taskCount;
    return "autoOpen";
  }
  return null;
}