@gajae-code/coding-agent 0.4.1 → 0.4.3

package/src/modes/shared/agent-wire/event-observation.ts

@@ -0,0 +1,397 @@
+/**
+ * Canonical AgentSession event observation: the single semantic mapping from
+ * `AgentSessionEvent` (and non-event wire frames) to bounded owner observations.
+ *
+ * This is the one place that derives `AgentWireOwnerObservation`s. Harness (and
+ * any other owner control plane) consumes these instead of re-parsing the wire
+ * protocol with private knowledge.
+ *
+ * Hard rule: evidence is BOUNDED — only ids, names, categories, statuses,
+ * cursors, timestamps, and short codes/messages. Never assistant text, message
+ * deltas, command output, raw args, or raw tool results.
+ */
+import type { AgentSessionEvent } from "../../../session/agent-session";
+import type { AgentWireEventPayload, AgentWireOwnerObservation } from "./event-contract";
+import { toAgentWireEventPayload } from "./event-envelope";
+
+const TEST_RE = /\b(bun test|npm test|yarn test|pnpm test|jest|vitest|pytest|go test|cargo test|mocha|ava)\b/i;
+const TOOL_STATUS_CODES = new Set([
+	"aborted",
+	"blocked",
+	"cancelled",
+	"complete",
+	"completed",
+	"error",
+	"failed",
+	"ok",
+	"pending",
+	"running",
+	"skipped",
+	"success",
+	"timeout",
+]);
+
+/** True when a tool name or command indicates a test-runner invocation. */
+export function isTestRunnerTool(toolName?: unknown, command?: unknown): boolean {
+	const name = typeof toolName === "string" ? toolName : "";
+	const cmd = typeof command === "string" ? command : "";
+	if (/test/i.test(name) && name !== "edit" && name !== "read") return true;
+	return TEST_RE.test(cmd);
+}
+
+function str(v: unknown): string | undefined {
+	return typeof v === "string" ? v : undefined;
+}
+function num(v: unknown): number | undefined {
+	return typeof v === "number" ? v : undefined;
+}
+/** Only accept a known closed-vocabulary tool status; reject arbitrary strings. */
+export function boundedStatus(v: unknown): string | undefined {
+	if (typeof v !== "string") return undefined;
+	const status = v.trim().toLowerCase();
+	return TOOL_STATUS_CODES.has(status) ? status : undefined;
+}
+/** Accept only identifier-shaped tokens (e.g. RPC command names); reject free text. */
+export function boundedToken(v: unknown): string | undefined {
+	if (typeof v !== "string") return undefined;
+	return /^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(v) ? v : undefined;
+}
+function recordObject(v: unknown): Record<string, unknown> | undefined {
+	return v && typeof v === "object" && !Array.isArray(v) ? (v as Record<string, unknown>) : undefined;
+}
+function idOf(v: unknown): string | null {
+	const record = recordObject(v);
+	return str(record?.id) ?? null;
+}
+/** Extract a bounded tool command for test detection only — never persisted. */
+function toolCommand(args: unknown): string | undefined {
+	const record = recordObject(args);
+	const c = record?.command ?? record?.cmd ?? record?.commandLine;
+	return typeof c === "string" ? c : undefined;
+}
+/** Derive a bounded tool status from a result/partialResult/isError shape. */
+function resultStatus(result: unknown, isError?: boolean): string | undefined {
+	if (isError === true) return "error";
+	const record = recordObject(result);
+	if (!record) return undefined;
+	if (record.isError === true) return "error";
+	return boundedStatus(record.status) ?? boundedStatus(recordObject(record.details)?.status);
+}
+
+function obs(
+	event: AgentSessionEvent,
+	partial: Omit<AgentWireOwnerObservation, "eventType">,
+): AgentWireOwnerObservation {
+	return { eventType: event.type, ...partial };
+}
+
+/**
+ * Map a single `AgentSessionEvent` to its bounded owner observation, or null
+ * when the event carries no owner-facing signal.
+ */
+export function observeAgentSessionEvent(event: AgentSessionEvent): AgentWireOwnerObservation | null {
+	switch (event.type) {
+		case "agent_start":
+			return obs(event, {
+				kind: "rpc_agent_started",
+				signal: "SessionStart",
+				evidence: {},
+				severity: "info",
+				semantic: true,
+				coalesceKey: null,
+			});
+		case "turn_start":
+			return obs(event, {
+				kind: "rpc_turn_started",
+				signal: "prompt-accepted",
+				evidence: {},
+				severity: "info",
+				semantic: true,
+				coalesceKey: null,
+			});
+		case "turn_end":
+			return obs(event, {
+				kind: "rpc_turn_ended",
+				signal: null,
+				evidence: {},
+				severity: "info",
+				semantic: false,
+				coalesceKey: null,
+			});
+		case "message_start":
+		case "message_update":
+		case "message_end": {
+			const messageId = idOf(event.message);
+			return obs(event, {
+				kind: "rpc_message_activity",
+				signal: null,
+				evidence: { phase: event.type, messageId },
+				severity: "info",
+				semantic: false,
+				coalesceKey: `message:${messageId ?? "msg"}`,
+			});
+		}
+		case "tool_execution_start": {
+			const test = isTestRunnerTool(event.toolName, toolCommand(event.args));
+			return obs(event, {
+				kind: "rpc_tool_started",
+				signal: test ? "test-running" : "tool-call",
+				evidence: { toolId: str(event.toolCallId) ?? null, toolName: str(event.toolName) ?? null },
+				severity: "info",
+				semantic: true,
+				coalesceKey: null,
+			});
+		}
+		case "tool_execution_update": {
+			const test = isTestRunnerTool(event.toolName, toolCommand(event.args));
+			return obs(event, {
+				kind: "rpc_tool_updated",
+				signal: test ? "test-running" : null,
+				evidence: { toolId: str(event.toolCallId) ?? null, status: resultStatus(event.partialResult) ?? null },
+				severity: "info",
+				semantic: false,
+				coalesceKey: `tool:${str(event.toolCallId) ?? "tool"}`,
+			});
+		}
+		case "tool_execution_end": {
+			const test = isTestRunnerTool(event.toolName);
+			const status = resultStatus(event.result, event.isError);
+			return obs(event, {
+				kind: "rpc_tool_ended",
+				signal: test ? "test-running" : "tool-call",
+				evidence: {
+					toolId: str(event.toolCallId) ?? null,
+					toolName: str(event.toolName) ?? null,
+					status: status ?? null,
+				},
+				severity: status === "error" ? "warn" : "info",
+				semantic: true,
+				coalesceKey: null,
+			});
+		}
+		case "auto_compaction_start":
+		case "auto_compaction_end":
+			return obs(event, {
+				kind: "rpc_compaction",
+				signal: null,
+				evidence: { phase: event.type },
+				severity: "info",
+				semantic: false,
+				coalesceKey: null,
+			});
+		case "auto_retry_start":
+			return obs(event, {
+				kind: "rpc_retry",
+				signal: null,
+				evidence: { phase: event.type, attempt: num(event.attempt) ?? null },
+				severity: "warn",
+				semantic: false,
+				coalesceKey: null,
+			});
+		case "auto_retry_end":
+			return obs(event, {
+				kind: "rpc_retry",
+				signal: null,
+				evidence: { phase: event.type, success: event.success === true },
+				severity: "warn",
+				semantic: false,
+				coalesceKey: null,
+			});
+		case "retry_fallback_applied":
+		case "retry_fallback_succeeded":
+			return obs(event, {
+				kind: "rpc_retry_fallback",
+				signal: null,
+				evidence: { phase: event.type, role: str(event.role) ?? null },
+				severity: "warn",
+				semantic: false,
+				coalesceKey: null,
+			});
+		case "ttsr_triggered":
+			return obs(event, {
+				kind: "rpc_ttsr",
+				signal: "error",
+				evidence: { ruleCount: Array.isArray(event.rules) ? event.rules.length : 0 },
+				severity: "warn",
+				semantic: true,
+				coalesceKey: null,
+			});
+		case "todo_reminder":
+		case "todo_auto_clear":
+			return obs(event, {
+				kind: "rpc_todo",
+				signal: null,
+				evidence: { phase: event.type },
+				severity: "info",
+				semantic: false,
+				coalesceKey: null,
+			});
+		case "irc_message":
+			return obs(event, {
+				kind: "rpc_irc",
+				signal: null,
+				evidence: {},
+				severity: "info",
+				semantic: false,
+				coalesceKey: null,
+			});
+		case "notice": {
+			const level = event.level;
+			return obs(event, {
+				kind: "rpc_notice",
+				signal: level === "error" ? "error" : null,
+				evidence: { level },
+				severity: level === "info" ? "info" : "warn",
+				semantic: level === "error",
+				coalesceKey: null,
+			});
+		}
+		case "thinking_level_changed":
+			return obs(event, {
+				kind: "rpc_thinking",
+				signal: null,
+				evidence: { thinkingLevel: str(event.thinkingLevel) ?? null },
+				severity: "info",
+				semantic: false,
+				coalesceKey: null,
+			});
+		case "goal_updated":
+			return obs(event, {
+				kind: "rpc_goal",
+				signal: null,
+				evidence: { hasGoal: event.goal != null },
+				severity: "info",
+				semantic: false,
+				coalesceKey: null,
+			});
+		case "agent_end":
+			return obs(event, {
+				kind: "rpc_agent_completed",
+				signal: "completed",
+				evidence: { stopReason: str(event.stopReason) ?? "completed" },
+				severity: "info",
+				semantic: true,
+				coalesceKey: null,
+			});
+		default:
+			return assertNeverEvent(event);
+	}
+}
+
+function assertNeverEvent(event: never): null {
+	void (event as AgentSessionEvent);
+	return null;
+}
+
+/** Build the rich event payload (renderer-facing) for an `AgentSessionEvent`. */
+export { toAgentWireEventPayload };
+
+/** Observe the bounded owner signal carried by a rich event payload. */
+export function observeAgentWireEventPayload(payload: AgentWireEventPayload): AgentWireOwnerObservation | null {
+	return observeAgentSessionEvent(payload.event);
+}
+
+function ownerFrame(
+	frameType: string,
+	partial: Omit<AgentWireOwnerObservation, "frameType">,
+): AgentWireOwnerObservation {
+	return { frameType, ...partial };
+}
+
+/**
+ * Map a single outbound RPC wire frame (docs/rpc.md) to a bounded owner
+ * observation, or null when the frame carries no owner-facing signal. Event
+ * frames delegate to {@link observeAgentWireEventPayload}; non-event frames are
+ * mapped here so owners never re-parse protocol semantics privately.
+ */
+export function observeRpcOutboundFrame(frame: Record<string, unknown>): AgentWireOwnerObservation | null {
+	const type = str(frame.type);
+	if (!type || type === "ready") return null;
+
+	switch (type) {
+		case "response": {
+			if (frame.success === false) {
+				const error = recordObject(frame.error);
+				return ownerFrame(type, {
+					kind: "rpc_response_failed",
+					signal: "error",
+					evidence: {
+						command: boundedToken(frame.command) ?? null,
+						id: boundedToken(frame.id) ?? null,
+						code: boundedToken(error?.code) ?? null,
+					},
+					severity: "warn",
+					semantic: false,
+					coalesceKey: null,
+				});
+			}
+			return null;
+		}
+		case "event": {
+			const payload = recordObject(frame.payload);
+			const event = recordObject(payload?.event);
+			if (!event) return null;
+			return observeAgentSessionEvent(event as unknown as AgentSessionEvent);
+		}
+		case "workflow_gate":
+			return ownerFrame(type, {
+				kind: "rpc_workflow_gate",
+				signal: null,
+				evidence: {
+					gate_id: str(frame.gate_id) ?? null,
+					kind: str(frame.kind) ?? null,
+					stage: str(frame.stage) ?? null,
+				},
+				severity: "info",
+				semantic: true,
+				coalesceKey: null,
+			});
+		case "extension_ui_request":
+			return ownerFrame(type, {
+				kind: "rpc_extension_request",
+				signal: "tool-call",
+				evidence: { id: str(frame.id) ?? null, method: str(frame.method) ?? null },
+				severity: "info",
+				semantic: false,
+				coalesceKey: null,
+			});
+		case "extension_error":
+			return ownerFrame(type, {
+				kind: "rpc_extension_error",
+				signal: "error",
+				evidence: {
+					extensionPath: str(frame.extensionPath) ?? null,
+					event: boundedToken(frame.event) ?? null,
+				},
+				severity: "critical",
+				semantic: true,
+				coalesceKey: null,
+			});
+		case "host_tool_call":
+		case "host_tool_cancel":
+			return ownerFrame(type, {
+				kind: type === "host_tool_cancel" ? "rpc_host_tool_cancel" : "rpc_host_tool_call",
+				signal: "tool-call",
+				evidence: { id: str(frame.id) ?? null, toolName: str(frame.toolName) ?? null },
+				severity: "info",
+				semantic: false,
+				coalesceKey: null,
+			});
+		case "host_uri_request":
+		case "host_uri_cancel":
+			return ownerFrame(type, {
+				kind: type === "host_uri_cancel" ? "rpc_host_uri_cancel" : "rpc_host_uri_request",
+				signal: "tool-call",
+				evidence: {
+					id: str(frame.id) ?? null,
+					operation: str(frame.operation) ?? null,
+					scheme: str(frame.scheme) ?? null,
+				},
+				severity: "info",
+				semantic: false,
+				coalesceKey: null,
+			});
+		default:
+			return null;
+	}
+}

