@gajae-code/coding-agent 0.4.2 → 0.4.4

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

@@ -0,0 +1,147 @@
+/**
+ * Canonical agent-wire contract: the single transport-neutral source of truth
+ * for AgentSession events and bounded owner observations.
+ *
+ * Two distinct consumer-facing shapes, deliberately NOT collapsed into one:
+ * - `AgentWireEventPayload`: rich, full `AgentSessionEvent` for renderers
+ *   (ACP SDK notifications, RPC/Bridge event frames).
+ * - `AgentWireOwnerObservation`: bounded/redacted owner evidence for control
+ *   planes (Harness). Never carries assistant text, message deltas, raw tool
+ *   args, raw command output, raw tool results, answers, or oversize strings.
+ *
+ * The exhaustive `AGENT_SESSION_EVENT_TYPE_REGISTRY` lives here so that adding
+ * an `AgentSessionEvent` variant fails typecheck until it is registered, and so
+ * conformance tests can assert fixture coverage equals the registry exactly.
+ */
+import type { AgentSessionEvent } from "../../../session/agent-session";
+
+/** Wire protocol version. Bump on breaking envelope/semantic changes. */
+export const AGENT_WIRE_PROTOCOL_VERSION = 2 as const;
+export type AgentWireProtocolVersion = typeof AGENT_WIRE_PROTOCOL_VERSION;
+
+/** The discriminant of every `AgentSessionEvent` the agent can emit. */
+export type AgentWireEventType = AgentSessionEvent["type"];
+
+/**
+ * Compile-time exhaustive registry of every `AgentSessionEvent` variant. The
+ * `Record<AgentWireEventType, true>` shape forces every member to be present:
+ * a new union variant is a type error until added here, and a removed variant
+ * is a type error until deleted.
+ */
+const AGENT_SESSION_EVENT_TYPE_REGISTRY: Record<AgentWireEventType, 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,
+};
+
+/** Every agent-session event type, derived from the exhaustive registry. */
+export const AGENT_WIRE_EVENT_TYPES: readonly AgentWireEventType[] = Object.keys(
+	AGENT_SESSION_EVENT_TYPE_REGISTRY,
+) as AgentWireEventType[];
+
+/**
+ * Rich event payload. Carries the full `AgentSessionEvent` so renderers (ACP,
+ * RPC, Bridge) can present message content, tool args/results, todo state, etc.
+ */
+export interface AgentWireEventPayload {
+	event_type: AgentWireEventType;
+	event: AgentSessionEvent;
+}
+
+/**
+ * Bounded observed-signal vocabulary surfaced to owner control planes. Mirrors
+ * the Harness `ObservedSignal` set; the Harness type aliases this in a later
+ * step so there is a single source of truth.
+ */
+export type AgentWireObservedSignal =
+	| "SessionStart"
+	| "prompt-accepted"
+	| "tool-call"
+	| "test-running"
+	| "commit-created"
+	| "completed"
+	| "error"
+	| "streaming"
+	| "idle";
+
+export type AgentWireSeverity = "info" | "warn" | "critical";
+
+/**
+ * Bounded, redacted owner observation. Evidence may include ids, names,
+ * categories, statuses, cursors, timestamps, short codes, and bounded short
+ * messages ONLY. It must never carry assistant text, message deltas, raw tool
+ * args, raw command output, raw tool result content, answers, or oversize
+ * strings.
+ */
+export interface AgentWireOwnerObservation {
+	/** Set when this observation derives from an `AgentSessionEvent`. */
+	eventType?: AgentWireEventType;
+	/** Set when this observation derives from a non-event wire frame. */
+	frameType?: string;
+	/** Owner event kind (e.g. `rpc_tool_started`). */
+	kind: string;
+	/** Bounded observed signal, or null when the frame carries no signal. */
+	signal: AgentWireObservedSignal | null;
+	/** Bounded evidence — ids/names/statuses/cursors/timestamps/short codes only. */
+	evidence: Record<string, unknown>;
+	/** Severity for the emitted event. */
+	severity: AgentWireSeverity;
+	/** Never-drop observations: must be enqueued in order, never coalesced away. */
+	semantic: boolean;
+	/** Coalescing key for high-frequency non-semantic frames; null otherwise. */
+	coalesceKey: string | null;
+}
+
+/** Top-level frame categories carried over any agent-wire transport. */
+export type AgentWireFrameType =
+	| "ready"
+	| "event"
+	| "response"
+	| "ui_request"
+	| "permission_request"
+	| "host_tool_call"
+	| "host_uri_request"
+	| "reset"
+	| "workflow_gate"
+	| "error";
+
+/**
+ * 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`).
+ */
+export interface AgentWireFrameEnvelope<TType extends AgentWireFrameType = AgentWireFrameType, TPayload = unknown> {
+	protocol_version: AgentWireProtocolVersion;
+	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;
+}
+
+/** An `AgentSessionEvent` serialized into a versioned wire frame. */
+export type AgentWireEventFrame = AgentWireFrameEnvelope<"event", AgentWireEventPayload>;

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

