remote-codex 0.11.50 → 0.11.52

package/packages/acp/src/catalog-runtime.ts

@@ -18,6 +18,8 @@ import {
   type InterruptAgentTurnInput,
   type ReadAgentSessionOptions,
   type ResumeAgentSessionInput,
+  type SendAgentInputInput,
+  type SetAgentGoalInput,
   type StartAgentSessionInput,
   type StartAgentSessionResult,
   type StartAgentTurnInput,
@@ -28,6 +30,7 @@ import {
   acpAgentMetadata,
   type AcpAgentCatalogEntry,
 } from './agent-catalog';
+import { snapshotAcpAgentCapabilities } from './capabilities';
 import { AcpRuntimeAdapter } from './runtimeAdapter';
 import { loadCodexAcpEnvironment } from './codex-environment';
 
@@ -90,7 +93,12 @@ const catalogCapabilities: AgentProviderCapabilities = {
 
 const catalogManagementSchema: AgentRuntimeManagementSchema = {
   hostConfigFiles: [],
-  toolboxItems: [],
+  toolboxItems: [
+    { action: 'fast', command: '/fast', label: 'Fast mode' },
+    { action: 'compact', command: '/compact', label: 'Compact context' },
+    { action: 'goal', command: '/goal', label: 'Goal' },
+    { action: 'fork', command: '/fork', label: 'Fork' },
+  ],
   hookCommandTemplates: [],
   providerConfigFormat: 'none',
   mcpConfigFormat: 'none',
@@ -117,6 +125,7 @@ function decodeScopedId(value: string | number) {
 function scopedSession(agentId: string, session: AgentSessionDetail): AgentSessionDetail {
   return {
     ...session,
+    agentId,
     providerSessionId: encodeSessionId(agentId, session.providerSessionId),
   };
 }
@@ -124,6 +133,7 @@ function scopedSession(agentId: string, session: AgentSessionDetail): AgentSessi
 function scopedSummary(agentId: string, session: AgentSessionSummary): AgentSessionSummary {
   return {
     ...session,
+    agentId,
     providerSessionId: encodeSessionId(agentId, session.providerSessionId),
   };
 }
@@ -154,6 +164,11 @@ export class AcpCatalogRuntimeAdapter extends EventEmitter implements AgentRunti
   private readonly catalog: AcpAgentCatalog;
   private readonly agents = new Map<string, AcpRuntimeAdapter>();
   private readonly modelCache = new Map<string, { at: number; models: AgentModel[] }>();
+  private readonly operationalMetrics = {
+    sessionStartFailures: 0,
+    resumeFailures: 0,
+    capabilityProbeFailures: 0,
+  };
   private status: AgentRuntimeStatus = {
     state: 'stopped',
     transport: 'stdio',
@@ -172,7 +187,10 @@ export class AcpCatalogRuntimeAdapter extends EventEmitter implements AgentRunti
   }
 
   getStatus() {
-    return { ...this.status };
+    return {
+      ...this.status,
+      operationalMetrics: { ...this.operationalMetrics },
+    };
   }
 
   async start() {
@@ -189,6 +207,7 @@ export class AcpCatalogRuntimeAdapter extends EventEmitter implements AgentRunti
   async stop() {
     await Promise.allSettled([...this.agents.values()].map((agent) => agent.stop()));
     this.agents.clear();
+    this.recomputeAgentCapabilities();
     this.status = {
       ...this.status,
       state: 'stopped',
@@ -219,21 +238,65 @@ export class AcpCatalogRuntimeAdapter extends EventEmitter implements AgentRunti
   }
 
   async listModelsForAgent(agentId: string, cwd: string) {
-    const cacheKey = `${agentId}\0${cwd}`;
-    const cached = this.modelCache.get(cacheKey);
-    if (cached && Date.now() - cached.at < 30_000) {
-      return cached.models;
-    }
-    const agent = await this.agentFor(agentId);
-    let models = await agent.inspectModelOptions(cwd);
-    if (models.length === 1 && models[0]?.model === 'default') {
-      const commandModels = await this.catalog.listCommandModels(agentId);
-      if (commandModels.length > 0) {
-        models = commandModels;
+    try {
+      const cacheKey = `${agentId}\0${cwd}`;
+      const cached = this.modelCache.get(cacheKey);
+      if (cached && Date.now() - cached.at < 30_000) {
+        return cached.models;
+      }
+      const agent = await this.agentFor(agentId);
+      let models = await agent.inspectModelOptions(cwd);
+      if (agent.capabilities.controls.performanceMode) {
+        models = models.map((model) => ({
+          ...model,
+          supportsPerformanceMode: true,
+        }));
+      }
+      if (models.length === 1 && models[0]?.model === 'default') {
+        const commandModels = await this.catalog.listCommandModels(agentId);
+        if (commandModels.length > 0) {
+          models = commandModels;
+        }
       }
+      this.modelCache.set(cacheKey, { at: Date.now(), models });
+      return models;
+    } catch (error) {
+      this.operationalMetrics.capabilityProbeFailures += 1;
+      throw error;
     }
-    this.modelCache.set(cacheKey, { at: Date.now(), models });
-    return models;
+  }
+
+  async getAgentCapabilitySnapshot(agentId: string) {
+    const entry = (await this.refreshCatalog()).find((candidate) => candidate.id === agentId);
+    if (!entry) {
+      throw new AgentRuntimeError(`Unknown ACP agent: ${agentId}`, 'acp', 'request_failed');
+    }
+    if (entry.availability !== 'ready') {
+      return snapshotAcpAgentCapabilities({
+        agentId,
+        availability: entry.availability,
+        effectiveCapabilities: this.capabilities,
+      });
+    }
+    const agent = await this.agentFor(agentId);
+    return snapshotAcpAgentCapabilities({
+      agentId,
+      availability: entry.availability,
+      negotiated: agent.getProtocolSnapshot(),
+      effectiveCapabilities: agent.capabilities,
+    });
+  }
+
+  getScopedCapabilities(input: {
+    agentId?: string | null;
+    providerSessionId?: string | null;
+  }) {
+    const sessionOwner = input.providerSessionId
+      ? decodeScopedId(input.providerSessionId)
+      : null;
+    const agentId = sessionOwner?.agentId ?? input.agentId ?? null;
+    const child = agentId ? this.agents.get(agentId) : null;
+    return structuredClone(child?.capabilities ?? catalogCapabilities);
   }
 
   async installModel(modelId: string) {
@@ -250,6 +313,27 @@ export class AcpCatalogRuntimeAdapter extends EventEmitter implements AgentRunti
     return sessions.flat();
   }
 
+  async listImportSessions(agentId?: string | null) {
+    const entries = agentId
+      ? (await this.refreshCatalog()).filter((entry) => entry.id === agentId)
+      : [];
+    const sessions = await Promise.all(
+      entries.map(async (entry) => {
+        if (entry.availability !== 'ready') {
+          return [];
+        }
+        try {
+          const agent = await this.agentFor(entry.id);
+          return (await agent.listSessions()).map((session) =>
+            scopedSummary(entry.id, session));
+        } catch {
+          return [];
+        }
+      }),
+    );
+    return sessions.flat();
+  }
+
   async listLoadedSessions() {
     const sessions = await Promise.all(
       [...this.agents.entries()].map(async ([agentId, agent]) =>
@@ -279,14 +363,30 @@ export class AcpCatalogRuntimeAdapter extends EventEmitter implements AgentRunti
     if (!agentId) {
       throw new AgentRuntimeError('Select an ACP agent before creating the thread.', 'acp');
     }
-    const agent = await this.agentFor(agentId);
-    const response = await agent.startSession(delegatedSessionInput(input));
+    let agent: AcpRuntimeAdapter;
+    let response: StartAgentSessionResult;
+    try {
+      agent = await this.agentFor(agentId);
+      response = await agent.startSession(delegatedSessionInput(input));
+    } catch (error) {
+      this.operationalMetrics.sessionStartFailures += 1;
+      throw error;
+    }
+    const probedDefaultModel = this.modelCache
+      .get(`${agentId}\0${input.cwd}`)
+      ?.models.find((model) => model.isDefault)?.model ?? null;
+    const resolvedModel = response.model && response.model !== 'default'
+      ? response.model
+      : input.model !== 'default'
+        ? input.model
+        : probedDefaultModel ?? input.model;
+    this.refreshAgentSessionCapabilities(agentId, agent);
     const session = scopedSession(agentId, response.session);
     return {
       ...response,
       agentId,
       providerSessionId: session.providerSessionId,
-      model: response.model ?? input.model,
+      model: resolvedModel,
       reasoningEffort: response.reasoningEffort ?? input.reasoningEffort ?? null,
       session,
     };
@@ -294,11 +394,19 @@ export class AcpCatalogRuntimeAdapter extends EventEmitter implements AgentRunti
 
   async resumeSession(input: ResumeAgentSessionInput): Promise<StartAgentSessionResult> {
     const owner = this.requireSessionOwner(input.providerSessionId);
-    const agent = await this.agentFor(owner.agentId);
-    const response = await agent.resumeSession({
-      ...input,
-      providerSessionId: owner.rawId,
-    });
+    let agent: AcpRuntimeAdapter;
+    let response: StartAgentSessionResult;
+    try {
+      agent = await this.agentFor(owner.agentId);
+      response = await agent.resumeSession({
+        ...input,
+        providerSessionId: owner.rawId,
+      });
+    } catch (error) {
+      this.operationalMetrics.resumeFailures += 1;
+      throw error;
+    }
+    this.refreshAgentSessionCapabilities(owner.agentId, agent);
     const session = scopedSession(owner.agentId, response.session);
     return {
       ...response,
@@ -327,6 +435,55 @@ export class AcpCatalogRuntimeAdapter extends EventEmitter implements AgentRunti
     });
   }
 
+  async sendInput(input: SendAgentInputInput) {
+    const owner = this.requireSessionOwner(input.providerSessionId);
+    const agent = await this.agentFor(owner.agentId);
+    return agent.sendInput({
+      ...input,
+      providerSessionId: owner.rawId,
+    });
+  }
+
+  async compactSession(providerSessionId: string) {
+    const owner = this.requireSessionOwner(providerSessionId);
+    const agent = await this.agentFor(owner.agentId);
+    return agent.compactSession(owner.rawId);
+  }
+
+  async forkSession(input: { providerSessionId: string; atTurnId?: string | null }) {
+    const owner = this.requireSessionOwner(input.providerSessionId);
+    const agent = await this.agentFor(owner.agentId);
+    return scopedSession(owner.agentId, await agent.forkSession({
+      ...input,
+      providerSessionId: owner.rawId,
+    }));
+  }
+
+  async getGoal(providerSessionId: string) {
+    const owner = this.requireSessionOwner(providerSessionId);
+    const agent = await this.agentFor(owner.agentId);
+    return agent.getGoal(owner.rawId);
+  }
+
+  async setGoal(input: SetAgentGoalInput) {
+    const owner = this.requireSessionOwner(input.providerSessionId);
+    const agent = await this.agentFor(owner.agentId);
+    const goal = await agent.setGoal({
+      ...input,
+      providerSessionId: owner.rawId,
+    });
+    return {
+      ...goal,
+      providerSessionId: encodeSessionId(owner.agentId, goal.providerSessionId),
+    };
+  }
+
+  async clearGoal(providerSessionId: string) {
+    const owner = this.requireSessionOwner(providerSessionId);
+    const agent = await this.agentFor(owner.agentId);
+    return agent.clearGoal(owner.rawId);
+  }
+
   mapProviderRequest(
     request: AgentProviderRequest,
     options: { approvalMode: 'yolo' | 'guarded' },
@@ -336,10 +493,17 @@ export class AcpCatalogRuntimeAdapter extends EventEmitter implements AgentRunti
     if (!owner || !agent) {
       return null;
     }
+    const scopedProviderSessionId = request.params && typeof request.params === 'object'
+      ? String((request.params as Record<string, unknown>).sessionId ?? '')
+      : '';
+    const sessionOwner = decodeScopedId(scopedProviderSessionId);
+    if (!sessionOwner || sessionOwner.agentId !== owner.agentId || !sessionOwner.rawId) {
+      return null;
+    }
     const params = request.params && typeof request.params === 'object'
       ? {
           ...(request.params as Record<string, unknown>),
-          sessionId: owner.rawId,
+          sessionId: sessionOwner.rawId,
         }
       : request.params;
     const mapping = agent.mapProviderRequest({
@@ -415,6 +579,7 @@ export class AcpCatalogRuntimeAdapter extends EventEmitter implements AgentRunti
     const existing = this.agents.get(agentId);
     if (existing) {
       await existing.start();
+      this.mergeAgentCapabilities(existing);
       return existing;
     }
 
@@ -435,6 +600,7 @@ export class AcpCatalogRuntimeAdapter extends EventEmitter implements AgentRunti
     this.agents.set(agentId, agent);
     try {
       await agent.start();
+      this.mergeAgentCapabilities(agent);
       return agent;
     } catch (error) {
       this.agents.delete(agentId);
@@ -442,6 +608,40 @@ export class AcpCatalogRuntimeAdapter extends EventEmitter implements AgentRunti
     }
   }
 
+  private mergeAgentCapabilities(agent: AcpRuntimeAdapter) {
+    void agent;
+    this.recomputeAgentCapabilities();
+  }
+
+  private refreshAgentSessionCapabilities(
+    agentId: string,
+    agent: AcpRuntimeAdapter,
+  ) {
+    for (const key of this.modelCache.keys()) {
+      if (key.startsWith(`${agentId}\0`)) {
+        this.modelCache.delete(key);
+      }
+    }
+    this.mergeAgentCapabilities(agent);
+  }
+
+  private recomputeAgentCapabilities() {
+    const next = structuredClone(catalogCapabilities);
+    for (const child of this.agents.values()) {
+      next.turns.steer ||= child.capabilities.turns.steer;
+      next.turns.compact ||= child.capabilities.turns.compact;
+      next.branching.fork ||= child.capabilities.branching.fork;
+      next.controls.goals ||= child.capabilities.controls.goals;
+      next.controls.performanceMode ||= child.capabilities.controls.performanceMode;
+      next.management.mcpStatus ||= child.capabilities.management.mcpStatus;
+      next.management.skills ||= child.capabilities.management.skills;
+      next.management.hooks ||= child.capabilities.management.hooks;
+    }
+    for (const section of Object.keys(next) as Array<keyof AgentProviderCapabilities>) {
+      Object.assign(this.capabilities[section], next[section]);
+    }
+  }
+
   private async createAgent(entry: AcpAgentCatalogEntry) {
     const env = entry.id === 'codex'
       ? await loadCodexAcpEnvironment(
@@ -461,9 +661,18 @@ export class AcpCatalogRuntimeAdapter extends EventEmitter implements AgentRunti
         : {}),
     });
     agent.on('event', (event: AgentRuntimeEvent) => {
+      const providerSessionId = encodeSessionId(entry.id, event.providerSessionId);
       this.emit('event', {
         ...event,
-        providerSessionId: encodeSessionId(entry.id, event.providerSessionId),
+        providerSessionId,
+        ...(event.type === 'goal.updated'
+          ? {
+              goal: {
+                ...event.goal,
+                providerSessionId,
+              },
+            }
+          : {}),
       } satisfies AgentRuntimeEvent);
     });
     agent.on('provider-request', (request: AgentProviderRequest) => {

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

@@ -0,0 +1,198 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  REMOTE_CODEX_HARNESS_EXTENSION_PROTOCOL,
+  type HarnessExtensionEventEnvelope,
+} from './extensions';
+import {
+  HarnessExtensionInvocationError,
+  HarnessExtensionRegistry,
+} from './extension-registry';
+
+const descriptor = {
+  id: 'fixture.session',
+  version: 1,
+  stability: 'experimental' as const,
+  methods: ['compact'],
+  events: ['checkpoint'],
+};
+
+describe('HarnessExtensionRegistry', () => {
+  it('enforces one owner and deduplicates idempotent calls', async () => {
+    const registry = new HarnessExtensionRegistry();
+    const request = vi.fn(async () => ({ compacted: true }));
+    registry.register({
+      ownerId: 'owner-1',
+      descriptor,
+      transport: { request },
+      capabilityPatch: {
+        turns: { compact: true },
+        controls: { goals: true },
+      },
+      paramMappers: {
+        compact: (envelope) => ({
+          sessionId: (envelope.params as { providerSessionId: string }).providerSessionId,
+        }),
+      },
+    });
+    expect(() => registry.register({
+      ownerId: 'owner-2',
+      descriptor,
+      transport: { request },
+    })).toThrow(/already owned/);
+    const input = {
+      extensionId: 'fixture.session',
+      extensionVersion: 1,
+      method: 'compact',
+      operationId: 'operation-1',
+      idempotencyKey: 'thread-1:compact:1',
+      params: { providerSessionId: 'session-1' },
+    };
+    const [first, second] = await Promise.all([
+      registry.invoke(input),
+      registry.invoke(input),
+    ]);
+    expect(first).toEqual({ compacted: true });
+    expect(second).toEqual(first);
+    expect(request).toHaveBeenCalledTimes(1);
+    expect(request).toHaveBeenCalledWith(
+      'remoteCodex/fixture.session/v1/compact',
+      { sessionId: 'session-1' },
+      expect.any(AbortSignal),
+    );
+    expect(registry.effectiveCapabilities({
+      sessions: { list: true, read: true, resume: true, importLocal: false },
+      turns: { start: true, streamInput: false, steer: false, interrupt: true, compact: false },
+      branching: { fork: false, hardRollback: false, resumeAt: false, rewindFiles: false },
+      controls: {
+        planMode: true,
+        permissionRequests: true,
+        sandboxMode: true,
+        performanceMode: false,
+        goals: false,
+      },
+      management: {
+        models: false,
+        mcpStatus: false,
+        skills: false,
+        hooks: false,
+        hookTrust: false,
+        hostConfigFiles: false,
+        providerSettings: false,
+      },
+      usage: { contextWindow: true, tokenUsage: true, costUsd: false },
+    })).toMatchObject({
+      turns: { compact: true },
+      controls: { goals: true },
+    });
+    await expect(registry.invoke({
+      ...input,
+      params: { providerSessionId: 'session-2' },
+    })).rejects.toMatchObject({
+      payload: { code: 'idempotency_conflict', retryable: false },
+    });
+    await expect(registry.invoke({
+      ...input,
+      extensionVersion: 2,
+      idempotencyKey: 'thread-1:compact:v2',
+    })).rejects.toMatchObject({
+      payload: { code: 'extension_method_unavailable', retryable: false },
+    });
+  });
+
+  it('times out, aborts transport, and permits an explicit retry', async () => {
+    const registry = new HarnessExtensionRegistry();
+    let calls = 0;
+    registry.register({
+      ownerId: 'owner-1',
+      descriptor,
+      transport: {
+        request: async (_method, _params, signal) => {
+          calls += 1;
+          await new Promise((_resolve, reject) =>
+            signal.addEventListener('abort', () => reject(signal.reason), { once: true }));
+          return {};
+        },
+      },
+    });
+    const input = {
+      extensionId: 'fixture.session',
+      extensionVersion: 1,
+      method: 'compact',
+      operationId: 'operation-timeout',
+      idempotencyKey: 'thread-1:compact:timeout',
+      params: {},
+      timeoutMs: 5,
+    };
+    await expect(registry.invoke(input)).rejects.toBeInstanceOf(
+      HarnessExtensionInvocationError,
+    );
+    await expect(registry.invoke(input)).rejects.toMatchObject({
+      payload: { code: 'extension_timeout', retryable: true },
+    });
+    expect(calls).toBe(2);
+  });
+
+  it('cancels promptly even when transport ignores abort and does not dispatch pre-aborted calls', async () => {
+    const registry = new HarnessExtensionRegistry();
+    const request = vi.fn(async () => new Promise<never>(() => {}));
+    registry.register({
+      ownerId: 'owner-1',
+      descriptor,
+      transport: { request },
+    });
+    const preAborted = new AbortController();
+    preAborted.abort(new Error('already cancelled'));
+    const input = {
+      extensionId: 'fixture.session',
+      extensionVersion: 1,
+      method: 'compact',
+      operationId: 'operation-cancel',
+      idempotencyKey: 'thread-1:compact:cancel',
+      params: {},
+      timeoutMs: 10_000,
+    };
+
+    await expect(registry.invoke({
+      ...input,
+      signal: preAborted.signal,
+    })).rejects.toMatchObject({
+      payload: { code: 'extension_cancelled', retryable: true },
+    });
+    expect(request).not.toHaveBeenCalled();
+
+    const controller = new AbortController();
+    const pending = registry.invoke({ ...input, signal: controller.signal });
+    await vi.waitFor(() => expect(request).toHaveBeenCalledTimes(1));
+    controller.abort(new Error('cancel now'));
+    await expect(pending).rejects.toMatchObject({
+      payload: { code: 'extension_cancelled', retryable: true },
+    });
+  });
+
+  it('validates and deduplicates declared extension events', () => {
+    const registry = new HarnessExtensionRegistry();
+    registry.register({
+      ownerId: 'owner-1',
+      descriptor,
+      transport: { request: async () => ({}) },
+    });
+    const events: HarnessExtensionEventEnvelope[] = [];
+    registry.on('event', (event) => events.push(event));
+    const event: HarnessExtensionEventEnvelope = {
+      protocol: REMOTE_CODEX_HARNESS_EXTENSION_PROTOCOL,
+      extensionId: 'fixture.session',
+      extensionVersion: 1,
+      event: 'checkpoint',
+      operationId: 'operation-1',
+      providerSessionId: 'session-1',
+      providerTurnId: 'turn-1',
+      providerItemId: 'checkpoint-1',
+      sequence: 1,
+      payload: { status: 'completed' },
+    };
+    expect(registry.handleEvent('owner-1', event)).toBe(true);
+    expect(registry.handleEvent('owner-1', event)).toBe(false);
+    expect(events).toHaveLength(1);
+  });
+});