remote-codex 0.11.50 → 0.11.52

package/packages/acp/src/extension-registry.ts

@@ -0,0 +1,285 @@
+import { EventEmitter } from 'node:events';
+
+import type { AgentProviderCapabilities } from '../../agent-runtime/src/types';
+import {
+  REMOTE_CODEX_HARNESS_EXTENSION_PROTOCOL,
+  type HarnessExtensionCallEnvelope,
+  type HarnessExtensionDescriptor,
+  type HarnessExtensionErrorEnvelope,
+  type HarnessExtensionEventEnvelope,
+  createHarnessExtensionCall,
+  harnessExtensionMethodName,
+} from './extensions';
+
+interface HarnessExtensionTransport {
+  request(
+    method: string,
+    params: unknown,
+    signal: AbortSignal,
+  ): Promise<unknown>;
+}
+
+interface RegisteredExtension {
+  ownerId: string;
+  descriptor: HarnessExtensionDescriptor;
+  transport: HarnessExtensionTransport;
+  wireMethods: Record<string, string>;
+  capabilityPatch: AgentProviderCapabilityPatch | null;
+  paramMappers: Record<
+    string,
+    (envelope: HarnessExtensionCallEnvelope) => unknown
+  >;
+}
+
+export type AgentProviderCapabilityPatch = {
+  [Section in keyof AgentProviderCapabilities]?: Partial<
+    AgentProviderCapabilities[Section]
+  >;
+};
+
+interface CachedOperation {
+  fingerprint: string;
+  promise: Promise<unknown>;
+}
+
+export class HarnessExtensionInvocationError extends Error {
+  constructor(public readonly payload: HarnessExtensionErrorEnvelope) {
+    super(payload.message);
+    this.name = 'HarnessExtensionInvocationError';
+  }
+}
+
+function extensionKey(extensionId: string, version: number) {
+  return `${extensionId}@${version}`;
+}
+
+function operationFingerprint(input: {
+  extensionId: string;
+  extensionVersion: number;
+  method: string;
+  params: unknown;
+}) {
+  return JSON.stringify(input);
+}
+
+export class HarnessExtensionRegistry extends EventEmitter {
+  private readonly extensions = new Map<string, RegisteredExtension>();
+  private readonly operations = new Map<string, CachedOperation>();
+  private readonly eventSequences = new Set<string>();
+
+  register(input: {
+    ownerId: string;
+    descriptor: HarnessExtensionDescriptor;
+    transport: HarnessExtensionTransport;
+    wireMethods?: Record<string, string>;
+    capabilityPatch?: AgentProviderCapabilityPatch;
+    paramMappers?: Record<
+      string,
+      (envelope: HarnessExtensionCallEnvelope) => unknown
+    >;
+  }) {
+    const key = extensionKey(input.descriptor.id, input.descriptor.version);
+    const existing = this.extensions.get(key);
+    if (existing && existing.ownerId !== input.ownerId) {
+      throw new Error(
+        `Harness extension ${key} is already owned by ${existing.ownerId}.`,
+      );
+    }
+    if (new Set(input.descriptor.methods).size !== input.descriptor.methods.length) {
+      throw new Error(`Harness extension ${key} declares duplicate methods.`);
+    }
+    if (new Set(input.descriptor.events).size !== input.descriptor.events.length) {
+      throw new Error(`Harness extension ${key} declares duplicate events.`);
+    }
+    this.extensions.set(key, {
+      ownerId: input.ownerId,
+      descriptor: structuredClone(input.descriptor),
+      transport: input.transport,
+      wireMethods: { ...(input.wireMethods ?? {}) },
+      capabilityPatch: input.capabilityPatch
+        ? structuredClone(input.capabilityPatch)
+        : null,
+      paramMappers: { ...(input.paramMappers ?? {}) },
+    });
+  }
+
+  unregisterOwner(ownerId: string) {
+    for (const [key, extension] of this.extensions) {
+      if (extension.ownerId === ownerId) {
+        this.extensions.delete(key);
+      }
+    }
+  }
+
+  list() {
+    return [...this.extensions.values()].map((extension) => ({
+      ownerId: extension.ownerId,
+      descriptor: structuredClone(extension.descriptor),
+    }));
+  }
+
+  supports(extensionId: string, version: number, method: string) {
+    return this.extensions
+      .get(extensionKey(extensionId, version))
+      ?.descriptor.methods.includes(method) ?? false;
+  }
+
+  effectiveCapabilities(base: AgentProviderCapabilities) {
+    const effective = structuredClone(base);
+    for (const extension of this.extensions.values()) {
+      if (!extension.capabilityPatch) continue;
+      for (const [section, patch] of Object.entries(extension.capabilityPatch)) {
+        Object.assign(
+          effective[section as keyof AgentProviderCapabilities],
+          patch,
+        );
+      }
+    }
+    return effective;
+  }
+
+  invoke<T = unknown>(input: {
+    extensionId: string;
+    extensionVersion: number;
+    method: string;
+    operationId: string;
+    idempotencyKey: string;
+    params: unknown;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+  }): Promise<T> {
+    const key = extensionKey(input.extensionId, input.extensionVersion);
+    const extension = this.extensions.get(key);
+    if (!extension || !extension.descriptor.methods.includes(input.method)) {
+      return Promise.reject(this.error(input, {
+        code: 'extension_method_unavailable',
+        message: `Harness extension method is unavailable: ${key}/${input.method}`,
+        retryable: false,
+      }));
+    }
+    if (input.signal?.aborted) {
+      return Promise.reject(this.error(input, {
+        code: 'extension_cancelled',
+        message: 'Harness extension request was cancelled before dispatch.',
+        retryable: true,
+      }));
+    }
+    const fingerprint = operationFingerprint(input);
+    const cached = this.operations.get(input.idempotencyKey);
+    if (cached) {
+      if (cached.fingerprint !== fingerprint) {
+        return Promise.reject(this.error(input, {
+          code: 'idempotency_conflict',
+          message: 'Harness extension idempotency key was reused for another operation.',
+          retryable: false,
+        }));
+      }
+      return cached.promise as Promise<T>;
+    }
+
+    const envelope = createHarnessExtensionCall(input);
+    const controller = new AbortController();
+    const timeoutMs = input.timeoutMs ?? 30_000;
+    let timer: NodeJS.Timeout | null = null;
+    let abort: (() => void) | null = null;
+    const request = new Promise<T>((resolve, reject) => {
+      abort = () => {
+        controller.abort(input.signal?.reason);
+        reject(this.error(input, {
+          code: 'extension_cancelled',
+          message: 'Harness extension request was cancelled.',
+          retryable: true,
+        }));
+      };
+      input.signal?.addEventListener('abort', abort, { once: true });
+      timer = setTimeout(() => {
+        controller.abort(new Error('Harness extension request timed out.'));
+        reject(this.error(input, {
+          code: 'extension_timeout',
+          message: `Harness extension request timed out after ${timeoutMs}ms.`,
+          retryable: true,
+        }));
+      }, timeoutMs);
+      void Promise.resolve().then(() => extension.transport.request(
+          extension.wireMethods[input.method] ?? harnessExtensionMethodName(
+            input.extensionId,
+            input.extensionVersion,
+            input.method,
+          ),
+          extension.paramMappers[input.method]?.(envelope) ?? envelope,
+          controller.signal,
+        )).then((value) => resolve(value as T), (cause) => reject(
+          cause instanceof HarnessExtensionInvocationError
+            ? cause
+            : this.error(input, {
+                code: 'extension_request_failed',
+                message: cause instanceof Error ? cause.message : String(cause),
+                retryable: false,
+              }),
+        ));
+    }).finally(() => {
+      if (timer) clearTimeout(timer);
+      if (abort) input.signal?.removeEventListener('abort', abort);
+    });
+    this.operations.set(input.idempotencyKey, { fingerprint, promise: request });
+    request.catch(() => {
+      if (this.operations.get(input.idempotencyKey)?.promise === request) {
+        this.operations.delete(input.idempotencyKey);
+      }
+    });
+    while (this.operations.size > 256) {
+      this.operations.delete(this.operations.keys().next().value!);
+    }
+    return request;
+  }
+
+  handleEvent(ownerId: string, event: HarnessExtensionEventEnvelope) {
+    if (event.protocol !== REMOTE_CODEX_HARNESS_EXTENSION_PROTOCOL) {
+      throw new Error('Harness extension event protocol is unsupported.');
+    }
+    const extension = this.extensions.get(
+      extensionKey(event.extensionId, event.extensionVersion),
+    );
+    if (!extension || extension.ownerId !== ownerId) {
+      throw new Error('Harness extension event owner does not match registration.');
+    }
+    if (!extension.descriptor.events.includes(event.event)) {
+      throw new Error(`Harness extension event is not declared: ${event.event}`);
+    }
+    if (event.sequence !== null) {
+      const sequenceKey = [
+        ownerId,
+        event.extensionId,
+        event.extensionVersion,
+        event.providerSessionId,
+        event.event,
+        event.sequence,
+      ].join('\0');
+      if (this.eventSequences.has(sequenceKey)) {
+        return false;
+      }
+      this.eventSequences.add(sequenceKey);
+    }
+    this.emit('event', structuredClone(event));
+    return true;
+  }
+
+  private error(
+    input: {
+      extensionId: string;
+      extensionVersion: number;
+      method: string;
+      operationId: string;
+    },
+    error: { code: string; message: string; retryable: boolean },
+  ) {
+    return new HarnessExtensionInvocationError({
+      protocol: REMOTE_CODEX_HARNESS_EXTENSION_PROTOCOL,
+      extensionId: input.extensionId,
+      extensionVersion: input.extensionVersion,
+      method: input.method,
+      operationId: input.operationId,
+      ...error,
+    });
+  }
+}

