gentle-pi 3.6.0 → 4.0.0

package/skills/work-unit-commits/SKILL.md

@@ -30,7 +30,7 @@ Use it for:
 | Keep docs with the user-visible change | Docs belong with the feature or workflow they explain. |
 | Tell a story | A reviewer should understand why each commit exists from its diff and message. |
 | Future PR-ready | Each commit should be a candidate chained PR when the change grows. |
-| SDD workload guard | If SDD tasks forecast a >400-line change, group commits into chained PR slices before implementation. |
+| SDD workload guard | If SDD tasks forecast a >400-line change, honor the selected `delivery_strategy`. On chaining paths only, group commits into chained PR slices before implementation. For explicit `single-pr` or `exception-ok`, keep one PR, report the review load, and follow the destination repository's documented contribution/size policy; selection alone does not accept an exception. |
 | Budget is not code-golf | Never shrink a diff by deleting comments, blank lines, docs, or tests, or by compressing code, to fit the review budget (400 by default, or the session `review_budget_lines`). Slice by work unit or report the overage. |
 
 ## Work Unit Checklist
@@ -67,8 +67,9 @@ When `sdd-tasks` produces a Review Workload Forecast:
 
 - Low risk: keep work-unit commits inside one PR.
 - Medium risk: commit by work unit and monitor changed lines before PR creation.
-- High risk: follow SDD `delivery_strategy` — ask on `ask-on-risk`, auto-slice on `auto-chain`, require `size:exception` on over-budget `single-pr`, or record accepted `size:exception` on `exception-ok`.
-- Splitting is bounded: after one honest slicing pass, if no cohesive work-unit split fits the budget, stop and report the smallest honest count with a `size:exception` recommendation. Do not iterate shrinking the code to reach the number.
+- High risk: follow SDD `delivery_strategy` — ask on `ask-on-risk`, auto-slice with the cached chain choice on `auto-chain`, follow the destination repository's documented contribution/size policy on over-budget `single-pr`, or record an explicitly accepted policy exception on `exception-ok`. A single-PR selection does not itself accept an exception.
+- `size:exception` is a Gentle-owned repository policy, not a universal label requirement. Never request, create, or add the label for generic users unless the destination policy uses it; preserve its maintainer acceptance and protected-label authorization gates.
+- Splitting is bounded: after one honest slicing pass, if no cohesive work-unit split fits the budget, stop and report the smallest honest count and rationale. Recommend an exception only where destination policy provides it. Do not iterate shrinking the code to reach the number.
 
 Each SDD work unit should map cleanly to a commit or PR with:
 

package/tests/agent-profiles.test.ts

@@ -437,6 +437,24 @@ test("normalizeProfilesFile drops an active marker that points nowhere", () => {
 	assert.equal(normalized?.drops.droppedProfiles.length, 0);
 });
 
