feat(server): ACP sessionUpdate parity for Grok clients

apps/server/scripts/acp-mock-agent.ts

@@ -38,6 +38,7 @@ const emitOverlappingXAiPromptCompleteOutOfOrder =
 const failPrompt = process.env.T3_ACP_FAIL_PROMPT === "1";
 const failSetConfigOption = process.env.T3_ACP_FAIL_SET_CONFIG_OPTION === "1";
 const exitOnSetConfigOption = process.env.T3_ACP_EXIT_ON_SET_CONFIG_OPTION === "1";
+const emitSessionInfoUpdate = process.env.T3_ACP_EMIT_SESSION_INFO === "1";
 const promptResponseText = process.env.T3_ACP_PROMPT_RESPONSE_TEXT;
 const promptDelayMs = Number(process.env.T3_ACP_PROMPT_DELAY_MS ?? "0");
 const permissionOptionIds = {
@@ -68,6 +69,17 @@ function promptIdFromRequestMeta(
  return typeof promptId === "string" && promptId.length > 0 ? promptId : undefined;
 }
 
+function promptTextFromRequest(request: AcpSchema.PromptRequest): string {
+ const parts = Array.isArray(request.prompt) ? request.prompt : [];
+ return parts
+ .flatMap((part) =>
+ part && typeof part === "object" && "type" in part && part.type === "text" && "text" in part
+ ? [String(part.text)]
+ : [],
+ )
+ .join("");
+}
+
 function logExit(reason: string): void {
  if (!exitLogPath) {
  return;
@@ -79,6 +91,10 @@ function writeJsonRpcNotification(method: string, params: unknown): void {
  process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", method, params })}\n`);
 }
 
+function writeJsonRpcResponse(id: string | number, result: unknown): void {
+ process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id, result })}\n`);
+}
+
 process.once("SIGTERM", () => {
  logExit("SIGTERM");
  process.exit(0);
@@ -300,9 +316,33 @@ const program = Effect.gen(function* () {
  Effect.sync(() => {
  parameterizedModelPicker =
  request.clientCapabilities?._meta?.parameterizedModelPicker === true;
+ // #4109-class: unsolicited response with non-numeric id must not crash the client.
+ if (process.env.T3_ACP_EMIT_SKILLS_RELOAD_ID === "1") {
+ queueMicrotask(() => {
+ writeJsonRpcResponse("skills-reload", { ok: true });
+ });
+ }
+ const initMeta =
+ process.env.T3_ACP_EMIT_INIT_AVAILABLE_COMMANDS === "1"
+ ? {
+ availableCommands: [
+ {
+ name: "compact",
+ description: "Compress conversation history",
+ input: { hint: "optional context" },
+ },
+ {
+ name: "session-info",
+ description: "Show session details",
+ input: null,
+ },
+ ],
+ }
+ : undefined;
  return {
  protocolVersion: 1,
  agentCapabilities: { loadSession: true },
+ ...(initMeta ? { _meta: initMeta } : {}),
  };
  }),
  );
@@ -465,6 +505,21 @@ const program = Effect.gen(function* () {
  return yield* AcpError.AcpRequestError.internalError("Mock prompt failure");
  }
 
+ // Mirror real Grok: `/compact` is handled as a prompt and emits auto_compact_completed.
+ const promptText = promptTextFromRequest(request).trim();
+ if (/^\/compact(?:\s|$)/i.test(promptText)) {
+ writeJsonRpcNotification("_x.ai/session_notification", {
+ sessionId: requestedSessionId,
+ update: {
+ sessionUpdate: "auto_compact_completed",
+ tokens_before: 12_000,
+ tokens_after: 4_000,
+ summary_preview: null,
+ },
+ });
+ return { stopReason: "end_turn" };
+ }
+
  if (emitStaleXAiPromptCompleteBeforeSecondHang && promptCount === 1) {
  return {
  stopReason: "end_turn",
@@ -865,6 +920,16 @@ const program = Effect.gen(function* () {
  },
  });
 
+ if (emitSessionInfoUpdate) {
+ yield* agent.client.sessionUpdate({
+ sessionId: requestedSessionId,
+ update: {
+ sessionUpdate: "session_info_update",
+ title: "Mock Grok session title",
+ },
+ });
+ }
+
  yield* agent.client.sessionUpdate({
  sessionId: requestedSessionId,
  update: {
@@ -873,7 +938,17 @@ const program = Effect.gen(function* () {
  },
  });
 
- return { stopReason: "end_turn" };
+ // Live Grok stamps usage on prompt result `_meta` (not only usage_update).
+ return {
+ stopReason: "end_turn",
+ _meta: {
+ totalTokens: 12_345,
+ inputTokens: 10_000,
+ outputTokens: 2_000,
+ cachedReadTokens: 8_000,
+ reasoningTokens: 345,
+ },
+ };
  }),
  );
 

apps/server/src/provider/Layers/CursorAdapter.ts

@@ -57,6 +57,7 @@ import {
  makeAcpPlanUpdatedEvent,
  makeAcpRequestOpenedEvent,
  makeAcpRequestResolvedEvent,
+ makeAcpTokenUsageEvent,
  makeAcpToolCallEvent,
 } from "../acp/AcpCoreRuntimeEvents.ts";
 import {
@@ -863,6 +864,28 @@ export function makeCursorAdapter(
  turnId: ctx.activeTurnId,
  ...(event.itemId ? { itemId: event.itemId } : {}),
  text: event.text,
+ streamKind: event.streamKind,
+ rawPayload: event.rawPayload,
+ }),
+ );
+ return;
+ case "UsageUpdated":
+ // Shared ACP consumer for usage_update (parser → runtime event).
+ // Same wiring pattern as ContentDelta/streamKind so the helper is live.
+ yield* logNative(
+ ctx.threadId,
+ "session/update",
+ event.rawPayload,
+ "acp.jsonrpc",
+ );
+ yield* offerRuntimeEvent(
+ makeAcpTokenUsageEvent({
+ stamp: yield* makeEventStamp(),
+ provider: PROVIDER,
+ threadId: ctx.threadId,
+ turnId: ctx.activeTurnId,
+ usedTokens: event.usage.used,
+ ...(event.usage.size > 0 ? { maxTokens: event.usage.size } : {}),
  rawPayload: event.rawPayload,
  }),
  );

apps/server/src/provider/acp/AcpCoreRuntimeEvents.test.ts

@@ -7,6 +7,7 @@ import {
  makeAcpPlanUpdatedEvent,
  makeAcpRequestOpenedEvent,
  makeAcpRequestResolvedEvent,
+ makeAcpTokenUsageEvent,
  makeAcpToolCallEvent,
 } from "./AcpCoreRuntimeEvents.ts";
 
@@ -124,16 +125,64 @@ describe("AcpCoreRuntimeEvents", () => {
  turnId,
  itemId: "assistant:session-1:segment:0",
  text: "hello",
+ streamKind: "reasoning_text",
  rawPayload: { sessionId: "session-1" },
  }),
  ).toMatchObject({
  type: "content.delta",
  itemId: "assistant:session-1:segment:0",
  payload: {
+ streamKind: "reasoning_text",
  delta: "hello",
  },
  });
 
+ const usageWithoutCompact = makeAcpTokenUsageEvent({
+ stamp,
+ provider: ProviderDriverKind.make("cursor"),
+ threadId: "thread-1" as never,
+ turnId,
+ usedTokens: 1200,
+ maxTokens: 256_000,
+ rawPayload: {
+ sessionId: "session-1",
+ update: { sessionUpdate: "usage_update", used: 1200, size: 256_000 },
+ },
+ });
+ expect(usageWithoutCompact).toMatchObject({
+ type: "thread.token-usage.updated",
+ payload: {
+ usage: {
+ usedTokens: 1200,
+ lastUsedTokens: 1200,
+ maxTokens: 256_000,
+ },
+ },
+ });
+ // Generic ACP must not hardcode auto-compact; omit when unknown.
+ expect(
+ (usageWithoutCompact as { payload: { usage: Record<string, unknown> } }).payload.usage
+ .compactsAutomatically,
+ ).toBeUndefined();
+
+ const usageWithCompact = makeAcpTokenUsageEvent({
+ stamp,
+ provider: ProviderDriverKind.make("cursor"),
+ threadId: "thread-1" as never,
+ turnId,
+ usedTokens: 1200,
+ maxTokens: 256_000,
+ compactsAutomatically: true,
+ rawPayload: {
+ sessionId: "session-1",
+ update: { sessionUpdate: "usage_update", used: 1200, size: 256_000 },
+ },
+ });
+ expect(
+ (usageWithCompact as { payload: { usage: Record<string, unknown> } }).payload.usage
+ .compactsAutomatically,
+ ).toBe(true);
+
  expect(
  makeAcpAssistantItemEvent({
  stamp,

apps/server/src/provider/acp/AcpCoreRuntimeEvents.ts

@@ -220,6 +220,7 @@ export function makeAcpContentDeltaEvent(input: {
  readonly turnId: TurnId | undefined;
  readonly itemId?: string;
  readonly text: string;
+ readonly streamKind?: "assistant_text" | "reasoning_text";
  readonly rawPayload: unknown;
 }): ProviderRuntimeEvent {
  return {
@@ -230,7 +231,7 @@ export function makeAcpContentDeltaEvent(input: {
  turnId: input.turnId,
  ...(input.itemId ? { itemId: RuntimeItemId.make(input.itemId) } : {}),
  payload: {
- streamKind: "assistant_text",
+ streamKind: input.streamKind ?? "assistant_text",
  delta: input.text,
  },
  raw: {
@@ -240,3 +241,65 @@ export function makeAcpContentDeltaEvent(input: {
  },
  };
 }
+
+export function makeAcpTokenUsageEvent(input: {
+ readonly stamp: AcpEventStamp;
+ readonly provider: ProviderDriverKind;
+ readonly threadId: ThreadId;
+ readonly turnId: TurnId | undefined;
+ readonly usedTokens: number;
+ readonly maxTokens?: number;
+ readonly inputTokens?: number;
+ readonly outputTokens?: number;
+ readonly cachedInputTokens?: number;
+ readonly reasoningOutputTokens?: number;
+ /**
+ * Only set when the agent/provider is known to auto-compact.
+ * Generic ACP (e.g. Cursor) often does not; omit when unknown so UI defaults to false.
+ */
+ readonly compactsAutomatically?: boolean;
+ readonly rawPayload: unknown;
+ readonly source?: AcpAdapterRawSource;
+ readonly method?: string;
+}): ProviderRuntimeEvent {
+ return {
+ type: "thread.token-usage.updated",
+ ...input.stamp,
+ provider: input.provider,
+ threadId: input.threadId,
+ turnId: input.turnId,
+ payload: {
+ usage: {
+ usedTokens: input.usedTokens,
+ lastUsedTokens: input.usedTokens,
+ ...(input.maxTokens !== undefined && input.maxTokens > 0
+ ? { maxTokens: input.maxTokens }
+ : {}),
+ ...(input.inputTokens !== undefined ? { inputTokens: input.inputTokens } : {}),
+ ...(input.outputTokens !== undefined ? { outputTokens: input.outputTokens } : {}),
+ ...(input.cachedInputTokens !== undefined
+ ? { cachedInputTokens: input.cachedInputTokens }
+ : {}),
+ ...(input.reasoningOutputTokens !== undefined
+ ? { reasoningOutputTokens: input.reasoningOutputTokens }
+ : {}),
+ ...(input.inputTokens !== undefined ? { lastInputTokens: input.inputTokens } : {}),
+ ...(input.outputTokens !== undefined ? { lastOutputTokens: input.outputTokens } : {}),
+ ...(input.cachedInputTokens !== undefined
+ ? { lastCachedInputTokens: input.cachedInputTokens }
+ : {}),
+ ...(input.reasoningOutputTokens !== undefined
+ ? { lastReasoningOutputTokens: input.reasoningOutputTokens }
+ : {}),
+ ...(input.compactsAutomatically !== undefined
+ ? { compactsAutomatically: input.compactsAutomatically }
+ : {}),
+ },
+ },
+ raw: {
+ source: input.source ?? "acp.jsonrpc",
+ method: input.method ?? "session/update",
+ payload: input.rawPayload,
+ },
+ };
+}

apps/server/scripts/acp-mock-agent.ts

@@ -38,6 +38,7 @@ const emitOverlappingXAiPromptCompleteOutOfOrder =
 const failPrompt = process.env.T3_ACP_FAIL_PROMPT === "1";
 const failSetConfigOption = process.env.T3_ACP_FAIL_SET_CONFIG_OPTION === "1";
 const exitOnSetConfigOption = process.env.T3_ACP_EXIT_ON_SET_CONFIG_OPTION === "1";
+const emitSessionInfoUpdate = process.env.T3_ACP_EMIT_SESSION_INFO === "1";
 const promptResponseText = process.env.T3_ACP_PROMPT_RESPONSE_TEXT;
 const promptDelayMs = Number(process.env.T3_ACP_PROMPT_DELAY_MS ?? "0");
 const permissionOptionIds = {
@@ -68,6 +69,17 @@ function promptIdFromRequestMeta(
  return typeof promptId === "string" && promptId.length > 0 ? promptId : undefined;
 }
 
+function promptTextFromRequest(request: AcpSchema.PromptRequest): string {
+ const parts = Array.isArray(request.prompt) ? request.prompt : [];
+ return parts
+ .flatMap((part) =>
+ part && typeof part === "object" && "type" in part && part.type === "text" && "text" in part
+ ? [String(part.text)]
+ : [],
+ )
+ .join("");
+}
+
 function logExit(reason: string): void {
  if (!exitLogPath) {
  return;
@@ -79,6 +91,10 @@ function writeJsonRpcNotification(method: string, params: unknown): void {
  process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", method, params })}\n`);
 }
 