package/packages/acp/src/extensions.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  REMOTE_CODEX_HARNESS_EXTENSION_PROTOCOL,
+  createHarnessExtensionCall,
+  harnessExtensionMethodName,
+} from './extensions';
+
+describe('harness extension contract', () => {
+  it('creates versioned, idempotent extension calls', () => {
+    expect(createHarnessExtensionCall({
+      extensionId: 'codex.session',
+      extensionVersion: 1,
+      method: 'compact',
+      operationId: 'operation-1',
+      idempotencyKey: 'thread-1:compact:operation-1',
+      params: { providerSessionId: 'session-1' },
+    })).toEqual({
+      protocol: REMOTE_CODEX_HARNESS_EXTENSION_PROTOCOL,
+      extensionId: 'codex.session',
+      extensionVersion: 1,
+      method: 'compact',
+      operationId: 'operation-1',
+      idempotencyKey: 'thread-1:compact:operation-1',
+      params: { providerSessionId: 'session-1' },
+    });
+    expect(harnessExtensionMethodName('codex.session', 1, 'compact')).toBe(
+      'remoteCodex/codex.session/v1/compact',
+    );
+  });
+
+  it('rejects ambiguous names and missing idempotency fields', () => {
+    expect(() => harnessExtensionMethodName('Codex Session', 1, 'compact')).toThrow(
+      /lowercase extension identifier/,
+    );
+    expect(() => createHarnessExtensionCall({
+      extensionId: 'codex.session',
+      extensionVersion: 1,
+      method: 'compact',
+      operationId: '',
+      idempotencyKey: '',
+      params: {},
+    })).toThrow(/operation id is required/);
+  });
+});

