pi-pier 0.1.4 → 0.2.0

package/src/subagent-poll-loop.ts

@@ -0,0 +1,285 @@
+/**
+ * Background settlement poller (takeover, blocked gate, observation, vacuum).
+ *
+ * Why: planners already live in subagent-poller.ts; this adapter owns the
+ * herdr/session I/O loop and pane-scope lifecycle so the plugin only starts it.
+ */
+import { appendFileSync } from 'node:fs';
+import type { Context } from '@deepseek-ai/cordis';
+import type { HerdrClientLike, HerdrAgentState } from './herdr-client.ts';
+import { applyReportedSessionFile } from './history-store.ts';
+import { runtimePolicy } from './runtime-policy.ts';
+import { mountSubagentScope } from './subagent-scope.ts';
+import {
+  OBSERVATION_TICK_MS,
+  TAKEOVER_RECHECK_MS,
+  planBlockedGate,
+  planObservationTick,
+  planTakeoverTick,
+  planVacuumTick,
+} from './subagent-poller.ts';
+import { buildBlockedGateNotice, type SubEntry } from './subagent-core.ts';
+import { formatSettlementNotice } from './vocab.ts';
+import type { SessionIo } from './subagent-session-io.ts';
+import type { GitIo } from './subagent-git-io.ts';
+
+function sleep(ms: number): Promise<void> {
+  const wait = Promise.withResolvers<void>();
+  setTimeout(wait.resolve, ms);
+  return wait.promise;
+}
+
+export interface PollerHost {
+  client: HerdrClientLike;
+  sessionRoot: Context;
+  subs: Map<string, SubEntry>;
+  persistSubs(): void;
+  writeHistory(e: SubEntry, patch?: { outcome?: string | null; status?: SubEntry['status']; closedAt?: number }, via?: string): void;
+  blockedGateNotified: Set<string>;
+  lastMachineInjectAt: Map<string, number>;
+  session: SessionIo;
+  git: GitIo;
+  injectNotice(content: string): Promise<void>;
+  reconcileOnSettlement(description: string, outcome: 'settled' | 'failed'): string[];
+  withReconcileNotes(base: string, notes: readonly string[]): string;
+  claimSettleNotice(key: string): boolean;
+}
+
+export interface Poller {
+  startPoller(paneId: string, cwd: string, spawnedAt: number, injectTs: number, description: string, requestId: string): void;
+  readonly pollers: Set<string>;
+}
+
+export function createPoller(h: PollerHost): Poller {
+  const pollers = new Set<string>();
+  const subScopes = new Map<string, { dispose: () => Promise<void> }>();
+  const observeWindowMs = runtimePolicy.observationWindowMs;
+  const machineInjectGraceMs = runtimePolicy.settlementWindowMs;
+  const takeoverIdleMs = runtimePolicy.settlementWindowMs;
+  const timeoutMs = runtimePolicy.subagentTimeoutMs;
+
+  async function pollLoop(
+    paneId: string,
+    cwd: string,
+    spawnedAt: number,
+    injectTs: number,
+    description: string,
+    requestId: string,
+  ): Promise<void> {
+    void spawnedAt;
+    const startedAt = Date.now();
+    let lastActivityAt = Date.now();
+    const pollTrace = process.env.PI_HERDR_TRACE
+      ? (msg: string) => { try { appendFileSync(process.env.PI_HERDR_TRACE!, `d98poll ${Date.now()} ${paneId} ${msg}\n`); } catch { /* best-effort */ } }
+      : null;
+    try {
+      while (true) {
+        const entry = h.subs.get(paneId);
+        if (!entry || entry.status === 'settled') return;
+
+        if (entry.userTakeover) {
+          try {
+            const agents = await h.client.listAgents();
+            const agent = agents.find((a) => a.paneId === paneId);
+            const tick = planTakeoverTick({
+              currentStatus: agent?.status ?? null,
+              previousStatus: entry.lastAgentStatus,
+              idleStartedAt: entry.observationStartedAt,
+              now: Date.now(),
+              idleMs: takeoverIdleMs,
+            });
+            if (tick.kind === 'start-idle') {
+              entry.observationStartedAt = Date.now();
+              entry.lastAgentStatus = 'idle';
+              h.persistSubs();
+            } else if (tick.kind === 'return-control') {
+              entry.userTakeover = false;
+              entry.observationStartedAt = null;
+              entry.lastAgentStatus = null;
+              h.persistSubs();
+            } else if (tick.kind === 'hold' && tick.clearIdleTimer) {
+              entry.lastAgentStatus = tick.lastAgentStatus;
+              entry.observationStartedAt = null;
+              h.persistSubs();
+            }
+          } catch {
+            /* status probe failure must not stop the poller */
+          }
+          if (entry.userTakeover) {
+            await sleep(TAKEOVER_RECHECK_MS);
+            continue;
+          }
+        }
+
+        let state: HerdrAgentState | null;
+        try {
+          state = await h.client.waitAgent(paneId, ['idle', 'done', 'blocked'], runtimePolicy.pollIntervalMs);
+        } catch {
+          state = null;
+        }
+        const gate = planBlockedGate(state, h.blockedGateNotified.has(paneId));
+        if (gate.kind === 'stay-blocked') {
+          if (gate.notify) {
+            h.blockedGateNotified.add(paneId);
+            const question = await h.session.readAskFlag(paneId);
+            try {
+              await h.injectNotice(buildBlockedGateNotice({ paneId, description, question }));
+            } catch {
+              /* list_agents can recover a missed notice */
+            }
+          }
+          continue;
+        }
+        if (gate.kind === 'clear-gate') h.blockedGateNotified.delete(paneId);
+        if (state === 'idle' || state === 'done') {
+          const s = await h.session.subSessionState(paneId, cwd, injectTs);
+          pollTrace?.(`state=${state} text=${s.text ? s.text.length : 'null'} pend=${s.pendingTool} act=${s.activity} obs=${String(entry.observationStartedAt ?? null)} takeover=${String(entry.userTakeover === true)}`);
+          if (s.text || (!s.pendingTool && s.activity)) {
+            const closing = s.text;
+            const obs = planObservationTick({
+              observationStartedAt: entry.observationStartedAt,
+              now: Date.now(),
+              windowMs: observeWindowMs,
+              agentStatus: null,
+              machineInjectAgoMs: Date.now() - (h.lastMachineInjectAt.get(paneId) ?? 0),
+              machineInjectGraceMs,
+            });
+            if (obs.kind === 'start-observation') {
+              entry.observationStartedAt = Date.now();
+              entry.lastAgentStatus = 'idle';
+              h.persistSubs();
+              await sleep(OBSERVATION_TICK_MS);
+              continue;
+            }
+            let agentStatus: string | null = null;
+            try {
+              const agents = await h.client.listAgents();
+              agentStatus = agents.find((a) => a.paneId === paneId)?.status ?? null;
+            } catch {
+              /* observation continues */
+            }
+            const obs2 = planObservationTick({
+              observationStartedAt: entry.observationStartedAt,
+              now: Date.now(),
+              windowMs: observeWindowMs,
+              agentStatus,
+              machineInjectAgoMs: Date.now() - (h.lastMachineInjectAt.get(paneId) ?? 0),
+              machineInjectGraceMs,
+            });
+            if (obs2.kind === 'user-takeover') {
+              entry.userTakeover = true;
+              entry.observationStartedAt = Date.now();
+              entry.lastAgentStatus = 'working';
+              h.persistSubs();
+              continue;
+            }
+            if (obs2.kind === 'machine-inject-reset') {
+              entry.observationStartedAt = Date.now();
+              h.persistSubs();
+              await sleep(OBSERVATION_TICK_MS);
+              continue;
+            }
+            if (obs2.kind === 'wait') {
+              await sleep(OBSERVATION_TICK_MS);
+              continue;
+            }
+            entry.observationStartedAt = null;
+            if (!entry.sessionFile) {
+              entry.sessionFile = applyReportedSessionFile(
+                entry.sessionFile,
+                await h.session.resolveSessionFile(paneId, cwd),
+              );
+            }
+            entry.status = 'consumed';
+            entry.consumedAt = Date.now();
+            h.writeHistory(entry, { outcome: closing }, 'poll-settle');
+            const notes = h.reconcileOnSettlement(description, 'settled');
+            const statLine = await h.git.worktreeStatLine(entry);
+            const notice = h.withReconcileNotes(
+              formatSettlementNotice(`${paneId} (${description})`, closing) + (statLine ? `\n${statLine}` : ''),
+              notes,
+            );
+            if (h.claimSettleNotice(`${paneId}:${requestId}`)) {
+              try {
+                await h.injectNotice(notice);
+              } catch {
+                /* list_agents can recover */
+              }
+            }
+            return;
+          }
+        }
+        let alive = false;
+        try {
+          alive = (await h.client.listAgents()).some((a) => a.paneId === paneId);
+        } catch {
+          alive = true;
+        }
+        const vacuum = planVacuumTick({
+          waitState: state,
+          paneAlive: alive,
+          now: Date.now(),
+          lastActivityAt,
+          timeoutMs,
+        });
+        if (vacuum.refreshActivity) lastActivityAt = Date.now();
+        if (vacuum.action === 'pane-closed') {
+          entry.status = 'consumed';
+          entry.consumedAt = Date.now();
+          h.persistSubs();
+          h.writeHistory(entry, { outcome: 'pane closed before settling' }, 'poll-pane-closed');
+          const notes = h.reconcileOnSettlement(description, 'failed');
+          const notice = h.withReconcileNotes(
+            `Background subagent ${paneId} (${description}) stopped before settling (its pane closed).`,
+            notes,
+          );
+          try {
+            await h.injectNotice(notice);
+          } catch { /* non-fatal */ }
+          return;
+        }
+        if (vacuum.action === 'timeout') {
+          entry.status = 'consumed';
+          entry.consumedAt = Date.now();
+          h.persistSubs();
+          h.writeHistory(entry, { outcome: 'observation timeout' }, 'poll-timeout');
+          const notes = h.reconcileOnSettlement(description, 'failed');
+          const notice = h.withReconcileNotes(
+            `Background subagent ${paneId} (${description}) has shown no progress for ${Math.round((Date.now() - lastActivityAt) / 1000)}s (observed since ${new Date(startedAt).toISOString()}). Run list_agents to check its live state; if it is working, let it run — its settlement notice will arrive automatically. Do not sleep-wait.`,
+            notes,
+          );
+          try {
+            await h.injectNotice(notice);
+          } catch { /* non-fatal */ }
+          return;
+        }
+      }
+    } finally {
+      pollers.delete(paneId);
+    }
+  }
+
+  function startPoller(paneId: string, cwd: string, spawnedAt: number, injectTs: number, description: string, requestId: string): void {
+    if (pollers.has(paneId)) return;
+    pollers.add(paneId);
+    void (async () => {
+      try {
+        if (!subScopes.has(paneId)) {
+          const fiber = await mountSubagentScope(h.sessionRoot, paneId, {
+            onDispose: () => { pollers.delete(paneId); },
+          });
+          subScopes.set(paneId, fiber);
+        }
+        await pollLoop(paneId, cwd, spawnedAt, injectTs, description, requestId);
+        const fiber = subScopes.get(paneId);
+        subScopes.delete(paneId);
+        try { await fiber?.dispose(); } catch { /* already gone */ }
+      } catch (err) {
+        pollers.delete(paneId);
+        console.error(`pier: subagent poller ${paneId} crashed: ${(err as Error)?.message ?? err}`);
+      }
+    })();
+  }
+
+  return { startPoller, pollers };
+}