+function writeJsonRpcResponse(id: string | number, result: unknown): void {
+ process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id, result })}\n`);
+}
+
 process.once("SIGTERM", () => {
  logExit("SIGTERM");
  process.exit(0);
@@ -300,9 +316,33 @@ const program = Effect.gen(function* () {
  Effect.sync(() => {
  parameterizedModelPicker =
  request.clientCapabilities?._meta?.parameterizedModelPicker === true;
+ // #4109-class: unsolicited response with non-numeric id must not crash the client.
+ if (process.env.T3_ACP_EMIT_SKILLS_RELOAD_ID === "1") {
+ queueMicrotask(() => {
+ writeJsonRpcResponse("skills-reload", { ok: true });
+ });
+ }
+ const initMeta =
+ process.env.T3_ACP_EMIT_INIT_AVAILABLE_COMMANDS === "1"
+ ? {
+ availableCommands: [
+ {
+ name: "compact",
+ description: "Compress conversation history",
+ input: { hint: "optional context" },
+ },
+ {
+ name: "session-info",
+ description: "Show session details",
+ input: null,
+ },
+ ],
+ }
+ : undefined;
  return {
  protocolVersion: 1,
  agentCapabilities: { loadSession: true },
+ ...(initMeta ? { _meta: initMeta } : {}),
  };
  }),
  );
@@ -465,6 +505,21 @@ const program = Effect.gen(function* () {
  return yield* AcpError.AcpRequestError.internalError("Mock prompt failure");
  }
 
+ // Mirror real Grok: `/compact` is handled as a prompt and emits auto_compact_completed.
+ const promptText = promptTextFromRequest(request).trim();
+ if (/^\/compact(?:\s|$)/i.test(promptText)) {
+ writeJsonRpcNotification("_x.ai/session_notification", {
+ sessionId: requestedSessionId,
+ update: {
+ sessionUpdate: "auto_compact_completed",
+ tokens_before: 12_000,
+ tokens_after: 4_000,
+ summary_preview: null,
+ },
+ });
+ return { stopReason: "end_turn" };
+ }
+
  if (emitStaleXAiPromptCompleteBeforeSecondHang && promptCount === 1) {
  return {
  stopReason: "end_turn",
@@ -865,6 +920,16 @@ const program = Effect.gen(function* () {
  },
  });
 
+ if (emitSessionInfoUpdate) {
+ yield* agent.client.sessionUpdate({
+ sessionId: requestedSessionId,
+ update: {
+ sessionUpdate: "session_info_update",
+ title: "Mock Grok session title",
+ },
+ });
+ }
+
  yield* agent.client.sessionUpdate({
  sessionId: requestedSessionId,
  update: {
@@ -873,7 +938,17 @@ const program = Effect.gen(function* () {
  },
  });
 
- return { stopReason: "end_turn" };
+ // Live Grok stamps usage on prompt result `_meta` (not only usage_update).
+ return {
+ stopReason: "end_turn",
+ _meta: {
+ totalTokens: 12_345,
+ inputTokens: 10_000,
+ outputTokens: 2_000,
+ cachedReadTokens: 8_000,
+ reasoningTokens: 345,
+ },
+ };
  }),
  );
 

apps/server/src/provider/Layers/CursorAdapter.ts

@@ -57,6 +57,7 @@ import {
  makeAcpPlanUpdatedEvent,
  makeAcpRequestOpenedEvent,
  makeAcpRequestResolvedEvent,
+ makeAcpTokenUsageEvent,
  makeAcpToolCallEvent,
 } from "../acp/AcpCoreRuntimeEvents.ts";
 import {
@@ -863,6 +864,28 @@ export function makeCursorAdapter(
  turnId: ctx.activeTurnId,
  ...(event.itemId ? { itemId: event.itemId } : {}),
  text: event.text,
+ streamKind: event.streamKind,
+ rawPayload: event.rawPayload,
+ }),
+ );
+ return;
+ case "UsageUpdated":
+ // Shared ACP consumer for usage_update (parser → runtime event).
+ // Same wiring pattern as ContentDelta/streamKind so the helper is live.
+ yield* logNative(
+ ctx.threadId,
+ "session/update",
+ event.rawPayload,
+ "acp.jsonrpc",
+ );
+ yield* offerRuntimeEvent(
+ makeAcpTokenUsageEvent({
+ stamp: yield* makeEventStamp(),
+ provider: PROVIDER,
+ threadId: ctx.threadId,
+ turnId: ctx.activeTurnId,
+ usedTokens: event.usage.used,
+ ...(event.usage.size > 0 ? { maxTokens: event.usage.size } : {}),
  rawPayload: event.rawPayload,
  }),
  );

apps/server/src/provider/acp/AcpCoreRuntimeEvents.test.ts

@@ -7,6 +7,7 @@ import {
  makeAcpPlanUpdatedEvent,
  makeAcpRequestOpenedEvent,
  makeAcpRequestResolvedEvent,
+ makeAcpTokenUsageEvent,
  makeAcpToolCallEvent,
 } from "./AcpCoreRuntimeEvents.ts";
 
@@ -124,16 +125,64 @@ describe("AcpCoreRuntimeEvents", () => {
  turnId,
  itemId: "assistant:session-1:segment:0",
  text: "hello",
+ streamKind: "reasoning_text",
  rawPayload: { sessionId: "session-1" },
  }),
  ).toMatchObject({
  type: "content.delta",
  itemId: "assistant:session-1:segment:0",
  payload: {
+ streamKind: "reasoning_text",
  delta: "hello",
  },
  });
 
+ const usageWithoutCompact = makeAcpTokenUsageEvent({
+ stamp,
+ provider: ProviderDriverKind.make("cursor"),
+ threadId: "thread-1" as never,
+ turnId,
+ usedTokens: 1200,
+ maxTokens: 256_000,
+ rawPayload: {
+ sessionId: "session-1",
+ update: { sessionUpdate: "usage_update", used: 1200, size: 256_000 },
+ },
+ });
+ expect(usageWithoutCompact).toMatchObject({
+ type: "thread.token-usage.updated",
+ payload: {
+ usage: {
+ usedTokens: 1200,
+ lastUsedTokens: 1200,
+ maxTokens: 256_000,
+ },
+ },
+ });
+ // Generic ACP must not hardcode auto-compact; omit when unknown.
+ expect(
+ (usageWithoutCompact as { payload: { usage: Record<string, unknown> } }).payload.usage
+ .compactsAutomatically,
+ ).toBeUndefined();
+
+ const usageWithCompact = makeAcpTokenUsageEvent({
+ stamp,
+ provider: ProviderDriverKind.make("cursor"),
+ threadId: "thread-1" as never,
+ turnId,
+ usedTokens: 1200,
+ maxTokens: 256_000,
+ compactsAutomatically: true,
+ rawPayload: {
+ sessionId: "session-1",
+ update: { sessionUpdate: "usage_update", used: 1200, size: 256_000 },
+ },
+ });
+ expect(
+ (usageWithCompact as { payload: { usage: Record<string, unknown> } }).payload.usage
+ .compactsAutomatically,
+ ).toBe(true);
+
  expect(
  makeAcpAssistantItemEvent({
  stamp,

apps/server/src/provider/acp/AcpCoreRuntimeEvents.ts

@@ -220,6 +220,7 @@ export function makeAcpContentDeltaEvent(input: {
  readonly turnId: TurnId | undefined;
  readonly itemId?: string;
  readonly text: string;
+ readonly streamKind?: "assistant_text" | "reasoning_text";
  readonly rawPayload: unknown;
 }): ProviderRuntimeEvent {
  return {
@@ -230,7 +231,7 @@ export function makeAcpContentDeltaEvent(input: {
  turnId: input.turnId,
  ...(input.itemId ? { itemId: RuntimeItemId.make(input.itemId) } : {}),
  payload: {
- streamKind: "assistant_text",
+ streamKind: input.streamKind ?? "assistant_text",
  delta: input.text,
  },
  raw: {
@@ -240,3 +241,65 @@ export function makeAcpContentDeltaEvent(input: {
  },
  };
 }
+
+export function makeAcpTokenUsageEvent(input: {
+ readonly stamp: AcpEventStamp;
+ readonly provider: ProviderDriverKind;
+ readonly threadId: ThreadId;
+ readonly turnId: TurnId | undefined;
+ readonly usedTokens: number;
+ readonly maxTokens?: number;
+ readonly inputTokens?: number;
+ readonly outputTokens?: number;
+ readonly cachedInputTokens?: number;
+ readonly reasoningOutputTokens?: number;
+ /**
+ * Only set when the agent/provider is known to auto-compact.
+ * Generic ACP (e.g. Cursor) often does not; omit when unknown so UI defaults to false.
+ */
+ readonly compactsAutomatically?: boolean;
+ readonly rawPayload: unknown;
+ readonly source?: AcpAdapterRawSource;
+ readonly method?: string;
+}): ProviderRuntimeEvent {
+ return {
+ type: "thread.token-usage.updated",
+ ...input.stamp,
+ provider: input.provider,
+ threadId: input.threadId,
+ turnId: input.turnId,
+ payload: {
+ usage: {
+ usedTokens: input.usedTokens,
+ lastUsedTokens: input.usedTokens,
+ ...(input.maxTokens !== undefined && input.maxTokens > 0
+ ? { maxTokens: input.maxTokens }
+ : {}),
+ ...(input.inputTokens !== undefined ? { inputTokens: input.inputTokens } : {}),
+ ...(input.outputTokens !== undefined ? { outputTokens: input.outputTokens } : {}),
+ ...(input.cachedInputTokens !== undefined
+ ? { cachedInputTokens: input.cachedInputTokens }
+ : {}),
+ ...(input.reasoningOutputTokens !== undefined
+ ? { reasoningOutputTokens: input.reasoningOutputTokens }
+ : {}),
+ ...(input.inputTokens !== undefined ? { lastInputTokens: input.inputTokens } : {}),
+ ...(input.outputTokens !== undefined ? { lastOutputTokens: input.outputTokens } : {}),
+ ...(input.cachedInputTokens !== undefined
+ ? { lastCachedInputTokens: input.cachedInputTokens }
+ : {}),
+ ...(input.reasoningOutputTokens !== undefined
+ ? { lastReasoningOutputTokens: input.reasoningOutputTokens }
+ : {}),
+ ...(input.compactsAutomatically !== undefined
+ ? { compactsAutomatically: input.compactsAutomatically }
+ : {}),
+ },
+ },
+ raw: {
+ source: input.source ?? "acp.jsonrpc",
+ method: input.method ?? "session/update",
+ payload: input.rawPayload,
+ },
+ };
+}

apps/server/scripts/acp-mock-agent.ts

@@ -38,6 +38,7 @@ const emitOverlappingXAiPromptCompleteOutOfOrder =
 const failPrompt = process.env.T3_ACP_FAIL_PROMPT === "1";
 const failSetConfigOption = process.env.T3_ACP_FAIL_SET_CONFIG_OPTION === "1";
 const exitOnSetConfigOption = process.env.T3_ACP_EXIT_ON_SET_CONFIG_OPTION === "1";
+const emitSessionInfoUpdate = process.env.T3_ACP_EMIT_SESSION_INFO === "1";
 const promptResponseText = process.env.T3_ACP_PROMPT_RESPONSE_TEXT;
 const promptDelayMs = Number(process.env.T3_ACP_PROMPT_DELAY_MS ?? "0");
 const permissionOptionIds = {
@@ -68,6 +69,17 @@ function promptIdFromRequestMeta(
  return typeof promptId === "string" && promptId.length > 0 ? promptId : undefined;
 }
 
+function promptTextFromRequest(request: AcpSchema.PromptRequest): string {
+ const parts = Array.isArray(request.prompt) ? request.prompt : [];
+ return parts
+ .flatMap((part) =>
+ part && typeof part === "object" && "type" in part && part.type === "text" && "text" in part
+ ? [String(part.text)]
+ : [],
+ )
+ .join("");
+}
+
 function logExit(reason: string): void {
  if (!exitLogPath) {
  return;
@@ -79,6 +91,10 @@ function writeJsonRpcNotification(method: string, params: unknown): void {
  process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", method, params })}\n`);
 }
 
