pi-crew 0.1.37 → 0.1.39

package/src/observability/metrics-primitives.ts

@@ -1,166 +1,166 @@
-export type MetricLabelValue = string | number;
-export type MetricLabels = Record<string, MetricLabelValue>;
-
-export interface MetricPoint {
-	labels: MetricLabels;
-	value: number;
-}
-
-export interface HistogramPoint {
-	labels: MetricLabels;
-	buckets: number[];
-	counts: number[];
-	sum: number;
-	count: number;
-	quantiles: Record<string, number>;
-}
-
-export interface MetricSnapshot {
-	type: "counter" | "gauge" | "histogram";
-	name: string;
-	description: string;
-	values: MetricPoint[] | HistogramPoint[];
-}
-
-interface StoredValue {
-	labels: MetricLabels;
-	value: number;
-}
-
-interface StoredHistogram {
-	labels: MetricLabels;
-	counts: number[];
-	sum: number;
-	count: number;
-}
-
-export const DEFAULT_HISTOGRAM_BUCKETS = [1, 2, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000] as const;
-
-function normalizeLabels(labels: MetricLabels = {}): MetricLabels {
-	const normalized: MetricLabels = {};
-	for (const [key, value] of Object.entries(labels).sort(([left], [right]) => left.localeCompare(right))) normalized[key] = value;
-	return normalized;
-}
-
-export function labelKey(labels: MetricLabels = {}): string {
-	return JSON.stringify(normalizeLabels(labels));
-}
-
-function cloneLabels(labels: MetricLabels): MetricLabels {
-	return { ...labels };
-}
-
-export abstract class Metric {
-	readonly name: string;
-	readonly description: string;
-
-	constructor(name: string, description: string) {
-		this.name = name;
-		this.description = description;
-	}
-
-	abstract snapshot(): MetricSnapshot;
-}
-
-export class Counter extends Metric {
-	private values = new Map<string, StoredValue>();
-
-	inc(labels: MetricLabels = {}, delta = 1): void {
-		if (!Number.isFinite(delta)) return;
-		const key = labelKey(labels);
-		const current = this.values.get(key) ?? { labels: normalizeLabels(labels), value: 0 };
-		this.values.set(key, { labels: current.labels, value: current.value + delta });
-	}
-
-	value(labels: MetricLabels = {}): number {
-		return this.values.get(labelKey(labels))?.value ?? 0;
-	}
-
-	snapshot(): MetricSnapshot {
-		return { type: "counter", name: this.name, description: this.description, values: [...this.values.values()].map((entry) => ({ labels: cloneLabels(entry.labels), value: entry.value })) };
-	}
-}
-
-export class Gauge extends Metric {
-	private values = new Map<string, StoredValue>();
-
-	set(labels: MetricLabels = {}, value: number): void {
-		if (!Number.isFinite(value)) return;
-		this.values.set(labelKey(labels), { labels: normalizeLabels(labels), value });
-	}
-
-	add(labels: MetricLabels = {}, delta: number): void {
-		if (!Number.isFinite(delta)) return;
-		this.set(labels, this.value(labels) + delta);
-	}
-
-	value(labels: MetricLabels = {}): number {
-		return this.values.get(labelKey(labels))?.value ?? 0;
-	}
-
-	snapshot(): MetricSnapshot {
-		return { type: "gauge", name: this.name, description: this.description, values: [...this.values.values()].map((entry) => ({ labels: cloneLabels(entry.labels), value: entry.value })) };
-	}
-}
-
-export class Histogram extends Metric {
-	private readonly buckets: number[];
-	private observations = new Map<string, StoredHistogram>();
-
-	constructor(name: string, description: string, buckets?: number[]) {
-		super(name, description);
-		const source = buckets?.length ? buckets : [...DEFAULT_HISTOGRAM_BUCKETS];
-		this.buckets = [...new Set(source.filter((bucket) => Number.isFinite(bucket)).sort((left, right) => left - right))];
-	}
-
-	observe(labels: MetricLabels = {}, value: number): void {
-		if (!Number.isFinite(value)) return;
-		const key = labelKey(labels);
-		const current = this.observations.get(key) ?? { labels: normalizeLabels(labels), counts: new Array(this.buckets.length + 1).fill(0) as number[], sum: 0, count: 0 };
-		const bucketIndex = this.buckets.findIndex((bucket) => value <= bucket);
-		current.counts[bucketIndex === -1 ? this.buckets.length : bucketIndex] = (current.counts[bucketIndex === -1 ? this.buckets.length : bucketIndex] ?? 0) + 1;
-		current.sum += value;
-		current.count += 1;
-		this.observations.set(key, current);
-	}
-
-	quantile(labels: MetricLabels = {}, q: number): number {
-		const obs = this.observations.get(labelKey(labels));
-		if (!obs || obs.count === 0 || !Number.isFinite(q)) return Number.NaN;
-		const bounded = Math.min(1, Math.max(0, q));
-		const target = Math.max(1, bounded * obs.count);
-		let cumulative = 0;
-		for (let index = 0; index < obs.counts.length; index += 1) {
-			const count = obs.counts[index] ?? 0;
-			cumulative += count;
-			if (cumulative >= target) {
-				const previous = cumulative - count;
-				const lower = index === 0 ? 0 : this.buckets[index - 1] ?? this.buckets.at(-1) ?? 0;
-				const upper = index < this.buckets.length ? this.buckets[index] ?? lower : Math.max(lower, obs.sum / Math.max(1, obs.count));
-				const fraction = count === 0 ? 0 : (target - previous) / Math.max(1, count);
-				return lower + fraction * (upper - lower);
-			}
-		}
-		return this.buckets.at(-1) ?? Number.NaN;
-	}
-
-	count(labels: MetricLabels = {}): number {
-		return this.observations.get(labelKey(labels))?.count ?? 0;
-	}
-
-	snapshot(): MetricSnapshot {
-		return {
-			type: "histogram",
-			name: this.name,
-			description: this.description,
-			values: [...this.observations.values()].map((entry) => ({
-				labels: cloneLabels(entry.labels),
-				buckets: [...this.buckets, Number.POSITIVE_INFINITY],
-				counts: [...entry.counts],
-				sum: entry.sum,
-				count: entry.count,
-				quantiles: { p50: this.quantile(entry.labels, 0.5), p95: this.quantile(entry.labels, 0.95), p99: this.quantile(entry.labels, 0.99) },
-			})),
-		};
-	}
-}
+export type MetricLabelValue = string | number;
+export type MetricLabels = Record<string, MetricLabelValue>;
+
+export interface MetricPoint {
+	labels: MetricLabels;
+	value: number;
+}
+
+export interface HistogramPoint {
+	labels: MetricLabels;
+	buckets: number[];
+	counts: number[];
+	sum: number;
+	count: number;
+	quantiles: Record<string, number>;
+}
+
+export interface MetricSnapshot {
+	type: "counter" | "gauge" | "histogram";
+	name: string;
+	description: string;
+	values: MetricPoint[] | HistogramPoint[];
+}
+
+interface StoredValue {
+	labels: MetricLabels;
+	value: number;
+}
+
+interface StoredHistogram {
+	labels: MetricLabels;
+	counts: number[];
+	sum: number;
+	count: number;
+}
+
+export const DEFAULT_HISTOGRAM_BUCKETS = [1, 2, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000] as const;
+
+function normalizeLabels(labels: MetricLabels = {}): MetricLabels {
+	const normalized: MetricLabels = {};
+	for (const [key, value] of Object.entries(labels).sort(([left], [right]) => left.localeCompare(right))) normalized[key] = value;
+	return normalized;
+}
+
+export function labelKey(labels: MetricLabels = {}): string {
+	return JSON.stringify(normalizeLabels(labels));
+}
+
+function cloneLabels(labels: MetricLabels): MetricLabels {
+	return { ...labels };
+}
+
+export abstract class Metric {
+	readonly name: string;
+	readonly description: string;
+
+	constructor(name: string, description: string) {
+		this.name = name;
+		this.description = description;
+	}
+
+	abstract snapshot(): MetricSnapshot;
+}
+
+export class Counter extends Metric {
+	private values = new Map<string, StoredValue>();
+
+	inc(labels: MetricLabels = {}, delta = 1): void {
+		if (!Number.isFinite(delta)) return;
+		const key = labelKey(labels);
+		const current = this.values.get(key) ?? { labels: normalizeLabels(labels), value: 0 };
+		this.values.set(key, { labels: current.labels, value: current.value + delta });
+	}
+
+	value(labels: MetricLabels = {}): number {
+		return this.values.get(labelKey(labels))?.value ?? 0;
+	}
+
+	snapshot(): MetricSnapshot {
+		return { type: "counter", name: this.name, description: this.description, values: [...this.values.values()].map((entry) => ({ labels: cloneLabels(entry.labels), value: entry.value })) };
+	}
+}
+
+export class Gauge extends Metric {
+	private values = new Map<string, StoredValue>();
+
+	set(labels: MetricLabels = {}, value: number): void {
+		if (!Number.isFinite(value)) return;
+		this.values.set(labelKey(labels), { labels: normalizeLabels(labels), value });
+	}
+
+	add(labels: MetricLabels = {}, delta: number): void {
+		if (!Number.isFinite(delta)) return;
+		this.set(labels, this.value(labels) + delta);
+	}
+
+	value(labels: MetricLabels = {}): number {
+		return this.values.get(labelKey(labels))?.value ?? 0;
+	}
+
+	snapshot(): MetricSnapshot {
+		return { type: "gauge", name: this.name, description: this.description, values: [...this.values.values()].map((entry) => ({ labels: cloneLabels(entry.labels), value: entry.value })) };
+	}
+}
+
+export class Histogram extends Metric {
+	private readonly buckets: number[];
+	private observations = new Map<string, StoredHistogram>();
+
+	constructor(name: string, description: string, buckets?: number[]) {
+		super(name, description);
+		const source = buckets?.length ? buckets : [...DEFAULT_HISTOGRAM_BUCKETS];
+		this.buckets = [...new Set(source.filter((bucket) => Number.isFinite(bucket)).sort((left, right) => left - right))];
+	}
+
+	observe(labels: MetricLabels = {}, value: number): void {
+		if (!Number.isFinite(value)) return;
+		const key = labelKey(labels);
+		const current = this.observations.get(key) ?? { labels: normalizeLabels(labels), counts: new Array(this.buckets.length + 1).fill(0) as number[], sum: 0, count: 0 };
+		const bucketIndex = this.buckets.findIndex((bucket) => value <= bucket);
+		current.counts[bucketIndex === -1 ? this.buckets.length : bucketIndex] = (current.counts[bucketIndex === -1 ? this.buckets.length : bucketIndex] ?? 0) + 1;
+		current.sum += value;
+		current.count += 1;
+		this.observations.set(key, current);
+	}
+
+	quantile(labels: MetricLabels = {}, q: number): number {
+		const obs = this.observations.get(labelKey(labels));
+		if (!obs || obs.count === 0 || !Number.isFinite(q)) return Number.NaN;
+		const bounded = Math.min(1, Math.max(0, q));
+		const target = Math.max(1, bounded * obs.count);
+		let cumulative = 0;
+		for (let index = 0; index < obs.counts.length; index += 1) {
+			const count = obs.counts[index] ?? 0;
+			cumulative += count;
+			if (cumulative >= target) {
+				const previous = cumulative - count;
+				const lower = index === 0 ? 0 : this.buckets[index - 1] ?? this.buckets.at(-1) ?? 0;
+				const upper = index < this.buckets.length ? this.buckets[index] ?? lower : Math.max(lower, obs.sum / Math.max(1, obs.count));
+				const fraction = count === 0 ? 0 : (target - previous) / Math.max(1, count);
+				return lower + fraction * (upper - lower);
+			}
+		}
+		return this.buckets.at(-1) ?? Number.NaN;
+	}
+
+	count(labels: MetricLabels = {}): number {
+		return this.observations.get(labelKey(labels))?.count ?? 0;
+	}
+
+	snapshot(): MetricSnapshot {
+		return {
+			type: "histogram",
+			name: this.name,
+			description: this.description,
+			values: [...this.observations.values()].map((entry) => ({
+				labels: cloneLabels(entry.labels),
+				buckets: [...this.buckets, Number.POSITIVE_INFINITY],
+				counts: [...entry.counts],
+				sum: entry.sum,
+				count: entry.count,
+				quantiles: { p50: this.quantile(entry.labels, 0.5), p95: this.quantile(entry.labels, 0.95), p99: this.quantile(entry.labels, 0.99) },
+			})),
+		};
+	}
+}

