mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-01 15:35:12 +01:00
DottaandPaperclip
8bcc5a01ed
## Thinking Path > - Paperclip lets people answer questions while native agent work is active. > - Runner drivers translate provider question forms and answers into the shared contract. > - Pinned OpenCode 1.18.34 enables written answers when `custom` is omitted. > - The driver required explicit `true`, so it removed that input from ordinary native questions. > - The same branch could override a native opt-out or add a separate custom field to a text-only question. > - This pull request preserves the native default, explicit opt-out, original choices, and exact answer delivery. ## Linked Issues or Issue Description **What happened?** A native OpenCode question with choices and no `custom` field loses its written-answer control in Paperclip. The pinned provider enables that control by default. A legacy alias can also override native `custom:false`. A question with no choices and `custom:true` is rejected because the driver adds a separate custom field to text mode. **Expected behavior** Follow the [pinned OpenCode question contract](https://github.com/anomalyco/opencode/blob/v1.18.34/packages/schema/src/v1/question.ts). Preserve the written-answer default for choices. Honor native `custom:false`. Keep optionless questions text-only. Preserve every supplied choice and return the exact written answer to the same native request. **Steps to reproduce** Use the normalizer regression or the local OpenCode driver fixture. Emit a native question with choices and omit `custom`. The unfixed driver omits `customAnswer`; its existing written-answer roundtrip assertion fails. The separate negative controls reproduce native opt-out precedence and text-only normalization errors. **Paperclip version or commit** Reproduced on main `f2db909393de124caf6a5380a52d4e0e1d621661`, with pinned `opencode-ai@1.18.34`. ## What Changed - Apply the native `custom` flag first, then the legacy alias, then the pinned default of `true`. - Add a separate custom field only when choices exist. Keep optionless questions text-only. - Add default, opt-out, alias, and exact response validation regressions. Make the driver fixture omit the optional native flag and retain its exact custom-answer roundtrip assertion. - Document the pinned native behavior. ## Verification - Before the fix, the real normalizer fails three targeted assertions: omitted custom input, native opt-out precedence, and optionless text with `custom:true`. - The local driver subprocess regression also fails before the fix. Its native request omits `custom`, and the driver drops the expected written-answer control. - After the fix, all **79 tests in three files pass**: the new nine-case normalizer suite, the full 65-case OpenCode driver suite, and the five question-set response tests. The driver sends the unchanged written answer in the provider's ordered answer array and records one terminal request resolution. - Runner TypeScript check passes. A first attempt lacked the isolated eval-kernel declarations; building that local dependency resolved the setup gap. Locked dependencies were installed from the existing cache with scripts disabled. - Diff checks pass. Exact-head [canonical CI run 41203866644](https://github.com/paperclipai/paperclip/actions/runs/41203866644) passes build, typecheck, release registry, Runner checks, server tests, and all eight E2E shards at `72b21207e8590b78e24fe2cef4e3f6c374be53a4`. All current PR checks are terminal with no failures. Storybook is skipped for this scope and Paperclip Review is neutral. Full repository checks were not repeated locally for this narrow provider translation change. - [Fresh Greptile review](https://github.com/paperclipai/paperclip/pull/18456#issuecomment-6543742512) gives 5/5 on that exact head with no actionable findings. All review threads are addressed. GitHub reports `MERGEABLE` and `CLEAN`. - Local tests use a controlled provider fixture. They do not establish a paid model pass or attribute a deployment incident without its original native arguments. No QA run, runtime deployment, protected pin, journey oracle, prompt, budget, run bound, or model setting changed. ## Risks Native OpenCode choices now expose the written-answer control that the provider already enables by default. Explicit native opt-out wins over the legacy alias, and disabled custom responses remain rejected. Existing choice IDs and labels remain unchanged. Deployed users need the repaired Runner artifact through the normal delivery path. Local driver proof does not replace deployed journey qualification. ## Model Used OpenAI Codex, GPT-6 family, with reasoning, source inspection, and code execution. The host does not expose the exact underlying model version or context-window size. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with available 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; none repairs this native default - [x] I have described the issue in-PR following the bug template - [x] I have not referenced internal/instance-local Paperclip issues or links - [x] My branch name describes the change and contains no internal ticket or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation - [x] I have considered and documented risks - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before merge Co-authored-by: Paperclip <noreply@paperclip.ing>
3234 lines
118 KiB
TypeScript
3234 lines
118 KiB
TypeScript
import { isOpenRouterUrl, OPENROUTER_ATTRIBUTION_HEADERS } from "../openrouter-attribution.js";
|
|
import { spawn, type ChildProcess } from "node:child_process";
|
|
import { resolveCompletionContinuation } from "../completion-continuation.js";
|
|
import { createHash, randomBytes } from "node:crypto";
|
|
import { accessSync, constants, readFileSync, realpathSync, statSync } from "node:fs";
|
|
import { createRequire } from "node:module";
|
|
import {
|
|
chmod,
|
|
lstat,
|
|
mkdir,
|
|
mkdtemp,
|
|
readFile,
|
|
readdir,
|
|
realpath,
|
|
rm,
|
|
writeFile,
|
|
} from "node:fs/promises";
|
|
import { createServer } from "node:net";
|
|
import { constants as osConstants } from "node:os";
|
|
import { Agent as HttpAgent, createServer as createHttpServer, request as requestHttp, type IncomingMessage } from "node:http";
|
|
import { Agent as HttpsAgent, request as requestHttps } from "node:https";
|
|
import { getCACertificates } from "node:tls";
|
|
import { pipeline } from "node:stream/promises";
|
|
import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
|
|
|
|
import { parseOpenCodeReasoningMode, type OpenCodeReasoningMode } from "./reasoning-mode.js";
|
|
import { createOpenCodeCompanyObservability } from "./company-observability.js";
|
|
import { startOpenCodePerformanceDiagnostics } from "./performance-diagnostics.js";
|
|
import { PROVIDER_PERFORMANCE_ENV } from "../../contracts/provider-performance.js";
|
|
import { annotateOmittedProviderText, parseOpenCodeSseFrames } from "./sse-frames.js";
|
|
import { githubCredentialEnvironment } from "../../github-credential-environment.js";
|
|
|
|
import {
|
|
CODEX_SKILLLESS_BASE_INSTRUCTIONS,
|
|
createCodexTaskEnvelope,
|
|
type CodexTaskEnvelope,
|
|
} from "../../contracts/codex.js";
|
|
import {
|
|
PRP_BLOCK_TOOL_NAME,
|
|
PRP_COMPLETION_TOOL_NAME,
|
|
} from "../../contracts/completion-result.js";
|
|
import type {
|
|
HarnessDriver,
|
|
HarnessDriverConfigValidation,
|
|
HarnessDriverDescriptor,
|
|
HarnessSession,
|
|
HarnessSessionRecoveryResult,
|
|
HarnessTranscriptSnapshot,
|
|
OpenHarnessSessionInput,
|
|
PersistedHarnessSession,
|
|
HarnessRuntimeRequest,
|
|
HarnessRuntimeRequestHandoff,
|
|
HarnessRuntimeRequestResolution,
|
|
PaperclipQuestion,
|
|
PaperclipQuestionResponse,
|
|
PaperclipQuestionSet,
|
|
} from "../../contracts/harness-driver.js";
|
|
import {
|
|
PAPERCLIP_QUESTION_SET_SCHEMA,
|
|
PAPERCLIP_RUNTIME_REQUEST_SCHEMA_V2,
|
|
harnessRuntimeInputExpiredOutcome,
|
|
harnessRuntimeRequestOutcome,
|
|
parseHarnessRuntimeRequestResolution,
|
|
parsePaperclipQuestionSet,
|
|
} from "../../contracts/harness-driver.js";
|
|
import type {
|
|
NativeSessionCapabilities,
|
|
NativeUserMessage,
|
|
} from "../../contracts/types.js";
|
|
import type { NativeRuntimeContextSnapshot } from "../../contracts/runtime-context.js";
|
|
import {
|
|
createProviderTraceFileSink,
|
|
type ProviderTraceFileSink,
|
|
} from "../../contracts/provider-trace-file-sink.js";
|
|
import type {
|
|
PrpEvent,
|
|
PrpStructuredRunResult,
|
|
} from "../../protocol/replay-contract.js";
|
|
import { validatePrpStructuredRunResult } from "../../protocol/replay-contract.js";
|
|
import { paperclipWorkspaceFileReferencesFromText } from "../../live/workspace-file-reference.js";
|
|
import {
|
|
canonicalOpenCodeDisplayToolName,
|
|
canonicalProviderEventsFromOpenCodePart,
|
|
providerFamilyCapabilities,
|
|
} from "../../provider-events.js";
|
|
import {
|
|
canonicalOpenCodeMcpToolName,
|
|
startOpenCodeMcpBridge,
|
|
type OpenCodeMcpBridge,
|
|
} from "./mcp-bridge.js";
|
|
import { nativeMcpLaunchBinding } from "../native-mcp.js";
|
|
import {
|
|
materializeNativeRuntimeSkills,
|
|
releaseMaterializedNativeRuntimeSkills,
|
|
} from "../runtime-context-materializer.js";
|
|
|
|
export const OPENCODE_SERVER_DRIVER_KIND = "opencode_server" as const;
|
|
export const QUALIFIED_OPENCODE_VERSION = "1.18.34" as const;
|
|
export const QUALIFIED_OPENCODE_MODEL =
|
|
"openrouter/deepseek/deepseek-v4-flash-0731" as const;
|
|
|
|
/** Resolve a declared, pinned native dependency without PATH or install fallback. */
|
|
export function resolvePinnedOpenCodeCommand(
|
|
issuer: string | URL = import.meta.url,
|
|
target: { platform?: string; architecture?: string } = {},
|
|
): string {
|
|
try {
|
|
const platform = target.platform ?? process.platform;
|
|
const architecture = target.architecture ?? process.arch;
|
|
const packageNames: Record<string, string[]> = {
|
|
"linux-x64": ["opencode-linux-x64-baseline"],
|
|
"darwin-arm64": ["opencode-darwin-arm64"],
|
|
"darwin-x64": ["opencode-darwin-x64-baseline"],
|
|
};
|
|
const candidates = packageNames[`${platform}-${architecture}`];
|
|
if (!candidates) {
|
|
throw new Error("OpenCode native target is not qualified");
|
|
}
|
|
const manifestPath = realpathSync(createRequire(issuer).resolve("opencode-ai/package.json"));
|
|
const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
|
|
if (manifest.name !== "opencode-ai" || manifest.version !== QUALIFIED_OPENCODE_VERSION) {
|
|
throw new Error(`OpenCode package version mismatch: expected opencode-ai@${QUALIFIED_OPENCODE_VERSION}`);
|
|
}
|
|
const dependencyRequire = createRequire(manifestPath);
|
|
for (const name of candidates) {
|
|
if (manifest.optionalDependencies?.[name] !== QUALIFIED_OPENCODE_VERSION) {
|
|
throw new Error("OpenCode platform dependency does not match its qualified version");
|
|
}
|
|
let platformManifest: string;
|
|
try {
|
|
platformManifest = realpathSync(dependencyRequire.resolve(`${name}/package.json`));
|
|
} catch (error) {
|
|
if (["MODULE_NOT_FOUND", "ENOENT"].includes((error as NodeJS.ErrnoException).code ?? "")) {
|
|
continue;
|
|
}
|
|
throw error;
|
|
}
|
|
const metadata = JSON.parse(readFileSync(platformManifest, "utf8"));
|
|
if (metadata.name !== name || metadata.version !== QUALIFIED_OPENCODE_VERSION
|
|
|| !Array.isArray(metadata.os) || !metadata.os.includes(platform)
|
|
|| !Array.isArray(metadata.cpu) || !metadata.cpu.includes(architecture)) {
|
|
throw new Error("OpenCode installed platform artifact identity mismatch");
|
|
}
|
|
const root = dirname(platformManifest);
|
|
const executable = realpathSync(resolve(root, "bin/opencode"));
|
|
const inside = relative(root, executable);
|
|
if (!inside || inside === ".." || inside.startsWith(`..${sep}`) || isAbsolute(inside)) {
|
|
throw new Error("OpenCode executable escapes its qualified platform package");
|
|
}
|
|
if (!statSync(executable).isFile()) {
|
|
throw new Error("OpenCode executable is not a regular file");
|
|
}
|
|
accessSync(executable, constants.X_OK);
|
|
return executable;
|
|
}
|
|
throw new Error("OpenCode qualified platform dependency is missing");
|
|
} catch (error) {
|
|
throw new Error(
|
|
`Pinned OpenCode runtime unavailable: ${(error as Error).message}. Restore Paperclip's runtime dependencies.`,
|
|
{ cause: error },
|
|
);
|
|
}
|
|
}
|
|
|
|
type DynamicToolHandler = (call: {
|
|
tool: string;
|
|
callId: string;
|
|
threadId: string;
|
|
turnId: string;
|
|
arguments: unknown;
|
|
}) => Promise<unknown>;
|
|
|
|
export type OpenCodeCompletionFeedback = (result: PrpStructuredRunResult, call: {
|
|
tool: string;
|
|
callId: string;
|
|
threadId: string;
|
|
turnId: string;
|
|
}) => Promise<string>;
|
|
|
|
export interface OpenCodeServerDriverOptions {
|
|
model: string;
|
|
permissionMode?: "allow" | "ask" | "deny";
|
|
taskEnvelope?: CodexTaskEnvelope;
|
|
conversationMode?: "task" | "prepared";
|
|
runnerInstanceId?: string;
|
|
command?: string;
|
|
/** Inherited runner-owned executable descriptor duplicated into the child. */
|
|
commandFd?: number;
|
|
/** Runner-owned executable path lifecycle used only by the macOS proxy. */
|
|
commandLifecycle?: {
|
|
beforeSpawn(): void;
|
|
afterSpawn(): void;
|
|
afterExit?(): void;
|
|
};
|
|
runtimeDirectory: string;
|
|
systemInstructions?: string;
|
|
runtimeContext?: NativeRuntimeContextSnapshot | null;
|
|
environment?: NodeJS.ProcessEnv;
|
|
dynamicTools?: readonly Readonly<Record<string, unknown>>[];
|
|
dynamicToolHandler?: DynamicToolHandler;
|
|
completionFeedback?: OpenCodeCompletionFeedback;
|
|
onSpawn?: (meta: {
|
|
pid: number;
|
|
processGroupId: number | null;
|
|
startedAt: string;
|
|
}) => Promise<void>;
|
|
/** Keep false when an outer supervisor already owns the process group. */
|
|
isolateProcessGroup?: boolean;
|
|
onDiagnostic?: (message: string) => void;
|
|
fetch?: typeof globalThis.fetch;
|
|
now?: () => Date;
|
|
}
|
|
|
|
interface OpenCodeRuntime {
|
|
baseUrl: string;
|
|
authHeader: string;
|
|
version: string;
|
|
permissionMode: "allow" | "ask" | "deny";
|
|
process: ChildProcess;
|
|
bridge: OpenCodeMcpBridge;
|
|
trace: ProviderTraceFileSink | null;
|
|
sensitiveValues: readonly string[];
|
|
performanceDiagnostics: Awaited<ReturnType<typeof startOpenCodePerformanceDiagnostics>> | null;
|
|
close(input?: {
|
|
finalizeTrace?: boolean;
|
|
reason?: string | null;
|
|
}): Promise<void>;
|
|
}
|
|
|
|
const CAPABILITIES: NativeSessionCapabilities = {
|
|
resume: true,
|
|
toolRefreshOnResume: true,
|
|
typedEvents: true,
|
|
typedEventFamilies: providerFamilyCapabilities({
|
|
tool_execution: "available",
|
|
research: "available",
|
|
delegation: "available",
|
|
context: "available",
|
|
artifact: "policy_disabled",
|
|
provider_notice: "available",
|
|
}),
|
|
steering: false,
|
|
interruption: true,
|
|
structuredResult: true,
|
|
read: true,
|
|
reconciliation: true,
|
|
usage: true,
|
|
dynamicTools: true,
|
|
runtimeRequestResolution: true,
|
|
runtimeRequestHandoff: true,
|
|
goals: false,
|
|
threadLineage: false,
|
|
unsupported: ["steering", "goals", "threadLineage"],
|
|
};
|
|
|
|
export class OpenCodeServerDriver implements HarnessDriver {
|
|
readonly #options: OpenCodeServerDriverOptions;
|
|
|
|
constructor(options: OpenCodeServerDriverOptions) {
|
|
this.#options = options;
|
|
}
|
|
|
|
async descriptor(): Promise<HarnessDriverDescriptor> {
|
|
return {
|
|
kind: OPENCODE_SERVER_DRIVER_KIND,
|
|
displayName: "OpenCode server",
|
|
version: QUALIFIED_OPENCODE_VERSION,
|
|
protocolVersion: "http+sse/v1",
|
|
runtimeContextCapabilities: {
|
|
instructions: "native",
|
|
skills: "native",
|
|
mcp: "native",
|
|
},
|
|
capabilities: structuredClone(CAPABILITIES),
|
|
};
|
|
}
|
|
|
|
async validateConfig(
|
|
config: unknown,
|
|
): Promise<HarnessDriverConfigValidation> {
|
|
const candidate = isRecord(config) ? config : {};
|
|
const issues = [];
|
|
const model =
|
|
typeof candidate.model === "string" ? candidate.model.trim() : "";
|
|
if (!validModel(model))
|
|
issues.push({
|
|
path: "model",
|
|
code: "invalid_model",
|
|
message: "OpenCode model must use provider/model form.",
|
|
});
|
|
const command =
|
|
typeof candidate.command === "string"
|
|
? candidate.command.trim()
|
|
: "opencode";
|
|
if (!command)
|
|
issues.push({
|
|
path: "command",
|
|
code: "invalid_command",
|
|
message: "OpenCode command cannot be empty.",
|
|
});
|
|
const permissionMode = candidate.permissionMode ?? "allow";
|
|
if (
|
|
permissionMode !== "allow" &&
|
|
permissionMode !== "ask" &&
|
|
permissionMode !== "deny"
|
|
) {
|
|
issues.push({
|
|
path: "permissionMode",
|
|
code: "invalid_permission_mode",
|
|
message: "OpenCode permission mode must be allow, ask, or deny.",
|
|
});
|
|
}
|
|
return issues.length === 0
|
|
? { ok: true, config: { model, command, permissionMode }, issues: [] }
|
|
: { ok: false, config: null, issues };
|
|
}
|
|
|
|
async openSession(input: OpenHarnessSessionInput): Promise<HarnessSession> {
|
|
return this.#open(input, null);
|
|
}
|
|
|
|
async recoverSession(
|
|
snapshot: PersistedHarnessSession,
|
|
): Promise<HarnessSessionRecoveryResult> {
|
|
if (
|
|
snapshot.driverKind !== OPENCODE_SERVER_DRIVER_KIND ||
|
|
!snapshot.runId ||
|
|
!snapshot.normalizedSessionId ||
|
|
!snapshot.driverSessionId
|
|
)
|
|
return {
|
|
recovered: false,
|
|
reason: "persisted OpenCode session identity is incomplete",
|
|
};
|
|
try {
|
|
const session = await this.#open(
|
|
{
|
|
runId: snapshot.runId,
|
|
normalizedSessionId: snapshot.normalizedSessionId,
|
|
workingDirectory: await this.#readWorkspace(
|
|
snapshot.normalizedSessionId,
|
|
),
|
|
},
|
|
snapshot,
|
|
);
|
|
return { recovered: true, session };
|
|
} catch (error) {
|
|
return {
|
|
recovered: false,
|
|
reason: redact(String(error), [
|
|
this.#options.environment?.OPENROUTER_API_KEY,
|
|
this.#options.environment?.PAPERCLIP_AI_PROVIDER_KEY,
|
|
]),
|
|
};
|
|
}
|
|
}
|
|
|
|
async #readWorkspace(normalizedSessionId: string): Promise<string> {
|
|
const raw = await readFile(
|
|
join(
|
|
sessionRoot(this.#options.runtimeDirectory, normalizedSessionId),
|
|
"workspace",
|
|
),
|
|
"utf8",
|
|
);
|
|
return raw.trim();
|
|
}
|
|
|
|
async #open(
|
|
input: OpenHarnessSessionInput,
|
|
snapshot: PersistedHarnessSession | null,
|
|
): Promise<HarnessSession> {
|
|
const cwd = validateWorkspace(input.workingDirectory);
|
|
const root = sessionRoot(
|
|
this.#options.runtimeDirectory,
|
|
input.normalizedSessionId,
|
|
);
|
|
await mkdir(root, { recursive: true, mode: 0o700 });
|
|
await writeFile(join(root, "workspace"), `${cwd}\n`, { mode: 0o600 });
|
|
await removeLegacyIsolatedHomes(root);
|
|
const trace = await createProviderTraceFileSink({
|
|
path: this.#options.environment?.PAPERCLIP_PROVIDER_TRACE_PATH,
|
|
provider: "opencode",
|
|
channel: "typescript_opencode_native",
|
|
maxBytes: this.#options.environment?.PAPERCLIP_PROVIDER_TRACE_MAX_BYTES,
|
|
});
|
|
let lastError: unknown = null;
|
|
for (let attempt = 1; attempt <= 3; attempt += 1) {
|
|
let session: OpenCodeHarnessSession | null = null;
|
|
let runtime: OpenCodeRuntime | null = null;
|
|
try {
|
|
runtime = await startRuntime({
|
|
options: this.#options,
|
|
root,
|
|
cwd,
|
|
trace,
|
|
dispatch: (call) => {
|
|
if (session === null)
|
|
throw new Error("OpenCode session is not ready for tool calls");
|
|
return session.dispatchTool(call);
|
|
},
|
|
});
|
|
const fetcher = this.#options.fetch ?? globalThis.fetch;
|
|
let providerSessionId =
|
|
snapshot?.providerSessionId ?? snapshot?.driverSessionId ?? null;
|
|
if (providerSessionId !== null) {
|
|
const existing = await api(
|
|
fetcher,
|
|
runtime,
|
|
`/session/${encodeURIComponent(providerSessionId)}`,
|
|
);
|
|
if (!isRecord(existing) || text(existing.id) !== providerSessionId)
|
|
throw new Error("OpenCode resumed a different session");
|
|
} else {
|
|
const created = await api(fetcher, runtime, "/session", {
|
|
method: "POST",
|
|
body: JSON.stringify({ title: `Paperclip ${input.runId}` }),
|
|
});
|
|
providerSessionId = text(record(created).id);
|
|
if (!providerSessionId)
|
|
throw new Error("OpenCode session creation omitted its id");
|
|
}
|
|
session = new OpenCodeHarnessSession({
|
|
runtime,
|
|
fetcher,
|
|
runId: input.runId,
|
|
normalizedSessionId: input.normalizedSessionId,
|
|
providerSessionId,
|
|
workingDirectory: cwd,
|
|
runnerInstanceId:
|
|
this.#options.runnerInstanceId ??
|
|
`paperclip-opencode-${input.runId}`,
|
|
model: this.#options.model,
|
|
taskEnvelope:
|
|
this.#options.taskEnvelope ??
|
|
createCodexTaskEnvelope({
|
|
objective: "Complete the supplied task.",
|
|
}),
|
|
conversationMode: this.#options.conversationMode,
|
|
systemInstructions:
|
|
this.#options.systemInstructions ??
|
|
CODEX_SKILLLESS_BASE_INSTRUCTIONS,
|
|
dynamicToolHandler: this.#options.dynamicToolHandler,
|
|
completionFeedback: this.#options.completionFeedback,
|
|
snapshot,
|
|
now: this.#options.now ?? (() => new Date()),
|
|
observabilityEnvironment: this.#options.environment,
|
|
onDiagnostic: this.#options.onDiagnostic,
|
|
});
|
|
session.startEventPump();
|
|
return session;
|
|
} catch (error) {
|
|
lastError = error;
|
|
await runtime?.close({ finalizeTrace: false });
|
|
if (attempt === 3 || !retryableOpenCodeStartupError(error)) {
|
|
await trace?.finish({ reason: "opencode_session_start_failed" });
|
|
throw error;
|
|
}
|
|
this.#options.onDiagnostic?.(
|
|
`OpenCode session startup attempt ${attempt} failed; retrying.`,
|
|
);
|
|
await new Promise((resolveDelay) =>
|
|
setTimeout(resolveDelay, 100 * attempt),
|
|
);
|
|
}
|
|
}
|
|
throw lastError;
|
|
}
|
|
}
|
|
|
|
class OpenCodeHarnessSession implements HarnessSession {
|
|
readonly #runtime: OpenCodeRuntime;
|
|
readonly #fetch: typeof globalThis.fetch;
|
|
#runId: string;
|
|
readonly #normalizedSessionId: string;
|
|
readonly #providerSessionId: string;
|
|
readonly #workingDirectory: string;
|
|
readonly #runnerInstanceId: string;
|
|
readonly #model: string;
|
|
readonly #taskEnvelope: CodexTaskEnvelope;
|
|
readonly #systemInstructions: string;
|
|
readonly #dynamicToolHandler?: DynamicToolHandler;
|
|
readonly #completionFeedback?: OpenCodeCompletionFeedback;
|
|
readonly #now: () => Date;
|
|
readonly #events = new AsyncQueue<PrpEvent>();
|
|
readonly #transcript: PrpEvent[] = [];
|
|
readonly #terminalTurns = new Map<string, string>();
|
|
readonly #seenProviderEvents = new Set<string>();
|
|
// The turn that created each native message. A raw OpenCode frame carries
|
|
// no turn identity of its own, so this map — not the mutable active-turn
|
|
// pointer, which can already have moved on to a later turn by the time a
|
|
// straggling frame for this message arrives — is the source of truth for
|
|
// which turn a message's content belongs to.
|
|
readonly #messageTurnIds = new Map<string, string>();
|
|
readonly #messageRoles = new Map<string, string>();
|
|
readonly #pendingMessageParts = new Map<
|
|
string,
|
|
Array<Record<string, unknown>>
|
|
>();
|
|
readonly #partText = new Map<string, string>();
|
|
readonly #streamingParts = new Map<string, Record<string, unknown>>();
|
|
readonly #completedTextPartIds = new Set<string>();
|
|
readonly #completedReasoningPartIds = new Set<string>();
|
|
readonly #completedTextParts: Array<{
|
|
partId: string;
|
|
messageId: string | null;
|
|
text: string;
|
|
item: Record<string, unknown>;
|
|
observedSourceSeq: number;
|
|
}> = [];
|
|
readonly #messageUsageFingerprints = new Map<string, string>();
|
|
readonly #workspaceChangesByTurn = new Map<string, Record<string, unknown>>();
|
|
#reportedSseCompaction = false;
|
|
readonly #emittedFileReferences = new Set<string>();
|
|
readonly #pendingRuntimeRequests = new Map<
|
|
string,
|
|
{
|
|
request: HarnessRuntimeRequest;
|
|
nativeQuestions: Record<string, unknown>[];
|
|
submittedResponse?: PaperclipQuestionResponse;
|
|
submittedAction?: "accept" | "accept_for_session" | "decline" | "cancel";
|
|
settling?: boolean;
|
|
}
|
|
>();
|
|
#activeTraceFrameId: number | null = null;
|
|
#activeTraceEmittedEventIds: string[] = [];
|
|
#sourceSequence: number;
|
|
#activeTurnId: string | null;
|
|
#performanceBoundaryMs = 0;
|
|
#result: PrpStructuredRunResult | null;
|
|
#resultFingerprint: string | null;
|
|
#resultCallId: string | null;
|
|
#resultTurnId: string | null;
|
|
#semanticResultTextBoundary: number | null = null;
|
|
#semanticResultProviderMessageId: string | null = null;
|
|
#lastNonTerminalToolSourceSeq = 0;
|
|
#usage: Record<string, unknown> | null = null;
|
|
readonly #conversationMode: "task" | "prepared";
|
|
#sendFullContext: boolean;
|
|
readonly #companyObservability: ReturnType<typeof createOpenCodeCompanyObservability>;
|
|
#closed = false;
|
|
#completionSettlement: Promise<void> | null = null;
|
|
#abort = new AbortController();
|
|
|
|
constructor(input: {
|
|
runtime: OpenCodeRuntime;
|
|
fetcher: typeof globalThis.fetch;
|
|
runId: string;
|
|
normalizedSessionId: string;
|
|
providerSessionId: string;
|
|
workingDirectory: string;
|
|
runnerInstanceId: string;
|
|
model: string;
|
|
conversationMode?: "task" | "prepared";
|
|
taskEnvelope: CodexTaskEnvelope;
|
|
systemInstructions: string;
|
|
dynamicToolHandler?: DynamicToolHandler;
|
|
completionFeedback?: OpenCodeCompletionFeedback;
|
|
snapshot: PersistedHarnessSession | null;
|
|
now: () => Date;
|
|
observabilityEnvironment?: NodeJS.ProcessEnv;
|
|
onDiagnostic?: (message: string) => void;
|
|
}) {
|
|
this.#runtime = input.runtime;
|
|
this.#companyObservability = createOpenCodeCompanyObservability({
|
|
environment: input.observabilityEnvironment, model: input.model, sensitiveValues: input.runtime.sensitiveValues,
|
|
onDiagnostic: input.onDiagnostic ?? ((message) => console.warn(message)),
|
|
});
|
|
this.#fetch = input.fetcher;
|
|
this.#runId = input.runId;
|
|
this.#sourceSequence = 0;
|
|
this.#normalizedSessionId = input.normalizedSessionId;
|
|
this.#providerSessionId = input.providerSessionId;
|
|
this.#workingDirectory = input.workingDirectory;
|
|
this.#runnerInstanceId = input.runnerInstanceId;
|
|
this.#model = input.model;
|
|
this.#conversationMode = input.conversationMode ?? "task";
|
|
this.#taskEnvelope = input.taskEnvelope;
|
|
this.#systemInstructions = input.systemInstructions;
|
|
this.#dynamicToolHandler = input.dynamicToolHandler;
|
|
this.#completionFeedback = input.completionFeedback;
|
|
this.#now = input.now;
|
|
this.#sendFullContext = input.snapshot === null && this.#conversationMode !== "prepared";
|
|
this.#sourceSequence = input.snapshot?.lastSourceSequence ?? 0;
|
|
this.#activeTurnId = input.snapshot?.activeTurnId ?? null;
|
|
const restored = input.snapshot?.semanticResult ?? null;
|
|
this.#result = restored?.result ?? null;
|
|
this.#resultFingerprint = restored?.fingerprint ?? null;
|
|
this.#resultCallId = restored?.callId ?? null;
|
|
this.#resultTurnId = restored?.turnId ?? null;
|
|
for (const terminal of input.snapshot?.terminalTurns ?? []) {
|
|
this.#terminalTurns.set(terminal.turnId, terminal.fingerprint);
|
|
}
|
|
if (this.#activeTurnId && this.#terminalTurns.has(this.#activeTurnId)) {
|
|
this.#activeTurnId = null;
|
|
}
|
|
this.#emit(input.snapshot ? "session.resumed" : "session.started", {
|
|
driverSessionId: input.providerSessionId,
|
|
providerSessionId: input.providerSessionId,
|
|
context: {
|
|
protocolVersion: "http+sse/v1",
|
|
opencodeVersion: input.runtime.version,
|
|
model: input.model,
|
|
modelProvider: input.model.split("/", 1)[0],
|
|
workingDirectory: input.workingDirectory,
|
|
environmentKeys: sanitizedEnvironmentKeys(),
|
|
permissionMode: input.runtime.permissionMode,
|
|
},
|
|
});
|
|
this.#emit(
|
|
"item.completed",
|
|
{
|
|
kind: "model",
|
|
text: `${input.model} (OpenCode ${input.runtime.version})`,
|
|
model: {
|
|
name: input.model,
|
|
provider: input.model.split("/", 1)[0],
|
|
opencodeVersion: input.runtime.version,
|
|
},
|
|
},
|
|
{ itemId: `${input.providerSessionId}:model` },
|
|
);
|
|
}
|
|
|
|
ids() {
|
|
return {
|
|
driverSessionId: this.#providerSessionId,
|
|
providerSessionId: this.#providerSessionId,
|
|
displayId: this.#providerSessionId,
|
|
};
|
|
}
|
|
|
|
attachRun(input: { runId: string }): void {
|
|
if (this.#activeTurnId !== null)
|
|
throw new Error("opencode_run_attach_busy");
|
|
if (!input.runId) throw new Error("opencode_run_attach_invalid");
|
|
this.#runId = input.runId;
|
|
this.#result = null;
|
|
this.#resultFingerprint = null;
|
|
this.#resultCallId = null;
|
|
this.#resultTurnId = null;
|
|
this.#semanticResultTextBoundary = null;
|
|
this.#semanticResultProviderMessageId = null;
|
|
this.#lastNonTerminalToolSourceSeq = 0;
|
|
this.#completedTextPartIds.clear();
|
|
this.#completedReasoningPartIds.clear();
|
|
this.#completedTextParts.length = 0;
|
|
// `#terminalTurns` clears here for its own persisted-snapshot bookkeeping.
|
|
// The late-frame gate in `#emit` does not depend on this map: it compares
|
|
// against `#activeTurnId` directly, so a frame for the just-finished turn
|
|
// stays blocked even after this new run attaches (see `#emit`).
|
|
this.#terminalTurns.clear();
|
|
this.#sendFullContext = false;
|
|
this.#emit("run.attached", { runId: input.runId, sameSession: true });
|
|
}
|
|
|
|
events(): AsyncIterable<PrpEvent> {
|
|
return this.#events;
|
|
}
|
|
|
|
startEventPump(): void {
|
|
void this.#recoverPendingRuntimeRequests()
|
|
.catch((error) =>
|
|
this.#emit("harness.diagnostic", {
|
|
code: "opencode_runtime_request_recovery_failed",
|
|
message: redact(String(error), this.#runtime.sensitiveValues),
|
|
}),
|
|
)
|
|
.finally(() => this.#pumpEvents());
|
|
}
|
|
|
|
supportsTurnReasoning(): boolean {
|
|
return this.#model.startsWith("openrouter/");
|
|
}
|
|
|
|
async startTurn(input: {
|
|
message: NativeUserMessage;
|
|
reasoningMode?: OpenCodeReasoningMode;
|
|
}): Promise<{ turnId: string }> {
|
|
if (this.#activeTurnId !== null)
|
|
throw new Error("OpenCode session already has an active turn");
|
|
const reasoningMode = parseOpenCodeReasoningMode(input.reasoningMode);
|
|
if (input.reasoningMode !== undefined && !this.#model.startsWith("openrouter/")) {
|
|
throw new Error("Per-turn OpenCode reasoning is supported only for OpenRouter models");
|
|
}
|
|
const turnId = `turn-${randomBytes(12).toString("hex")}`;
|
|
this.#streamingParts.clear();
|
|
this.#activeTurnId = turnId;
|
|
this.#emit("turn.submitted", {
|
|
envelopeSchema: this.#taskEnvelope.schema,
|
|
text: input.message.text,
|
|
}, { turnId });
|
|
this.#emit("turn.accepted", { turnId }, { turnId });
|
|
this.#emit("turn.started", { status: "inProgress" }, { turnId });
|
|
const [providerID, ...modelParts] = this.#model.split("/");
|
|
const modelID = modelParts.join("/");
|
|
// Keep the task envelope only on the initial task-mode wake. OpenCode
|
|
// rebuilds system instructions from the latest user message, so system
|
|
// instructions must still accompany every prompt (including recovery).
|
|
const prompt = this.#sendFullContext
|
|
? JSON.stringify({
|
|
task: this.#taskEnvelope,
|
|
message: input.message.text,
|
|
})
|
|
: input.message.text;
|
|
await api(
|
|
this.#fetch,
|
|
this.#runtime,
|
|
`/session/${encodeURIComponent(this.#providerSessionId)}/prompt_async`,
|
|
{
|
|
method: "POST",
|
|
body: JSON.stringify({
|
|
// OpenCode 1.18's PromptPayload carries the provider and model at the
|
|
// top level. Older examples used a nested `model` object; 1.18
|
|
// silently ignores that shape and falls back to the configured model,
|
|
// which can turn `openrouter/deepseek/...` into a duplicated provider
|
|
// lookup. Keep Paperclip's persisted provider/model form, but adapt it
|
|
// at this HTTP boundary.
|
|
providerID,
|
|
modelID,
|
|
// Always select the empty default variant on an ordinary turn so a
|
|
// previous disabled turn cannot change this turn's provider defaults.
|
|
...(providerID === "openrouter"
|
|
? { variant: reasoningMode === "disabled" ? "paperclip-no-reasoning" : "paperclip-default" }
|
|
: {}),
|
|
// Keep question enabled in the isolated config. OpenCode 1.18.32
|
|
// turns a prompt's deprecated `tools` map into replacement session
|
|
// permissions, so a sparse override here discards the session policy.
|
|
system: this.#systemInstructions,
|
|
parts: [{ type: "text", text: prompt }],
|
|
}),
|
|
},
|
|
);
|
|
this.#sendFullContext = false;
|
|
return { turnId };
|
|
}
|
|
|
|
async interrupt(input: { turnId?: string; reason?: string }): Promise<void> {
|
|
await this.#completionSettlement;
|
|
if (
|
|
input.turnId &&
|
|
this.#activeTurnId &&
|
|
input.turnId !== this.#activeTurnId
|
|
)
|
|
throw new Error("stale OpenCode turn");
|
|
await api(
|
|
this.#fetch,
|
|
this.#runtime,
|
|
`/session/${encodeURIComponent(this.#providerSessionId)}/abort`,
|
|
{ method: "POST" },
|
|
);
|
|
}
|
|
|
|
pendingRuntimeRequests(): HarnessRuntimeRequest[] {
|
|
return [...this.#pendingRuntimeRequests.values()].map(({ request }) =>
|
|
structuredClone(request),
|
|
);
|
|
}
|
|
|
|
async resolveRuntimeRequest(input: {
|
|
requestId: string;
|
|
turnId: string;
|
|
resolution: HarnessRuntimeRequestResolution;
|
|
}): Promise<void> {
|
|
const pending = this.#pendingRuntimeRequests.get(input.requestId);
|
|
if (!pending)
|
|
throw new Error(
|
|
`OpenCode request ${input.requestId} is no longer pending`,
|
|
);
|
|
if (
|
|
pending.request.turnId !== input.turnId ||
|
|
this.#activeTurnId !== input.turnId
|
|
) {
|
|
throw new Error(
|
|
`OpenCode request ${input.requestId} belongs to a stale turn`,
|
|
);
|
|
}
|
|
const resolution = parseHarnessRuntimeRequestResolution(
|
|
pending.request.requestKind,
|
|
input.resolution,
|
|
pending.request.input,
|
|
);
|
|
if (pending.settling)
|
|
throw new Error(
|
|
`OpenCode request ${input.requestId} is already settling`,
|
|
);
|
|
pending.settling = true;
|
|
const submit = async (operation: Promise<unknown>) => {
|
|
try {
|
|
await operation;
|
|
} catch (error) {
|
|
if (this.#pendingRuntimeRequests.get(input.requestId) === pending)
|
|
pending.settling = false;
|
|
throw error;
|
|
}
|
|
};
|
|
const workspace = `directory=${encodeURIComponent(this.#workingDirectory)}`;
|
|
if (pending.request.requestKind === "permission_approval") {
|
|
const action =
|
|
resolution.action === "accept" ||
|
|
resolution.action === "accept_for_session"
|
|
? resolution.action
|
|
: resolution.action === "decline" || resolution.action === "cancel"
|
|
? resolution.action
|
|
: "decline";
|
|
pending.submittedAction = action;
|
|
await submit(
|
|
api(
|
|
this.#fetch,
|
|
this.#runtime,
|
|
`/permission/${encodeURIComponent(input.requestId)}/reply?${workspace}`,
|
|
{
|
|
method: "POST",
|
|
body: JSON.stringify({
|
|
reply:
|
|
action === "accept"
|
|
? "once"
|
|
: action === "accept_for_session"
|
|
? "always"
|
|
: "reject",
|
|
}),
|
|
},
|
|
),
|
|
);
|
|
if (!this.#pendingRuntimeRequests.delete(input.requestId)) return;
|
|
this.#emit(
|
|
"runtime_request.resolved",
|
|
harnessRuntimeRequestOutcome(pending.request, { action }),
|
|
{
|
|
turnId: input.turnId,
|
|
itemId: pending.request.itemId,
|
|
},
|
|
);
|
|
return;
|
|
}
|
|
const base = `/question/${encodeURIComponent(input.requestId)}`;
|
|
if (resolution.action === "submit" && "response" in resolution) {
|
|
// OpenCode can broadcast question.replied before the reply HTTP request
|
|
// returns. Retain the canonical response before crossing that boundary
|
|
// so the racing terminal event carries the same durable answer record.
|
|
pending.submittedResponse = structuredClone(resolution.response);
|
|
await submit(
|
|
api(this.#fetch, this.#runtime, `${base}/reply?${workspace}`, {
|
|
method: "POST",
|
|
body: JSON.stringify({
|
|
answers: openCodeAnswers(pending, resolution.response),
|
|
}),
|
|
}),
|
|
);
|
|
} else if (resolution.action === "submit" && "answers" in resolution) {
|
|
await submit(
|
|
api(this.#fetch, this.#runtime, `${base}/reply?${workspace}`, {
|
|
method: "POST",
|
|
body: JSON.stringify({
|
|
answers: pending.nativeQuestions.map(
|
|
(question, index) =>
|
|
resolution.answers[openCodeQuestionId(question, index)]
|
|
?.answers ?? [],
|
|
),
|
|
}),
|
|
}),
|
|
);
|
|
} else {
|
|
await submit(
|
|
api(this.#fetch, this.#runtime, `${base}/reject?${workspace}`, {
|
|
method: "POST",
|
|
}),
|
|
);
|
|
}
|
|
// question.replied/question.rejected can race the HTTP response on the SSE
|
|
// stream. The first terminal fact wins; the echo must not emit a duplicate.
|
|
if (!this.#pendingRuntimeRequests.delete(input.requestId)) return;
|
|
this.#emit(
|
|
"runtime_request.resolved",
|
|
harnessRuntimeRequestOutcome(pending.request, {
|
|
action: resolution.action,
|
|
...(resolution.action === "submit" && "response" in resolution
|
|
? { response: resolution.response }
|
|
: {}),
|
|
}),
|
|
{ turnId: input.turnId, itemId: pending.request.itemId },
|
|
);
|
|
}
|
|
|
|
handoffRuntimeRequest(input: {
|
|
requestId: string;
|
|
turnId: string;
|
|
reason: "durable_handoff";
|
|
signal: AbortSignal;
|
|
}): HarnessRuntimeRequestHandoff {
|
|
if (input.signal.aborted) {
|
|
return { result: "already_settled", cleanup: Promise.resolve() };
|
|
}
|
|
const pending = this.#pendingRuntimeRequests.get(input.requestId);
|
|
if (
|
|
!pending ||
|
|
pending.request.input === undefined ||
|
|
pending.request.turnId !== input.turnId ||
|
|
this.#activeTurnId !== input.turnId ||
|
|
pending.settling ||
|
|
pending.submittedResponse !== undefined ||
|
|
pending.submittedAction !== undefined
|
|
)
|
|
return { result: "already_settled", cleanup: Promise.resolve() };
|
|
if (!this.#pendingRuntimeRequests.delete(input.requestId)) {
|
|
return { result: "already_settled", cleanup: Promise.resolve() };
|
|
}
|
|
this.#emit(
|
|
"runtime_request.expired",
|
|
harnessRuntimeInputExpiredOutcome(pending.request, input.reason),
|
|
{ turnId: input.turnId, itemId: pending.request.itemId },
|
|
);
|
|
const workspace = `directory=${encodeURIComponent(this.#workingDirectory)}`;
|
|
const cleanup = Promise.allSettled([
|
|
api(
|
|
this.#fetch,
|
|
this.#runtime,
|
|
`/question/${encodeURIComponent(input.requestId)}/reject?${workspace}`,
|
|
{ method: "POST" },
|
|
),
|
|
api(
|
|
this.#fetch,
|
|
this.#runtime,
|
|
`/session/${encodeURIComponent(this.#providerSessionId)}/abort`,
|
|
{ method: "POST" },
|
|
),
|
|
]).then(() => undefined);
|
|
return { result: "handed_off", cleanup };
|
|
}
|
|
|
|
async read(): Promise<Record<string, unknown>> {
|
|
const messages = await api(
|
|
this.#fetch,
|
|
this.#runtime,
|
|
`/session/${encodeURIComponent(this.#providerSessionId)}/message`,
|
|
);
|
|
return { sessionId: this.#providerSessionId, messages };
|
|
}
|
|
|
|
async reconcile(): Promise<Record<string, unknown>> {
|
|
const status = await api(this.#fetch, this.#runtime, "/session/status");
|
|
return {
|
|
sessionId: this.#providerSessionId,
|
|
status: record(status)[this.#providerSessionId] ?? null,
|
|
};
|
|
}
|
|
|
|
async usage(): Promise<Record<string, unknown> | null> {
|
|
return this.#usage === null ? null : structuredClone(this.#usage);
|
|
}
|
|
|
|
async transcript(): Promise<HarnessTranscriptSnapshot> {
|
|
return {
|
|
schema: "paperclip-runner/harness-transcript/v1",
|
|
complete: true,
|
|
eventCount: this.#transcript.length,
|
|
events: structuredClone(this.#transcript),
|
|
omissionReason: null,
|
|
};
|
|
}
|
|
|
|
async snapshot(): Promise<PersistedHarnessSession> {
|
|
return {
|
|
driverKind: OPENCODE_SERVER_DRIVER_KIND,
|
|
driverSessionId: this.#providerSessionId,
|
|
providerSessionId: this.#providerSessionId,
|
|
runId: this.#runId,
|
|
normalizedSessionId: this.#normalizedSessionId,
|
|
activeTurnId: this.#activeTurnId,
|
|
semanticResult:
|
|
this.#result && this.#resultFingerprint && this.#resultTurnId
|
|
? {
|
|
result: structuredClone(this.#result),
|
|
fingerprint: this.#resultFingerprint,
|
|
callId: this.#resultCallId,
|
|
turnId: this.#resultTurnId,
|
|
}
|
|
: null,
|
|
terminalTurns: [...this.#terminalTurns].map(([turnId, fingerprint]) => ({
|
|
turnId,
|
|
fingerprint,
|
|
})),
|
|
pendingRuntimeRequests: this.pendingRuntimeRequests(),
|
|
lastSourceSequence: this.#sourceSequence,
|
|
};
|
|
}
|
|
|
|
async close(): Promise<void> {
|
|
if (this.#closed) return;
|
|
// A controller response is authoritative. Settle its tool result before
|
|
// closing the provider or the event stream, rather than reject after acceptance.
|
|
await this.#completionSettlement;
|
|
if (this.#closed) return;
|
|
this.#closed = true;
|
|
this.#abort.abort();
|
|
// Settle whatever is still pending, including a request whose turn
|
|
// already went terminal without the driver observing it (see
|
|
// `#settlePendingRuntimeRequestsForTurn`). Bypass the terminal-turn
|
|
// gate so each settlement event still reaches the consumer instead of
|
|
// getting dropped as a late frame.
|
|
for (const requestId of [...this.#pendingRuntimeRequests.keys()])
|
|
this.#settlePendingRuntimeRequest(requestId);
|
|
this.#events.close();
|
|
await Promise.all([this.#runtime.close(), this.#companyObservability?.close()]);
|
|
}
|
|
|
|
// A request can outlive its own turn: the turn can fail or get cancelled
|
|
// while the request is still pending, which clears `#activeTurnId`
|
|
// without settling the request. Settle any such request the moment its
|
|
// owning turn goes terminal, before emitting the terminal turn event
|
|
// itself, so the settlement event reaches the consumer within the same
|
|
// turn it belongs to instead of waiting for a later, separate close.
|
|
#settlePendingRuntimeRequestsForTurn(turnId: string): void {
|
|
const requestIds = [...this.#pendingRuntimeRequests]
|
|
.filter(([, pending]) => pending.request.turnId === turnId)
|
|
.map(([requestId]) => requestId);
|
|
for (const requestId of requestIds)
|
|
this.#settlePendingRuntimeRequest(requestId);
|
|
}
|
|
|
|
#settlePendingRuntimeRequest(requestId: string): void {
|
|
const pending = this.#pendingRuntimeRequests.get(requestId);
|
|
if (!pending) return;
|
|
this.#pendingRuntimeRequests.delete(requestId);
|
|
const { request } = pending;
|
|
this.#emit(
|
|
request.input === undefined
|
|
? "runtime_request.cancelled"
|
|
: "runtime_request.expired",
|
|
request.input === undefined
|
|
? harnessRuntimeRequestOutcome(request, { reason: "session_closed" })
|
|
: harnessRuntimeInputExpiredOutcome(request, "provider_process_lost"),
|
|
{ turnId: request.turnId, itemId: request.itemId },
|
|
{ bypassTerminalTurnGate: true },
|
|
);
|
|
}
|
|
|
|
async dispatchTool(call: {
|
|
tool: string;
|
|
callId: string;
|
|
arguments: unknown;
|
|
}): Promise<unknown> {
|
|
// The authenticated MCP bridge has resolved this against its closed
|
|
// declared catalog. A second prefix strip changes legitimate operation IDs.
|
|
const tool = call.tool;
|
|
const turnId = this.#activeTurnId;
|
|
if (turnId === null)
|
|
throw new Error("OpenCode tool call is not bound to an active turn");
|
|
this.#emit(
|
|
"item.started",
|
|
{
|
|
kind: "dynamicToolCall",
|
|
item: {
|
|
type: "tool_call",
|
|
id: call.callId,
|
|
name: tool,
|
|
arguments: call.arguments,
|
|
},
|
|
},
|
|
{ turnId, itemId: call.callId },
|
|
);
|
|
if (tool === PRP_COMPLETION_TOOL_NAME || tool === PRP_BLOCK_TOOL_NAME) {
|
|
let settle: (() => void) | undefined;
|
|
try {
|
|
if (this.#closed || this.#completionSettlement)
|
|
throw new Error("A completion is already settling or the session is closed");
|
|
this.#completionSettlement = new Promise<void>(resolve => { settle = resolve; });
|
|
const completionInput = await resolveCompletionContinuation(call.arguments, this.#runId,
|
|
this.#dynamicToolHandler ? () => this.#dynamicToolHandler!({
|
|
tool: "get_task_context", callId: `${call.callId}:continuation`,
|
|
threadId: this.#providerSessionId, turnId, arguments: {},
|
|
}) : undefined);
|
|
if (this.#closed || this.#activeTurnId !== turnId)
|
|
throw new Error("The turn ended while resolving completion");
|
|
const validation = validatePrpStructuredRunResult(completionInput);
|
|
if (!validation.ok) throw new Error("Invalid semantic result");
|
|
if (
|
|
(tool === PRP_BLOCK_TOOL_NAME &&
|
|
validation.result.reportedWorkDisposition !== "blocked") ||
|
|
(tool === PRP_COMPLETION_TOOL_NAME &&
|
|
validation.result.reportedWorkDisposition === "blocked")
|
|
)
|
|
throw new Error(
|
|
"Semantic result disposition does not match the terminal tool",
|
|
);
|
|
if (
|
|
validation.result.completionClaim.contractRevision !==
|
|
this.#taskEnvelope.completionContract.revision
|
|
) {
|
|
throw new Error(
|
|
"Semantic result completion contract revision does not match",
|
|
);
|
|
}
|
|
const expectedIds = this.#taskEnvelope.completionContract.criteria.map((criterion) => criterion.id);
|
|
const receivedIds = validation.result.completionClaim.criteria.map((criterion) => criterion.criterionId);
|
|
if (receivedIds.length !== expectedIds.length || new Set(receivedIds).size !== receivedIds.length || receivedIds.some((id) => !expectedIds.includes(id))) {
|
|
// Reject at the tool boundary so the provider can repair its claim.
|
|
// Emitting a bad result here kills runnerd's strict outer validation.
|
|
throw new Error(`Semantic result criteria must contain exactly these criterionIds, once each: ${JSON.stringify(expectedIds)}. Keep contractRevision ${JSON.stringify(this.#taskEnvelope.completionContract.revision)}.`);
|
|
}
|
|
const fingerprint = canonicalJson(validation.result);
|
|
if (this.#resultFingerprint && this.#resultFingerprint !== fingerprint)
|
|
throw new Error("A different semantic result was already committed");
|
|
// Wait for the bound controller before committing or resolving the
|
|
// provider call. A rejection remains repairable in this same turn.
|
|
const feedback = this.#completionFeedback
|
|
? await this.#completionFeedback(validation.result, {
|
|
tool, callId: call.callId, threadId: this.#providerSessionId, turnId,
|
|
})
|
|
: "Semantic completion accepted.";
|
|
if (typeof feedback !== "string" || !feedback.trim())
|
|
throw new Error("Completion feedback omitted its response text");
|
|
if (this.#resultFingerprint && this.#resultFingerprint !== fingerprint)
|
|
throw new Error("A different semantic result was already committed");
|
|
if (!this.#resultFingerprint) {
|
|
this.#result = structuredClone(validation.result);
|
|
this.#resultFingerprint = fingerprint;
|
|
this.#resultCallId = call.callId;
|
|
this.#resultTurnId = turnId;
|
|
this.#semanticResultTextBoundary = this.#completedTextParts.length;
|
|
this.#emit("run.result.proposed", validation.result, {
|
|
turnId,
|
|
itemId: call.callId,
|
|
});
|
|
}
|
|
this.#emit(
|
|
"item.completed",
|
|
{
|
|
kind: "dynamicToolCall",
|
|
item: {
|
|
type: "tool_result",
|
|
id: call.callId,
|
|
tool_use_id: call.callId,
|
|
result: feedback,
|
|
},
|
|
},
|
|
{ turnId, itemId: call.callId },
|
|
);
|
|
return { accepted: true, feedback };
|
|
} catch (error) {
|
|
// A rejected semantic call still completes its tool activity item.
|
|
// Otherwise a later question can appear to have an in-flight tool.
|
|
this.#emit("item.completed", {
|
|
kind: "dynamicToolCall",
|
|
item: { type: "tool_result", id: call.callId, tool_use_id: call.callId,
|
|
is_error: true, error: error instanceof Error ? error.message : String(error) },
|
|
}, { turnId, itemId: call.callId });
|
|
throw error;
|
|
} finally {
|
|
if (settle) {
|
|
this.#completionSettlement = null;
|
|
settle();
|
|
}
|
|
}
|
|
}
|
|
if (!this.#dynamicToolHandler)
|
|
throw new Error("Unsupported Paperclip operation");
|
|
try {
|
|
const result = await this.#dynamicToolHandler({
|
|
tool,
|
|
callId: call.callId,
|
|
threadId: this.#providerSessionId,
|
|
turnId,
|
|
arguments: call.arguments,
|
|
});
|
|
this.#emit(
|
|
"item.completed",
|
|
{
|
|
kind: "dynamicToolCall",
|
|
item: {
|
|
type: "tool_result",
|
|
id: call.callId,
|
|
tool_use_id: call.callId,
|
|
result,
|
|
},
|
|
},
|
|
{ turnId, itemId: call.callId },
|
|
);
|
|
return result;
|
|
} catch (error) {
|
|
this.#emit(
|
|
"item.completed",
|
|
{
|
|
kind: "dynamicToolCall",
|
|
item: {
|
|
type: "tool_result",
|
|
id: call.callId,
|
|
tool_use_id: call.callId,
|
|
error: redact(String(error)),
|
|
is_error: true,
|
|
},
|
|
},
|
|
{ turnId, itemId: call.callId },
|
|
);
|
|
throw error;
|
|
}
|
|
}
|
|
|
|
async #recoverPendingRuntimeRequests(): Promise<void> {
|
|
await this.#recoverPendingQuestions();
|
|
const value = await api(
|
|
this.#fetch,
|
|
this.#runtime,
|
|
`/permission?directory=${encodeURIComponent(this.#workingDirectory)}`,
|
|
);
|
|
const pending = Array.isArray(value)
|
|
? value
|
|
: Array.isArray(record(value).permissions)
|
|
? (record(value).permissions as unknown[])
|
|
: [];
|
|
for (const entry of pending)
|
|
this.#acceptPermission(record(entry), "permission.recovered");
|
|
}
|
|
|
|
async #recoverPendingQuestions(): Promise<void> {
|
|
const value = await api(
|
|
this.#fetch,
|
|
this.#runtime,
|
|
`/question?directory=${encodeURIComponent(this.#workingDirectory)}`,
|
|
);
|
|
const pending = Array.isArray(value)
|
|
? value
|
|
: Array.isArray(record(value).questions)
|
|
? (record(value).questions as unknown[])
|
|
: [];
|
|
for (const entry of pending) {
|
|
const question = record(entry);
|
|
const sessionId = text(question.sessionID, text(question.sessionId));
|
|
if (sessionId && sessionId !== this.#providerSessionId) continue;
|
|
this.#acceptQuestion(question);
|
|
}
|
|
}
|
|
|
|
#acceptQuestion(properties: Record<string, unknown>): void {
|
|
const turnId = this.#activeTurnId;
|
|
if (!turnId) return;
|
|
const requestId = text(
|
|
properties.id,
|
|
text(properties.requestID, text(properties.requestId)),
|
|
);
|
|
const nativeQuestions = Array.isArray(properties.questions)
|
|
? properties.questions.map(record).slice(0, 64)
|
|
: [];
|
|
if (!requestId || nativeQuestions.length === 0) {
|
|
this.#emit(
|
|
"harness.diagnostic",
|
|
{
|
|
code: "runtime_input_rejected",
|
|
adapter: "opencode-server",
|
|
reason:
|
|
"OpenCode emitted a question event without a request id or supported questions.",
|
|
},
|
|
{ turnId, ...(requestId ? { itemId: requestId } : {}) },
|
|
);
|
|
return;
|
|
}
|
|
if (this.#pendingRuntimeRequests.has(requestId)) return;
|
|
let input: PaperclipQuestionSet;
|
|
try {
|
|
input = normalizeOpenCodeQuestionSet(nativeQuestions, properties);
|
|
} catch {
|
|
this.#emit(
|
|
"harness.diagnostic",
|
|
{
|
|
code: "runtime_input_rejected",
|
|
adapter: "opencode-server",
|
|
reason: "OpenCode emitted a malformed or ambiguous question set.",
|
|
},
|
|
{ turnId, itemId: requestId },
|
|
);
|
|
return;
|
|
}
|
|
const request: HarnessRuntimeRequest = {
|
|
requestId,
|
|
requestKind: "user_input",
|
|
method: "question.asked",
|
|
turnId,
|
|
itemId: requestId,
|
|
status: "pending",
|
|
prompt: "OpenCode requests user input.",
|
|
details: {},
|
|
input,
|
|
origin: {
|
|
adapter: "opencode-server",
|
|
provider: "opencode",
|
|
method: "question.asked",
|
|
},
|
|
};
|
|
this.#pendingRuntimeRequests.set(requestId, { request, nativeQuestions });
|
|
this.#emit(
|
|
"runtime_request.created",
|
|
{
|
|
request: {
|
|
schema: PAPERCLIP_RUNTIME_REQUEST_SCHEMA_V2,
|
|
requestKind: "runtime",
|
|
requestId,
|
|
type: "input",
|
|
status: "pending",
|
|
prompt: request.prompt,
|
|
input,
|
|
origin: request.origin,
|
|
turnId,
|
|
itemId: request.itemId,
|
|
},
|
|
},
|
|
{ turnId, itemId: request.itemId },
|
|
);
|
|
}
|
|
|
|
#acceptPermission(properties: Record<string, unknown>, method: string): void {
|
|
const turnId = this.#activeTurnId;
|
|
if (!turnId) return;
|
|
const permission = isRecord(properties.permission)
|
|
? properties.permission
|
|
: isRecord(properties.request)
|
|
? properties.request
|
|
: properties;
|
|
const requestId = text(
|
|
permission.id,
|
|
text(
|
|
permission.requestID,
|
|
text(permission.requestId, text(permission.permissionID)),
|
|
),
|
|
);
|
|
if (!requestId || this.#pendingRuntimeRequests.has(requestId)) return;
|
|
const title = text(
|
|
permission.title,
|
|
text(permission.permission, text(permission.tool, "requested operation")),
|
|
);
|
|
const request: HarnessRuntimeRequest = {
|
|
requestId,
|
|
requestKind: "permission_approval",
|
|
method,
|
|
turnId,
|
|
itemId: requestId,
|
|
status: "pending",
|
|
prompt: `OpenCode requests permission for ${title}.`.slice(0, 4000),
|
|
details: bounded(permission),
|
|
origin: { adapter: "opencode-server", provider: "opencode", method },
|
|
};
|
|
this.#pendingRuntimeRequests.set(requestId, {
|
|
request,
|
|
nativeQuestions: [],
|
|
});
|
|
this.#emit(
|
|
"runtime_request.created",
|
|
{
|
|
request: {
|
|
schema: PAPERCLIP_RUNTIME_REQUEST_SCHEMA_V2,
|
|
requestKind: "runtime",
|
|
requestId,
|
|
type: "permission",
|
|
status: "pending",
|
|
prompt: request.prompt,
|
|
actions: ["accept", "accept_for_session", "decline", "cancel"],
|
|
details: request.details,
|
|
origin: request.origin,
|
|
turnId,
|
|
itemId: request.itemId,
|
|
},
|
|
},
|
|
{ turnId, itemId: request.itemId },
|
|
);
|
|
}
|
|
|
|
async #pumpEvents(): Promise<void> {
|
|
let attempts = 0;
|
|
while (!this.#closed && !this.#abort.signal.aborted) {
|
|
try {
|
|
const response = await this.#fetch(`${this.#runtime.baseUrl}/event`, {
|
|
headers: {
|
|
Authorization: this.#runtime.authHeader,
|
|
Accept: "text/event-stream",
|
|
},
|
|
signal: this.#abort.signal,
|
|
});
|
|
if (!response.ok || !response.body)
|
|
throw Object.assign(
|
|
new Error(`OpenCode event stream returned HTTP ${response.status}`),
|
|
{ httpStatus: response.status },
|
|
);
|
|
const outboundFrameId = this.#runtime.trace?.frame({
|
|
direction: "client_to_provider",
|
|
raw: "",
|
|
transport: "http_sse",
|
|
nativeMethod: "GET /event",
|
|
});
|
|
if (outboundFrameId) {
|
|
this.#runtime.trace?.interpretation({
|
|
frameId: outboundFrameId,
|
|
stage: "typescript_opencode_http_transport",
|
|
ruleId: "opencode.http.GET_event",
|
|
disposition: "operator_only",
|
|
reason: "Opened the OpenCode server-sent event stream",
|
|
});
|
|
}
|
|
for await (const frame of parseOpenCodeSseFrames(response.body)) {
|
|
if (this.#closed) return;
|
|
const compaction = frame.compaction;
|
|
if (compaction?.omitted) {
|
|
// Even the compacted structure exceeded its bound. Report the
|
|
// frame instead of ending the stream or dropping it silently.
|
|
this.#emit("harness.diagnostic", {
|
|
code: "opencode_sse_event_omitted",
|
|
message: `OpenCode sent a ${compaction.frameChars}-character event that could not be retained within the payload bound.`,
|
|
providerEventType: compaction.eventType,
|
|
frameChars: compaction.frameChars,
|
|
});
|
|
continue;
|
|
}
|
|
if (compaction && !this.#reportedSseCompaction) {
|
|
this.#reportedSseCompaction = true;
|
|
this.#emit("harness.diagnostic", {
|
|
code: "opencode_sse_event_compacted",
|
|
message: `OpenCode sent a ${compaction.frameChars}-character event. Long strings were shortened to keep the event within the payload bound.`,
|
|
providerEventType: compaction.eventType,
|
|
frameChars: compaction.frameChars,
|
|
truncatedStrings: compaction.truncatedStrings,
|
|
omittedChars: compaction.omittedChars,
|
|
});
|
|
}
|
|
const frameId =
|
|
this.#runtime.trace?.frame({
|
|
direction: "provider_to_client",
|
|
raw: frame.raw,
|
|
transport: "http_sse",
|
|
nativeMethod: "SSE /event",
|
|
}) ?? null;
|
|
let event: unknown;
|
|
try {
|
|
event = JSON.parse(frame.data);
|
|
if (compaction) annotateOmittedProviderText(event, compaction);
|
|
if (frameId) {
|
|
this.#runtime.trace?.interpretation({
|
|
frameId,
|
|
stage: "typescript_opencode_sse_parse",
|
|
ruleId: compaction ? "opencode.sse.compacted_json" : "opencode.sse.json",
|
|
disposition: "mapped",
|
|
fieldMappings: [
|
|
{
|
|
inputPath: "$raw.data",
|
|
outputPath: "$providerEvent",
|
|
action: "normalized",
|
|
reason: compaction
|
|
? "Decoded the compacted SSE data payload as an OpenCode event"
|
|
: "Decoded the exact SSE data payload as an OpenCode event",
|
|
},
|
|
],
|
|
reason: compaction
|
|
? `OpenCode SSE frame of ${compaction.frameChars} characters parsed as JSON after ${compaction.truncatedStrings} long strings were shortened (${compaction.omittedChars} characters omitted)`
|
|
: "OpenCode SSE frame parsed as JSON",
|
|
});
|
|
}
|
|
} catch (error) {
|
|
if (frameId) {
|
|
this.#runtime.trace?.interpretation({
|
|
frameId,
|
|
stage: "typescript_opencode_sse_parse",
|
|
ruleId: "opencode.sse.invalid_json",
|
|
disposition: "rejected",
|
|
reason: `OpenCode SSE data was not valid JSON: ${String(error).slice(0, 400)}`,
|
|
});
|
|
}
|
|
throw error;
|
|
}
|
|
const type = text(record(event).type);
|
|
const properties = record(record(event).properties);
|
|
if (type === "session.idle" || type === "session.error"
|
|
|| (type === "session.status" && text(record(record(event).properties).status && record(record(record(event).properties).status).type) === "idle")) {
|
|
// Do not seal the turn while its bound controller is deciding a
|
|
// finishing call. Acceptance/rejection and the tool result must
|
|
// precede the provider's terminal event.
|
|
await this.#completionSettlement;
|
|
if (this.#closed) return;
|
|
}
|
|
this.#mapProviderEvent(event, frameId);
|
|
}
|
|
throw Object.assign(
|
|
new Error("OpenCode event stream closed before the session became terminal"),
|
|
{ streamClosed: true },
|
|
);
|
|
} catch (error) {
|
|
if (this.#closed || this.#abort.signal.aborted) return;
|
|
attempts += 1;
|
|
if (attempts > 3) {
|
|
await this.#completionSettlement;
|
|
if (this.#closed) return;
|
|
const failure = await openCodeEventStreamFailure(error, this.#runtime.process);
|
|
if (this.#closed) return;
|
|
this.#emit("harness.diagnostic", {
|
|
code: "opencode_sse_failed",
|
|
message: redact(String(error), this.#runtime.sensitiveValues),
|
|
failure,
|
|
});
|
|
this.#failActiveTurnOnStreamLoss(failure);
|
|
this.#events.fail(error);
|
|
return;
|
|
}
|
|
await new Promise((resolve) => setTimeout(resolve, 50 * attempts));
|
|
}
|
|
}
|
|
}
|
|
|
|
/**
|
|
* The event stream is the only path for this turn's terminal event. Once it
|
|
* is gone the turn cannot finish, so record why before the stream ends
|
|
* instead of leaving runnerd to close it later with no cause.
|
|
*/
|
|
#failActiveTurnOnStreamLoss(failure: OpenCodeEventStreamFailure): void {
|
|
const turnId = this.#activeTurnId;
|
|
if (!turnId || this.#terminalTurns.has(turnId)) return;
|
|
this.#settlePendingRuntimeRequestsForTurn(turnId);
|
|
this.#emit(
|
|
"turn.failed",
|
|
{
|
|
status: "failed",
|
|
providerTerminalObserved: false,
|
|
error: {
|
|
code: failure.kind === "server_exited" ? "opencode_server_exited" : "opencode_event_stream_lost",
|
|
message: failure.kind === "server_exited"
|
|
? "OpenCode stopped while the turn was running."
|
|
: "The OpenCode event stream failed while the turn was running.",
|
|
opencodeFailure: failure,
|
|
},
|
|
},
|
|
{ turnId },
|
|
);
|
|
this.#terminalTurns.set(turnId, canonicalJson({ status: "failed" }));
|
|
this.#activeTurnId = null;
|
|
}
|
|
|
|
#mapProviderEvent(value: unknown, traceFrameId: number | null = null): void {
|
|
this.#activeTraceFrameId = traceFrameId;
|
|
this.#activeTraceEmittedEventIds = [];
|
|
let rejected: unknown = null;
|
|
try {
|
|
this.#mapProviderEventValue(value);
|
|
} catch (error) {
|
|
rejected = error;
|
|
throw error;
|
|
} finally {
|
|
if (traceFrameId) {
|
|
const providerType = text(record(value).type, "unknown");
|
|
this.#runtime.trace?.interpretation({
|
|
frameId: traceFrameId,
|
|
stage: "typescript_opencode_driver_normalization",
|
|
ruleId: `opencode.normalize.${providerType.replace(/[^A-Za-z0-9_.-]/g, "_")}`,
|
|
disposition: rejected
|
|
? "rejected"
|
|
: this.#activeTraceEmittedEventIds.length > 0
|
|
? "mapped"
|
|
: "ignored",
|
|
emittedEventIds: [...this.#activeTraceEmittedEventIds],
|
|
fieldMappings:
|
|
this.#activeTraceEmittedEventIds.length > 0
|
|
? [
|
|
{
|
|
inputPath: "properties",
|
|
outputPath: "prpEvent.payload",
|
|
action: "normalized",
|
|
reason:
|
|
"Mapped OpenCode event fields into canonical PRP payloads",
|
|
},
|
|
]
|
|
: [],
|
|
reason: rejected
|
|
? `OpenCode event normalization failed: ${String(rejected).slice(0, 400)}`
|
|
: this.#activeTraceEmittedEventIds.length > 0
|
|
? "OpenCode event emitted one or more canonical PRP events"
|
|
: "OpenCode event was observed but produced no canonical PRP event",
|
|
});
|
|
}
|
|
this.#activeTraceFrameId = null;
|
|
this.#activeTraceEmittedEventIds = [];
|
|
}
|
|
}
|
|
|
|
#mapProviderEventValue(value: unknown): void {
|
|
const event = record(value);
|
|
const properties = record(event.properties);
|
|
const type = text(event.type);
|
|
// Id-less deltas are additive: two identical chunks can be legitimate
|
|
// adjacent tokens. Content deduplication would silently lose the second.
|
|
// Key id-less events by digest: a retained canonical copy of each recent
|
|
// event would hold up to 10,000 large tool payloads in memory.
|
|
const eventId = text(event.id) || (type === "message.part.delta"
|
|
? null
|
|
: `sha256:${createHash("sha256").update(canonicalJson(value)).digest("hex")}`);
|
|
if (eventId !== null && this.#seenProviderEvents.has(eventId)) return;
|
|
if (eventId !== null) this.#seenProviderEvents.add(eventId);
|
|
if (this.#seenProviderEvents.size > 10_000)
|
|
this.#seenProviderEvents.delete(
|
|
this.#seenProviderEvents.values().next().value!,
|
|
);
|
|
const sessionId = text(
|
|
properties.sessionID,
|
|
text(record(properties.info).sessionID),
|
|
);
|
|
if (sessionId && sessionId !== this.#providerSessionId) return;
|
|
const turnId = this.#activeTurnId;
|
|
if (type === "question.asked" && turnId) {
|
|
this.#acceptQuestion(properties);
|
|
return;
|
|
}
|
|
if (
|
|
(type === "permission.updated" ||
|
|
type === "permission.asked" ||
|
|
type === "permission.v2.asked") &&
|
|
turnId
|
|
) {
|
|
this.#acceptPermission(properties, type);
|
|
return;
|
|
}
|
|
if (
|
|
(type === "permission.replied" || type === "permission.v2.replied") &&
|
|
turnId
|
|
) {
|
|
const permission = isRecord(properties.permission)
|
|
? properties.permission
|
|
: isRecord(properties.request)
|
|
? properties.request
|
|
: properties;
|
|
const requestId = text(
|
|
permission.id,
|
|
text(
|
|
permission.requestID,
|
|
text(permission.requestId, text(permission.permissionID)),
|
|
),
|
|
);
|
|
const pending = this.#pendingRuntimeRequests.get(requestId);
|
|
if (!pending || pending.request.requestKind !== "permission_approval")
|
|
return;
|
|
this.#pendingRuntimeRequests.delete(requestId);
|
|
const nativeReply = text(
|
|
properties.reply,
|
|
text(
|
|
properties.response,
|
|
text(permission.reply, text(permission.response)),
|
|
),
|
|
);
|
|
const action =
|
|
pending.submittedAction ??
|
|
(nativeReply === "always" || nativeReply === "always_allow"
|
|
? "accept_for_session"
|
|
: nativeReply === "once" || nativeReply === "allow"
|
|
? "accept"
|
|
: "decline");
|
|
this.#emit(
|
|
"runtime_request.resolved",
|
|
harnessRuntimeRequestOutcome(pending.request, { action }),
|
|
{
|
|
turnId: pending.request.turnId,
|
|
itemId: pending.request.itemId,
|
|
},
|
|
);
|
|
return;
|
|
}
|
|
if (
|
|
(type === "question.replied" || type === "question.rejected") &&
|
|
turnId
|
|
) {
|
|
const requestId = text(
|
|
properties.id,
|
|
text(properties.requestID, text(properties.requestId)),
|
|
);
|
|
const pending = this.#pendingRuntimeRequests.get(requestId);
|
|
if (!pending) return;
|
|
this.#pendingRuntimeRequests.delete(requestId);
|
|
this.#emit(
|
|
type === "question.replied"
|
|
? "runtime_request.resolved"
|
|
: "runtime_request.cancelled",
|
|
harnessRuntimeRequestOutcome(
|
|
pending.request,
|
|
type === "question.replied"
|
|
? { action: "submit", response: pending.submittedResponse }
|
|
: { reason: "provider_rejected" },
|
|
),
|
|
{ turnId: pending.request.turnId, itemId: pending.request.itemId },
|
|
);
|
|
return;
|
|
}
|
|
if (type === "message.part.updated" || type === "message.part.delta") {
|
|
let part = record(properties.part);
|
|
if (type === "message.part.delta") {
|
|
const previous = this.#streamingParts.get(text(properties.partID));
|
|
// A delta has no role or part type. Only stream text for an observed
|
|
// part with matching message identity; never infer assistant identity.
|
|
if (!previous || properties.field !== "text" || typeof properties.delta !== "string"
|
|
|| text(previous.messageID, text(previous.messageId)) !== text(properties.messageID)) return;
|
|
part = { ...previous, text: text(previous.text) + properties.delta };
|
|
}
|
|
const messageId = text(part.messageID, text(part.messageId));
|
|
if (!messageId) return;
|
|
// Resolve the turn this message actually belongs to, not whichever
|
|
// turn is active right now. A straggling part for an earlier message
|
|
// must stay attributed to the turn that created that message.
|
|
const owningTurnId = this.#messageTurnIds.get(messageId) ?? turnId;
|
|
if (!owningTurnId) return;
|
|
if (owningTurnId === turnId && text(part.id) && ["text", "reasoning"].includes(text(part.type))) {
|
|
this.#streamingParts.set(text(part.id), part);
|
|
}
|
|
const role = this.#messageRoles.get(messageId);
|
|
if (role === "assistant") this.#emitAssistantPart(part, owningTurnId);
|
|
else if (role === undefined) {
|
|
const pending = this.#pendingMessageParts.get(messageId) ?? [];
|
|
// Text deltas are cumulative by this point. Keep the newest snapshot
|
|
// (including completion metadata), not the first 100 token chunks.
|
|
const previousIndex = ["text", "reasoning"].includes(text(part.type)) && text(part.id)
|
|
? pending.findIndex(candidate => candidate.id === part.id && candidate.type === part.type)
|
|
: -1;
|
|
if (previousIndex >= 0) pending[previousIndex] = part;
|
|
else if (pending.length < 100) pending.push(part);
|
|
this.#pendingMessageParts.set(messageId, pending);
|
|
}
|
|
return;
|
|
}
|
|
if (type === "message.updated") {
|
|
const info = record(properties.info);
|
|
const messageId = text(
|
|
info.id,
|
|
text(info.messageID, text(info.messageId)),
|
|
);
|
|
const role = text(info.role);
|
|
// Record the message's owning turn at the moment OpenCode first
|
|
// reports it. A later turn that reuses the same native message id
|
|
// legitimately reclaims ownership; a stale message never sees this
|
|
// branch again, so its recorded owner never changes.
|
|
if (messageId && role && turnId) this.#messageTurnIds.set(messageId, turnId);
|
|
const owningTurnId = messageId
|
|
? (this.#messageTurnIds.get(messageId) ?? turnId)
|
|
: turnId;
|
|
if (!owningTurnId) return;
|
|
if (messageId && role) {
|
|
this.#messageRoles.set(messageId, role);
|
|
const pending = this.#pendingMessageParts.get(messageId) ?? [];
|
|
this.#pendingMessageParts.delete(messageId);
|
|
if (role === "assistant")
|
|
for (const part of pending)
|
|
this.#emitAssistantPart(part, owningTurnId);
|
|
}
|
|
const tokens = record(info.tokens);
|
|
if (
|
|
role === "assistant" &&
|
|
(Object.keys(tokens).length > 0 || typeof info.cost === "number")
|
|
) {
|
|
this.#usage = bounded({
|
|
...tokens,
|
|
costUsd: info.cost ?? null,
|
|
model: this.#model,
|
|
provider: this.#model.split("/", 1)[0],
|
|
driverVersion: this.#runtime.version,
|
|
});
|
|
const usageFingerprint = canonicalJson(this.#usage);
|
|
const hasMeaningfulUsage =
|
|
hasPositiveNumber(tokens) ||
|
|
(typeof info.cost === "number" && info.cost > 0);
|
|
if (
|
|
hasMeaningfulUsage &&
|
|
this.#messageUsageFingerprints.get(messageId) !== usageFingerprint
|
|
) {
|
|
this.#messageUsageFingerprints.set(messageId, usageFingerprint);
|
|
this.#emit(
|
|
"item.completed",
|
|
{ kind: "usage", usage: this.#usage, usageMessageId: messageId },
|
|
{ turnId: owningTurnId, itemId: `${owningTurnId}:usage` },
|
|
);
|
|
}
|
|
}
|
|
return;
|
|
}
|
|
if (
|
|
(type === "session.idle" ||
|
|
(type === "session.status" &&
|
|
text(record(properties.status).type) === "idle")) &&
|
|
turnId
|
|
) {
|
|
const fingerprint = canonicalJson({
|
|
status: "completed",
|
|
semanticResult: this.#resultFingerprint,
|
|
});
|
|
this.#terminalTurns.set(turnId, fingerprint);
|
|
this.#emitSettledFinalAgentMessage(turnId);
|
|
const workspace = this.#workspaceChangesByTurn.get(turnId);
|
|
if (workspace !== undefined)
|
|
this.#emit(
|
|
"workspace.diff.recorded",
|
|
{ ...workspace, complete: true },
|
|
{ turnId, itemId: `${turnId}:workspace` },
|
|
);
|
|
// Settle any request this turn never answered before the terminal
|
|
// event, so a consumer that stops reading at that terminal event still
|
|
// observes the settlement.
|
|
this.#settlePendingRuntimeRequestsForTurn(turnId);
|
|
// Emit while this turn is still `#activeTurnId`; the gate in `#emit`
|
|
// drops any frame whose turnId is not the active turn, so nulling it
|
|
// first would make `#emit` drop this very event.
|
|
this.#emit("turn.completed", { status: "completed" }, { turnId });
|
|
this.#activeTurnId = null;
|
|
return;
|
|
}
|
|
if (type === "session.error" && turnId) {
|
|
const providerError = record(properties.error);
|
|
const providerErrorData = record(providerError.data);
|
|
if (
|
|
text(providerError.name) === "MessageAbortedError" &&
|
|
text(providerErrorData.message, text(providerError.message)) ===
|
|
"Aborted"
|
|
) {
|
|
// OpenCode reports its normal /abort control path as session.error. That
|
|
// endpoint is also how Paperclip parks a provider turn after a durable
|
|
// governed interaction is created, so presenting it as a provider
|
|
// failure produces a false red error immediately above a healthy wait
|
|
// card. Preserve the provider fact as a cancelled terminal event; the
|
|
// native session loop independently commits the authoritative yielded
|
|
// result when this abort followed a governed wait.
|
|
// Settle any request this turn never answered before the terminal
|
|
// event, so a consumer that stops reading at that terminal event
|
|
// still observes the settlement.
|
|
this.#settlePendingRuntimeRequestsForTurn(turnId);
|
|
this.#emit(
|
|
"turn.cancelled",
|
|
{
|
|
status: "cancelled",
|
|
error: bounded(properties.error ?? properties),
|
|
},
|
|
{ turnId },
|
|
);
|
|
this.#terminalTurns.set(turnId, canonicalJson({ status: "cancelled" }));
|
|
this.#activeTurnId = null;
|
|
return;
|
|
}
|
|
this.#emit(
|
|
"provider.notice.recorded",
|
|
{
|
|
schema: "paperclip.provider.notice.v1",
|
|
noticeId: `${turnId}:session-error`,
|
|
severity: "error",
|
|
category: "session_error",
|
|
scope: "turn",
|
|
recoverable: false,
|
|
userActionable: true,
|
|
summary: redact(
|
|
text(record(properties.error).message, "OpenCode session failed."),
|
|
this.#runtime.sensitiveValues,
|
|
).slice(0, 4000),
|
|
},
|
|
{ turnId, itemId: `${turnId}:session-error` },
|
|
);
|
|
// Settle any request this turn never answered before the terminal
|
|
// event, so a consumer that stops reading at that terminal event still
|
|
// observes the settlement.
|
|
this.#settlePendingRuntimeRequestsForTurn(turnId);
|
|
this.#emit(
|
|
"turn.failed",
|
|
{ status: "failed", error: bounded(properties.error ?? properties) },
|
|
{ turnId },
|
|
);
|
|
this.#terminalTurns.set(turnId, canonicalJson({ status: "failed" }));
|
|
this.#activeTurnId = null;
|
|
}
|
|
}
|
|
|
|
#emitAssistantPart(part: Record<string, unknown>, turnId: string): void {
|
|
const partId = text(part.id, `${turnId}:part`);
|
|
const partType = text(part.type, "unknown");
|
|
const messageId = text(part.messageID, text(part.messageId)) || null;
|
|
const canonicalToolName = canonicalOpenCodeMcpToolName(
|
|
canonicalOpenCodeDisplayToolName(
|
|
text(part.tool, text(part.name)),
|
|
text(part.callID, text(part.callId)),
|
|
),
|
|
);
|
|
if (
|
|
["tool", "tool-call", "tool_call"].includes(partType) &&
|
|
[PRP_COMPLETION_TOOL_NAME, PRP_BLOCK_TOOL_NAME].includes(
|
|
canonicalToolName as typeof PRP_COMPLETION_TOOL_NAME,
|
|
) &&
|
|
messageId
|
|
) {
|
|
// OpenCode may report the terminal MCP call before it marks the text
|
|
// part from the same assistant message complete. Correlating by native
|
|
// message identity selects that response while excluding both earlier
|
|
// commentary messages and later acknowledgement-only messages.
|
|
this.#semanticResultProviderMessageId = messageId;
|
|
}
|
|
for (const canonical of canonicalProviderEventsFromOpenCodePart(part)) {
|
|
this.#emit(canonical.eventType, canonical.payload, {
|
|
turnId,
|
|
itemId: canonical.itemId,
|
|
});
|
|
}
|
|
if (
|
|
["tool", "tool-call", "tool_call"].includes(partType) &&
|
|
![PRP_COMPLETION_TOOL_NAME, PRP_BLOCK_TOOL_NAME].includes(
|
|
canonicalToolName as typeof PRP_COMPLETION_TOOL_NAME,
|
|
)
|
|
) {
|
|
this.#lastNonTerminalToolSourceSeq = this.#sourceSequence;
|
|
}
|
|
if (partType === "patch") {
|
|
const paths = Array.isArray(part.files) ? part.files : [];
|
|
const files = paths
|
|
.slice(0, 2_000)
|
|
.flatMap((value): Record<string, unknown>[] => {
|
|
const path = text(value).replaceAll("\\", "/");
|
|
if (!path || path.startsWith("/") || path.split("/").includes(".."))
|
|
return [];
|
|
return [
|
|
{
|
|
path,
|
|
operation: "modify",
|
|
previousPath: null,
|
|
additions: null,
|
|
deletions: null,
|
|
binary: false,
|
|
diff: null,
|
|
},
|
|
];
|
|
});
|
|
if (files.length > 0) {
|
|
const previous = this.#workspaceChangesByTurn.get(turnId);
|
|
const payload = {
|
|
schema: "paperclip.workspace.diff.v1",
|
|
changeSetId: `${turnId}:workspace`,
|
|
revision: Number(record(previous).revision ?? 0) + 1,
|
|
source: "harness_reported",
|
|
complete: false,
|
|
files,
|
|
totals: { files: files.length, additions: null, deletions: null },
|
|
patchArtifactRef: null,
|
|
};
|
|
this.#workspaceChangesByTurn.set(turnId, payload);
|
|
this.#emit("workspace.change.updated", payload, {
|
|
turnId,
|
|
itemId: `${turnId}:workspace`,
|
|
});
|
|
}
|
|
}
|
|
const content = text(part.text, text(part.output));
|
|
const previous = this.#partText.get(partId) ?? "";
|
|
this.#partText.set(partId, content);
|
|
if (partType === "text" && content.length > 0) {
|
|
for (const reference of paperclipWorkspaceFileReferencesFromText(
|
|
this.#workingDirectory,
|
|
content,
|
|
turnId,
|
|
)) {
|
|
if (this.#emittedFileReferences.has(reference.referenceId)) continue;
|
|
this.#emittedFileReferences.add(reference.referenceId);
|
|
this.#emit(
|
|
"workspace.file.referenced",
|
|
{ ...reference },
|
|
{ turnId, itemId: reference.referenceId },
|
|
);
|
|
}
|
|
}
|
|
const delta = content.startsWith(previous)
|
|
? content.slice(previous.length)
|
|
: content;
|
|
if (delta) {
|
|
// OpenCode calls assistant prose a `text` part, but `text` is not a PRP
|
|
// item identity and is consequently ignored by the task projection.
|
|
// Until settlement selects one completed part as the final response,
|
|
// every assistant text update is canonical progress/commentary.
|
|
const assistantDelta = partType === "text";
|
|
const reasoningDelta = partType === "reasoning";
|
|
this.#emit(
|
|
"item.delta",
|
|
{
|
|
kind: assistantDelta
|
|
? "agentMessage"
|
|
: reasoningDelta
|
|
? "reasoning"
|
|
: partType,
|
|
...(assistantDelta
|
|
? { channel: "progress", providerPhase: "commentary" }
|
|
: reasoningDelta
|
|
? { channel: "detail", providerPhase: "reasoning" }
|
|
: {}),
|
|
text: delta,
|
|
item: bounded(
|
|
assistantDelta
|
|
? {
|
|
...part,
|
|
type: "agentMessage",
|
|
channel: "progress",
|
|
phase: "commentary",
|
|
text: delta,
|
|
}
|
|
: reasoningDelta
|
|
? {
|
|
...part,
|
|
type: "reasoning",
|
|
channel: "detail",
|
|
phase: "reasoning",
|
|
text: delta,
|
|
}
|
|
: part,
|
|
),
|
|
},
|
|
{ turnId, itemId: partId },
|
|
);
|
|
}
|
|
const completedAt = record(part.time).end;
|
|
if (
|
|
partType === "reasoning" &&
|
|
content.trim().length > 0 &&
|
|
Number.isFinite(completedAt) &&
|
|
!this.#completedReasoningPartIds.has(partId)
|
|
) {
|
|
this.#completedReasoningPartIds.add(partId);
|
|
this.#emit(
|
|
"item.completed",
|
|
{
|
|
kind: "reasoning",
|
|
channel: "detail",
|
|
providerPhase: "reasoning",
|
|
text: content,
|
|
item: bounded({
|
|
...part,
|
|
type: "reasoning",
|
|
channel: "detail",
|
|
phase: "reasoning",
|
|
text: content,
|
|
}),
|
|
},
|
|
{ turnId, itemId: partId },
|
|
);
|
|
}
|
|
if (
|
|
partType === "text" &&
|
|
content.trim().length > 0 &&
|
|
Number.isFinite(completedAt) &&
|
|
!this.#completedTextPartIds.has(partId)
|
|
) {
|
|
this.#completedTextPartIds.add(partId);
|
|
this.#completedTextParts.push({
|
|
partId,
|
|
messageId,
|
|
text: content,
|
|
item: bounded({
|
|
...part,
|
|
type: "agentMessage",
|
|
phase: "final_answer",
|
|
text: content,
|
|
}),
|
|
observedSourceSeq: this.#sourceSequence,
|
|
});
|
|
}
|
|
}
|
|
|
|
#emitSettledFinalAgentMessage(turnId: string): void {
|
|
// OpenCode labels every assistant text part as plain `text`; unlike Codex,
|
|
// it does not provide commentary/final-answer channels. A single native
|
|
// assistant message can therefore contain an opening progress note, many
|
|
// work tools, and the terminal MCP call. Do not promote that opening note
|
|
// into the settled response merely because it shares the terminal call's
|
|
// message id. Only text observed after the last non-terminal work tool can
|
|
// be a final response. When no such text exists, emit no final agentMessage
|
|
// and let the accepted semantic summary resolve the durable reply.
|
|
const afterLastWorkTool = (part: { observedSourceSeq: number }) =>
|
|
part.observedSourceSeq > this.#lastNonTerminalToolSourceSeq;
|
|
const eligibleText = this.#completedTextParts.filter(afterLastWorkTool);
|
|
// OpenCode exposes no prose channel, so final selection must use provider
|
|
// structure rather than text length or content. When OpenCode reports the
|
|
// terminal tool part, prefer prose completed afterward in that exact
|
|
// provider message. If that message contains only pre-tool commentary,
|
|
// the first later assistant message is the compatible terminal response.
|
|
// Without a reported tool-message identity, a completed pre-tool message
|
|
// is more authoritative than a later acknowledgement; otherwise the first
|
|
// post-tool message is the only available compatibility fallback.
|
|
const indexed = eligibleText.map((part) => ({
|
|
part,
|
|
index: this.#completedTextParts.indexOf(part),
|
|
}));
|
|
const boundary = this.#semanticResultTextBoundary;
|
|
const beforeResult = indexed.filter(
|
|
({ index }) => boundary !== null && index < boundary,
|
|
);
|
|
const afterResult = indexed.filter(
|
|
({ index }) => boundary === null || index >= boundary,
|
|
);
|
|
const correlatedAfterResult =
|
|
this.#semanticResultProviderMessageId === null
|
|
? []
|
|
: afterResult.filter(
|
|
({ part }) =>
|
|
part.messageId === this.#semanticResultProviderMessageId,
|
|
);
|
|
const uncorrelatedAfterResult =
|
|
this.#semanticResultProviderMessageId === null
|
|
? afterResult
|
|
: afterResult.filter(
|
|
({ part }) =>
|
|
part.messageId !== this.#semanticResultProviderMessageId,
|
|
);
|
|
const selected =
|
|
correlatedAfterResult.at(-1)?.part ??
|
|
(this.#semanticResultProviderMessageId === null
|
|
? beforeResult.at(-1)?.part
|
|
: uncorrelatedAfterResult[0]?.part) ??
|
|
beforeResult.at(-1)?.part ??
|
|
afterResult[0]?.part ??
|
|
null;
|
|
if (!selected) return;
|
|
this.#emit(
|
|
"item.completed",
|
|
{
|
|
kind: "agentMessage",
|
|
channel: "final",
|
|
providerPhase: "final_answer",
|
|
text: selected.text,
|
|
item: selected.item,
|
|
},
|
|
{ turnId, itemId: selected.partId },
|
|
);
|
|
}
|
|
|
|
#emit(
|
|
eventType: PrpEvent["eventType"],
|
|
payload: Record<string, unknown>,
|
|
refs: { turnId?: string; itemId?: string } = {},
|
|
options?: { bypassTerminalTurnGate?: boolean },
|
|
): void {
|
|
if (
|
|
!options?.bypassTerminalTurnGate &&
|
|
eventType !== "harness.diagnostic" &&
|
|
refs.turnId !== undefined &&
|
|
refs.turnId !== this.#activeTurnId
|
|
) {
|
|
// The provider sent this frame for a turn that is not the current
|
|
// active turn, so that turn already reached a terminal state: turns
|
|
// run strictly one at a time (`startTurn` and `attachRun` both refuse
|
|
// to proceed while `#activeTurnId` is set), and a turn id is never
|
|
// reused. Comparing directly against `#activeTurnId` needs no history
|
|
// of past turns, so the gate stays correct and its memory stays O(1)
|
|
// no matter how many turns a long-lived session runs. The queue stays
|
|
// open across turns, so a silent drop here would let a stale frame
|
|
// reach the next turn's consumer. Report it instead of discarding it
|
|
// without a trace.
|
|
this.#emit("harness.diagnostic", {
|
|
code: "opencode_late_terminal_turn_event_dropped",
|
|
message: `OpenCode sent a ${eventType} event for a turn that already reached a terminal state.`,
|
|
droppedEventType: eventType,
|
|
turnId: refs.turnId,
|
|
});
|
|
return;
|
|
}
|
|
if (["turn.completed", "turn.failed", "turn.cancelled", "turn.interrupted"].includes(eventType)) {
|
|
const performance = this.#runtime.performanceDiagnostics?.take(this.#performanceBoundaryMs);
|
|
this.#performanceBoundaryMs = this.#now().getTime();
|
|
if (performance) this.#emit("harness.diagnostic", performance, refs);
|
|
}
|
|
const sourceSeq = ++this.#sourceSequence;
|
|
const event: PrpEvent = {
|
|
schema: "paperclip.prp.event.v1",
|
|
sourceEventId: `${this.#runnerInstanceId}:${this.#runId}:${sourceSeq}`,
|
|
sourceSeq,
|
|
sourceInstanceId: this.#runnerInstanceId,
|
|
sourceKind: "runner",
|
|
runId: this.#runId,
|
|
normalizedSessionId: this.#normalizedSessionId,
|
|
...(refs.turnId ? { turnId: refs.turnId } : {}),
|
|
...(refs.itemId ? { itemId: refs.itemId } : {}),
|
|
eventType,
|
|
schemaVersion: 1,
|
|
priority: eventType === "run.result.proposed" ? 0 : 1,
|
|
emittedAt: this.#now().toISOString(),
|
|
payload,
|
|
};
|
|
if (this.#activeTraceFrameId !== null) {
|
|
this.#activeTraceEmittedEventIds.push(event.sourceEventId);
|
|
}
|
|
this.#companyObservability?.observe(event);
|
|
this.#transcript.push(structuredClone(event));
|
|
this.#events.push(event);
|
|
}
|
|
}
|
|
|
|
/** Retain the reusable gateway key in the runner; the harness gets a session-scoped capability. */
|
|
async function startOpenCodeProviderProxy(baseUrl: string, key: string, model: string, environment: NodeJS.ProcessEnv) {
|
|
const upstreamUrl = new URL(`${baseUrl.replace(/\/+$/, "")}/chat/completions`);
|
|
const token = randomBytes(32).toString("base64url");
|
|
// Agent-local settings keep one runtime's transport configuration out of other sessions.
|
|
const proxyEnv = {
|
|
HTTP_PROXY: environment.http_proxy ?? environment.HTTP_PROXY ?? environment.all_proxy ?? environment.ALL_PROXY,
|
|
HTTPS_PROXY: environment.https_proxy ?? environment.HTTPS_PROXY ?? environment.http_proxy ?? environment.HTTP_PROXY ?? environment.all_proxy ?? environment.ALL_PROXY,
|
|
NO_PROXY: environment.no_proxy ?? environment.NO_PROXY,
|
|
};
|
|
const ca = [...getCACertificates("default")];
|
|
if (environment.SSL_CERT_FILE) ca.push(await readFile(environment.SSL_CERT_FILE, "utf8"));
|
|
if (environment.SSL_CERT_DIR) {
|
|
for (const entry of await readdir(environment.SSL_CERT_DIR, { withFileTypes: true })) {
|
|
if (!entry.isDirectory()) {
|
|
const certificate = await readFile(join(environment.SSL_CERT_DIR, entry.name), "utf8");
|
|
if (certificate.includes("-----BEGIN CERTIFICATE-----")) ca.push(certificate);
|
|
}
|
|
}
|
|
}
|
|
const agent = upstreamUrl.protocol === "https:" ? new HttpsAgent({ proxyEnv, ca }) : new HttpAgent({ proxyEnv });
|
|
const controllers = new Set<AbortController>();
|
|
const server = createHttpServer((request, response) => {
|
|
const controller = new AbortController();
|
|
controllers.add(controller);
|
|
response.once("close", () => controller.abort());
|
|
void (async () => {
|
|
if (request.headers.authorization !== `Bearer ${token}`) {
|
|
response.writeHead(401).end();
|
|
return;
|
|
}
|
|
if (request.method !== "POST" || request.url !== "/v1/chat/completions") {
|
|
response.writeHead(404).end();
|
|
return;
|
|
}
|
|
const chunks: Buffer[] = [];
|
|
let bytes = 0;
|
|
for await (const chunk of request) {
|
|
bytes += chunk.length;
|
|
if (bytes > 16 * 1024 * 1024) {
|
|
response.writeHead(413).end();
|
|
return;
|
|
}
|
|
chunks.push(Buffer.from(chunk));
|
|
}
|
|
const body = Buffer.concat(chunks);
|
|
let payload: Record<string, unknown>;
|
|
try { payload = JSON.parse(body.toString("utf8")); }
|
|
catch { response.writeHead(400).end(); return; }
|
|
if (!payload || typeof payload !== "object" || payload.model !== model ||
|
|
["models", "route", "plugins", "transforms"].some(field => Object.hasOwn(payload, field))) {
|
|
response.writeHead(400).end();
|
|
return;
|
|
}
|
|
const upstream = await new Promise<IncomingMessage>((resolve, reject) => {
|
|
const outgoing = (upstreamUrl.protocol === "https:" ? requestHttps : requestHttp)(upstreamUrl, {
|
|
method: "POST",
|
|
agent,
|
|
headers: { ...(isOpenRouterUrl(baseUrl) ? OPENROUTER_ATTRIBUTION_HEADERS : {}), "Content-Type": "application/json", "Content-Length": body.length, ...(key ? { Authorization: `Bearer ${key}` } : {}) },
|
|
signal: AbortSignal.any([controller.signal, AbortSignal.timeout(600_000)]),
|
|
}, resolve);
|
|
outgoing.once("error", reject);
|
|
outgoing.end(body);
|
|
});
|
|
// Never forward authentication to a redirect destination.
|
|
const status = upstream.statusCode ?? 502;
|
|
if (status >= 300 && status < 400) {
|
|
upstream.destroy();
|
|
throw new Error("Provider redirects are not supported");
|
|
}
|
|
const headers: Record<string, string> = {};
|
|
for (const name of ["content-type", "content-encoding", "cache-control", "retry-after"]) {
|
|
const value = upstream.headers[name];
|
|
if (typeof value === "string") headers[name] = value;
|
|
}
|
|
response.writeHead(status, headers);
|
|
await pipeline(upstream, response);
|
|
})().catch(() => {
|
|
if (!response.headersSent) response.writeHead(502).end("Provider request failed");
|
|
else response.destroy();
|
|
}).finally(() => controllers.delete(controller));
|
|
});
|
|
try {
|
|
await new Promise<void>((resolve, reject) => {
|
|
server.once("error", reject);
|
|
server.listen(0, "127.0.0.1", () => { server.off("error", reject); resolve(); });
|
|
});
|
|
} catch (error) { agent.destroy(); throw error; }
|
|
const address = server.address();
|
|
if (!address || typeof address === "string") {
|
|
server.close();
|
|
agent.destroy();
|
|
throw new Error("Could not bind OpenCode provider proxy");
|
|
}
|
|
return {
|
|
baseURL: `http://127.0.0.1:${address.port}/v1`,
|
|
token,
|
|
close: async () => {
|
|
for (const controller of controllers) controller.abort();
|
|
agent.destroy();
|
|
await new Promise<void>((resolve) => { server.close(() => resolve()); server.closeAllConnections(); });
|
|
},
|
|
};
|
|
}
|
|
|
|
async function startRuntime(input: {
|
|
options: OpenCodeServerDriverOptions;
|
|
root: string;
|
|
cwd: string;
|
|
trace: ProviderTraceFileSink | null;
|
|
dispatch: (call: {
|
|
tool: string;
|
|
callId: string;
|
|
arguments: unknown;
|
|
}) => Promise<unknown>;
|
|
}): Promise<OpenCodeRuntime> {
|
|
const port = await reservePort();
|
|
const password = randomBytes(32).toString("base64url");
|
|
const username = "paperclip";
|
|
const authHeader = `Basic ${Buffer.from(`${username}:${password}`).toString("base64")}`;
|
|
const configHome = join(input.root, "config");
|
|
const dataHome = join(input.root, "data");
|
|
const cacheHome = join(input.root, "cache");
|
|
await Promise.all([
|
|
mkdir(join(configHome, "opencode"), { recursive: true, mode: 0o700 }),
|
|
mkdir(dataHome, { recursive: true, mode: 0o700 }),
|
|
mkdir(cacheHome, { recursive: true, mode: 0o700 }),
|
|
]);
|
|
// HOME contains a read-only skill snapshot, whose destination must be fresh.
|
|
// Keep OpenCode's XDG data stable for provider-session recovery while giving
|
|
// every launch (including retries and recovery) a new isolated HOME.
|
|
const homesRoot = join(input.root, OPENCODE_ISOLATED_HOMES_DIRECTORY);
|
|
await mkdir(homesRoot, { recursive: true, mode: 0o700 });
|
|
const isolatedHome = await mkdtemp(join(homesRoot, "home-"));
|
|
await chmod(isolatedHome, 0o700);
|
|
try {
|
|
await materializeNativeRuntimeSkills(
|
|
input.options.runtimeContext ?? null,
|
|
join(isolatedHome, ".claude", "skills"),
|
|
);
|
|
} catch (error) {
|
|
await removeIsolatedHome(isolatedHome).catch(() => undefined);
|
|
throw error;
|
|
}
|
|
const bridge = await startOpenCodeMcpBridge({
|
|
tools: input.options.dynamicTools,
|
|
handler: input.dispatch,
|
|
}).catch(async (error) => {
|
|
await removeIsolatedHome(isolatedHome).catch(() => undefined);
|
|
throw error;
|
|
});
|
|
const assignedMcp = nativeMcpLaunchBinding(
|
|
input.options.environment ?? process.env,
|
|
);
|
|
const identityKey = input.options.environment?.PAPERCLIP_AGENT_PRIVATE_KEY;
|
|
const identityValues = identityKey ? [identityKey, JSON.stringify(identityKey).slice(1, -1),
|
|
...identityKey.split(/\r?\n/).filter(line => line && !line.startsWith("-----"))] : [];
|
|
const providerEnvironment = input.options.environment ?? process.env;
|
|
const sensitiveValues = [
|
|
...identityValues,
|
|
password,
|
|
authHeader,
|
|
bridge.secret,
|
|
assignedMcp?.token,
|
|
providerEnvironment.OPENROUTER_API_KEY,
|
|
providerEnvironment.PAPERCLIP_AI_PROVIDER_KEY,
|
|
].filter((value): value is string => Boolean(value));
|
|
input.trace?.addSensitiveValues(sensitiveValues);
|
|
const instructionRoot =
|
|
input.options.runtimeContext?.instructions.bundle.rootPath;
|
|
// OpenCode canonicalizes tool paths (for example /var -> /private/var on
|
|
// macOS). Permit the assigned workspace under either spelling; operations
|
|
// within it still obey the selected allow/ask/deny permission mode.
|
|
const externalDirectories: Record<string, string> = { "*": "deny" };
|
|
for (const root of new Set([input.cwd, await realpath(input.cwd)])) {
|
|
externalDirectories[root] = "allow";
|
|
externalDirectories[`${root}/**`] = "allow";
|
|
}
|
|
if (instructionRoot) externalDirectories[`${instructionRoot}/**`] = "allow";
|
|
const [modelProvider, ...modelIdParts] = input.options.model.split("/");
|
|
const providerModelId = modelIdParts.join("/");
|
|
const providerRoute = modelProvider === "openrouter"
|
|
? { baseUrl: "https://openrouter.ai/api/v1", key: providerEnvironment.OPENROUTER_API_KEY ?? "" }
|
|
: modelProvider === "paperclip" && input.options.environment?.PAPERCLIP_AI_PROVIDER_URL
|
|
? { baseUrl: input.options.environment.PAPERCLIP_AI_PROVIDER_URL, key: input.options.environment.PAPERCLIP_AI_PROVIDER_KEY ?? "" }
|
|
: null;
|
|
const providerProxy = providerRoute
|
|
? await startOpenCodeProviderProxy(providerRoute.baseUrl, providerRoute.key, providerModelId, providerEnvironment).catch(async error => {
|
|
await bridge.close().catch(() => {});
|
|
await removeIsolatedHome(isolatedHome).catch(() => {});
|
|
throw error;
|
|
})
|
|
: null;
|
|
if (providerProxy) {
|
|
sensitiveValues.push(providerProxy.token);
|
|
input.trace?.addSensitiveValues([providerProxy.token]);
|
|
}
|
|
let child: ChildProcess | undefined;
|
|
// Failure to collect diagnostics must not prevent the requested work.
|
|
const performanceDiagnostics = input.options.environment?.[PROVIDER_PERFORMANCE_ENV] === "1"
|
|
? await startOpenCodePerformanceDiagnostics().catch(() => null) : null;
|
|
if (performanceDiagnostics) {
|
|
const values = [performanceDiagnostics.environment.OTEL_EXPORTER_OTLP_HEADERS,
|
|
performanceDiagnostics.environment.OTEL_EXPORTER_OTLP_HEADERS.replace("Authorization=Bearer ", "")];
|
|
sensitiveValues.push(...values);
|
|
input.trace?.addSensitiveValues(values);
|
|
}
|
|
let launchPrepared = false;
|
|
const releaseExecutable = () => {
|
|
if (!launchPrepared) return;
|
|
launchPrepared = false;
|
|
try {
|
|
input.options.commandLifecycle?.afterExit?.();
|
|
} catch (error) {
|
|
input.options.onDiagnostic?.(redact(`OpenCode executable cleanup failed: ${String(error)}`, sensitiveValues));
|
|
}
|
|
};
|
|
try {
|
|
const config = {
|
|
$schema: "https://opencode.ai/config.json",
|
|
model: input.options.model,
|
|
small_model: input.options.model,
|
|
share: "disabled",
|
|
autoupdate: false,
|
|
...(performanceDiagnostics ? { experimental: { openTelemetry: true } } : {}),
|
|
// The configured entry is already composed exactly once into the session
|
|
// system prompt; siblings remain available through the read-only root.
|
|
instructions: [],
|
|
plugin: [],
|
|
// OpenCode's bundled models.dev snapshot can lag behind OpenRouter's live
|
|
// catalog. Bind the already-qualified exact model slug into the built-in
|
|
// provider instead of silently falling back or rejecting a newer model.
|
|
provider: {
|
|
[modelProvider!]: {
|
|
...(modelProvider === "openrouter" ? { options: { headers: OPENROUTER_ATTRIBUTION_HEADERS } } : {}),
|
|
...(providerProxy ? {
|
|
npm: "@ai-sdk/openai-compatible",
|
|
name: modelProvider === "openrouter" ? "OpenRouter" : "Paperclip connection",
|
|
options: {
|
|
...(modelProvider === "openrouter" ? { headers: OPENROUTER_ATTRIBUTION_HEADERS } : {}),
|
|
baseURL: providerProxy.baseURL,
|
|
apiKey: providerProxy.token,
|
|
},
|
|
} : {}),
|
|
models: {
|
|
[providerModelId]: {
|
|
name: providerModelId,
|
|
...(modelProvider === "openrouter"
|
|
? { variants: {
|
|
"paperclip-default": {},
|
|
"paperclip-no-reasoning": { reasoning: { enabled: false } },
|
|
} }
|
|
: {}),
|
|
},
|
|
},
|
|
},
|
|
},
|
|
tools: {
|
|
question: true,
|
|
},
|
|
permission: {
|
|
"*": input.options.permissionMode ?? "allow",
|
|
question: "allow",
|
|
"paperclip_*": "allow",
|
|
"mcp__paperclip__*": "allow",
|
|
external_directory: externalDirectories,
|
|
},
|
|
mcp: {
|
|
paperclip: {
|
|
type: "remote",
|
|
url: bridge.url,
|
|
enabled: true,
|
|
oauth: false,
|
|
headers: { Authorization: `Bearer ${bridge.secret}` },
|
|
timeout: 30_000,
|
|
},
|
|
...(assignedMcp
|
|
? {
|
|
[assignedMcp.name]: {
|
|
type: "remote",
|
|
url: assignedMcp.url,
|
|
enabled: true,
|
|
oauth: false,
|
|
headers: { Authorization: `Bearer ${assignedMcp.token}` },
|
|
timeout: 30_000,
|
|
},
|
|
}
|
|
: {}),
|
|
},
|
|
};
|
|
await writeFile(
|
|
join(configHome, "opencode", "opencode.json"),
|
|
`${JSON.stringify(config, null, 2)}\n`,
|
|
{ mode: 0o600 },
|
|
);
|
|
const environment = sanitizedEnvironment(
|
|
input.options.environment,
|
|
{
|
|
HOME: isolatedHome,
|
|
XDG_CONFIG_HOME: configHome,
|
|
XDG_DATA_HOME: dataHome,
|
|
XDG_CACHE_HOME: cacheHome,
|
|
OPENCODE_DISABLE_PROJECT_CONFIG: "true",
|
|
// The runner pins the executable, model and assigned MCP tools. A
|
|
// fresh isolated cache must not fetch a catalog or install unrelated
|
|
// default plugins before it can submit the first prompt.
|
|
OPENCODE_DISABLE_MODELS_FETCH: "true",
|
|
OPENCODE_DISABLE_DEFAULT_PLUGINS: "true",
|
|
OPENCODE_SERVER_USERNAME: username,
|
|
OPENCODE_SERVER_PASSWORD: password,
|
|
...performanceDiagnostics?.environment,
|
|
...(providerProxy ? { NO_PROXY: [providerEnvironment.no_proxy ?? providerEnvironment.NO_PROXY, "127.0.0.1", "localhost"].filter(Boolean).join(",") } : {}),
|
|
},
|
|
);
|
|
const isolateProcessGroup = input.options.isolateProcessGroup ?? true;
|
|
const stdio: Array<"ignore" | "pipe" | number> = ["ignore", "ignore", "pipe"];
|
|
if (input.options.commandFd !== undefined) {
|
|
while (stdio.length <= input.options.commandFd) stdio.push("ignore");
|
|
stdio[input.options.commandFd] = input.options.commandFd;
|
|
}
|
|
input.options.commandLifecycle?.beforeSpawn();
|
|
launchPrepared = true;
|
|
child = spawn(
|
|
input.options.command ?? resolvePinnedOpenCodeCommand(),
|
|
["serve", "--hostname", "127.0.0.1", "--port", String(port)],
|
|
{
|
|
cwd: input.cwd,
|
|
env: environment,
|
|
stdio,
|
|
detached: globalThis.process.platform !== "win32" && isolateProcessGroup,
|
|
},
|
|
);
|
|
child.once("exit", releaseExecutable);
|
|
if (child.pid !== undefined) {
|
|
try {
|
|
input.options.commandLifecycle?.afterSpawn();
|
|
} catch (error) {
|
|
child.kill("SIGKILL");
|
|
throw error;
|
|
}
|
|
}
|
|
let diagnostics = "";
|
|
child.stderr?.on("data", (chunk) => {
|
|
const raw = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
|
|
const redactedDiagnostic = redact(raw.toString("utf8"), sensitiveValues);
|
|
diagnostics = `${diagnostics}${redactedDiagnostic}`.slice(-8_192);
|
|
const frameId = input.trace?.frame({
|
|
direction: "provider_stderr",
|
|
raw,
|
|
transport: "process_stderr",
|
|
nativeMethod: "opencode serve stderr",
|
|
});
|
|
if (frameId) {
|
|
input.trace?.interpretation({
|
|
frameId,
|
|
stage: "typescript_opencode_process_transport",
|
|
ruleId: "opencode.stderr",
|
|
disposition: "operator_only",
|
|
reason:
|
|
"OpenCode stderr is retained only in the restricted trace sidecar",
|
|
});
|
|
}
|
|
input.options.onDiagnostic?.(redactedDiagnostic);
|
|
});
|
|
const providerChild = child;
|
|
await new Promise<void>((resolve, reject) => {
|
|
providerChild.once("spawn", resolve);
|
|
providerChild.once("error", reject);
|
|
});
|
|
if (child.pid)
|
|
await input.options.onSpawn?.({
|
|
pid: child.pid,
|
|
processGroupId:
|
|
globalThis.process.platform === "win32" || !isolateProcessGroup
|
|
? null
|
|
: child.pid,
|
|
startedAt: new Date().toISOString(),
|
|
});
|
|
const baseUrl = `http://127.0.0.1:${port}`;
|
|
const health = await waitForHealth(
|
|
baseUrl,
|
|
authHeader,
|
|
input.options.fetch ?? globalThis.fetch,
|
|
child,
|
|
() => diagnostics,
|
|
input.trace,
|
|
);
|
|
const version = text(record(health).version);
|
|
if (!/^\d+\.\d+\.\d+$/.test(version))
|
|
throw new Error("OpenCode health response omitted a semantic version");
|
|
const qualifiedComparison = compareVersion(
|
|
version,
|
|
QUALIFIED_OPENCODE_VERSION,
|
|
);
|
|
if (qualifiedComparison !== 0) {
|
|
throw new Error(
|
|
`OpenCode ${version} is not the question-conformance-qualified ${QUALIFIED_OPENCODE_VERSION}`,
|
|
);
|
|
}
|
|
return {
|
|
baseUrl,
|
|
authHeader,
|
|
version,
|
|
permissionMode: input.options.permissionMode ?? "allow",
|
|
process: child,
|
|
bridge,
|
|
trace: input.trace,
|
|
sensitiveValues,
|
|
performanceDiagnostics,
|
|
close: async (closeInput = {}) => {
|
|
await providerProxy?.close();
|
|
await bridge.close().catch(() => {});
|
|
if (providerChild.exitCode === null && providerChild.signalCode === null && providerChild.pid) {
|
|
try {
|
|
if (globalThis.process.platform === "win32" || !isolateProcessGroup)
|
|
providerChild.kill("SIGTERM");
|
|
else globalThis.process.kill(-providerChild.pid, "SIGTERM");
|
|
} catch {
|
|
providerChild.kill("SIGTERM");
|
|
}
|
|
}
|
|
await waitForExit(providerChild, 2_000);
|
|
if (providerChild.exitCode === null && providerChild.signalCode === null && providerChild.pid) {
|
|
try {
|
|
if (globalThis.process.platform === "win32" || !isolateProcessGroup)
|
|
providerChild.kill("SIGKILL");
|
|
else globalThis.process.kill(-providerChild.pid, "SIGKILL");
|
|
} catch {
|
|
providerChild.kill("SIGKILL");
|
|
}
|
|
await waitForExit(providerChild, 2_000);
|
|
}
|
|
await performanceDiagnostics?.close().catch(() => {});
|
|
await rm(join(configHome, "opencode", "opencode.json"), {
|
|
force: true,
|
|
}).catch(() => undefined);
|
|
await removeIsolatedHome(isolatedHome).catch(() => undefined);
|
|
if (closeInput.finalizeTrace !== false) {
|
|
await input.trace?.finish({ reason: closeInput.reason ?? null });
|
|
}
|
|
},
|
|
};
|
|
} catch (error) {
|
|
await performanceDiagnostics?.close().catch(() => {});
|
|
await providerProxy?.close();
|
|
await bridge.close().catch(() => {});
|
|
child?.kill("SIGKILL");
|
|
if (child?.pid) await waitForExit(child, 2_000);
|
|
if (!child?.pid || child.exitCode !== null || child.signalCode !== null) releaseExecutable();
|
|
await rm(join(configHome, "opencode", "opencode.json"), {
|
|
force: true,
|
|
}).catch(() => undefined);
|
|
await removeIsolatedHome(isolatedHome).catch(() => undefined);
|
|
throw error;
|
|
}
|
|
}
|
|
|
|
export function normalizeOpenCodeQuestionSet(
|
|
nativeQuestions: Record<string, unknown>[],
|
|
metadata: Record<string, unknown> = {},
|
|
): PaperclipQuestionSet {
|
|
const questions = nativeQuestions.map(
|
|
(question, index): PaperclipQuestion => {
|
|
const options = (Array.isArray(question.options) ? question.options : [])
|
|
.map(record)
|
|
.slice(0, 128)
|
|
.map((option, optionIndex) => ({
|
|
id: text(option.id, `option-${optionIndex + 1}`).slice(0, 160),
|
|
label: text(
|
|
option.label,
|
|
text(option.value, `Option ${optionIndex + 1}`),
|
|
).slice(0, 1_000),
|
|
...(text(option.description)
|
|
? { description: text(option.description).slice(0, 4_000) }
|
|
: {}),
|
|
}));
|
|
const custom = question.custom ?? question.allowCustom ?? true;
|
|
return {
|
|
id: openCodeQuestionId(question, index),
|
|
...(text(question.header)
|
|
? { header: text(question.header).slice(0, 1_000) }
|
|
: {}),
|
|
prompt: text(
|
|
question.question,
|
|
text(question.prompt, `Question ${index + 1}`),
|
|
).slice(0, 4_000),
|
|
...(text(question.description)
|
|
? { helpText: text(question.description).slice(0, 4_000) }
|
|
: {}),
|
|
required: question.required === true,
|
|
answerMode:
|
|
options.length === 0
|
|
? "text"
|
|
: question.multiple === true
|
|
? "multi_select"
|
|
: "single_select",
|
|
...(options.length > 0 ? { options } : {}),
|
|
...(options.length > 0 && custom === true
|
|
? {
|
|
customAnswer: {
|
|
enabled: true,
|
|
label: "Other",
|
|
placeholder: "Enter another answer",
|
|
},
|
|
}
|
|
: {}),
|
|
};
|
|
},
|
|
);
|
|
return parsePaperclipQuestionSet({
|
|
schema: PAPERCLIP_QUESTION_SET_SCHEMA,
|
|
title: text(metadata.title, "OpenCode needs your input").slice(0, 1_000),
|
|
...(text(metadata.description)
|
|
? { description: text(metadata.description).slice(0, 4_000) }
|
|
: {}),
|
|
submitLabel: text(metadata.submitLabel, "Submit answers").slice(0, 200),
|
|
questions,
|
|
});
|
|
}
|
|
|
|
function openCodeAnswers(
|
|
pending: {
|
|
request: HarnessRuntimeRequest;
|
|
nativeQuestions: Record<string, unknown>[];
|
|
},
|
|
response: PaperclipQuestionResponse,
|
|
): string[][] {
|
|
return pending.nativeQuestions.map((nativeQuestion, index) => {
|
|
const questionId = openCodeQuestionId(nativeQuestion, index);
|
|
const question = pending.request.input?.questions.find(
|
|
(candidate) => candidate.id === questionId,
|
|
);
|
|
const answer = response.answers[questionId];
|
|
if (!question || !answer) return [];
|
|
const values = (answer.selectedOptionIds ?? [])
|
|
.map(
|
|
(optionId) =>
|
|
question.options?.find((option) => option.id === optionId)?.label,
|
|
)
|
|
.filter((value): value is string => typeof value === "string");
|
|
if (answer.text !== undefined) values.push(answer.text);
|
|
if (answer.customText !== undefined) values.push(answer.customText);
|
|
return values;
|
|
});
|
|
}
|
|
|
|
function openCodeQuestionId(
|
|
question: Record<string, unknown>,
|
|
index: number,
|
|
): string {
|
|
const nativeId = text(question.id).trim();
|
|
if (nativeId) return nativeId.slice(0, 160);
|
|
const header = text(question.header)
|
|
.trim()
|
|
.toLowerCase()
|
|
.replace(/[^a-z0-9._:-]+/g, "-")
|
|
.replace(/^-+|-+$/g, "")
|
|
.slice(0, 160);
|
|
return header || `question-${index + 1}`;
|
|
}
|
|
|
|
async function api(
|
|
fetcher: typeof globalThis.fetch,
|
|
runtime: OpenCodeRuntime,
|
|
path: string,
|
|
init: RequestInit = {},
|
|
): Promise<unknown> {
|
|
const timeout = AbortSignal.timeout(20_000);
|
|
const signal = init.signal
|
|
? AbortSignal.any([init.signal, timeout])
|
|
: timeout;
|
|
const method = String(init.method ?? "GET").toUpperCase();
|
|
const requestRaw =
|
|
typeof init.body === "string"
|
|
? init.body
|
|
: init.body instanceof Uint8Array
|
|
? init.body
|
|
: "";
|
|
const requestFrameId = runtime.trace?.frame({
|
|
direction: "client_to_provider",
|
|
raw: requestRaw,
|
|
transport: "http_json",
|
|
nativeMethod: `${method} ${path}`,
|
|
});
|
|
if (requestFrameId) {
|
|
runtime.trace?.interpretation({
|
|
frameId: requestFrameId,
|
|
stage: "typescript_opencode_http_transport",
|
|
ruleId: `opencode.http.${method}.${safeTraceRulePath(path)}`,
|
|
disposition: "operator_only",
|
|
reason: "Sent an exact HTTP request body to the OpenCode app server",
|
|
});
|
|
}
|
|
let response: Response;
|
|
try {
|
|
response = await fetcher(`${runtime.baseUrl}${path}`, {
|
|
...init,
|
|
signal,
|
|
headers: {
|
|
Authorization: runtime.authHeader,
|
|
"Content-Type": "application/json",
|
|
...init.headers,
|
|
},
|
|
});
|
|
} catch (error) {
|
|
throw new Error(
|
|
`OpenCode API ${path} request failed: ${redact(String(error), runtime.sensitiveValues)}`,
|
|
);
|
|
}
|
|
const responseRaw = await response.text();
|
|
const responseFrameId = runtime.trace?.frame({
|
|
direction: "provider_to_client",
|
|
raw: responseRaw,
|
|
transport: "http_json",
|
|
nativeMethod: `${method} ${path} ${response.status}`,
|
|
});
|
|
if (!response.ok) {
|
|
if (responseFrameId) {
|
|
runtime.trace?.interpretation({
|
|
frameId: responseFrameId,
|
|
stage: "typescript_opencode_http_parse",
|
|
ruleId: `opencode.http.error.${response.status}`,
|
|
disposition: "rejected",
|
|
reason: `OpenCode API returned HTTP ${response.status}`,
|
|
});
|
|
}
|
|
throw new Error(
|
|
`OpenCode API ${path} returned HTTP ${response.status}: ${redact(responseRaw, runtime.sensitiveValues)}`,
|
|
);
|
|
}
|
|
if (response.status === 204 || !responseRaw) {
|
|
if (responseFrameId) {
|
|
runtime.trace?.interpretation({
|
|
frameId: responseFrameId,
|
|
stage: "typescript_opencode_http_parse",
|
|
ruleId: "opencode.http.empty_success",
|
|
disposition: "operator_only",
|
|
reason: "OpenCode API returned a successful empty response",
|
|
});
|
|
}
|
|
return null;
|
|
}
|
|
try {
|
|
const parsed = JSON.parse(responseRaw) as unknown;
|
|
if (responseFrameId) {
|
|
runtime.trace?.interpretation({
|
|
frameId: responseFrameId,
|
|
stage: "typescript_opencode_http_parse",
|
|
ruleId: "opencode.http.json_success",
|
|
disposition: "operator_only",
|
|
fieldMappings: [
|
|
{
|
|
inputPath: "$raw",
|
|
outputPath: "$response",
|
|
action: "normalized",
|
|
reason: "Decoded the exact OpenCode HTTP response body as JSON",
|
|
},
|
|
],
|
|
reason: "OpenCode HTTP response parsed as JSON",
|
|
});
|
|
}
|
|
return parsed;
|
|
} catch (error) {
|
|
if (responseFrameId) {
|
|
runtime.trace?.interpretation({
|
|
frameId: responseFrameId,
|
|
stage: "typescript_opencode_http_parse",
|
|
ruleId: "opencode.http.invalid_json",
|
|
disposition: "rejected",
|
|
reason: `OpenCode response was not valid JSON: ${String(error).slice(0, 400)}`,
|
|
});
|
|
}
|
|
throw error;
|
|
}
|
|
}
|
|
|
|
function retryableOpenCodeStartupError(error: unknown): boolean {
|
|
const message = String(error);
|
|
return (
|
|
message.includes("request failed") ||
|
|
message.includes("did not become healthy") ||
|
|
message.includes("exited during startup") ||
|
|
message.includes("provider_initialize_timeout") ||
|
|
message.includes("provider_process_exited") ||
|
|
message.includes("HTTP 408") ||
|
|
message.includes("HTTP 425") ||
|
|
message.includes("HTTP 429") ||
|
|
/HTTP 5\d\d/.test(message)
|
|
);
|
|
}
|
|
|
|
async function waitForHealth(
|
|
baseUrl: string,
|
|
authHeader: string,
|
|
fetcher: typeof globalThis.fetch,
|
|
process: ChildProcess,
|
|
diagnostics: () => string,
|
|
trace: ProviderTraceFileSink | null,
|
|
): Promise<unknown> {
|
|
const deadline = Date.now() + 10_000;
|
|
while (Date.now() < deadline) {
|
|
if (process.exitCode !== null || process.signalCode !== null) {
|
|
const detail = redact(diagnostics());
|
|
throw new Error(
|
|
`provider_process_exited: provider=opencode stage=health exitCode=${process.exitCode ?? "null"} signal=${process.signalCode ?? "null"}${detail ? ` stderrTail=${detail}` : ""}`,
|
|
);
|
|
}
|
|
try {
|
|
const requestFrameId = trace?.frame({
|
|
direction: "client_to_provider",
|
|
raw: "",
|
|
transport: "http_json",
|
|
nativeMethod: "GET /global/health",
|
|
});
|
|
if (requestFrameId) {
|
|
trace?.interpretation({
|
|
frameId: requestFrameId,
|
|
stage: "typescript_opencode_http_transport",
|
|
ruleId: "opencode.http.GET_global_health",
|
|
disposition: "operator_only",
|
|
reason: "Probed the local OpenCode app-server health endpoint",
|
|
});
|
|
}
|
|
const response = await fetcher(`${baseUrl}/global/health`, {
|
|
headers: { Authorization: authHeader },
|
|
signal: AbortSignal.timeout(1_000),
|
|
});
|
|
const raw = await response.text();
|
|
const responseFrameId = trace?.frame({
|
|
direction: "provider_to_client",
|
|
raw,
|
|
transport: "http_json",
|
|
nativeMethod: `GET /global/health ${response.status}`,
|
|
});
|
|
if (response.ok) {
|
|
const parsed = JSON.parse(raw) as unknown;
|
|
if (responseFrameId) {
|
|
trace?.interpretation({
|
|
frameId: responseFrameId,
|
|
stage: "typescript_opencode_http_parse",
|
|
ruleId: "opencode.http.health_success",
|
|
disposition: "operator_only",
|
|
reason: "OpenCode health response parsed successfully",
|
|
});
|
|
}
|
|
return parsed;
|
|
}
|
|
} catch {
|
|
/* server is still starting */
|
|
}
|
|
await new Promise((resolve) => setTimeout(resolve, 50));
|
|
}
|
|
const detail = redact(diagnostics());
|
|
throw new Error(
|
|
`provider_initialize_timeout: provider=opencode stage=health${detail ? ` stderrTail=${detail}` : ""}`,
|
|
);
|
|
}
|
|
|
|
async function reservePort(): Promise<number> {
|
|
const server = createServer();
|
|
await new Promise<void>((resolve, reject) => {
|
|
server.once("error", reject);
|
|
server.listen(0, "127.0.0.1", () => resolve());
|
|
});
|
|
const address = server.address();
|
|
if (!address || typeof address === "string")
|
|
throw new Error("Unable to reserve OpenCode port");
|
|
const port = address.port;
|
|
await new Promise<void>((resolve, reject) =>
|
|
server.close((error) => (error ? reject(error) : resolve())),
|
|
);
|
|
return port;
|
|
}
|
|
|
|
async function* parseSse(
|
|
stream: ReadableStream<Uint8Array>,
|
|
): AsyncIterable<unknown> {
|
|
for await (const frame of parseOpenCodeSseFrames(stream)) {
|
|
if (frame.compaction?.omitted) continue;
|
|
const event = JSON.parse(frame.data) as unknown;
|
|
if (frame.compaction) annotateOmittedProviderText(event, frame.compaction);
|
|
yield event;
|
|
}
|
|
}
|
|
|
|
function sanitizedEnvironment(
|
|
source: NodeJS.ProcessEnv | undefined,
|
|
overrides: Record<string, string>,
|
|
): NodeJS.ProcessEnv {
|
|
const allowed = [
|
|
"PAPERCLIP_RUNTIME_NOTIFICATION_CONTEXT", "PAPERCLIP_RUNTIME_NOTIFICATION_HELPER",
|
|
"PAPERCLIP_AGENT_KEY_ID", "PAPERCLIP_AGENT_PUBLIC_KEY", "PAPERCLIP_AGENT_PRIVATE_KEY",
|
|
"PATH",
|
|
"LANG",
|
|
"LC_ALL",
|
|
"LC_CTYPE",
|
|
"TZ",
|
|
"HTTP_PROXY",
|
|
"HTTPS_PROXY",
|
|
"NO_PROXY",
|
|
"ALL_PROXY",
|
|
"SSL_CERT_FILE",
|
|
"SSL_CERT_DIR",
|
|
];
|
|
const result: NodeJS.ProcessEnv = {};
|
|
const candidate = source ?? process.env;
|
|
for (const key of allowed)
|
|
if (candidate[key] !== undefined) result[key] = candidate[key];
|
|
return { ...result, ...githubCredentialEnvironment(source ?? {}), ...overrides };
|
|
}
|
|
|
|
function sanitizedEnvironmentKeys(): string[] {
|
|
return [
|
|
"PAPERCLIP_RUNTIME_NOTIFICATION_CONTEXT", "PAPERCLIP_RUNTIME_NOTIFICATION_HELPER",
|
|
"PATH",
|
|
"LANG",
|
|
"LC_ALL",
|
|
"LC_CTYPE",
|
|
"TZ",
|
|
"HTTP_PROXY",
|
|
"HTTPS_PROXY",
|
|
"NO_PROXY",
|
|
"ALL_PROXY",
|
|
"SSL_CERT_FILE",
|
|
"SSL_CERT_DIR",
|
|
];
|
|
}
|
|
|
|
export const OPENCODE_ISOLATED_HOMES_DIRECTORY = "homes";
|
|
|
|
export function opencodeRuntimeSessionDirectoryName(
|
|
normalizedSessionId: string,
|
|
): string {
|
|
const safe = normalizedSessionId
|
|
.replace(/[^a-zA-Z0-9._-]/g, "_")
|
|
.slice(0, 120);
|
|
if (!safe || safe === "." || safe === "..")
|
|
throw new Error("Invalid normalized OpenCode session id");
|
|
return safe;
|
|
}
|
|
|
|
function sessionRoot(
|
|
runtimeDirectory: string,
|
|
normalizedSessionId: string,
|
|
): string {
|
|
return join(
|
|
resolve(runtimeDirectory),
|
|
opencodeRuntimeSessionDirectoryName(normalizedSessionId),
|
|
);
|
|
}
|
|
|
|
async function removeIsolatedHome(home: string): Promise<void> {
|
|
const skillsParent = await lstat(join(home, ".claude")).catch(() => null);
|
|
if (skillsParent?.isDirectory()) {
|
|
await releaseMaterializedNativeRuntimeSkills(
|
|
join(home, ".claude", "skills"),
|
|
).catch(() => undefined);
|
|
}
|
|
await rm(home, { recursive: true, force: true });
|
|
}
|
|
|
|
async function removeLegacyIsolatedHomes(root: string): Promise<void> {
|
|
const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
|
|
for (const entry of entries) {
|
|
if (!entry.isDirectory() || !entry.name.startsWith("home-")) continue;
|
|
await removeIsolatedHome(join(root, entry.name)).catch(() => undefined);
|
|
}
|
|
}
|
|
|
|
function validateWorkspace(value: string): string {
|
|
const cwd = resolve(value);
|
|
if (!value.trim() || cwd === dirname(cwd))
|
|
throw new Error("OpenCode working directory must not be a filesystem root");
|
|
return cwd;
|
|
}
|
|
|
|
function validModel(value: string): boolean {
|
|
const slash = value.indexOf("/");
|
|
return slash > 0 && slash < value.length - 1;
|
|
}
|
|
|
|
function compareVersion(left: string, right: string): number {
|
|
const a = left.split(".").map(Number);
|
|
const b = right.split(".").map(Number);
|
|
for (let index = 0; index < 3; index += 1) {
|
|
if (a[index] !== b[index]) return (a[index] ?? 0) - (b[index] ?? 0);
|
|
}
|
|
return 0;
|
|
}
|
|
|
|
function bounded(value: unknown): Record<string, unknown> {
|
|
const serialized = JSON.stringify(value);
|
|
if (!serialized || serialized.length > 64 * 1024)
|
|
return { omitted: true, reason: "payload_limit" };
|
|
const parsed = JSON.parse(serialized) as unknown;
|
|
return isRecord(parsed) ? parsed : { value: parsed };
|
|
}
|
|
|
|
function record(value: unknown): Record<string, unknown> {
|
|
return isRecord(value) ? value : {};
|
|
}
|
|
function isRecord(value: unknown): value is Record<string, unknown> {
|
|
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
}
|
|
function text(value: unknown, fallback = ""): string {
|
|
return typeof value === "string" ? value : fallback;
|
|
}
|
|
function hasPositiveNumber(value: unknown): boolean {
|
|
if (typeof value === "number") return Number.isFinite(value) && value > 0;
|
|
if (Array.isArray(value)) return value.some(hasPositiveNumber);
|
|
if (isRecord(value)) return Object.values(value).some(hasPositiveNumber);
|
|
return false;
|
|
}
|
|
function safeTraceRulePath(value: string): string {
|
|
return value
|
|
.replace(/\/[A-Za-z0-9_-]{12,}/g, "/:id")
|
|
.replace(/[^A-Za-z0-9_.:/-]/g, "_")
|
|
.replaceAll("/", "_")
|
|
.slice(0, 120);
|
|
}
|
|
function redact(
|
|
value: string,
|
|
sensitiveValues: readonly (string | undefined)[] = [],
|
|
): string {
|
|
let redacted = value;
|
|
for (const sensitive of sensitiveValues) {
|
|
if (sensitive && sensitive.length >= 4)
|
|
redacted = redacted.split(sensitive).join("[REDACTED]");
|
|
}
|
|
return redacted
|
|
.replace(
|
|
/(OPENROUTER_API_KEY|authorization|password|token|secret)\s*[:=]\s*[^\s,}\]]+/gi,
|
|
"$1=[REDACTED]",
|
|
)
|
|
.slice(0, 8_192);
|
|
}
|
|
function canonicalJson(value: unknown): string {
|
|
if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
|
|
if (isRecord(value))
|
|
return `{${Object.keys(value)
|
|
.sort()
|
|
.map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`)
|
|
.join(",")}}`;
|
|
return JSON.stringify(value) ?? "undefined";
|
|
}
|
|
|
|
async function waitForExit(
|
|
process: ChildProcess,
|
|
timeoutMs: number,
|
|
): Promise<void> {
|
|
if (process.exitCode !== null || process.signalCode !== null) return;
|
|
await new Promise<void>((resolve) => {
|
|
const timer = setTimeout(resolve, timeoutMs);
|
|
timer.unref?.();
|
|
process.once("exit", () => {
|
|
clearTimeout(timer);
|
|
resolve();
|
|
});
|
|
});
|
|
}
|
|
|
|
/** Closed vocabulary for a lost OpenCode event stream. Never provider text. */
|
|
export interface OpenCodeEventStreamFailure {
|
|
kind: "server_exited" | "connection_failed" | "http_error" | "stream_closed" | "stream_error";
|
|
exitCode?: number;
|
|
signal?: string;
|
|
connectionError?: string;
|
|
httpStatus?: number;
|
|
}
|
|
|
|
const OPENCODE_CONNECTION_ERROR_CODES: ReadonlySet<string> = new Set([
|
|
"ECONNREFUSED", "ECONNRESET", "EPIPE", "ETIMEDOUT", "EHOSTUNREACH", "ENETUNREACH",
|
|
"UND_ERR_SOCKET", "UND_ERR_CLOSED", "UND_ERR_CONNECT_TIMEOUT", "UND_ERR_HEADERS_TIMEOUT",
|
|
"UND_ERR_BODY_TIMEOUT",
|
|
]);
|
|
|
|
function connectionErrorCode(error: unknown): string | undefined {
|
|
// undici reports `TypeError: fetch failed` and keeps the socket error in `cause`.
|
|
for (let current = error, depth = 0; current && depth < 4; current = record(current).cause, depth += 1) {
|
|
const code = record(current).code;
|
|
if (typeof code === "string") return OPENCODE_CONNECTION_ERROR_CODES.has(code) ? code : "unrecognized";
|
|
}
|
|
return undefined;
|
|
}
|
|
|
|
async function openCodeEventStreamFailure(
|
|
error: unknown,
|
|
process: ChildProcess,
|
|
): Promise<OpenCodeEventStreamFailure> {
|
|
const connectionError = connectionErrorCode(error);
|
|
// A refused or reset connection usually means `opencode serve` has died.
|
|
// Give its exit a moment to be observed so the cause is the exit itself.
|
|
if (connectionError) await waitForExit(process, 1_000);
|
|
if (process.exitCode !== null || process.signalCode !== null) {
|
|
return {
|
|
kind: "server_exited",
|
|
...(process.exitCode !== null ? { exitCode: process.exitCode } : {}),
|
|
...(process.signalCode !== null && process.signalCode in osConstants.signals ? { signal: process.signalCode } : {}),
|
|
...(connectionError ? { connectionError } : {}),
|
|
};
|
|
}
|
|
const httpStatus = record(error).httpStatus;
|
|
if (typeof httpStatus === "number" && Number.isInteger(httpStatus) && httpStatus >= 100 && httpStatus <= 599)
|
|
return { kind: "http_error", httpStatus };
|
|
if (connectionError) return { kind: "connection_failed", connectionError };
|
|
if (record(error).streamClosed === true) return { kind: "stream_closed" };
|
|
return { kind: "stream_error" };
|
|
}
|
|
|
|
export const openCodeServerDriverInternals = { parseSse, openCodeEventStreamFailure };
|
|
|
|
class AsyncQueue<T> implements AsyncIterable<T> {
|
|
#items: T[] = [];
|
|
#waiters: Array<{
|
|
resolve: (result: IteratorResult<T>) => void;
|
|
reject: (error: unknown) => void;
|
|
}> = [];
|
|
#closed = false;
|
|
#error: unknown = null;
|
|
push(item: T): void {
|
|
if (this.#closed) return;
|
|
const waiter = this.#waiters.shift();
|
|
if (waiter) waiter.resolve({ done: false, value: item });
|
|
else this.#items.push(item);
|
|
}
|
|
close(): void {
|
|
if (this.#closed) return;
|
|
this.#closed = true;
|
|
for (const waiter of this.#waiters.splice(0))
|
|
waiter.resolve({ done: true, value: undefined });
|
|
}
|
|
fail(error: unknown): void {
|
|
if (this.#closed) return;
|
|
this.#closed = true;
|
|
this.#error = error;
|
|
for (const waiter of this.#waiters.splice(0)) waiter.reject(error);
|
|
}
|
|
[Symbol.asyncIterator](): AsyncIterator<T> {
|
|
return {
|
|
next: () => {
|
|
const item = this.#items.shift();
|
|
if (item !== undefined)
|
|
return Promise.resolve({ done: false, value: item });
|
|
if (this.#error !== null) return Promise.reject(this.#error);
|
|
if (this.#closed)
|
|
return Promise.resolve({ done: true, value: undefined });
|
|
return new Promise((resolve, reject) =>
|
|
this.#waiters.push({ resolve, reject }),
|
|
);
|
|
},
|
|
};
|
|
}
|
|
}
|