package/src/subagent-poller.ts

@@ -0,0 +1,90 @@
+/**
+ * Subagent pollLoop transition planners.
+ *
+ * Why: pollLoop mixed herdr I/O with takeover / observation / vacuum decisions.
+ * Extracting the decisions makes the 30s observation window vs 60s takeover-idle
+ * window explicit and unit-testable without a live pane.
+ */
+
+export const TAKEOVER_RECHECK_MS = 5_000;
+export const OBSERVATION_TICK_MS = 1_000;
+
+export type HerdrWaitState = 'idle' | 'working' | 'blocked' | 'done' | 'unknown' | null;
+
+export type TakeoverTickPlan =
+  | { kind: 'ignore' }
+  | { kind: 'start-idle' }
+  | { kind: 'return-control' }
+  | { kind: 'hold'; lastAgentStatus: string; clearIdleTimer: boolean };
+
+export function planTakeoverTick(input: {
+  currentStatus: string | null;
+  previousStatus: string | null | undefined;
+  idleStartedAt: number | null | undefined;
+  now: number;
+  idleMs: number;
+}): TakeoverTickPlan {
+  if (input.currentStatus == null) return { kind: 'ignore' };
+  if (input.currentStatus === 'idle') {
+    if (input.previousStatus !== 'idle') return { kind: 'start-idle' };
+    if (input.idleStartedAt != null && input.now - input.idleStartedAt > input.idleMs) {
+      return { kind: 'return-control' };
+    }
+    return { kind: 'hold', lastAgentStatus: 'idle', clearIdleTimer: false };
+  }
+  return { kind: 'hold', lastAgentStatus: input.currentStatus, clearIdleTimer: true };
+}
+
+export type BlockedGatePlan =
+  | { kind: 'stay-blocked'; notify: boolean }
+  | { kind: 'clear-gate' }
+  | { kind: 'pass' };
+
+export function planBlockedGate(state: HerdrWaitState, alreadyNotified: boolean): BlockedGatePlan {
+  if (state === 'blocked') return { kind: 'stay-blocked', notify: !alreadyNotified };
+  if (state !== null) return { kind: 'clear-gate' };
+  return { kind: 'pass' };
+}
+
+export type ObservationTickPlan =
+  | { kind: 'start-observation' }
+  | { kind: 'user-takeover' }
+  | { kind: 'machine-inject-reset' }
+  | { kind: 'wait' }
+  | { kind: 'settle' };
+
+export function planObservationTick(input: {
+  observationStartedAt: number | null | undefined;
+  now: number;
+  windowMs: number;
+  agentStatus: string | null;
+  machineInjectAgoMs: number;
+  machineInjectGraceMs: number;
+}): ObservationTickPlan {
+  if (!input.observationStartedAt) return { kind: 'start-observation' };
+  if (input.agentStatus === 'working') {
+    if (input.machineInjectAgoMs > input.machineInjectGraceMs) return { kind: 'user-takeover' };
+    return { kind: 'machine-inject-reset' };
+  }
+  if (input.now - input.observationStartedAt < input.windowMs) return { kind: 'wait' };
+  return { kind: 'settle' };
+}
+
+export type VacuumTickPlan = {
+  refreshActivity: boolean;
+  action: 'pane-closed' | 'timeout' | 'continue';
+};
+
+export function planVacuumTick(input: {
+  waitState: HerdrWaitState;
+  paneAlive: boolean;
+  now: number;
+  lastActivityAt: number;
+  timeoutMs: number;
+}): VacuumTickPlan {
+  const refreshActivity = input.waitState === null;
+  const lastActivityAt = refreshActivity ? input.now : input.lastActivityAt;
+  if (!input.paneAlive) return { refreshActivity, action: 'pane-closed' };
+  if (input.now - lastActivityAt > input.timeoutMs) return { refreshActivity, action: 'timeout' };
+  return { refreshActivity, action: 'continue' };
+}

