{"record":{"id":"aca40ee471bfd879","repo":"paperclipai/paperclip","slug":"acpx-sidecar-runtime-context-must-be-pre-materiali","errorCode":null,"errorMessage":"ACPX sidecar runtime context must be pre-materialized","messagePattern":"ACPX sidecar runtime context must be pre-materialized","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/paperclip-runner/src/cli/acpx-runtime-sidecar.ts","lineNumber":1016,"sourceCode":"  const bytes = Buffer.from(redacted);\n  return {\n    output: bytes\n      .subarray(Math.max(0, bytes.length - 64 * 1024))\n      .toString(\"utf8\"),\n    outputBytes: bytes.length,\n    outputTruncated: bytes.length > 64 * 1024,\n    outputDigest: `sha256:${createHash(\"sha256\").update(bytes).digest(\"hex\")}`,\n  };\n}\n\nfunction parseOpenParams(\n  value: Record<string, unknown>,\n): AcpxSidecarOpenParams {\n  const agent = requireQualifiedAgent(value.agent);\n  const model = requiredText(value.model, \"model\");\n  resolveQualifiedAcpxProfile(agent, model);\n  if (value.runtimeContext !== undefined && value.runtimeContext !== null) {\n    throw new Error(\"ACPX sidecar runtime context must be pre-materialized\");\n  }\n  if (\n    value.providerSessionKey !== undefined &&\n    value.providerSessionKey !== null\n  ) {\n    throw new Error(\n      \"ACPX replacement provider sessions are not available in this release\",\n    );\n  }\n  return {\n    runtimeDirectory: requiredText(value.runtimeDirectory, \"runtimeDirectory\"),\n    normalizedSessionId: boundedIdentity(\n      value.normalizedSessionId,\n      \"normalizedSessionId\",\n    ),\n    workingDirectory: requiredText(value.workingDirectory, \"workingDirectory\"),\n    agent,\n    model,","sourceCodeStart":998,"sourceCodeEnd":1034,"githubUrl":"https://github.com/paperclipai/paperclip/blob/01ad8584922b5d85292b1723cae71fa0d9b07a19/packages/paperclip-runner/src/cli/acpx-runtime-sidecar.ts#L998-L1034","documentation":"The ACPX sidecar expects its runtime context to be materialized (written to disk / pre-created) before the sidecar opens; it refuses inline runtimeContext payloads in open params. Passing a non-null runtimeContext is treated as a caller contract violation.","triggerScenarios":"Calling the open-params parser (from record value) with value.runtimeContext set to any non-undefined, non-null value.","commonSituations":"Older callers embedding runtime context directly in open params; a serialization layer forwarding the whole parent context object instead of the pre-materialized path/ID.","solutions":["Pre-materialize the runtime context (write it out via the designated mechanism) and omit runtimeContext from the open params","Set runtimeContext to undefined/null in the params you pass","Update the calling code to the current sidecar open contract"],"exampleFix":"// before\nopenSidecar({ agent: 'codex', model: 'gpt-5', runtimeContext: ctx });\n// after\nawait materializeRuntimeContext(ctx);\nopenSidecar({ agent: 'codex', model: 'gpt-5' });","handlingStrategy":"validation","validationCode":"if (params.runtimeContext !== undefined && params.runtimeContext !== null) throw new Error('materialize runtime context before opening sidecar');","typeGuard":"function hasNoInlineRuntimeContext(p: { runtimeContext?: unknown }): p is Omit<typeof p, 'runtimeContext'> {\n  return p.runtimeContext === undefined || p.runtimeContext === null;\n}","tryCatchPattern":"try { await openSidecar(params); }\ncatch (e) { if (String(e.message).includes('pre-materialized')) { await materializeRuntimeContext(params.runtimeContext); delete params.runtimeContext; await openSidecar(params); } else throw e; }","preventionTips":["Follow the current sidecar open contract: materialize context out-of-band","Add a caller-side assert that runtimeContext is absent before open","Keep serialization layers from forwarding whole context objects into open params"],"tags":["acpx","validation","contract"],"backgroundTag":"invalid-argument-value","analyzedSha":"01ad8584922b5d85292b1723cae71fa0d9b07a19","analyzedAt":"2026-09-10T03:14:50.855Z","contentChangedAt":"2026-09-10T03:14:50.855Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}