pi-crew 0.9.62 → 0.9.65

package/src/config/role-tools.ts

@@ -3,11 +3,17 @@
  * Uses the excludeTools option from pi v0.77.0.
  */
 
+import { permissionForRole } from "../runtime/role-permission.ts";
+
 export interface RoleToolConfig {
 	/** Explicit list of tools to use (if undefined, use all default tools) */
 	tools?: string[];
 	/** Tools to exclude from the default set */
 	excludeTools?: string[];
+	/** Phase 1 scratchpad: opt-in the persistent Bun-free JS evaluator (execute tool)
+	 * for this role. Only effective on WRITE roles — read-only roles are gated
+	 * out by `isScratchpadEnabledForRole` (S-6, privilege-elevation guard). */
+	scratchpad?: boolean;
 }
 
 export const ROLE_TOOL_CONFIGS: Record<string, RoleToolConfig> = {
@@ -44,9 +50,11 @@ export const ROLE_TOOL_CONFIGS: Record<string, RoleToolConfig> = {
 		excludeTools: ["edit", "write", "bash", "web"],
 	},
 
-	// Executor - Full access (default)
+	// Executor - Full access (default). Phase 1 scratchpad-enabled (stateful
+	// evaluator compounds intermediate results across execute calls).
 	executor: {
 		// No restrictions - full tool access
+		scratchpad: true,
 	},
 
 	// Reviewer - Read and review, no write
@@ -78,12 +86,16 @@ export const ROLE_TOOL_CONFIGS: Record<string, RoleToolConfig> = {
 	verifier: {
 		tools: ["read", "grep", "find", "ls", "bash"],
 		excludeTools: ["edit", "write", "web"],
+		// Phase 1 scratchpad: multi-cell test/verify flows reuse parsed state.
+		scratchpad: true,
 	},
 
 	// Test Engineer - Can write tests (F1: hyphenated key)
 	"test-engineer": {
 		tools: ["read", "edit", "write", "bash", "ls"],
 		excludeTools: ["web"],
+		// Phase 1 scratchpad: build/run test suites with state across cells.
+		scratchpad: true,
 	},
 };
 
@@ -116,3 +128,39 @@ export function getRestrictedRoles(): string[] {
 		.filter(([, config]) => config.tools !== undefined || config.excludeTools !== undefined)
 		.map(([role]) => role);
 }
+
+/** Agent frontmatter shape consumed by the scratchpad opt-in check. */
+export interface ScratchpadAgentOption {
+	scratchpad?: boolean;
+}
+
+/**
+ * Phase 1: is the scratchpad (execute tool) enabled for this role/agent?
+ *
+ * Decision order (load-bearing — do not reorder):
+ *  1. S-6 (SECURITY, privilege-elevation guard): read-only roles NEVER enable,
+ *     regardless of any agent frontmatter opt-in. A `scratchpad: true` on a
+ *     read-only role (e.g. security-reviewer, whose tool-set is read/grep/find
+ *     with NO bash) would grant full-trust JS execution (fs/network/env/
+ *     child_process) inside a role designed to have no execution — a real
+ *     elevation. `permissionForRole` is default-deny (unknown → read_only), so
+ *     typos/underscore/case-drift cannot bypass this.
+ *  2. F6 (kill-switch): `agent.scratchpad === false` WINS over the role default,
+ *     giving an emergency off-switch for an experimental full-trust feature.
+ *  3. agent explicit opt-in (`scratchpad: true`) OR role default (`scratchpad:
+ *     true` in ROLE_TOOL_CONFIGS).
+ *
+ * F10: `permissionForRole` and `getToolConfig` both expect HYPHENATED role
+ * strings (runtime convention); a raw underscore role would default-deny
+ * wrongly, so normalize FIRST.
+ */
+export function isScratchpadEnabledForRole(role: string, agent?: ScratchpadAgentOption): boolean {
+	// F10: normalize underscore→hyphen before every downstream lookup.
+	const normalized = role.includes("_") ? role.replaceAll("_", "-") : role;
+	// S-6 (điều kiện tiên quyết): read-only gate trước mọi agent flag.
+	if (permissionForRole(normalized) === "read_only") return false;
+	// F6: explicit-false agent override (kill-switch) wins over role default.
+	if (agent?.scratchpad === false) return false;
+	// agent explicit opt-in OR role default.
+	return agent?.scratchpad === true || getToolConfig(normalized).scratchpad === true;
+}

package/src/observability/event-to-metric.ts

@@ -1,5 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { MetricRegistry } from "./metric-registry.ts";
+import { getCardinalityEvictions } from "./metrics-primitives.ts";
 
 function recordValue(value: unknown): Record<string, unknown> {
 	return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : {};
@@ -41,6 +42,19 @@ export function wireEventToMetrics(events: ExtensionAPI["events"] | undefined, r
 	const deadletterCount = registry.counter("crew.task.deadletter_total", "Deadletter triggers by reason");
 	const overflowCount = registry.counter("crew.task.overflow_phase_total", "Overflow recovery phase transitions");
 	const supervisorContactCount = registry.counter("crew.task.supervisor_contact_total", "Supervisor contact requests by reason");
+	const unboundedConcurrencyCount = registry.counter(
+		"crew.limits.unbounded_total",
+		"Runs that enabled allowUnboundedConcurrency (advisory; bypasses hard cap)",
+	);
+	// Gauge reflecting cumulative label-combination evictions across all
+	// metrics in this process. Updated lazily on every metric event so the
+	// value stays fresh without a separate timer. Non-zero = aggregation
+	// for high-cardinality labels is unreliable. See metrics-primitives.ts
+	// `enforceLabelCap`.
+	const cardinalityEvictedGauge = registry.gauge(
+		"crew.metrics.cardinality_evicted",
+		"Cumulative label-combination evictions (non-zero = unreliable aggregation)",
+	);
 	registry.gauge("crew.heartbeat.staleness_ms", "Heartbeat elapsed since last seen, milliseconds");
 	const runDuration = registry.histogram(
 		"crew.run.duration_ms",
@@ -146,11 +160,26 @@ export function wireEventToMetrics(events: ExtensionAPI["events"] | undefined, r
 				});
 			},
 		],
+		[
+			"crew.limits.unbounded",
+			() => {
+				// Fires when a run enables allowUnboundedConcurrency (bypasses the
+				// hard cap of 8 and the worker cap). One emit per affected run.
+				unboundedConcurrencyCount.inc({});
+			},
+		],
 	];
 
 	const unsubscribers: Array<() => void> = [];
 	for (const [event, handler] of handlers) {
 		const unsubscribe = events?.on?.(event, (data: unknown) => {
+			// Refresh the cardinality-eviction gauge on every event so the
+			// value reflects the latest eviction state without a timer.
+			try {
+				cardinalityEvictedGauge.set({}, getCardinalityEvictions());
+			} catch {
+				/* gauge refresh must never break event delivery */
+			}
 			try {
 				handler(data);
 			} catch {

package/src/observability/metrics-primitives.ts

@@ -36,13 +36,51 @@ interface StoredHistogram {
 
 export const DEFAULT_HISTOGRAM_BUCKETS = [1, 2, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000] as const;
 
-/** Maximum number of unique label combinations per metric. */
+/**
+ * Maximum number of unique label combinations per metric.
+ *
+ * When this cap is reached, the oldest label combination is silently
+ * evicted (FIFO by insertion order, with MRU promotion on use). Read
+ * {@link getCardinalityEvictions} to detect when aggregation has become
+ * unreliable for high-cardinality labels.
+ */
 const MAX_LABEL_COMBINATIONS = 10_000;
 
-function enforceLabelCap(map: Map<string, unknown>, metricName: string): void {
+/**
+ * Cumulative count of label-combination evictions across all metrics in
+ * this process. Incremented every time {@link enforceLabelCap} drops an
+ * entry. Exported so observability wiring and OTLP/Prometheus exporters
+ * can surface `crew.metrics.cardinality_evicted` without risking the
+ * recursion of routing this signal through a `Counter` (a Counter itself
+ * consumes a label slot and could self-evict).
+ */
+let cardinalityEvictions = 0;
+
+/**
+ * Returns the cumulative number of metric label-combination evictions
+ * that have occurred in this process. A non-zero value means at least
+ * one metric exceeded {@link MAX_LABEL_COMBINATIONS} and silently dropped
+ * the oldest label combination — aggregation for high-cardinality labels
+ * is unreliable.
+ */
+export function getCardinalityEvictions(): number {
+	return cardinalityEvictions;
+}
+
+/** Reset the eviction counter. Intended for tests only. */
+export function _resetCardinalityEvictionsForTests(): void {
+	cardinalityEvictions = 0;
+}
+
+function enforceLabelCap(map: Map<string, unknown>, _metricName: string): void {
 	while (map.size > MAX_LABEL_COMBINATIONS) {
 		const firstKey = map.keys().next().value;
-		if (firstKey !== undefined) map.delete(firstKey);
+		if (firstKey !== undefined) {
+			map.delete(firstKey);
+			cardinalityEvictions++;
+		} else {
+			break;
+		}
 	}
 }
 

package/src/prompt/prompt-runtime.ts

@@ -4,6 +4,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { startChildBrokerClient } from "../runtime/broker/crew-broker-child.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import { resolveRealContainedPath } from "../utils/safe-paths.ts";
+import { registerScratchpadLifecycle } from "./scratchpad-lifecycle.ts";
 
 export const PI_TEAMS_INHERIT_PROJECT_CONTEXT_ENV = "PI_TEAMS_INHERIT_PROJECT_CONTEXT";
 export const PI_TEAMS_INHERIT_SKILLS_ENV = "PI_TEAMS_INHERIT_SKILLS";
@@ -377,4 +378,9 @@ export default function registerPiTeamsPromptRuntime(pi: ExtensionAPI): void {
 		if (rewritten === event.systemPrompt) return;
 		return { systemPrompt: rewritten };
 	});
+
+	// ── Phase 1 scratchpad (T6): conditional `execute` tool + EngineManager
+	// lifecycle. Registers nothing when PI_CREW_SCRATCHPAD !== "1" (D3) and
+	// only flushes+kills the engine on session_shutdown reason "quit" (F3).
+	registerScratchpadLifecycle(pi);
 }