feat(runtime): add plugin-backed Session executors

apps/desktop/src/main/__tests__/runtime-host-session-catalog-ipc-main.test.ts

@@ -62,6 +62,26 @@ test('session creation forwards the caller name for a mode that carries none', a
   );
 });
 
+test('session creation forwards a plugin executor without a model target', async () => {
+  const creates: SessionCreateInput[] = [];
+  const ipc = ipcHarness();
+  registerRuntimeHostSessionCatalogIpc(createDeps(creates), ipc as unknown as IpcMain);
+
+  await ipc.invoke('sessions:create', { executorId: 'codex.app-server' });
+
+  assert.equal(creates[0]?.executorId, 'codex.app-server');
+  assert.equal(creates[0]?.modelTarget, undefined);
+  await assert.rejects(
+    ipc.invoke('sessions:create', {
+      executorId: 'codex',
+      llmConnectionId: 'connection-1',
+      llmConnectionSlug: 'openai',
+      model: 'gpt-5',
+    }),
+    /cannot include a model target/,
+  );
+});
+
 type IpcHandler = Parameters<Pick<IpcMain, 'handle'>['handle']>[1];
 
 function ipcHarness() {

apps/desktop/src/main/__tests__/session-local.test.ts

@@ -638,6 +638,47 @@ test('attachment retries across restart reuse committed uploads and release stag
   assert.deepEqual(db.store.stagedAttachments('authority', 'message-1'), []);
 });
 