+function writeJsonRpcResponse(id: string | number, result: unknown): void {
+ process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id, result })}\n`);
+}
+
 process.once("SIGTERM", () => {
  logExit("SIGTERM");
  process.exit(0);
@@ -300,9 +316,33 @@ const program = Effect.gen(function* () {
  Effect.sync(() => {
  parameterizedModelPicker =
  request.clientCapabilities?._meta?.parameterizedModelPicker === true;
+ // #4109-class: unsolicited response with non-numeric id must not crash the client.
+ if (process.env.T3_ACP_EMIT_SKILLS_RELOAD_ID === "1") {
+ queueMicrotask(() => {
+ writeJsonRpcResponse("skills-reload", { ok: true });
+ });
+ }
+ const initMeta =
+ process.env.T3_ACP_EMIT_INIT_AVAILABLE_COMMANDS === "1"
+ ? {
+ availableCommands: [
+ {
+ name: "compact",
+ description: "Compress conversation history",
+ input: { hint: "optional context" },
+ },
+ {
+ name: "session-info",
+ description: "Show session details",
+ input: null,
+ },
+ ],
+ }
+ : undefined;
  return {
  protocolVersion: 1,
  agentCapabilities: { loadSession: true },
+ ...(initMeta ? { _meta: initMeta } : {}),
  };
  }),
  );
@@ -465,6 +505,21 @@ const program = Effect.gen(function* () {
  return yield* AcpError.AcpRequestError.internalError("Mock prompt failure");
  }
 
+ // Mirror real Grok: `/compact` is handled as a prompt and emits auto_compact_completed.
+ const promptText = promptTextFromRequest(request).trim();
+ if (/^\/compact(?:\s|$)/i.test(promptText)) {
+ writeJsonRpcNotification("_x.ai/session_notification", {
+ sessionId: requestedSessionId,
+ update: {
+ sessionUpdate: "auto_compact_completed",
+ tokens_before: 12_000,
+ tokens_after: 4_000,
+ summary_preview: null,
+ },
+ });
+ return { stopReason: "end_turn" };
+ }
+
  if (emitStaleXAiPromptCompleteBeforeSecondHang && promptCount === 1) {
  return {
  stopReason: "end_turn",
@@ -865,6 +920,16 @@ const program = Effect.gen(function* () {
  },
  });
 
+ if (emitSessionInfoUpdate) {
+ yield* agent.client.sessionUpdate({
+ sessionId: requestedSessionId,
+ update: {
+ sessionUpdate: "session_info_update",
+ title: "Mock Grok session title",
+ },
+ });
+ }
+
  yield* agent.client.sessionUpdate({
  sessionId: requestedSessionId,
  update: {
@@ -873,7 +938,17 @@ const program = Effect.gen(function* () {
  },
  });
 
- return { stopReason: "end_turn" };
+ // Live Grok stamps usage on prompt result `_meta` (not only usage_update).
+ return {
+ stopReason: "end_turn",
+ _meta: {
+ totalTokens: 12_345,
+ inputTokens: 10_000,
+ outputTokens: 2_000,
+ cachedReadTokens: 8_000,
+ reasoningTokens: 345,
+ },
+ };
  }),
  );
 

apps/server/src/provider/Layers/CursorAdapter.ts

@@ -57,6 +57,7 @@ import {
  makeAcpPlanUpdatedEvent,
  makeAcpRequestOpenedEvent,
  makeAcpRequestResolvedEvent,
+ makeAcpTokenUsageEvent,
  makeAcpToolCallEvent,
 } from "../acp/AcpCoreRuntimeEvents.ts";
 import {
@@ -863,6 +864,28 @@ export function makeCursorAdapter(
  turnId: ctx.activeTurnId,
  ...(event.itemId ? { itemId: event.itemId } : {}),
  text: event.text,
+ streamKind: event.streamKind,
+ rawPayload: event.rawPayload,
+ }),
+ );
+ return;
+ case "UsageUpdated":
+ // Shared ACP consumer for usage_update (parser → runtime event).
+ // Same wiring pattern as ContentDelta/streamKind so the helper is live.
+ yield* logNative(
+ ctx.threadId,
+ "session/update",
+ event.rawPayload,
+ "acp.jsonrpc",
+ );
+ yield* offerRuntimeEvent(
+ makeAcpTokenUsageEvent({
+ stamp: yield* makeEventStamp(),
+ provider: PROVIDER,
+ threadId: ctx.threadId,
+ turnId: ctx.activeTurnId,
+ usedTokens: event.usage.used,
+ ...(event.usage.size > 0 ? { maxTokens: event.usage.size } : {}),
  rawPayload: event.rawPayload,
  }),
  );

apps/server/src/provider/acp/AcpCoreRuntimeEvents.test.ts

@@ -7,6 +7,7 @@ import {
  makeAcpPlanUpdatedEvent,
  makeAcpRequestOpenedEvent,
  makeAcpRequestResolvedEvent,
+ makeAcpTokenUsageEvent,
  makeAcpToolCallEvent,
 } from "./AcpCoreRuntimeEvents.ts";
 
@@ -124,16 +125,64 @@ describe("AcpCoreRuntimeEvents", () => {
  turnId,
  itemId: "assistant:session-1:segment:0",
  text: "hello",
+ streamKind: "reasoning_text",
  rawPayload: { sessionId: "session-1" },
  }),
  ).toMatchObject({
  type: "content.delta",
  itemId: "assistant:session-1:segment:0",
  payload: {
+ streamKind: "reasoning_text",
  delta: "hello",
  },
  });
 
+ const usageWithoutCompact = makeAcpTokenUsageEvent({
+ stamp,
+ provider: ProviderDriverKind.make("cursor"),
+ threadId: "thread-1" as never,
+ turnId,
+ usedTokens: 1200,
+ maxTokens: 256_000,
+ rawPayload: {
+ sessionId: "session-1",
+ update: { sessionUpdate: "usage_update", used: 1200, size: 256_000 },
+ },
+ });
+ expect(usageWithoutCompact).toMatchObject({
+ type: "thread.token-usage.updated",
+ payload: {
+ usage: {
+ usedTokens: 1200,
+ lastUsedTokens: 1200,
+ maxTokens: 256_000,
+ },
+ },
+ });
+ // Generic ACP must not hardcode auto-compact; omit when unknown.
+ expect(
+ (usageWithoutCompact as { payload: { usage: Record<string, unknown> } }).payload.usage
+ .compactsAutomatically,
+ ).toBeUndefined();
+
+ const usageWithCompact = makeAcpTokenUsageEvent({
+ stamp,
+ provider: ProviderDriverKind.make("cursor"),
+ threadId: "thread-1" as never,
+ turnId,
+ usedTokens: 1200,
+ maxTokens: 256_000,
+ compactsAutomatically: true,
+ rawPayload: {
+ sessionId: "session-1",
+ update: { sessionUpdate: "usage_update", used: 1200, size: 256_000 },
+ },
+ });
+ expect(
+ (usageWithCompact as { payload: { usage: Record<string, unknown> } }).payload.usage
+ .compactsAutomatically,
+ ).toBe(true);
+
  expect(
  makeAcpAssistantItemEvent({
  stamp,

apps/server/src/provider/acp/AcpCoreRuntimeEvents.ts

@@ -220,6 +220,7 @@ export function makeAcpContentDeltaEvent(input: {
  readonly turnId: TurnId | undefined;
  readonly itemId?: string;
  readonly text: string;
+ readonly streamKind?: "assistant_text" | "reasoning_text";
  readonly rawPayload: unknown;
 }): ProviderRuntimeEvent {
  return {
@@ -230,7 +231,7 @@ export function makeAcpContentDeltaEvent(input: {
  turnId: input.turnId,
  ...(input.itemId ? { itemId: RuntimeItemId.make(input.itemId) } : {}),
  payload: {
- streamKind: "assistant_text",
+ streamKind: input.streamKind ?? "assistant_text",
  delta: input.text,
  },
  raw: {
@@ -240,3 +241,65 @@ export function makeAcpContentDeltaEvent(input: {
  },
  };
 }
+
+export function makeAcpTokenUsageEvent(input: {
+ readonly stamp: AcpEventStamp;
+ readonly provider: ProviderDriverKind;
+ readonly threadId: ThreadId;
+ readonly turnId: TurnId | undefined;
+ readonly usedTokens: number;
+ readonly maxTokens?: number;
+ readonly inputTokens?: number;
+ readonly outputTokens?: number;
+ readonly cachedInputTokens?: number;
+ readonly reasoningOutputTokens?: number;
+ /**
+ * Only set when the agent/provider is known to auto-compact.
+ * Generic ACP (e.g. Cursor) often does not; omit when unknown so UI defaults to false.
+ */
+ readonly compactsAutomatically?: boolean;
+ readonly rawPayload: unknown;
+ readonly source?: AcpAdapterRawSource;
+ readonly method?: string;
+}): ProviderRuntimeEvent {
+ return {
+ type: "thread.token-usage.updated",
+ ...input.stamp,
+ provider: input.provider,
+ threadId: input.threadId,
+ turnId: input.turnId,
+ payload: {
+ usage: {
+ usedTokens: input.usedTokens,
+ lastUsedTokens: input.usedTokens,
+ ...(input.maxTokens !== undefined && input.maxTokens > 0
+ ? { maxTokens: input.maxTokens }
+ : {}),
+ ...(input.inputTokens !== undefined ? { inputTokens: input.inputTokens } : {}),
+ ...(input.outputTokens !== undefined ? { outputTokens: input.outputTokens } : {}),
+ ...(input.cachedInputTokens !== undefined
+ ? { cachedInputTokens: input.cachedInputTokens }
+ : {}),
+ ...(input.reasoningOutputTokens !== undefined
+ ? { reasoningOutputTokens: input.reasoningOutputTokens }
+ : {}),
+ ...(input.inputTokens !== undefined ? { lastInputTokens: input.inputTokens } : {}),
+ ...(input.outputTokens !== undefined ? { lastOutputTokens: input.outputTokens } : {}),
+ ...(input.cachedInputTokens !== undefined
+ ? { lastCachedInputTokens: input.cachedInputTokens }
+ : {}),
+ ...(input.reasoningOutputTokens !== undefined
+ ? { lastReasoningOutputTokens: input.reasoningOutputTokens }
+ : {}),
+ ...(input.compactsAutomatically !== undefined
+ ? { compactsAutomatically: input.compactsAutomatically }
+ : {}),
+ },
+ },
+ raw: {
+ source: input.source ?? "acp.jsonrpc",
+ method: input.method ?? "session/update",
+ payload: input.rawPayload,
+ },
+ };
+}

apps/server/scripts/acp-mock-agent.ts

@@ -38,6 +38,7 @@ const emitOverlappingXAiPromptCompleteOutOfOrder =
 const failPrompt = process.env.T3_ACP_FAIL_PROMPT === "1";
 const failSetConfigOption = process.env.T3_ACP_FAIL_SET_CONFIG_OPTION === "1";
 const exitOnSetConfigOption = process.env.T3_ACP_EXIT_ON_SET_CONFIG_OPTION === "1";
+const emitSessionInfoUpdate = process.env.T3_ACP_EMIT_SESSION_INFO === "1";
 const promptResponseText = process.env.T3_ACP_PROMPT_RESPONSE_TEXT;
 const promptDelayMs = Number(process.env.T3_ACP_PROMPT_DELAY_MS ?? "0");
 const permissionOptionIds = {
@@ -68,6 +69,17 @@ function promptIdFromRequestMeta(
  return typeof promptId === "string" && promptId.length > 0 ? promptId : undefined;
 }
 
+function promptTextFromRequest(request: AcpSchema.PromptRequest): string {
+ const parts = Array.isArray(request.prompt) ? request.prompt : [];
+ return parts
+ .flatMap((part) =>
+ part && typeof part === "object" && "type" in part && part.type === "text" && "text" in part
+ ? [String(part.text)]
+ : [],
+ )
+ .join("");
+}
+
 function logExit(reason: string): void {
  if (!exitLogPath) {
  return;
@@ -79,6 +91,10 @@ function writeJsonRpcNotification(method: string, params: unknown): void {
  process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", method, params })}\n`);
 }
 
