From 59c755067e0d99ed3099c0da33c982953f1ff430 Mon Sep 17 00:00:00 2001 From: Jason Woltje Date: Mon, 22 Jun 2026 01:43:18 +0000 Subject: [PATCH] =?UTF-8?q?feat(fleet):=20F3-m2=20=E2=80=94=20native=20Pi?= =?UTF-8?q?=20heartbeat=20+=20model=20surface=20+=20mosaic=5Fmission=5Fsta?= =?UTF-8?q?tus=20tool=20(#602)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jason Woltje Co-committed-by: Jason Woltje --- .../framework/runtime/pi/mosaic-extension.ts | 127 +++++++++++++++++- .../tools/fleet/start-agent-session.sh | 13 +- packages/mosaic/src/commands/fleet.spec.ts | 11 ++ packages/mosaic/src/commands/fleet.ts | 13 +- 4 files changed, 155 insertions(+), 9 deletions(-) diff --git a/packages/mosaic/framework/runtime/pi/mosaic-extension.ts b/packages/mosaic/framework/runtime/pi/mosaic-extension.ts index 92f4185..cbf783f 100644 --- a/packages/mosaic/framework/runtime/pi/mosaic-extension.ts +++ b/packages/mosaic/framework/runtime/pi/mosaic-extension.ts @@ -9,8 +9,16 @@ * 4. Memory routing — remind agent to use ~/.config/mosaic/memory/ */ -import type { ExtensionAPI } from '@mariozechner/pi-coding-agent'; -import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync } from 'node:fs'; +import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'; +import { Type } from 'typebox'; +import { + existsSync, + readFileSync, + writeFileSync, + unlinkSync, + mkdirSync, + renameSync, +} from 'node:fs'; import { join, basename } from 'node:path'; import { homedir } from 'node:os'; import { execSync, spawnSync } from 'node:child_process'; @@ -25,6 +33,57 @@ const MOSAIC_HOME = process.env['MOSAIC_HOME'] ?? join(homedir(), '.config', 'mo // Helpers // --------------------------------------------------------------------------- +// --------------------------------------------------------------------------- +// Native heartbeat (fleet R14/R15) +// --------------------------------------------------------------------------- +// When this agent runs under the Mosaic fleet (MOSAIC_AGENT_NAME set), the +// extension writes its OWN heartbeat in the same .hb contract `fleet ps` reads +// (ts/pid/status[/model]) and touches a `.hb.native` precedence marker so the +// shell sidecar defers. Native HB knows the real turn state (busy/ok), so it is +// more accurate than the pane-PID-only sidecar fallback. +const HB_AGENT_NAME = process.env['MOSAIC_AGENT_NAME'] ?? ''; +const HB_RUN_DIR = process.env['MOSAIC_HEARTBEAT_RUN_DIR'] ?? join(MOSAIC_HOME, 'fleet', 'run'); +const HB_INTERVAL_MS = (() => { + const s = Number.parseInt(process.env['MOSAIC_HEARTBEAT_INTERVAL'] ?? '', 10); + return Number.isFinite(s) && s > 0 ? s * 1000 : 15_000; +})(); + +function nativeHbEnabled(): boolean { + return HB_AGENT_NAME.length > 0; +} + +function readModelId(ctx: ExtensionContext): string | null { + const m = ctx.model as unknown as { id?: string; name?: string } | undefined; + return m?.id ?? m?.name ?? null; +} + +function writeNativeHeartbeat(status: 'ok' | 'busy', model: string | null): void { + if (!nativeHbEnabled()) return; + try { + mkdirSync(HB_RUN_DIR, { recursive: true }); + const hb = join(HB_RUN_DIR, `${HB_AGENT_NAME}.hb`); + const lines = [`ts=${nowIso()}`, `pid=${process.pid}`, `status=${status}`]; + if (model) lines.push(`model=${model}`); + const tmp = `${hb}.tmp.${process.pid}`; + writeFileSync(tmp, lines.join('\n') + '\n'); + renameSync(tmp, hb); // atomic replace — fleet ps never reads a partial file + // Precedence marker: tells the shell sidecar that native HB is authoritative. + writeFileSync(join(HB_RUN_DIR, `${HB_AGENT_NAME}.hb.native`), nowIso() + '\n'); + } catch { + // Best-effort: never let heartbeat I/O disrupt the Pi session. + } +} + +function clearNativeMarker(): void { + if (!nativeHbEnabled()) return; + try { + const m = join(HB_RUN_DIR, `${HB_AGENT_NAME}.hb.native`); + if (existsSync(m)) unlinkSync(m); // native stopping — let the sidecar take over + } catch { + /* ignore */ + } +} + function safeRead(filePath: string): string | null { try { return readFileSync(filePath, 'utf-8'); @@ -187,6 +246,9 @@ function buildMissionSummary(cwd: string, mission: ActiveMission): string { export default function register(pi: ExtensionAPI) { let sessionCwd = process.cwd(); + let hbStatus: 'ok' | 'busy' = 'ok'; + let hbModel: string | null = null; + let hbTimer: ReturnType | null = null; // ── Session Start ───────────────────────────────────────────────────── pi.on('session_start', async (_event, ctx) => { @@ -207,10 +269,39 @@ export default function register(pi: ExtensionAPI) { } else { ctx.ui.notify('Mosaic framework loaded', 'info'); } + + // Native heartbeat: write immediately, then on an interval. Idle = 'ok'; + // turn_start/turn_end flip the status so `fleet ps` reflects real activity. + if (nativeHbEnabled()) { + hbModel = readModelId(ctx); + writeNativeHeartbeat('ok', hbModel); + hbTimer = setInterval(() => writeNativeHeartbeat(hbStatus, hbModel), HB_INTERVAL_MS); + if (typeof hbTimer.unref === 'function') hbTimer.unref(); + } }); - // ── Session End ─────────────────────────────────────────────────────── - pi.on('session_end', async (_event, _ctx) => { + // ── Turn lifecycle → accurate busy/ok heartbeat ─────────────────────── + pi.on('turn_start', async (_event, ctx) => { + hbStatus = 'busy'; + hbModel = readModelId(ctx) ?? hbModel; + writeNativeHeartbeat('busy', hbModel); + }); + pi.on('turn_end', async (_event, ctx) => { + hbStatus = 'ok'; + hbModel = readModelId(ctx) ?? hbModel; + writeNativeHeartbeat('ok', hbModel); + }); + + // ── Session Shutdown ────────────────────────────────────────────────── + // (The pi API event is 'session_shutdown'; the prior 'session_end' handler + // never fired — fixed here so repo hooks + lock cleanup actually run.) + pi.on('session_shutdown', async (_event, _ctx) => { + if (hbTimer) { + clearInterval(hbTimer); + hbTimer = null; + } + clearNativeMarker(); + // Run repo session-end hook runRepoHook(sessionCwd, 'session-end'); @@ -252,4 +343,32 @@ export default function register(pi: ExtensionAPI) { } }, }); + + // ── Register mosaic_mission_status tool (model-callable) ────────────── + // R14 "proper tool usage": give the agent a first-class tool to load its + // active Mosaic mission, milestone progress, task counts, and latest + // scratchpad — so it self-orients on in-flight work before planning, + // instead of shelling out or guessing. Mirrors the /mosaic-status command + // but returns the summary as tool output the LLM can read. + pi.registerTool({ + name: 'mosaic_mission_status', + label: 'Mosaic Mission Status', + description: + 'Return the active Mosaic mission, milestone progress, task counts, and latest scratchpad for the current project. Returns a note when no mission is active.', + promptSnippet: 'Read the active Mosaic mission + task state for the current project', + promptGuidelines: [ + 'Use mosaic_mission_status at the start of a session or task to load the active mission, milestone progress, and open tasks before planning work.', + ], + parameters: Type.Object({}), + async execute(_toolCallId, _params, _signal, _onUpdate, _ctx) { + const mission = detectMission(sessionCwd); + const text = mission + ? buildMissionSummary(sessionCwd, mission) + : 'No active Mosaic mission in this project.'; + return { + content: [{ type: 'text', text }], + details: mission ? { ...mission } : { active: false }, + }; + }, + }); } diff --git a/packages/mosaic/framework/tools/fleet/start-agent-session.sh b/packages/mosaic/framework/tools/fleet/start-agent-session.sh index 356b630..7aacb67 100755 --- a/packages/mosaic/framework/tools/fleet/start-agent-session.sh +++ b/packages/mosaic/framework/tools/fleet/start-agent-session.sh @@ -90,11 +90,18 @@ MOSAIC_RUNTIME_BIN_PREFIX=$(_build_runtime_bin_prefix) # # We build the snippet as a double-quoted here-string embedded in a printf call # to avoid nested quoting problems. +# +# MOSAIC_AGENT_NAME must also be exported INTO the pane: panes inherit the tmux +# server environment (not this script's, and not the systemd unit's), so the +# name would otherwise be empty in-pane and the runtime's native heartbeat +# (which gates on MOSAIC_AGENT_NAME) would never fire. %q-quote it so it is a +# safe single bash token regardless of the name's characters. +AGENT_NAME_Q=$(printf '%q' "$AGENT_NAME") if [ -n "$MOSAIC_RUNTIME_BIN_PREFIX" ]; then - PANE_SHELL_SNIPPET="export PATH=\"${MOSAIC_RUNTIME_BIN_PREFIX}:\${PATH}\"; exec ${MOSAIC_AGENT_COMMAND}" + PANE_SHELL_SNIPPET="export MOSAIC_AGENT_NAME=${AGENT_NAME_Q}; export PATH=\"${MOSAIC_RUNTIME_BIN_PREFIX}:\${PATH}\"; exec ${MOSAIC_AGENT_COMMAND}" else - PANE_SHELL_SNIPPET="exec ${MOSAIC_AGENT_COMMAND}" + PANE_SHELL_SNIPPET="export MOSAIC_AGENT_NAME=${AGENT_NAME_Q}; exec ${MOSAIC_AGENT_COMMAND}" fi mkdir -p "$MOSAIC_AGENT_WORKDIR" @@ -129,7 +136,7 @@ _start_heartbeat_sidecar() { # references to any variables from this script's environment. local sidecar_script sidecar_script=$(printf \ - 'hb=%q; pid=%q; iv=%q; mkdir -p "$(dirname "$hb")"; while kill -0 "$pid" 2>/dev/null; do tmp="$hb.tmp.$$"; printf "ts=%%s\npid=%%s\nstatus=ok\n" "$(date +%%Y-%%m-%%dT%%H:%%M:%%S%%z)" "$pid" > "$tmp" && mv "$tmp" "$hb"; sleep "$iv"; done' \ + 'hb=%q; pid=%q; iv=%q; mkdir -p "$(dirname "$hb")"; while kill -0 "$pid" 2>/dev/null; do nat="$hb.native"; if [ -f "$nat" ] && [ "$(( $(date +%%s) - $(stat -c %%Y "$nat" 2>/dev/null || echo 0) ))" -lt "$(( iv * 2 ))" ]; then sleep "$iv"; continue; fi; tmp="$hb.tmp.$$"; printf "ts=%%s\npid=%%s\nstatus=ok\n" "$(date +%%Y-%%m-%%dT%%H:%%M:%%S%%z)" "$pid" > "$tmp" && mv "$tmp" "$hb"; sleep "$iv"; done' \ "$hb_file" "$pane_pid" "$interval") # setsid + disown ensures the sidecar survives this script exiting. diff --git a/packages/mosaic/src/commands/fleet.spec.ts b/packages/mosaic/src/commands/fleet.spec.ts index 401469d..f0c3262 100644 --- a/packages/mosaic/src/commands/fleet.spec.ts +++ b/packages/mosaic/src/commands/fleet.spec.ts @@ -833,6 +833,17 @@ describe('fleet ps — heartbeat parsing', () => { expect(hb.pid).toBe(12345); expect(hb.status).toBe('ok'); expect(hb.ageMs).toBe(10_000); + // No model= line in a legacy/sidecar heartbeat → model is null. + expect(hb.model).toBeNull(); + }); + + it('parses a self-reported model id from a native heartbeat (model= line)', () => { + const ts = new Date(NOW - 5_000).toISOString(); + const content = `ts=${ts}\npid=42\nstatus=busy\nmodel=openai-codex/gpt-5.5:high\n`; + const hb = parseHeartbeat(content, NOW); + expect(hb.model).toBe('openai-codex/gpt-5.5:high'); + expect(hb.status).toBe('busy'); + expect(hb.health).toBe('healthy'); }); it('reports stale when heartbeat is older than 3×interval', () => { diff --git a/packages/mosaic/src/commands/fleet.ts b/packages/mosaic/src/commands/fleet.ts index 8b1aee1..eb0c462 100644 --- a/packages/mosaic/src/commands/fleet.ts +++ b/packages/mosaic/src/commands/fleet.ts @@ -390,6 +390,8 @@ export interface HeartbeatInfo { /** healthy | stale | unknown */ health: 'healthy' | 'stale' | 'unknown'; ageMs: number | null; + /** Model id the runtime self-reported in its heartbeat (native HB only), else null. */ + model: string | null; } export interface AgentPsRow { @@ -490,15 +492,17 @@ export function heartbeatPath(agentName: string, mosaicHome = defaultMosaicHome( * ts= * pid= * status= + * model= (optional — native runtime heartbeats self-report it) */ export function parseHeartbeat(content: string | null, nowMs = Date.now()): HeartbeatInfo { if (content === null) { - return { ts: null, pid: null, status: null, health: 'unknown', ageMs: null }; + return { ts: null, pid: null, status: null, health: 'unknown', ageMs: null, model: null }; } const lines = content.split('\n'); let ts: Date | null = null; let pid: number | null = null; let status: 'ok' | 'busy' | null = null; + let model: string | null = null; for (const line of lines) { const [key, ...rest] = line.split('='); const val = rest.join('=').trim(); @@ -510,6 +514,8 @@ export function parseHeartbeat(content: string | null, nowMs = Date.now()): Hear if (Number.isFinite(n)) pid = n; } else if (key === 'status' && (val === 'ok' || val === 'busy')) { status = val; + } else if (key === 'model' && val) { + model = val; } } const thresholdMs = heartbeatIntervalMs() * HEARTBEAT_HEALTHY_MULTIPLIER; @@ -519,7 +525,7 @@ export function parseHeartbeat(content: string | null, nowMs = Date.now()): Hear ageMs = nowMs - ts.getTime(); health = ageMs <= thresholdMs ? 'healthy' : 'stale'; } - return { ts, pid, status, health, ageMs }; + return { ts, pid, status, health, ageMs, model }; } /** @@ -1123,6 +1129,7 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps = 'PID'.padEnd(8), 'IDLE'.padEnd(8), 'HB'.padEnd(12), + 'MODEL'.padEnd(22), 'FLAGS', ].join(' '); console.log(header); @@ -1137,6 +1144,7 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps = row.heartbeat.ageMs !== null ? `${Math.round(row.heartbeat.ageMs / 1000)}s/${row.heartbeat.health}` : `unknown`; + const model = row.heartbeat.model ?? '-'; const flags: string[] = []; if (!row.managed) flags.push('UNMANAGED'); if (row.driftFlag) flags.push('DRIFT'); @@ -1153,6 +1161,7 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps = pid.padEnd(8), idle.padEnd(8), hbAge.padEnd(12), + model.padEnd(22), flags.join(','), ].join(' '), );