package/src/modes/shared/agent-wire/protocol.ts

@@ -1,100 +1,43 @@
 /**
  * Shared agent-wire protocol primitives for GJC bridge surfaces.
  *
- * This module is the transport-agnostic, versioned frame contract that the
- * RPC mode and the (in-progress) `--mode bridge` wiring site both build on.
- * It carries the SEMANTIC agent surface — events, responses, and UI/permission
- * requests — never pixels. See `.gjc/specs/deep-interview-gjc-backend-bridge.md`
- * and `.gjc/plans/ralplan/gjc-backend-bridge/pending-approval.md`.
+ * The canonical event/frame contract now lives in `event-contract.ts`. This
+ * module re-exports it under the historical `Bridge*` names so existing RPC and
+ * Bridge code keeps compiling while the adapters migrate to the canonical
+ * `AgentWire*` names. See `.gjc/specs/deep-interview-reconcile-rpc-adapters.md`.
  */
-import type { AgentSessionEvent } from "../../../session/agent-session";
+import type {
+	AgentWireEventFrame,
+	AgentWireEventPayload,
+	AgentWireEventType,
+	AgentWireFrameEnvelope,
+	AgentWireFrameType,
+} from "./event-contract";
+import { AGENT_WIRE_EVENT_TYPES, AGENT_WIRE_PROTOCOL_VERSION } from "./event-contract";
 
 /** Wire protocol version. Bump on breaking envelope/semantic changes. */
