Files
PaperClipAI/packages/paperclip-runner/src/drivers/codex/codex-app-server-driver-impl.ts
T
DottaandPaperclip 992f720262 fix: make runner task context ownership explicit (#13753)
<!-- Write all pull request text in Simplified Technical English
(ASD-STE100). -->

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Task descriptions, comments, continuation data, skills, and
execution rules enter several agent adapters.
> - The same source can be rendered by more than one automatic input
carrier.
> - Failed resumes can also rebuild input from stale or compact context.
> - This pull request gives each Paperclip-owned source one delivery
owner and preserves the required transport boundaries.
> - It adds deterministic adapter, interaction, runner, and browser
tests for these boundaries.
> - The benefit is more predictable context delivery with explicit
evidence for later live qualification.

## Linked Issues or Issue Description

Related: #13144 removes a duplicate environment payload and bounds wake
lists. Related: #11360 addresses Hermes resume behavior. This pull
request preserves compatible active-session formats while repairing
context ownership and stale question creation.

**What happened?**

Task descriptions and comments could enter more than one automatic
context block. Native transports could wrap a complete model input in a
second task envelope. Some legacy and gateway adapters could omit the
owned assignment on ordinary tasks or rebuild a failed resume with stale
compact context. A continuation could also request a question after
newer human comments had arrived.

**Expected behavior**

Each task or comment source has one automatic model-facing owner.
Distinct comment IDs and repeated wording remain distinct. Fresh
fallback attempts rebuild the required full context. A question request
is rejected when newer queued human direction makes it stale. Harness
access policy remains owned by execution configuration.

**Steps to reproduce**

1. Build a task with a description and current comments.
2. Capture the actual adapter or runner input.
3. Compare source ownership and task-envelope nesting.
4. Queue a human comment before a continuation requests a question.
5. Trigger a failed resume and inspect the fresh retry input.
6. Run the focused adapter, interaction, runner, and browser checks.

## What Changed

- Add shared prompt-section selection at the provider-attempt boundary.
- Deliver owned assignment context through native, legacy CLI, ACP,
gateway, cloud, Pi, Kimi, Grok, Gemini, OpenCode, Cursor, OpenClaw, and
Hermes paths.
- Rebuild full or compact context after resume recovery changes the
attempt. Add native and Claude ACP tests of actual recovery requests.
- Preserve custom templates, loaded instruction files, execution
policies, and older active-session formats.
- Record continuation source metadata and reject stale question creation
under the issue-row lock.
- Add explicit Product E2E context-integrity profiles, prerequisite
gates, credential-isolation checks, and report fixtures.
- Bypass service-worker forwarding for same-origin Vite development
modules. A real Chromium test fails with resource exhaustion before the
repair and passes after it. Production asset caching keeps its existing
policy.
- Add browser diagnostics and service-worker module-loading regressions.
- Add an explicit zero-retry eval option. The default retry behavior
remains unchanged. Each campaign records its effective policy.
- Remove the model-facing working-directory sentence from four prompt
builders. Existing workspace, sandbox, permission, and custom-template
configuration remains unchanged.
- Align the everyday workflow assertion with the current 47-entry
catalog.

Compared with current upstream master, the branch carries the
context-ownership implementation and its tests, the explicit
context-integrity catalog and evidence harness, and the focused browser
regression checks.

## Verification

**Merge assessment:** focused regression evidence supports merge. This
is not full completion of the original broad qualification matrix. The
maintainer has authorized merge after fresh verification of the master
integration.

- Current head: `bbd52f82114eabf09bc7b1a7e97d54a5b43bbc00`. This
integrates current master `2f585ef26a1814fa209715242d1ca791b63e4c4e`.
All 14 conflicts are resolved. Cancellation checks, workspace
finalization, native Grok support, and both sets of tests are retained.
- Current-head Greptile: **5/5**, with no blocking findings. The review
names this exact commit. All **59 reported checks are terminal: 55
successful, 4 skipped, zero pending or failing**. This includes the full
root general and serialized suites, separate runner checks, typecheck,
build, canary, browser E2E, Docker, and security checks. The successful
legacy security status is included in that total.
- After integration: workspace typecheck and full build passed. Separate
runner checks passed: **2,160 TypeScript tests (10 skipped), 582 Rust
tests, and 39 preparation checks**. Other passing checks include 621
Product E2E harness units, 376 focused shared/adapter tests, 160
real-database/API tests, 86 Hermes tests, 18 browser-support checks, and
Product E2E typechecking. The complete root suite passed in CI. The
duplicate local monolithic root run was stopped after that CI result; it
is not counted as a completed local pass.
- New native recovery coverage retains full assignment, completion
contract, and explicit skill selection after safe replacement, for old
and prepared input formats. Full native session test file: **136/136
passed**.
- New Claude ACP coverage captures actual fresh, resumed, and
missing-session fallback requests. It verifies one assignment copy,
comment order, identical text under distinct comment IDs, and full
fallback context. Full file: **33/33 passed**. Both affected TypeScript
checks passed.
- Existing deterministic tests cover source revisions, approval and
trust boundaries, completion validation, custom templates, compatible
sessions, standalone driver wrapping, and maintained adapter transport
requests.
- Provider-free browser support: **17/17 passed** after the master
merge. Service-worker unit tests: **33/33 passed**. The module-overload
regression failed before the repair and passed after it in real
Chromium.

### Fresh live comparisons

The new batch ran exactly four Product E2E attempts. **All four passed
on the first attempt; no retries.** Each has six terminal matchers plus
the existing browser lifecycle and invariant checks.

| Exact case ID | Control | Candidate |
|---|---|---|
| `core-compatibility.runner-codex.local.plan-revise-accept` | Passed |
Passed |
|
`local-session-integrity.runner-acpx-claude.local.structured-question-restart-resume`
| Passed | Passed |

The plan case checks a revised canonical plan and revision-bound
approval before completion. The question case restarts the server before
submitting the answer, then verifies the continuation completes.

Control source is `dfa4e1bda8d50a1a01746603251a9128dbe9d0d6`. Candidate
source is `79fcdb5dece501d28064ea9da306603881b46f0c`. They use identical
frozen definitions and provider versions: Codex `0.156.0` with
`gpt-5.6-sol`; ACPX `0.13.1` / Claude ACP `0.73.0` with
`claude-sonnet-5`. The September 24 head added master browser recovery
and test-only changes. The September 28 head also integrates newer
master changes, including cancellation, workspace finalization, and
native Grok. These are frozen-source live results, not exact-head live
runs.

The candidate received one description copy where the control initially
received three. The submitted initial plan envelopes were 7,969 versus
19,097 characters. Question envelopes were 7,592 versus 18,919. These
are structural measurements, not whole-provider token or dollar savings.

### Earlier evidence and failed attempts

- The preceding fresh batch has four effective passing pairs: OpenCode
comment continuation and assigned skill, native Codex comment
continuation, and native Claude comment continuation. It retains **11
attempts: eight passed and three failed**.
- Original failures remain recorded: missing local PostgreSQL library
links before task creation; host-sleep cleanup after task/page checks
passed; and a Claude **control** session-open rejection before a model
turn. Setup was repaired identically on both worktrees. The permitted
unchanged infrastructure retries passed. The underlying Claude provider
startup error was not retained and remains unknown.
- Older R2 retains **17 passes and one failure** across 18 attempts,
including eight both-pass native/legacy Codex/Claude pairs. Its OpenCode
blank-page failure led to the service-worker repair. R2 is historical
evidence: master changed the native fixed prompt and removed duplicate
wake environment data afterward.
- The September 24 CI run initially failed one unrelated preview
readiness test (`ECONNREFUSED` on its local fixture). Its test and
production code match master. Isolated local verification passed **28
tests, 3 skipped**. One unchanged CI retry passed the full shard: **831
passed, 1 skipped**, including all **31 preview-exposure tests**. The
aggregate CI gate passed afterward. The precise startup cause remains
unknown; a port race is a hypothesis, not a proved cause.

### Limits

The original wider profile/workflow matrix, repeated trials, and remote
Daytona qualification are incomplete. These results support a focused
merge recommendation, not statistical equivalence or universal harness
qualification. Some usage receipts are missing in both variants, so no
token or dollar savings are claimed. The $500 ceiling was preserved
using conservative allowances; failed attempts and unknown charges
remain in the ledger.

Reproduce the focused additions with `pnpm exec vitest run
packages/adapters/claude-local/src/server/acp.test.ts` and `pnpm
--filter @paperclipai/paperclip-runner exec vitest run
src/native-session-runtime.test.ts`. Full checks use `pnpm -r
typecheck`, `pnpm test:run`, `pnpm build`, and the separate runner
checks. Paid evals require the frozen definitions, profiles, and
credentials; do not use `--all` as a substitute for the selected cases.

## Risks

- Context placement changes can affect model behavior. Deterministic
checks cover the selected paths, but live qualification remains
incomplete.
- The stale-question guard can reject a request when queued human
comments arrived during the run. This is intended.
- New stored inputs and model envelopes retain compatibility readers for
older active sessions.
- Custom templates may intentionally repeat content.
- Removing a model-facing working-directory sentence does not change
filesystem, command, sandbox, or permission configuration.
- The worker bypass applies only to same-origin development module
paths. Cache-policy tests preserve private-response handling and
production asset caching. Mounted HTTP fixture changes remain test-only.
- This PR does not claim measured token savings or statistical
equivalence across every harness.

## Model Used

OpenAI Codex, exact model gpt-6-astra, with repository tools and code
execution. Bounded supporting work used gpt-5.6-luna and gpt-6-luna. The
serving context-window size is not exposed in this task.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have described the issue in-PR using the required issue fields
- [x] I have not referenced internal/instance-local Paperclip issues or
links
- [x] My branch name describes the change and contains no internal
ticket id
- [x] I have run the focused local checks and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect these changes
- [x] I have considered and documented risks above
- [x] All current-head Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
for the current head
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-09-28 14:49:14 -05:00

938 lines
36 KiB
TypeScript

import { trustCodexStartupRoot } from "./codex-startup-trust.js";
import { readCodexThreadState, readCodexTurnMetadata } from "./codex-history.js";
import { codexExecutableReadOnlyRoots } from "./codex-security-config.js";
import { resolve } from "node:path";
import type {
HarnessDriver,
HarnessDriverDescriptor,
HarnessRuntimeRequest,
HarnessSession,
HarnessSessionRecoveryOptions,
HarnessSessionRecoveryResult,
HarnessThreadGoal,
HarnessThreadLineageEntry,
OpenHarnessSessionInput,
PersistedHarnessSemanticResult,
PersistedHarnessSession,
PersistedHarnessTurnTerminal,
} from "../../contracts/harness-driver.js";
import { NativeSessionProtocolIntegrityError } from "../../contracts/native-session-backend.js";
import { HarnessReconciliationError } from "../../contracts/harness-driver.js";
import {
CODEX_CODEX_PROTOCOL_VERSION,
CODEX_SKILLLESS_BASE_INSTRUCTIONS,
} from "../../contracts/codex.js";
import { providerFamilyCapabilities } from "../../provider-events.js";
import {
CodexRpcError,
ProcessCodexAppServerTransport,
createSanitizedCodexEnvironment,
isCodexMethodUnavailable,
redactCodexDiagnostic,
type CodexAppServerTransport,
type CodexTransportProcessInfo,
} from "./app-server-transport.js";
import {
boundedCodexValue,
validateCodexWorkingDirectory as validateWorkingDirectory,
} from "./codex-boundaries.js";
import {
codexCommandEnvironment,
createIsolatedCodexAppServerArgs,
codexNetworkAccess,
createSecuredCodexThreadParams,
createSkilllessCodexThreadConfig,
} from "./codex-security-config.js";
import {
codexThreadLineage as lineageFromThread,
codexThreadStatus as threadStatus,
parseCodexThreadGoal as parseThreadGoal,
} from "./codex-thread-normalization.js";
import { CodexHarnessSession } from "./codex-harness-session.js";
import type {
CodexAppServerDriverOptions,
CodexCapabilities,
CodexGoalAvailability,
OpenedCodexThread,
} from "./codex-driver-types.js";
import {
boundedText,
canonicalJson,
codexSemanticToolSpecs,
differingJsonPaths,
parseProviderIdentity,
record,
text,
} from "./codex-driver-values.js";
const DRIVER_KIND = "codex_app_server";
const DRIVER_VERSION = "codex-v2";
interface BootstrapCancellation {
close(): Promise<void>;
detach(): void;
wait<T>(operation: Promise<T>): Promise<T>;
}
function bootstrapCancellation(
transport: CodexAppServerTransport,
signal: AbortSignal | undefined,
): BootstrapCancellation {
let closePromise: Promise<void> | null = null;
const close = (): Promise<void> => {
closePromise ??= transport.close();
return closePromise;
};
let rejectAborted!: (reason: unknown) => void;
const aborted = new Promise<never>((_resolve, reject) => {
rejectAborted = reject;
});
let abortStarted = false;
const onAbort = (): void => {
if (abortStarted) return;
abortStarted = true;
// Provider bootstrap owns a local process. Do not report cancellation
// until its pending RPCs have been rejected and TERM/KILL cleanup has
// completed. The cancellation reason remains authoritative if cleanup
// itself reports a secondary failure.
void close().then(
() =>
rejectAborted(signal?.reason ?? new Error("Codex bootstrap aborted")),
() =>
rejectAborted(signal?.reason ?? new Error("Codex bootstrap aborted")),
);
};
signal?.addEventListener("abort", onAbort, { once: true });
// Close the construction/listener race after the caller's preflight abort
// check without creating a provider for an already-aborted operation.
if (signal?.aborted) onAbort();
return {
close,
detach(): void {
signal?.removeEventListener("abort", onAbort);
},
async wait<T>(operation: Promise<T>): Promise<T> {
if (signal === undefined) return await operation;
const result = await Promise.race([operation, aborted]);
// An operation and abort cleanup may settle in the same microtask turn.
// Cancellation wins until session admission, and still awaits cleanup.
if (signal.aborted) return await aborted;
return result;
},
};
}
export class CodexAppServerDriver implements HarnessDriver {
readonly #options: CodexAppServerDriverOptions;
readonly #caps: CodexCapabilities;
#goalAvailability: CodexGoalAvailability;
#goalReasonCode: string | null = null;
#goalReason: string | null = null;
readonly #goalCapability: NonNullable<
CodexAppServerDriverOptions["goalCapability"]
>;
readonly #persistedProcessIdentities = new WeakMap<object, string>();
constructor(options: CodexAppServerDriverOptions) {
this.#options = options;
this.#caps = {
resume: true,
read: true,
steering: true,
interruption: true,
usage: true,
reconciliation: true,
dynamicTools: true,
runtimeRequestResolution: true,
goals: true,
threadLineage: true,
...options.capabilities,
};
this.#goalAvailability = this.#caps.goals ? "available" : "unsupported";
this.#goalCapability = options.goalCapability ?? {
actions: ["set", "pause", "resume", "clear"],
autonomousUpdates: true,
persistentAcrossResume: true,
maxObjectiveChars: 4_000,
tokenBudgetControl: true,
usageReporting: true,
};
if (!this.#caps.goals) {
this.#goalReasonCode = "codex_goal_api_unavailable";
this.#goalReason = "This Codex app-server does not expose thread goals.";
}
if (!this.#caps.read) this.#caps.reconciliation = false;
}
#direct(): boolean {
return this.#options.conversationMode === "direct";
}
#prepared(): boolean {
return this.#options.conversationMode === "prepared";
}
#providerDynamicTools(): readonly Readonly<Record<string, unknown>>[] {
if (!this.#caps.dynamicTools) return [];
const supplied = this.#options.dynamicTools ?? [];
if (this.#direct()) {
// Direct chat deliberately excludes the general semantic/governance
// catalog. Keep only the server-authorized question, file handoff, and
// current-wake tools so the harness can ask a structured provider
// question or return requested files without reopening general task
// authority.
return supplied.filter(
(tool) =>
text(tool.name) === "register_deliverable" ||
text(tool.name) === "request_human_input" ||
text(tool.name) === "read_current_wake_comments" ||
text(tool.name) === "list_chat_attachments" ||
text(tool.name) === "reuse_chat_attachment" ||
text(tool.name) === "read_chat_attachment",
);
}
return [...supplied, ...codexSemanticToolSpecs()];
}
#baseInstructions(): string {
return this.#options.baseInstructions ?? CODEX_SKILLLESS_BASE_INSTRUCTIONS;
}
async descriptor(): Promise<HarnessDriverDescriptor> {
const unsupported = Object.entries(this.#caps)
.filter(([, supported]) => !supported)
.map(([operation]) => operation);
return {
kind: this.#options.driverIdentity?.kind ?? DRIVER_KIND,
displayName:
this.#options.driverIdentity?.displayName ?? "Codex app-server",
version: this.#options.driverIdentity?.version ?? DRIVER_VERSION,
protocolVersion: CODEX_CODEX_PROTOCOL_VERSION,
runtimeContextCapabilities: {
instructions: "native",
skills: "native",
mcp: "native",
},
capabilities: {
resume: this.#caps.resume,
typedEvents: true,
typedEventFamilies: providerFamilyCapabilities({
plan: "available",
tool_execution: "available",
research: "available",
delegation: "available",
model_identity: "available",
context: "available",
artifact: "policy_disabled",
review: "available",
hook: "available",
memory: "available",
safety: "available",
terminal: "available",
wait: "available",
provider_notice: "available",
}),
steering: this.#caps.steering,
interruption: this.#caps.interruption,
structuredResult: true,
read: this.#caps.read,
reconciliation: this.#caps.reconciliation,
usage: this.#caps.usage,
dynamicTools: this.#caps.dynamicTools,
runtimeRequestResolution: this.#caps.runtimeRequestResolution,
runtimeRequestHandoff: this.#caps.runtimeRequestResolution,
goals: this.#caps.goals,
threadLineage: this.#caps.threadLineage,
collaborationModes: [
...(this.#options.collaborationModes ?? ["default", "plan"]),
],
unsupported,
},
};
}
async openSession(input: OpenHarnessSessionInput): Promise<HarnessSession> {
input.signal?.throwIfAborted();
const workingDirectory = validateWorkingDirectory(
input.workingDirectory,
this.#options.environment,
this.#options.workingDirectoryAuthority,
);
const transport = this.#transport({ workingDirectory });
const cancellation = bootstrapCancellation(transport, input.signal);
try {
await cancellation.wait(this.#persistProcessOwnership(transport));
const initialize = await cancellation.wait(this.#initialize(transport));
const requestedMode =
this.#options.requestedCollaborationMode ?? "default";
const response = await cancellation.wait(
transport.request("thread/start", {
...createSecuredCodexThreadParams(
workingDirectory,
requestedMode,
this.#options.includeCollaborationModeInstructions ?? true,
this.#options.includeSkillInstructions ?? false,
this.#options.environment,
),
approvalPolicy: this.#options.approvalPolicy ?? "never",
...(this.#options.model ? { model: this.#options.model } : {}),
...(this.#direct()
? {}
: {
baseInstructions: this.#baseInstructions(),
completionContract: {
revision:
this.#options.taskEnvelope.completionContract.revision,
criterionIds:
this.#options.taskEnvelope.completionContract.criteria.map(
(criterion) => criterion.id,
),
},
}),
dynamicTools: this.#providerDynamicTools(),
...(this.#prepared() ? { conversationMode: "prepared" } : {}),
experimentalRawEvents: false,
persistExtendedHistory: false,
}),
);
await cancellation.wait(this.#persistProcessOwnership(transport));
const collaborationMode = await cancellation.wait(
this.#negotiateCollaborationMode(transport, response, requestedMode),
);
const opened = this.#openedThread(
response,
initialize,
workingDirectory,
collaborationMode,
);
const goal = await cancellation.wait(
this.#discoverGoal(transport, opened.threadId),
);
if (opened.context.liveConsole)
opened.context.liveConsole.goals = this.#caps.goals;
return this.#session({
transport,
runId: input.runId,
normalizedSessionId: input.normalizedSessionId,
opened,
goal,
goalAvailability: this.#goalAvailability,
goalReasonCode: this.#goalReasonCode,
goalReason: this.#goalReason,
resumed: false,
sourceSequence: 0,
});
} catch (error) {
// Cleanup must never replace the provider/bootstrap failure that caused
// the session open to abort. Remote transports may perform checkpoint
// work during close; when no durable provider identity exists that
// cleanup can fail independently.
await cancellation.close().catch(() => {});
if (error instanceof NativeSessionProtocolIntegrityError) throw error;
if (input.signal?.aborted) input.signal.throwIfAborted();
throw error;
} finally {
cancellation.detach();
}
}
async recoverSession(
snapshot: PersistedHarnessSession,
options: HarnessSessionRecoveryOptions = {
signal: new AbortController().signal,
},
): Promise<HarnessSessionRecoveryResult> {
options.signal.throwIfAborted();
if (!this.#caps.resume) {
return { recovered: false, reason: "resume capability is unavailable" };
}
if (!this.#caps.read) {
return {
recovered: false,
reason: "read capability is required for safe resume",
};
}
if (
!snapshot.runId ||
!snapshot.normalizedSessionId ||
!snapshot.driverSessionId
) {
return {
recovered: false,
reason: "persisted session identity is incomplete",
};
}
const transport = this.#transport({
workingDirectory: snapshot.workingDirectory
? validateWorkingDirectory(snapshot.workingDirectory, this.#options.environment, this.#options.workingDirectoryAuthority)
: undefined,
providerRecoveryPolicy: snapshot.providerRecoveryPolicy,
persistedSession: {
driverSessionId: snapshot.driverSessionId,
providerSessionId: snapshot.providerSessionId,
providerIdentity: snapshot.providerIdentity,
activeTurnId: snapshot.activeTurnId,
},
});
const cancellation = bootstrapCancellation(transport, options.signal);
try {
await cancellation.wait(this.#persistProcessOwnership(transport));
const initialize = await cancellation.wait(this.#initialize(transport));
const existing = await cancellation.wait(
readCodexThreadState(transport, snapshot.driverSessionId),
);
await cancellation.wait(this.#persistProcessOwnership(transport));
const existingThread = record(existing.thread);
existingThread.turns = await cancellation.wait(readCodexTurnMetadata(transport, snapshot.driverSessionId));
if (text(existingThread.id) !== snapshot.driverSessionId) {
await cancellation.wait(cancellation.close());
return {
recovered: false,
reason: "provider read a different session",
};
}
const workingDirectory = validateWorkingDirectory(
text(existingThread.cwd),
this.#options.environment,
this.#options.workingDirectoryAuthority,
);
const response = await cancellation.wait(
transport.request("thread/resume", {
excludeTurns: true,
threadId: snapshot.driverSessionId,
...createSecuredCodexThreadParams(
workingDirectory,
this.#options.requestedCollaborationMode ?? "default",
this.#options.includeCollaborationModeInstructions ?? true,
this.#options.includeSkillInstructions ?? false,
this.#options.environment,
),
baseInstructions: this.#direct() ? "" : this.#baseInstructions(),
approvalPolicy: this.#options.approvalPolicy ?? "never",
...(this.#options.model ? { model: this.#options.model } : {}),
dynamicTools: this.#providerDynamicTools(),
...(this.#prepared() ? { conversationMode: "prepared" } : {}),
persistExtendedHistory: false,
}),
);
await cancellation.wait(this.#persistProcessOwnership(transport));
const collaborationMode = await cancellation.wait(
this.#negotiateCollaborationMode(
transport,
response,
this.#options.requestedCollaborationMode ?? "default",
),
);
const opened = this.#openedThread(
response,
initialize,
workingDirectory,
collaborationMode,
);
if (opened.threadId !== snapshot.driverSessionId) {
await cancellation.wait(cancellation.close());
return {
recovered: false,
reason: "provider resumed a different session",
};
}
if (
snapshot.providerSessionId &&
opened.providerSessionId !== snapshot.providerSessionId
) {
await cancellation.wait(cancellation.close());
return {
recovered: false,
reason: "provider resumed a different provider session",
};
}
if (
snapshot.providerIdentity !== undefined &&
canonicalJson(opened.providerIdentity) !==
canonicalJson(snapshot.providerIdentity)
) {
await cancellation.wait(cancellation.close());
return {
recovered: false,
reason: "provider resumed with a different tagged session identity",
};
}
const checkpointedActiveTurnId = snapshot.activeTurnId ?? null;
// A terminal fingerprint is the durable provider fact. A crash can
// persist it before the following active-turn clear reaches the same
// checkpoint, so never resurrect that already-terminal turn as active.
const checkpointedActiveTurnIsTerminal =
checkpointedActiveTurnId !== null &&
(snapshot.terminalTurns ?? []).some(
(terminal) => terminal.turnId === checkpointedActiveTurnId,
);
let recoveredActiveTurnId = checkpointedActiveTurnIsTerminal
? null
: checkpointedActiveTurnId;
let dispositionOnlyRecoveryConsumed =
snapshot.dispositionOnlyRecoveryConsumed ?? false;
let dispositionOnlyRecoveryTurnId =
snapshot.dispositionOnlyRecoveryTurnId ?? null;
let reconcileUncheckpointedDispositionTurn = false;
let providerTurnIds: Set<string> | null = null;
const goal = await cancellation.wait(
this.#discoverGoal(transport, opened.threadId),
);
const recoveringAutonomousGoal = snapshot.goal?.status === "active"
&& goal != null
&& goal.createdAt === snapshot.goal.createdAt;
if (recoveringAutonomousGoal) {
// Goal activation and continuation have no turn/start response. The
// provider can advance beyond the last controller checkpoint while
// disconnected, so bind the single live turn from the authenticated,
// identity-checked thread read before draining its notifications.
// Never infer a turn from an arbitrary notification or another goal.
const turns = Array.isArray(existingThread.turns)
? existingThread.turns.map(record)
: null;
const active = turns?.filter((turn) => text(turn.status) === "inProgress");
if (!active || active.length > 1 || (active.length === 1 && (
!text(active[0]?.id)
|| (snapshot.terminalTurns ?? []).some((turn) => turn.turnId === text(active[0]?.id))
))) {
await cancellation.wait(cancellation.close());
return { recovered: false, reason: "provider exposed ambiguous autonomous goal turn history" };
}
recoveredActiveTurnId = active.length === 1 ? text(active[0]?.id) : recoveredActiveTurnId;
}
if (
!recoveringAutonomousGoal &&
!this.#direct() &&
snapshot.semanticResult == null &&
recoveredActiveTurnId === null &&
(snapshot.terminalTurns?.length ?? 0) > 0
) {
const providerHistory = existingThread.turns;
const providerHistoryIsArray = Array.isArray(providerHistory);
const turns = providerHistoryIsArray ? providerHistory.map(record) : [];
const terminalIds = new Set(
(snapshot.terminalTurns ?? []).map((turn) => turn.turnId),
);
let lastKnownTerminalIndex = -1;
turns.forEach((turn, index) => {
if (terminalIds.has(text(turn.id))) lastKnownTerminalIndex = index;
});
// Releasing a consumed marker requires both an actual history array
// and a checkpointed terminal that anchors its ordering. An array that
// omits every durable terminal may be truncated or inconsistent, so
// absence from it is not proof that the provider rejected the turn.
if (providerHistoryIsArray && lastKnownTerminalIndex >= 0) {
providerTurnIds = new Set(
turns
.map((turn) => text(turn.id))
.filter((turnId) => turnId.length > 0),
);
}
const laterTurns =
lastKnownTerminalIndex < 0
? []
: turns.slice(lastKnownTerminalIndex + 1);
if (laterTurns.length > 1) {
await cancellation.wait(cancellation.close());
return {
recovered: false,
reason:
"provider exposed multiple uncheckpointed disposition recovery turns",
};
}
const uncheckpointedTurnId = text(laterTurns[0]?.id);
if (laterTurns.length === 1 && uncheckpointedTurnId.length === 0) {
await cancellation.wait(cancellation.close());
return {
recovered: false,
reason:
"provider exposed an unidentifiable disposition recovery turn",
};
}
if (uncheckpointedTurnId.length > 0) {
if (
dispositionOnlyRecoveryTurnId !== null &&
dispositionOnlyRecoveryTurnId !== uncheckpointedTurnId
) {
await cancellation.wait(cancellation.close());
return {
recovered: false,
reason: "provider changed the bound disposition recovery turn",
};
}
// A previous process reached the provider but crashed before it
// could checkpoint the accepted turn or durably append its terminal.
// Inspect provider history even when the one-shot submitted marker
// was checkpointed, and adopt the exact turn instead of waiting on a
// reconstructed terminal session or submitting a duplicate.
recoveredActiveTurnId = uncheckpointedTurnId;
dispositionOnlyRecoveryConsumed = true;
dispositionOnlyRecoveryTurnId = uncheckpointedTurnId;
reconcileUncheckpointedDispositionTurn = true;
}
}
if (
dispositionOnlyRecoveryConsumed &&
recoveredActiveTurnId === null &&
!reconcileUncheckpointedDispositionTurn &&
providerTurnIds !== null &&
(dispositionOnlyRecoveryTurnId === null ||
(!providerTurnIds.has(dispositionOnlyRecoveryTurnId) &&
!(snapshot.terminalTurns ?? []).some(
(terminal) => terminal.turnId === dispositionOnlyRecoveryTurnId,
)))
) {
// Older or crash-raced checkpoints could persist the pre-request
// one-shot marker, including a requested turn id, without an accepted
// provider turn. With no matching provider history or checkpointed
// terminal, the marker alone is not acceptance evidence. The native
// runtime still checks durable replay before allowing a retry, and the
// reconstructed session must retain disposition-only mode so that a
// safe retry cannot repeat the original task envelope.
dispositionOnlyRecoveryConsumed = false;
dispositionOnlyRecoveryTurnId = null;
}
if (opened.context.liveConsole)
opened.context.liveConsole.goals = this.#caps.goals;
const session = this.#session({
transport,
runId: snapshot.runId,
normalizedSessionId: snapshot.normalizedSessionId,
opened,
goal,
goalAvailability: this.#goalAvailability,
goalReasonCode: this.#goalReasonCode,
goalReason: this.#goalReason,
resumed: true,
activeTurnId: recoveredActiveTurnId,
semanticResult: snapshot.semanticResult ?? null,
terminalTurns: snapshot.terminalTurns ?? [],
codexUsageBaseline: snapshot.codexUsageBaseline,
dispositionOnlyRecoveryConsumed,
dispositionOnlyRecoveryTurnId,
stalePendingRuntimeRequests: snapshot.pendingRuntimeRequests ?? [],
lineage: snapshot.lineage,
sourceSequence: snapshot.lastSourceSequence ?? 0,
});
// A provider may settle the checkpointed turn while this controller is
// disconnected (including during timeout cleanup). Reopening a thread
// does not replay that terminal notification. Reconcile the exact turn
// before exposing the session so callers neither wait on a dead turn
// nor submit the original work again. Missing/conflicting history still
// fails closed in reconcile().
if (
recoveredActiveTurnId !== null ||
reconcileUncheckpointedDispositionTurn
) {
await cancellation.wait(session.reconcile?.() ?? Promise.resolve({}));
}
return {
recovered: true,
session,
};
} catch (error) {
await cancellation.close().catch(() => {});
if (error instanceof NativeSessionProtocolIntegrityError) throw error;
if (options.signal.aborted) options.signal.throwIfAborted();
return { recovered: false, reason: redactCodexDiagnostic(String(error)) };
} finally {
cancellation.detach();
}
}
#transport(context?: {
workingDirectory?: string;
providerRecoveryPolicy?: PersistedHarnessSession["providerRecoveryPolicy"];
persistedSession?: Pick<
PersistedHarnessSession,
| "driverSessionId"
| "providerSessionId"
| "providerIdentity"
| "activeTurnId"
>;
}): CodexAppServerTransport {
const workingDirectory = context?.workingDirectory ?? this.#options.environment?.PAPERCLIP_WORKSPACE_CWD;
if (!this.#options.transportFactory && this.#options.environment?.CODEX_HOME && workingDirectory) {
trustCodexStartupRoot(this.#options.environment.CODEX_HOME, workingDirectory);
}
return (
this.#options.transportFactory?.(context) ??
new ProcessCodexAppServerTransport({
workingDirectory,
args: createIsolatedCodexAppServerArgs(this.#options.environment, codexExecutableReadOnlyRoots(this.#options.environment ?? process.env)),
environment: createSanitizedCodexEnvironment(this.#options.environment),
onDiagnostic: this.#options.onDiagnostic,
processGroup: true,
})
);
}
async #negotiateCollaborationMode(
transport: CodexAppServerTransport,
threadResponse: Record<string, unknown>,
requested: "default" | "plan",
): Promise<Record<string, unknown> | null> {
if (requested !== "plan") return null;
try {
const response = await transport.request("collaborationMode/list", {});
const preset = Array.isArray(response.data)
? response.data
.map(record)
.find((candidate) => text(candidate.mode) === "plan")
: undefined;
if (!preset) throw new Error("plan preset is absent");
const model = text(
preset.model,
text(threadResponse.model, text(record(threadResponse.thread).model)),
);
if (model.length === 0)
throw new Error("plan preset did not resolve a model");
return {
mode: "plan",
settings: {
model,
reasoning_effort: preset.reasoning_effort ?? null,
developer_instructions: null,
},
};
} catch (cause) {
if (cause instanceof NativeSessionProtocolIntegrityError) throw cause;
const error = new Error(
`planning_mode_unsupported: installed Codex app-server did not expose a usable native plan collaboration mode (${redactCodexDiagnostic(String(cause))})`,
);
error.name = "PlanningModeUnsupportedError";
throw error;
}
}
async #persistProcessOwnership(
transport: CodexAppServerTransport,
): Promise<void> {
if (!this.#options.onSpawn) return;
const processInfo: CodexTransportProcessInfo | undefined =
transport.processInfo?.();
if (!processInfo || processInfo.exited || processInfo.pid === null) return;
const identity = `${processInfo.pid}:${processInfo.processGroupId ?? ""}:${processInfo.startedAt}`;
if (this.#persistedProcessIdentities.get(transport) === identity) return;
await this.#options.onSpawn({
pid: processInfo.pid,
processGroupId: processInfo.processGroupId,
startedAt: processInfo.startedAt,
});
this.#persistedProcessIdentities.set(transport, identity);
}
async #initialize(
transport: CodexAppServerTransport,
): Promise<Record<string, unknown>> {
const initialized = await transport.request("initialize", {
clientInfo: {
name: "paperclip-runner",
title: "Paperclip Runner",
version: DRIVER_VERSION,
},
capabilities: { experimentalApi: true, requestAttestation: false },
});
transport.notify("initialized");
return initialized;
}
async #discoverGoal(
transport: CodexAppServerTransport,
threadId: string,
): Promise<HarnessThreadGoal | null | undefined> {
if (!this.#caps.goals) return undefined;
try {
const response = await transport.request("thread/goal/get", { threadId });
return parseThreadGoal(response.goal);
} catch (error) {
if (error instanceof NativeSessionProtocolIntegrityError) throw error;
const policyDisabled =
error instanceof CodexRpcError
&& (error.message.toLowerCase().includes("policy")
|| error.message.toLowerCase().includes("disabled"));
if (policyDisabled || isCodexMethodUnavailable(error)) {
// The provider answered, and its answer is that this build has no goal
// API. That is the only evidence that retires the capability.
this.#caps.goals = false;
if (policyDisabled) {
this.#goalAvailability = "policy_disabled";
this.#goalReasonCode = "codex_goal_policy_disabled";
this.#goalReason =
"Session goals are disabled by the Codex provider policy.";
} else {
this.#goalAvailability = "unsupported";
this.#goalReasonCode = "codex_goal_api_unavailable";
this.#goalReason =
"This Codex app-server does not expose thread goals.";
}
this.#options.onDiagnostic?.(
redactCodexDiagnostic(`thread goals unavailable: ${String(error)}`),
);
return undefined;
}
// A transport or protocol failure says nothing about what the provider
// supports, so the capability stays as advertised and the goal is merely
// unknown until the next call.
this.#options.onDiagnostic?.(
redactCodexDiagnostic(`thread goal probe failed: ${String(error)}`),
);
return undefined;
}
}
#openedThread(
response: Record<string, unknown>,
initialize: Record<string, unknown>,
workingDirectory: string,
collaborationMode: Record<string, unknown> | null,
): OpenedCodexThread {
const thread = record(response.thread);
const threadId = text(thread.id);
if (threadId.length === 0)
throw new Error("Codex thread response omitted thread.id");
const providerSessionId = text(thread.sessionId) || null;
if (
this.#options.requireProviderSessionIdentity &&
providerSessionId === null
) {
throw new Error(
`provider_initialize_protocol_error: provider=${this.#options.driverIdentity?.kind ?? "codex"} stage=session.open omitted provider session identity`,
);
}
const activePermissionProfile = record(thread.activePermissionProfile);
const permissionProfileId = text(activePermissionProfile.id);
const requestedMode = this.#options.requestedCollaborationMode ?? "default";
const requiredPermissionProfile =
text(createSecuredCodexThreadParams(workingDirectory, requestedMode, true, false, this.#options.environment).permissions);
if (
permissionProfileId.length > 0 &&
permissionProfileId !== requiredPermissionProfile
) {
throw new Error(
"Codex thread did not activate the required filesystem permission profile",
);
}
const configuredPermissionProfile = {
...activePermissionProfile,
id: requiredPermissionProfile,
};
const returnedWorkingDirectory = text(response.cwd, workingDirectory);
if (resolve(returnedWorkingDirectory) !== workingDirectory) {
throw new Error(
"Codex thread response changed the assigned working directory",
);
}
const providerIdentity = parseProviderIdentity(thread.providerIdentity);
return {
threadId,
providerSessionId,
...(providerIdentity === undefined ? {} : { providerIdentity }),
collaborationMode,
context: {
protocolVersion: CODEX_CODEX_PROTOCOL_VERSION,
codexVersion: boundedText(initialize.userAgent),
clientInfo: {
name: "paperclip-runner",
title: "Paperclip Runner",
version: DRIVER_VERSION,
},
model: boundedText(response.model),
modelProvider: boundedText(
response.modelProvider,
boundedText(thread.modelProvider),
),
workingDirectory,
collaborationMode: collaborationMode === null ? "default" : "plan",
sandbox: {
permissionProfile: boundedCodexValue(configuredPermissionProfile),
legacyPolicy: boundedCodexValue(response.sandbox ?? null),
rootAccess: "none",
minimalRuntimeAccess: "read",
workspaceAccess: requestedMode === "plan" ? "read" : "write",
networkAccess: codexNetworkAccess(this.#options.environment),
githubAuthenticationMode: this.#options.environment?.PAPERCLIP_GITHUB_AUTH_MODE ?? "managed",
},
approvalPolicy: boundedCodexValue(
response.approvalPolicy ??
this.#options.approvalPolicy ??
"never",
),
baseInstructions: this.#baseInstructions(),
instructionSources: Array.isArray(response.instructionSources)
? response.instructionSources
.filter((value): value is string => typeof value === "string")
.slice(0, 32)
.map((value) => boundedText(value))
: [],
instructionPolicy: {
skillInstructions: this.#options.includeSkillInstructions ?? false,
appInstructions: false,
collaborationInstructions:
this.#options.includeCollaborationModeInstructions ?? true,
},
environmentKeys: Object.keys(
codexCommandEnvironment(this.#options.environment),
).sort(),
dynamicToolNames: this.#providerDynamicTools().map((tool) =>
text(tool.name),
),
modelInputKinds: ["text"],
liveConsole: {
conversationMode: this.#prepared()
? "prepared"
: this.#direct()
? "direct"
: "task",
runtimeRequestResolution: this.#caps.runtimeRequestResolution,
goals: this.#caps.goals,
threadLineage: this.#caps.threadLineage,
},
envelope: structuredClone(this.#options.taskEnvelope),
},
lineage: lineageFromThread(thread),
};
}
#session(input: {
transport: CodexAppServerTransport;
runId: string;
normalizedSessionId: string;
opened: OpenedCodexThread;
goal?: HarnessThreadGoal | null;
goalAvailability: CodexGoalAvailability;
goalReasonCode: string | null;
goalReason: string | null;
resumed: boolean;
activeTurnId?: string | null;
semanticResult?: PersistedHarnessSemanticResult | null;
terminalTurns?: PersistedHarnessTurnTerminal[];
codexUsageBaseline?: PersistedHarnessSession["codexUsageBaseline"];
dispositionOnlyRecoveryConsumed?: boolean;
dispositionOnlyRecoveryTurnId?: string | null;
stalePendingRuntimeRequests?: HarnessRuntimeRequest[];
lineage?: HarnessThreadLineageEntry[];
sourceSequence: number;
}): CodexHarnessSession {
return new CodexHarnessSession({
...input,
taskEnvelope: this.#options.taskEnvelope,
conversationMode: this.#prepared()
? "prepared"
: this.#direct()
? "direct"
: "task",
now: this.#options.now ?? (() => new Date()),
runnerInstanceId: this.#options.runnerInstanceId ?? "runner-codex",
driverKind: this.#options.driverIdentity?.kind ?? DRIVER_KIND,
capabilities: this.#caps,
goalCapability: this.#goalCapability,
dynamicTools: this.#providerDynamicTools(),
skillInputs: this.#options.skillInputs,
dynamicToolHandler: this.#options.dynamicToolHandler,
completionFeedback: this.#options.completionFeedback,
});
}
}