@canonmsg/codex-plugin 0.26.1 → 0.26.2

package/README.md

@@ -79,6 +79,10 @@ model cannot select another user, conversation, or responder. It can display a
 card with `send_card`, wait for an action card with `request_card`, or ask one
 standalone question with `request_input`.
 
+Service-agent sessions use the configured shared workspace and read-only local
+filesystem automatically. They do not ask conversation members to choose a
+coding workspace, execution mode, model, reasoning level, or permission mode.
+
 Authorized conversation members may use a service agent even when they do not
 own its Canon identity. Normal coding-host sessions keep their existing
 owner-only execution boundary.

package/dist/host.d.ts

@@ -36,6 +36,19 @@ export declare function buildCodexLiveSessionConfig(input: {
     permissionMode?: string | undefined;
     model?: string | undefined;
 };
+export declare function buildCodexServiceSnapshotConfig(input: {
+    model?: string;
+    permissionMode?: string;
+    effort?: string;
+    workspaceId?: string;
+}): {
+    model: string | undefined;
+    permissionMode: string | undefined;
+    effort: string | undefined;
+    workspaceId: string | undefined;
+    executionMode: "locked";
+    executionBranch: null;
+};
 /** Conservative fallback used only when native app-server discovery is unavailable. */
 export declare const CODEX_EFFORT_OPTIONS: readonly CodexControlOption[];
 export declare const CODEX_SESSION_CONFIG_FIELDS: readonly ["permissionMode", "effort"];
@@ -57,6 +70,7 @@ export declare function buildCodexRuntimeDescriptor(input: {
     supportsCompact?: boolean;
     supportsRichCards?: boolean;
     skills?: ReadonlyArray<CodexSkillMetadata>;
+    serviceAgentMode?: boolean;
 }): CanonRuntimeDescriptor;
 export declare function buildCodexTurnResponseRouting(input: {
     requestingUserId?: string | null;
@@ -73,6 +87,7 @@ export declare function getCodexRequestingUserId(message: {
 export declare function resolveSessionExecutionMode(config: {
     executionMode?: ExecutionEnvironmentMode;
 } | null | undefined, serviceAgentMode?: boolean): ExecutionEnvironmentMode;
+export declare function resolveCodexSessionConfig<T extends Record<string, unknown>>(config: T | null | undefined, serviceAgentMode?: boolean): T | null;
 export declare function resolveWorkspaceCwd(config: {
     workspaceId?: string;
     retiredWorkspaceConfig?: boolean;
@@ -95,6 +110,19 @@ export declare function resolveCodexEffectiveRuntimePolicy(input: {
     environment: Pick<PreparedExecutionEnvironment, 'baseCwd' | 'mode'>;
     serviceAgentMode?: boolean;
 }): CodexEffectiveRuntimePolicy;
+export declare function resolveCodexPlanCommand(input: {
+    content: string;
+    requestedPlanMode: boolean;
+    useAppServer: boolean;
+    serviceAgentMode: boolean;
+}): {
+    planMode: boolean;
+    content: string;
+};
+export declare function isCodexPlanApprovalReply(metadata: unknown, serviceAgentMode?: boolean): metadata is Record<string, unknown> & {
+    type: 'plan_approval_reply';
+    decision: string;
+};
 /**
  * `--turn-verbosity` beats `CANON_TURN_VERBOSITY`; `null` means "unset, use the
  * per-conversation-type default".

package/dist/host.js

@@ -78,6 +78,20 @@ export function buildCodexLiveSessionConfig(input) {
         executionBranch: input.executionBranch ?? null,
     };
 }
+export function buildCodexServiceSnapshotConfig(input) {
+    // Keep every setup key present, including keys whose host value is
+    // undefined. `publishHostSessionSnapshots` merges this over any persisted
+    // coding config, so an absent host value clears rather than resurrects a
+    // stale member-selected value.
+    return {
+        model: input.model,
+        permissionMode: input.permissionMode,
+        effort: input.effort,
+        workspaceId: input.workspaceId,
+        executionMode: 'locked',
+        executionBranch: null,
+    };
+}
 const MAX_SESSIONS = 12;
 // IDLE_TIMEOUT_MS (30 minutes) is shared with the other coding-agent hosts.
 const HEARTBEAT_MS = 30_000;
@@ -138,6 +152,7 @@ export function buildCodexSkillCommands(skills) {
     });
 }
 export function buildCodexRuntimeDescriptor(input) {
+    const serviceAgentMode = input.serviceAgentMode === true;
     const commands = [
         {
             id: 'runtime-status',
@@ -157,7 +172,7 @@ export function buildCodexRuntimeDescriptor(input) {
         RUNTIME_STOP_ACTION,
         RUNTIME_STOP_AND_DROP_ACTION,
     ];
-    if (input.supportsCompact) {
+    if (input.supportsCompact && !serviceAgentMode) {
         commands.push({
             id: 'codex-compact-context',
             label: 'Compact',
@@ -177,20 +192,22 @@ export function buildCodexRuntimeDescriptor(input) {
     }
     const descriptor = buildFirstPartyCodingRuntimeDescriptor({
         clientType: 'codex',
-        models: input.models,
-        workspaces: input.workspaces,
-        workspaceRoots: input.workspaceRoots,
-        executionModes: input.executionModes,
-        permissionModes: input.permissionModes,
-        defaultPermissionMode: input.defaultPermissionMode,
+        models: serviceAgentMode ? [] : input.models,
+        workspaces: serviceAgentMode ? [] : input.workspaces,
+        workspaceRoots: serviceAgentMode ? undefined : input.workspaceRoots,
+        executionModes: serviceAgentMode ? [] : input.executionModes,
+        permissionModes: serviceAgentMode ? [] : input.permissionModes,
+        defaultPermissionMode: serviceAgentMode ? undefined : input.defaultPermissionMode,
         permissionModeLabel: 'Execution policy',
         modelLiveBehavior: 'next_turn',
-        effortOptions: input.effortOptions ?? [...CODEX_EFFORT_OPTIONS],
-        defaultEffort: input.defaultEffort ?? 'medium',
+        effortOptions: serviceAgentMode
+            ? []
+            : input.effortOptions ?? [...CODEX_EFFORT_OPTIONS],
+        defaultEffort: serviceAgentMode ? undefined : input.defaultEffort ?? 'medium',
         effortLiveBehavior: 'next_turn',
         presentation: input.presentation,
         streamingTextMode: 'snapshot',
-        ...(input.supportsPlanMode
+        ...(input.supportsPlanMode && !serviceAgentMode
             ? {
                 turnModes: [
                     {
@@ -220,7 +237,7 @@ export function buildCodexRuntimeDescriptor(input) {
                     rich: {
                         schema: 'canon.card.v1',
                         lifecycle: 'blocking_requires_action',
-                        responder: 'agent_owner',
+                        ...(serviceAgentMode ? {} : { responder: 'agent_owner' }),
                         result: 'action_or_values',
                         maxTimeoutMs: 30 * 60_000,
                         blockKinds: ['summary', 'metricGrid', 'chart', 'table', 'list', 'callout', 'actions'],
@@ -231,6 +248,13 @@ export function buildCodexRuntimeDescriptor(input) {
             }
             : {}),
     });
+    if (serviceAgentMode) {
+        const { runtimeControls: _runtimeControls, ...serviceDescriptor } = descriptor;
+        return {
+            ...serviceDescriptor,
+            coreControls: [],
+        };
+    }
     if (input.models.length > 0) {
         return descriptor;
     }
@@ -269,6 +293,9 @@ export function resolveSessionExecutionMode(config, serviceAgentMode = false) {
         return config.executionMode;
     throw new ExecutionEnvironmentError('Session config is missing an execution mode.', 'Choose Isolated worktree or Use shared project before starting this coding session.');
 }
+export function resolveCodexSessionConfig(config, serviceAgentMode = false) {
+    return serviceAgentMode ? null : config ?? null;
+}
 export function resolveWorkspaceCwd(config, serviceAgentMode = false) {
     return resolveHostWorkspaceCwd({
         workspaceOptions,
@@ -311,6 +338,9 @@ export function resolveCodexEffectiveRuntimePolicy(input) {
         baseCwd: input.environment.baseCwd,
         executionMode: input.environment.mode,
         permissionMode: permissionMode ?? null,
+        ...(input.serviceAgentMode
+            ? { serviceAgentMode: true, model: model ?? null }
+            : {}),
         sandbox,
         // `--ask-for-approval` is rejected at startup, so this was always null.
         // The key must stay: it is hashed into every persisted thread fingerprint.
@@ -400,6 +430,14 @@ function parsePlanCommand(content) {
         content: rest || 'Please inspect the request and propose a plan before making changes.',
     };
 }
+export function resolveCodexPlanCommand(input) {
+    if (!input.useAppServer || input.serviceAgentMode) {
+        return { planMode: false, content: input.content };
+    }
+    return input.requestedPlanMode
+        ? { planMode: true, content: input.content }
+        : parsePlanCommand(input.content);
+}
 function mapCodexQuestions(value) {
     if (!Array.isArray(value))
         return undefined;
@@ -453,6 +491,12 @@ function mapCodexQuestions(value) {
 function isRecord(value) {
     return Boolean(value && typeof value === 'object' && !Array.isArray(value));
 }
+export function isCodexPlanApprovalReply(metadata, serviceAgentMode = false) {
+    return !serviceAgentMode
+        && isRecord(metadata)
+        && metadata.type === 'plan_approval_reply'
+        && typeof metadata.decision === 'string';
+}
 function readString(record, key) {
     const value = record[key];
     return typeof value === 'string' && value.trim() ? value.trim() : undefined;
@@ -1205,7 +1249,7 @@ export async function main() {
             evictOldestIdle();
         }
         const creation = (async () => {
-            const config = await loadSessionConfig(conversationId, agentId, rtdb);
+            const config = resolveCodexSessionConfig(await loadSessionConfig(conversationId, agentId, rtdb), serviceAgentMode);
             const sessionExecutionMode = resolveSessionExecutionMode(config, serviceAgentMode);
             const workspaceCwd = resolveWorkspaceCwd(config, serviceAgentMode);
             const environment = prepareConversationEnvironment({
@@ -1718,9 +1762,14 @@ export async function main() {
             persistInboundRecoveryCursorWhenIdle(input.conversationId, input.message.id);
             return;
         }
-        if (isRecord(input.message.metadata)
-            && input.message.metadata.type === 'plan_approval_reply'
-            && typeof input.message.metadata.decision === 'string') {
+        if (input.message.metadata?.type === 'plan_approval_reply') {
+            if (!isCodexPlanApprovalReply(input.message.metadata, serviceAgentMode)) {
+                // A service agent never advertises or enters plan mode. Consume stale
+                // replies left by an older coding descriptor instead of turning them
+                // into hidden plan/implementation prompts after an upgrade or restart.
+                persistInboundRecoveryCursorWhenIdle(input.conversationId, input.message.id);
+                return;
+            }
             const planId = readString(input.message.metadata, 'planId');
             if (planId && runtimeRequests.handleMessage(input.conversationId, {
                 senderId: input.message.senderId,
@@ -1758,11 +1807,12 @@ export async function main() {
         const renderedContent = renderInboundContent(input.message, materialized);
         const turnMetadata = normalizeTurnMetadata(input.message.metadata);
         const requestedPlanMode = turnMetadata?.requestedTurnMode === 'plan';
-        const planCommand = useAppServer
-            ? requestedPlanMode
-                ? { planMode: true, content: renderedContent }
-                : parsePlanCommand(renderedContent)
-            : { planMode: false, content: renderedContent };
+        const planCommand = resolveCodexPlanCommand({
+            content: renderedContent,
+            requestedPlanMode,
+            useAppServer,
+            serviceAgentMode,
+        });
         const content = planCommand.content;
         const hydrated = await loadHydratedInboundContext({
             conversationId: input.conversationId,
@@ -2354,14 +2404,18 @@ export async function main() {
     });
     let codexSkills = [];
     const buildCurrentRuntimeDescriptor = () => ({
-        defaultWorkspaceId: workspaceOptions[0]?.id,
+        ...(serviceAgentMode
+            ? {}
+            : {
+                defaultWorkspaceId: workspaceOptions[0]?.id,
+                availableWorkspaces: buildPublicWorkspaceOptions(workspaceOptions),
+                availableExecutionModes: hostAvailableExecutionModes,
+                availablePermissionModes: [...codexPermissionEnvelope.availablePermissionModes],
+                ...(codexPermissionEnvelope.defaultPermissionMode
+                    ? { defaultPermissionMode: codexPermissionEnvelope.defaultPermissionMode }
+                    : {}),
+            }),
         ...(codexDefaultModel ? { defaultModel: codexDefaultModel } : {}),
-        availableWorkspaces: buildPublicWorkspaceOptions(workspaceOptions),
-        availableExecutionModes: hostAvailableExecutionModes,
-        availablePermissionModes: [...codexPermissionEnvelope.availablePermissionModes],
-        ...(codexPermissionEnvelope.defaultPermissionMode
-            ? { defaultPermissionMode: codexPermissionEnvelope.defaultPermissionMode }
-            : {}),
         runtimeDescriptor: buildCodexRuntimeDescriptor({
             models: codexModelOptions,
             effortOptions: codexEffortOptions,
@@ -2376,6 +2430,7 @@ export async function main() {
             supportsCompact: useAppServer,
             supportsRichCards: useAppServer,
             skills: codexSkills,
+            serviceAgentMode,
         }),
     });
     let runtimeDescriptor = buildCurrentRuntimeDescriptor();
@@ -2421,6 +2476,11 @@ export async function main() {
         const session = sessions.get(conversationId);
         if (!session || session.closed)
             return;
+        if (serviceAgentMode) {
+            console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Ignoring user session controls for service-agent runtime`);
+            writeState(session);
+            return;
+        }
         let modelChanged = false;
         if (control.model && control.model !== session.state.model) {
             if (codexModelOptions.length > 0 && !codexModelOptions.some((option) => option.value === control.model)) {
@@ -2577,10 +2637,27 @@ export async function main() {
                 workspaceOptions,
                 defaultCwd: workingDir,
                 extraSessionConfigFields: CODEX_SESSION_CONFIG_FIELDS,
-                liveSessionConfigByConversation: new Map(Array.from(sessions.values()).map((session) => {
+                liveSessionConfigByConversation: new Map(Array.from(serviceAgentMode ? knownConversationIds : sessions.keys()).map((conversationId) => {
+                    const session = sessions.get(conversationId);
+                    if (serviceAgentMode) {
+                        return [
+                            conversationId,
+                            buildCodexServiceSnapshotConfig({
+                                model: codexDefaultModel ?? session?.state.model ?? undefined,
+                                permissionMode: codexPermissionEnvelope.defaultPermissionMode,
+                                effort: codexDefaultEffort ?? session?.state.effort ?? undefined,
+                                workspaceId: resolveWorkspaceIdForBaseCwd(workingDir) ?? undefined,
+                            }),
+                        ];
+                    }
+                    if (!session) {
+                        // Non-service snapshots are published only for live sessions,
+                        // but keep this branch total if that invariant changes.
+                        return [conversationId, {}];
+                    }
                     const workspaceId = resolveWorkspaceIdForBaseCwd(session.environment.baseCwd);
                     return [
-                        session.conversationId,
+                        conversationId,
                         buildCodexLiveSessionConfig({
                             model: session.state.model,
                             permissionMode: session.state.permissionMode,
@@ -2749,7 +2826,7 @@ export async function main() {
                 console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Recovery cursor was not found within ${STARTUP_RECOVERY_MAX_MESSAGES} messages; replaying the bounded recent window`);
             }
             for (const message of recovered.messages) {
-                const isPlanReply = message.metadata?.type === 'plan_approval_reply';
+                const isPlanReply = isCodexPlanApprovalReply(message.metadata, serviceAgentMode);
                 if (!isPlanReply && !shouldTriggerAgentTurn({
                     senderType: message.senderType,
                     metadata: message.metadata,

package/dist/session-store.d.ts

@@ -3,6 +3,8 @@ export declare function buildCodexThreadPolicyFingerprint(input: {
     baseCwd: string;
     executionMode?: ExecutionEnvironmentMode;
     permissionMode?: string | null;
+    model?: string | null;
+    serviceAgentMode?: boolean;
     sandbox?: string | null;
     approvalPolicy?: string | null;
     fullAuto?: boolean;

package/dist/session-store.js

@@ -6,6 +6,14 @@ export function buildCodexThreadPolicyFingerprint(input) {
         baseCwd: input.baseCwd,
         executionMode: input.executionMode ?? null,
         permissionMode: input.permissionMode ?? null,
+        // Service agents make the model a host-owned runtime choice. Include it,
+        // plus an explicit service-mode marker, so the first service-agent
+        // release drops coding threads that may retain a member-selected model
+        // and later host model changes start a clean thread. Ordinary Codex host
+        // fingerprints intentionally remain byte-for-byte compatible.
+        ...(input.serviceAgentMode
+            ? { serviceAgentMode: true, model: input.model ?? null }
+            : {}),
         sandbox: input.sandbox ?? null,
         approvalPolicy: input.approvalPolicy ?? null,
         fullAuto: input.fullAuto === true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/codex-plugin",
-  "version": "0.26.1",
+  "version": "0.26.2",
   "description": "Canon host integration for Codex CLI",
   "type": "module",
   "main": "dist/index.js",