feat: add auto-mode iteration events

Author: igorcosta

src/__tests__/extension-features-e2e.test.ts

@@ -10,7 +10,7 @@ async function createFeatureCli(options: {
   method: string;
   params: Record<string, unknown>;
   result: unknown;
-  notification?: { method: string; params: Record<string, unknown> };
+  notifications?: Array<{ method: string; params: Record<string, unknown> }>;
 }): Promise<string> {
   const directory = await mkdtemp(join(tmpdir(), 'autohand-ts-features-'));
   temporaryDirectories.push(directory);
@@ -36,11 +36,11 @@ for await (const line of lines) {
         messageCount: 0,
       },
     }) + '\\n');
-    if (fixture.notification !== undefined) {
+    for (const notification of fixture.notifications ?? []) {
       process.stdout.write(JSON.stringify({
         jsonrpc: '2.0',
-        method: fixture.notification.method,
-        params: fixture.notification.params,
+        method: notification.method,
+        params: notification.params,
       }) + '\\n');
     }
     continue;
@@ -80,6 +80,15 @@ async function withSDK<T>(
   }
 }
 
+async function nextNotification(sdk: AutohandSDK) {
+  const events = sdk.events();
+  const next = events.next();
+  await sdk.getState();
+  const event = await next;
+  await events.return(undefined);
+  return event.value;
+}
+
 afterEach(async () => {
   await Promise.all(temporaryDirectories.splice(0).map((directory) =>
     rm(directory, { recursive: true, force: true })
@@ -595,3 +604,58 @@ describe('extension RPC features', () => {
     )).rejects.toThrow(/Invalid RPC result for autohand\.setContextCompact/);
   });
 });
+
+describe('extension notification features', () => {
+  it('streams typed auto-mode iteration events from the spawned CLI', async () => {
+    const notification = {
+      method: 'autohand.automode.iteration',
+      params: {
+        sessionId: 'automode-1',
+        iteration: 3,
+        actions: ['edited src/index.ts', 'ran tests'],
+        tokensUsed: 1_250,
+        timestamp: '2026-07-20T00:03:00.000Z',
+      },
+    };
+    const sentinel = {
+      method: 'autohand.error',
+      params: { code: 500, message: 'sentinel', recoverable: true, timestamp: 'sentinel' },
+    };
+
+    await expect(withSDK({
+      method: 'unused',
+      params: {},
+      result: {},
+      notifications: [notification, sentinel],
+    }, nextNotification)).resolves.toEqual({
+      type: 'automode_iteration',
+      ...notification.params,
+    });
+  });
+
+  it('drops malformed auto-mode iterations without hiding later valid events', async () => {
+    const malformed = {
+      method: 'autohand.automode.iteration',
+      params: {
+        sessionId: 'automode-1',
+        iteration: 'three',
+        actions: [],
+        timestamp: '2026-07-20T00:03:00.000Z',
+      },
+    };
+    const sentinel = {
+      method: 'autohand.error',
+      params: { code: 500, message: 'sentinel', recoverable: true, timestamp: 'sentinel' },
+    };
+
+    await expect(withSDK({
+      method: 'unused',
+      params: {},
+      result: {},
+      notifications: [malformed, sentinel],
+    }, nextNotification)).resolves.toEqual({
+      type: 'error',
+      ...sentinel.params,
+    });
+  });
+});

src/rpc/client.ts

@@ -125,6 +125,7 @@ import type {
 import { detectProviderFromModel, validateProviderConfig, getSkillName, getSkillPath } from '../types/index.js';
 import { validateSessionControlRpcResult } from '../validation/session-control-rpc-results.js';
 import { validateExtensionRpcResult } from '../validation/extension-rpc-results.js';
+import { parseAutomodeIterationEvent } from '../validation/extension-notifications.js';
 
 function scopedDecision(
   allowed: boolean,
@@ -1069,6 +1070,11 @@ export class RPCClient {
       this.queueEvent(event);
     });
 
+    this.transport.onNotification('autohand.automode.iteration', (params) => {
+      const event = parseAutomodeIterationEvent(params);
+      if (event !== undefined) this.queueEvent(event);
+    });
+
     const queueAutoresearchEvent = (phase: AutoresearchLifecycleEvent['phase'], params: unknown): void => {
       const p = params as Omit<AutoresearchLifecycleEvent, 'type' | 'phase'>;
       this.queueEvent({

src/types/index.ts

@@ -2340,10 +2340,20 @@ export type SDKEvent =
   | ToolEndEvent
   | FileModifiedEvent
   | PermissionRequestEvent
+  | AutomodeIterationEvent
   | AutoresearchEvent
   | AutoresearchOperationEvent
   | ErrorEvent;
 
+export interface AutomodeIterationEvent {
+  type: 'automode_iteration';
+  sessionId: string;
+  iteration: number;
+  actions: string[];
+  tokensUsed?: number;
+  timestamp: string;
+}
+
 export interface AutoresearchEvent {
   type: 'autoresearch';
   phase: 'start' | 'status' | 'pause';

src/validation/extension-notifications.ts

@@ -0,0 +1,31 @@
+import type { AutomodeIterationEvent } from '../types/index.js';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((entry) => typeof entry === 'string');
+}
+
+/** Parse a CLI auto-mode iteration notification at the transport trust boundary. */
+export function parseAutomodeIterationEvent(value: unknown): AutomodeIterationEvent | undefined {
+  if (!isRecord(value)
+    || typeof value.sessionId !== 'string'
+    || typeof value.iteration !== 'number'
+    || !Number.isFinite(value.iteration)
+    || !isStringArray(value.actions)
+    || typeof value.timestamp !== 'string'
+    || (value.tokensUsed !== undefined
+      && (typeof value.tokensUsed !== 'number' || !Number.isFinite(value.tokensUsed)))) {
+    return undefined;
+  }
+  return {
+    type: 'automode_iteration',
+    sessionId: value.sessionId,
+    iteration: value.iteration,
+    actions: value.actions,
+    ...(value.tokensUsed !== undefined ? { tokensUsed: value.tokensUsed } : {}),
+    timestamp: value.timestamp,
+  };
+}