package/src/subagent-port.ts

@@ -0,0 +1,27 @@
+/**
+ * Subagent outbound port (composition root → plugin).
+ *
+ * Why: index used to pass a bag of independently-nullable callbacks that the
+ * plugin mutated field-by-field. A missing bag crashed at mount
+ * (`Cannot set properties of undefined (setting 'applyReplySession')`).
+ * Binding one `current` object is atomic: all methods or none.
+ */
+export interface RunningSub {
+  paneId: string;
+  description: string;
+}
+
+export interface SubagentPort {
+  applyReplySession(paneId: string, sessionFile: string | null): void;
+  reconcileOnReply(paneId: string): string[];
+  listRunningSubs(): RunningSub[];
+  settleStatLine(paneId: string): Promise<string | null>;
+}
+
+export interface SubagentPortBox {
+  current: SubagentPort | null;
+}
+
+export function emptySubagentPortBox(): SubagentPortBox {
+  return { current: null };
+}

package/src/subagent-scope.ts

@@ -1,7 +1,7 @@
 /**
- * 档 0：master 进程内每个 subagent 一个 cordis fiber。
- * pipe / poller / history 的清理走 ctx.effect，dispose LIFO。
- * C3：worker 进程不引入本模块。
+ * One Cordis fiber per subagent in the master process.
+ * pipe / poller / history cleanup uses ctx.effect (LIFO dispose).
+ * C3: workers must not import this module.
  */
 import { Context } from '@deepseek-ai/cordis';
 