package/src/prompt/prompt-runtime.ts

@@ -1,68 +1,68 @@
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-
-export const PI_TEAMS_INHERIT_PROJECT_CONTEXT_ENV = "PI_TEAMS_INHERIT_PROJECT_CONTEXT";
-export const PI_TEAMS_INHERIT_SKILLS_ENV = "PI_TEAMS_INHERIT_SKILLS";
-export const PI_CREW_INHERIT_PROJECT_CONTEXT_ENV = "PI_CREW_INHERIT_PROJECT_CONTEXT";
-export const PI_CREW_INHERIT_SKILLS_ENV = "PI_CREW_INHERIT_SKILLS";
-
-const PROJECT_CONTEXT_HEADER = "\n\n# Project Context\n\nProject-specific instructions and guidelines:\n\n";
-const SKILLS_HEADER = "\n\nThe following skills provide specialized instructions for specific tasks.";
-const DATE_HEADER = "\nCurrent date:";
-
-function readBooleanEnv(name: string): boolean | undefined {
-	const value = process.env[name];
-	if (value === undefined) return undefined;
-	return value !== "0";
-}
-
-function readBooleanEnvAny(...names: string[]): boolean | undefined {
-	for (const name of names) {
-		const value = readBooleanEnv(name);
-		if (value !== undefined) return value;
-	}
-	return undefined;
-}
-
-function findSectionEnd(prompt: string, startIndex: number, nextHeaders: string[]): number {
-	let endIndex = prompt.length;
-	for (const header of nextHeaders) {
-		const index = prompt.indexOf(header, startIndex);
-		if (index !== -1 && index < endIndex) endIndex = index;
-	}
-	return endIndex;
-}
-
-export function stripProjectContext(prompt: string): string {
-	const startIndex = prompt.indexOf(PROJECT_CONTEXT_HEADER);
-	if (startIndex === -1) return prompt;
-	const endIndex = findSectionEnd(prompt, startIndex + PROJECT_CONTEXT_HEADER.length, [SKILLS_HEADER, DATE_HEADER]);
-	return `${prompt.slice(0, startIndex)}${prompt.slice(endIndex)}`;
-}
-
-export function stripInheritedSkills(prompt: string): string {
-	const startIndex = prompt.indexOf(SKILLS_HEADER);
-	if (startIndex === -1) return prompt;
-	const endIndex = findSectionEnd(prompt, startIndex + SKILLS_HEADER.length, [DATE_HEADER]);
-	return `${prompt.slice(0, startIndex)}${prompt.slice(endIndex)}`;
-}
-
-export function rewriteTeamWorkerPrompt(prompt: string, options: { inheritProjectContext: boolean; inheritSkills: boolean }): string {
-	let rewritten = prompt;
-	if (!options.inheritProjectContext) rewritten = stripProjectContext(rewritten);
-	if (!options.inheritSkills) rewritten = stripInheritedSkills(rewritten);
-	return rewritten;
-}
-
-export default function registerPiTeamsPromptRuntime(pi: ExtensionAPI): void {
-	pi.on("before_agent_start", (event) => {
-		const inheritProjectContext = readBooleanEnvAny(PI_CREW_INHERIT_PROJECT_CONTEXT_ENV, PI_TEAMS_INHERIT_PROJECT_CONTEXT_ENV);
-		const inheritSkills = readBooleanEnvAny(PI_CREW_INHERIT_SKILLS_ENV, PI_TEAMS_INHERIT_SKILLS_ENV);
-		if (inheritProjectContext === undefined && inheritSkills === undefined) return;
-		const rewritten = rewriteTeamWorkerPrompt(event.systemPrompt, {
-			inheritProjectContext: inheritProjectContext ?? true,
-			inheritSkills: inheritSkills ?? true,
-		});
-		if (rewritten === event.systemPrompt) return;
-		return { systemPrompt: rewritten };
-	});
-}
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+export const PI_TEAMS_INHERIT_PROJECT_CONTEXT_ENV = "PI_TEAMS_INHERIT_PROJECT_CONTEXT";
+export const PI_TEAMS_INHERIT_SKILLS_ENV = "PI_TEAMS_INHERIT_SKILLS";
+export const PI_CREW_INHERIT_PROJECT_CONTEXT_ENV = "PI_CREW_INHERIT_PROJECT_CONTEXT";
+export const PI_CREW_INHERIT_SKILLS_ENV = "PI_CREW_INHERIT_SKILLS";
+
+const PROJECT_CONTEXT_HEADER = "\n\n# Project Context\n\nProject-specific instructions and guidelines:\n\n";
+const SKILLS_HEADER = "\n\nThe following skills provide specialized instructions for specific tasks.";
+const DATE_HEADER = "\nCurrent date:";
+
+function readBooleanEnv(name: string): boolean | undefined {
+	const value = process.env[name];
+	if (value === undefined) return undefined;
+	return value !== "0";
+}
+
+function readBooleanEnvAny(...names: string[]): boolean | undefined {
+	for (const name of names) {
+		const value = readBooleanEnv(name);
+		if (value !== undefined) return value;
+	}
+	return undefined;
+}
+
+function findSectionEnd(prompt: string, startIndex: number, nextHeaders: string[]): number {
+	let endIndex = prompt.length;
+	for (const header of nextHeaders) {
+		const index = prompt.indexOf(header, startIndex);
+		if (index !== -1 && index < endIndex) endIndex = index;
+	}
+	return endIndex;
+}
+
+export function stripProjectContext(prompt: string): string {
+	const startIndex = prompt.indexOf(PROJECT_CONTEXT_HEADER);
+	if (startIndex === -1) return prompt;
+	const endIndex = findSectionEnd(prompt, startIndex + PROJECT_CONTEXT_HEADER.length, [SKILLS_HEADER, DATE_HEADER]);
+	return `${prompt.slice(0, startIndex)}${prompt.slice(endIndex)}`;
+}
+
+export function stripInheritedSkills(prompt: string): string {
+	const startIndex = prompt.indexOf(SKILLS_HEADER);
+	if (startIndex === -1) return prompt;
+	const endIndex = findSectionEnd(prompt, startIndex + SKILLS_HEADER.length, [DATE_HEADER]);
+	return `${prompt.slice(0, startIndex)}${prompt.slice(endIndex)}`;
+}
+
+export function rewriteTeamWorkerPrompt(prompt: string, options: { inheritProjectContext: boolean; inheritSkills: boolean }): string {
+	let rewritten = prompt;
+	if (!options.inheritProjectContext) rewritten = stripProjectContext(rewritten);
+	if (!options.inheritSkills) rewritten = stripInheritedSkills(rewritten);
+	return rewritten;
+}
+
+export default function registerPiTeamsPromptRuntime(pi: ExtensionAPI): void {
+	pi.on("before_agent_start", (event) => {
+		const inheritProjectContext = readBooleanEnvAny(PI_CREW_INHERIT_PROJECT_CONTEXT_ENV, PI_TEAMS_INHERIT_PROJECT_CONTEXT_ENV);
+		const inheritSkills = readBooleanEnvAny(PI_CREW_INHERIT_SKILLS_ENV, PI_TEAMS_INHERIT_SKILLS_ENV);
+		if (inheritProjectContext === undefined && inheritSkills === undefined) return;
+		const rewritten = rewriteTeamWorkerPrompt(event.systemPrompt, {
+			inheritProjectContext: inheritProjectContext ?? true,
+			inheritSkills: inheritSkills ?? true,
+		});
+		if (rewritten === event.systemPrompt) return;
+		return { systemPrompt: rewritten };
+	});
+}

