@matthewfl/pi-contemplator 0.0.4 → 0.0.5

package/README.md

@@ -1,8 +1,11 @@
 # pi-contemplator
 
-`pi-contemplator` is a [Pi](https://pi.dev/) plugin designed to help long-running, unsupervised agentic sessions stay on track.
+`pi-contemplator` is a [Pi](https://pi.dev/) plugin for long-running, largely unsupervised agentic sessions. It does two things:
 
-It adds a background **contemplator** agent that examines accumulated session memories for logical fallacies, unsupported assumptions, contradictions, and incorrect conclusions. When it finds a meaningful reasoning problem, it can interject with a focused question that helps the primary agent reconsider its reasoning before a mistaken premise poisons the rest of the session.
+1. **Keeps memory alive across compaction.** A background **observer**, **reflector**, and **dropper** distill the conversation into a durable, branch-local memory ledger. When Pi compacts the context window, the summary is rendered deterministically from that ledger — fast, model-free, and lossless enough that important facts survive.
+2. **Gives the primary agent a second set of eyes.** A background **contemplator** reads the accumulated memories and watches for reasoning that is going wrong. When it finds a genuine problem, it can inject a focused, memory-cited question. For deeper, recurring structural issues, it can commission a short-lived **reviewer** that produces a durable, advisory design proposal.
+
+The result: a long session is less likely to drift off course, get stuck in an unproductive loop, or silently compound a wrong conclusion — and when it does, it can often catch itself before the mistake poisons the rest of the work.
 
 > [!WARNING]
 > **Alpha-quality software:** `pi-contemplator` is under active development. Expect bugs, behavioral changes, and breaking configuration or memory-format changes.
@@ -15,7 +18,11 @@ It adds a background **contemplator** agent that examines accumulated session me
 
 ## Why use it?
 
-A long-running agent can draw the wrong conclusion from valid evidence and then repeatedly reinforce that conclusion. As the mistake accumulates in context, the agent becomes less likely to question it and less able to discover the real problem.
+A long-running agent faces three compounding risks:
+
+- **Compaction amnesia.** Pi compacts older messages to fit the context window. Details that weren't captured deliberately are simply gone.
+- **Reasoning entrenchment.** An agent can draw the wrong conclusion from valid evidence and then repeatedly reinforce it. As the mistake accumulates in context, the agent becomes *less* likely to question it and *less* able to discover the real problem.
+- **Unproductive loops.** The agent keeps bumping into the same obstacle through slightly different approaches, burning tokens without gaining information.
 
 Without a contemplator, a session can look like this:
 
@@ -66,17 +73,86 @@ A or C is true
 
 The contemplator does not take over the primary agent's work. It provides occasional, evidence-grounded challenges when reconsidering the current reasoning is more valuable than allowing the session to continue along the same path.
 
+## What it does for you
+
+### It catches reasoning problems before they settle
+
+The contemplator is a "System 2" thinker: slower and more deliberative, focused on the larger shape of the problem while the primary agent does the hands-on work. It watches the memory ledger (not the live transcript) and looks for:
+
+- unsupported assumptions — a conclusion that depends on something never established;
+- contradictions — a recent claim that conflicts with earlier recorded evidence;
+- drift from the user's intent, priorities, or constraints;
+- overlooked alternatives — treating one explanation as settled when others are still plausible;
+- unproductive loops — several memories showing the agent returning to the same obstacle;
+- connections — relevant facts from separate memories that the primary agent never joined up.
+
+When it finds something worth challenging, it sends a concise, memory-cited question as an asynchronous probe. Probes appear as purple cards in the chat and are delivered to the agent's next turn — they never interrupt mid-work or force a new turn:
+
+```text
+◆ CONTEMPLATOR PROBE
+
+You concluded that fix Y resolved the failure, citing memory [a1b2c3d4e5f6].
+Earlier, memory [d4e5f6a1b2c3] recorded that A, B, and C were also
+possible explanations. What observation would distinguish Y from A, B, and C
+before you build on that conclusion?
+```
+
+### It commissions deeper structural reviews
+
+Some patterns are bigger than one question. When several memories point at a *recurring* structural problem, the contemplator can request a review instead of a probe. The reviewer is a separate, short-lived, strictly-scoped agent that independently investigates the concern and, if the evidence supports it, records a durable conceptual proposal.
+
+Two scopes are handled separately:
+
+- **Workflow** — problems in *how* the work is performed: repeatedly reconstructing the same information, reasoning at length about something that could just be observed or computed, failing to preserve a reusable result, weak feedback loops.
+- **Software** — problems in *the software being produced*: repeated special cases, several fixes touching the same missing invariant, duplicated concepts, unclear responsibility boundaries, local workarounds that hint at a missing abstraction.
+
+The reviewer isn't just fed the concern and asked to design a fix. It independently searches the memory ledger *and* the primary agent's recorded chat history (including regex search over the transcript), looks for supporting and contrary evidence, and reaches exactly one terminal outcome: either a durable proposal with a memory id, or a conclusion that no proposal is currently justified. The primary agent receives only a compact notice pointing at the proposal:
+
+```text
+◆ CONTEMPLATOR REVIEW
+
+BACKGROUND WORKFLOW REVIEW PROPOSAL [f7a8b9c0d1e2]
+
+Several memories ([1111], [2222], [3333]) show the same multi-step lookup being
+rebuilt from scratch each time. The proposal suggests a reusable, indexable
+trace that would make the relationship reproducible in seconds instead of minutes.
+
+Recall memory [f7a8b9c0d1e2] to read the full conceptual proposal when it is
+relevant. This is advisory.
+```
+
+Proposals are deliberately conceptual — the reviewer cannot write code, specify exact APIs, name files, or hand over an implementation plan. The primary agent remains the only agent grounded in the actual codebase and environment, and it decides whether, when, and how to use a proposal.
+
+### It keeps memory useful and accountable
+
+The memory system is built to be trustworthy:
+
+- **Every memory has provenance.** Observations cite the exact source entries that support them; reflections cite the observations they're based on. Everything gets a deterministic 12-character id computed in code, not guessed by a model.
+- **Nothing important is silently lost.** The `recall` tool recovers the exact source evidence behind any memory id. The `search_memories` tool finds candidate memories by topic. Even observations the dropper later prunes remain recallable from ledger history.
+- **Compaction is deterministic and model-free.** The summary the agent sees is folded from the ledger by code, not rewritten by a model. That makes compaction fast and cheap, and it means the same session state always produces the same summary.
+
+## Why you can trust it in the background
+
+Running extra agents in the background can be worrying — what if they take over, spam the user, or go off the rails? `pi-contemplator` is explicitly designed against that:
+
+- **Advisory only.** The contemplator and reviewer never modify the primary agent's work, never implement anything, and never inject instructions into the user's session. They produce questions and proposals; the primary agent decides what to do.
+- **One intervention per update.** The contemplator can send at most one probe *or* one review request per turn — never a barrage. Most turns it sends nothing at all.
+- **Grounded in evidence, not noise.** Loops must be supported by a clear pattern across *multiple* memories. The contemplator is explicitly forbidden from inferring a stall from silence, elapsed time, or a missing recent result. It may consult activity signals (cumulative tokens, tool-call count, active time) as *advisory* context, but never as proof.
+- **Sees memory, not secrets.** The contemplator reads only the memory ledger, not the live transcript, so it can't react to or interfere with in-flight work.
+- **Epistemic humility.** The contemplator is instructed not to behave as though it already knows the answer, not to praise or criticize, and not to manage the primary agent step by step. It asks questions that help *both* agents discover what's missing.
+- **Bounded and de-duplicated.** Reviews are serialized (one at a time), coalesced (no duplicate review for the same evidence and concern), and capped by a lifetime output-token budget — a review that runs out of budget records an honest "no proposal" rather than a half-baked design.
+
 ## Background agents
 
-`pi-contemplator` uses five specialized background agents:
+`pi-contemplator` uses five specialized background agents, all enabled by default:
 
-| Agent | Purpose | Compared with `pi-observational-memory` |
+| Agent | What it does | When it runs |
 |---|---|---|
-| **Observer** | Extracts concrete, durable observations from the primary session. | Same as `pi-observational-memory` |
-| **Reflector** | Finds higher-level patterns and relationships across observations. | Same as `pi-observational-memory` |
-| **Dropper** | Removes observations that are obsolete, redundant, or safely represented elsewhere. | Same as `pi-observational-memory` |
-| **Contemplator** | Watches accumulated memories for reasoning gaps, contradictions, overlooked alternatives, and recurring structural concerns; it can send a focused probe to the primary agent. | Added by `pi-contemplator` |
-| **Reviewer** | Performs a deeper, scoped workflow or software-design investigation when the contemplator identifies a well-supported recurring structural issue. | Added by `pi-contemplator` |
+| **Observer** | Extracts concrete, timestamped observations from the primary session, citing source entries. | In the background after turns, once enough new source text accumulates. |
+| **Reflector** | Distills durable conclusions (user intent, decisions, constraints) from observations, citing supporting observations. | Periodically, after the observer is up to date. |
+| **Dropper** | Prunes observations that are obsolete, redundant, or safely represented elsewhere, keeping the active memory pool bounded. | Only after a successful reflection, when the memory pool is over target. |
+| **Contemplator** | Watches accumulated memories for reasoning gaps, contradictions, overlooked alternatives, and recurring structural concerns; can send a focused probe or request a review. | Asynchronously after enough new memories accumulate. |
+| **Reviewer** | Performs a deep, scoped (workflow or software) structural investigation and records a durable proposal or a no-proposal conclusion. | Only when the contemplator commissions a review, and only one at a time. |
 
 The observer, reflector, and dropper provide the durable memory substrate. The contemplator reasons over that substrate, while the reviewer is launched only when a concern warrants a deeper structural investigation.
 
@@ -94,18 +170,20 @@ Or run it directly from a local checkout:
 pi -e ./src/index.ts
 ```
 
-## Configuration and commands
+## Commands and configuration
 
-The plugin works with its defaults, including the contemplator and reviewer. Contemplator probes and review notices appear as purple cards in the chat by default; use `/om:settings messages off` to hide newly sent cards without stopping their delivery to the agent. Model selection, trigger thresholds, passive mode, compaction behavior, and other settings are documented in [docs/configuration.md](docs/configuration.md).
+The plugin works with its defaults, including the contemplator and reviewer. Contemplator probes and review notices appear as purple cards in the chat by default; use `/om:settings messages off` to hide newly sent cards without stopping their delivery to the agent.
 
-Useful commands include:
+Useful commands:
 
-- `/om:status` — show memory and background-agent status.
-- `/om:view contemplator` — inspect the contemplator's persisted private transcript.
+- `/om:status` — show memory and background-agent status, including how much recorded memory is still visible vs. pending.
+- `/om:view` — inspect visible memory (and attempt to copy it).
+- `/om:view full` — inspect the full memory ledger, including everything not yet folded into a compaction.
+- `/om:view contemplator` — inspect the contemplator's private transcript and probes.
 - `/om:view reviewer` — inspect structural reviewer transcripts and outcomes.
-- `/om:settings` — inspect or change session-level settings.
+- `/om:settings` — inspect or change session-level settings (including `messages on|off`, `reviewer on|off`, `compaction on|off`).
 
-See [docs/how-it-works.md](docs/how-it-works.md) for the memory lifecycle and detailed behavior.
+Model selection, trigger thresholds, passive mode (which stops all background work), compaction behavior, and other tuning are documented in [docs/configuration.md](docs/configuration.md). See [docs/how-it-works.md](docs/how-it-works.md) for the memory lifecycle and [docs/concepts.md](docs/concepts.md) for the mental model.
 
 ## Development
 
@@ -117,4 +195,4 @@ npm run typecheck
 
 ## License
 
-MIT. See [LICENSE](LICENSE).
+MIT. See [LICENSE](LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matthewfl/pi-contemplator",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "A Pi extension that keeps long-running agentic sessions on track with background memory, contemplation, and structural review.",
   "type": "module",
   "license": "MIT",

package/src/agents/contemplator/agent.ts

@@ -5,7 +5,7 @@ import { streamSimple } from "@earendil-works/pi-ai/compat";
 import { generateSummaryWithUsage } from "@earendil-works/pi-coding-agent";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Box, Text } from "@earendil-works/pi-tui";
-import { assistantOutputTokens, assistantToolCallCount, fullProjection, isReviewRequestEntry, isReviewResultEntry, OM_REVIEWER_MESSAGE, OM_REVIEWER_NOTICE, OM_REVIEWER_STATE, OM_REVIEW_REQUEST, OM_REVIEW_RESULT, type Entry, type ReviewResult, type StructuralReviewRequest } from "../../session-ledger/index.js";
+import { agentActiveTimeMs, assistantOutputTokens, assistantToolCallCount, fullProjection, isReviewRequestEntry, isReviewResultEntry, OM_AGENT_ACTIVITY, OM_REVIEWER_MESSAGE, OM_REVIEWER_NOTICE, OM_REVIEWER_STATE, OM_REVIEW_REQUEST, OM_REVIEW_RESULT, type Entry, type ReviewResult, type StructuralReviewRequest } from "../../session-ledger/index.js";
 import { hashId } from "../../ids.js";
 import { createSearchMemoriesAgentTool } from "../../tools/search-memories.js";
 import { createRecallAgentTool } from "../../tools/recall-observation.js";
@@ -22,6 +22,7 @@ interface PendingUpdate {
 	reviews: string[];
 	mainAgentOutputTokens: number;
 	mainAgentToolCalls: number;
+	mainAgentActiveTimeMs: number;
 }
 
 type Intervention =
@@ -90,6 +91,19 @@ function customMessageText(content: unknown): string {
 		.filter(Boolean)
 		.join("\n");
 }
+
+const AGENT_TIME_BUCKET_MINUTES = 5;
+
+function coarseAgentTime(durationMs: number): string {
+	const totalMinutes = Math.floor(durationMs / 60_000);
+	const bucketMinutes = Math.floor(totalMinutes / AGENT_TIME_BUCKET_MINUTES) * AGENT_TIME_BUCKET_MINUTES;
+	if (bucketMinutes < AGENT_TIME_BUCKET_MINUTES) return `less than ${AGENT_TIME_BUCKET_MINUTES} minutes`;
+	const hours = Math.floor(bucketMinutes / 60);
+	const minutes = bucketMinutes % 60;
+	if (hours === 0) return `about ${minutes} minutes`;
+	const hourLabel = `${hours} hour${hours === 1 ? "" : "s"}`;
+	return minutes === 0 ? `about ${hourLabel}` : `about ${hourLabel} ${minutes} minutes`;
+}
 const CONTEMPLATOR_MESSAGE = "om.contemplator.message";
 const CONTEMPLATOR_STATE = "om.contemplator.state";
 const CONTEMPLATOR_SUGGESTION = "om.contemplator.suggestion";
@@ -160,6 +174,8 @@ export class Contemplator {
 	private latestCtx: MemoryUpdateCtx | undefined;
 	private turnsSinceRun = 0;
 	private restoredTipId: string | undefined;
+	/** Start of the unpersisted portion of the current main-agent run. */
+	private agentActiveSince: number | undefined;
 
 	constructor(private readonly pi: ExtensionAPI, private readonly runtime: Runtime) {}
 
@@ -176,8 +192,16 @@ export class Contemplator {
 			return box;
 		});
 		this.runtime.setMemoryUpdateListener((ctx) => this.withDebugContext(ctx, () => this.observeTurn(ctx)));
+		this.pi.on("agent_start", () => {
+			this.agentActiveSince = Date.now();
+		});
+		this.pi.on("agent_end", (_event: unknown, ctx: ExtensionContext) => {
+			this.persistAgentActivity(ctx);
+			this.agentActiveSince = undefined;
+		});
 		this.pi.on("session_start", (event: any, ctx: ExtensionContext) => {
 			this.sessionGeneration++;
+			this.agentActiveSince = undefined;
 			// AgentSession preserves its steering queue across extension reloads. An
 			// undelivered tracking entry therefore still has a live queued message;
 			// restoring it here would enqueue the same probe a second time.
@@ -186,11 +210,13 @@ export class Contemplator {
 		});
 		this.pi.on("session_tree", (_event: any, ctx: ExtensionContext) => {
 			this.sessionGeneration++;
+			this.agentActiveSince = undefined;
 			// Pending steering messages remain queued while navigating the tree.
 			this.restore(ctx, true, true);
 		});
 		this.pi.on("session_shutdown", () => {
 			this.sessionGeneration++;
+			this.agentActiveSince = undefined;
 			this.history = [];
 			this.pending = undefined;
 			this.seenObservationIds.clear();
@@ -234,11 +260,23 @@ export class Contemplator {
 			}
 		});
 		this.pi.on("turn_end", (_event: any, ctx: ExtensionContext) => {
+			this.persistAgentActivity(ctx);
 			this.turnsSinceRun++;
 			this.withDebugContext(ctx, () => this.observeTurn(ctx));
 		});
 	}
 
+	private persistAgentActivity(ctx: MemoryUpdateCtx): void {
+		const startedAt = this.agentActiveSince;
+		if (startedAt === undefined) return;
+		const endedAt = Date.now();
+		this.agentActiveSince = endedAt;
+		const durationMs = Math.max(0, endedAt - startedAt);
+		if (durationMs === 0) return;
+		this.pi.appendEntry(OM_AGENT_ACTIVITY, { version: 1, durationMs, endedAt });
+		debugLog("agent.activity_recorded", { durationMs });
+	}
+
 	private withDebugContext<T>(ctx: MemoryUpdateCtx, fn: () => T): T {
 		this.runtime.ensureConfig(ctx.cwd);
 		const sessionManager = ctx.sessionManager as { getSessionId?: () => string; getSessionFile?: () => string };
@@ -359,7 +397,8 @@ export class Contemplator {
 			debugLog("contemplator.skipped", { reason: "passive" });
 			return;
 		}
-		const projection = fullProjection(ctx.sessionManager.getBranch() as Entry[]);
+		const branchEntries = ctx.sessionManager.getBranch() as Entry[];
+		const projection = fullProjection(branchEntries);
 		const observations = projection.observations.map((item) => `[${item.id}] ${item.content}`);
 		const reflections = projection.reflections.map((item) => `[${item.id}] ${item.content}`);
 		const reviews = projection.reviews ?? [];
@@ -387,11 +426,18 @@ export class Contemplator {
 				observations: mergeMemoryLines(this.pending?.observations ?? [], newObservations),
 				reflections: mergeMemoryLines(this.pending?.reflections ?? [], newReflections),
 				reviews: mergeMemoryLines(this.pending?.reviews ?? [], newReviews),
-				mainAgentOutputTokens: assistantOutputTokens(ctx.sessionManager.getBranch() as Entry[]),
-				mainAgentToolCalls: assistantToolCallCount(ctx.sessionManager.getBranch() as Entry[]),
+				mainAgentOutputTokens: assistantOutputTokens(branchEntries),
+				mainAgentToolCalls: assistantToolCallCount(branchEntries),
+				mainAgentActiveTimeMs: agentActiveTimeMs(branchEntries),
 			};
 		}
 		if (!this.pending) return;
+		// Activity values are cumulative send-time snapshots, not values frozen when
+		// the first memory entered a pending batch. This includes work performed
+		// while that batch waits for its memory/turn thresholds.
+		this.pending.mainAgentOutputTokens = assistantOutputTokens(branchEntries);
+		this.pending.mainAgentToolCalls = assistantToolCallCount(branchEntries);
+		this.pending.mainAgentActiveTimeMs = agentActiveTimeMs(branchEntries);
 		const enoughMemories = this.pending.reviews.length > 0 || this.pending.observations.length >= this.runtime.config.contemplatorMinNewObservations || this.pending.reflections.length >= this.runtime.config.contemplatorMinNewReflections;
 		if (!enoughMemories || this.turnsSinceRun < this.runtime.config.contemplatorMinTurns) {
 			debugLog("contemplator.waiting", {
@@ -452,6 +498,7 @@ export class Contemplator {
 						reviews: mergeMemoryLines(pending?.reviews ?? [], update.reviews),
 						mainAgentOutputTokens: update.mainAgentOutputTokens,
 						mainAgentToolCalls: update.mainAgentToolCalls,
+						mainAgentActiveTimeMs: update.mainAgentActiveTimeMs,
 					};
 					this.turnsSinceRun = turnsBeforeRun;
 				}
@@ -476,7 +523,7 @@ export class Contemplator {
 			const interventionInstruction = reviewerEnabled
 				? "Use send_probe for one focused question, or request_review only when a deeper workflow or software review is justified. Use no more than one intervention."
 				: "Use send_probe only when one focused question is materially useful. Use no more than one intervention.";
-			const prompt: Message = { role: "user", content: [{ type: "text", text: `NEW MEMORY UPDATE\n\n${updateBody}\n\nACTIVITY SIGNAL cumulative primary-agent generated tokens: ${update.mainAgentOutputTokens}; cumulative primary-agent tool calls: ${update.mainAgentToolCalls}\n\nConsider these updates in the context of the accumulated memories. Prioritize reasoning gaps, contradictions, user-intent alignment, relevant overlooked alternatives, well-supported loops, and recurring structural patterns. ${interventionInstruction}` }], timestamp: Date.now() };
+			const prompt: Message = { role: "user", content: [{ type: "text", text: `NEW MEMORY UPDATE\n\n${updateBody}\n\nCUMULATIVE ACTIVITY: ${update.mainAgentOutputTokens} generated tokens; ${update.mainAgentToolCalls} tool calls; ${coarseAgentTime(update.mainAgentActiveTimeMs)} active.\n\nConsider these updates in the context of the accumulated memories. Prioritize reasoning gaps, contradictions, user-intent alignment, relevant overlooked alternatives, well-supported loops, and recurring structural patterns. ${interventionInstruction}` }], timestamp: Date.now() };
 			promptMessage = prompt;
 			this.history.push(prompt);
 			let intervention: Intervention | undefined;
@@ -578,6 +625,7 @@ export class Contemplator {
 					reviews: mergeMemoryLines(pending?.reviews ?? [], update.reviews),
 					mainAgentOutputTokens: update.mainAgentOutputTokens,
 					mainAgentToolCalls: update.mainAgentToolCalls,
+					mainAgentActiveTimeMs: update.mainAgentActiveTimeMs,
 				};
 				this.turnsSinceRun = turnsBeforeRun;
 			}

package/src/commands/status.ts

@@ -3,6 +3,7 @@ import { observationPoolMetrics } from "../agents/dropper/pool.js";
 import { resolveCompactAfterTokens } from "../config.js";
 import type { Runtime } from "../runtime.js";
 import {
+	agentActiveTimeMs,
 	diffProjection,
 	foldLedger,
 	fullProjection,
@@ -26,6 +27,16 @@ function formatTokens(n: number): string {
 	return String(n);
 }
 
+function formatDuration(durationMs: number): string {
+	const totalSeconds = Math.floor(durationMs / 1_000);
+	const hours = Math.floor(totalSeconds / 3_600);
+	const minutes = Math.floor((totalSeconds % 3_600) / 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`;
+}
+
 function truncateStatusText(value: string, limit = 1_000): string {
 	return value.length <= limit ? value : `${value.slice(0, limit - 1)}…`;
 }
@@ -99,6 +110,7 @@ export function registerStatusCommand(pi: ExtensionAPI, runtime: Runtime): void
 				`Visible observation pool: ~${visibleObservationTokens.toLocaleString()} / ${runtime.config.observationsPoolMaxTokens.toLocaleString()} tokens (${pct(visibleObservationTokens, runtime.config.observationsPoolMaxTokens)}%)`,
 				`Active observation pool: ~${activeObservationPool.observationTokens.toLocaleString()} / ${runtime.config.observationsPoolTargetTokens.toLocaleString()} target tokens (${pct(activeObservationPool.observationTokens, runtime.config.observationsPoolTargetTokens)}%)`,
 				`Reflection pool:         ~${visibleReflectionTokens.toLocaleString()} tokens`,
+				`Cumulative agent time:   ${formatDuration(agentActiveTimeMs(entries))}`,
 				`Compaction observer:     ${runtime.config.compactionObserverEnabled === false ? "disabled" : "enabled"}`,
 				`Contemplator:             ${runtime.config.contemplatorEnabled ? "enabled" : "disabled"}`,
 				`Contemplator model:      ${runtime.config.contemplatorModel ? `${runtime.config.contemplatorModel.provider}/${runtime.config.contemplatorModel.id}` : "current session model"}`,

package/src/session-ledger/progress.ts

@@ -1,5 +1,6 @@
 import { estimateEntryTokens } from "../tokens.js";
 import {
+	OM_AGENT_ACTIVITY,
 	OM_OBSERVATIONS_DROPPED,
 	OM_OBSERVATIONS_RECORDED,
 	OM_REFLECTIONS_RECORDED,
@@ -52,6 +53,17 @@ export function assistantToolCallCount(entries: Entry[]): number {
 	return total;
 }
 
+/** Sum persisted main-agent active wall-clock time on the current branch. */
+export function agentActiveTimeMs(entries: Entry[]): number {
+	let total = 0;
+	for (const entry of entries) {
+		if (entry.type !== "custom" || entry.customType !== OM_AGENT_ACTIVITY || !isObject(entry.data)) continue;
+		const durationMs = entry.data.durationMs;
+		if (typeof durationMs === "number" && Number.isFinite(durationMs) && durationMs >= 0) total += durationMs;
+	}
+	return total;
+}
+
 function isObject(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null;
 }

package/src/session-ledger/types.ts

@@ -9,6 +9,8 @@ export const OM_REVIEWER_MESSAGE = "om.reviewer.message";
 export const OM_REVIEWER_STATE = "om.reviewer.state";
 /** Compact proposal notice queued for the primary agent. */
 export const OM_REVIEWER_NOTICE = "om.reviewer.notice";
+/** Main-agent active wall-clock time, excluding idle waits for user input. */
+export const OM_AGENT_ACTIVITY = "om.agent.activity";
 export const OM_FOLDED = "om.folded";
 
 export const RELEVANCE_VALUES = ["low", "medium", "high", "critical"] as const;