@parall/codex-agent 1.42.1 → 1.43.0

package/dist/dispatch.d.ts

@@ -7,6 +7,14 @@ type CodexAppServerAdapterOptions = Pick<CodexAgentConfig, 'approvalPolicy' | 'c
     contextFilePath?: string;
     contextDirPath?: string;
     useParallProvider?: boolean;
+    /**
+     * Channel-capability shim directory (agent-core's capabilityBinDir),
+     * prepended to the subprocess PATH unconditionally. The DIRECTORY is
+     * constant for the bridge's lifetime; its CONTENT tracks capability
+     * grants, so a grant or revocation reaches even a long-lived app-server
+     * on its next shell command — no respawn needed.
+     */
+    capabilityBinDir?: string;
 };
 export declare class CodexAppServerAdapter implements DispatchAdapter {
     private readonly opts;
@@ -41,6 +49,16 @@ export declare class CodexAppServerAdapter implements DispatchAdapter {
     forkSession({ sessionKey: parentSessionKey }: ForkOpts): Promise<ForkSessionHandle | null>;
     cleanupFork({ fork }: CleanupForkOpts): void;
     private logForkFailure;
+    /**
+     * Lazily restart the app-server before the NEXT turn: the workspace
+     * config.toml (developer_instructions, carrying capability fragments) is
+     * loaded at process start, so a changed fragment set needs a respawn to
+     * reach the prompt. Deferred to the next dispatch with no active turns —
+     * never kills an in-flight turn; thread state survives via thread/resume.
+     */
+    requestProcessRestart(): void;
+    private restartRequested;
+    private applyPendingRestart;
     stop(): Promise<void>;
     private ensureStarted;
     private doStart;

package/dist/dispatch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EACf,YAAY,EACZ,QAAQ,EACR,iBAAiB,EACjB,aAAa,EACb,YAAY,EACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAIpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE,KAAK,4BAA4B,GAAG,IAAI,CACtC,gBAAgB,EACd,gBAAgB,GAChB,UAAU,GACV,WAAW,GACX,OAAO,GACP,iBAAiB,GACjB,SAAS,GACT,cAAc,CACjB,GAAG;IACF,cAAc,EAAE,mBAAmB,CAAC;IACpC,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B,CAAC;AAqCF,qBAAa,qBAAsB,YAAW,eAAe;IA+B/C,OAAO,CAAC,QAAQ,CAAC,IAAI;IA9BjC,OAAO,CAAC,MAAM,CAAmC;IACjD,OAAO,CAAC,IAAI,CAA+C;IAC3D,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,YAAY,CAA8B;IAClD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA+B;IAC3D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA6B;IAC3D,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA6B;IAC/D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqB;IACtD,OAAO,CAAC,QAAQ,CAAS;IAEzB;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;gBAYQ,IAAI,EAAE,4BAA4B;IAE/D,YAAY,CAAC,MAAM,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI;IAMhF,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAqB/E,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAUvC,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAI1C,QAAQ,CAAC,EACd,KAAK,EACL,YAAY,EACZ,UAAU,EACV,OAAO,GACR,EAAE,YAAY,GAAG,aAAa,CAAC,YAAY,CAAC;IA6P7C,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAMjD,WAAW,CAAC,EAAE,UAAU,EAAE,gBAAgB,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAgChG,WAAW,CAAC,EAAE,IAAI,EAAE,EAAE,eAAe;IAIrC,OAAO,CAAC,cAAc;IAKhB,IAAI;YAiBI,aAAa;YA2Bb,OAAO;IAuFrB,OAAO,CAAC,qBAAqB;YAmCf,UAAU;IA6CxB,OAAO,CAAC,iBAAiB;CA2B1B"}
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EACf,YAAY,EACZ,QAAQ,EACR,iBAAiB,EACjB,aAAa,EACb,YAAY,EACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAIpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE,KAAK,4BAA4B,GAAG,IAAI,CACtC,gBAAgB,EACd,gBAAgB,GAChB,UAAU,GACV,WAAW,GACX,OAAO,GACP,iBAAiB,GACjB,SAAS,GACT,cAAc,CACjB,GAAG;IACF,cAAc,EAAE,mBAAmB,CAAC;IACpC,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAqCF,qBAAa,qBAAsB,YAAW,eAAe;IA+B/C,OAAO,CAAC,QAAQ,CAAC,IAAI;IA9BjC,OAAO,CAAC,MAAM,CAAmC;IACjD,OAAO,CAAC,IAAI,CAA+C;IAC3D,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,YAAY,CAA8B;IAClD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA+B;IAC3D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA6B;IAC3D,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA6B;IAC/D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqB;IACtD,OAAO,CAAC,QAAQ,CAAS;IAEzB;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;gBAYQ,IAAI,EAAE,4BAA4B;IAE/D,YAAY,CAAC,MAAM,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI;IAMhF,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAqB/E,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAUvC,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAI1C,QAAQ,CAAC,EACd,KAAK,EACL,YAAY,EACZ,UAAU,EACV,OAAO,GACR,EAAE,YAAY,GAAG,aAAa,CAAC,YAAY,CAAC;IA8P7C,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAMjD,WAAW,CAAC,EAAE,UAAU,EAAE,gBAAgB,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAgChG,WAAW,CAAC,EAAE,IAAI,EAAE,EAAE,eAAe;IAIrC,OAAO,CAAC,cAAc;IAKtB;;;;;;OAMG;IACH,qBAAqB,IAAI,IAAI;IAI7B,OAAO,CAAC,gBAAgB,CAAS;YAEnB,mBAAmB;IAS3B,IAAI;YAuBI,aAAa;YA2Bb,OAAO;IAuGrB,OAAO,CAAC,qBAAqB;YAmCf,UAAU;IA6CxB,OAAO,CAAC,iBAAiB;CA2B1B"}

package/dist/dispatch.js

@@ -1,6 +1,7 @@
 import { execSync, spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import * as fs from 'node:fs';
+import * as path from 'node:path';
 import { appendPreparedLocalAttachmentRefs, ensureLocalAttachmentGitExclude, pinLocalAttachmentPaths, } from '@parall/agent-core/internal/attachment-input';
 import { normalizeApprovalPolicy, normalizeSandbox } from './config.js';
 import { EventMapper } from './event-mapping.js';
@@ -125,6 +126,7 @@ export class CodexAppServerAdapter {
             }
             (this.opts.log ?? context.log)?.warn?.(`pending steer invalidated (subprocess died); falling through to normal dispatch`);
         }
+        await this.applyPendingRestart(context.log);
         await this.ensureStarted(context.log);
         // After ensureStarted resolves the subprocess could still die before we
         // capture the client (handleSubprocessClose nulls this.client). Yield a
@@ -405,6 +407,24 @@ export class CodexAppServerAdapter {
         this.opts.log?.warn?.(`thread/fork failed: ${errToString(err)}`);
         return null;
     }
+    /**
+     * Lazily restart the app-server before the NEXT turn: the workspace
+     * config.toml (developer_instructions, carrying capability fragments) is
+     * loaded at process start, so a changed fragment set needs a respawn to
+     * reach the prompt. Deferred to the next dispatch with no active turns —
+     * never kills an in-flight turn; thread state survives via thread/resume.
+     */
+    requestProcessRestart() {
+        this.restartRequested = true;
+    }
+    restartRequested = false;
+    async applyPendingRestart(log) {
+        if (!this.restartRequested || this.activeTurns.size > 0)
+            return;
+        this.restartRequested = false;
+        (log ?? this.opts.log)?.info?.('restarting codex app-server to pick up updated developer_instructions');
+        await this.stop();
+    }
     async stop() {
         this.stopping = true;
         const proc = this.proc;
@@ -414,6 +434,12 @@ export class CodexAppServerAdapter {
         this.initialized = false;
         this.activeTurnIds.clear();
         this.pendingInjections.clear();
+        // Resume markers are process-local facts. Clear them HERE, synchronously:
+        // the old child's close callback sees the replaced refs and skips its
+        // cleanup as stale, so a marker surviving stop() would make the next
+        // dispatch treat the persisted thread as already resumed in the NEW
+        // process and lose conversation continuity when turn/start rejects.
+        this.resumedThreadIds.clear();
         if (client)
             client.dispose(new Error('adapter stopped'));
         if (proc && proc.exitCode === null && proc.signalCode === null) {
@@ -468,6 +494,22 @@ export class CodexAppServerAdapter {
             FORCE_COLOR: '0',
             NO_COLOR: '1',
         };
+        // Channel-capability shims resolve ahead of any globally-installed CLI of
+        // the same name (the shim owns auth; the real binary is found further
+        // down the PATH by the shim itself). On Windows env keys are
+        // case-insensitive and the host key is usually `Path`; after the
+        // plain-object spread a literal `PATH` write would SPLIT the key
+        // (undefined which wins in the child), so reuse the parent's casing. On
+        // POSIX keys are case-SENSITIVE — match `PATH` exactly.
+        if (this.opts.capabilityBinDir) {
+            const pathKey = IS_WIN32
+                ? (Object.keys(env).find((k) => k.toUpperCase() === 'PATH') ?? 'PATH')
+                : 'PATH';
+            const existing = env[pathKey];
+            env[pathKey] = existing
+                ? `${this.opts.capabilityBinDir}${path.delimiter}${existing}`
+                : this.opts.capabilityBinDir;
+        }
         if (this.opts.contextFilePath) {
             env.PRLL_CONTEXT_FILE = this.opts.contextFilePath;
         }

package/dist/index.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import * as os from 'node:os';
-import { ParallAgentGateway, createPlatformConfigManager, createLogger, createOtelLogger, childLogger, deriveModelIsPin, resolveRuntimeModel, parseShutdownDeadlineMs, parseForkDeadlineMs, parseDispatchDeadlineMs, parseProviderConfig, clearAllProviderCreds, llmSource, initAgentTelemetry, } from '@parall/agent-core';
+import { ParallAgentGateway, capabilityBinDir, createPlatformConfigManager, createLogger, createOtelLogger, childLogger, deriveModelIsPin, materializeChannelCapabilities, resolveRuntimeModel, parseShutdownDeadlineMs, parseForkDeadlineMs, parseDispatchDeadlineMs, parseProviderConfig, clearAllProviderCreds, llmSource, initAgentTelemetry, } from '@parall/agent-core';
 import { ApiError, ParallClient, ParallWs } from '@parall/sdk';
 import { buildCodexRuntimeKey, contextFilePathForSession, dispatchContextDirPath, resolveCodexAgentConfig, resolveWsUrl, sessionStateFilePathForRuntime, stepIdFilePathForSession, } from './config.js';
 import { CodexAppServerAdapter } from './dispatch.js';
 import { CodexSessionManager } from './session-manager.js';
-import { ensureCodexWorkspace, ensureParallProvider, ensureWorkspaceTrusted, isParallProxyMode, } from './workspace.js';
+import { ensureCodexWorkspace, ensureParallProvider, ensureWorkspaceTrusted, isParallProxyMode, writeCodexSystemPrompt, } from './workspace.js';
 const log = createLogger('codex-agent');
 let activeLog = log;
 async function getAgentMeWithLegacyFallback(client, orgId) {
@@ -58,11 +58,11 @@ async function main() {
             ensureParallProvider(config.codexHome, config.apiUrl, agentLog);
             agentLog.info('parall custom provider configured (Responses API HTTP/SSE mode)');
         }
-        ensureCodexWorkspace(config.workspaceDir, agentLog, {
+        const agentIdentity = {
             userId: agentUserId,
             displayName: me.display_name,
             description: me.agent_profile?.description ?? undefined,
-        });
+        };
         const runtimeKey = config.runtimeKey || buildCodexRuntimeKey(agentUserId);
         const mainContextFilePath = contextFilePathForSession(config.stateDir, runtimeKey);
         const sessionStateFilePath = sessionStateFilePathForRuntime(config.stateDir, runtimeKey);
@@ -79,6 +79,21 @@ async function main() {
             log: agentLog,
         });
         const platformDefaults = await configMgr.fetch();
+        // Channel capabilities: ONE call materializes the local artifacts (the
+        // lark-cli auth shim under capabilityBinDir) and yields the system-prompt
+        // fragments, so declaration and shim can never diverge within a refresh.
+        // No freshness gate — a stale (LKG-cached) declaration fail-closes at the
+        // mint endpoint, which re-evaluates the grant on every token request.
+        const applyChannelCapabilities = () => {
+            const caps = configMgr.capabilities();
+            materializeChannelCapabilities(config.stateDir, caps, agentLog);
+            return caps.map((c) => c.fragment);
+        };
+        // Assemble the workspace AFTER the first config fetch so
+        // developer_instructions carries the capability declarations from boot.
+        const bootCapabilityFragments = applyChannelCapabilities();
+        let lastCapabilityFragments = bootCapabilityFragments.join('\n\n');
+        ensureCodexWorkspace(config.workspaceDir, agentLog, agentIdentity, bootCapabilityFragments);
         // Model precedence: operator PIN (override) > env > server FLOOR. The server
         // now says which it is via model_is_pin (deriveModelIsPin presence-gates the
         // dual-read: old servers omit it → fall back to model_management). A PIN beats
@@ -104,6 +119,7 @@ async function main() {
             contextFilePath: mainContextFilePath,
             contextDirPath: dispatchContextDirPath(config.stateDir),
             useParallProvider,
+            capabilityBinDir: capabilityBinDir(config.stateDir),
         });
         // Shared by onConfigUpdate + onSessionReady. /agents/me is only consumed as
         // deriveModelIsPin's legacy fallback when the server omits model_is_pin
@@ -129,6 +145,24 @@ async function main() {
                 model: resolveRuntimeModel(isPin, updated.model, config.model) ?? null,
                 reasoningEffort: updated.thinkingEffort ?? config.reasoningEffort ?? null,
             });
+            // Capability heat-update: re-materialize shims + rewrite the prompt
+            // surfaces. The write is refresh-tolerant (warn + retry next refresh);
+            // only a SUCCESSFUL write with a changed fragment set schedules the
+            // lazy app-server restart (developer_instructions loads at spawn).
+            const fragments = applyChannelCapabilities();
+            const joinedFragments = fragments.join('\n\n');
+            let promptWritten = true;
+            try {
+                writeCodexSystemPrompt(config.workspaceDir, agentIdentity, fragments);
+            }
+            catch (err) {
+                promptWritten = false;
+                agentLog.warn(`system prompt refresh write failed (retrying next refresh): ${String(err)}`);
+            }
+            if (promptWritten && joinedFragments !== lastCapabilityFragments) {
+                lastCapabilityFragments = joinedFragments;
+                adapter.requestProcessRestart();
+            }
         };
         const gateway = new ParallAgentGateway({
             accountId: agentUserId,
@@ -152,6 +186,9 @@ async function main() {
             },
             dispatchAdapter: adapter,
             log: agentLog,
+            // Live capability view for hint routing: the channel reply hint points
+            // at the vendor CLI only while the grant is active.
+            getCapabilityKeys: () => configMgr.capabilities().map((c) => c.key),
             shutdownDeadlineMs: parseShutdownDeadlineMs(process.env.PRLL_SHUTDOWN_DEADLINE_MS),
             forkDeadlineMs: parseForkDeadlineMs(process.env.PRLL_FORK_DEADLINE_MS),
             dispatchDeadlineMs: parseDispatchDeadlineMs(process.env.PRLL_DISPATCH_DEADLINE_MS),

package/dist/workspace.d.ts

@@ -120,7 +120,8 @@ export declare function isParallProxyMode(env?: NodeJS.ProcessEnv): boolean;
 export declare function ensureParallProvider(codexHome: string, apiUrl: string, log?: {
     warn: (msg: string) => void;
 }): void;
+export declare function writeCodexSystemPrompt(workspaceDir: string, agentIdentity?: AgentIdentity, capabilityFragments?: string[]): void;
 export declare function ensureCodexWorkspace(workspaceDir: string, log?: {
     warn: (msg: string) => void;
-}, agentIdentity?: AgentIdentity): void;
+}, agentIdentity?: AgentIdentity, capabilityFragments?: string[]): void;
 //# sourceMappingURL=workspace.d.ts.map

package/dist/workspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB;;;;CAI/B,CAAC;AAUF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GAAG,SAAS,EAChD,EAAE,EAAE,MAAM,IAAI,GACb,IAAI,CAkJN;AAED;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,EAAE;IACnC,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAC;IAClC,mBAAmB,CAAC,EAAE,MAAM,IAAI,CAAC;IACjC,iBAAiB,CAAC,EAAE,MAAM,IAAI,CAAC;CAC3B,CAAC;AAuJP;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,GAAG,CAAC,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GACpC,IAAI,CAEN;AAqGD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAK/E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,GAAG,CAAC,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GACpC,IAAI,CAEN;AAwDD,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,MAAM,EACpB,GAAG,CAAC,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,EACrC,aAAa,CAAC,EAAE,aAAa,GAC5B,IAAI,CAqBN"}
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB;;;;CAI/B,CAAC;AAUF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GAAG,SAAS,EAChD,EAAE,EAAE,MAAM,IAAI,GACb,IAAI,CAkJN;AAED;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,EAAE;IACnC,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAC;IAClC,mBAAmB,CAAC,EAAE,MAAM,IAAI,CAAC;IACjC,iBAAiB,CAAC,EAAE,MAAM,IAAI,CAAC;CAC3B,CAAC;AAuJP;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,GAAG,CAAC,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GACpC,IAAI,CAEN;AAqGD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAK/E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,GAAG,CAAC,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GACpC,IAAI,CAEN;AAoED,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,MAAM,EACpB,aAAa,CAAC,EAAE,aAAa,EAC7B,mBAAmB,CAAC,EAAE,MAAM,EAAE,GAC7B,IAAI,CAqBN;AAED,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,MAAM,EACpB,GAAG,CAAC,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,EACrC,aAAa,CAAC,EAAE,aAAa,EAC7B,mBAAmB,CAAC,EAAE,MAAM,EAAE,GAC7B,IAAI,CAQN"}

package/dist/workspace.js

@@ -585,21 +585,42 @@ function findSectionEnd(content, fromIndex) {
     const nextHeader = content.indexOf('\n[', fromIndex);
     return nextHeader === -1 ? content.length : nextHeader;
 }
-export function ensureCodexWorkspace(workspaceDir, log, agentIdentity) {
-    const systemPrompt = [
+// writeCodexSystemPrompt (re)writes the standing platform prompt surfaces:
+// .parall/system-prompt.md (human-inspectable copy) and the workspace
+// .codex/config.toml developer_instructions (what the CLI actually loads).
+// capabilityFragments are platform-derived capability declarations
+// (agents.capabilities[].fragment) — placed after the platform reference
+// guide, before skill references; empty/absent = no capability section.
+// Split out from ensureCodexWorkspace so the bridge can rewrite on
+// platform-config heat-update; the app-server reads workspace config at
+// process start, so the caller pairs a CHANGED fragment set with
+// adapter.requestProcessRestart(). Throws on failure BY DESIGN — at boot the
+// prompt is mandatory, so a write failure must fail startup loudly; the
+// refresh hot path wraps this in try/catch and retries next refresh.
+export function writeCodexSystemPrompt(workspaceDir, agentIdentity, capabilityFragments) {
+    const parts = [
         buildIdentity(agentIdentity),
         BRIDGE_WORKSPACE_INSTRUCTIONS,
         PRLL_BEHAVIOR,
         PRLL_REFERENCE_GUIDE,
-        buildSkillReferences(workspaceDir),
-    ].join('\n\n');
-    fs.mkdirSync(workspaceDir, { recursive: true });
+    ];
+    if (capabilityFragments && capabilityFragments.length > 0) {
+        parts.push(capabilityFragments.join('\n\n'));
+    }
+    parts.push(buildSkillReferences(workspaceDir));
+    const systemPrompt = parts.join('\n\n');
     const parallDir = path.join(workspaceDir, '.parall');
     fs.mkdirSync(parallDir, { recursive: true });
     fs.writeFileSync(path.join(parallDir, 'system-prompt.md'), systemPrompt, 'utf8');
-    writeSkillFiles(path.join(parallDir, 'skills'));
     const codexConfigDir = path.join(workspaceDir, '.codex');
     fs.mkdirSync(codexConfigDir, { recursive: true });
     const toml = `developer_instructions = """\n${systemPrompt.replace(/\\/g, '\\\\').replace(/"""/g, '\\"""')}\n"""\n`;
     fs.writeFileSync(path.join(codexConfigDir, 'config.toml'), toml, 'utf8');
 }
+export function ensureCodexWorkspace(workspaceDir, log, agentIdentity, capabilityFragments) {
+    fs.mkdirSync(workspaceDir, { recursive: true });
+    // Boot: let a write failure PROPAGATE (fatal) — startup must not proceed
+    // without the platform prompt. The refresh path tolerates failure.
+    writeCodexSystemPrompt(workspaceDir, agentIdentity, capabilityFragments);
+    writeSkillFiles(path.join(workspaceDir, '.parall', 'skills'));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/codex-agent",
-  "version": "1.42.1",
+  "version": "1.43.0",
   "description": "Codex CLI bridge runtime for self-hosted Parall agents",
   "license": "MIT",
   "repository": {
@@ -26,9 +26,9 @@
   ],
   "dependencies": {
     "smol-toml": "^1.6.1",
-    "@parall/agent-core": "1.42.1",
-    "@parall/cli": "1.42.1",
-    "@parall/sdk": "1.42.1"
+    "@parall/agent-core": "1.43.0",
+    "@parall/cli": "1.43.0",
+    "@parall/sdk": "1.43.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/dispatch.ts

@@ -1,6 +1,7 @@
 import { execSync, spawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import * as fs from 'node:fs';
+import * as path from 'node:path';
 import {
   appendPreparedLocalAttachmentRefs,
   ensureLocalAttachmentGitExclude,
@@ -37,6 +38,14 @@ type CodexAppServerAdapterOptions = Pick<
   contextFilePath?: string;
   contextDirPath?: string;
   useParallProvider?: boolean;
+  /**
+   * Channel-capability shim directory (agent-core's capabilityBinDir),
+   * prepended to the subprocess PATH unconditionally. The DIRECTORY is
+   * constant for the bridge's lifetime; its CONTENT tracks capability
+   * grants, so a grant or revocation reaches even a long-lived app-server
+   * on its next shell command — no respawn needed.
+   */
+  capabilityBinDir?: string;
 };
 
 type TurnEventEnvelope =
@@ -174,6 +183,7 @@ export class CodexAppServerAdapter implements DispatchAdapter {
       );
     }
 
+    await this.applyPendingRestart(context.log);
     await this.ensureStarted(context.log);
     // After ensureStarted resolves the subprocess could still die before we
     // capture the client (handleSubprocessClose nulls this.client). Yield a
@@ -453,6 +463,28 @@ export class CodexAppServerAdapter implements DispatchAdapter {
     return null;
   }
 
+  /**
+   * Lazily restart the app-server before the NEXT turn: the workspace
+   * config.toml (developer_instructions, carrying capability fragments) is
+   * loaded at process start, so a changed fragment set needs a respawn to
+   * reach the prompt. Deferred to the next dispatch with no active turns —
+   * never kills an in-flight turn; thread state survives via thread/resume.
+   */
+  requestProcessRestart(): void {
+    this.restartRequested = true;
+  }
+
+  private restartRequested = false;
+
+  private async applyPendingRestart(log?: GatewayLogger): Promise<void> {
+    if (!this.restartRequested || this.activeTurns.size > 0) return;
+    this.restartRequested = false;
+    (log ?? this.opts.log)?.info?.(
+      'restarting codex app-server to pick up updated developer_instructions',
+    );
+    await this.stop();
+  }
+
   async stop() {
     this.stopping = true;
     const proc = this.proc;
@@ -462,6 +494,12 @@ export class CodexAppServerAdapter implements DispatchAdapter {
     this.initialized = false;
     this.activeTurnIds.clear();
     this.pendingInjections.clear();
+    // Resume markers are process-local facts. Clear them HERE, synchronously:
+    // the old child's close callback sees the replaced refs and skips its
+    // cleanup as stale, so a marker surviving stop() would make the next
+    // dispatch treat the persisted thread as already resumed in the NEW
+    // process and lose conversation continuity when turn/start rejects.
+    this.resumedThreadIds.clear();
     if (client) client.dispose(new Error('adapter stopped'));
     if (proc && proc.exitCode === null && proc.signalCode === null) {
       if (!IS_WIN32 || !proc.pid || !killWin32Tree(proc.pid)) {
@@ -515,6 +553,22 @@ export class CodexAppServerAdapter implements DispatchAdapter {
       FORCE_COLOR: '0',
       NO_COLOR: '1',
     };
+    // Channel-capability shims resolve ahead of any globally-installed CLI of
+    // the same name (the shim owns auth; the real binary is found further
+    // down the PATH by the shim itself). On Windows env keys are
+    // case-insensitive and the host key is usually `Path`; after the
+    // plain-object spread a literal `PATH` write would SPLIT the key
+    // (undefined which wins in the child), so reuse the parent's casing. On
+    // POSIX keys are case-SENSITIVE — match `PATH` exactly.
+    if (this.opts.capabilityBinDir) {
+      const pathKey = IS_WIN32
+        ? (Object.keys(env).find((k) => k.toUpperCase() === 'PATH') ?? 'PATH')
+        : 'PATH';
+      const existing = env[pathKey];
+      env[pathKey] = existing
+        ? `${this.opts.capabilityBinDir}${path.delimiter}${existing}`
+        : this.opts.capabilityBinDir;
+    }
     if (this.opts.contextFilePath) {
       env.PRLL_CONTEXT_FILE = this.opts.contextFilePath;
     }

package/src/index.ts

@@ -3,11 +3,13 @@
 import * as os from 'node:os';
 import {
   ParallAgentGateway,
+  capabilityBinDir,
   createPlatformConfigManager,
   createLogger,
   createOtelLogger,
   childLogger,
   deriveModelIsPin,
+  materializeChannelCapabilities,
   resolveRuntimeModel,
   parseShutdownDeadlineMs,
   parseForkDeadlineMs,
@@ -34,6 +36,7 @@ import {
   ensureParallProvider,
   ensureWorkspaceTrusted,
   isParallProxyMode,
+  writeCodexSystemPrompt,
 } from './workspace.js';
 
 const log = createLogger('codex-agent');
@@ -88,11 +91,11 @@ async function main() {
       ensureParallProvider(config.codexHome, config.apiUrl, agentLog);
       agentLog.info('parall custom provider configured (Responses API HTTP/SSE mode)');
     }
-    ensureCodexWorkspace(config.workspaceDir, agentLog, {
+    const agentIdentity = {
       userId: agentUserId,
       displayName: me.display_name,
       description: me.agent_profile?.description ?? undefined,
-    });
+    };
     const runtimeKey = config.runtimeKey || buildCodexRuntimeKey(agentUserId);
     const mainContextFilePath = contextFilePathForSession(config.stateDir, runtimeKey);
     const sessionStateFilePath = sessionStateFilePathForRuntime(config.stateDir, runtimeKey);
@@ -111,6 +114,21 @@ async function main() {
       log: agentLog,
     });
     const platformDefaults = await configMgr.fetch();
+    // Channel capabilities: ONE call materializes the local artifacts (the
+    // lark-cli auth shim under capabilityBinDir) and yields the system-prompt
+    // fragments, so declaration and shim can never diverge within a refresh.
+    // No freshness gate — a stale (LKG-cached) declaration fail-closes at the
+    // mint endpoint, which re-evaluates the grant on every token request.
+    const applyChannelCapabilities = () => {
+      const caps = configMgr.capabilities();
+      materializeChannelCapabilities(config.stateDir, caps, agentLog);
+      return caps.map((c) => c.fragment);
+    };
+    // Assemble the workspace AFTER the first config fetch so
+    // developer_instructions carries the capability declarations from boot.
+    const bootCapabilityFragments = applyChannelCapabilities();
+    let lastCapabilityFragments = bootCapabilityFragments.join('\n\n');
+    ensureCodexWorkspace(config.workspaceDir, agentLog, agentIdentity, bootCapabilityFragments);
     // Model precedence: operator PIN (override) > env > server FLOOR. The server
     // now says which it is via model_is_pin (deriveModelIsPin presence-gates the
     // dual-read: old servers omit it → fall back to model_management). A PIN beats
@@ -143,6 +161,7 @@ async function main() {
       contextFilePath: mainContextFilePath,
       contextDirPath: dispatchContextDirPath(config.stateDir),
       useParallProvider,
+      capabilityBinDir: capabilityBinDir(config.stateDir),
     });
 
     // Shared by onConfigUpdate + onSessionReady. /agents/me is only consumed as
@@ -172,6 +191,23 @@ async function main() {
         model: resolveRuntimeModel(isPin, updated.model, config.model) ?? null,
         reasoningEffort: updated.thinkingEffort ?? config.reasoningEffort ?? null,
       });
+      // Capability heat-update: re-materialize shims + rewrite the prompt
+      // surfaces. The write is refresh-tolerant (warn + retry next refresh);
+      // only a SUCCESSFUL write with a changed fragment set schedules the
+      // lazy app-server restart (developer_instructions loads at spawn).
+      const fragments = applyChannelCapabilities();
+      const joinedFragments = fragments.join('\n\n');
+      let promptWritten = true;
+      try {
+        writeCodexSystemPrompt(config.workspaceDir, agentIdentity, fragments);
+      } catch (err) {
+        promptWritten = false;
+        agentLog.warn(`system prompt refresh write failed (retrying next refresh): ${String(err)}`);
+      }
+      if (promptWritten && joinedFragments !== lastCapabilityFragments) {
+        lastCapabilityFragments = joinedFragments;
+        adapter.requestProcessRestart();
+      }
     };
 
     const gateway = new ParallAgentGateway({
@@ -196,6 +232,9 @@ async function main() {
       },
       dispatchAdapter: adapter,
       log: agentLog,
+      // Live capability view for hint routing: the channel reply hint points
+      // at the vendor CLI only while the grant is active.
+      getCapabilityKeys: () => configMgr.capabilities().map((c) => c.key),
       shutdownDeadlineMs: parseShutdownDeadlineMs(process.env.PRLL_SHUTDOWN_DEADLINE_MS),
       forkDeadlineMs: parseForkDeadlineMs(process.env.PRLL_FORK_DEADLINE_MS),
       dispatchDeadlineMs: parseDispatchDeadlineMs(process.env.PRLL_DISPATCH_DEADLINE_MS),

package/src/workspace.ts

@@ -609,29 +609,56 @@ function findSectionEnd(content: string, fromIndex: number): number {
   return nextHeader === -1 ? content.length : nextHeader;
 }
 
-export function ensureCodexWorkspace(
+// writeCodexSystemPrompt (re)writes the standing platform prompt surfaces:
+// .parall/system-prompt.md (human-inspectable copy) and the workspace
+// .codex/config.toml developer_instructions (what the CLI actually loads).
+// capabilityFragments are platform-derived capability declarations
+// (agents.capabilities[].fragment) — placed after the platform reference
+// guide, before skill references; empty/absent = no capability section.
+// Split out from ensureCodexWorkspace so the bridge can rewrite on
+// platform-config heat-update; the app-server reads workspace config at
+// process start, so the caller pairs a CHANGED fragment set with
+// adapter.requestProcessRestart(). Throws on failure BY DESIGN — at boot the
+// prompt is mandatory, so a write failure must fail startup loudly; the
+// refresh hot path wraps this in try/catch and retries next refresh.
+export function writeCodexSystemPrompt(
   workspaceDir: string,
-  log?: { warn: (msg: string) => void },
   agentIdentity?: AgentIdentity,
+  capabilityFragments?: string[],
 ): void {
-  const systemPrompt = [
+  const parts = [
     buildIdentity(agentIdentity),
     BRIDGE_WORKSPACE_INSTRUCTIONS,
     PRLL_BEHAVIOR,
     PRLL_REFERENCE_GUIDE,
-    buildSkillReferences(workspaceDir),
-  ].join('\n\n');
-
-  fs.mkdirSync(workspaceDir, { recursive: true });
+  ];
+  if (capabilityFragments && capabilityFragments.length > 0) {
+    parts.push(capabilityFragments.join('\n\n'));
+  }
+  parts.push(buildSkillReferences(workspaceDir));
+  const systemPrompt = parts.join('\n\n');
 
   const parallDir = path.join(workspaceDir, '.parall');
   fs.mkdirSync(parallDir, { recursive: true });
   fs.writeFileSync(path.join(parallDir, 'system-prompt.md'), systemPrompt, 'utf8');
 
-  writeSkillFiles(path.join(parallDir, 'skills'));
-
   const codexConfigDir = path.join(workspaceDir, '.codex');
   fs.mkdirSync(codexConfigDir, { recursive: true });
   const toml = `developer_instructions = """\n${systemPrompt.replace(/\\/g, '\\\\').replace(/"""/g, '\\"""')}\n"""\n`;
   fs.writeFileSync(path.join(codexConfigDir, 'config.toml'), toml, 'utf8');
 }
+
+export function ensureCodexWorkspace(
+  workspaceDir: string,
+  log?: { warn: (msg: string) => void },
+  agentIdentity?: AgentIdentity,
+  capabilityFragments?: string[],
+): void {
+  fs.mkdirSync(workspaceDir, { recursive: true });
+
+  // Boot: let a write failure PROPAGATE (fatal) — startup must not proceed
+  // without the platform prompt. The refresh path tolerates failure.
+  writeCodexSystemPrompt(workspaceDir, agentIdentity, capabilityFragments);
+
+  writeSkillFiles(path.join(workspaceDir, '.parall', 'skills'));
+}