@oar-sh/oar 0.9.0

package/server/claude-worker/workflow-progress-digest.mjs

@@ -0,0 +1,269 @@
+// Normalize Claude CLI workflow progress into the bounded digest the relay
+// ships on a background-task row (`workflowProgress`).
+//
+// Two sources feed the digest (verified against CLI 2.1.226):
+//
+// - `<sessionDir>/workflows/<runId>.json` — the run record, written only at
+//   workflow COMPLETION. Its `workflowProgress` array mixes
+//   `{type:'workflow_phase'}` and `{type:'workflow_agent'}` entries and is the
+//   authoritative tree once it exists.
+// - `<sessionDir>/subagents/workflows/<runId>/journal.jsonl` — the live
+//   append-only source while the run is in flight: `{type:'started', key,
+//   agentId}` then `{type:'result', key, agentId, result}` per agent.
+//   started-without-result = running; result = done.
+//
+// The digest shape is a contract shared with the relay sanitizer and the
+// client tree renderer — keep it EXACTLY this:
+//
+//   { runId, workflowName, status, agentCount, totalTokens, durationMs,
+//     phases: [{index, title}], logs: [string],          // last 5, ≤300 chars
+//     agents: [{index, label, phaseIndex, phaseTitle, model, state, attempt,
+//               lastToolName, tokens, toolCalls, durationMs, startedAt}],
+//     agentsOmitted }                                    // agents ≤100, order kept
+//
+// Both file formats are undocumented CLI internals, so every field is
+// presence-checked and clamped; malformed input degrades to omitted fields or
+// a null digest — these functions NEVER throw.
+
+const MAX_AGENTS = 100;
+const MAX_PHASES = 50;
+const MAX_LOGS = 5;
+const MAX_LOG_CHARS = 300;
+const MAX_LABEL_CHARS = 160;
+const MAX_TOOL_NAME_CHARS = 160;
+const MAX_TITLE_CHARS = 120;
+const MAX_MODEL_CHARS = 80;
+const MAX_STATE_CHARS = 32;
+const MAX_RUN_ID_CHARS = 64;
+const MAX_WORKFLOW_NAME_CHARS = 120;
+
+/** Trimmed string clamped to `max` chars, or null for anything non-string. */
+function clampString(value, max) {
+  if (typeof value !== 'string') return null;
+  const text = value.trim();
+  if (!text) return null;
+  return text.length > max ? text.slice(0, max) : text;
+}
+
+/** A finite number, or null — never NaN/Infinity/strings coerced. */
+function finiteOrNull(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+/**
+ * Digest a completed (or partial) run record. Returns null when `record` is
+ * not an object carrying a usable `runId` — the one field every real record
+ * has and the digest cannot identify a run without.
+ */
+export function digestFromRunRecord(record) {
+  try {
+    if (!record || typeof record !== 'object' || Array.isArray(record)) return null;
+    const runId = clampString(record.runId, MAX_RUN_ID_CHARS);
+    if (!runId) return null;
+
+    const progress = Array.isArray(record.workflowProgress) ? record.workflowProgress : [];
+    const phases = [];
+    const agents = [];
+    let agentTotal = 0;
+    for (const entry of progress) {
+      if (!entry || typeof entry !== 'object') continue;
+      if (entry.type === 'workflow_phase') {
+        if (phases.length < MAX_PHASES) {
+          phases.push({
+            index: finiteOrNull(entry.index) ?? phases.length + 1,
+            title: clampString(entry.title, MAX_TITLE_CHARS),
+          });
+        }
+        continue;
+      }
+      if (entry.type !== 'workflow_agent') continue;
+      agentTotal += 1;
+      if (agents.length >= MAX_AGENTS) continue;
+      // promptPreview/resultPreview are dropped deliberately: they are the
+      // multi-hundred-char fields that would balloon a 2s-cadence broadcast.
+      agents.push({
+        index: finiteOrNull(entry.index) ?? agentTotal,
+        label: clampString(entry.label, MAX_LABEL_CHARS),
+        phaseIndex: finiteOrNull(entry.phaseIndex),
+        phaseTitle: clampString(entry.phaseTitle, MAX_TITLE_CHARS),
+        model: clampString(entry.model, MAX_MODEL_CHARS),
+        state: clampString(entry.state, MAX_STATE_CHARS),
+        attempt: finiteOrNull(entry.attempt),
+        lastToolName: clampString(entry.lastToolName, MAX_TOOL_NAME_CHARS),
+        tokens: finiteOrNull(entry.tokens),
+        toolCalls: finiteOrNull(entry.toolCalls),
+        durationMs: finiteOrNull(entry.durationMs),
+        startedAt: finiteOrNull(entry.startedAt),
+      });
+    }
+
+    // The record also carries top-level `phases: [{title}]`; used only when
+    // workflowProgress had no phase entries to derive titles from.
+    if (!phases.length && Array.isArray(record.phases)) {
+      for (const phase of record.phases) {
+        if (phases.length >= MAX_PHASES) break;
+        if (!phase || typeof phase !== 'object') continue;
+        phases.push({ index: phases.length + 1, title: clampString(phase.title, MAX_TITLE_CHARS) });
+      }
+    }
+
+    const logs = (Array.isArray(record.logs) ? record.logs : [])
+      .filter((line) => typeof line === 'string' && line.trim())
+      .slice(-MAX_LOGS)
+      .map((line) => line.slice(0, MAX_LOG_CHARS));
+
+    return {
+      runId,
+      workflowName: clampString(record.workflowName, MAX_WORKFLOW_NAME_CHARS),
+      status: clampString(record.status, MAX_STATE_CHARS),
+      agentCount: finiteOrNull(record.agentCount) ?? (agentTotal || null),
+      totalTokens: finiteOrNull(record.totalTokens),
+      // Top-level run duration: only the completed run record knows it. The
+      // finished-task card renders it; renderers ignore it when null.
+      durationMs: finiteOrNull(record.durationMs),
+      phases,
+      logs,
+      agents,
+      agentsOmitted: Math.max(0, agentTotal - agents.length),
+    };
+  } catch {
+    return null;
+  }
+}
+
+// Shared-prefix stripping only kicks in when the common prefix is long enough
+// to be boilerplate; short shared openers ("review: ") are kept as-is.
+const MIN_COMMON_PREFIX_CHARS = 24;
+// Leftovers a stripped tail may start with (the prefix often ends mid-
+// separator): whitespace, dashes, and common punctuation.
+const LABEL_LEADING_NOISE = /^[\s.,;:!?·…"'()[\]{}<>|/\\`~*_#=–—-]+/;
+
+/**
+ * Strip the longest common prefix shared by the given labels. Live labels are
+ * prompt previews, and workflows often prefix every agent's prompt with the
+ * same boilerplate — N indistinguishable labels. When ≥2 non-empty string
+ * entries share a prefix of ≥24 chars, that prefix is stripped from each and
+ * the tail (trimmed of leading whitespace/punctuation, clamped to the label
+ * limit) becomes the label. Non-string entries pass through untouched and do
+ * not join the prefix computation; a label that was nothing but the shared
+ * prefix keeps its original text (an empty label would be strictly worse).
+ * Single label or short prefix ⇒ unchanged. Pure and throw-free.
+ */
+export function stripCommonPromptPrefix(labels) {
+  try {
+    if (!Array.isArray(labels)) return [];
+    const strings = labels.filter((label) => typeof label === 'string' && label.length > 0);
+    if (strings.length < 2) return labels.slice();
+    let prefix = strings[0];
+    for (const label of strings) {
+      let shared = 0;
+      const limit = Math.min(prefix.length, label.length);
+      while (shared < limit && prefix[shared] === label[shared]) shared += 1;
+      prefix = prefix.slice(0, shared);
+      if (!prefix) break;
+    }
+    if (prefix.length < MIN_COMMON_PREFIX_CHARS) return labels.slice();
+    return labels.map((label) => {
+      if (typeof label !== 'string' || label.length === 0) return label;
+      const tail = label.slice(prefix.length).replace(LABEL_LEADING_NOISE, '').slice(0, MAX_LABEL_CHARS);
+      return tail || label;
+    });
+  } catch {
+    return Array.isArray(labels) ? labels.slice() : [];
+  }
+}
+
+/** Label lookup tolerant of a Map or a plain object (own keys only). */
+function labelFor(labelsByAgentId, agentId) {
+  try {
+    if (!labelsByAgentId) return null;
+    if (typeof labelsByAgentId.get === 'function') return labelsByAgentId.get(agentId) ?? null;
+    if (typeof labelsByAgentId === 'object' && Object.hasOwn(labelsByAgentId, agentId)) {
+      return labelsByAgentId[agentId];
+    }
+  } catch {
+    // fall through to null
+  }
+  return null;
+}
+
+/**
+ * Digest the live journal while the run record does not exist yet. `entries`
+ * are the parsed journal lines in file order; `labelsByAgentId` (Map or plain
+ * object) supplies per-agent labels read from the first line of each
+ * `agent-<agentId>.jsonl`, falling back to `agent <n>`. The journal carries no
+ * phases, tokens, or timings, so those digest fields are empty/null; `runId`
+ * is optional (the caller knows it from the run directory's name).
+ * Returns null when no agent can be derived — an empty digest has nothing to
+ * render and would only churn the publish path.
+ */
+export function digestFromJournal({ entries, labelsByAgentId, workflowName, runId } = {}) {
+  try {
+    if (!Array.isArray(entries)) return null;
+    const stateByAgentId = new Map();
+    for (const entry of entries) {
+      if (!entry || typeof entry !== 'object') continue;
+      const agentId = clampString(entry.agentId, 256);
+      if (!agentId) continue;
+      if (entry.type === 'started') {
+        if (!stateByAgentId.has(agentId)) stateByAgentId.set(agentId, 'running');
+      } else if (entry.type === 'result') {
+        // A result without a prior `started` still proves the agent ran.
+        stateByAgentId.set(agentId, 'done');
+      }
+    }
+    if (!stateByAgentId.size) return null;
+
+    // Live labels are prompt previews; when the workflow prefixed every
+    // agent's prompt with the same boilerplate, strip the shared prefix so
+    // each label shows the distinguishing tail instead of N identical strings.
+    // The strip runs on the UNCLAMPED strings — boilerplate longer than the
+    // label limit would otherwise clamp every label to the same prefix and
+    // leave nothing to distinguish — and the label clamp is applied to the
+    // results (stripped tails come back pre-clamped, but the keep-original
+    // degenerate paths do not).
+    const agentEntries = [...stateByAgentId];
+    const labels = stripCommonPromptPrefix(
+      agentEntries.map(([agentId]) => {
+        const label = labelFor(labelsByAgentId, agentId);
+        return typeof label === 'string' ? label.trim() || null : null;
+      }),
+    ).map((label) => clampString(label, MAX_LABEL_CHARS));
+
+    const agents = [];
+    let index = 0;
+    for (const [, state] of agentEntries) {
+      index += 1;
+      if (agents.length >= MAX_AGENTS) continue;
+      agents.push({
+        index,
+        label: (typeof labels[index - 1] === 'string' && labels[index - 1]) || `agent ${index}`,
+        phaseIndex: null,
+        phaseTitle: null,
+        model: null,
+        state,
+        attempt: null,
+        lastToolName: null,
+        tokens: null,
+        toolCalls: null,
+        durationMs: null,
+        startedAt: null,
+      });
+    }
+
+    return {
+      runId: clampString(runId, MAX_RUN_ID_CHARS),
+      workflowName: clampString(workflowName, MAX_WORKFLOW_NAME_CHARS),
+      status: 'running',
+      agentCount: stateByAgentId.size,
+      totalTokens: null,
+      durationMs: null,
+      phases: [],
+      logs: [],
+      agents,
+      agentsOmitted: Math.max(0, stateByAgentId.size - agents.length),
+    };
+  } catch {
+    return null;
+  }
+}

package/server/copilot-sdk-runtime.mjs

@@ -0,0 +1,126 @@
+'use strict';
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { pathToFileURL } from 'url';
+
+function dedupePaths(paths) {
+  const seen = new Set();
+  return paths.filter((value) => {
+    const candidate = String(value || '').trim();
+    if (!candidate) return false;
+    const normalized = path.normalize(candidate);
+    if (seen.has(normalized)) return false;
+    seen.add(normalized);
+    return true;
+  });
+}
+
+export function getCopilotBaseDirs({ env = process.env, platform = process.platform, homeDir = os.homedir() } = {}) {
+  const configured = String(env.COPILOT_PKG_DIR || '').trim();
+  if (platform === 'win32') {
+    return dedupePaths([configured, path.join(env.LOCALAPPDATA || path.join(homeDir, 'AppData', 'Local'), 'copilot', 'pkg')]);
+  }
+  if (platform === 'darwin') {
+    return dedupePaths([configured, path.join(homeDir, 'Library', 'Application Support', 'copilot', 'pkg')]);
+  }
+  return dedupePaths([
+    configured,
+    path.join(env.XDG_CACHE_HOME || path.join(homeDir, '.cache'), 'copilot', 'pkg'),
+    path.join(env.XDG_DATA_HOME || path.join(homeDir, '.local', 'share'), 'copilot', 'pkg'),
+  ]);
+}
+
+/**
+ * The runtime entry point inside a Copilot CLI version directory.
+ *
+ * It is `app.js` and never the sibling `index.js`: `index.js` is a
+ * self-updating launcher that resolves the newest version in the cache and
+ * `exec`s THAT version's `app.js`. Spawning it silently defeats pinning the
+ * runtime to the SDK bundle's own version, which matters because the event
+ * shapes the workers normalize are per-version. Exported so every caller pins
+ * the same file.
+ */
+export function copilotRuntimeEntry(versionDir) {
+  return path.join(versionDir, 'app.js');
+}
+
+export function resolveInstalledCopilotPaths({ config = {}, env = process.env, platform = process.platform, arch = process.arch } = {}) {
+  if (config.sdkPath && config.cliPath) {
+    return { sdkPath: path.resolve(config.sdkPath), cliPath: path.resolve(config.cliPath), version: 'configured' };
+  }
+  const requestedVersion = String(config.sdkVersion || '').trim();
+  const subdirs = platform === 'universal' ? ['universal'] : [`${platform}-${arch}`, 'universal'];
+  const candidates = [];
+  for (const [baseDirIdx, baseDir] of getCopilotBaseDirs({ env, platform }).entries()) {
+    for (const [subdirIdx, subdir] of subdirs.entries()) {
+      let entries = [];
+      try { entries = fs.readdirSync(path.join(baseDir, subdir)); } catch { continue; }
+      for (const version of entries) {
+        if (!/^\d+\.\d+\.\d+$/.test(version) || (requestedVersion && version !== requestedVersion)) continue;
+        const versionDir = path.join(baseDir, subdir, version);
+        const sdkPath = path.join(versionDir, 'copilot-sdk', 'index.js');
+        const cliPath = copilotRuntimeEntry(versionDir);
+        if (fs.existsSync(sdkPath) && fs.existsSync(cliPath)) {
+          candidates.push({ version, baseDirIdx, subdirIdx, sdkPath, cliPath });
+        }
+      }
+    }
+  }
+  candidates.sort((a, b) => {
+    const aVersion = a.version.split('.').map(Number);
+    const bVersion = b.version.split('.').map(Number);
+    return bVersion[0] - aVersion[0] || bVersion[1] - aVersion[1] || bVersion[2] - aVersion[2]
+      || a.baseDirIdx - b.baseDirIdx || a.subdirIdx - b.subdirIdx;
+  });
+  if (candidates.length) return candidates[0];
+  const scope = requestedVersion ? `version ${requestedVersion}` : 'a compatible version';
+  throw new Error(`Copilot SDK runtime not found (${scope}). Install Copilot CLI or configure sdkPath and cliPath.`);
+}
+
+export function buildInstalledCopilotClientOptions({
+  cliPath,
+  cwd,
+  baseDirectory,
+  logLevel = 'debug',
+} = {}) {
+  return {
+    connection: {
+      kind: 'stdio',
+      path: cliPath,
+    },
+    mode: 'empty',
+    baseDirectory,
+    useLoggedInUser: true,
+    logLevel,
+    workingDirectory: cwd,
+  };
+}
+
+export async function createInstalledCopilotClient({
+  config = {},
+  cwd,
+  baseDirectory,
+  logLevel = 'debug',
+} = {}) {
+  const paths = resolveInstalledCopilotPaths({ config });
+  const sdk = await import(pathToFileURL(paths.sdkPath).href);
+  if (typeof sdk.CopilotClient !== 'function') throw new Error('CopilotClient not found in installed Copilot SDK exports');
+  const client = new sdk.CopilotClient(buildInstalledCopilotClientOptions({
+    cliPath: paths.cliPath,
+    cwd,
+    baseDirectory,
+    logLevel,
+  }));
+  await client.start();
+  return {
+    client,
+    approveAll: sdk.approveAll,
+    paths,
+    async dispose() {
+      await client.stop?.();
+      await client.dispose?.();
+    },
+  };
+}

package/server/copilot-worker/copilot-attachments.mjs

@@ -0,0 +1,97 @@
+import fs from 'fs';
+
+// Very large base64 payloads risk rejection by the runtime; larger images fall
+// back to a file reference so the agent can read them from disk instead. Same
+// threshold the Claude and Cursor workers use.
+export const MAX_INLINE_IMAGE_BYTES = 5 * 1024 * 1024;
+
+function isImageAttachment(att) {
+  return String(att?.type || '').toLowerCase().startsWith('image/');
+}
+
+function imageFromDataUrl(att) {
+  const dataUrl = String(att?.dataUrl || '').trim();
+  if (!dataUrl.startsWith('data:')) return null;
+  const match = dataUrl.match(/^data:([^;,]+);base64,(.+)$/i);
+  if (!match) return null;
+  const mimeType = String(match[1] || '').trim().toLowerCase();
+  const data = String(match[2] || '').trim();
+  if (!mimeType.startsWith('image/') || !data) return null;
+  return { data, mimeType };
+}
+
+/**
+ * Build the `MessageOptions` payload for `session.send()` from a relay
+ * message.
+ *
+ * Mirrors `buildCursorUserMessage` / `buildClaudeUserContent`: images small
+ * enough to embed travel inline, everything else becomes a reference the
+ * agent's file tools can open, and the server-provided
+ * `attachmentPromptContext` is appended to the prompt. What differs is the
+ * carrier — the Copilot SDK's `MessageOptions.attachments` is a typed union
+ * rather than content blocks:
+ *
+ *   image, embeddable → `{ type: 'blob', data, mimeType, displayName }`
+ *   image, too large  → `{ type: 'file', path, displayName }`
+ *   any other file    → `{ type: 'file', path, displayName }`
+ *
+ * The note lines are kept even though the attachments are structured, because
+ * they are what tells the model the absolute path of a file it may want to
+ * re-read with its own tools — the same reason the siblings emit them.
+ *
+ * Text composition order (identical to the siblings): user text, note lines,
+ * `attachmentPromptContext`, joined by blank lines.
+ */
+export function buildCopilotMessageOptions(message, {
+  fsImpl = fs,
+  maxInlineImageBytes = MAX_INLINE_IMAGE_BYTES,
+} = {}) {
+  const text = String(message?.text || '').trim();
+  const input = Array.isArray(message?.attachments) ? message.attachments : [];
+  const attachments = [];
+  const noteLines = [];
+
+  for (const att of input) {
+    if (!att || typeof att !== 'object') continue;
+    const name = String(att.name || 'attachment').trim() || 'attachment';
+    const mime = String(att.type || 'application/octet-stream').trim() || 'application/octet-stream';
+    const filePath = String(att.path || '').trim();
+
+    if (isImageAttachment(att)) {
+      let blob = null;
+      if (filePath && fsImpl.existsSync(filePath)) {
+        try {
+          const bytes = fsImpl.readFileSync(filePath);
+          if (Buffer.isBuffer(bytes) && bytes.length && bytes.length <= maxInlineImageBytes) {
+            blob = {
+              data: bytes.toString('base64'),
+              mimeType: mime.toLowerCase().startsWith('image/') ? mime.toLowerCase() : 'image/png',
+            };
+          }
+        } catch {
+          blob = null;
+        }
+      }
+      if (!blob) blob = imageFromDataUrl(att);
+      if (blob) {
+        attachments.push({ type: 'blob', data: blob.data, mimeType: blob.mimeType, displayName: name });
+        noteLines.push(`Attached image "${name}" (${mime}) is embedded in this message.`);
+      } else if (filePath) {
+        attachments.push({ type: 'file', path: filePath, displayName: name });
+        noteLines.push(`Attached image "${name}" (${mime}): ${filePath}`);
+      }
+      continue;
+    }
+
+    if (filePath && fsImpl.existsSync(filePath)) {
+      attachments.push({ type: 'file', path: filePath, displayName: name });
+      noteLines.push(`Attached file "${name}" (${mime}): ${filePath}`);
+    }
+  }
+
+  const attachmentPromptContext = String(message?.attachmentPromptContext || '').trim();
+  const textParts = [text];
+  if (noteLines.length) textParts.push(noteLines.join('\n'));
+  if (attachmentPromptContext) textParts.push(attachmentPromptContext);
+  return { prompt: textParts.filter(Boolean).join('\n\n'), attachments };
+}

package/server/copilot-worker/copilot-byok-provider.mjs

@@ -0,0 +1,121 @@
+// BYOK (bring-your-own-key) provider config for the SDK worker.
+//
+// Why this exists at all: on the EXTENSION path the `COPILOT_PROVIDER_*`
+// environment variables are read by the `copilot` CLI's own startup layer,
+// which turns them into the process-wide custom provider. Sessions this worker
+// creates through the SDK never go through that layer — a live probe confirmed
+// the runtime IGNORES those variables for SDK-created sessions — so the same
+// configuration has to be re-expressed in-process as `SessionConfig.provider`
+// (`ProviderConfig`, verified against the bundled runtime 1.0.82 types).
+//
+// The variable names are deliberately NOT re-invented here: they are exactly
+// the ones `applyOpenAIProviderEnvironment()`
+// (server/services/session-worker-launch-service.mjs) writes today, so one
+// relay-side OpenAI configuration drives both engines and the existing
+// secret-env-file plumbing (`WORKER_SECRET_ENV_VARS` already carries
+// `COPILOT_PROVIDER_API_KEY`) keeps working untouched.
+//
+// Note on cost: BYOK usage events report `cost: 0` (the field is the premium
+// multiplier, not money), so nothing here feeds a spend display.
+
+import { resolveModelTokenCeilings } from '../../shared/context-window-fallbacks.mjs';
+
+const DEFAULT_BASE_URL = 'https://api.openai.com/v1';
+
+function text(value) {
+  return String(value ?? '').trim();
+}
+
+/**
+ * A token ceiling override read from the environment.
+ *
+ * `parseInt` is deliberately NOT used: it truncates at the first character it
+ * cannot read, so `1e6` would silently become **1** and `90000.5` would become
+ * 90000 — an escape hatch that quietly does the wrong thing is worse than one
+ * that refuses. An unusable value is logged and IGNORED, falling through to the
+ * shared table and then to the runtime's own default, rather than being
+ * truncated into a number nobody asked for.
+ */
+function tokenCeilingOverride(name, raw, dbg) {
+  const value = text(raw);
+  if (!value) return null;
+  const numeric = Number(value);
+  if (!Number.isInteger(numeric) || numeric <= 0) {
+    dbg(`ignoring ${name}: expected a positive whole number of tokens, got ${JSON.stringify(value)}`);
+    return null;
+  }
+  return numeric;
+}
+
+/**
+ * Prompt/output token ceilings for the model this session will call.
+ *
+ * The runtime resolves these from its own model catalog and falls back to a
+ * synthesized 128k context for a model it does not recognise, which is wrong in
+ * the expensive direction for a large-context model: a long relay conversation
+ * would lose history it never needed to lose.
+ *
+ * The numbers themselves live in `shared/context-window-fallbacks.mjs` — the
+ * same module the Copilot snapshot service and the Cursor worker read — so this
+ * worker cannot disagree with the rest of the relay about how big a model's
+ * window is. The prompt ceiling is derived there as `window − output`.
+ *
+ * An unknown model is left UNSET on purpose: the runtime's own default is a
+ * safe answer, whereas a guessed ceiling that is too HIGH turns early
+ * compaction into hard API errors.
+ */
+export function resolveOpenAiModelTokenLimits(model) {
+  const { maxPromptTokens = null, maxOutputTokens = null } = resolveModelTokenCeilings(model);
+  if (maxPromptTokens === null || maxOutputTokens === null) return {};
+  return { maxPromptTokens, maxOutputTokens };
+}
+
+/**
+ * Build `SessionConfig.provider` from the worker's environment, or null when
+ * this session is not a BYOK session.
+ *
+ * The signal is the same one the extension path uses: the launch service only
+ * writes `COPILOT_PROVIDER_TYPE` for a session whose relay provider is
+ * `openai`, and deletes the whole family otherwise. An API key is required
+ * because a provider config without credentials would silently fail every
+ * model call instead of failing to start.
+ *
+ * `modelId` is deliberately left UNSET. `ProviderConfig.modelId` falls back to
+ * `SessionConfig.model`, so leaving it out is what keeps `session.setModel()`
+ * authoritative for the rest of the session; pinning it here would freeze the
+ * session on the model it was created with and make every later switch a
+ * silent no-op.
+ *
+ * The ceilings are resolved against the model passed in, so a caller that
+ * switches models must rebuild this config — `SessionConfig.provider` is fixed
+ * at session creation and runtime 1.0.82 exposes no way to update it
+ * mid-session (see `copilot-sdk-session-process.mjs`).
+ */
+export function resolveCopilotProviderConfig({ env = process.env, model = '', dbg = () => {} } = {}) {
+  const type = text(env.COPILOT_PROVIDER_TYPE).toLowerCase();
+  if (type !== 'openai') return null;
+  const apiKey = text(env.COPILOT_PROVIDER_API_KEY);
+  if (!apiKey) return null;
+  // The session's live model wins over the configured default: the token
+  // ceilings below have to describe the model that will actually be called.
+  const effectiveModel = text(model) || text(env.COPILOT_MODEL);
+  const wireApi = text(env.COPILOT_PROVIDER_WIRE_API).toLowerCase();
+  const limits = resolveOpenAiModelTokenLimits(effectiveModel);
+  const maxPromptTokens = tokenCeilingOverride(
+    'COPILOT_PROVIDER_MAX_PROMPT_TOKENS', env.COPILOT_PROVIDER_MAX_PROMPT_TOKENS, dbg,
+  ) ?? limits.maxPromptTokens ?? null;
+  const maxOutputTokens = tokenCeilingOverride(
+    'COPILOT_PROVIDER_MAX_OUTPUT_TOKENS', env.COPILOT_PROVIDER_MAX_OUTPUT_TOKENS, dbg,
+  ) ?? limits.maxOutputTokens ?? null;
+  return {
+    type: 'openai',
+    baseUrl: text(env.COPILOT_PROVIDER_BASE_URL) || DEFAULT_BASE_URL,
+    apiKey,
+    // Only the two documented values are forwarded; anything else is a typo in
+    // the relay config and the runtime's own default ("completions") is a
+    // better answer than a rejected session config.
+    ...(wireApi === 'responses' || wireApi === 'completions' ? { wireApi } : {}),
+    ...(maxPromptTokens ? { maxPromptTokens } : {}),
+    ...(maxOutputTokens ? { maxOutputTokens } : {}),
+  };
+}