+test('local creation preserves a plugin executor in the pending Session projection', async (t) => {
+  const { store, beforeClose } = await database(t);
+  const target: DesktopSessionLocalTarget = {
+    partition: 'authority',
+    profileId: 'profile',
+    scope: { hostId: 'root', targetEpoch: 'target' },
+  };
+  const service = new DesktopSessionLocalService(store, {
+    targets: () => [target],
+    changed() {},
+    onError: (error) => assert.fail(String(error)),
+  });
+  beforeClose.push(() => service.close());
+  type Ipc = Parameters<typeof registerDesktopSessionLocalIpc>[0]['ipcMain'];
+  let create!: Parameters<Ipc['handle']>[1];
+  registerDesktopSessionLocalIpc({
+    ipcMain: {
+      handle: (channel, handler) => {
+        if (channel === 'session-local:create') create = handler;
+      },
+    },
+    service,
+    approvals: createAttachmentApprovalRegistry(),
+    resizeImage: async (bytes) => bytes,
+    resolveWorkspace: async () => ({ kind: 'host_path', path: '/workspace' }),
+    changed() {},
+  });
+
+  const summary = (await create(
+    {} as IpcMainInvokeEvent,
+    target.scope,
+    { executorId: 'codex.app-server' },
+  )) as DesktopSessionSummaryInput;
+  assert.equal(summary.backend, 'plugin-executor');
+  assert.equal(summary.executorId, 'codex.app-server');
+  assert.equal(summary.llmConnectionId, undefined);
+  assert.equal(summary.llmConnectionSlug, 'executor:codex.app-server');
+  assert.equal(summary.model, 'codex.app-server');
+  assert.equal(store.creation(target.partition, summary.id)?.executorId, 'codex.app-server');
+});
+
 test('local submit preserves picked-file approvals until durable admission succeeds', async (t) => {
   const { store, path, beforeClose } = await database(t);
   const file = join(path, '..', 'picked.txt');

apps/desktop/src/main/runtime-host-session-catalog-ipc-main.ts

@@ -322,12 +322,21 @@ function normalizeSessionListFilter(value: unknown): SessionListFilter | undefin
 
 export function resolveDesktopSessionCreateInput(input: CreateSessionRequestInput | undefined, sessionId: string, workspace: WorkspaceTarget): SessionCreateInput {
   const request = resolveCreateSessionRequest(input);
+  const executorId = normalizeOptionalString(input?.executorId, 'executor id');
+  if (
+    executorId &&
+    (input?.llmConnectionId !== undefined ||
+      input?.llmConnectionSlug !== undefined ||
+      input?.model !== undefined)
+  ) {
+    throw new Error('Plugin executor selection cannot include a model target');
+  }
   return {
     sessionId, workspace,
     ...(request.mode === undefined ? {} : { mode: request.mode }),
     name: request.name,
     ...(request.labels === undefined ? {} : { labels: request.labels }),
-    modelTarget: normalizeModelTarget(input),
+    ...(executorId ? { executorId } : { modelTarget: normalizeModelTarget(input) }),
     ...normalizeCreateThinkingLevel(input?.thinkingLevel),
     ...(request.mode !== undefined || request.permissionMode === undefined ? {} : { permissionMode: request.permissionMode }),
     collaborationMode: request.collaborationMode,

apps/desktop/src/main/session-local-service.ts

@@ -537,10 +537,18 @@ export function registerDesktopSessionLocalIpc(deps: {
         labels: [...(creation.labels ?? [])],
         hasUnread: false,
         status: 'active',
-        backend: 'ai-sdk',
-        llmConnectionSlug: input.llmConnectionSlug ?? '',
-        model: input.model ?? '',
-        ...(input.llmConnectionId ? { llmConnectionId: input.llmConnectionId } : {}),
+        backend: creation.executorId ? 'plugin-executor' : 'ai-sdk',
+        ...(creation.executorId
+          ? {
+              executorId: creation.executorId,
+              llmConnectionSlug: `executor:${creation.executorId}`,
+              model: creation.executorId,
+            }
+          : {
+              llmConnectionSlug: input.llmConnectionSlug ?? '',
+              model: input.model ?? '',
+              ...(input.llmConnectionId ? { llmConnectionId: input.llmConnectionId } : {}),
+            }),
         connectionLocked: false,
         permissionMode: creation.permissionMode ?? 'ask',
         collaborationMode: creation.collaborationMode,

packages/core/package.json

@@ -7,6 +7,7 @@
   "sideEffects": false,
   "private": true,
   "exports": {
+    "./executor-id": "./dist/executor-id.js",
     "./durable-tool-result-projection": "./dist/durable-tool-result-projection.js",
     "./model-projection-transition": "./dist/model-projection-transition.js",
     "./canonical-runtime-event": "./dist/canonical-runtime-event.js",

packages/core/src/__tests__/agent-graph-schedule.test.ts

@@ -34,6 +34,29 @@ describe('agent graph schedule contract', () => {
     assert.equal(isAgentGraphScheduleUpdateRequest(request), true);
   });
 
+  test('accepts a plugin executor only on newly created graph targets', () => {
+    const request = scheduleRequest();
+    request.addWork[0]!.target = {
+      kind: 'agent',
+      agentId: 'fact-checker',
+      executorId: 'codex.app-server',
+    };
+    assert.equal(isAgentGraphScheduleUpdateRequest(request), true);
+
+    request.addWork[0]!.target = {
+      kind: 'agent',
+      agentId: 'fact-checker',
+      executorId: 'invalid executor',
+    };
+    assert.equal(isAgentGraphScheduleUpdateRequest(request), false);
+    request.addWork[0]!.target = {
+      kind: 'operator',
+      operatorId: 'existing-operator',
+      executorId: 'codex',
+    } as never;
+    assert.equal(isAgentGraphScheduleUpdateRequest(request), false);
+  });
+
   test('rejects ambiguous, duplicate, empty, and add-plus-finish updates', () => {
     assert.equal(
       isAgentGraphScheduleUpdateRequest({

packages/core/src/__tests__/executor-id.test.ts

@@ -0,0 +1,30 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { isExecutorId } from '../executor-id.js';
+
+test('executor ids use one bounded canonical grammar', () => {
+  assert.equal(isExecutorId('codex.app-server:v1'), true);
+  assert.equal(isExecutorId(`a${'b'.repeat(127)}`), true);
+  for (const value of ['', '1codex', 'codex/app', `a${'b'.repeat(128)}`, null]) {
+    assert.equal(isExecutorId(value), false);
+  }
+});

packages/core/src/__tests__/runtime-invocation-opened.test.ts

@@ -117,6 +117,28 @@ describe('invocation_opened content contract', () => {
     );
   });
 
+  test('binds a plugin executor route to its exact activation generation', () => {
+    const route = {
+      provenance: 'runtime',
+      backendKind: 'plugin-executor',
+      executorId: 'codex.app-server',
+      llmConnectionSlug: 'executor:codex.app-server',
+      modelId: 'codex.app-server',
+      providerStateIdentity: DIGEST,
+    } as const;
+    assert.deepEqual(decodeRuntimeInvocationOpened(opening({ route })).route, route);
+    assert.throws(() =>
+      decodeRuntimeInvocationOpened(
+        opening({ route: { ...route, providerStateIdentity: undefined } as never }),
+      ),
+    );
+    assert.throws(() =>
+      decodeRuntimeInvocationOpened(
+        opening({ route: { ...route, llmConnectionId: 'not-an-executor-route' } as never }),
+      ),
+    );
+  });
+
   test('accepts every root authority the runtime can open, and no mixture of them', () => {
     for (const root of [
       { kind: 'user' },

packages/core/src/__tests__/session-send-projection.test.ts

@@ -62,6 +62,23 @@ describe('projectSessionSendOutcome — exact Connection identity', () => {
     assert.deepEqual(projectSessionSendOutcome(input()), { kind: 'ready' });
   });
 
+  it('does not require a Maka model connection for a plugin executor Session', () => {
+    assert.deepEqual(
+      projectSessionSendOutcome(
+        input({
+          session: {
+            backend: 'plugin-executor',
+            llmConnectionSlug: 'executor:codex',
+            model: 'codex',
+            connectionLocked: false,
+          },
+          connections: [],
+        }),
+      ),
+      { kind: 'ready' },
+    );
+  });
+
   it('blocks a legacy Session until the user explicitly selects an account', () => {
     const current = input();
     assert.deepEqual(

packages/core/src/agent-graph-schedule.ts

@@ -24,6 +24,7 @@ import type {
 } from './agent-graph-control.js';
 import type { AgentGraphTopologyStore } from './agent-graph-topology.js';
 import type { OrchestrationMode } from './orchestration.js';
+import { isExecutorId } from './executor-id.js';
 
 export const AGENT_GRAPH_SCHEDULE_UPDATE_SCHEMA_VERSION = 1 as const;
 
@@ -48,10 +49,12 @@ export type AgentGraphWorkTarget =
   | {
       kind: 'agent';
       agentId: string;
+      executorId?: string;
     }
   | {
       kind: 'preset';
       presetId: string;
+      executorId?: string;
     }
   | {
       kind: 'operator';
@@ -346,16 +349,26 @@ function isSelectedResultInput(value: unknown): value is AgentGraphSelectedResul
 function isWorkTarget(value: unknown): value is AgentGraphWorkTarget {
   if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
   if (
-    isExactRecord(value, ['kind', 'agentId']) &&
+    isExactRecord(value, [
+      'kind',
+      'agentId',
+      ...(hasOwn(value, 'executorId') ? ['executorId'] : []),
+    ]) &&
     value.kind === 'agent' &&
-    isOpaqueIdentity(value.agentId)
+    isOpaqueIdentity(value.agentId) &&
+    (value.executorId === undefined || isExecutorId(value.executorId))
   ) {
     return true;
   }
   if (
-    isExactRecord(value, ['kind', 'presetId']) &&
+    isExactRecord(value, [
+      'kind',
+      'presetId',
+      ...(hasOwn(value, 'executorId') ? ['executorId'] : []),
+    ]) &&
     value.kind === 'preset' &&
-    isOpaqueIdentity(value.presetId)
+    isOpaqueIdentity(value.presetId) &&
+    (value.executorId === undefined || isExecutorId(value.executorId))
   ) {
     return true;
   }

packages/core/src/executor-id.ts

@@ -0,0 +1,24 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+export const EXECUTOR_ID_PATTERN = /^[A-Za-z][A-Za-z0-9._:-]{0,127}$/u;
+
+export function isExecutorId(value: unknown): value is string {
+  return typeof value === 'string' && EXECUTOR_ID_PATTERN.test(value);
+}