+function writeJsonRpcResponse(id: string | number, result: unknown): void {
+ process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id, result })}\n`);
+}
+
 process.once("SIGTERM", () => {
  logExit("SIGTERM");
  process.exit(0);
@@ -300,9 +316,33 @@ const program = Effect.gen(function* () {
  Effect.sync(() => {
  parameterizedModelPicker =
  request.clientCapabilities?._meta?.parameterizedModelPicker === true;
+ // #4109-class: unsolicited response with non-numeric id must not crash the client.
+ if (process.env.T3_ACP_EMIT_SKILLS_RELOAD_ID === "1") {
+ queueMicrotask(() => {
+ writeJsonRpcResponse("skills-reload", { ok: true });
+ });
+ }
+ const initMeta =
+ process.env.T3_ACP_EMIT_INIT_AVAILABLE_COMMANDS === "1"
+ ? {
+ availableCommands: [
+ {
+ name: "compact",
+ description: "Compress conversation history",
+ input: { hint: "optional context" },
+ },
+ {
+ name: "session-info",
+ description: "Show session details",
+ input: null,
+ },
+ ],
+ }
+ : undefined;
  return {
  protocolVersion: 1,
  agentCapabilities: { loadSession: true },
+ ...(initMeta ? { _meta: initMeta } : {}),
  };
  }),
  );
@@ -465,6 +505,21 @@ const program = Effect.gen(function* () {
  return yield* AcpError.AcpRequestError.internalError("Mock prompt failure");
  }
 
+ // Mirror real Grok: `/compact` is handled as a prompt and emits auto_compact_completed.
+ const promptText = promptTextFromRequest(request).trim();
+ if (/^\/compact(?:\s|$)/i.test(promptText)) {
+ writeJsonRpcNotification("_x.ai/session_notification", {
+ sessionId: requestedSessionId,
+ update: {
+ sessionUpdate: "auto_compact_completed",
+ tokens_before: 12_000,
+ tokens_after: 4_000,
+ summary_preview: null,
+ },
+ });
+ return { stopReason: "end_turn" };
+ }
+
  if (emitStaleXAiPromptCompleteBeforeSecondHang && promptCount === 1) {
  return {
  stopReason: "end_turn",
@@ -865,6 +920,16 @@ const program = Effect.gen(function* () {
  },
  });
 
+ if (emitSessionInfoUpdate) {
+ yield* agent.client.sessionUpdate({
+ sessionId: requestedSessionId,
+ update: {
+ sessionUpdate: "session_info_update",
+ title: "Mock Grok session title",
+ },
+ });
+ }
+
  yield* agent.client.sessionUpdate({
  sessionId: requestedSessionId,
  update: {
@@ -873,7 +938,17 @@ const program = Effect.gen(function* () {
  },
  });
 
- return { stopReason: "end_turn" };
+ // Live Grok stamps usage on prompt result `_meta` (not only usage_update).
+ return {
+ stopReason: "end_turn",
+ _meta: {
+ totalTokens: 12_345,
+ inputTokens: 10_000,
+ outputTokens: 2_000,
+ cachedReadTokens: 8_000,
+ reasoningTokens: 345,
+ },
+ };
  }),
  );
 

apps/server/src/provider/Layers/CursorAdapter.ts

@@ -57,6 +57,7 @@ import {
  makeAcpPlanUpdatedEvent,
  makeAcpRequestOpenedEvent,
  makeAcpRequestResolvedEvent,
+ makeAcpTokenUsageEvent,
  makeAcpToolCallEvent,
 } from "../acp/AcpCoreRuntimeEvents.ts";
 import {
@@ -863,6 +864,28 @@ export function makeCursorAdapter(
  turnId: ctx.activeTurnId,
  ...(event.itemId ? { itemId: event.itemId } : {}),
  text: event.text,
+ streamKind: event.streamKind,
+ rawPayload: event.rawPayload,
+ }),
+ );
+ return;
+ case "UsageUpdated":
+ // Shared ACP consumer for usage_update (parser → runtime event).
+ // Same wiring pattern as ContentDelta/streamKind so the helper is live.
+ yield* logNative(
+ ctx.threadId,
+ "session/update",
+ event.rawPayload,
+ "acp.jsonrpc",
+ );
+ yield* offerRuntimeEvent(
+ makeAcpTokenUsageEvent({
+ stamp: yield* makeEventStamp(),
+ provider: PROVIDER,
+ threadId: ctx.threadId,
+ turnId: ctx.activeTurnId,
+ usedTokens: event.usage.used,
+ ...(event.usage.size > 0 ? { maxTokens: event.usage.size } : {}),
  rawPayload: event.rawPayload,
  }),
  );

apps/server/src/provider/acp/AcpCoreRuntimeEvents.test.ts

@@ -7,6 +7,7 @@ import {
  makeAcpPlanUpdatedEvent,
  makeAcpRequestOpenedEvent,
  makeAcpRequestResolvedEvent,
+ makeAcpTokenUsageEvent,
  makeAcpToolCallEvent,
 } from "./AcpCoreRuntimeEvents.ts";
 
@@ -124,16 +125,64 @@ describe("AcpCoreRuntimeEvents", () => {
  turnId,
  itemId: "assistant:session-1:segment:0",
  text: "hello",
+ streamKind: "reasoning_text",
  rawPayload: { sessionId: "session-1" },
  }),
  ).toMatchObject({
  type: "content.delta",
  itemId: "assistant:session-1:segment:0",
  payload: {
+ streamKind: "reasoning_text",
  delta: "hello",
  },
  });
 
+ const usageWithoutCompact = makeAcpTokenUsageEvent({
+ stamp,
+ provider: ProviderDriverKind.make("cursor"),
+ threadId: "thread-1" as never,
+ turnId,
+ usedTokens: 1200,
+ maxTokens: 256_000,
+ rawPayload: {
+ sessionId: "session-1",
+ update: { sessionUpdate: "usage_update", used: 1200, size: 256_000 },
+ },
+ });
+ expect(usageWithoutCompact).toMatchObject({
+ type: "thread.token-usage.updated",
+ payload: {
+ usage: {
+ usedTokens: 1200,
+ lastUsedTokens: 1200,
+ maxTokens: 256_000,
+ },
+ },
+ });
+ // Generic ACP must not hardcode auto-compact; omit when unknown.
+ expect(
+ (usageWithoutCompact as { payload: { usage: Record<string, unknown> } }).payload.usage
+ .compactsAutomatically,
+ ).toBeUndefined();
+
+ const usageWithCompact = makeAcpTokenUsageEvent({
+ stamp,
+ provider: ProviderDriverKind.make("cursor"),
+ threadId: "thread-1" as never,
+ turnId,
+ usedTokens: 1200,
+ maxTokens: 256_000,
+ compactsAutomatically: true,
+ rawPayload: {
+ sessionId: "session-1",
+ update: { sessionUpdate: "usage_update", used: 1200, size: 256_000 },
+ },
+ });
+ expect(
+ (usageWithCompact as { payload: { usage: Record<string, unknown> } }).payload.usage
+ .compactsAutomatically,
+ ).toBe(true);
+
  expect(
  makeAcpAssistantItemEvent({
  stamp,

apps/server/src/provider/acp/AcpCoreRuntimeEvents.ts

@@ -220,6 +220,7 @@ export function makeAcpContentDeltaEvent(input: {
  readonly turnId: TurnId | undefined;
  readonly itemId?: string;
  readonly text: string;
+ readonly streamKind?: "assistant_text" | "reasoning_text";
  readonly rawPayload: unknown;
 }): ProviderRuntimeEvent {
  return {
@@ -230,7 +231,7 @@ export function makeAcpContentDeltaEvent(input: {
  turnId: input.turnId,
  ...(input.itemId ? { itemId: RuntimeItemId.make(input.itemId) } : {}),
  payload: {
- streamKind: "assistant_text",
+ streamKind: input.streamKind ?? "assistant_text",
  delta: input.text,
  },
  raw: {
@@ -240,3 +241,65 @@ export function makeAcpContentDeltaEvent(input: {
  },
  };
 }
+
+export function makeAcpTokenUsageEvent(input: {
+ readonly stamp: AcpEventStamp;
+ readonly provider: ProviderDriverKind;
+ readonly threadId: ThreadId;
+ readonly turnId: TurnId | undefined;
+ readonly usedTokens: number;
+ readonly maxTokens?: number;
+ readonly inputTokens?: number;
+ readonly outputTokens?: number;
+ readonly cachedInputTokens?: number;
+ readonly reasoningOutputTokens?: number;
+ /**
+ * Only set when the agent/provider is known to auto-compact.
+ * Generic ACP (e.g. Cursor) often does not; omit when unknown so UI defaults to false.
+ */
+ readonly compactsAutomatically?: boolean;
+ readonly rawPayload: unknown;
+ readonly source?: AcpAdapterRawSource;
+ readonly method?: string;
+}): ProviderRuntimeEvent {
+ return {
+ type: "thread.token-usage.updated",
+ ...input.stamp,
+ provider: input.provider,
+ threadId: input.threadId,
+ turnId: input.turnId,
+ payload: {
+ usage: {
+ usedTokens: input.usedTokens,
+ lastUsedTokens: input.usedTokens,
+ ...(input.maxTokens !== undefined && input.maxTokens > 0
+ ? { maxTokens: input.maxTokens }
+ : {}),
+ ...(input.inputTokens !== undefined ? { inputTokens: input.inputTokens } : {}),
+ ...(input.outputTokens !== undefined ? { outputTokens: input.outputTokens } : {}),
+ ...(input.cachedInputTokens !== undefined
+ ? { cachedInputTokens: input.cachedInputTokens }
+ : {}),
+ ...(input.reasoningOutputTokens !== undefined
+ ? { reasoningOutputTokens: input.reasoningOutputTokens }
+ : {}),
+ ...(input.inputTokens !== undefined ? { lastInputTokens: input.inputTokens } : {}),
+ ...(input.outputTokens !== undefined ? { lastOutputTokens: input.outputTokens } : {}),
+ ...(input.cachedInputTokens !== undefined
+ ? { lastCachedInputTokens: input.cachedInputTokens }
+ : {}),
+ ...(input.reasoningOutputTokens !== undefined
+ ? { lastReasoningOutputTokens: input.reasoningOutputTokens }
+ : {}),
+ ...(input.compactsAutomatically !== undefined
+ ? { compactsAutomatically: input.compactsAutomatically }
+ : {}),
+ },
+ },
+ raw: {
+ source: input.source ?? "acp.jsonrpc",
+ method: input.method ?? "session/update",
+ payload: input.rawPayload,
+ },
+ };
+}

apps/server/scripts/acp-mock-agent.ts

@@ -38,6 +38,7 @@ const emitOverlappingXAiPromptCompleteOutOfOrder =
 const failPrompt = process.env.T3_ACP_FAIL_PROMPT === "1";
 const failSetConfigOption = process.env.T3_ACP_FAIL_SET_CONFIG_OPTION === "1";
 const exitOnSetConfigOption = process.env.T3_ACP_EXIT_ON_SET_CONFIG_OPTION === "1";
+const emitSessionInfoUpdate = process.env.T3_ACP_EMIT_SESSION_INFO === "1";
 const promptResponseText = process.env.T3_ACP_PROMPT_RESPONSE_TEXT;
 const promptDelayMs = Number(process.env.T3_ACP_PROMPT_DELAY_MS ?? "0");
 const permissionOptionIds = {
@@ -68,6 +69,17 @@ function promptIdFromRequestMeta(
  return typeof promptId === "string" && promptId.length > 0 ? promptId : undefined;
 }
 
+function promptTextFromRequest(request: AcpSchema.PromptRequest): string {
+ const parts = Array.isArray(request.prompt) ? request.prompt : [];
+ return parts
+ .flatMap((part) =>
+ part && typeof part === "object" && "type" in part && part.type === "text" && "text" in part
+ ? [String(part.text)]
+ : [],
+ )
+ .join("");
+}
+
 function logExit(reason: string): void {
  if (!exitLogPath) {
  return;
@@ -79,6 +91,10 @@ function writeJsonRpcNotification(method: string, params: unknown): void {
  process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", method, params })}\n`);
 }
 
