gentle-pi 3.7.0 → 4.1.0

package/lib/agent-profile-pin.ts

@@ -293,6 +293,18 @@ export function evaluateProfilePin(
 	return evaluation;
 }
 
+// Admission-only lookup at an explicitly bound non-Git project. Do not create
+// a fake commonDir or change public pin/status semantics outside repositories.
+export function resolveUnversionedProjectProfile(cwd: string, configHome: string): (ProfilePinSelection & { modelProfiles: AgentModelConfig }) | undefined {
+	const path = repoProfileDeclarationPath(cwd);
+	const pin = readProfilePinResult(path);
+	if (pin.status !== "valid") return undefined;
+	const store = readProfilesFileResult(profilesFilePath(configHome));
+	if (store.status !== "valid" || !hasProfile(store.file.profiles, pin.profile)) return undefined;
+	const config = store.file.profiles[pin.profile];
+	return { source: "repo", profile: pin.profile, path, modelProfiles: Object.fromEntries(profileRoleEntries(config).map(([agent, entry]) => [agent, { ...entry }])) };
+}
+
 export interface ProfilePinResolveOptions {
 	cwd: string;
 	configHome: string;

package/lib/agent-profiles.ts

@@ -406,18 +406,28 @@ export interface ProfileListItem {
 	description: string;
 }
 
+/** One list item per saved profile, named with the markers that explain what a launch would use: the global `(active)` claim, plus `(pinned)` for the pin winner or `(session)` for this session's binding when either applies. */
 export function buildProfileListItems(
 	file: AgentProfilesFile,
 	pinned?: string,
+	sessionBound?: string,
 ): ProfileListItem[] {
 	return Object.entries(file.profiles).map(([name, config]) => {
 		const roles = profileRoleEntries(config).length;
 		const active = name === file.active ? `${name} (active)` : name;
+		// A pinned profile is the one this repository launches with, which is not the
+		// same thing as the globally active profile, so both are named. A session
+		// binding outranks the pin in this list (slice 1 stores it; slice 2,
+		// gentle-shell#1558, makes launches resolve it), so its marker wins on the
+		// same profile.
+		const label = name === sessionBound
+			? `${active} (session)`
+			: name === pinned
+				? `${active} (pinned)`
+				: active;
 		return {
 			id: name,
-			// A pinned profile is the one this repository launches with, which is not the
-			// same thing as the globally active profile, so both are named.
-			label: name === pinned ? `${active} (pinned)` : active,
+			label,
 			description: `${roles} ${roles === 1 ? "role" : "roles"}`,
 		};
 	});

package/lib/agents-completion-delivery.ts

@@ -11,9 +11,10 @@
 // behavior is unit-testable against a fake clock.
 
 /**
- * A completion older than this at flush time is stale: the parent had many
- * turns to pull the result with subagent_result, so replaying it into the
- * model context would re-enter state the conversation may already have used.
+ * A completion older than this at flush time is stale: replaying its full
+ * report into the model context could re-enter state the conversation may
+ * already have used, so the parent gets a compact notice instead. The parent
+ * is told never to poll, so a stale completion must still announce itself.
  * Ninety seconds comfortably covers one slow orchestrator turn (model latency
  * plus a few tool calls) while staying orders of magnitude below the 50-58
  * minute followUp delays measured in issue #867.
@@ -36,6 +37,8 @@ export interface CompletionQueue<T extends { id: string }> {
 	consume(taskId: string): void;
 	/** Remove and return the still-pending completions in settle order, each with its staleness decision at `now`. Consumed entries are dropped and never returned. */
 	takeDeliverable(now: number): Array<DeliverableCompletion<T>>;
+	/** Return a taken completion whose forwarding failed to the pending queue, so a later flush retries it. A consumed id stays dropped. */
+	requeue(entry: DeliverableCompletion<T>): void;
 	/** Discard everything: pending completions and consumed/delivered bookkeeping. Used on session start and shutdown so nothing replays after a resume. */
 	dropAll(): void;
 }
@@ -63,6 +66,11 @@ export function createCompletionQueue<T extends { id: string }>(): CompletionQue
 			}
 			return deliverable;
 		},