package/packages/acp/src/extensions.ts

@@ -0,0 +1,103 @@
+export const REMOTE_CODEX_HARNESS_EXTENSION_META_KEY =
+  'remoteCodex.harnessExtensions';
+export const REMOTE_CODEX_HARNESS_EXTENSION_PROTOCOL =
+  'remote-codex.harness-extension/v1';
+export const REMOTE_CODEX_HARNESS_EXTENSION_VERSION = 1;
+export const REMOTE_CODEX_HARNESS_EXTENSION_EVENT_METHOD =
+  'remoteCodex/harness-extension/event';
+
+export type HarnessExtensionStability = 'experimental' | 'stable';
+
+export interface HarnessExtensionDescriptor {
+  id: string;
+  version: number;
+  stability: HarnessExtensionStability;
+  methods: string[];
+  events: string[];
+}
+
+export interface HarnessExtensionCallEnvelope<TParams = unknown> {
+  protocol: typeof REMOTE_CODEX_HARNESS_EXTENSION_PROTOCOL;
+  extensionId: string;
+  extensionVersion: number;
+  method: string;
+  operationId: string;
+  idempotencyKey: string;
+  params: TParams;
+}
+
+export interface HarnessExtensionEventEnvelope<TPayload = unknown> {
+  protocol: typeof REMOTE_CODEX_HARNESS_EXTENSION_PROTOCOL;
+  extensionId: string;
+  extensionVersion: number;
+  event: string;
+  operationId: string | null;
+  providerSessionId: string;
+  providerTurnId: string | null;
+  providerItemId: string | null;
+  sequence: number | null;
+  payload: TPayload;
+}
+
+export interface HarnessExtensionErrorEnvelope {
+  protocol: typeof REMOTE_CODEX_HARNESS_EXTENSION_PROTOCOL;
+  extensionId: string;
+  extensionVersion: number;
+  method: string;
+  operationId: string;
+  code: string;
+  message: string;
+  retryable: boolean;
+  details?: Record<string, unknown>;
+}
+
+const extensionSegmentPattern = /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/;
+
+function assertExtensionSegment(value: string, label: string) {
+  if (!extensionSegmentPattern.test(value)) {
+    throw new Error(`${label} must be a lowercase extension identifier.`);
+  }
+}
+
+export function harnessExtensionMethodName(
+  extensionId: string,
+  version: number,
+  method: string,
+) {
+  assertExtensionSegment(extensionId, 'Extension id');
+  assertExtensionSegment(method, 'Extension method');
+  if (!Number.isInteger(version) || version < 1) {
+    throw new Error('Extension version must be a positive integer.');
+  }
+  return `remoteCodex/${extensionId}/v${version}/${method}`;
+}
+
+export function createHarnessExtensionCall<TParams>(input: {
+  extensionId: string;
+  extensionVersion: number;
+  method: string;
+  operationId: string;
+  idempotencyKey: string;
+  params: TParams;
+}): HarnessExtensionCallEnvelope<TParams> {
+  harnessExtensionMethodName(
+    input.extensionId,
+    input.extensionVersion,
+    input.method,
+  );
+  if (!input.operationId.trim()) {
+    throw new Error('Extension operation id is required.');
+  }
+  if (!input.idempotencyKey.trim()) {
+    throw new Error('Extension idempotency key is required.');
+  }
+  return {
+    protocol: REMOTE_CODEX_HARNESS_EXTENSION_PROTOCOL,
+    extensionId: input.extensionId,
+    extensionVersion: input.extensionVersion,
+    method: input.method,
+    operationId: input.operationId,
+    idempotencyKey: input.idempotencyKey,
+    params: input.params,
+  };
+}

