feat: expose durable material-progress inspection

packages/cli/src/commands/agent/inspect.test.ts

@@ -0,0 +1,46 @@
+import type { AgentSnapshotPayload } from "@getpaseo/protocol/messages";
+import { describe, expect, it } from "vitest";
+import { toInspectData, toInspectRows } from "./inspect.js";
+
+describe("agent inspect material progress", () => {
+  it("preserves the structured signal and renders its state and reason", () => {
+    const snapshot = {
+      id: "agent-1",
+      provider: "opencode",
+      cwd: "/tmp/work",
+      model: "test-model",
+      createdAt: "2026-07-31T00:00:00.000Z",
+      updatedAt: "2026-07-31T00:01:00.000Z",
+      lastUserMessageAt: "2026-07-31T00:00:30.000Z",
+      status: "running",
+      capabilities: {
+        supportsStreaming: true,
+        supportsSessionPersistence: true,
+        supportsDynamicModes: false,
+        supportsMcpServers: true,
+        supportsReasoningStream: true,
+        supportsToolInvocations: true,
+      },
+      currentModeId: null,
+      availableModes: [],
+      pendingPermissions: [],
+      persistence: null,
+      title: "Stalled worker",
+      labels: {},
+      materialProgress: {
+        state: "stalled",
+        completedCompactionsSinceMaterialProgress: 2,
+        lastMaterialProgressAt: null,
+        lastMaterialProgressKind: null,
+        reason: "Two compactions completed without later material progress.",
+      },
+    } as AgentSnapshotPayload;
+
+    const inspect = toInspectData(snapshot);
+    expect(inspect.MaterialProgress).toEqual(snapshot.materialProgress);
+    expect(toInspectRows(inspect)).toContainEqual({
+      key: "MaterialProgress",
+      value: "stalled: Two compactions completed without later material progress.",
+    });
+  });
+});

packages/cli/src/commands/agent/inspect.ts

@@ -11,7 +11,7 @@ export function addInspectOptions(cmd: Command): Command {
 }
 
 /** Agent inspect data for display (matches CLI spec format) */