+function writeJsonRpcResponse(id: string | number, result: unknown): void {
+ process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id, result })}\n`);
+}
+
 process.once("SIGTERM", () => {
  logExit("SIGTERM");
  process.exit(0);
@@ -300,9 +316,33 @@ const program = Effect.gen(function* () {
  Effect.sync(() => {
  parameterizedModelPicker =
  request.clientCapabilities?._meta?.parameterizedModelPicker === true;
+ // #4109-class: unsolicited response with non-numeric id must not crash the client.
+ if (process.env.T3_ACP_EMIT_SKILLS_RELOAD_ID === "1") {
+ queueMicrotask(() => {
+ writeJsonRpcResponse("skills-reload", { ok: true });
+ });
+ }
+ const initMeta =
+ process.env.T3_ACP_EMIT_INIT_AVAILABLE_COMMANDS === "1"
+ ? {
+ availableCommands: [
+ {
+ name: "compact",
+ description: "Compress conversation history",
+ input: { hint: "optional context" },
+ },
+ {
+ name: "session-info",
+ description: "Show session details",
+ input: null,
+ },
+ ],
+ }
+ : undefined;
  return {
  protocolVersion: 1,
  agentCapabilities: { loadSession: true },
+ ...(initMeta ? { _meta: initMeta } : {}),
  };
  }),
  );
@@ -465,6 +505,21 @@ const program = Effect.gen(function* () {
  return yield* AcpError.AcpRequestError.internalError("Mock prompt failure");
  }
 
+ // Mirror real Grok: `/compact` is handled as a prompt and emits auto_compact_completed.
+ const promptText = promptTextFromRequest(request).trim();
+ if (/^\/compact(?:\s|$)/i.test(promptText)) {
+ writeJsonRpcNotification("_x.ai/session_notification", {
+ sessionId: requestedSessionId,
+ update: {
+ sessionUpdate: "auto_compact_completed",
+ tokens_before: 12_000,
+ tokens_after: 4_000,
+ summary_preview: null,
+ },
+ });
+ return { stopReason: "end_turn" };
+ }
+
  if (emitStaleXAiPromptCompleteBeforeSecondHang && promptCount === 1) {
  return {
  stopReason: "end_turn",
@@ -865,6 +920,16 @@ const program = Effect.gen(function* () {
  },
  });
 
+ if (emitSessionInfoUpdate) {
+ yield* agent.client.sessionUpdate({
+ sessionId: requestedSessionId,
+ update: {
+ sessionUpdate: "session_info_update",
+ title: "Mock Grok session title",
+ },
+ });
+ }
+
  yield* agent.client.sessionUpdate({
  sessionId: requestedSessionId,
  update: {
@@ -873,7 +938,17 @@ const program = Effect.gen(function* () {
  },
  });
 
- return { stopReason: "end_turn" };
+ // Live Grok stamps usage on prompt result `_meta` (not only usage_update).
+ return {
+ stopReason: "end_turn",
+ _meta: {
+ totalTokens: 12_345,
+ inputTokens: 10_000,
+ outputTokens: 2_000,
+ cachedReadTokens: 8_000,
+ reasoningTokens: 345,
+ },
+ };
  }),
  );
 

apps/server/src/provider/Layers/CursorAdapter.ts

@@ -57,6 +57,7 @@ import {
  makeAcpPlanUpdatedEvent,
  makeAcpRequestOpenedEvent,
  makeAcpRequestResolvedEvent,
+ makeAcpTokenUsageEvent,
  makeAcpToolCallEvent,
 } from "../acp/AcpCoreRuntimeEvents.ts";
 import {
@@ -863,6 +864,28 @@ export function makeCursorAdapter(
  turnId: ctx.activeTurnId,
  ...(event.itemId ? { itemId: event.itemId } : {}),
  text: event.text,
+ streamKind: event.streamKind,
+ rawPayload: event.rawPayload,
+ }),
+ );
+ return;
+ case "UsageUpdated":
+ // Shared ACP consumer for usage_update (parser → runtime event).
+ // Same wiring pattern as ContentDelta/streamKind so the helper is live.
+ yield* logNative(
+ ctx.threadId,
+ "session/update",
+ event.rawPayload,
+ "acp.jsonrpc",
+ );
+ yield* offerRuntimeEvent(
+ makeAcpTokenUsageEvent({
+ stamp: yield* makeEventStamp(),
+ provider: PROVIDER,
+ threadId: ctx.threadId,
+ turnId: ctx.activeTurnId,
+ usedTokens: event.usage.used,
+ ...(event.usage.size > 0 ? { maxTokens: event.usage.size } : {}),
  rawPayload: event.rawPayload,
  }),
  );

apps/server/src/provider/acp/AcpCoreRuntimeEvents.test.ts

@@ -7,6 +7,7 @@ import {
  makeAcpPlanUpdatedEvent,
  makeAcpRequestOpenedEvent,
  makeAcpRequestResolvedEvent,
+ makeAcpTokenUsageEvent,
  makeAcpToolCallEvent,
 } from "./AcpCoreRuntimeEvents.ts";
 
@@ -124,16 +125,64 @@ describe("AcpCoreRuntimeEvents", () => {
  turnId,
  itemId: "assistant:session-1:segment:0",
  text: "hello",
+ streamKind: "reasoning_text",
  rawPayload: { sessionId: "session-1" },
  }),
  ).toMatchObject({
  type: "content.delta",
  itemId: "assistant:session-1:segment:0",
  payload: {
+ streamKind: "reasoning_text",
  delta: "hello",
  },
  });
 
+ const usageWithoutCompact = makeAcpTokenUsageEvent({
+ stamp,
+ provider: ProviderDriverKind.make("cursor"),
+ threadId: "thread-1" as never,
+ turnId,
+ usedTokens: 1200,
+ maxTokens: 256_000,
+ rawPayload: {
+ sessionId: "session-1",
+ update: { sessionUpdate: "usage_update", used: 1200, size: 256_000 },
+ },
+ });
+ expect(usageWithoutCompact).toMatchObject({
+ type: "thread.token-usage.updated",
+ payload: {
+ usage: {
+ usedTokens: 1200,
+ lastUsedTokens: 1200,
+ maxTokens: 256_000,
+ },
+ },
+ });
+ // Generic ACP must not hardcode auto-compact; omit when unknown.
+ expect(
+ (usageWithoutCompact as { payload: { usage: Record<string, unknown> } }).payload.usage
+ .compactsAutomatically,
+ ).toBeUndefined();
+
+ const usageWithCompact = makeAcpTokenUsageEvent({
+ stamp,
+ provider: ProviderDriverKind.make("cursor"),
+ threadId: "thread-1" as never,
+ turnId,
+ usedTokens: 1200,
+ maxTokens: 256_000,
+ compactsAutomatically: true,
+ rawPayload: {
+ sessionId: "session-1",
+ update: { sessionUpdate: "usage_update", used: 1200, size: 256_000 },
+ },
+ });
+ expect(
+ (usageWithCompact as { payload: { usage: Record<string, unknown> } }).payload.usage
+ .compactsAutomatically,
+ ).toBe(true);
+
  expect(
  makeAcpAssistantItemEvent({
  stamp,

apps/server/src/provider/acp/AcpCoreRuntimeEvents.ts

@@ -220,6 +220,7 @@ export function makeAcpContentDeltaEvent(input: {
  readonly turnId: TurnId | undefined;
  readonly itemId?: string;
  readonly text: string;
+ readonly streamKind?: "assistant_text" | "reasoning_text";
  readonly rawPayload: unknown;
 }): ProviderRuntimeEvent {
  return {
@@ -230,7 +231,7 @@ export function makeAcpContentDeltaEvent(input: {
  turnId: input.turnId,
  ...(input.itemId ? { itemId: RuntimeItemId.make(input.itemId) } : {}),
  payload: {
- streamKind: "assistant_text",
+ streamKind: input.streamKind ?? "assistant_text",
  delta: input.text,
  },
  raw: {
@@ -240,3 +241,65 @@ export function makeAcpContentDeltaEvent(input: {
  },
  };
 }
+
+export function makeAcpTokenUsageEvent(input: {
+ readonly stamp: AcpEventStamp;
+ readonly provider: ProviderDriverKind;
+ readonly threadId: ThreadId;
+ readonly turnId: TurnId | undefined;
+ readonly usedTokens: number;
+ readonly maxTokens?: number;
+ readonly inputTokens?: number;
+ readonly outputTokens?: number;
+ readonly cachedInputTokens?: number;
+ readonly reasoningOutputTokens?: number;
+ /**
+ * Only set when the agent/provider is known to auto-compact.
+ * Generic ACP (e.g. Cursor) often does not; omit when unknown so UI defaults to false.
+ */
+ readonly compactsAutomatically?: boolean;
+ readonly rawPayload: unknown;
+ readonly source?: AcpAdapterRawSource;
+ readonly method?: string;
+}): ProviderRuntimeEvent {
+ return {
+ type: "thread.token-usage.updated",
+ ...input.stamp,
+ provider: input.provider,
+ threadId: input.threadId,
+ turnId: input.turnId,
+ payload: {
+ usage: {
+ usedTokens: input.usedTokens,
+ lastUsedTokens: input.usedTokens,
+ ...(input.maxTokens !== undefined && input.maxTokens > 0
+ ? { maxTokens: input.maxTokens }
+ : {}),
+ ...(input.inputTokens !== undefined ? { inputTokens: input.inputTokens } : {}),
+ ...(input.outputTokens !== undefined ? { outputTokens: input.outputTokens } : {}),
+ ...(input.cachedInputTokens !== undefined
+ ? { cachedInputTokens: input.cachedInputTokens }
+ : {}),
+ ...(input.reasoningOutputTokens !== undefined
+ ? { reasoningOutputTokens: input.reasoningOutputTokens }
+ : {}),
+ ...(input.inputTokens !== undefined ? { lastInputTokens: input.inputTokens } : {}),
+ ...(input.outputTokens !== undefined ? { lastOutputTokens: input.outputTokens } : {}),
+ ...(input.cachedInputTokens !== undefined
+ ? { lastCachedInputTokens: input.cachedInputTokens }
+ : {}),
+ ...(input.reasoningOutputTokens !== undefined
+ ? { lastReasoningOutputTokens: input.reasoningOutputTokens }
+ : {}),
+ ...(input.compactsAutomatically !== undefined
+ ? { compactsAutomatically: input.compactsAutomatically }
+ : {}),
+ },
+ },
+ raw: {
+ source: input.source ?? "acp.jsonrpc",
+ method: input.method ?? "session/update",
+ payload: input.rawPayload,
+ },
+ };
+}

apps/server/scripts/acp-mock-agent.ts

@@ -38,6 +38,7 @@ const emitOverlappingXAiPromptCompleteOutOfOrder =
 const failPrompt = process.env.T3_ACP_FAIL_PROMPT === "1";
 const failSetConfigOption = process.env.T3_ACP_FAIL_SET_CONFIG_OPTION === "1";
 const exitOnSetConfigOption = process.env.T3_ACP_EXIT_ON_SET_CONFIG_OPTION === "1";
+const emitSessionInfoUpdate = process.env.T3_ACP_EMIT_SESSION_INFO === "1";
 const promptResponseText = process.env.T3_ACP_PROMPT_RESPONSE_TEXT;
 const promptDelayMs = Number(process.env.T3_ACP_PROMPT_DELAY_MS ?? "0");
 const permissionOptionIds = {
@@ -68,6 +69,17 @@ function promptIdFromRequestMeta(
  return typeof promptId === "string" && promptId.length > 0 ? promptId : undefined;
 }
 
+function promptTextFromRequest(request: AcpSchema.PromptRequest): string {
+ const parts = Array.isArray(request.prompt) ? request.prompt : [];
+ return parts
+ .flatMap((part) =>
+ part && typeof part === "object" && "type" in part && part.type === "text" && "text" in part
+ ? [String(part.text)]
+ : [],
+ )
+ .join("");
+}
+
 function logExit(reason: string): void {
  if (!exitLogPath) {
  return;
@@ -79,6 +91,10 @@ function writeJsonRpcNotification(method: string, params: unknown): void {
  process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", method, params })}\n`);
 }
 
