@gajae-code/coding-agent 0.18.6 → 0.18.8

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],
+		},
+	};
+}