+		requeue(entry) {
+			delivered.delete(entry.task.id);
+			if (consumed.has(entry.task.id) || pending.some((pendingEntry) => pendingEntry.task.id === entry.task.id)) return;
+			pending.push({ task: entry.task, settledAt: entry.settledAt });
+		},
 		dropAll() {
 			pending = [];
 			consumed.clear();

package/lib/agents-message-delivery.ts

@@ -0,0 +1,181 @@
+// Gentle Agents subagent message delivery queue (issue #1162).
+//
+// Background and foreground child notifications and queries used to be handed
+// straight to the host as `deliverAs: "followUp"` messages. Because the host
+// only drains the follow-up queue when the parent agent stops calling tools
+// entirely, stale notifications and already-answered or expired queries could
+// re-enter the conversation long after the child task completed, re-triggering
+// the parent LLM unnecessarily (#1162).
+//
+// This module owns the pending messages instead: the extension enqueues them,
+// tracks query answer/timeout/cancellation lifecycle, invalidates messages on
+// task completion, and flushes only live, fresh messages at turn boundaries or
+// idle using `deliverAs: "steer"`.
+
+export const STALE_NOTIFICATION_MS = 90_000;
+
+export type AgentMessageKind = "notification" | "query";
+
+export interface PendingAgentMessage {
+	taskId: string;
+	agent: string;
+	kind: AgentMessageKind;
+	content: string;
+	parentSessionId: string;
+	requestId?: string;
+	display: boolean;
+	details: Record<string, unknown>;
+	enqueuedAt: number;
+}
+
+export interface AgentMessageQueue {
+	/** Enqueue an ordinary notification from a subagent. */
+	enqueueNotification(
+		task: { id: string; agent: string; parentSessionId: string },
+		content: string,
+		enqueuedAt: number,
+	): void;
+
+	/** Enqueue an interactive query from a subagent. */
+	enqueueQuery(
+		task: { id: string; agent: string; parentSessionId: string },
+		requestId: string,
+		question: string,
+		enqueuedAt: number,
+	): void;
+
+	/** Mark a query as consumed (e.g. answered or directly handed off). Prevents subsequent delivery. */
+	consumeQuery(taskId: string, requestId: string): void;
+
+	/** Mark a query as expired (timed out or errored). Prevents delivery. */
+	expireQuery(taskId: string, requestId: string): void;
+
+	/** Invalidate all pending messages (notifications and queries) for a settled or cancelled task. */
+	invalidateTask(taskId: string): void;
+
+	/** Return deliverable messages in enqueue order for the active session, dropping stale/consumed ones. */
+	takeDeliverable(
+		now: number,
+		activeSessionId: string,
+		isTaskLive: (taskId: string) => boolean,
+	): Array<PendingAgentMessage>;
+
+	/** Return number of pending messages waiting to be delivered. */
+	pendingCount(): number;
+
+	/** Discard all pending messages and tracking sets (on session change or shutdown). */
+	dropAll(): void;
+}
+
+/**
+ * Creates an agent message queue that manages pending notifications and queries
+ * from subagents, bounding their lifetime and invalidating stale messages upon
+ * task settlement or query resolution.
+ */
+export function createAgentMessageQueue(): AgentMessageQueue {
+	let pending: Array<PendingAgentMessage> = [];
+	const consumedQueries = new Set<string>();
+	const expiredQueries = new Set<string>();
+	const invalidatedTasks = new Set<string>();
+
+	const queryKey = (taskId: string, requestId: string) => `${taskId}:${requestId}`;
+
+	return {
+		enqueueNotification(task, content, enqueuedAt) {
+			if (invalidatedTasks.has(task.id)) return;
+			pending.push({
+				taskId: task.id,
+				agent: task.agent,
+				kind: "notification",
+				content,
+				parentSessionId: task.parentSessionId,
+				display: false,
+				details: {
+					gentleAgents: {
+						taskId: task.id,
+						agent: task.agent,
+						parentSessionId: task.parentSessionId,
+						kind: "notification",
+					},
+				},
+				enqueuedAt,
+			});
+		},
+
+		enqueueQuery(task, requestId, question, enqueuedAt) {
+			const key = queryKey(task.id, requestId);
+			if (invalidatedTasks.has(task.id) || consumedQueries.has(key) || expiredQueries.has(key)) return;
+			if (pending.some((msg) => msg.kind === "query" && msg.taskId === task.id && msg.requestId === requestId)) return;
+			pending.push({
+				taskId: task.id,
+				agent: task.agent,
+				kind: "query",
+				content: `Subagent ${task.agent} asks:\nTask ID: ${task.id}\nRequest ID: ${requestId}\nQuestion: ${question}`,
+				parentSessionId: task.parentSessionId,
+				requestId,
+				display: true,
+				details: {
+					gentleAgents: {
+						taskId: task.id,
+						agent: task.agent,
+						parentSessionId: task.parentSessionId,
+						requestId,
+						kind: "query",
+					},
+				},
+				enqueuedAt,
+			});
+		},
+
+		consumeQuery(taskId, requestId) {
+			const key = queryKey(taskId, requestId);
+			consumedQueries.add(key);
+			pending = pending.filter((msg) => !(msg.kind === "query" && msg.taskId === taskId && msg.requestId === requestId));
+		},
+
+		expireQuery(taskId, requestId) {
+			const key = queryKey(taskId, requestId);
+			expiredQueries.add(key);
+			pending = pending.filter((msg) => !(msg.kind === "query" && msg.taskId === taskId && msg.requestId === requestId));
+		},
+
+		invalidateTask(taskId) {
+			invalidatedTasks.add(taskId);
+			pending = pending.filter((msg) => msg.taskId !== taskId);
+		},
+
+		takeDeliverable(now, activeSessionId, isTaskLive) {
+			const taken = pending;
+			pending = [];
+			const deliverable: Array<PendingAgentMessage> = [];
+
+			for (const msg of taken) {
+				if (msg.parentSessionId !== activeSessionId) continue;
+				if (invalidatedTasks.has(msg.taskId)) continue;
+				if (!isTaskLive(msg.taskId)) continue;
+
+				if (msg.kind === "query") {
+					const key = queryKey(msg.taskId, msg.requestId!);
+					if (consumedQueries.has(key) || expiredQueries.has(key)) continue;
+				} else if (msg.kind === "notification") {
+					if (now - msg.enqueuedAt >= STALE_NOTIFICATION_MS) continue;
+				}
+
+				deliverable.push(msg);
+			}
+
+			return deliverable;
+		},
+
+		pendingCount() {
+			return pending.length;
+		},
+
+		dropAll() {
+			pending = [];
+			consumedQueries.clear();
+			expiredQueries.clear();
+			invalidatedTasks.clear();
+		},
+	};
+}

package/lib/agents-messaging.ts

@@ -95,7 +95,7 @@ function parseAck(value: unknown): AckFrame | undefined {
 	if (!record(value) || !exact(value, ["id", "kind", "accepted", "error"]) || !validChildId(value.id) || value.kind !== "ack" || typeof value.accepted !== "boolean") return undefined;
 	if (value.accepted && value.error !== undefined) return undefined;
 	if (value.error !== undefined && !boundedText(value.error, CHILD_ACK_ERROR_MAX_BYTES)) return undefined;
-	return { id: value.id, accepted: value.accepted, ...(value.error === undefined ? {} : { error: value.error }) };
+	return { id: value.id, accepted: value.accepted, ...(typeof value.error === "string" ? { error: value.error } : {}) };
 }
 
 function parseReply(value: unknown): ReplyFrame | undefined {

package/lib/agents-protocol.ts

@@ -1,3 +1,4 @@
+import { createHash, randomUUID } from "node:crypto";
 import { sanitizeTerminalText } from "./terminal-theme.ts";
 
 // Gentle Agents protocol. A child pi process streams RPC events; the host
@@ -147,10 +148,23 @@ export interface TaskSummary {
 
 export type TaskListener = (task: TaskRecord, thread: TaskThread) => void;
 export type SummaryListener = (summary: TaskSummary) => void;
+export interface TaskStatusChange {
+	readonly producerId: string;
+	readonly sessionId: string;
+	readonly parentSessionId: string;
+	readonly taskId: string;
+	readonly runId: string;
+	readonly status: TaskStatus;
+	readonly previousStatus?: TaskStatus;
+	readonly sequence: number;
+}
+export type StatusChangeListener = (change: TaskStatusChange) => void | Promise<void>;
 
 const DEFAULT_LIMITS: ThreadLimits = { maxItems: 400, maxOutputChars: 16_000 };
 /** Child UI requests that block on an answer; everything else (notify, setStatus, setWidget) is noise here. */
 export const DIALOG_METHODS: ReadonlySet<string> = new Set(["select", "confirm", "input", "editor"]);
+/** The one child notify that reaches the task thread: requested --tools the child does not have (#1690). */
+export const MISSING_TOOLS_NOTE_PREFIX = "gentle-agents: requested tools missing in child:";
 const LABEL_MAX = 72;
 const TEXT_CAP = 20_000;
 const ELLIPSIS = "…";
@@ -226,6 +240,65 @@ function childResponse(message: Raw): ChildResponseObservation | undefined {
 	});
 }
 
+const ARGUMENT_PROGRESS_MAX = 4096;
+
+/** Per-child liveness evidence, separate from display events and usage.
+ * RPC deltas have no sequence number. Reject duplicate fingerprints rather
+ * than claiming indistinguishable repeated bytes are fresh progress. Retain
+ * only hashes, never arguments; exhaustion fails closed until a new message.
+ */
+export class ToolArgumentProgress {
+	private timestamp = -1;
+	private active = false;
+	private readonly blocks = new Map<number, boolean>();
+	private readonly fingerprints = new Set<string>();
+
+	observe(raw: Record<string, unknown>): boolean {
+		if (raw.type === "message_start") {
+			const message = raw.message as Raw | undefined;
+			if (message?.role === "assistant" && typeof message.timestamp === "number" && Number.isSafeInteger(message.timestamp)
+				&& message.timestamp >= 0 && message.timestamp > this.timestamp && !this.active) {
+				this.timestamp = message.timestamp;
+				this.active = true;
+				this.blocks.clear();
+				this.fingerprints.clear();
+			}
+			return false;
+		}
+		if (raw.type === "message_end" || raw.type === "agent_end" || raw.type === "agent_settled" || raw.type === "turn_end") {
+			this.active = false;
+			this.blocks.clear();
+			this.fingerprints.clear();
+			return false;
+		}
+		if (!this.active || raw.type !== "message_update") return false;
+		const inner = raw.assistantMessageEvent as Raw | undefined;
+		if (!inner || typeof inner !== "object") return false;
+		const index = inner.contentIndex;
+		if (typeof index !== "number" || !Number.isSafeInteger(index) || index < 0 || index >= ARGUMENT_PROGRESS_MAX) return false;
+		if (inner.type === "toolcall_start") {
+			// Older Pi RPC forwards SDK partial snapshots; current RPC puts the
+			// identity directly on toolcall_start. Neither shape is persisted.
+			const partial = inner.partial as Raw | undefined;
+			const block = Array.isArray(partial?.content) ? partial.content[index] as Raw | undefined : undefined;
+			const id = inner.id ?? (block?.type === "toolCall" ? block.id : undefined);
+			const name = inner.toolName ?? (block?.type === "toolCall" ? block.name : undefined);
+			if (typeof id === "string" && id.length > 0 && typeof name === "string" && name.length > 0 && !this.blocks.has(index)) this.blocks.set(index, true);
+			return false;
+		}
+		if (inner.type === "toolcall_end") {
+			if (this.blocks.has(index)) this.blocks.set(index, false);
+			return false;
+		}
+		if (inner.type !== "toolcall_delta" || this.blocks.get(index) !== true || typeof inner.delta !== "string" || inner.delta.length === 0) return false;
+		if (this.fingerprints.size >= ARGUMENT_PROGRESS_MAX) return false;
+		const fingerprint = createHash("sha256").update(`${index}:`).update(inner.delta).digest("hex");
+		if (this.fingerprints.has(fingerprint)) return false;
+		this.fingerprints.add(fingerprint);
+		return true;
+	}
+}
+
 // One RPC line in, zero or more deltas out. Streaming deltas carry only the
 // chunk; whole-message payloads that pi repeats on every update are ignored.
 export function normalizeRpcEvent(raw: unknown, options: { observeResponses?: boolean } = {}): TaskEvent[] {
@@ -270,6 +343,7 @@ export function normalizeRpcEvent(raw: unknown, options: { observeResponses?: bo
 		case "agent_settled":
 			return [{ type: TASK_EVENT.AGENT_SETTLED }];
 		case "extension_ui_request":
+			if (event.method === "notify" && typeof event.message === "string" && event.message.startsWith(MISSING_TOOLS_NOTE_PREFIX)) return [{ type: TASK_EVENT.NOTE, text: clean(event.message) }];
 			return DIALOG_METHODS.has(String(event.method)) ? [{ type: TASK_EVENT.ASK, request: askRequest(event) }] : [];
 		case "auto_retry_start":
 			return [{ type: TASK_EVENT.NOTE, text: `retrying (${String(event.attempt ?? "?")}/${String(event.maxAttempts ?? "?")})` }];
@@ -400,14 +474,21 @@ export class TaskStore {
 	private readonly listeners = new Map<string, Set<TaskListener>>();
 	private readonly summaryListeners = new Set<SummaryListener>();
 	private readonly limits: Partial<ThreadLimits>;
+	private readonly producerId = randomUUID();
+	private sequence = 0;
+	private readonly runIds = new Map<string, string>();
+	private readonly statusListeners = new Set<StatusChangeListener>();
 
 	constructor(limits: Partial<ThreadLimits> = {}) {
 		this.limits = limits;
 	}
 
 	add(task: TaskRecord): void {
+		const previous = this.tasks.get(task.id)?.status;
+		if (!this.tasks.has(task.id)) this.runIds.set(task.id, randomUUID());
 		this.tasks.set(task.id, task);
 		this.threads.set(task.id, emptyThread(this.limits));
+		this.notifyStatus(task, previous);
 		this.notifySummary();
 	}
 
@@ -416,6 +497,7 @@ export class TaskStore {
 	restore(task: TaskRecord, thread: TaskThread): boolean {
 		if (this.tasks.has(task.id)) return false;
 		this.tasks.set(task.id, task);
+		this.runIds.set(task.id, randomUUID());
 		this.threads.set(task.id, { ...thread, limits: { ...DEFAULT_LIMITS, ...this.limits } });
 		this.notifySummary();
 		return true;
@@ -446,6 +528,7 @@ export class TaskStore {
 		if (!current) return undefined;
 		const next = { ...current, ...patch };
 		this.tasks.set(id, next);
+		this.notifyStatus(next, current.status);
 		this.notifyTask(next);
 		if (next.status !== current.status) this.notifySummary();
 		return next;
@@ -473,6 +556,22 @@ export class TaskStore {
 		return () => this.summaryListeners.delete(listener);
 	}
 
+	/** Optional, content-free observer. Restores and unchanged snapshots are silent. */
+	subscribeStatusChanges(listener: StatusChangeListener): () => void {
+		this.statusListeners.add(listener);
+		return () => { this.statusListeners.delete(listener); };
+	}
+
+	private notifyStatus(task: TaskRecord, previousStatus?: TaskStatus): void {
+		if (task.status === previousStatus) return;
+		const change: TaskStatusChange = Object.freeze({ producerId: this.producerId,
+			sessionId: task.parentSessionId, parentSessionId: task.parentSessionId, taskId: task.id,
+			runId: this.runIds.get(task.id)!, status: task.status, previousStatus, sequence: ++this.sequence });
+		for (const listener of [...this.statusListeners]) {
+			try { void Promise.resolve(listener(change)).catch(() => {}); } catch { /* Observability cannot fail a mutation. */ }
+		}
+	}
+
 	private notifyTask(task: TaskRecord): void {
 		const set = this.listeners.get(task.id);
 		if (!set) return;