+function writeJsonRpcResponse(id: string | number, result: unknown): void {
+ process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id, result })}\n`);
+}
+
 process.once("SIGTERM", () => {
  logExit("SIGTERM");
  process.exit(0);
@@ -300,9 +316,33 @@ const program = Effect.gen(function* () {
  Effect.sync(() => {
  parameterizedModelPicker =
  request.clientCapabilities?._meta?.parameterizedModelPicker === true;
+ // #4109-class: unsolicited response with non-numeric id must not crash the client.
+ if (process.env.T3_ACP_EMIT_SKILLS_RELOAD_ID === "1") {
+ queueMicrotask(() => {
+ writeJsonRpcResponse("skills-reload", { ok: true });
+ });
+ }
+ const initMeta =
+ process.env.T3_ACP_EMIT_INIT_AVAILABLE_COMMANDS === "1"
+ ? {
+ availableCommands: [
+ {
+ name: "compact",
+ description: "Compress conversation history",
+ input: { hint: "optional context" },
+ },
+ {
+ name: "session-info",
+ description: "Show session details",
+ input: null,
+ },
+ ],
+ }
+ : undefined;
  return {
  protocolVersion: 1,
  agentCapabilities: { loadSession: true },
+ ...(initMeta ? { _meta: initMeta } : {}),
  };
  }),
  );
@@ -465,6 +505,21 @@ const program = Effect.gen(function* () {
  return yield* AcpError.AcpRequestError.internalError("Mock prompt failure");
  }
 
+ // Mirror real Grok: `/compact` is handled as a prompt and emits auto_compact_completed.
+ const promptText = promptTextFromRequest(request).trim();
+ if (/^\/compact(?:\s|$)/i.test(promptText)) {
+ writeJsonRpcNotification("_x.ai/session_notification", {
+ sessionId: requestedSessionId,
+ update: {
+ sessionUpdate: "auto_compact_completed",
+ tokens_before: 12_000,
+ tokens_after: 4_000,
+ summary_preview: null,
+ },
+ });
+ return { stopReason: "end_turn" };
+ }
+
  if (emitStaleXAiPromptCompleteBeforeSecondHang && promptCount === 1) {
  return {
  stopReason: "end_turn",
@@ -865,6 +920,16 @@ const program = Effect.gen(function* () {
  },
  });
 
+ if (emitSessionInfoUpdate) {
+ yield* agent.client.sessionUpdate({
+ sessionId: requestedSessionId,
+ update: {
+ sessionUpdate: "session_info_update",
+ title: "Mock Grok session title",
+ },
+ });
+ }
+
  yield* agent.client.sessionUpdate({
  sessionId: requestedSessionId,
  update: {
@@ -873,7 +938,17 @@ const program = Effect.gen(function* () {
  },
  });
 
- return { stopReason: "end_turn" };
+ // Live Grok stamps usage on prompt result `_meta` (not only usage_update).
+ return {
+ stopReason: "end_turn",
+ _meta: {
+ totalTokens: 12_345,
+ inputTokens: 10_000,
+ outputTokens: 2_000,
+ cachedReadTokens: 8_000,
+ reasoningTokens: 345,
+ },
+ };
  }),
  );
 

apps/server/src/provider/Layers/CursorAdapter.ts

@@ -57,6 +57,7 @@ import {
  makeAcpPlanUpdatedEvent,
  makeAcpRequestOpenedEvent,
  makeAcpRequestResolvedEvent,
+ makeAcpTokenUsageEvent,
  makeAcpToolCallEvent,
 } from "../acp/AcpCoreRuntimeEvents.ts";
 import {
@@ -863,6 +864,28 @@ export function makeCursorAdapter(
  turnId: ctx.activeTurnId,
  ...(event.itemId ? { itemId: event.itemId } : {}),
  text: event.text,
+ streamKind: event.streamKind,
+ rawPayload: event.rawPayload,
+ }),
+ );
+ return;
+ case "UsageUpdated":
+ // Shared ACP consumer for usage_update (parser → runtime event).
+ // Same wiring pattern as ContentDelta/streamKind so the helper is live.
+ yield* logNative(
+ ctx.threadId,
+ "session/update",
+ event.rawPayload,
+ "acp.jsonrpc",
+ );
+ yield* offerRuntimeEvent(
+ makeAcpTokenUsageEvent({
+ stamp: yield* makeEventStamp(),
+ provider: PROVIDER,
+ threadId: ctx.threadId,
+ turnId: ctx.activeTurnId,
+ usedTokens: event.usage.used,
+ ...(event.usage.size > 0 ? { maxTokens: event.usage.size } : {}),
  rawPayload: event.rawPayload,
  }),
  );

apps/server/src/provider/acp/AcpCoreRuntimeEvents.test.ts

@@ -7,6 +7,7 @@ import {
  makeAcpPlanUpdatedEvent,
  makeAcpRequestOpenedEvent,
  makeAcpRequestResolvedEvent,
+ makeAcpTokenUsageEvent,
  makeAcpToolCallEvent,
 } from "./AcpCoreRuntimeEvents.ts";
 
@@ -124,16 +125,64 @@ describe("AcpCoreRuntimeEvents", () => {
  turnId,
  itemId: "assistant:session-1:segment:0",
  text: "hello",
+ streamKind: "reasoning_text",
  rawPayload: { sessionId: "session-1" },
  }),
  ).toMatchObject({
  type: "content.delta",
  itemId: "assistant:session-1:segment:0",
  payload: {
+ streamKind: "reasoning_text",
  delta: "hello",
  },
  });
 
+ const usageWithoutCompact = makeAcpTokenUsageEvent({
+ stamp,
+ provider: ProviderDriverKind.make("cursor"),
+ threadId: "thread-1" as never,
+ turnId,
+ usedTokens: 1200,
+ maxTokens: 256_000,
+ rawPayload: {
+ sessionId: "session-1",
+ update: { sessionUpdate: "usage_update", used: 1200, size: 256_000 },
+ },
+ });
+ expect(usageWithoutCompact).toMatchObject({
+ type: "thread.token-usage.updated",
+ payload: {
+ usage: {
+ usedTokens: 1200,
+ lastUsedTokens: 1200,
+ maxTokens: 256_000,
+ },
+ },
+ });
+ // Generic ACP must not hardcode auto-compact; omit when unknown.
+ expect(
+ (usageWithoutCompact as { payload: { usage: Record<string, unknown> } }).payload.usage
+ .compactsAutomatically,
+ ).toBeUndefined();
+
+ const usageWithCompact = makeAcpTokenUsageEvent({
+ stamp,
+ provider: ProviderDriverKind.make("cursor"),
+ threadId: "thread-1" as never,
+ turnId,
+ usedTokens: 1200,
+ maxTokens: 256_000,
+ compactsAutomatically: true,
+ rawPayload: {
+ sessionId: "session-1",
+ update: { sessionUpdate: "usage_update", used: 1200, size: 256_000 },
+ },
+ });
+ expect(
+ (usageWithCompact as { payload: { usage: Record<string, unknown> } }).payload.usage
+ .compactsAutomatically,
+ ).toBe(true);
+
  expect(
  makeAcpAssistantItemEvent({
  stamp,

apps/server/src/provider/acp/AcpCoreRuntimeEvents.ts

@@ -220,6 +220,7 @@ export function makeAcpContentDeltaEvent(input: {
  readonly turnId: TurnId | undefined;
  readonly itemId?: string;
  readonly text: string;
+ readonly streamKind?: "assistant_text" | "reasoning_text";
  readonly rawPayload: unknown;
 }): ProviderRuntimeEvent {
  return {
@@ -230,7 +231,7 @@ export function makeAcpContentDeltaEvent(input: {
  turnId: input.turnId,
  ...(input.itemId ? { itemId: RuntimeItemId.make(input.itemId) } : {}),
  payload: {
- streamKind: "assistant_text",
+ streamKind: input.streamKind ?? "assistant_text",
  delta: input.text,
  },
  raw: {
@@ -240,3 +241,65 @@ export function makeAcpContentDeltaEvent(input: {
  },
  };
 }
+
+export function makeAcpTokenUsageEvent(input: {
+ readonly stamp: AcpEventStamp;
+ readonly provider: ProviderDriverKind;
+ readonly threadId: ThreadId;
+ readonly turnId: TurnId | undefined;
+ readonly usedTokens: number;
+ readonly maxTokens?: number;
+ readonly inputTokens?: number;
+ readonly outputTokens?: number;
+ readonly cachedInputTokens?: number;
+ readonly reasoningOutputTokens?: number;
+ /**
+ * Only set when the agent/provider is known to auto-compact.
+ * Generic ACP (e.g. Cursor) often does not; omit when unknown so UI defaults to false.
+ */
+ readonly compactsAutomatically?: boolean;
+ readonly rawPayload: unknown;
+ readonly source?: AcpAdapterRawSource;
+ readonly method?: string;
+}): ProviderRuntimeEvent {
+ return {
+ type: "thread.token-usage.updated",
+ ...input.stamp,
+ provider: input.provider,
+ threadId: input.threadId,
+ turnId: input.turnId,
+ payload: {
+ usage: {
+ usedTokens: input.usedTokens,
+ lastUsedTokens: input.usedTokens,
+ ...(input.maxTokens !== undefined && input.maxTokens > 0
+ ? { maxTokens: input.maxTokens }
+ : {}),
+ ...(input.inputTokens !== undefined ? { inputTokens: input.inputTokens } : {}),
+ ...(input.outputTokens !== undefined ? { outputTokens: input.outputTokens } : {}),
+ ...(input.cachedInputTokens !== undefined
+ ? { cachedInputTokens: input.cachedInputTokens }
+ : {}),
+ ...(input.reasoningOutputTokens !== undefined
+ ? { reasoningOutputTokens: input.reasoningOutputTokens }
+ : {}),
+ ...(input.inputTokens !== undefined ? { lastInputTokens: input.inputTokens } : {}),
+ ...(input.outputTokens !== undefined ? { lastOutputTokens: input.outputTokens } : {}),
+ ...(input.cachedInputTokens !== undefined
+ ? { lastCachedInputTokens: input.cachedInputTokens }
+ : {}),
+ ...(input.reasoningOutputTokens !== undefined
+ ? { lastReasoningOutputTokens: input.reasoningOutputTokens }
+ : {}),
+ ...(input.compactsAutomatically !== undefined
+ ? { compactsAutomatically: input.compactsAutomatically }
+ : {}),
+ },
+ },
+ raw: {
+ source: input.source ?? "acp.jsonrpc",
+ method: input.method ?? "session/update",
+ payload: input.rawPayload,
+ },
+ };
+}

apps/server/scripts/acp-mock-agent.ts

@@ -38,6 +38,7 @@ const emitOverlappingXAiPromptCompleteOutOfOrder =
 const failPrompt = process.env.T3_ACP_FAIL_PROMPT === "1";
 const failSetConfigOption = process.env.T3_ACP_FAIL_SET_CONFIG_OPTION === "1";
 const exitOnSetConfigOption = process.env.T3_ACP_EXIT_ON_SET_CONFIG_OPTION === "1";
+const emitSessionInfoUpdate = process.env.T3_ACP_EMIT_SESSION_INFO === "1";
 const promptResponseText = process.env.T3_ACP_PROMPT_RESPONSE_TEXT;
 const promptDelayMs = Number(process.env.T3_ACP_PROMPT_DELAY_MS ?? "0");
 const permissionOptionIds = {
@@ -68,6 +69,17 @@ function promptIdFromRequestMeta(
  return typeof promptId === "string" && promptId.length > 0 ? promptId : undefined;
 }
 
+function promptTextFromRequest(request: AcpSchema.PromptRequest): string {
+ const parts = Array.isArray(request.prompt) ? request.prompt : [];
+ return parts
+ .flatMap((part) =>
+ part && typeof part === "object" && "type" in part && part.type === "text" && "text" in part
+ ? [String(part.text)]
+ : [],
+ )
+ .join("");
+}
+
 function logExit(reason: string): void {
  if (!exitLogPath) {
  return;
@@ -79,6 +91,10 @@ function writeJsonRpcNotification(method: string, params: unknown): void {
  process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", method, params })}\n`);
 }
 