@@ -1,19 +1,23 @@
 /**
- * Serialize `AgentSessionEvent`s into versioned bridge wire frames.
+ * Serialize `AgentSessionEvent`s into versioned agent-wire frames.
  *
  * The mapping is intentionally exhaustive: `agentSessionEventType` switches over
  * every variant of the event union and calls `assertNever` in the default arm,
  * so a newly added event variant fails to compile until it is handled here.
+ *
+ * The canonical sequencer + frame builders live here; the historical `Bridge*`
+ * names are retained as thin aliases for callers that have not yet migrated.
  */
 import { randomUUID } from "node:crypto";
 import type { AgentSessionEvent } from "../../../session/agent-session";
 import {
-	type AgentSessionEventType,
-	BRIDGE_PROTOCOL_VERSION,
-	type BridgeEventFrame,
-	type BridgeFrameEnvelope,
-	type BridgeFrameType,
-} from "./protocol";
+	AGENT_WIRE_PROTOCOL_VERSION,
+	type AgentWireEventFrame,
+	type AgentWireEventPayload,
+	type AgentWireEventType,
+	type AgentWireFrameEnvelope,
+	type AgentWireFrameType,
+} from "./event-contract";
 
 function assertNever(value: never): never {
 	throw new Error(`Unhandled AgentSessionEvent variant: ${JSON.stringify(value)}`);
@@ -24,7 +28,7 @@ function assertNever(value: never): never {
  *
  * Exhaustive over the union; adding a variant without a case is a type error.
  */
-export function agentSessionEventType(event: AgentSessionEvent): AgentSessionEventType {
+export function agentSessionEventType(event: AgentSessionEvent): AgentWireEventType {
 	switch (event.type) {
 		case "agent_start":
 		case "agent_end":
@@ -59,7 +63,7 @@ export function agentSessionEventType(event: AgentSessionEvent): AgentSessionEve
  * Per-session monotonic frame builder. One instance per active session; `seq`
  * starts at 1 and increments per frame so clients can order and resume.
  */
-export class BridgeFrameSequencer {
+export class AgentWireFrameSequencer {
 	readonly #sessionId: string;
 	#seq = 0;
 
@@ -78,14 +82,14 @@ export class BridgeFrameSequencer {
 	}
 
 	/** Build the next envelope of the given type with a fresh seq + frame id. */
-	next<TType extends BridgeFrameType, TPayload>(
+	next<TType extends AgentWireFrameType, TPayload>(
 		type: TType,
 		payload: TPayload,
 		correlationId?: string,
-	): BridgeFrameEnvelope<TType, TPayload> {
+	): AgentWireFrameEnvelope<TType, TPayload> {
 		this.#seq += 1;
-		const frame: BridgeFrameEnvelope<TType, TPayload> = {
-			protocol_version: BRIDGE_PROTOCOL_VERSION,
+		const frame: AgentWireFrameEnvelope<TType, TPayload> = {
+			protocol_version: AGENT_WIRE_PROTOCOL_VERSION,
 			session_id: this.#sessionId,
 			seq: this.#seq,
 			frame_id: randomUUID(),
@@ -99,14 +103,29 @@ export class BridgeFrameSequencer {
 	}
 }
 
-/** Serialize a single `AgentSessionEvent` into an `event` wire frame. */
-export function toBridgeEventFrame(event: AgentSessionEvent, sequencer: BridgeFrameSequencer): BridgeEventFrame {
+/** Back-compat alias for {@link AgentWireFrameSequencer}. */
+export const BridgeFrameSequencer = AgentWireFrameSequencer;
+export type BridgeFrameSequencer = AgentWireFrameSequencer;
+
+/** Serialize a single `AgentSessionEvent` into a canonical `event` wire frame. */
+export function toAgentWireEventFrame(
+	event: AgentSessionEvent,
+	sequencer: AgentWireFrameSequencer,
+): AgentWireEventFrame {
 	return sequencer.next("event", {
 		event_type: agentSessionEventType(event),
 		event,
 	});
 }
 
+/** Build the rich event payload (renderer-facing) for an `AgentSessionEvent`. */
+export function toAgentWireEventPayload(event: AgentSessionEvent): AgentWireEventPayload {
+	return { event_type: agentSessionEventType(event), event };
+}
+
+/** Back-compat alias for {@link toAgentWireEventFrame}. */
+export const toBridgeEventFrame = toAgentWireEventFrame;
+
 /**
  * Serialize a `workflow_gate` event into a sequenced wire frame (#321). The
  * gate_id is stamped as the correlation id so the answer (posted to the
@@ -115,7 +134,7 @@ export function toBridgeEventFrame(event: AgentSessionEvent, sequencer: BridgeFr
  */
 export function toBridgeWorkflowGateFrame(
 	gate: import("../../rpc/rpc-types").RpcWorkflowGate,
-	sequencer: BridgeFrameSequencer,
+	sequencer: AgentWireFrameSequencer,
 ): import("./protocol").BridgeWorkflowGateFrame {
 	return sequencer.next("workflow_gate", gate, gate.gate_id);
 }

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;
+	}
+}