feat(cursor): surface shell command text and subagent work in timeline

Advertise `terminal: true` so Cursor issues `terminal/create` requests we
can capture command text from, then merge that into the matching tool_call
event via a new terminal-id hint lookup. Adds defense-in-depth fallbacks
(content[] heuristic, `_meta.command`, alt rawInput keys) on both server
and shared extractors. Wires a `cursor/task` notification handler that
projects the single post-completion notification into paired
`task.started` + `task.completed` events, with a turnId fallback to the
last known turn so late notifications survive the latest-turn filter.

Author: tyulyukov

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

@@ -17,6 +17,8 @@ const emitInterleavedAssistantToolCalls =
   process.env.T3_ACP_EMIT_INTERLEAVED_ASSISTANT_TOOL_CALLS === "1";
 const emitGenericToolPlaceholders = process.env.T3_ACP_EMIT_GENERIC_TOOL_PLACEHOLDERS === "1";
 const emitAskQuestion = process.env.T3_ACP_EMIT_ASK_QUESTION === "1";
+const emitTerminalCreate = process.env.MARCODE_ACP_EMIT_TERMINAL_CREATE === "1";
+const emitCursorTask = process.env.MARCODE_ACP_EMIT_CURSOR_TASK === "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 promptResponseText = process.env.T3_ACP_PROMPT_RESPONSE_TEXT;
@@ -484,6 +486,52 @@ const program = Effect.gen(function* () {
         return { stopReason: "end_turn" };
       }
 
+      if (emitTerminalCreate) {
+        // Mirror the terminal/create → session/update flow Cursor uses when
+        // the client advertises `terminal: true`: spawn a terminal, then emit
+        // a tool_call whose content[] references it by terminalId.
+        const createResponse = yield* agent.client.createTerminal({
+          sessionId: requestedSessionId,
+          command: "cc",
+          args: ["--version"],
+        });
+        yield* agent.client.sessionUpdate({
+          sessionId: requestedSessionId,
+          update: {
+            sessionUpdate: "tool_call",
+            toolCallId: "tool-call-terminal-1",
+            title: "Terminal",
+            kind: "execute",
+            status: "pending",
+            rawInput: {},
+            content: [{ type: "terminal", terminalId: createResponse.terminalId }],
+          },
+        });
+        yield* agent.client.sessionUpdate({
+          sessionId: requestedSessionId,
+          update: {
+            sessionUpdate: "tool_call_update",
+            toolCallId: "tool-call-terminal-1",
+            status: "completed",
+          },
+        });
+        return { stopReason: "end_turn" };
+      }
+
+      if (emitCursorTask) {
+        // Cursor fires `cursor/task` post-completion as a fire-and-forget
+        // notification — the sole observable signal for subagent work.
+        yield* agent.client.extNotification("cursor/task", {
+          toolCallId: "task-subagent-1",
+          description: "Explored BullMQ usages",
+          prompt: "find all bullmq usages",
+          subagentType: "explore",
+          model: "default",
+          durationMs: 1234,
+        });
+        return { stopReason: "end_turn" };
+      }
+
       yield* agent.client.sessionUpdate({
         sessionId: requestedSessionId,
         update: {

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

@@ -1,6 +1,12 @@
 import { describe, expect, it } from "vitest";
 
-import { applyToolCallHint } from "./CursorAdapter.ts";
+import { TurnId } from "@marcode/contracts";
+
+import {
+  applyToolCallHint,
+  resolveEffectiveTurnId,
+  resolveTerminalHintFromToolCall,
+} from "./CursorAdapter.ts";
 import type { AcpToolCallState } from "../acp/AcpRuntimeModel.ts";
 
 // Cursor ACP only emits the real command text in `session/request_permission`
@@ -58,3 +64,100 @@ describe("applyToolCallHint", () => {
     expect(merged.detail).toBe("existing output");
   });
 });
+
+// When Cursor advertises `terminal: true`, it issues a `terminal/create`
+// request that carries the real command + args. The adapter stashes the
+// spawned terminal keyed by terminalId, and subsequent `session/update`
+// tool_call events reference that terminalId in `data.content` via
+// `{ type: "terminal", terminalId }`. `resolveTerminalHintFromToolCall`
+// bridges those two channels: it returns a hint with the captured command so
+// `applyToolCallHint` can merge it into the tool_call state.
+describe("resolveTerminalHintFromToolCall", () => {
+  const terminalState: AcpToolCallState = {
+    toolCallId: "tool-terminal-1",
+    kind: "execute",
+    title: "Ran command",
+    status: "inProgress",
+    data: {
+      toolCallId: "tool-terminal-1",
+      kind: "execute",
+      toolName: "execute",
+      content: [{ type: "terminal", terminalId: "t-1" }],
+    },
+  };
+
+  it("returns undefined when the tool_call has no terminal content ref", () => {
+    expect(
+      resolveTerminalHintFromToolCall(
+        { ...terminalState, data: { ...terminalState.data, content: [] } },
+        new Map([["t-1", { command: "cc --version" }]]),
+      ),
+    ).toBeUndefined();
+  });
+
+  it("returns undefined when the terminalId is not in the terminals map", () => {
+    expect(resolveTerminalHintFromToolCall(terminalState, new Map())).toBeUndefined();
+  });
+
+  it("returns the stored command when the tool_call references a known terminal", () => {
+    const hint = resolveTerminalHintFromToolCall(
+      terminalState,
+      new Map([["t-1", { command: "cc --version" }]]),
+    );
+    expect(hint).toEqual({ command: "cc --version" });
+  });
+
+  it("composes with applyToolCallHint to populate the command on the tool_call state", () => {
+    const hint = resolveTerminalHintFromToolCall(
+      terminalState,
+      new Map([["t-1", { command: "bun run typecheck" }]]),
+    );
+    const merged = applyToolCallHint(terminalState, hint);
+    expect(merged.command).toBe("bun run typecheck");
+    expect(merged.data.command).toBe("bun run typecheck");
+  });
+});
+
+// Cursor fires `cursor/task` as a fire-and-forget notification after the
+// subagent run completes. Depending on timing, `ctx.activeTurnId` may still be
+// the turn that just ended, or may be undefined (e.g. if another code path
+// cleared it, or if the notification arrives between turns). Either way the
+// session-logic filter drops activities whose `turnId !== latestTurnId`, so
+// falling back to the last known turn prevents the subagent work from being
+// silently swallowed by the UI.
+describe("resolveEffectiveTurnId", () => {
+  const turnA = TurnId.make("11111111-1111-1111-1111-111111111111");
+  const turnB = TurnId.make("22222222-2222-2222-2222-222222222222");
+
+  it("returns undefined when no ctx is provided", () => {
+    expect(resolveEffectiveTurnId(undefined)).toBeUndefined();
+  });
+
+  it("prefers the active turn when one is set", () => {
+    expect(resolveEffectiveTurnId({ activeTurnId: turnA, turns: [] })).toBe(turnA);
+    expect(
+      resolveEffectiveTurnId({
+        activeTurnId: turnA,
+        turns: [{ id: turnB }],
+      }),
+    ).toBe(turnA);
+  });
+
+  it("falls back to the last known turn when activeTurnId is undefined", () => {
+    expect(
+      resolveEffectiveTurnId({
+        activeTurnId: undefined,
+        turns: [{ id: turnA }, { id: turnB }],
+      }),
+    ).toBe(turnB);
+  });
+
+  it("returns undefined when there's no active turn and no known turns", () => {
+    expect(
+      resolveEffectiveTurnId({
+        activeTurnId: undefined,
+        turns: [],
+      }),
+    ).toBeUndefined();
+  });
+});

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

@@ -1174,4 +1174,144 @@ cursorAdapterTestLayer("CursorAdapterLive", (it) => {
       yield* adapter.stopSession(threadId);
     }),
   );
+
+  // When the client advertises `terminal: true`, Cursor issues a
+  // `terminal/create` request to run the command, then references the
+  // returned terminalId from the `session/update` tool_call via
+  // `content: [{ type: "terminal", terminalId }]`. The adapter merges the
+  // captured command onto the tool_call event so the CommandExecutionCard
+  // can render the command text instead of a blank "Ran command" pill.
+  it.effect("resolves command text from `terminal/create` into tool_call events", () =>
+    Effect.gen(function* () {
+      const adapter = yield* CursorAdapter;
+      const serverSettings = yield* ServerSettingsService;
+      const threadId = ThreadId.make("cursor-terminal-create-probe");
+      const runtimeEvents: Array<ProviderRuntimeEvent> = [];
+      const itemCompletedReady = yield* Deferred.make<void>();
+
+      const wrapperPath = yield* Effect.promise(() =>
+        makeMockAgentWrapper({ MARCODE_ACP_EMIT_TERMINAL_CREATE: "1" }),
+      );
+      yield* serverSettings.updateSettings({
+        providers: { cursor: { binaryPath: wrapperPath } },
+      });
+
+      yield* Stream.runForEach(adapter.streamEvents, (event) =>
+        Effect.gen(function* () {
+          runtimeEvents.push(event);
+          if (String(event.threadId) !== String(threadId)) return;
+          if (event.type === "item.completed" && event.payload.itemType === "command_execution") {
+            yield* Deferred.succeed(itemCompletedReady, undefined).pipe(Effect.ignore);
+          }
+        }),
+      ).pipe(Effect.forkChild);
+
+      yield* adapter.startSession({
+        threadId,
+        provider: "cursor",
+        cwd: process.cwd(),
+        runtimeMode: "full-access",
+        modelSelection: { provider: "cursor", model: "default" },
+      });
+
+      yield* adapter.sendTurn({
+        threadId,
+        input: "run cc --version",
+        attachments: [],
+      });
+
+      yield* Deferred.await(itemCompletedReady);
+
+      const threadEvents = runtimeEvents.filter(
+        (event) => String(event.threadId) === String(threadId),
+      );
+      const commandEvent = threadEvents.find(
+        (event) =>
+          (event.type === "item.updated" || event.type === "item.completed") &&
+          event.payload.itemType === "command_execution",
+      );
+      assert.isDefined(commandEvent);
+      if (
+        (commandEvent?.type === "item.updated" || commandEvent?.type === "item.completed") &&
+        commandEvent.payload.itemType === "command_execution"
+      ) {
+        const data = commandEvent.payload.data as Record<string, unknown> | undefined;
+        assert.equal(data?.command, "cc --version");
+      }
+
+      yield* adapter.stopSession(threadId);
+    }),
+  );
+
+  // `cursor/task` is a fire-and-forget notification Cursor fires post-
+  // completion, so `ctx.activeTurnId` may be stale. `resolveEffectiveTurnId`
+  // falls back to `ctx.turns.at(-1).id` so the session-logic latest-turn
+  // filter doesn't drop the resulting subagent activity.
+  it.effect("emits task.started/task.completed runtime events for cursor/task", () =>
+    Effect.gen(function* () {
+      const adapter = yield* CursorAdapter;
+      const serverSettings = yield* ServerSettingsService;
+      const threadId = ThreadId.make("cursor-task-probe");
+      const runtimeEvents: Array<ProviderRuntimeEvent> = [];
+      const taskCompletedReady = yield* Deferred.make<void>();
+
+      const wrapperPath = yield* Effect.promise(() =>
+        makeMockAgentWrapper({ MARCODE_ACP_EMIT_CURSOR_TASK: "1" }),
+      );
+      yield* serverSettings.updateSettings({
+        providers: { cursor: { binaryPath: wrapperPath } },
+      });
+
+      yield* Stream.runForEach(adapter.streamEvents, (event) =>
+        Effect.gen(function* () {
+          runtimeEvents.push(event);
+          if (String(event.threadId) !== String(threadId)) return;
+          if (event.type === "task.completed") {
+            yield* Deferred.succeed(taskCompletedReady, undefined).pipe(Effect.ignore);
+          }
+        }),
+      ).pipe(Effect.forkChild);
+
+      yield* adapter.startSession({
+        threadId,
+        provider: "cursor",
+        cwd: process.cwd(),
+        runtimeMode: "full-access",
+        modelSelection: { provider: "cursor", model: "default" },
+      });
+
+      const turn = yield* adapter.sendTurn({
+        threadId,
+        input: "use the explore subagent",
+        attachments: [],
+      });
+
+      yield* Deferred.await(taskCompletedReady);
+
+      const threadEvents = runtimeEvents.filter(
+        (event) => String(event.threadId) === String(threadId),
+      );
+      const taskStartedIndex = threadEvents.findIndex((event) => event.type === "task.started");
+      const taskCompletedIndex = threadEvents.findIndex((event) => event.type === "task.completed");
+      assert.isAtLeast(taskStartedIndex, 0);
+      assert.isAtLeast(taskCompletedIndex, 0);
+      // Effect.yieldNow between the two emissions guarantees the handler
+      // interleaves before offerRuntimeEvent#2 runs — which shows up as
+      // emission-order ordering on the PubSub stream.
+      assert.isBelow(taskStartedIndex, taskCompletedIndex);
+
+      const taskStarted = threadEvents[taskStartedIndex];
+      const taskCompleted = threadEvents[taskCompletedIndex];
+      if (taskStarted?.type === "task.started" && taskCompleted?.type === "task.completed") {
+        assert.equal(String(taskStarted.turnId), String(turn.turnId));
+        assert.equal(String(taskCompleted.turnId), String(turn.turnId));
+        assert.equal(taskStarted.payload.agentType, "explore");
+        assert.equal(taskStarted.payload.toolUseId, "task-subagent-1");
+        assert.equal(taskStarted.payload.prompt, "find all bullmq usages");
+        assert.equal(taskCompleted.payload.status, "completed");
+      }
+
+      yield* adapter.stopSession(threadId);
+    }),
+  );
 });