piher 0.0.0-stage → 0.2.0

package/src/settle-wake-core.ts

@@ -0,0 +1,73 @@
+/**
+ * Settled-wake decision (prevents wake storms): a settle wake that injects messages creates a
+ * self-triggering loop (settle → notice → new run → settle → …) that even ESC cannot break, so an
+ * aborted previous turn injects nothing and a running set is announced once, re-announced only after
+ * D96_REPEAT_NOTICE_MS or when the set changes.
+ */
+
+export const ABORT_STOP_REASON = 'aborted';
+
+/** pi/provider failure stop. pi auto-retries these, so the run has not settled for the user. */
+export const ERROR_STOP_REASON = 'error';
+
+/** D96: cooldown before repeating a notice for the same running set. */
+export const D96_REPEAT_NOTICE_MS = 10 * 60_000;
+
+export interface SettleWakeInput {
+  /** stopReason of the last assistant turn (null = treated as natural completion). */
+  lastStopReason: string | null;
+  /**
+   * pi ≥ 1.1 carries `aborted` on agent_settled itself: authoritative for runs cancelled without a
+   * final assistant message (ESC mid-tool), where stopReason tracking sees a stale natural reason.
+   */
+  aborted?: boolean;
+  running: ReadonlyArray<{ paneId: string }>;
+  lastNoticeKey: string | null;
+  lastNoticeAt: number;
+  now: number;
+}
+
+export interface SettleWakePlan {
+  /** false means this settlement stays silent and emits no wake-up message. */
+  wake: boolean;
+  notice: boolean;
+  /** New set key; empty running set → null. */
+  noticeKey: string | null;
+  noticeAt: number;
+}
+
+export function planSettleWake(input: SettleWakeInput): SettleWakePlan {
+  if (input.aborted === true || input.lastStopReason === ABORT_STOP_REASON) {
+    return {
+      wake: false,
+      notice: false,
+      noticeKey: input.lastNoticeKey,
+      noticeAt: input.lastNoticeAt,
+    };
+  }
+  const key = input.running.length === 0 ? null : input.running.map((s) => s.paneId).sort().join(',');
+  if (key === null) {
+    return { wake: true, notice: false, noticeKey: null, noticeAt: input.lastNoticeAt };
+  }
+  const newSet = key !== input.lastNoticeKey;
+  const cooled = input.now - input.lastNoticeAt >= D96_REPEAT_NOTICE_MS;
+  const notice = newSet || cooled;
+  return { wake: true, notice, noticeKey: key, noticeAt: notice ? input.now : input.lastNoticeAt };
+}
+
+/**
+ * Whether a just-settled run may answer its pending machine request (the pipe settle fast-path).
+ * A user abort ('aborted') settles a run that may re-run, and an 'error' stop is an upstream
+ * failure pi retries — answering then reports "finished, no closing message" for live work and
+ * consumes the one-shot request plus the parent's claim latch, so the real closing message can
+ * never be delivered.
+ */
+export function shouldPushSettleReply(input: {
+  /** pi ≥ 1.1 agent_settled.aborted: the run was cancelled — the closing message may still come after a re-run. */
+  aborted?: boolean;
+  lastStopReason: string | null;
+}): boolean {
+  return input.aborted !== true
+    && input.lastStopReason !== ABORT_STOP_REASON
+    && input.lastStopReason !== ERROR_STOP_REASON;
+}

package/src/settlement-card.ts