@@ -34,6 +34,6 @@ export async function disposeSessionRoot(root: Context): Promise<void> {
   try {
     await root.fiber.dispose();
   } catch {
-    /* 二次 dispose 是 no-op */
+    /* second dispose is a no-op */
   }
 }

package/src/subagent-session-io.ts

@@ -0,0 +1,143 @@
+/**
+ * Child-session JSONL I/O: path resolution, settlement text, liveness probes.
+ *
+ * Why: pollLoop, foreground wait, and revive all shared the same candidate
+ * order (reported path/id before recent-file fallback, excluding the parent
+ * session). Keeping it in one adapter prevents settlement text from crossing sessions.
+ */
+import { stat as statCb } from 'node:fs';
+import { promisify } from 'node:util';
+import type { HerdrClientLike } from './herdr-client.ts';
+import {
+  hasAssistantAfter,
+  hasPendingToolCall,
+  lastAssistantText,
+  listSessionFiles,
+  readSessionFile,
+  sessionFileById,
+} from './session-tail.ts';
+import type { AliveProbe } from './subagent-core.ts';
+
+const statAsync = promisify(statCb);
+
+export interface SessionIoHost {
+  client: HerdrClientLike;
+  getSessionId: () => string;
+  sessionsDir: () => string;
+}
+
+export interface SessionIo {
+  resolveSessionFileCandidates(paneId: string, cwd: string): Promise<string[]>;
+  resolveSessionFile(paneId: string, cwd: string): Promise<string | null>;
+  collectFinalText(paneId: string, cwd: string, sinceTs: number, attempts?: number): Promise<string | null>;
+  readAskFlag(paneId: string): Promise<string | null>;
+  probeAlive(paneId: string, cwd: string): Promise<AliveProbe>;
+  subSessionState(paneId: string, cwd: string, sinceTs: number): Promise<{ text: string | null; pendingTool: boolean; activity: boolean }>;
+}
+
+export function createSessionIo(h: SessionIoHost): SessionIo {
+  async function resolveSessionFileCandidates(paneId: string, cwd: string): Promise<string[]> {
+    const out: string[] = [];
+    try {
+      const reported = await h.client.getAgentSessionPath(paneId);
+      if (reported) {
+        if (/\.jsonl$/.test(reported)) out.push(reported);
+        else {
+          const byId = sessionFileById(cwd, h.sessionsDir(), reported);
+          if (byId) out.push(byId);
+        }
+      }
+    } catch {
+      /* Reports may be unavailable during startup. */
+    }
+    const ownSession = h.getSessionId();
+    for (const f of listSessionFiles(cwd, h.sessionsDir(), 4)) {
+      if (f !== ownSession && !out.includes(f)) out.push(f);
+    }
+    return out;
+  }
+
+  async function resolveSessionFile(paneId: string, cwd: string): Promise<string | null> {
+    for (const file of await resolveSessionFileCandidates(paneId, cwd)) {
+      if (readSessionFile(file)) return file;
+    }
+    return null;
+  }
+
+  async function collectFinalText(
+    paneId: string,
+    cwd: string,
+    sinceTs: number,
+    attempts = 12,
+  ): Promise<string | null> {
+    for (let i = 0; i < attempts; i++) {
+      for (const file of await resolveSessionFileCandidates(paneId, cwd)) {
+        const entries = readSessionFile(file);
+        if (!entries) continue;
+        const r = lastAssistantText(entries, { sinceTs });
+        if (r?.text) return r.text;
+      }
+      const wait = Promise.withResolvers<void>();
+      setTimeout(wait.resolve, 500);
+      await wait.promise;
+    }
+    return null;
+  }
+
+  async function readAskFlag(paneId: string): Promise<string | null> {
+    try {
+      const a = (await h.client.listAgents()).find((x) => x.paneId === paneId);
+      const v = a?.tokens?.['pi-ask'];
+      return typeof v === 'string' && v ? v : null;
+    } catch {
+      return null;
+    }
+  }
+
+  async function probeAlive(paneId: string, cwd: string): Promise<AliveProbe> {
+    const probe: AliveProbe = { paneExists: false, agentStatus: null, lastActivityMs: null };
+    try {
+      const agents = await h.client.listAgents();
+      const a = agents.find((x) => x.paneId === paneId);
+      probe.paneExists = a != null;
+      probe.agentStatus = a?.status ?? null;
+    } catch {
+      /* Fall back to session activity when agent.list is unavailable. */
+    }
+    for (const file of await resolveSessionFileCandidates(paneId, cwd)) {
+      try {
+        const mtime = (await statAsync(file)).mtimeMs;
+        if (probe.lastActivityMs == null || mtime > probe.lastActivityMs) probe.lastActivityMs = mtime;
+      } catch {
+        /* Session files can disappear during candidate scanning. */
+      }
+    }
+    return probe;
+  }
+
+  async function subSessionState(
+    paneId: string,
+    cwd: string,
+    sinceTs: number,
+  ): Promise<{ text: string | null; pendingTool: boolean; activity: boolean }> {
+    for (const file of await resolveSessionFileCandidates(paneId, cwd)) {
+      const entries = readSessionFile(file);
+      if (entries.length === 0) continue;
+      const r = lastAssistantText(entries, { sinceTs });
+      if (r?.text) return { text: r.text, pendingTool: false, activity: true };
+      if (hasPendingToolCall(entries, sinceTs)) return { text: null, pendingTool: true, activity: true };
+      if (hasAssistantAfter(entries, sinceTs)) return { text: null, pendingTool: false, activity: true };
+    }
+    return { text: null, pendingTool: false, activity: false };
+  }
+
+  return {
+    resolveSessionFileCandidates,
+    resolveSessionFile,
+    collectFinalText,
+    readAskFlag,
+    probeAlive,
+    subSessionState,
+  };
+}
+