@gajae-code/coding-agent 0.18.7 → 0.18.9

package/src/progress/collect-project-progress.ts

@@ -0,0 +1,153 @@
+import type { SubagentLifecycle } from "../async/job-manager";
+import { readUltragoalPlan } from "../gjc-runtime/ultragoal-runtime";
+import type { Goal, GoalModeState } from "../goals/state";
+import type { SessionManager } from "../session/session-manager";
+import {
+	normalizeWorkflowHudSummary,
+	readVisibleSkillActiveStateWithStatus,
+	type VisibleSkillActiveStateReadStatus,
+} from "../skill-state/active-state";
+import { findLatestTodoPhasesFromEntries, type TodoPhase } from "../tools/todo-write";
+import type { ProgressDurableSource } from "./progress-contract";
+import {
+	computeProjectProgress,
+	type ProgressUltragoalInput,
+	type ProgressWorkflowInput,
+	type ProjectProgressInput,
+	type ProjectProgressReport,
+} from "./project-progress";
+
+/** Session-owned state the overview reads; everything else comes from durable `.gjc` files. */
+export interface ProjectProgressSessionView {
+	cwd: string;
+	/** GJC session id that scopes `.gjc/_session-{id}` state; without it no workflow state is read. */
+	sessionId: string | undefined;
+	goal: Goal | undefined;
+	todoPhases: readonly TodoPhase[];
+	subagents: readonly SubagentLifecycle[];
+}
+
+async function readWorkflows(
+	cwd: string,
+	sessionId: string,
+): Promise<{ status: VisibleSkillActiveStateReadStatus; workflows: ProgressWorkflowInput[] }> {
+	// The tolerant HUD reader maps an unreadable session snapshot to "nothing
+	// active" and lets snapshot-only rows survive; this projection must report
+	// unreadable state as unreadable, and never report a row without authority.
+	const { status, state } = await readVisibleSkillActiveStateWithStatus(cwd, sessionId);
+	const workflows = (state?.active_skills ?? [])
+		.filter(entry => entry.active !== false)
+		.map(entry => {
+			const hud = normalizeWorkflowHudSummary(entry.hud);
+			return {
+				skill: entry.skill,
+				phase: entry.phase?.trim() || "unknown",
+				...(hud?.summary ? { summary: hud.summary } : {}),
+				chips: (hud?.chips ?? []).map(chip => ({
+					label: chip.label,
+					...(chip.value ? { value: chip.value } : {}),
+					...(chip.severity ? { severity: chip.severity } : {}),
+				})),
+			};
+		});
+	return { status, workflows };
+}
+
+async function readUltragoal(cwd: string, sessionId: string): Promise<ProgressUltragoalInput | undefined> {
+	const plan = await readUltragoalPlan(cwd, sessionId);
+	if (!plan || plan.goals.length === 0) return undefined;
+	return {
+		objective: plan.gjcObjective,
+		stories: plan.goals.map(goal => ({
+			id: goal.id,
+			title: goal.title,
+			status: goal.status,
+			hasVerificationReceipt: typeof goal.completionVerification?.receiptId === "string",
+		})),
+	};
+}
+
+/**
+ * Gather progress input strictly by reading state. A source that fails to read
+ * is reported as unreadable and excluded; it never aborts the overview and is
+ * never replaced by a guess. A source rebuilt from authoritative per-entry
+ * records after its snapshot failed to read is reported as recovered; one whose
+ * readable derived snapshot listed stale rows is reported as discarded; one whose
+ * rows could not be attributed to an authority is reported as unresolved.
+ */
+export async function collectProjectProgressInput(view: ProjectProgressSessionView): Promise<ProjectProgressInput> {
+	const unreadable: ProgressDurableSource[] = [];
+	const recovered: ProgressDurableSource[] = [];
+	const discarded: ProgressDurableSource[] = [];
+	const unresolved: ProgressDurableSource[] = [];
+	const sessionId = view.sessionId?.trim() || undefined;
+	let workflows: ProgressWorkflowInput[] = [];
+	let ultragoal: ProgressUltragoalInput | undefined;
+	if (sessionId) {
+		const [workflowResult, ultragoalResult] = await Promise.allSettled([
+			readWorkflows(view.cwd, sessionId),
+			readUltragoal(view.cwd, sessionId),
+		]);
+		if (workflowResult.status === "rejected" || workflowResult.value.status === "failed") {
+			unreadable.push("workflow-state");
+		} else {
+			workflows = workflowResult.value.workflows;
+			if (workflowResult.value.status === "recovered") recovered.push("workflow-state");
+			else if (workflowResult.value.status === "discarded") discarded.push("workflow-state");
+			else if (workflowResult.value.status === "unresolved") unresolved.push("workflow-state");
+		}
+		if (ultragoalResult.status === "fulfilled") ultragoal = ultragoalResult.value;
+		else unreadable.push("ultragoal-plan");
+	}
+	return {
+		...(view.goal
+			? {
+					goal: {
+						objective: view.goal.objective,
+						status: view.goal.status,
+						timeUsedSeconds: view.goal.timeUsedSeconds,
+					},
+				}
+			: {}),
+		todos: view.todoPhases.flatMap(phase =>
+			phase.tasks.map(task => ({ content: task.content, status: task.status })),
+		),
+		workflows,
+		...(ultragoal ? { ultragoal } : {}),
+		subagents: [...view.subagents],
+		sessionStateRead: sessionId !== undefined,
+		unreadable,
+		recovered,
+		discarded,
+		unresolved,
+	};
+}
+
+/** The live session state `/progress` and `session.progress` read; satisfied by `AgentSession`. */
+export interface ProjectProgressSessionSource {
+	getGoalModeState(): GoalModeState | undefined;
+	getTodoPhases(): TodoPhase[];
+	getSubagentLifecycleStatuses(): SubagentLifecycle[];
+}
+
+/**
+ * Single entry point shared by the human view and the machine snapshot.
+ *
+ * Todos come from the persisted branch history, as `/todo` reads them: the live
+ * list drops completed and abandoned items when a session is resumed, so it is
+ * only the fallback when no todo state was ever persisted. A persisted empty
+ * list is authoritative and is not replaced by live state.
+ */
+export async function buildSessionProjectProgress(
+	session: ProjectProgressSessionSource,
+	sessionManager: Pick<SessionManager, "getCwd" | "getSessionId" | "getBranch">,
+): Promise<ProjectProgressReport> {
+	const input = await collectProjectProgressInput({
+		cwd: sessionManager.getCwd(),
+		sessionId: sessionManager.getSessionId(),
+		goal: session.getGoalModeState()?.goal,
+		todoPhases: findLatestTodoPhasesFromEntries(sessionManager.getBranch()) ?? session.getTodoPhases(),
+		subagents: session.getSubagentLifecycleStatuses(),
+	});
+	return computeProjectProgress(input);
+}