@@ -0,0 +1,96 @@
+/**
+ * A settlement travels as a custom `piher.settlement` message: the transcript draws a card
+ * (name, role, outcome, elapsed) while the text the model reads stays exactly the settlement
+ * notice. A host without custom-message support gets the same text as a plain user message, so
+ * delivery never depends on the rendering.
+ */
+
+export const SETTLEMENT_CUSTOM_TYPE = 'piher.settlement';
+
+/** Why the worker left: normal settlement, a dead pane / settle timeout, or a reclaimed row. */
+export type SettlementOutcome = 'settled' | 'failed' | 'closed';
+
+/** Card fields only — the notice text itself is the message content. */
+export interface SettlementCard {
+  name: string;
+  /** Role name from the ledger row's `kind`; `null` for a plain task. */
+  role: string | null;
+  outcome: SettlementOutcome;
+  /** Worker lifetime, spawn → settlement; `null` when the row is gone. */
+  elapsedMs: number | null;
+}
+
+/** `12s` / `3m04s` / `2h11m`: short enough for a card header, unambiguous at a glance. */
+export function formatElapsed(ms: number): string {
+  const seconds = Math.max(0, Math.round(ms / 1000));
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m${String(seconds % 60).padStart(2, '0')}s`;
+  return `${Math.floor(minutes / 60)}h${String(minutes % 60).padStart(2, '0')}m`;
+}
+
+/** `kind` is the ledger row's role label; `'task'` (the default) means the worker ran no role. */
+export function settlementRole(kind: string | null | undefined): string | null {
+  return typeof kind === 'string' && kind !== '' && kind !== 'task' ? kind : null;
+}
+
+export function settlementCard(input: {
+  name: string;
+  kind?: string | null;
+  outcome: SettlementOutcome;
+  startedAt?: number | null;
+  now?: number;
+}): SettlementCard {
+  const now = input.now ?? Date.now();
+  const startedAt = typeof input.startedAt === 'number' && Number.isFinite(input.startedAt)
+    ? input.startedAt
+    : null;
+  return {
+    name: input.name,
+    role: settlementRole(input.kind),
+    outcome: input.outcome,
+    elapsedMs: startedAt === null ? null : Math.max(0, now - startedAt),
+  };
+}
+
+export interface SettlementMessageApi {
+  sendMessage?(
+    message: { customType: string; content: string; display: boolean; details?: unknown },
+    opts?: { deliverAs?: string; triggerTurn?: boolean },
+  ): void;
+  sendUserMessage?(content: string, opts?: { deliverAs?: string; triggerTurn?: boolean }): void;
+}
+
+/**
+ * Deliver one settlement notice. Custom message first (card rendered, content untouched), then the
+ * plain notice when the host has no custom messages or the renderer could not be registered; a
+ * synchronous throw from either path propagates so the caller can retry instead of losing the
+ * settlement.
+ */
+export async function sendSettlementNotice(
+  api: SettlementMessageApi,
+  input: {
+    content: string;
+    mode: 'steer' | 'followUp';
+    /** Absent for a collapsed batch: the card describes one settlement, the batch text covers many. */
+    card?: SettlementCard | null;
+    /** False when no `registerMessageRenderer` exists, so a card would render as raw JSON. */
+    cardsRendered: boolean;
+  },
+): Promise<void> {
+  const opts = { deliverAs: input.mode, triggerTurn: true };
+  if (input.cardsRendered && typeof api.sendMessage === 'function') {
+    try {
+      api.sendMessage({
+        customType: SETTLEMENT_CUSTOM_TYPE,
+        content: input.content,
+        display: true,
+        ...(input.card ? { details: input.card } : {}),
+      }, opts);
+      return;
+    } catch {
+      /* Older host or a rejected custom message: the plain notice below is the delivery. */
+    }
+  }
+  api.sendUserMessage?.(input.content, opts);
+}

package/src/storage-layout.ts

@@ -0,0 +1,92 @@
+/**
+ * Storage path layout (session dirs, role dirs) — the single owner of the
+ * session-dir encoding, so session-tail / role-loader cannot drift apart.
+ *
+ * Reads try pi core's own directory name first, then piher's collision-resistant encoding
+ * (`a/b` ≠ `a-b`), because both spellings can exist on disk.
+ */
+import { readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+
+/** One shape for every per-session id carved out of a transcript path (worker marker, session dir). */
+const SAFE_SESSION_ID_RE = /^[a-z0-9][a-z0-9._-]*$/i;
+
+export function isValidSessionId(id: string | null | undefined): boolean {
+  return typeof id === 'string' && id.length > 0 && SAFE_SESSION_ID_RE.test(id);
+}
+
+/** Collision-resistant name: `%` is escaped first so `/` `\` `:` round-trip (`a/b` → `--a%2Fb--`). */
+export function sessionDirName(cwd: string): string {
+  const encoded = cwd
+    .replace(/%/g, '%25')
+    .replace(/\\/g, '%5C')
+    .replace(/\//g, '%2F')
+    .replace(/:/g, '%3A');
+  return `--${encoded}--`;
+}
+
+/**
+ * pi core's own session-directory encoding, byte-for-byte: strip ONE leading separator, then flatten
+ * `/` `\` `:` — it does NOT escape `%` like `sessionDirName`. `<agentDir>/sessions/` is pi core's
+ * directory, so reading pi sessions must match it exactly.
+ */
+export function piCoreSessionDirName(cwd: string): string {
+  return `--${cwd.replace(/^[/\\]/, '').replace(/[/\\:]/g, '-')}--`;
+}
+
+/**
+ * pi core's exact name first, then piher's own encoding. Read-only: writes to
+ * `<agentDir>/sessions/` are pi core's business.
+ */
+export function piSessionDirCandidates(cwd: string): readonly string[] {
+  return [...new Set([piCoreSessionDirName(cwd), sessionDirName(cwd)])];
+}
+
+/**
+ * Main worktree root of the repository containing `cwd`, or null when `cwd` is not in a working
+ * tree. Mirrors the first entry of `git worktree list --porcelain` without spawning git, because the
+ * ledger is written on a synchronous path: a main checkout has a `.git` directory, a linked
+ * worktree has a `.git` file whose `commondir` points back at the main checkout's `.git`.
+ */
+export function mainWorktreeRoot(cwd: string): string | null {
+  let dir = resolve(cwd);
+  try {
+    if (!statSync(dir).isDirectory()) return null;
+  } catch {
+    return null; // a collected checkout (deleted worktree) has no repository to write into
+  }
+  for (;;) {
+    const dotGit = join(dir, '.git');
+    let isDir: boolean | null = null;
+    try {
+      isDir = statSync(dotGit).isDirectory();
+    } catch {
+      isDir = null;
+    }
+    if (isDir === true) return dir;
+    if (isDir === false) {
+      try {
+        const m = /^gitdir:\s*(.+)$/m.exec(readFileSync(dotGit, 'utf8'));
+        if (!m) return null;
+        const gitdir = resolve(dir, m[1]!.trim());
+        // A linked worktree records the shared git dir in `commondir` (`../..` from its own gitdir).
+        // A submodule or a bare redirect has no commondir and owns no working tree here.
+        return dirname(resolve(gitdir, readFileSync(join(gitdir, 'commondir'), 'utf8').trim()));
+      } catch {
+        return null;
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+export function userRolesDir(): string {
+  return join(homedir(), '.pi', 'agent', 'piher', 'roles');
+}
+
+export function workspaceRolesDir(baseDir: string): string {
+  return join(baseDir, '.piher', 'roles');
+}