package/packages/acp/src/harness-contract.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from 'vitest';
+
+import type { AgentProviderCapabilities } from '../../agent-runtime/src/index';
+import type { AcpNegotiatedCapabilitySnapshot } from './capabilities';
+import { acpCapabilities } from './runtimeAdapter';
+import { assertAcpHarnessContract } from './harness-contract';
+
+function negotiated(name: string): AcpNegotiatedCapabilitySnapshot {
+  return {
+    protocolVersion: 1,
+    agentInfo: { name, title: null, version: 'test' },
+    agentCapabilities: {},
+    harnessExtensions: [],
+    legacyExtensions: { steering: null, goal: null },
+  };
+}
+
+function capabilities(
+  patch: Partial<AgentProviderCapabilities>,
+): AgentProviderCapabilities {
+  const value = structuredClone(acpCapabilities);
+  for (const section of Object.keys(patch) as Array<keyof AgentProviderCapabilities>) {
+    Object.assign(value[section], patch[section]);
+  }
+  return value;
+}
+
+describe('ACP harness contract kit', () => {
+  it('validates the Codex extension profile', () => {
+    expect(assertAcpHarnessContract({
+      negotiated: negotiated('@agentclientprotocol/codex-acp'),
+      effectiveCapabilities: capabilities({
+        sessions: { ...acpCapabilities.sessions, list: true, load: true, resume: true },
+        turns: { ...acpCapabilities.turns, steer: true, compact: true },
+        controls: { ...acpCapabilities.controls, goals: true, performanceMode: true },
+      }),
+      expectedAgentName: '@agentclientprotocol/codex-acp',
+      required: [
+        'sessions.list',
+        'sessions.load',
+        'sessions.resume',
+        'turns.steer',
+        'turns.compact',
+        'controls.goals',
+        'controls.performanceMode',
+      ],
+      unsupported: ['branching.fork', 'branching.hardRollback'],
+    })).toMatchObject({ protocolVersion: 1 });
+  });
+
+  it('validates a portable fork profile without Codex-only compact', () => {
+    expect(assertAcpHarnessContract({
+      negotiated: negotiated('@agentclientprotocol/claude-agent-acp'),
+      effectiveCapabilities: capabilities({
+        sessions: { ...acpCapabilities.sessions, list: true, load: true, resume: true },
+        turns: { ...acpCapabilities.turns, steer: true },
+        branching: { ...acpCapabilities.branching, fork: true },
+        controls: { ...acpCapabilities.controls, goals: true },
+      }),
+      expectedAgentName: '@agentclientprotocol/claude-agent-acp',
+      required: [
+        'sessions.list',
+        'sessions.load',
+        'sessions.resume',
+        'turns.steer',
+        'branching.fork',
+        'controls.goals',
+      ],
+      unsupported: ['turns.compact', 'branching.hardRollback'],
+    })).toMatchObject({ protocolVersion: 1 });
+  });
+
+  it('fails closed when a required capability disappears', () => {
+    expect(() => assertAcpHarnessContract({
+      negotiated: negotiated('minimal-agent'),
+      effectiveCapabilities: capabilities({}),
+      expectedAgentName: 'minimal-agent',
+      required: ['sessions.resume'],
+    })).toThrow(/missing=sessions\.resume/);
+  });
+});