-export const BRIDGE_PROTOCOL_VERSION = 1 as const;
+export const BRIDGE_PROTOCOL_VERSION = AGENT_WIRE_PROTOCOL_VERSION;
 
 /** The discriminant of every `AgentSessionEvent` the agent can emit. */
-export type AgentSessionEventType = AgentSessionEvent["type"];
-
-/**
- * Compile-time exhaustive registry of every `AgentSessionEvent` variant.
- *
- * Adding a new variant to `AgentSessionEvent` without registering it here is a
- * type error. This keeps the bridge wire surface in lockstep with the agent
- * event union — the "event/element drift → silent incompleteness" mitigation
- * from the plan's pre-mortem.
- */
-const AGENT_SESSION_EVENT_TYPE_REGISTRY: Record<AgentSessionEventType, true> = {
-	agent_start: true,
-	agent_end: true,
-	turn_start: true,
-	turn_end: true,
-	message_start: true,
-	message_update: true,
-	message_end: true,
-	tool_execution_start: true,
-	tool_execution_update: true,
-	tool_execution_end: true,
-	auto_compaction_start: true,
-	auto_compaction_end: true,
-	auto_retry_start: true,
-	auto_retry_end: true,
-	retry_fallback_applied: true,
-	retry_fallback_succeeded: true,
-	ttsr_triggered: true,
-	todo_reminder: true,
-	todo_auto_clear: true,
-	irc_message: true,
-	notice: true,
-	thinking_level_changed: true,
-	goal_updated: true,
-};
+export type AgentSessionEventType = AgentWireEventType;
 
 /** Every agent-session event type, derived from the exhaustive registry. */