+function writeJsonRpcResponse(id: string | number, result: unknown): void {
+ process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id, result })}\n`);
+}
+
 process.once("SIGTERM", () => {
  logExit("SIGTERM");
  process.exit(0);
@@ -300,9 +316,33 @@ const program = Effect.gen(function* () {
  Effect.sync(() => {
  parameterizedModelPicker =
  request.clientCapabilities?._meta?.parameterizedModelPicker === true;
+ // #4109-class: unsolicited response with non-numeric id must not crash the client.
+ if (process.env.T3_ACP_EMIT_SKILLS_RELOAD_ID === "1") {
+ queueMicrotask(() => {
+ writeJsonRpcResponse("skills-reload", { ok: true });
+ });
+ }
+ const initMeta =
+ process.env.T3_ACP_EMIT_INIT_AVAILABLE_COMMANDS === "1"
+ ? {
+ availableCommands: [
+ {
+ name: "compact",
+ description: "Compress conversation history",
+ input: { hint: "optional context" },
+ },
+ {
+ name: "session-info",
+ description: "Show session details",
+ input: null,
+ },
+ ],
+ }
+ : undefined;
  return {
  protocolVersion: 1,
  agentCapabilities: { loadSession: true },
+ ...(initMeta ? { _meta: initMeta } : {}),
  };
  }),
  );
@@ -465,6 +505,21 @@ const program = Effect.gen(function* () {
  return yield* AcpError.AcpRequestError.internalError("Mock prompt failure");
  }
 
+ // Mirror real Grok: `/compact` is handled as a prompt and emits auto_compact_completed.
+ const promptText = promptTextFromRequest(request).trim();
+ if (/^\/compact(?:\s|$)/i.test(promptText)) {
+ writeJsonRpcNotification("_x.ai/session_notification", {
+ sessionId: requestedSessionId,
+ update: {
+ sessionUpdate: "auto_compact_completed",
+ tokens_before: 12_000,
+ tokens_after: 4_000,
+ summary_preview: null,
+ },
+ });
+ return { stopReason: "end_turn" };
+ }
+
  if (emitStaleXAiPromptCompleteBeforeSecondHang && promptCount === 1) {
  return {
  stopReason: "end_turn",
@@ -865,6 +920,16 @@ const program = Effect.gen(function* () {
  },
  });
 
+ if (emitSessionInfoUpdate) {
+ yield* agent.client.sessionUpdate({
+ sessionId: requestedSessionId,
+ update: {
+ sessionUpdate: "session_info_update",
+ title: "Mock Grok session title",
+ },
+ });
+ }
+
  yield* agent.client.sessionUpdate({
  sessionId: requestedSessionId,
  update: {
@@ -873,7 +938,17 @@ const program = Effect.gen(function* () {
  },
  });
 
- return { stopReason: "end_turn" };
+ // Live Grok stamps usage on prompt result `_meta` (not only usage_update).
+ return {
+ stopReason: "end_turn",
+ _meta: {
+ totalTokens: 12_345,
+ inputTokens: 10_000,
+ outputTokens: 2_000,
+ cachedReadTokens: 8_000,
+ reasoningTokens: 345,
+ },
+ };
  }),
  );
 

apps/server/src/provider/Layers/CursorAdapter.ts

@@ -57,6 +57,7 @@ import {
  makeAcpPlanUpdatedEvent,
  makeAcpRequestOpenedEvent,
  makeAcpRequestResolvedEvent,
+ makeAcpTokenUsageEvent,
  makeAcpToolCallEvent,
 } from "../acp/AcpCoreRuntimeEvents.ts";
 import {
@@ -863,6 +864,28 @@ export function makeCursorAdapter(
  turnId: ctx.activeTurnId,
  ...(event.itemId ? { itemId: event.itemId } : {}),
  text: event.text,
+ streamKind: event.streamKind,
+ rawPayload: event.rawPayload,
+ }),
+ );
+ return;
+ case "UsageUpdated":
+ // Shared ACP consumer for usage_update (parser → runtime event).
+ // Same wiring pattern as ContentDelta/streamKind so the helper is live.
+ yield* logNative(
+ ctx.threadId,
+ "session/update",
+ event.rawPayload,
+ "acp.jsonrpc",
+ );
+ yield* offerRuntimeEvent(
+ makeAcpTokenUsageEvent({
+ stamp: yield* makeEventStamp(),
+ provider: PROVIDER,
+ threadId: ctx.threadId,
+ turnId: ctx.activeTurnId,
+ usedTokens: event.usage.used,
+ ...(event.usage.size > 0 ? { maxTokens: event.usage.size } : {}),
  rawPayload: event.rawPayload,
  }),
  );

apps/server/src/provider/acp/AcpCoreRuntimeEvents.test.ts

@@ -7,6 +7,7 @@ import {
  makeAcpPlanUpdatedEvent,
  makeAcpRequestOpenedEvent,
  makeAcpRequestResolvedEvent,
+ makeAcpTokenUsageEvent,
  makeAcpToolCallEvent,
 } from "./AcpCoreRuntimeEvents.ts";
 
@@ -124,16 +125,64 @@ describe("AcpCoreRuntimeEvents", () => {
  turnId,
  itemId: "assistant:session-1:segment:0",
  text: "hello",
+ streamKind: "reasoning_text",
  rawPayload: { sessionId: "session-1" },
  }),
  ).toMatchObject({
  type: "content.delta",
  itemId: "assistant:session-1:segment:0",
  payload: {
+ streamKind: "reasoning_text",
  delta: "hello",
  },
  });
 
+ const usageWithoutCompact = makeAcpTokenUsageEvent({
+ stamp,
+ provider: ProviderDriverKind.make("cursor"),
+ threadId: "thread-1" as never,
+ turnId,
+ usedTokens: 1200,
+ maxTokens: 256_000,
+ rawPayload: {
+ sessionId: "session-1",
+ update: { sessionUpdate: "usage_update", used: 1200, size: 256_000 },
+ },
+ });
+ expect(usageWithoutCompact).toMatchObject({
+ type: "thread.token-usage.updated",
+ payload: {
+ usage: {
+ usedTokens: 1200,
+ lastUsedTokens: 1200,
+ maxTokens: 256_000,
+ },
+ },
+ });
+ // Generic ACP must not hardcode auto-compact; omit when unknown.
+ expect(
+ (usageWithoutCompact as { payload: { usage: Record<string, unknown> } }).payload.usage
+ .compactsAutomatically,
+ ).toBeUndefined();
+
+ const usageWithCompact = makeAcpTokenUsageEvent({
+ stamp,
+ provider: ProviderDriverKind.make("cursor"),
+ threadId: "thread-1" as never,
+ turnId,
+ usedTokens: 1200,
+ maxTokens: 256_000,
+ compactsAutomatically: true,
+ rawPayload: {
+ sessionId: "session-1",
+ update: { sessionUpdate: "usage_update", used: 1200, size: 256_000 },
+ },
+ });
+ expect(
+ (usageWithCompact as { payload: { usage: Record<string, unknown> } }).payload.usage
+ .compactsAutomatically,
+ ).toBe(true);
+
  expect(
  makeAcpAssistantItemEvent({
  stamp,

apps/server/src/provider/acp/AcpCoreRuntimeEvents.ts

@@ -220,6 +220,7 @@ export function makeAcpContentDeltaEvent(input: {
  readonly turnId: TurnId | undefined;
  readonly itemId?: string;
  readonly text: string;
+ readonly streamKind?: "assistant_text" | "reasoning_text";
  readonly rawPayload: unknown;
 }): ProviderRuntimeEvent {
  return {
@@ -230,7 +231,7 @@ export function makeAcpContentDeltaEvent(input: {
  turnId: input.turnId,
  ...(input.itemId ? { itemId: RuntimeItemId.make(input.itemId) } : {}),
  payload: {
- streamKind: "assistant_text",
+ streamKind: input.streamKind ?? "assistant_text",
  delta: input.text,
  },
  raw: {
@@ -240,3 +241,65 @@ export function makeAcpContentDeltaEvent(input: {
  },
  };
 }
+
+export function makeAcpTokenUsageEvent(input: {
+ readonly stamp: AcpEventStamp;
+ readonly provider: ProviderDriverKind;
+ readonly threadId: ThreadId;
+ readonly turnId: TurnId | undefined;
+ readonly usedTokens: number;
+ readonly maxTokens?: number;
+ readonly inputTokens?: number;
+ readonly outputTokens?: number;
+ readonly cachedInputTokens?: number;
+ readonly reasoningOutputTokens?: number;
+ /**
+ * Only set when the agent/provider is known to auto-compact.
+ * Generic ACP (e.g. Cursor) often does not; omit when unknown so UI defaults to false.
+ */
+ readonly compactsAutomatically?: boolean;
+ readonly rawPayload: unknown;
+ readonly source?: AcpAdapterRawSource;
+ readonly method?: string;
+}): ProviderRuntimeEvent {
+ return {
+ type: "thread.token-usage.updated",
+ ...input.stamp,
+ provider: input.provider,
+ threadId: input.threadId,
+ turnId: input.turnId,
+ payload: {
+ usage: {
+ usedTokens: input.usedTokens,
+ lastUsedTokens: input.usedTokens,
+ ...(input.maxTokens !== undefined && input.maxTokens > 0
+ ? { maxTokens: input.maxTokens }
+ : {}),
+ ...(input.inputTokens !== undefined ? { inputTokens: input.inputTokens } : {}),
+ ...(input.outputTokens !== undefined ? { outputTokens: input.outputTokens } : {}),
+ ...(input.cachedInputTokens !== undefined
+ ? { cachedInputTokens: input.cachedInputTokens }
+ : {}),
+ ...(input.reasoningOutputTokens !== undefined
+ ? { reasoningOutputTokens: input.reasoningOutputTokens }
+ : {}),
+ ...(input.inputTokens !== undefined ? { lastInputTokens: input.inputTokens } : {}),
+ ...(input.outputTokens !== undefined ? { lastOutputTokens: input.outputTokens } : {}),
+ ...(input.cachedInputTokens !== undefined
+ ? { lastCachedInputTokens: input.cachedInputTokens }
+ : {}),
+ ...(input.reasoningOutputTokens !== undefined
+ ? { lastReasoningOutputTokens: input.reasoningOutputTokens }
+ : {}),
+ ...(input.compactsAutomatically !== undefined
+ ? { compactsAutomatically: input.compactsAutomatically }
+ : {}),
+ },
+ },
+ raw: {
+ source: input.source ?? "acp.jsonrpc",
+ method: input.method ?? "session/update",
+ payload: input.rawPayload,
+ },
+ };
+}

apps/server/scripts/acp-mock-agent.ts

@@ -38,6 +38,7 @@ const emitOverlappingXAiPromptCompleteOutOfOrder =
 const failPrompt = process.env.T3_ACP_FAIL_PROMPT === "1";
 const failSetConfigOption = process.env.T3_ACP_FAIL_SET_CONFIG_OPTION === "1";
 const exitOnSetConfigOption = process.env.T3_ACP_EXIT_ON_SET_CONFIG_OPTION === "1";
+const emitSessionInfoUpdate = process.env.T3_ACP_EMIT_SESSION_INFO === "1";
 const promptResponseText = process.env.T3_ACP_PROMPT_RESPONSE_TEXT;
 const promptDelayMs = Number(process.env.T3_ACP_PROMPT_DELAY_MS ?? "0");
 const permissionOptionIds = {
@@ -68,6 +69,17 @@ function promptIdFromRequestMeta(
  return typeof promptId === "string" && promptId.length > 0 ? promptId : undefined;
 }
 
+function promptTextFromRequest(request: AcpSchema.PromptRequest): string {
+ const parts = Array.isArray(request.prompt) ? request.prompt : [];
+ return parts
+ .flatMap((part) =>
+ part && typeof part === "object" && "type" in part && part.type === "text" && "text" in part
+ ? [String(part.text)]
+ : [],
+ )
+ .join("");
+}
+
 function logExit(reason: string): void {
  if (!exitLogPath) {
  return;
@@ -79,6 +91,10 @@ function writeJsonRpcNotification(method: string, params: unknown): void {
  process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", method, params })}\n`);
 }
 