+test("normalizeProfilesFile accepts effort as alias for thinking in profile entries (#1403)", () => {
+	const normalized = normalizeProfilesFile(
+		JSON.parse(
+			profilesText({
+				hybrid: {
+					"example-agent": { model: "anthropic/claude-sonnet-4", effort: "medium" },
+					"worker": { effort: "high" },
+				},
+			}),
+		),
+	);
+	assert.deepEqual(normalized?.file.profiles.hybrid, {
+		"example-agent": { model: "anthropic/claude-sonnet-4", thinking: "medium" },
+		"worker": { model: undefined, thinking: "high" },
+	});
+	assert.equal(normalized?.drops.droppedAgents.length, 0);
+});
+
 test("bootstrapProfilesFile seeds a current profile, active only when routing is non-empty", () => {
 	const empty = bootstrapProfilesFile({});
 	assert.deepEqual(empty, {

package/tests/agents-fake-child.ts

@@ -9,7 +9,7 @@ export interface FakeChild {
 	child: ChildLike;
 	written: Array<Record<string, unknown>>;
 	emit(event: Record<string, unknown>): void;
-	exit(code: number): void;
+	exit(code: number | null, signal?: string | null): void;
 	fail(message: string): void;
 	killed: string[];
 	sent: Array<Record<string, unknown>>;
@@ -62,5 +62,5 @@ export function fakeChild(options: { exitOnKill?: boolean; pid?: number } = {}):
 			return child;
 		},
 	};
-	return { child, written, killed, sent, get disconnects() { return disconnects; }, message: (event) => emitter.emit("message", event), emit: (event) => stdout.write(`${JSON.stringify(event)}\n`), exit: (code) => emitter.emit("exit", code, null), fail: (message) => emitter.emit("error", new Error(message)) };
+	return { child, written, killed, sent, get disconnects() { return disconnects; }, message: (event) => emitter.emit("message", event), emit: (event) => stdout.write(`${JSON.stringify(event)}\n`), exit: (code, signal = null) => emitter.emit("exit", code, signal), fail: (message) => emitter.emit("error", new Error(message)) };
 }

package/tests/agents-message-delivery.test.ts

@@ -0,0 +1,106 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createAgentMessageQueue, STALE_NOTIFICATION_MS } from "../lib/agents-message-delivery.ts";
+
+test("delivers live notifications and queries in order for the active session", () => {
+	const queue = createAgentMessageQueue();
+	queue.enqueueNotification({ id: "task-1", agent: "scout", parentSessionId: "s1" }, "First progress", 1000);
+	queue.enqueueQuery({ id: "task-1", agent: "scout", parentSessionId: "s1" }, "q1", "Which branch?", 1050);
+
+	assert.equal(queue.pendingCount(), 2);
+	const deliverable = queue.takeDeliverable(1100, "s1", () => true);
+	assert.equal(deliverable.length, 2);
+
+	assert.equal(deliverable[0]?.kind, "notification");
+	assert.equal(deliverable[0]?.content, "First progress");
+	assert.equal(deliverable[0]?.display, false);
+
+	assert.equal(deliverable[1]?.kind, "query");
+	assert.match(deliverable[1]?.content ?? "", /Which branch\?/);
+	assert.equal(deliverable[1]?.display, true);
+	assert.equal(deliverable[1]?.requestId, "q1");
+
+	assert.equal(queue.pendingCount(), 0);
+	assert.equal(queue.takeDeliverable(1200, "s1", () => true).length, 0, "messages are delivered at most once");
+});
+
+test("a notification from a task that settled before delivery is dropped silently", () => {
+	const queue = createAgentMessageQueue();
+	queue.enqueueNotification({ id: "task-1", agent: "scout", parentSessionId: "s1" }, "Late notice", 1000);
+
+	// The task finishes and is invalidated before the parent turn boundary.
+	queue.invalidateTask("task-1");
+
+	const deliverable = queue.takeDeliverable(1050, "s1", () => false);
+	assert.equal(deliverable.length, 0, "notification from settled task must never enter conversation");
+});
+
+test("an answered query is consumed and never delivered", () => {
+	const queue = createAgentMessageQueue();
+	queue.enqueueQuery({ id: "task-1", agent: "scout", parentSessionId: "s1" }, "q1", "Which target?", 1000);
+
+	// Parent replies before queue flush.
+	queue.consumeQuery("task-1", "q1");
+
+	const deliverable = queue.takeDeliverable(1050, "s1", () => true);
+	assert.equal(deliverable.length, 0, "answered query must not be delivered");
+});
+
+test("an expired query is dropped and never delivered", () => {
+	const queue = createAgentMessageQueue();
+	queue.enqueueQuery({ id: "task-1", agent: "scout", parentSessionId: "s1" }, "q1", "Need approval", 1000);
+
+	// Query times out.
+	queue.expireQuery("task-1", "q1");
+
+	const deliverable = queue.takeDeliverable(1050, "s1", () => true);
+	assert.equal(deliverable.length, 0, "expired query must not be delivered");
+});
+
+test("a notification exceeding the stale window is dropped", () => {
+	const queue = createAgentMessageQueue();
+	queue.enqueueNotification({ id: "task-1", agent: "scout", parentSessionId: "s1" }, "Slow notice", 1000);
+
+	// Held past the 90-second threshold.
+	const deliverable = queue.takeDeliverable(1000 + STALE_NOTIFICATION_MS + 10, "s1", () => true);
+	assert.equal(deliverable.length, 0, "stale notification must not be delivered");
+});
+
+test("isTaskLive returning false drops messages for non-live tasks", () => {
+	const queue = createAgentMessageQueue();
+	queue.enqueueNotification({ id: "task-1", agent: "scout", parentSessionId: "s1" }, "Dead task notice", 1000);
+	queue.enqueueQuery({ id: "task-1", agent: "scout", parentSessionId: "s1" }, "q1", "Dead task query", 1000);
+
+	const deliverable = queue.takeDeliverable(1050, "s1", (id) => id !== "task-1");
+	assert.equal(deliverable.length, 0, "non-live task messages must be dropped");
+});
+
+test("session mismatch drops foreign session messages", () => {
+	const queue = createAgentMessageQueue();
+	queue.enqueueNotification({ id: "task-1", agent: "scout", parentSessionId: "session-old" }, "Old session notice", 1000);
+
+	const deliverable = queue.takeDeliverable(1050, "session-new", () => true);
+	assert.equal(deliverable.length, 0, "foreign session message must be dropped");
+});
+
+test("deduplicates identical query requests for the same task and requestId", () => {
+	const queue = createAgentMessageQueue();
+	queue.enqueueQuery({ id: "task-1", agent: "scout", parentSessionId: "s1" }, "q1", "First ask", 1000);
+	queue.enqueueQuery({ id: "task-1", agent: "scout", parentSessionId: "s1" }, "q1", "Duplicate ask", 1001);
+
+	assert.equal(queue.pendingCount(), 1);
+	const deliverable = queue.takeDeliverable(1050, "s1", () => true);
+	assert.equal(deliverable.length, 1);
+	assert.match(deliverable[0]!.content, /First ask/);
+});
+
+test("dropAll clears everything across session reset", () => {
+	const queue = createAgentMessageQueue();
+	queue.enqueueNotification({ id: "task-1", agent: "scout", parentSessionId: "s1" }, "Notice", 1000);
+	queue.enqueueQuery({ id: "task-1", agent: "scout", parentSessionId: "s1" }, "q1", "Query", 1000);
+	assert.equal(queue.pendingCount(), 2);
+
+	queue.dropAll();
+	assert.equal(queue.pendingCount(), 0);
+	assert.equal(queue.takeDeliverable(1050, "s1", () => true).length, 0);
+});

package/tests/agents-protocol.test.ts

@@ -4,6 +4,7 @@ import {
 	applyTaskEvent,
 	emptyThread,
 	normalizeRpcEvent,
+	ToolArgumentProgress,
 	TASK_EVENT,
 	TASK_STATUS,
 	taskLabel,
@@ -67,6 +68,45 @@ test("normalizeRpcEvent maps pi RPC events to task deltas and ignores the rest",
 	assert.deepEqual(normalizeRpcEvent("garbage"), []);
 });
 
+test("argument liveness accepts current and legacy Pi starts without display or usage deltas", () => {
+	for (const start of [{ type: "toolcall_start", contentIndex: 0, id: "c1", toolName: "write" },
+		{ type: "toolcall_start", contentIndex: 0, partial: { content: [{ type: "toolCall", id: "c1", name: "write", arguments: {} }] } }]) {
+		const progress = new ToolArgumentProgress();
+		const update = (inner: Record<string, unknown>) => ({ type: "message_update", assistantMessageEvent: inner });
+		const delta = update({ type: "toolcall_delta", contentIndex: 0, delta: "private" });
+		assert.equal(progress.observe(delta), false, "no active generation");
+		progress.observe({ type: "message_start", message: { role: "assistant", timestamp: 1 } });
+		assert.equal(progress.observe(delta), false, "no announced block");
+		assert.equal(progress.observe(update(start)), false, "announcement alone is not progress");
+		assert.equal(progress.observe(delta), true);
+		assert.equal(progress.observe(delta), false);
+		assert.deepEqual(normalizeRpcEvent(delta), [], "no arguments in display events or provisional totals");
+		progress.observe(update({ type: "toolcall_end", contentIndex: 0 }));
+		assert.equal(progress.observe(update({ type: "toolcall_delta", contentIndex: 0, delta: "late" })), false);
+		progress.observe(update(start));
+		assert.equal(progress.observe(delta), false, "a closed block cannot be reopened");
+	}
+});
+
+test("argument liveness fails closed on malformed starts, stale generations and fingerprint exhaustion", () => {
+	const progress = new ToolArgumentProgress();
+	const update = (inner: Record<string, unknown>) => ({ type: "message_update", assistantMessageEvent: inner });
+	for (const timestamp of [undefined, "1", -1, 1.5]) progress.observe({ type: "message_start", message: { role: "assistant", timestamp } });
+	assert.equal(progress.observe(update({ type: "toolcall_delta", contentIndex: 0, delta: "x" })), false);
+	progress.observe({ type: "message_start", message: { role: "assistant", timestamp: 1 } });
+	for (const fields of [{ id: 1, toolName: "write" }, { id: "c", toolName: "" }, { partial: null }]) {
+		progress.observe(update({ type: "toolcall_start", contentIndex: 0, ...fields }));
+		assert.equal(progress.observe(update({ type: "toolcall_delta", contentIndex: 0, delta: "x" })), false);
+	}
+	progress.observe(update({ type: "toolcall_start", contentIndex: 0, id: "c", toolName: "write" }));
+	for (let index = 0; index < 4096; index++) assert.equal(progress.observe(update({ type: "toolcall_delta", contentIndex: 0, delta: String(index) })), true);
+	assert.equal(progress.observe(update({ type: "toolcall_delta", contentIndex: 0, delta: "over-cap" })), false);
+	progress.observe({ type: "message_end" });
+	progress.observe({ type: "message_start", message: { role: "assistant", timestamp: 1 } });
+	progress.observe(update({ type: "toolcall_start", contentIndex: 0, id: "c", toolName: "write" }));
+	assert.equal(progress.observe(update({ type: "toolcall_delta", contentIndex: 0, delta: "stale" })), false);
+});
+
 test("response observations are opt-in, finalized, field-specific and content-free", () => {
 	const message = { role: "assistant", provider: "openai", model: "gpt-4o", responseModel: "gpt-4o-2024-08-06",
 		providerThinkingLevel: "high", stopReason: "stop", content: [{ type: "text", text: "private response" }],