package/src/progress/progress-contract.ts

@@ -0,0 +1,172 @@
+/**
+ * Wire contract of the `session.progress` (Q32) snapshot, `gjc.project_progress.v1`.
+ *
+ * This module is a dependency leaf on purpose: the production ACP agent renders
+ * `/progress` from this contract and must not reach the in-process session
+ * graph (enforced by `scripts/verify-gjc-sdk-canonicalization.ts`, which also
+ * follows type-only imports). Status unions are restated here; the projection
+ * in `progress-snapshot.ts` assigns the runtime statuses to them, so a new
+ * runtime status that the contract lacks fails type checking.
+ */
+import { sanitizeDisplayLine } from "@gajae-code/utils";
+
+/** Ultragoal story status (`UltragoalGoalStatus`). */
+export type ProgressStoryStatus =
+	| "pending"
+	| "active"
+	| "complete"
+	| "failed"
+	| "blocked"
+	| "review_blocked"
+	| "superseded";
+/** Session goal status (`GoalStatus`). */
+export type ProgressGoalStatus = "active" | "paused" | "complete" | "dropped";
+/** Todo item status (`TodoStatus`). */
+export type ProgressTodoStatus = "pending" | "in_progress" | "completed" | "abandoned";
+/** Workflow HUD chip severity (`WorkflowHudSeverity`). */
+export type ProgressChipSeverity = "info" | "warning" | "blocked" | "error" | "success";
+
+/** Durable `.gjc` session-state sources that can fail to read. */
+export type ProgressDurableSource = "workflow-state" | "ultragoal-plan";
+
+export type ProgressBasisKind = "ultragoal-stories" | "todos" | "goal-status" | "none";
+
+export type ProgressHeadline =
+	| "complete"
+	| "awaiting-completion"
+	| "blocked"
+	| "in-progress"
+	| "not-started"
+	| "paused"
+	| "dropped"
+	| "no-tracked-work";
+
+export type ProgressSignalKind = "blocker" | "pending" | "note";
+
+export type ProgressSignalSource = "ultragoal" | "workflow" | "subagents" | "todos" | "goal" | "state";
+
+export interface ProgressAgentCounts {
+	total: number;
+	running: number;
+	/** Subagents that are queued or paused. */
+	waiting: number;
+	completed: number;
+	failed: number;
+	cancelled: number;
+}
+
+export interface ProgressReviewVerdict {
+	skill: string;
+	verdict: string;
+}
+
+export const PROJECT_PROGRESS_SNAPSHOT_SCHEMA = "gjc.project_progress.v1";
+
+/** Bounds keep one snapshot well under a single SDK query page. */
+export const PROGRESS_SNAPSHOT_LIMITS = { stories: 100, todos: 100, workflows: 16, attention: 50, text: 300 } as const;
+
+export interface ProgressSnapshotStory {
+	id: string;
+	title: string;
+	status: ProgressStoryStatus;
+	/** A completion-verification (quality-gate) receipt is recorded on the story. */
+	verificationReceipt: boolean;
+}
+
+export interface ProgressSnapshotTodo {
+	content: string;
+	status: ProgressTodoStatus;
+}
+
+export interface ProgressSnapshotWorkflow {
+	skill: string;
+	phase: string;
+	summary: string | null;
+	chips: { label: string; value: string | null; severity: ProgressChipSeverity | null }[];
+}
+
+export interface ProgressSnapshotAttention {
+	kind: ProgressSignalKind;
+	source: ProgressSignalSource;
+	ref: string | null;
+	text: string;
+}
+
+export interface ProjectProgressSnapshot {
+	schema: typeof PROJECT_PROGRESS_SNAPSHOT_SCHEMA;
+	/** Overall completion state; identical to the `/progress` headline. */
+	state: ProgressHeadline;
+	completion: {
+		/** Which countable units the indicator was derived from; `none` means nothing is countable. */
+		basis: ProgressBasisKind;
+		done: number;
+		total: number;
+		/** Whole percent; `null` when `basis` is `none`. Never 100 while a unit is open. */
+		percent: number | null;
+		/** Every counted unit is done (the session may still be awaiting goal completion or subagents). */
+		allUnitsDone: boolean;
+		/** `state === "complete"`: units done, goal (if any) complete, no subagents running, queued, or paused. */
+		complete: boolean;
+		explanation: string;
+	};
+	execution: {
+		goal: { objective: string; status: ProgressGoalStatus; timeUsedSeconds: number } | null;
+		ultragoal: {
+			objective: string;
+			counts: {
+				total: number;
+				complete: number;
+				active: number;
+				pending: number;
+				blocked: number;
+				superseded: number;
+			};
+			stories: ProgressSnapshotStory[];
+			omittedStories: number;
+		} | null;
+		todos: {
+			counts: { total: number; completed: number; inProgress: number; pending: number; abandoned: number };
+			items: ProgressSnapshotTodo[];
+			omittedItems: number;
+		} | null;
+	};
+	activeWork: {
+		/**
+		 * Active story, else the next pending one, matching the Ultragoal scheduler.
+		 * Blocked, review-blocked, and failed stories are never reported here (failed
+		 * stories are retried only on explicit request); `null` when nothing is schedulable.
+		 */
+		story: { id: string; title: string } | null;
+		/** In-progress todo, else the next pending one. */
+		todo: string | null;
+		workflows: ProgressSnapshotWorkflow[];
+		/** Active workflows beyond `PROGRESS_SNAPSHOT_LIMITS.workflows` that `workflows` leaves out. */
+		omittedWorkflows: number;
+		agents: ProgressAgentCounts;
+	};
+	verification: {
+		/** Present only when at least one story is complete. */
+		storyReceipts: { complete: number; withReceipt: number; withoutReceipt: number } | null;
+		reviewVerdicts: ProgressReviewVerdict[];
+	};
+	attention: ProgressSnapshotAttention[];
+	omittedAttention: number;
+	sources: {
+		/** Session-scoped `.gjc` state (workflows, ultragoal plan) was consulted. */
+		sessionStateRead: boolean;
+		/** Sources that exist but could not be read; excluded from every count. */
+		unreadable: ProgressDurableSource[];
+		/** Sources whose primary record was unreadable but whose contents were recovered from authoritative per-entry records. */
+		recovered: ProgressDurableSource[];
+		/** Sources whose readable derived snapshot listed entries the authoritative per-entry records do not; those stale entries were discarded. */
+		discarded: ProgressDurableSource[];
+		/** Sources listing entries whose authority could not be established; those entries are excluded and their absence is unconfirmed. */
+		unresolved: ProgressDurableSource[];
+	};
+}
+
+/** Strip terminal escapes/control characters and bound length; durable text is untrusted. */
+export function boundSnapshotText(text: string, max: number = PROGRESS_SNAPSHOT_LIMITS.text): string {
+	const clean = sanitizeDisplayLine(text).replace(/\s+/g, " ").trim();
+	return clean.length > max ? `${clean.slice(0, max - 1)}…` : clean;
+}

