@oar-sh/oar 0.9.0

package/server/copilot-worker/copilot-continuation-signals.mjs

@@ -0,0 +1,349 @@
+// Pure signal extraction for self-initiated (continuation) turns.
+//
+// The Copilot runtime can start a turn with nobody asking it to. The shape that
+// motivated this module, captured live on 2026-08-31 (session `10a1a9ad`,
+// gpt-5.6-luna, "set a timer to 1 minute"):
+//
+//   user prompt → bash{mode:"async", detach:true} → tool.execution_complete
+//                 "<command started in detached background with shellId: 1>"
+//               → assistant.message "Timer set for 1 minute…" → session.idle
+//   ── the worker settles the row here, correctly ──
+//   60s later:  system.notification{kind:{type:"shell_detached_completed", shellId:"1"}}
+//               → assistant.turn_start → read_bash{shellId:"1"}
+//               → assistant.message "⏰ The 1-minute timer fired." → session.idle
+//
+// Everything after the notification arrived with **no active turn**, so the
+// worker dropped it and the user never saw the reply. Worse, the 10-minute idle
+// shutdown would have killed the detached shell outright had the timer been
+// longer. This module supplies the three signals the runner needs to fix that,
+// with no I/O and no SDK import so they can be unit-tested against real event
+// payloads:
+//
+//  1. `createBackgroundShellTracker` — which detached shells are still live
+//     (lifecycle pinning), and when one settles (a continuation is due).
+//  2. `isContinuationOpeningEvent` — the runtime has started work of its own.
+//  3. `createReplayGate` — the events a `session.resume` replays are history,
+//     not new work, and must never open a continuation row.
+//
+// ## Why detached shells rather than `session.background_tasks_changed`
+//
+// `BackgroundTasksChangedEvent` exists and fires (~23 times during a single
+// bash call), but its `data` is documented as an **empty payload** —
+// "indicating background task state changed", with no task list, no id and no
+// state. It cannot answer "is anything still running?", which is the only
+// question lifecycle pinning has. The typed, id-carrying signals are the shell
+// ones, so those are what this tracks:
+//
+//  - opened: a `bash` `tool.execution_complete` whose telemetry says
+//    `detached: "true"` and/or whose result text names the new shell id;
+//  - settled: `system.notification` with a `shell_detached_completed` /
+//    `shell_completed` `kind` — a discriminated union carrying `shellId`;
+//  - closed by hand: a `read_bash` result reporting the exit code, or a
+//    successful `stop_bash`.
+//
+// The set is a best-effort superset-free view: a shell this module never learns
+// about simply is not pinned (the old behaviour), and a shell it never learns
+// the end of is released by the runner's cap. Neither can wedge a turn.
+
+/** `system.notification` kinds that mean "a shell this session started is done". */
+export const SHELL_SETTLED_NOTIFICATION_KINDS = Object.freeze([
+  'shell_detached_completed',
+  'shell_completed',
+]);
+
+/** Tools that address an already-running shell by id. */
+export const SHELL_HANDLE_TOOLS = Object.freeze(['read_bash', 'write_bash', 'stop_bash']);
+
+// `<command started in detached background with shellId: 1>`
+const SHELL_OPENED_RE = /detached\s+(?:background|command)[^<>]*?shellId:\s*([^\s>,]+)/i;
+// `<detached command with shellId: 1 completed with exit code 0>`
+const SHELL_EXITED_RE = /shellId:\s*([^\s>,]+)[^<>]*?completed with exit code/i;
+
+/** Cap on the toolCallId → shell bookkeeping, so a long session cannot grow it forever. */
+const TOOL_CALL_MEMORY = 200;
+
+function eventData(event) {
+  return event && typeof event.data === 'object' && event.data ? event.data : {};
+}
+
+function toolResultText(data) {
+  const result = data?.result;
+  if (!result || typeof result !== 'object') return '';
+  return `${String(result.content || '')}\n${String(result.detailedContent || '')}`;
+}
+
+function normalizeShellId(value) {
+  const id = String(value ?? '').trim();
+  return id && id !== 'undefined' && id !== 'null' ? id : '';
+}
+
+/**
+ * The events that mean "the runtime has started doing something".
+ *
+ * An allowlist, not a denylist: the SDK event set grows between CLI releases
+ * (a live probe already found an undocumented `subagent.configured`), and the
+ * cost of the two directions is not symmetric. A missing opener costs one
+ * dropped continuation — today's behaviour. A spurious opener creates a
+ * synthetic queue row for a housekeeping event and leaves it open until the
+ * stall watchdog fails it, in the user's transcript.
+ *
+ * `session.idle` / `session.error` are deliberately absent: they terminate
+ * turns, and a stray terminator arriving with no turn must stay a no-op rather
+ * than open a row it would immediately close. So are `session.start`,
+ * `session.resume`, `session.shutdown`, `session.background_tasks_changed`,
+ * `pending_messages.modified`, `capabilities.changed` and the `model.*` family,
+ * which is all connection bookkeeping.
+ */
+export const CONTINUATION_OPENING_EVENT_TYPES = Object.freeze([
+  // The runtime picked up a prompt on its own (a resume with
+  // `continuePendingWork`, or a prompt queued inside the runtime that outlived
+  // the interaction it was sent into).
+  'user.message',
+  'assistant.turn_start',
+  'assistant.message_start',
+  'assistant.message_delta',
+  'assistant.message',
+  'assistant.reasoning',
+  'assistant.reasoning_delta',
+  'assistant.intent',
+  'tool.execution_start',
+  'tool.user_requested',
+  'permission.requested',
+  'user_input.requested',
+  'elicitation.requested',
+  'exit_plan_mode.requested',
+  'subagent.started',
+  'skill.invoked',
+]);
+
+const OPENING_TYPES = new Set(CONTINUATION_OPENING_EVENT_TYPES);
+
+export function isContinuationOpeningEvent(event) {
+  return OPENING_TYPES.has(String(event?.type || ''));
+}
+
+/**
+ * Suppress the historical events a `session.resume` replays through the live
+ * event callback.
+ *
+ * `ResumeData` gives both halves of the discriminator, and they are used
+ * together because either alone is unsafe:
+ *
+ *  - `resumeTime` — "ISO 8601 timestamp when the session was resumed". A
+ *    persisted event carries its ORIGINAL `timestamp` (verified against a real
+ *    `events.jsonl`), so anything older than `resumeTime` is history. Alone,
+ *    this would suppress forever if the runtime ever emitted a stale timestamp.
+ *  - `eventCount` — "Total number of persisted events in the session at the
+ *    time of resume". That is an exact ceiling on how many events a replay can
+ *    produce. Alone, a count is fragile: ephemeral events interleave with the
+ *    replay (the resume fixture has 20+ of them in the first second), and
+ *    miscounting by one would eat a live event or admit a replayed one.
+ *
+ * So: suppress events older than `resumeTime`, at most `eventCount` of them,
+ * and disarm at the first event that is not older — the replay is contiguous
+ * and precedes live traffic, so the first live event proves it is over.
+ *
+ * A resume with no `resumeTime`, or `eventCount: 0`, arms nothing at all: a
+ * fresh session has no history to replay, and guessing would be worse than the
+ * status quo.
+ */
+export function createReplayGate() {
+  let window = null;
+
+  function arm(event) {
+    const data = eventData(event);
+    const resumeTime = Date.parse(String(data.resumeTime || ''));
+    const eventCount = Number(data.eventCount);
+    if (!Number.isFinite(resumeTime) || !Number.isFinite(eventCount) || eventCount <= 0) {
+      window = null;
+      return;
+    }
+    window = { resumeTime, remaining: Math.floor(eventCount) };
+  }
+
+  /** True when `event` is a replayed historical event and must be dropped. */
+  function isReplay(event) {
+    if (String(event?.type || '') === 'session.resume') {
+      // The resume event itself is live — it is the thing that arms the window.
+      arm(event);
+      return false;
+    }
+    if (!window) return false;
+    const timestamp = Date.parse(String(event?.timestamp || ''));
+    if (!Number.isFinite(timestamp)) return false;
+    if (timestamp >= window.resumeTime) {
+      window = null;
+      return false;
+    }
+    window.remaining -= 1;
+    if (window.remaining <= 0) window = null;
+    return true;
+  }
+
+  return {
+    isReplay,
+    reset: () => { window = null; },
+    /** Test seam: whether a replay window is currently open. */
+    armed: () => !!window,
+  };
+}
+
+/**
+ * Track the detached shells this session has running.
+ *
+ * `observe(event)` returns what the event changed, so the caller can pin the
+ * runtime's lifecycle and note that a continuation is due without re-parsing.
+ */
+export function createBackgroundShellTracker({ now = () => Date.now() } = {}) {
+  const shells = new Map(); // shellId -> { shellId, description, startedAt }
+  const toolCalls = new Map(); // toolCallId -> { toolName, shellId, description }
+
+  function rememberToolCall(toolCallId, entry) {
+    if (!toolCallId) return;
+    toolCalls.set(toolCallId, entry);
+    // Bounded: a long conversation makes thousands of tool calls and only the
+    // most recent handful are ever looked up.
+    while (toolCalls.size > TOOL_CALL_MEMORY) {
+      const oldest = toolCalls.keys().next().value;
+      toolCalls.delete(oldest);
+    }
+  }
+
+  function open(shellId, description) {
+    const id = normalizeShellId(shellId);
+    if (!id || shells.has(id)) return null;
+    const shell = { shellId: id, description: String(description || '').trim(), startedAt: now() };
+    shells.set(id, shell);
+    return shell;
+  }
+
+  function close(shellId) {
+    const id = normalizeShellId(shellId);
+    if (!id) return null;
+    const shell = shells.get(id) || null;
+    shells.delete(id);
+    // A shell can settle before this tracker ever saw it open (the worker
+    // reconnected mid-flight); report the id anyway so the caller still knows a
+    // continuation is due.
+    return shell || { shellId: id, description: '', startedAt: 0 };
+  }
+
+  /**
+   * `heralded` is true only for the `system.notification` path.
+   *
+   * That notification is the runtime telling ITSELF a shell finished, and it is
+   * what makes it re-invoke the model — so it, and only it, means "a
+   * continuation is imminent". A `read_bash` that reports an exit code closes
+   * the same shell, but it happens INSIDE a turn that already knows: treating
+   * it as a herald would hold the runtime open for the grace window after every
+   * ordinary background command.
+   */
+  function observe(event) {
+    const type = String(event?.type || '');
+    const data = eventData(event);
+    const opened = [];
+    const settled = [];
+    let heralded = false;
+
+    if (type === 'tool.execution_start') {
+      const toolCallId = String(data.toolCallId || '').trim();
+      const toolName = String(data.toolName || '').trim();
+      const args = data.arguments && typeof data.arguments === 'object' ? data.arguments : {};
+      rememberToolCall(toolCallId, {
+        toolName,
+        shellId: normalizeShellId(args.shellId),
+        description: String(args.description || '').trim(),
+      });
+      return { opened, settled, heralded };
+    }
+
+    if (type === 'tool.execution_complete') {
+      const toolCallId = String(data.toolCallId || '').trim();
+      const call = toolCalls.get(toolCallId) || null;
+      toolCalls.delete(toolCallId);
+      const text = toolResultText(data);
+      const detached = String(data.toolTelemetry?.properties?.detached || '') === 'true';
+
+      // The exit report wins over the open report: a `read_bash` whose result
+      // says the command exited is a close, even though its text also matches
+      // the "detached … shellId" shape.
+      const exited = SHELL_EXITED_RE.exec(text);
+      if (exited) {
+        const shell = close(exited[1]);
+        if (shell) settled.push(shell);
+        return { opened, settled, heralded };
+      }
+
+      if (call?.toolName === 'stop_bash' && data.success !== false) {
+        const shell = close(call.shellId);
+        if (shell) settled.push(shell);
+        return { opened, settled, heralded };
+      }
+
+      const started = SHELL_OPENED_RE.exec(text);
+      if (started && data.success !== false) {
+        const shell = open(started[1], call?.description);
+        if (shell) opened.push(shell);
+        return { opened, settled, heralded };
+      }
+      // Telemetry says detached but the result text named no id — nothing to
+      // key on, so it is deliberately not tracked rather than tracked wrongly.
+      return { opened, settled, heralded };
+    }
+
+    if (type === 'system.notification') {
+      const kind = data.kind && typeof data.kind === 'object' ? data.kind : {};
+      if (!SHELL_SETTLED_NOTIFICATION_KINDS.includes(String(kind.type || ''))) {
+        return { opened, settled, heralded };
+      }
+      // The runtime is about to re-invoke the model off the back of this.
+      heralded = true;
+      const shell = close(kind.shellId);
+      if (shell) {
+        settled.push({
+          ...shell,
+          description: shell.description || String(kind.description || '').trim(),
+        });
+      }
+      return { opened, settled, heralded };
+    }
+
+    return { opened, settled, heralded };
+  }
+
+  return {
+    observe,
+    size: () => shells.size,
+    live: () => [...shells.values()],
+    /**
+     * Drop every shell that has been running longer than `capMs`, so a forgotten
+     * background command cannot pin the runtime forever. Returns what it forgot.
+     */
+    expireOlderThan(capMs) {
+      if (!(capMs > 0)) return [];
+      const deadline = now() - capMs;
+      const expired = [];
+      for (const shell of [...shells.values()]) {
+        if (shell.startedAt <= deadline) {
+          shells.delete(shell.shellId);
+          expired.push(shell);
+        }
+      }
+      return expired;
+    },
+    reset() {
+      shells.clear();
+      toolCalls.clear();
+    },
+  };
+}
+
+/** A one-line transcript note for a settled shell, posted into its continuation. */
+export function describeSettledShell(shell) {
+  const id = normalizeShellId(shell?.shellId);
+  const description = String(shell?.description || '').trim();
+  if (!id) return '';
+  return description
+    ? `Background shell ${id} finished: ${description}`
+    : `Background shell ${id} finished`;
+}