+function writeJsonRpcResponse(id: string | number, result: unknown): void {
+ process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id, result })}\n`);
+}
+
 process.once("SIGTERM", () => {
  logExit("SIGTERM");
  process.exit(0);
@@ -300,9 +316,33 @@ const program = Effect.gen(function* () {
  Effect.sync(() => {
  parameterizedModelPicker =
  request.clientCapabilities?._meta?.parameterizedModelPicker === true;
+ // #4109-class: unsolicited response with non-numeric id must not crash the client.
+ if (process.env.T3_ACP_EMIT_SKILLS_RELOAD_ID === "1") {
+ queueMicrotask(() => {
+ writeJsonRpcResponse("skills-reload", { ok: true });
+ });
+ }
+ const initMeta =
+ process.env.T3_ACP_EMIT_INIT_AVAILABLE_COMMANDS === "1"
+ ? {
+ availableCommands: [
+ {
+ name: "compact",
+ description: "Compress conversation history",
+ input: { hint: "optional context" },
+ },
+ {
+ name: "session-info",
+ description: "Show session details",
+ input: null,
+ },
+ ],
+ }
+ : undefined;
  return {
  protocolVersion: 1,
  agentCapabilities: { loadSession: true },
+ ...(initMeta ? { _meta: initMeta } : {}),
  };
  }),
  );
@@ -465,6 +505,21 @@ const program = Effect.gen(function* () {
  return yield* AcpError.AcpRequestError.internalError("Mock prompt failure");
  }
 
+ // Mirror real Grok: `/compact` is handled as a prompt and emits auto_compact_completed.
+ const promptText = promptTextFromRequest(request).trim();
+ if (/^\/compact(?:\s|$)/i.test(promptText)) {
+ writeJsonRpcNotification("_x.ai/session_notification", {
+ sessionId: requestedSessionId,
+ update: {
+ sessionUpdate: "auto_compact_completed",
+ tokens_before: 12_000,
+ tokens_after: 4_000,
+ summary_preview: null,
+ },
+ });
+ return { stopReason: "end_turn" };
+ }
+
  if (emitStaleXAiPromptCompleteBeforeSecondHang && promptCount === 1) {
  return {
  stopReason: "end_turn",
@@ -865,6 +920,16 @@ const program = Effect.gen(function* () {
  },
  });
 
+ if (emitSessionInfoUpdate) {
+ yield* agent.client.sessionUpdate({
+ sessionId: requestedSessionId,
+ update: {
+ sessionUpdate: "session_info_update",
+ title: "Mock Grok session title",
+ },
+ });
+ }
+
  yield* agent.client.sessionUpdate({
  sessionId: requestedSessionId,
  update: {
@@ -873,7 +938,17 @@ const program = Effect.gen(function* () {
  },
  });
 
- return { stopReason: "end_turn" };
+ // Live Grok stamps usage on prompt result `_meta` (not only usage_update).
+ return {
+ stopReason: "end_turn",
+ _meta: {
+ totalTokens: 12_345,
+ inputTokens: 10_000,
+ outputTokens: 2_000,
+ cachedReadTokens: 8_000,
+ reasoningTokens: 345,
+ },
+ };
  }),
  );
 

apps/server/src/provider/Layers/CursorAdapter.ts

@@ -57,6 +57,7 @@ import {
  makeAcpPlanUpdatedEvent,
  makeAcpRequestOpenedEvent,
  makeAcpRequestResolvedEvent,
+ makeAcpTokenUsageEvent,
  makeAcpToolCallEvent,
 } from "../acp/AcpCoreRuntimeEvents.ts";
 import {
@@ -863,6 +864,28 @@ export function makeCursorAdapter(
  turnId: ctx.activeTurnId,
  ...(event.itemId ? { itemId: event.itemId } : {}),
  text: event.text,
+ streamKind: event.streamKind,
+ rawPayload: event.rawPayload,
+ }),
+ );
+ return;
+ case "UsageUpdated":
+ // Shared ACP consumer for usage_update (parser → runtime event).
+ // Same wiring pattern as ContentDelta/streamKind so the helper is live.
+ yield* logNative(
+ ctx.threadId,
+ "session/update",
+ event.rawPayload,
+ "acp.jsonrpc",
+ );
+ yield* offerRuntimeEvent(
+ makeAcpTokenUsageEvent({
+ stamp: yield* makeEventStamp(),
+ provider: PROVIDER,
+ threadId: ctx.threadId,
+ turnId: ctx.activeTurnId,
+ usedTokens: event.usage.used,
+ ...(event.usage.size > 0 ? { maxTokens: event.usage.size } : {}),
  rawPayload: event.rawPayload,
  }),
  );

apps/server/src/provider/acp/AcpCoreRuntimeEvents.test.ts

@@ -7,6 +7,7 @@ import {
  makeAcpPlanUpdatedEvent,
  makeAcpRequestOpenedEvent,
  makeAcpRequestResolvedEvent,
+ makeAcpTokenUsageEvent,
  makeAcpToolCallEvent,
 } from "./AcpCoreRuntimeEvents.ts";
 
@@ -124,16 +125,64 @@ describe("AcpCoreRuntimeEvents", () => {
  turnId,
  itemId: "assistant:session-1:segment:0",
  text: "hello",
+ streamKind: "reasoning_text",
  rawPayload: { sessionId: "session-1" },
  }),
  ).toMatchObject({
  type: "content.delta",
  itemId: "assistant:session-1:segment:0",
  payload: {
+ streamKind: "reasoning_text",
  delta: "hello",
  },
  });
 
+ const usageWithoutCompact = makeAcpTokenUsageEvent({
+ stamp,
+ provider: ProviderDriverKind.make("cursor"),
+ threadId: "thread-1" as never,
+ turnId,
+ usedTokens: 1200,
+ maxTokens: 256_000,
+ rawPayload: {
+ sessionId: "session-1",
+ update: { sessionUpdate: "usage_update", used: 1200, size: 256_000 },
+ },
+ });
+ expect(usageWithoutCompact).toMatchObject({
+ type: "thread.token-usage.updated",
+ payload: {
+ usage: {
+ usedTokens: 1200,
+ lastUsedTokens: 1200,
+ maxTokens: 256_000,
+ },
+ },
+ });
+ // Generic ACP must not hardcode auto-compact; omit when unknown.
+ expect(
+ (usageWithoutCompact as { payload: { usage: Record<string, unknown> } }).payload.usage
+ .compactsAutomatically,
+ ).toBeUndefined();
+
+ const usageWithCompact = makeAcpTokenUsageEvent({
+ stamp,
+ provider: ProviderDriverKind.make("cursor"),
+ threadId: "thread-1" as never,
+ turnId,
+ usedTokens: 1200,
+ maxTokens: 256_000,
+ compactsAutomatically: true,
+ rawPayload: {
+ sessionId: "session-1",
+ update: { sessionUpdate: "usage_update", used: 1200, size: 256_000 },
+ },
+ });
+ expect(
+ (usageWithCompact as { payload: { usage: Record<string, unknown> } }).payload.usage
+ .compactsAutomatically,
+ ).toBe(true);
+
  expect(
  makeAcpAssistantItemEvent({
  stamp,

apps/server/src/provider/acp/AcpCoreRuntimeEvents.ts

@@ -220,6 +220,7 @@ export function makeAcpContentDeltaEvent(input: {
  readonly turnId: TurnId | undefined;
  readonly itemId?: string;
  readonly text: string;
+ readonly streamKind?: "assistant_text" | "reasoning_text";
  readonly rawPayload: unknown;
 }): ProviderRuntimeEvent {
  return {
@@ -230,7 +231,7 @@ export function makeAcpContentDeltaEvent(input: {
  turnId: input.turnId,
  ...(input.itemId ? { itemId: RuntimeItemId.make(input.itemId) } : {}),
  payload: {
- streamKind: "assistant_text",
+ streamKind: input.streamKind ?? "assistant_text",
  delta: input.text,
  },
  raw: {
@@ -240,3 +241,65 @@ export function makeAcpContentDeltaEvent(input: {
  },
  };
 }
+
+export function makeAcpTokenUsageEvent(input: {
+ readonly stamp: AcpEventStamp;
+ readonly provider: ProviderDriverKind;
+ readonly threadId: ThreadId;
+ readonly turnId: TurnId | undefined;
+ readonly usedTokens: number;
+ readonly maxTokens?: number;
+ readonly inputTokens?: number;
+ readonly outputTokens?: number;
+ readonly cachedInputTokens?: number;
+ readonly reasoningOutputTokens?: number;
+ /**
+ * Only set when the agent/provider is known to auto-compact.
+ * Generic ACP (e.g. Cursor) often does not; omit when unknown so UI defaults to false.
+ */
+ readonly compactsAutomatically?: boolean;
+ readonly rawPayload: unknown;
+ readonly source?: AcpAdapterRawSource;
+ readonly method?: string;
+}): ProviderRuntimeEvent {
+ return {
+ type: "thread.token-usage.updated",
+ ...input.stamp,
+ provider: input.provider,
+ threadId: input.threadId,
+ turnId: input.turnId,
+ payload: {
+ usage: {
+ usedTokens: input.usedTokens,
+ lastUsedTokens: input.usedTokens,
+ ...(input.maxTokens !== undefined && input.maxTokens > 0
+ ? { maxTokens: input.maxTokens }
+ : {}),
+ ...(input.inputTokens !== undefined ? { inputTokens: input.inputTokens } : {}),
+ ...(input.outputTokens !== undefined ? { outputTokens: input.outputTokens } : {}),
+ ...(input.cachedInputTokens !== undefined
+ ? { cachedInputTokens: input.cachedInputTokens }
+ : {}),
+ ...(input.reasoningOutputTokens !== undefined
+ ? { reasoningOutputTokens: input.reasoningOutputTokens }
+ : {}),
+ ...(input.inputTokens !== undefined ? { lastInputTokens: input.inputTokens } : {}),
+ ...(input.outputTokens !== undefined ? { lastOutputTokens: input.outputTokens } : {}),
+ ...(input.cachedInputTokens !== undefined
+ ? { lastCachedInputTokens: input.cachedInputTokens }
+ : {}),
+ ...(input.reasoningOutputTokens !== undefined
+ ? { lastReasoningOutputTokens: input.reasoningOutputTokens }
+ : {}),
+ ...(input.compactsAutomatically !== undefined
+ ? { compactsAutomatically: input.compactsAutomatically }
+ : {}),
+ },
+ },
+ raw: {
+ source: input.source ?? "acp.jsonrpc",
+ method: input.method ?? "session/update",
+ payload: input.rawPayload,
+ },
+ };
+}