package/packages/acp/src/harness-contract.ts

@@ -0,0 +1,62 @@
+import type { AgentProviderCapabilities } from '../../agent-runtime/src/index';
+import type { AcpNegotiatedCapabilitySnapshot } from './capabilities';
+
+export type AcpHarnessContractCapability =
+  | 'sessions.list'
+  | 'sessions.load'
+  | 'sessions.resume'
+  | 'sessions.close'
+  | 'sessions.delete'
+  | 'turns.steer'
+  | 'turns.compact'
+  | 'branching.fork'
+  | 'branching.hardRollback'
+  | 'controls.performanceMode'
+  | 'controls.goals';
+
+function capabilityValue(
+  capabilities: AgentProviderCapabilities,
+  capability: AcpHarnessContractCapability,
+) {
+  const [section, key] = capability.split('.') as [
+    keyof AgentProviderCapabilities,
+    string,
+  ];
+  return capabilities[section][
+    key as keyof AgentProviderCapabilities[typeof section]
+  ] === true;
+}
+
+export function assertAcpHarnessContract(input: {
+  negotiated: AcpNegotiatedCapabilitySnapshot | null;
+  effectiveCapabilities: AgentProviderCapabilities;
+  expectedAgentName: string;
+  required: AcpHarnessContractCapability[];
+  unsupported?: AcpHarnessContractCapability[];
+}) {
+  const actualAgentName = input.negotiated?.agentInfo?.name ?? null;
+  if (actualAgentName !== input.expectedAgentName) {
+    throw new Error(
+      `ACP harness contract expected ${input.expectedAgentName}, received ` +
+      `${actualAgentName ?? 'unknown'}.`,
+    );
+  }
+  const missing = input.required.filter(
+    (capability) => !capabilityValue(input.effectiveCapabilities, capability),
+  );
+  const unexpectedlySupported = (input.unsupported ?? []).filter(
+    (capability) => capabilityValue(input.effectiveCapabilities, capability),
+  );
+  if (missing.length > 0 || unexpectedlySupported.length > 0) {
+    throw new Error(
+      `ACP harness contract mismatch: missing=${missing.join(',') || 'none'}; ` +
+      `unexpected=${unexpectedlySupported.join(',') || 'none'}.`,
+    );
+  }
+  return {
+    agentName: actualAgentName,
+    protocolVersion: input.negotiated!.protocolVersion,
+    required: [...input.required],
+    unsupported: [...(input.unsupported ?? [])],
+  };
+}