package/server/copilot-worker/copilot-plan-board.mjs

@@ -0,0 +1,110 @@
+// The `plan_ready` board: the card that gives the UI its autopilot handoff
+// buttons when a plan-mode turn produces a plan.
+//
+// The payload is byte-compatible with the Claude, Cursor and Grok workers'
+// (`PLAN_BOARD_ACTIONS`, `boardType`, `title`, `recommendedAction`, `context`
+// shape), because the UI renders whatever `actions` the board carries and the
+// relay's action handler maps those ids onto relay modes. Diverging here would
+// mean a Copilot plan card whose buttons behave differently from every other
+// provider's.
+//
+// Copilot has something the Cursor and Grok workers do not: a real
+// `onExitPlanModeRequest` hook, so the plan text can be taken from the runtime
+// at the moment the agent finishes planning rather than only guessed from the
+// shape of the final prose. Both paths are wired — the hook is primary, the
+// text heuristic is the fallback — which is the Claude worker's arrangement.
+import { countPlanLikeLines } from '../../shared/plan-lines.mjs';
+
+/**
+ * Kept identical across workers. `exit_only` dismisses; `autopilot` and
+ * `interactive` queue a follow-up user message in the mapped relay mode.
+ */
+export const PLAN_BOARD_ACTIONS = [
+  { id: 'autopilot', label: 'Implement in autopilot', mode: 'autopilot' },
+  { id: 'interactive', label: 'Stop here and prompt myself', mode: 'agent' },
+  { id: 'exit_only', label: 'Stop here', mode: 'agent' },
+];
+
+/**
+ * How many list-ish lines a final message needs before it is treated as a plan.
+ * Same threshold as the siblings; `countPlanLikeLines` is the shared predicate.
+ */
+export const PLAN_LINE_THRESHOLD = 2;
+
+/** Returns null when there is nothing worth posting — the caller then skips. */
+export function buildCopilotPlanReadyBoardPayload({
+  message,
+  planText = '',
+  source = 'plan-mode-fallback',
+} = {}) {
+  const summary = String(planText || '').trim();
+  if (!summary) return null;
+  return {
+    queueId: message?.id,
+    messageId: message?.id,
+    conversationId: message?.conversationId,
+    mode: message?.relayMode || 'agent',
+    boardType: 'plan_ready',
+    title: 'Plan ready for review',
+    body: summary,
+    actions: PLAN_BOARD_ACTIONS,
+    recommendedAction: null,
+    context: {
+      source,
+      queueMessageId: message?.id || null,
+      conversationId: message?.conversationId || null,
+      relayMode: message?.relayMode || 'agent',
+    },
+  };
+}
+
+/**
+ * Should the fallback path post a board for this finished turn?
+ *
+ * Gated on plan AND ask, which is one mode wider than the Cursor worker (plan
+ * only). The board's real precondition is "the work is described but not
+ * started", and in plan mode that is guaranteed — mutating tools are denied
+ * outright. In ask mode it is NOT: the user can approve a tool, so a turn there
+ * can genuinely do the work and then summarise it in bullets. Offering
+ * "Implement in autopilot" for work already done would be worse than offering
+ * nothing, so ask mode additionally requires that nothing was actually
+ * approved (`acted`).
+ */
+export function shouldPostPlanBoard({
+  relayMode,
+  finalText,
+  alreadyPosted = false,
+  acted = false,
+} = {}) {
+  if (alreadyPosted) return false;
+  const mode = String(relayMode || '').trim().toLowerCase();
+  if (mode !== 'plan' && mode !== 'ask') return false;
+  if (mode === 'ask' && acted) return false;
+  return countPlanLikeLines(finalText) >= PLAN_LINE_THRESHOLD;
+}
+
+/**
+ * The text the runtime handed to `onExitPlanModeRequest`. `planContent` is the
+ * full plan when the runtime has it; `summary` is always present.
+ */
+export function planTextFromExitRequest(request) {
+  return String(request?.planContent || request?.summary || '').trim();
+}
+
+/**
+ * Returned to the runtime after a board is posted.
+ *
+ * `approved: false` deliberately — approving exit-plan-mode tells the runtime
+ * the user accepted the plan, and the SAME turn then rolls straight into
+ * implementing it while the board is still sitting unanswered in the UI. The
+ * feedback explains the situation so the agent closes out instead of treating
+ * the refusal as an obstacle to route around. Mirrors the Claude worker's
+ * `EXIT_PLAN_DENY_MESSAGE`.
+ */
+export const EXIT_PLAN_BOARD_POSTED_FEEDBACK =
+  'Plan received — it is shown to the user in the relay for review. End the turn now with a short '
+  + 'closing message and do not start implementing; the user\'s decision will arrive as a new message.';
+
+export const EXIT_PLAN_NO_BOARD_FEEDBACK =
+  'Plan received, but it could not be shown for review. Restate the complete plan as your final '
+  + 'message, then end the turn without implementing; the user\'s decision will arrive as a new message.';