package/src/progress/progress-snapshot.ts

@@ -0,0 +1,140 @@
+/**
+ * Machine-facing projection of the project progress report (SDK query
+ * `session.progress`, Q32). It is a pure re-shaping of `ProjectProgressReport`:
+ * every number, state, and attention item comes from the same computation, and
+ * the human `/progress` view renders this snapshot (`render-progress.ts`), so
+ * the two can never disagree. Absent evidence is `null`/empty, never estimated.
+ * Every bounded list reports how many entries it omitted.
+ */
+import {
+	boundSnapshotText,
+	PROGRESS_SNAPSHOT_LIMITS,
+	PROJECT_PROGRESS_SNAPSHOT_SCHEMA,
+	type ProjectProgressSnapshot,
+} from "./progress-contract";
+import type { ProjectProgressReport } from "./project-progress";
+
+function bounded<T, U>(items: readonly T[], limit: number, map: (item: T) => U): { kept: U[]; omitted: number } {
+	return { kept: items.slice(0, limit).map(map), omitted: Math.max(0, items.length - limit) };
+}
+
+export function toProjectProgressSnapshot(report: ProjectProgressReport): ProjectProgressSnapshot {
+	const { completion } = report;
+	const stories = report.stories;
+	const ultragoal =
+		report.ultragoal && stories
+			? (() => {
+					const { kept, omitted } = bounded(report.ultragoal.stories, PROGRESS_SNAPSHOT_LIMITS.stories, story => ({
+						id: boundSnapshotText(story.id, 64),
+						title: boundSnapshotText(story.title),
+						status: story.status,
+						verificationReceipt: story.hasVerificationReceipt,
+					}));
+					return {
+						objective: boundSnapshotText(report.ultragoal.objective),
+						counts: {
+							total: stories.total,
+							complete: stories.complete,
+							active: stories.active,
+							pending: stories.pending,
+							blocked: stories.blocked,
+							superseded: stories.superseded,
+						},
+						stories: kept,
+						omittedStories: omitted,
+					};
+				})()
+			: null;
+	const todos = report.todos
+		? (() => {
+				const { kept, omitted } = bounded(report.todoItems, PROGRESS_SNAPSHOT_LIMITS.todos, todo => ({
+					content: boundSnapshotText(todo.content),
+					status: todo.status,
+				}));
+				const t = report.todos;
+				return {
+					counts: {
+						total: t.total,
+						completed: t.completed,
+						inProgress: t.inProgress,
+						pending: t.pending,
+						abandoned: t.abandoned,
+					},
+					items: kept,
+					omittedItems: omitted,
+				};
+			})()
+		: null;
+	const workflows = bounded(report.workflows, PROGRESS_SNAPSHOT_LIMITS.workflows, workflow => ({
+		skill: boundSnapshotText(workflow.skill, 64),
+		phase: boundSnapshotText(workflow.phase, 64),
+		summary: workflow.summary ? boundSnapshotText(workflow.summary) : null,
+		chips: workflow.chips.map(chip => ({
+			label: boundSnapshotText(chip.label, 64),
+			value: chip.value ? boundSnapshotText(chip.value) : null,
+			severity: chip.severity ?? null,
+		})),
+	}));
+	const attention = bounded(report.signals, PROGRESS_SNAPSHOT_LIMITS.attention, signal => ({
+		kind: signal.kind,
+		source: signal.source,
+		ref: signal.ref === undefined ? null : boundSnapshotText(signal.ref, 64),
+		text: boundSnapshotText(signal.text),
+	}));
+	const receipts = report.verification.storyReceipts;
+	return {
+		schema: PROJECT_PROGRESS_SNAPSHOT_SCHEMA,
+		state: report.headline,
+		completion: {
+			basis: completion.basis,
+			done: completion.done,
+			total: completion.total,
+			percent: completion.percent ?? null,
+			allUnitsDone: completion.total > 0 && completion.done >= completion.total,
+			complete: report.headline === "complete",
+			explanation: report.basisExplanation,
+		},
+		execution: {
+			goal: report.goal
+				? {
+						objective: boundSnapshotText(report.goal.objective),
+						status: report.goal.status,
+						timeUsedSeconds: report.goal.timeUsedSeconds,
+					}
+				: null,
+			ultragoal,
+			todos,
+		},
+		activeWork: {
+			story: stories?.current
+				? { id: boundSnapshotText(stories.current.id, 64), title: boundSnapshotText(stories.current.title) }
+				: null,
+			todo: report.todos?.current ? boundSnapshotText(report.todos.current) : null,
+			workflows: workflows.kept,
+			omittedWorkflows: workflows.omitted,
+			agents: { ...report.agents },
+		},
+		verification: {
+			storyReceipts: receipts
+				? {
+						complete: receipts.complete,
+						withReceipt: receipts.withReceipt,
+						withoutReceipt: receipts.complete - receipts.withReceipt,
+					}
+				: null,
+			reviewVerdicts: report.verification.reviewVerdicts.map(({ skill, verdict }) => ({
+				skill: boundSnapshotText(skill, 64),
+				verdict: boundSnapshotText(verdict, 64),
+			})),
+		},
+		attention: attention.kept,
+		omittedAttention: attention.omitted,
+		sources: {
+			sessionStateRead: report.sessionStateRead,
+			unreadable: [...report.unreadable],
+			recovered: [...report.recovered],
+			discarded: [...report.discarded],
+			unresolved: [...report.unresolved],
+		},
+	};
+}