package/packages/acp/src/index.ts

@@ -1,5 +1,12 @@
 export * from './agent-catalog';
+export * from './capabilities';
 export * from './catalog-runtime';
+export * from './extensions';
+export * from './harness-contract';
+export * from './extension-registry';
 export * from './item-mapper';
+export * from './prompt-content';
 export * from './runtimeAdapter';
+export * from './session-hydrator';
 export * from './terminal-service';
+export * from './workspace-boundary';

package/packages/acp/src/item-mapper.ts

@@ -23,6 +23,8 @@ export interface AcpMappedSessionUpdate {
   usage: { used: number; size: number; cost?: acp.Cost | null } | null;
 }
 
+export type AcpMappingMode = 'hydrate' | 'live';
+
 interface StoredToolCall extends acp.ToolCall {
   title: string;
 }
@@ -227,12 +229,24 @@ export class AcpTurnItemMapper {
   constructor(
     readonly turnId: string,
     initialItems: AgentHistoryItem[] = [],
+    readonly mode: AcpMappingMode = 'live',
   ) {
     for (const item of initialItems) {
       this.upsert(item);
     }
   }
 
+  appendUserMessage(content: acp.ContentBlock, itemId: string) {
+    const current = this.items.get(itemId);
+    const item: AgentHistoryItem = {
+      ...(current ?? { id: itemId, kind: 'userMessage' as const }),
+      text: `${current?.text ?? ''}${acpContentBlockText(content)}`,
+      status: modeStatus(this.mode),
+    };
+    this.upsert(item);
+    return item;
+  }
+
   turn(status: AgentTurn['status'] = 'inProgress', error: string | null = null): AgentTurn {
     return {
       providerTurnId: this.turnId,
@@ -257,7 +271,8 @@ export class AcpTurnItemMapper {
       case 'agent_message_chunk': {
         result.itemUpdates.push(...this.finishThought());
         const delta = acpContentBlockText(update.content);
-        const itemId = this.currentAgentMessageId ?? `${this.turnId}:agent:${++this.agentMessageIndex}`;
+        const itemId = this.currentAgentMessageId ?? messageId(update) ??
+          `${this.turnId}:agent:${++this.agentMessageIndex}`;
         this.currentAgentMessageId = itemId;
         const current = this.items.get(itemId);
         const item: AgentHistoryItem = {
@@ -272,7 +287,8 @@ export class AcpTurnItemMapper {
       case 'agent_thought_chunk': {
         result.itemUpdates.push(...this.finishAgentMessage());
         const delta = acpContentBlockText(update.content);
-        const itemId = this.currentThoughtId ?? `${this.turnId}:thought:${++this.thoughtIndex}`;
+        const itemId = this.currentThoughtId ?? messageId(update) ??
+          `${this.turnId}:thought:${++this.thoughtIndex}`;
         this.currentThoughtId = itemId;
         const current = this.items.get(itemId);
         const item: AgentHistoryItem = {
@@ -471,3 +487,13 @@ export class AcpTurnItemMapper {
     return [...this.finishAgentMessage(), ...this.finishThought()];
   }
 }
+
+function messageId(update: { messageId?: unknown }) {
+  return typeof update.messageId === 'string' && update.messageId.trim()
+    ? update.messageId.trim()
+    : null;
+}
+
+function modeStatus(mode: AcpMappingMode) {
+  return mode === 'hydrate' ? 'completed' : 'running';
+}