package/src/runtime/agent-control.ts

@@ -1,64 +1,64 @@
-import type { PiTeamsConfig } from "../config/config.ts";
-import type { TeamRunManifest } from "../state/types.ts";
-import { appendEvent } from "../state/event-log.ts";
-import type { CrewAgentRecord } from "./crew-agent-runtime.ts";
-import { upsertCrewAgent } from "./crew-agent-records.ts";
-
-export interface CrewControlConfig {
-	enabled: boolean;
-	needsAttentionAfterMs: number;
-}
-
-const DEFAULT_NEEDS_ATTENTION_MS = 60_000;
-
-function positiveInt(value: unknown): number | undefined {
-	return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : undefined;
-}
-
-export function resolveCrewControlConfig(config: PiTeamsConfig | undefined): CrewControlConfig {
-	const raw = config as PiTeamsConfig & { control?: { enabled?: unknown; needsAttentionAfterMs?: unknown } } | undefined;
-	return {
-		enabled: raw?.control?.enabled === false ? false : true,
-		needsAttentionAfterMs: positiveInt(raw?.control?.needsAttentionAfterMs) ?? DEFAULT_NEEDS_ATTENTION_MS,
-	};
-}
-
-export function activityAgeMs(agent: CrewAgentRecord, now = Date.now()): number | undefined {
-	const timestamp = agent.progress?.lastActivityAt ?? agent.startedAt;
-	if (!timestamp) return undefined;
-	const ms = now - new Date(timestamp).getTime();
-	return Number.isFinite(ms) ? Math.max(0, ms) : undefined;
-}
-
-export function formatActivityAge(agent: CrewAgentRecord, now = Date.now()): string | undefined {
-	const age = activityAgeMs(agent, now);
-	if (age === undefined) return undefined;
-	if (age < 1000) return "active now";
-	const seconds = Math.floor(age / 1000);
-	if (seconds < 60) return agent.progress?.activityState === "needs_attention" ? `no activity for ${seconds}s` : `active ${seconds}s ago`;
-	const minutes = Math.floor(seconds / 60);
-	return agent.progress?.activityState === "needs_attention" ? `no activity for ${minutes}m` : `active ${minutes}m ago`;
-}
-
-export function applyAttentionState(manifest: TeamRunManifest, agent: CrewAgentRecord, config: CrewControlConfig, now = Date.now()): CrewAgentRecord {
-	if (!config.enabled || agent.status !== "running") return agent;
-	const age = activityAgeMs(agent, now);
-	if (age === undefined || age <= config.needsAttentionAfterMs) return agent;
-	if (agent.progress?.activityState === "needs_attention") return agent;
-	const updated: CrewAgentRecord = {
-		...agent,
-		progress: {
-			...(agent.progress ?? { recentTools: [], recentOutput: [], toolCount: agent.toolUses ?? 0 }),
-			activityState: "needs_attention",
-		},
-	};
-	upsertCrewAgent(manifest, updated);
-	appendEvent(manifest.eventsPath, {
-		type: "agent.needs_attention",
-		runId: manifest.runId,
-		taskId: agent.taskId,
-		message: `${agent.agent} needs attention (no observed activity for ${Math.floor(age / 1000)}s).`,
-		data: { agentId: agent.id, ageMs: age, needsAttentionAfterMs: config.needsAttentionAfterMs },
-	});
-	return updated;
-}
+import type { PiTeamsConfig } from "../config/config.ts";
+import type { TeamRunManifest } from "../state/types.ts";
+import { appendEvent } from "../state/event-log.ts";
+import type { CrewAgentRecord } from "./crew-agent-runtime.ts";
+import { upsertCrewAgent } from "./crew-agent-records.ts";
+
+export interface CrewControlConfig {
+	enabled: boolean;
+	needsAttentionAfterMs: number;
+}
+
+const DEFAULT_NEEDS_ATTENTION_MS = 60_000;
+
+function positiveInt(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : undefined;
+}
+
+export function resolveCrewControlConfig(config: PiTeamsConfig | undefined): CrewControlConfig {
+	const raw = config as PiTeamsConfig & { control?: { enabled?: unknown; needsAttentionAfterMs?: unknown } } | undefined;
+	return {
+		enabled: raw?.control?.enabled === false ? false : true,
+		needsAttentionAfterMs: positiveInt(raw?.control?.needsAttentionAfterMs) ?? DEFAULT_NEEDS_ATTENTION_MS,
+	};
+}
+
+export function activityAgeMs(agent: CrewAgentRecord, now = Date.now()): number | undefined {
+	const timestamp = agent.progress?.lastActivityAt ?? agent.startedAt;
+	if (!timestamp) return undefined;
+	const ms = now - new Date(timestamp).getTime();
+	return Number.isFinite(ms) ? Math.max(0, ms) : undefined;
+}
+
+export function formatActivityAge(agent: CrewAgentRecord, now = Date.now()): string | undefined {
+	const age = activityAgeMs(agent, now);
+	if (age === undefined) return undefined;
+	if (age < 1000) return "active now";
+	const seconds = Math.floor(age / 1000);
+	if (seconds < 60) return agent.progress?.activityState === "needs_attention" ? `no activity for ${seconds}s` : `active ${seconds}s ago`;
+	const minutes = Math.floor(seconds / 60);
+	return agent.progress?.activityState === "needs_attention" ? `no activity for ${minutes}m` : `active ${minutes}m ago`;
+}
+
+export function applyAttentionState(manifest: TeamRunManifest, agent: CrewAgentRecord, config: CrewControlConfig, now = Date.now()): CrewAgentRecord {
+	if (!config.enabled || agent.status !== "running") return agent;
+	const age = activityAgeMs(agent, now);
+	if (age === undefined || age <= config.needsAttentionAfterMs) return agent;
+	if (agent.progress?.activityState === "needs_attention") return agent;
+	const updated: CrewAgentRecord = {
+		...agent,
+		progress: {
+			...(agent.progress ?? { recentTools: [], recentOutput: [], toolCount: agent.toolUses ?? 0 }),
+			activityState: "needs_attention",
+		},
+	};
+	upsertCrewAgent(manifest, updated);
+	appendEvent(manifest.eventsPath, {
+		type: "agent.needs_attention",
+		runId: manifest.runId,
+		taskId: agent.taskId,
+		message: `${agent.agent} needs attention (no observed activity for ${Math.floor(age / 1000)}s).`,
+		data: { agentId: agent.id, ageMs: age, needsAttentionAfterMs: config.needsAttentionAfterMs },
+	});
+	return updated;
+}