@parall/codex-agent 1.18.0

package/dist/config.d.ts

@@ -0,0 +1,33 @@
+export type CodexAgentConfig = {
+    apiUrl: string;
+    apiKey: string;
+    orgId: string;
+    wsUrl?: string;
+    swimlaneName?: string;
+    codexBin: string;
+    codexHome: string;
+    stateDir: string;
+    workspaceDir: string;
+    model?: string;
+    reasoningEffort?: string;
+    sandbox: string;
+    approvalPolicy: string;
+    runtimeKey?: string;
+};
+export declare function resolveCodexAgentConfig(env?: NodeJS.ProcessEnv): CodexAgentConfig;
+/**
+ * Normalise a sandbox value (CLI docs use kebab-case like `workspace-write`,
+ * but the app-server JSON-RPC protocol uses camelCase like `workspaceWrite`).
+ * Accept both forms and emit the canonical protocol form.
+ */
+export declare function normalizeSandbox(value: string): string;
+/**
+ * Normalise an approval policy string to the camelCase form the app-server
+ * JSON-RPC protocol uses (`never` / `onRequest` / `unlessTrusted`).
+ */
+export declare function normalizeApprovalPolicy(value: string): string;
+export declare function resolveWsUrl(apiUrl: string, explicitWsUrl?: string, swimlaneName?: string): string;
+export declare function buildCodexRuntimeKey(agentUserId: string): string;
+export declare function sessionStateFilePathForRuntime(stateDir: string, runtimeKey: string): string;
+export declare function stepIdFilePathForSession(stateDir: string, sessionKey: string): string;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAcF,wBAAgB,uBAAuB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,gBAAgB,CA6B9F;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAUtD;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAW7D;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAMlG;AAED,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAG3F;AAED,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAGrF"}

package/dist/config.js

@@ -0,0 +1,90 @@
+import * as os from "node:os";
+import * as path from "node:path";
+function requireEnv(env, name) {
+    const value = env[name]?.trim();
+    if (!value) {
+        throw new Error(`Missing required env var: ${name}`);
+    }
+    return value;
+}
+function resolvePath(value) {
+    return path.isAbsolute(value) ? value : path.resolve(process.cwd(), value);
+}
+export function resolveCodexAgentConfig(env = process.env) {
+    const apiUrl = requireEnv(env, "PRLL_API_URL");
+    const apiKey = requireEnv(env, "PRLL_API_KEY");
+    const orgId = requireEnv(env, "PRLL_ORG_ID");
+    const codexHome = resolvePath(env.PRLL_CODEX_HOME?.trim()
+        || env.CODEX_HOME?.trim()
+        || env.HOME
+        || os.homedir());
+    const stateDir = resolvePath(env.PRLL_CODEX_STATE_DIR?.trim() || path.join(codexHome, ".parall-agent"));
+    const workspaceDir = resolvePath(env.PRLL_CODEX_WORKSPACE_DIR?.trim() || path.join(stateDir, "workspace"));
+    return {
+        apiUrl,
+        apiKey,
+        orgId,
+        wsUrl: env.PRLL_WS_URL?.trim() || undefined,
+        swimlaneName: env.PRLL_SWIMLANE_NAME?.trim() || undefined,
+        codexBin: env.PRLL_CODEX_BIN?.trim() || "codex",
+        codexHome,
+        stateDir,
+        workspaceDir,
+        model: env.PRLL_CODEX_MODEL?.trim() || undefined,
+        reasoningEffort: env.PRLL_CODEX_REASONING_EFFORT?.trim() || undefined,
+        sandbox: env.PRLL_CODEX_SANDBOX?.trim() || "workspace-write",
+        approvalPolicy: env.PRLL_CODEX_APPROVAL?.trim() || "never",
+        runtimeKey: env.PRLL_CODEX_RUNTIME_KEY?.trim() || undefined,
+    };
+}
+/**
+ * Normalise a sandbox value (CLI docs use kebab-case like `workspace-write`,
+ * but the app-server JSON-RPC protocol uses camelCase like `workspaceWrite`).
+ * Accept both forms and emit the canonical protocol form.
+ */
+export function normalizeSandbox(value) {
+    const map = {
+        "workspace-write": "workspaceWrite",
+        "workspacewrite": "workspaceWrite",
+        "danger-full-access": "dangerFullAccess",
+        "dangerfullaccess": "dangerFullAccess",
+        "read-only": "readOnly",
+        "readonly": "readOnly",
+    };
+    return map[value.toLowerCase()] ?? value;
+}
+/**
+ * Normalise an approval policy string to the camelCase form the app-server
+ * JSON-RPC protocol uses (`never` / `onRequest` / `unlessTrusted`).
+ */
+export function normalizeApprovalPolicy(value) {
+    const map = {
+        "never": "never",
+        "on-request": "onRequest",
+        "onrequest": "onRequest",
+        "unless-trusted": "unlessTrusted",
+        "unlesstrusted": "unlessTrusted",
+        "on-failure": "onFailure",
+        "onfailure": "onFailure",
+    };
+    return map[value.toLowerCase()] ?? value;
+}
+export function resolveWsUrl(apiUrl, explicitWsUrl, swimlaneName) {
+    const base = explicitWsUrl || `${apiUrl.replace(/\/$/, "").replace(/^http/, "ws")}/ws`;
+    if (!swimlaneName)
+        return base;
+    const url = new URL(base);
+    url.searchParams.set("swimlane", swimlaneName);
+    return url.toString();
+}
+export function buildCodexRuntimeKey(agentUserId) {
+    return `agent:main:codex:${agentUserId}:orchestrator`;
+}
+export function sessionStateFilePathForRuntime(stateDir, runtimeKey) {
+    const fileName = Buffer.from(runtimeKey).toString("base64url");
+    return path.join(stateDir, "threads", `${fileName}.json`);
+}
+export function stepIdFilePathForSession(stateDir, sessionKey) {
+    const fileName = Buffer.from(sessionKey).toString("base64url");
+    return path.join(stateDir, "step-ids", `${fileName}.txt`);
+}