package/server/copilot-worker/copilot-prompt-context.mjs

@@ -0,0 +1,86 @@
+// Relay prompt context for the SDK worker: the mode marker, the mode's
+// standing instructions, the relay tool guidance, and the live preview-lane
+// block.
+//
+// This mirrors the extension's `createRelayPromptBuilder`
+// (`.github/extensions/web-relay/skills/prompt-context.mjs`) and reuses its
+// text verbatim through `buildModePrompt`, so a conversation reads the same
+// guidance whichever engine ran it. It does NOT reuse the extension's builder
+// wholesale for one reason: that builder also composes the message BODY via its
+// own `buildPrompt`, which renders attachments as a text note. This worker
+// passes real `MessageOptions.attachments` to the runtime
+// (`buildCopilotMessageOptions`), so only the PREFIX is wanted here.
+//
+// Why the relay tool doc applies to this worker at all: `server/relay-tools.md`
+// tells the model to ask through `ask_user` rather than in plain prose, and to
+// restart the relay through the authenticated localhost API. Both are now true
+// on the SDK path — `onUserInputRequest` is bridged to the relay question
+// cards. The preview section is the part that must be live rather than static,
+// which is exactly what `applyPreviewInstructions` swaps in.
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+import {
+  applyPreviewInstructions,
+  createPreviewInstructionsProvider,
+} from '../../shared/preview-instructions.mjs';
+import { buildModePrompt } from '../../.github/extensions/web-relay/skills/prompt-context.mjs';
+import { loadRelayInstructionsFromFile } from '../../.github/extensions/web-relay/runtime/config-loader.mjs';
+
+export { createPreviewInstructionsProvider, loadRelayInstructionsFromFile };
+
+/**
+ * Read `server/relay-tools.md`, honouring the same `COPILOT_WEB_RELAY_TOOLS`
+ * override the extension uses.
+ *
+ * The path is resolved relative to THIS module rather than through the
+ * extension's `resolveRelayPaths`, whose `../../../server` walk is anchored to
+ * the extension's own directory depth and resolves to the wrong place from
+ * `server/copilot-worker/`. A missing file yields '' (the loader swallows the
+ * error), which degrades to "no tool guidance", never to a failed turn.
+ */
+export function loadDefaultRelayToolInstructions({ env = process.env } = {}) {
+  const override = String(env.COPILOT_WEB_RELAY_TOOLS || '').trim();
+  const toolsPath = override
+    || path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'relay-tools.md');
+  return loadRelayInstructionsFromFile(toolsPath);
+}
+
+/**
+ * Build the per-turn relay context prefix.
+ *
+ * The heavy guidance rides along only when the relay mode CHANGED, matching the
+ * extension: repeat turns in one mode stay cheap, and the model is not re-read
+ * its standing instructions every message. The mode marker itself is always
+ * present.
+ *
+ * `agentMode` is threaded to the runtime natively as well
+ * (`copilotAgentModeForRelayMode`); the text is not a substitute for it but a
+ * reinforcement, same as on the extension path.
+ */
+export function createCopilotPromptContextBuilder({
+  toolInstructions = '',
+  getPreviewInstructions = null,
+} = {}) {
+  let lastPromptedRelayMode = null;
+  return async function buildRelayContextPrefix(message) {
+    const relayMode = String(message?.relayMode || 'agent').trim().toLowerCase() || 'agent';
+    const includeInstructions = lastPromptedRelayMode !== relayMode;
+    let instructions = '';
+    if (includeInstructions) {
+      // Advisory: a preview lookup that fails costs the block, never the turn.
+      const previewBlock = typeof getPreviewInstructions === 'function'
+        ? await Promise.resolve().then(getPreviewInstructions).catch(() => '')
+        : '';
+      instructions = applyPreviewInstructions(toolInstructions, previewBlock);
+    }
+    const prefix = buildModePrompt(relayMode, instructions, { includeInstructions });
+    lastPromptedRelayMode = relayMode;
+    return prefix;
+  };
+}
+
+/** Prepend the relay context prefix to a message body built elsewhere. */
+export function withRelayContext(prefix, body) {
+  return [String(prefix || '').trim(), String(body || '').trim()].filter(Boolean).join(' ');
+}