-export const AGENT_SESSION_EVENT_TYPES: readonly AgentSessionEventType[] = Object.keys(
-	AGENT_SESSION_EVENT_TYPE_REGISTRY,
-) as AgentSessionEventType[];
+export const AGENT_SESSION_EVENT_TYPES: readonly AgentSessionEventType[] = AGENT_WIRE_EVENT_TYPES;
 
 /** Top-level frame categories carried over any bridge transport. */
-export type BridgeFrameType =
-	| "ready"
-	| "event"
-	| "response"
-	| "ui_request"
-	| "permission_request"
-	| "host_tool_call"
-	| "host_uri_request"
-	| "reset"
-	| "workflow_gate"
-	| "error";
+export type BridgeFrameType = AgentWireFrameType;
 
-/**
- * Universal frame envelope. Every frame on every transport carries these
- * fields so clients can order (`seq`), resume (`seq` cursor), and correlate
- * request/response pairs (`correlation_id`). `session_id` is present from v1
- * even though v1 runs one session per process, so in-process multiplexing is
- * an additive, non-breaking change later.
- */
-export interface BridgeFrameEnvelope<TType extends BridgeFrameType = BridgeFrameType, TPayload = unknown> {
-	protocol_version: typeof BRIDGE_PROTOCOL_VERSION;
-	session_id: string;
-	/** Monotonic per-session sequence number, starting at 1. */
-	seq: number;
-	/** Unique id for this frame. */
-	frame_id: string;
-	/** Ties a request frame to its response frame, when applicable. */
-	correlation_id?: string;
-	type: TType;
-	payload: TPayload;
-}
+/** Universal frame envelope. See {@link AgentWireFrameEnvelope}. */
+export type BridgeFrameEnvelope<
+	TType extends BridgeFrameType = BridgeFrameType,
+	TPayload = unknown,
+> = AgentWireFrameEnvelope<TType, TPayload>;
 