package/dist/dispatch.d.ts

@@ -0,0 +1,53 @@
+import type { CleanupForkOpts, DispatchAdapter, DispatchOpts, ForkOpts, ForkSessionHandle, GatewayLogger, RuntimeEvent } from "@parall/agent-core";
+import type { CodexAgentConfig } from "./config.js";
+import type { CodexSessionManager } from "./session-manager.js";
+type CodexAppServerAdapterOptions = Pick<CodexAgentConfig, "approvalPolicy" | "codexBin" | "codexHome" | "model" | "reasoningEffort" | "sandbox" | "workspaceDir"> & {
+    sessionManager: CodexSessionManager;
+    log?: GatewayLogger;
+};
+/**
+ * Bridge driver backed by `codex app-server --listen stdio://`.
+ *
+ * Lifecycle:
+ *   - bridge startup: spawn one `codex app-server` subprocess, do the
+ *     `initialize` / `initialized` handshake once, keep the pipe open
+ *   - per Parall dispatch: `thread/start` (first time) or `thread/resume`,
+ *     then `turn/start`; forward server notifications until `turn/completed`
+ *   - fork-on-busy: `thread/fork` creates a disposable sibling thread
+ *
+ * Concurrency: agent-core routes one dispatch per sessionKey at a time, so
+ * main + fork can interleave turns on the same stdio pipe. We route
+ * notifications by threadId the server stamps on every item/turn event.
+ */
+export declare class CodexAppServerAdapter implements DispatchAdapter {
+    private readonly opts;
+    private client;
+    private proc;
+    private initialized;
+    private startPromise;
+    private readonly activeTurns;
+    private readonly resumedThreadIds;
+    private stopping;
+    /**
+     * Store an active turn sink keyed by threadId. If a sink already exists for
+     * the same threadId, log a warning and fail the existing sink — this
+     * shouldn't happen in practice (agent-core serialises per sessionKey, and
+     * thread/fork returns a distinct id) but the failure mode of a silent
+     * replacement would be a perpetually hung dispatch generator, which is
+     * hard to debug.
+     */
+    private setActiveTurn;
+    constructor(opts: CodexAppServerAdapterOptions);
+    dispatch({ bodyForAgent, sessionKey, context }: DispatchOpts): AsyncIterable<RuntimeEvent>;
+    forkSession({ sessionKey: parentSessionKey }: ForkOpts): Promise<ForkSessionHandle | null>;
+    cleanupFork({ fork }: CleanupForkOpts): void;
+    private logForkFailure;
+    stop(): Promise<void>;
+    private ensureStarted;
+    private doStart;
+    private handleSubprocessClose;
+    private openThread;
+    private routeNotification;
+}
+export {};
+//# sourceMappingURL=dispatch.d.ts.map

package/dist/dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"AAKA,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;CACrB,CAAC;AAOF;;;;;;;;;;;;;GAaG;AACH,qBAAa,qBAAsB,YAAW,eAAe;IA6B/C,OAAO,CAAC,QAAQ,CAAC,IAAI;IA5BjC,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,gBAAgB,CAAqB;IACtD,OAAO,CAAC,QAAQ,CAAS;IAEzB;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;gBAYQ,IAAI,EAAE,4BAA4B;IAExD,QAAQ,CAAC,EAAE,YAAY,EAAE,UAAU,EAAE,OAAO,EAAE,EAAE,YAAY,GAAG,aAAa,CAAC,YAAY,CAAC;IA0J3F,WAAW,CAAC,EAAE,UAAU,EAAE,gBAAgB,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAuBhG,WAAW,CAAC,EAAE,IAAI,EAAE,EAAE,eAAe;IAIrC,OAAO,CAAC,cAAc;IAKhB,IAAI;YAaI,aAAa;YAcb,OAAO;IA2DrB,OAAO,CAAC,qBAAqB;YAiCf,UAAU;IAuCxB,OAAO,CAAC,iBAAiB;CA2B1B"}