@a5c-ai/babysitter-pi 0.1.0

package/extensions/babysitter/tool-renderer.ts

@@ -0,0 +1,263 @@
+/**
+ * Custom message renderer for babysitter tool calls.
+ *
+ * Registered with oh-my-pi via `pi.registerMessageRenderer` so that
+ * babysitter effect execution results, run status updates, and iteration
+ * progress are displayed in a structured, human-readable format rather
+ * than raw JSON.
+ *
+ * @module tool-renderer
+ */
+
+import type { MessageRenderer } from './types';
+
+// ---------------------------------------------------------------------------
+// Payload interfaces
+// ---------------------------------------------------------------------------
+
+/** The payload shape expected by the babysitter tool renderer. */
+export interface BabysitterToolPayload {
+  effectId: string;
+  kind: string;
+  title: string;
+  success: boolean;
+  value?: unknown;
+  error?: string;
+  durationMs?: number;
+}
+
+/** Payload for the `babysitter:status` message type. */
+export interface RunStatusPayload {
+  runId: string;
+  processId?: string;
+  iteration?: number;
+  status: string;
+  pendingEffectsCount?: number;
+}
+
+/** Payload for the `babysitter:effect-result` message type. */
+export interface EffectResultPayload {
+  effectId: string;
+  kind: string;
+  status: string;
+}
+
+/** Payload for the `babysitter:iteration` message type. */
+export interface IterationPayload {
+  iteration: number;
+  status: string;
+  pendingCount?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Box-drawing helpers
+// ---------------------------------------------------------------------------
+
+const BOX_HORIZONTAL = '\u2500';
+const BOX_VERTICAL = '\u2502';
+const BOX_TOP_LEFT = '\u250C';
+const BOX_TOP_RIGHT = '\u2510';
+const BOX_BOTTOM_LEFT = '\u2514';
+const BOX_BOTTOM_RIGHT = '\u2518';
+
+/**
+ * Wrap a set of lines inside a simple Unicode box.
+ *
+ * @param lines - Content lines (no newlines within each entry).
+ * @param minWidth - Minimum inner width of the box.
+ * @returns The formatted box as a single string.
+ */
+function drawBox(lines: string[], minWidth = 40): string {
+  const innerWidth = Math.max(minWidth, ...lines.map((l) => l.length));
+  const top = `${BOX_TOP_LEFT}${BOX_HORIZONTAL.repeat(innerWidth + 2)}${BOX_TOP_RIGHT}`;
+  const bottom = `${BOX_BOTTOM_LEFT}${BOX_HORIZONTAL.repeat(innerWidth + 2)}${BOX_BOTTOM_RIGHT}`;
+  const body = lines.map((l) => `${BOX_VERTICAL} ${l.padEnd(innerWidth)} ${BOX_VERTICAL}`);
+  return [top, ...body, bottom].join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Public format helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Format run status as a clean multi-line display inside a box.
+ *
+ * Shows: run ID, process, iteration, status, and pending effects count.
+ *
+ * @param data - The run status payload (loosely typed for renderer compatibility).
+ * @returns A formatted multi-line string.
+ */
+export function formatRunStatus(data: unknown): string {
+  const d = (data ?? {}) as Record<string, unknown>;
+  const runId = typeof d['runId'] === 'string' ? d['runId'] : 'unknown';
+  const processId = typeof d['processId'] === 'string' ? d['processId'] : 'n/a';
+  const iteration =
+    typeof d['iteration'] === 'number' ? String(d['iteration']) : 'n/a';
+  const status = typeof d['status'] === 'string' ? d['status'] : 'unknown';
+  const pending =
+    typeof d['pendingEffectsCount'] === 'number'
+      ? String(d['pendingEffectsCount'])
+      : '0';
+
+  const lines = [
+    `Run Status`,
+    `${'─'.repeat(38)}`,
+    `  Run ID  : ${runId}`,
+    `  Process : ${processId}`,
+    `  Iter    : ${iteration}`,
+    `  Status  : ${status}`,
+    `  Pending : ${pending} effect(s)`,
+  ];
+
+  return drawBox(lines);
+}
+
+/**
+ * Compact one-line format for an effect completion summary.
+ *
+ * Format: `Effect <effectId> (<kind>): <status>`
+ *
+ * @param data - The effect result payload (loosely typed for renderer compatibility).
+ * @returns A single-line formatted string.
+ */
+export function formatEffectResult(data: unknown): string {
+  const d = (data ?? {}) as Record<string, unknown>;
+  const effectId = typeof d['effectId'] === 'string' ? d['effectId'] : 'unknown';
+  const kind = typeof d['kind'] === 'string' ? d['kind'] : 'unknown';
+  const status = typeof d['status'] === 'string' ? d['status'] : 'unknown';
+
+  return `Effect ${effectId} (${kind}): ${status}`;
+}
+
+/**
+ * Format an iteration progress summary.
+ *
+ * Format: `Iteration N: <status> | <pending count> pending effects`
+ *
+ * @param data - The iteration payload (loosely typed for renderer compatibility).
+ * @returns A single-line formatted string.
+ */
+export function formatIterationSummary(data: unknown): string {
+  const d = (data ?? {}) as Record<string, unknown>;
+  const iteration =
+    typeof d['iteration'] === 'number' ? d['iteration'] : 0;
+  const status = typeof d['status'] === 'string' ? d['status'] : 'unknown';
+  const pendingCount =
+    typeof d['pendingCount'] === 'number' ? d['pendingCount'] : 0;
+
+  return `Iteration ${iteration}: ${status} | ${pendingCount} pending effects`;
+}
+
+// ---------------------------------------------------------------------------
+// Tool-result renderer (original functionality, preserved)
+// ---------------------------------------------------------------------------
+
+/**
+ * Create the babysitter tool-result message renderer.
+ *
+ * Returns a {@link MessageRenderer} that formats babysitter effect results
+ * for the TUI.
+ *
+ * @returns A renderer function that converts payloads to display strings.
+ */
+export function createToolRenderer(): MessageRenderer {
+  return (payload: unknown): string => {
+    if (!isBabysitterPayload(payload)) {
+      return `[babysitter] Unrecognised payload: ${JSON.stringify(payload)}`;
+    }
+
+    return formatToolResult(payload);
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Registration entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Register all babysitter-related message renderers with oh-my-pi.
+ *
+ * Registers renderers for the following message types:
+ * - `babysitter:tool-result` -- per-effect execution result
+ * - `babysitter:status`       -- run status overview (formatted box)
+ * - `babysitter:effect-result` -- compact effect completion summary
+ * - `babysitter:iteration`    -- iteration progress line
+ *
+ * @param pi - The oh-my-pi ExtensionAPI (or compatible object exposing
+ *             `registerMessageRenderer`).
+ */
+export function registerBabysitterRenderers(pi: unknown): void {
+  const api = pi as { registerMessageRenderer(type: string, renderer: MessageRenderer): void };
+
+  // Per-effect tool execution result (original renderer)
+  api.registerMessageRenderer('babysitter:tool-result', createToolRenderer());
+
+  // Run status box
+  api.registerMessageRenderer('babysitter:status', (payload: unknown): string => {
+    return formatRunStatus(payload);
+  });
+
+  // Effect completion one-liner
+  api.registerMessageRenderer('babysitter:effect-result', (payload: unknown): string => {
+    return formatEffectResult(payload);
+  });
+
+  // Iteration progress
+  api.registerMessageRenderer('babysitter:iteration', (payload: unknown): string => {
+    return formatIterationSummary(payload);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Format a single effect result into a readable string.
+ *
+ * @param p - The structured payload.
+ * @returns A formatted string for display.
+ */
+function formatToolResult(p: BabysitterToolPayload): string {
+  const statusIcon = p.success ? '[OK]' : '[FAIL]';
+  const duration = p.durationMs !== undefined ? ` (${p.durationMs}ms)` : '';
+
+  const lines: string[] = [
+    `${statusIcon} ${p.kind}: ${p.title}${duration}`,
+    `    effect: ${p.effectId}`,
+  ];
+
+  if (p.success && p.value !== undefined) {
+    const valueStr =
+      typeof p.value === 'string' ? p.value : JSON.stringify(p.value, null, 2);
+    // Truncate long values
+    const truncated =
+      valueStr.length > 500 ? valueStr.slice(0, 497) + '...' : valueStr;
+    lines.push(`    result: ${truncated}`);
+  }
+
+  if (!p.success && p.error) {
+    lines.push(`    error: ${p.error}`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Type guard for {@link BabysitterToolPayload}.
+ */
+function isBabysitterPayload(
+  value: unknown,
+): value is BabysitterToolPayload {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+
+  const obj = value as Record<string, unknown>;
+  return (
+    typeof obj['effectId'] === 'string' &&
+    typeof obj['kind'] === 'string' &&
+    typeof obj['title'] === 'string' &&
+    typeof obj['success'] === 'boolean'
+  );
+}

package/extensions/babysitter/tui-widgets.ts

@@ -0,0 +1,164 @@
+/**
+ * TUI widget rendering for babysitter orchestration state.
+ *
+ * Renders run progress, pending effects, and quality scores into
+ * oh-my-pi's widget panels via `pi.setWidget(key, lines[])` so the
+ * user can monitor babysitter activity without leaving the terminal.
+ *
+ * @module tui-widgets
+ */
+
+import type { RunState } from './session-binder.js';
+
+// ---------------------------------------------------------------------------
+// Widget keys
+// ---------------------------------------------------------------------------
+
+const WIDGET_KEY_RUN = 'babysitter:run';
+const WIDGET_KEY_EFFECTS = 'babysitter:effects';
+const WIDGET_KEY_QUALITY = 'babysitter:quality';
+
+// ---------------------------------------------------------------------------
+// formatElapsed
+// ---------------------------------------------------------------------------
+
+/**
+ * Format elapsed time from an ISO-8601 timestamp to a human-readable string.
+ *
+ * Returns the most compact representation that still conveys the duration:
+ * - Under a minute: `"42s"`
+ * - Under an hour:  `"5m 32s"`
+ * - An hour or more: `"1h 12m 5s"`
+ *
+ * @param startedAt - ISO-8601 timestamp string.
+ * @returns A formatted duration string.
+ */
+export function formatElapsed(startedAt: string): string {
+  const elapsedMs = Date.now() - new Date(startedAt).getTime();
+  const totalSeconds = Math.max(0, Math.floor(elapsedMs / 1000));
+
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const seconds = totalSeconds % 60;
+
+  if (hours > 0) {
+    return `${hours}h ${minutes}m ${seconds}s`;
+  }
+  if (minutes > 0) {
+    return `${minutes}m ${seconds}s`;
+  }
+  return `${seconds}s`;
+}
+
+// ---------------------------------------------------------------------------
+// renderRunWidget
+// ---------------------------------------------------------------------------
+
+/**
+ * Render the babysitter run progress widget.
+ *
+ * Displays the run ID, process ID, current iteration/status, and elapsed
+ * time as a set of compact lines in the `"babysitter:run"` widget panel.
+ *
+ * @param runState - The current {@link RunState} snapshot.
+ * @param pi       - The oh-my-pi extension API handle (must expose `setWidget`).
+ */
+export function renderRunWidget(runState: RunState, pi: any): void {
+  const elapsed = formatElapsed(runState.startedAt);
+  const statusLabel = runState.status ?? 'unknown';
+
+  const lines: string[] = [
+    `Babysitter Run: ${runState.runId}`,
+    `Process: ${runState.processId}`,
+    `Iteration: ${runState.iteration}/${runState.maxIterations} | Status: ${statusLabel}`,
+    `Elapsed: ${elapsed}`,
+  ];
+
+  pi.setWidget(WIDGET_KEY_RUN, lines);
+}
+
+// ---------------------------------------------------------------------------
+// renderEffectsWidget
+// ---------------------------------------------------------------------------
+
+/**
+ * Render the pending effects widget.
+ *
+ * Shows a compact list of effects currently awaiting resolution. Each
+ * effect is expected to have at least a `kind` property; a `title` or
+ * `label` property is used for the human-readable description when
+ * available.
+ *
+ * @param effects - Array of effect descriptors (objects with `kind` and
+ *                  optionally `title` / `label` / `taskId` fields).
+ * @param pi      - The oh-my-pi extension API handle.
+ */
+export function renderEffectsWidget(effects: any[], pi: any): void {
+  if (!effects || effects.length === 0) {
+    pi.setWidget(WIDGET_KEY_EFFECTS, ['Pending Effects (0)']);
+    return;
+  }
+
+  const header = `Pending Effects (${effects.length}):`;
+  const itemLines = effects.map((effect: any) => {
+    const kind: string = effect.kind ?? 'unknown';
+    const title: string = effect.title ?? effect.label ?? effect.taskId ?? kind;
+    return `  [${kind}] ${title}`;
+  });
+
+  pi.setWidget(WIDGET_KEY_EFFECTS, [header, ...itemLines]);
+}
+
+// ---------------------------------------------------------------------------
+// renderQualityWidget
+// ---------------------------------------------------------------------------
+
+/**
+ * Render the quality score widget with a visual progress bar.
+ *
+ * Displays the current score against the target threshold using an
+ * ASCII progress bar. The bar is 16 characters wide; an arrow (`>`)
+ * marks the current position.
+ *
+ * @param score  - The current quality score (0-100).
+ * @param target - The target quality threshold (0-100).
+ * @param pi     - The oh-my-pi extension API handle.
+ */
+export function renderQualityWidget(score: number, target: number, pi: any): void {
+  const barWidth = 16;
+  const maxVal = Math.max(target, 100);
+  const filled = Math.round((score / maxVal) * barWidth);
+  const clamped = Math.min(filled, barWidth);
+
+  let bar = '';
+  for (let i = 0; i < barWidth; i++) {
+    if (i < clamped && i !== clamped - 1) {
+      bar += '=';
+    } else if (i === clamped - 1 && clamped > 0) {
+      bar += '>';
+    } else {
+      bar += ' ';
+    }
+  }
+
+  const line = `Quality: ${score}/${target} [${bar}]`;
+  pi.setWidget(WIDGET_KEY_QUALITY, [line]);
+}
+
+// ---------------------------------------------------------------------------
+// clearWidgets
+// ---------------------------------------------------------------------------
+
+/**
+ * Clear all babysitter TUI widgets.
+ *
+ * Sets each widget key to an empty array so oh-my-pi removes the panels
+ * from the display.
+ *
+ * @param pi - The oh-my-pi extension API handle.
+ */
+export function clearWidgets(pi: any): void {
+  pi.setWidget(WIDGET_KEY_RUN, []);
+  pi.setWidget(WIDGET_KEY_EFFECTS, []);
+  pi.setWidget(WIDGET_KEY_QUALITY, []);
+}

package/extensions/babysitter/types.ts

@@ -0,0 +1,222 @@
+/**
+ * TypeScript type definitions for the babysitter oh-my-pi extension.
+ *
+ * Defines the contracts between extension modules,
+ * the oh-my-pi ExtensionAPI surface, and babysitter run state.
+ *
+ * @module types
+ */
+
+// ---------------------------------------------------------------------------
+// oh-my-pi ExtensionAPI surface (subset relevant to this extension)
+// ---------------------------------------------------------------------------
+
+/** Handler that can optionally block a tool call. */
+export interface ToolCallInterceptResult {
+  block: boolean;
+  reason?: string;
+}
+
+/** A tool definition registered with oh-my-pi. */
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>;
+  handler: (params: Record<string, unknown>) => Promise<unknown>;
+}
+
+/** An entry appended to the oh-my-pi session log. */
+export interface SessionEntry {
+  type: string;
+  content: unknown;
+  timestamp?: string;
+}
+
+/** Message payload for pi.sendMessage / pi.sendUserMessage. */
+export interface PiMessage {
+  role: 'user' | 'assistant' | 'system';
+  content: string;
+}
+
+/** Custom renderer for a specific message type. */
+export type MessageRenderer = (payload: unknown) => string;
+
+/**
+ * The oh-my-pi Extension API surface.
+ *
+ * This is the primary interface handed to `activate()` by the host.
+ */
+export interface ExtensionAPI {
+  /** Subscribe to a lifecycle or data event. */
+  on(
+    event:
+      | 'session_start'
+      | 'agent_end'
+      | 'session_shutdown'
+      | 'before_agent_start'
+      | 'tool_call'
+      | 'tool_result'
+      | 'context'
+      | 'input'
+      | 'turn_start'
+      | 'turn_end',
+    handler: (...args: unknown[]) => unknown,
+  ): void;
+
+  /** Register a custom tool with the host. */
+  registerTool(toolDef: ToolDefinition): void;
+
+  /** Register a slash command. */
+  registerCommand(name: string, options: { description?: string; handler: (...args: unknown[]) => unknown }): void;
+
+  /** Register a custom message renderer for a given type. */
+  registerMessageRenderer(type: string, renderer: MessageRenderer): void;
+
+  /** Append an entry to the session log. */
+  appendEntry(entry: SessionEntry): void;
+
+  /** Inject a message into the conversation. */
+  sendMessage(msg: PiMessage): void;
+
+  /** Inject a user-role message into the conversation. */
+  sendUserMessage(msg: PiMessage): void;
+
+  /** Retrieve the currently active tool set. */
+  getActiveTools(): ToolDefinition[];
+
+  /** Replace the active tool set. */
+  setActiveTools(tools: ToolDefinition[]): void;
+}
+
+// ---------------------------------------------------------------------------
+// Babysitter run / effect state
+// ---------------------------------------------------------------------------
+
+/** Possible states of a babysitter run. */
+export type RunStatus = 'pending' | 'running' | 'completed' | 'failed' | 'waiting';
+
+/** Kinds of effects the babysitter runtime can request. */
+export type EffectKind =
+  | 'agent'
+  | 'node'
+  | 'shell'
+  | 'breakpoint'
+  | 'sleep'
+  | 'skill'
+  | 'orchestrator_task';
+
+/** A single babysitter effect descriptor. */
+export interface EffectDef {
+  /** Unique effect identifier (ULID). */
+  effectId: string;
+  /** The kind of work to perform. */
+  kind: EffectKind;
+  /** Human-readable title. */
+  title: string;
+  /** Task identifier. */
+  taskId: string;
+  /** Arbitrary arguments for the task implementation. */
+  args: Record<string, unknown>;
+  /** Labels attached to the task definition. */
+  labels?: string[];
+}
+
+/** Snapshot of a babysitter run as tracked by this extension. */
+export interface RunState {
+  /** The active run identifier. */
+  runId: string;
+  /** The oh-my-pi session identifier bound to this run. */
+  sessionId: string;
+  /** Current run status. */
+  status: RunStatus;
+  /** Number of orchestration iterations completed so far. */
+  iterationCount: number;
+  /** ISO-8601 timestamp when the run started. */
+  startedAt: string;
+  /** Effects currently pending execution. */
+  pendingEffects: EffectDef[];
+  /** Effects that have been resolved. */
+  resolvedEffects: EffectDef[];
+  /** Consecutive error counter (for guard thresholds). */
+  consecutiveErrors: number;
+  /** Most recent quality / score value, if available. */
+  lastScore?: number;
+  /** Current phase label (e.g. "plan", "execute", "verify"). */
+  currentPhase?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Guard configuration
+// ---------------------------------------------------------------------------
+
+/** Configurable limits checked by the guard module. */
+export interface GuardConfig {
+  /** Maximum number of orchestration iterations before aborting. */
+  maxIterations: number;
+  /** Maximum wall-clock time (ms) before aborting. */
+  maxDurationMs: number;
+  /** Consecutive error count that triggers an abort. */
+  errorThreshold: number;
+  /** Number of identical iteration outputs that indicate a doom loop. */
+  doomLoopWindow: number;
+}
+
+/** Result returned by the guard check. */
+export interface GuardResult {
+  /** Whether the run should continue. */
+  allowed: boolean;
+  /** Human-readable reason when `allowed` is false. */
+  reason?: string;
+}
+
+// ---------------------------------------------------------------------------
+// TUI / widget state
+// ---------------------------------------------------------------------------
+
+/** State bag consumed by TUI widget renderers. */
+export interface WidgetState {
+  /** Run identifier. */
+  runId: string;
+  /** Current phase label. */
+  phase: string;
+  /** Number of pending tasks. */
+  pendingCount: number;
+  /** Number of resolved tasks. */
+  resolvedCount: number;
+  /** Total tasks seen so far. */
+  totalCount: number;
+  /** Latest quality score. */
+  score?: number;
+  /** Elapsed wall-clock time in ms. */
+  elapsedMs: number;
+}
+
+// ---------------------------------------------------------------------------
+// CLI output shapes
+// ---------------------------------------------------------------------------
+
+/** JSON output from `babysitter run:iterate --json`. */
+export interface IterateOutput {
+  status: RunStatus;
+  pendingActions?: EffectDef[];
+  output?: unknown;
+  error?: string;
+}
+
+/** JSON output from `babysitter session:init --json`. */
+export interface SessionInitOutput {
+  sessionId: string;
+  runsDir: string;
+}
+
+/** JSON output from `babysitter session:associate --json`. */
+export interface SessionAssociateOutput {
+  runId: string;
+  sessionId: string;
+}
+
+/** JSON output from `babysitter task:post --json`. */
+export interface TaskPostOutput {
+  effectId: string;
+  recorded: boolean;
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@a5c-ai/babysitter-pi",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Babysitter plugin package for the upstream pi coding agent",
+  "keywords": [
+    "pi",
+    "babysitter",
+    "orchestration",
+    "ai-agent"
+  ],
+  "omp": {
+    "extensions": [
+      "./extensions"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "dependencies": {
+    "@a5c-ai/babysitter-sdk": "0.0.184-staging.26c556be"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*"
+  },
+  "scripts": {
+    "test": "node --test test/integration.test.js && npx tsx --test test/harness.test.js && npx tsx --test test/tui.test.js",
+    "sync:commands": "node scripts/sync-command-docs.cjs",
+    "test:integration": "node --test test/integration.test.js",
+    "test:harness": "npx tsx --test test/harness.test.js",
+    "test:tui": "npx tsx --test test/tui.test.js",
+    "deploy": "npm publish --access public",
+    "deploy:staging": "npm publish --access public --tag staging"
+  },
+  "bin": {
+    "babysitter-pi": "bin/cli.cjs"
+  },
+  "files": [
+    "bin/",
+    "package.json",
+    "extensions/",
+    "skills/",
+    "commands/",
+    "scripts/"
+  ],
+  "author": "a5c.ai",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/a5c-ai/babysitter"
+  },
+  "homepage": "https://github.com/a5c-ai/babysitter/tree/main/plugins/babysitter-pi#readme"
+}