-/** Payload carried by an `event` frame. */
-export interface BridgeEventPayload {
-	event_type: AgentSessionEventType;
-	event: AgentSessionEvent;
-}
+/** Payload carried by an `event` frame. See {@link AgentWireEventPayload}. */
+export type BridgeEventPayload = AgentWireEventPayload;
 
 /** An `AgentSessionEvent` serialized into a versioned wire frame. */
-export type BridgeEventFrame = BridgeFrameEnvelope<"event", BridgeEventPayload>;
+export type BridgeEventFrame = AgentWireEventFrame;
 
 /** A `workflow_gate` event serialized into a versioned wire frame (#321). */
 export type BridgeWorkflowGateFrame = BridgeFrameEnvelope<

package/src/modes/utils/context-usage.ts

@@ -197,14 +197,14 @@ export function computeContextBreakdown(
 	if (contextWindow > 0) {
 		const compactionSettings = session.settings.getGroup("compaction") as CompactionSettings;
 		if (compactionSettings.enabled && compactionSettings.strategy !== "off") {
-			const threshold = resolveThresholdTokens(contextWindow, compactionSettings);
+			const threshold = resolveThresholdTokens(contextWindow, compactionSettings, model?.maxTokens ?? 0);
 			autoCompactBufferTokens = Math.max(0, contextWindow - threshold);
 		} else {
 			autoCompactBufferTokens = 0;
 		}
 		// Even when fully disabled, fall back to a sensible reserve floor for display.
 		if (autoCompactBufferTokens === 0 && compactionSettings.enabled) {
-			autoCompactBufferTokens = effectiveReserveTokens(contextWindow, compactionSettings);
+			autoCompactBufferTokens = effectiveReserveTokens(contextWindow, compactionSettings, model?.maxTokens ?? 0);
 		}
 	}
 	autoCompactBufferTokens = Math.min(autoCompactBufferTokens, Math.max(0, contextWindow - usedTokens));

package/src/prompts/agents/explore.md

@@ -2,7 +2,7 @@
 name: explore
 description: Fast read-only codebase scout returning compressed context for handoff
 tools: read, search, find, web_search
-model: pi/smol
+model: pi/default
 thinking-level: med
 output:
   properties:

package/src/prompts/agents/plan.md

@@ -3,7 +3,7 @@ name: plan
 description: Software architect for complex multi-file architectural decisions. NOT for simple tasks, single-file changes, or tasks completable in <5 tool calls.
 tools: read, search, find, bash, lsp, web_search, ast_grep
 spawns: explore
-model: pi/plan, pi/slow
+model: pi/default
 thinking-level: high
 hide: true
 ---

package/src/prompts/agents/reviewer.md

@@ -3,7 +3,7 @@ name: reviewer
 description: "Code review specialist for quality/security analysis"
 tools: read, search, find, bash, lsp, web_search, ast_grep, report_finding
 spawns: explore
-model: pi/slow
+model: pi/default
 thinking-level: high
 blocking: true
 output:

package/src/prompts/tools/browser.md

@@ -2,10 +2,11 @@ Drives a real Chromium tab with full puppeteer access via JS execution.
 
 <instruction>
 - For static web content (articles, docs, issues/PRs, JSON, PDFs, feeds), prefer the `read` tool with a URL — reader-mode text without spinning up a browser. Use this tool when you need JS execution, authentication, or interactive actions.
-- Three actions only:
+- Four actions:
   - `open` — acquire (or reuse) a named tab. `name` defaults to `"main"`. Optional `url` navigates after the tab is ready. Optional `viewport` sets dimensions. Optional `dialogs: "accept" | "dismiss"` auto-handles `alert`/`confirm`/`beforeunload` so navigation/clicks don't hang (default: leave dialogs unhandled — page hangs until caller wires `page.on('dialog', …)`).
   - `close` — release a tab by `name`, or every tab with `all: true`. For spawned-app browsers, set `kill: true` to terminate the process tree (default leaves it running).
   - `run` — execute JS against an existing tab. `code` is the body of an async function with `page`, `browser`, `tab`, `display`, `assert`, `wait` in scope. The function's return value is JSON-stringified into the tool result; multiple `display(value)` calls accumulate text/images.
+  - `act` — run a list of structured `actions` against an existing tab without writing JS (preferred for routine navigation/interaction). Each step is `{ verb, … }`; verbs: `navigate {url, wait_until?}`, `click {id|selector}`, `type {id|selector, text}`, `fill {selector, value}`, `select {selector, values}`, `press {key, selector?}`, `scroll {dx?, dy?}`, `back`, `wait {selector?|ms?}`, `observe {viewport_only?, include_all?}`, `extract {format?}`, `screenshot`. Address elements by the numeric `id` from a prior `observe` (preferred) or a selector. Steps run in order; the tool returns an array of per-step results (observations/extracted content included). Use `run` only when a verb does not cover what you need.
 - Tabs survive across `run` calls and across in-process subagents. Open once, reuse many times.
 - Browser kinds, selected by the `app` field on `open`:
   - default (no `app`) → headless Chromium with stealth patches.
@@ -32,7 +33,7 @@ Drives a real Chromium tab with full puppeteer access via JS execution.
 </instruction>
 
 <critical>
-- You MUST call `open` before `run`. `run` does not implicitly create a tab.
+- You MUST call `open` before `run` or `act`. Neither implicitly creates a tab.
 - You NEVER screenshot just to "see what's on the page" — `tab.observe()` returns structured data with element ids you can act on immediately.
 - After a `tab.goto()` or any navigation, prior element ids from `tab.observe()` are invalidated. Re-observe before referencing them.
 - `code` runs with full Node access. Treat it as your code, not sandboxed code.