-interface AgentInspect {
+export interface AgentInspect {
   Id: string;
   Name: string;
   Provider: string;
@@ -46,10 +46,11 @@ interface AgentInspect {
   }>;
   Worktree: string | null;
   ParentAgentId: string | null;
+  MaterialProgress: AgentSnapshotPayload["materialProgress"] | null;
 }
 
 /** Key-value row for table display */
-interface InspectRow {
+export interface InspectRow {
   key: string;
   value: string;
 }
@@ -126,7 +127,7 @@ function buildCapabilities(snapshot: AgentSnapshotPayload): AgentInspect["Capabi
 }
 
 /** Convert agent snapshot to inspection data */
-function toInspectData(snapshot: AgentSnapshotPayload): AgentInspect {
+export function toInspectData(snapshot: AgentSnapshotPayload): AgentInspect {
   return {
     Id: snapshot.id,
     Name: snapshot.title ?? "-",
@@ -151,11 +152,12 @@ function toInspectData(snapshot: AgentSnapshotPayload): AgentInspect {
     })),
     Worktree: snapshot.labels?.["paseo.worktree"] ?? null,
     ParentAgentId: snapshot.labels?.[PARENT_AGENT_ID_LABEL] ?? null,
+    MaterialProgress: snapshot.materialProgress ?? null,
   };
 }
 
 /** Convert agent to key-value rows for table display */
-function toInspectRows(agent: AgentInspect): InspectRow[] {
+export function toInspectRows(agent: AgentInspect): InspectRow[] {
   const rows: InspectRow[] = [
     { key: "Id", value: agent.Id },
     { key: "Name", value: agent.Name },
@@ -202,6 +204,12 @@ function toInspectRows(agent: AgentInspect): InspectRow[] {
 
   rows.push({ key: "Worktree", value: agent.Worktree ?? "null" });
   rows.push({ key: "ParentAgentId", value: agent.ParentAgentId ?? "null" });
+  rows.push({
+    key: "MaterialProgress",
+    value: agent.MaterialProgress
+      ? `${agent.MaterialProgress.state}: ${agent.MaterialProgress.reason}`
+      : "unavailable",
+  });
 
   return rows;
 }

packages/protocol/src/material-progress-schema.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from "vitest";
+import { AgentSnapshotPayloadSchema } from "./messages.js";
+
+const baseSnapshot = {
+  id: "agent-1",
+  provider: "opencode",
+  cwd: "/tmp/work",
+  model: null,
+  createdAt: "2026-07-31T00:00:00.000Z",
+  updatedAt: "2026-07-31T00:00:00.000Z",
+  lastUserMessageAt: null,
+  status: "running" as const,
+  capabilities: {
+    supportsStreaming: true,
+    supportsSessionPersistence: true,
+    supportsDynamicModes: false,
+    supportsMcpServers: true,
+    supportsReasoningStream: true,
+    supportsToolInvocations: true,
+  },
+  currentModeId: null,
+  availableModes: [],
+  pendingPermissions: [],
+  persistence: null,
+  title: null,
+  labels: {},
+};
+
+describe("material progress wire compatibility", () => {
+  it("accepts legacy snapshots without the optional signal", () => {
+    expect(AgentSnapshotPayloadSchema.parse(baseSnapshot).materialProgress).toBeUndefined();
+  });
+
+  it("accepts a structured material progress signal", () => {
+    const parsed = AgentSnapshotPayloadSchema.parse({
+      ...baseSnapshot,
+      materialProgress: {
+        state: "warning",
+        completedCompactionsSinceMaterialProgress: 1,
+        lastMaterialProgressAt: null,
+        lastMaterialProgressKind: null,
+        reason: "One compaction completed without later material progress.",
+      },
+    });
+
+    expect(parsed.materialProgress?.state).toBe("warning");
+  });
+
+  it.each(["evidence", "verification", "decision"] as const)(
+    "accepts the %s material progress kind",
+    (lastMaterialProgressKind) => {
+      const parsed = AgentSnapshotPayloadSchema.parse({
+        ...baseSnapshot,
+        materialProgress: {
+          state: "progressing",
+          completedCompactionsSinceMaterialProgress: 0,
+          lastMaterialProgressAt: "2026-07-31T00:00:01.000Z",
+          lastMaterialProgressKind,
+          reason: "Material progress followed the latest user message.",
+        },
+      });
+
+      expect(parsed.materialProgress?.lastMaterialProgressKind).toBe(lastMaterialProgressKind);
+    },
+  );
+});

packages/protocol/src/messages.ts

@@ -693,6 +693,31 @@ const AgentRuntimeInfoSchema: z.ZodType<AgentRuntimeInfo> = z.object({
   extra: z.record(z.string(), z.unknown()).optional(),
 });
 
+export interface MaterialProgressPayload {
+  state: "none" | "progressing" | "warning" | "stalled";
+  completedCompactionsSinceMaterialProgress: number;
+  lastMaterialProgressAt: string | null;
+  lastMaterialProgressKind:
+    | "edit"
+    | "write"
+    | "evidence"
+    | "verification"
+    | "decision"
+    | "assistant_result"
+    | null;
+  reason: string;
+}
+
+export const MaterialProgressPayloadSchema: z.ZodType<MaterialProgressPayload> = z.object({
+  state: z.enum(["none", "progressing", "warning", "stalled"]),
+  completedCompactionsSinceMaterialProgress: z.number().int().nonnegative(),
+  lastMaterialProgressAt: z.string().nullable(),
+  lastMaterialProgressKind: z
+    .enum(["edit", "write", "evidence", "verification", "decision", "assistant_result"])
+    .nullable(),
+  reason: z.string(),
+});
+
 export const AgentSnapshotPayloadSchema = z.object({
   id: z.string(),
   provider: AgentProviderSchema,
@@ -721,6 +746,8 @@ export const AgentSnapshotPayloadSchema = z.object({
   attentionTimestamp: z.string().nullable().optional(),
   archivedAt: z.string().nullable().optional(),
   providerUnavailable: z.boolean().optional(),
+  // COMPAT(materialProgress): added in v0.2.5, remove optional after 2027-01-31.
+  materialProgress: MaterialProgressPayloadSchema.optional(),
 });
 
 export type AgentSnapshotPayload = z.infer<typeof AgentSnapshotPayloadSchema>;