@oar-sh/oar 0.9.0

package/.github/extensions/web-relay/skills/reasoning-stream.mjs

@@ -0,0 +1,285 @@
+/**
+ * reasoning-stream.mjs — capture the Copilot SDK's assistant reasoning ("thoughts")
+ * and incremental assistant text via session.on(...) subscriptions, and relay them to
+ * the web server.
+ *
+ * The SDK exposes reasoning as session EVENTS (not hooks):
+ *   - assistant.reasoning        complete reasoning block (fires regardless of streaming flag)
+ *   - assistant.reasoning_delta  token-level reasoning deltas (requires streaming:true at join)
+ *   - assistant.message_delta    token-level assistant text deltas (requires streaming:true)
+ *
+ * Events are still delivered to handlers registered via on() while sendAndWait is in flight,
+ * so we can capture reasoning without abandoning the stable sendAndWait turn path.
+ *
+ * Guards mirror question-routing-hooks.mjs: only relay while a relay turn is active and an
+ * active message exists. Sub-agent thoughts (event.agentId set) are dropped to start.
+ */
+
+// Coalesce reasoning deltas to avoid request floods: emit when >= this many new chars
+// accumulated or a sentence/line boundary is reached.
+const REASONING_DELTA_MIN_CHARS = 24;
+const MAX_THOUGHT_CHARS = 16 * 1024;
+
+function shouldEmitDelta(nextText, previousText) {
+  const next = String(nextText || "");
+  const prev = String(previousText || "");
+  if (!next) return false;
+  if (!prev) return true;
+  if (next === prev) return false;
+  const delta = next.length - prev.length;
+  if (delta >= REASONING_DELTA_MIN_CHARS) return true;
+  if (delta > 0 && /[\n.!?:)]$/.test(next)) return true;
+  if (delta <= 0) return true;
+  return false;
+}
+
+function capThought(text) {
+  const value = String(text || "");
+  if (value.length <= MAX_THOUGHT_CHARS) return value;
+  return value.slice(0, MAX_THOUGHT_CHARS);
+}
+
+function fnv1a32(value) {
+  const text = String(value || "");
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < text.length; index += 1) {
+    hash ^= text.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0).toString(16);
+}
+
+function shouldSkipCompleteReasoning(nextText, previousText) {
+  const next = String(nextText || "");
+  const previous = String(previousText || "");
+  if (!next) return true;
+  if (!previous) return false;
+  if (next === previous) return true;
+  if (!next.startsWith(previous)) return false;
+  const growth = next.length - previous.length;
+  return growth >= 0 && growth < REASONING_DELTA_MIN_CHARS;
+}
+
+function toolThoughtReasoningId(messageId, phase, toolRequests, messageContent) {
+  const tools = (Array.isArray(toolRequests) ? toolRequests : []).map((request) => ({
+    id: String(request?.id || request?.toolCallId || "").trim() || null,
+    name: String(request?.name || request?.toolName || request?.tool || "").trim() || null,
+  }));
+  const fingerprintInput = JSON.stringify({
+    phase: String(phase || "").trim().toLowerCase(),
+    tools,
+    content: String(messageContent || "").trim(),
+  });
+  return `message:${messageId}:tool:${fnv1a32(fingerprintInput)}`;
+}
+
+export function createReasoningStreamHandlers({
+  api,
+  dbg = () => {},
+  getRelayTurnActive,
+  getActiveMessage,
+  notifySubagentAgentId,
+} = {}) {
+  // reasoningId -> accumulated reasoning text (for delta coalescing)
+  const reasoningAccum = new Map();
+  // reasoningId -> last emitted reasoning text (so we only emit meaningful changes)
+  const reasoningLastSent = new Map();
+  // messageId -> last assistant.message.reasoningText we emitted (dedupe repeated final envelopes)
+  const messageReasoningLastSent = new Map();
+  // cumulative assistant text seen via message deltas + last value pushed to /api/stream
+  let messageTextAccum = "";
+  let messageTextLastSent = "";
+  let maxReadableReasoningChars = 0;
+
+  function relayContext() {
+    if (!getRelayTurnActive?.()) return null;
+    const activeMsg = getActiveMessage?.();
+    if (!activeMsg?.id) return null;
+    return activeMsg;
+  }
+
+  function extractAgentId(event) {
+    const agentId = event?.agentId || event?.data?.agentId || null;
+    return agentId ? String(agentId).trim() : null;
+  }
+
+  function isRootAgentEvent(event) {
+    return !extractAgentId(event);
+  }
+
+  function reasoningIdFor(event) {
+    return String(event?.data?.reasoningId || event?.reasoningId || "reasoning").trim() || "reasoning";
+  }
+
+  function noteReadableReasoning(text) {
+    const length = String(text || "").length;
+    if (length > maxReadableReasoningChars) {
+      maxReadableReasoningChars = length;
+    }
+    return length;
+  }
+
+  function isClaudeModel(event) {
+    const model = String(event?.data?.model || event?.model || "").trim().toLowerCase();
+    return model.includes("claude");
+  }
+
+  async function postThought(activeMsg, { reasoningId, text, done, subagentRunId = null }) {
+    try {
+      await api("POST", "/api/thought", {
+        messageId: activeMsg.id,
+        conversationId: activeMsg.conversationId,
+        mode: activeMsg.relayMode || "agent",
+        reasoningId,
+        text: capThought(text),
+        done: !!done,
+        subagentRunId: subagentRunId || undefined,
+      });
+    } catch (error) {
+      dbg("relay thought publish failed", `msgId=${activeMsg.id}`, `reasoningId=${reasoningId}`, error?.message || String(error));
+    }
+  }
+
+  async function onReasoning(event) {
+    const activeMsg = relayContext();
+    if (!activeMsg) return;
+    const subagentRunId = extractAgentId(event);
+    if (subagentRunId) await notifySubagentAgentId?.(subagentRunId);
+    const reasoningId = reasoningIdFor(event);
+    const text = String(event?.data?.content ?? event?.data?.text ?? "");
+    if (!text) return;
+    const lastSent = reasoningLastSent.get(reasoningId) || "";
+    if (shouldSkipCompleteReasoning(text, lastSent)) {
+      reasoningAccum.delete(reasoningId);
+      return;
+    }
+    // The complete block is authoritative — clear delta bookkeeping for this id.
+    reasoningAccum.delete(reasoningId);
+    reasoningLastSent.set(reasoningId, text);
+    noteReadableReasoning(text);
+    await postThought(activeMsg, { reasoningId, text, done: true, subagentRunId });
+  }
+
+  async function onReasoningDelta(event) {
+    const activeMsg = relayContext();
+    if (!activeMsg) return;
+    const subagentRunId = extractAgentId(event);
+    if (subagentRunId) await notifySubagentAgentId?.(subagentRunId);
+    const reasoningId = reasoningIdFor(event);
+    const deltaContent = String(event?.data?.deltaContent ?? event?.data?.delta ?? "");
+    if (!deltaContent) return;
+    const accumulated = (reasoningAccum.get(reasoningId) || "") + deltaContent;
+    reasoningAccum.set(reasoningId, accumulated);
+    const lastSent = reasoningLastSent.get(reasoningId) || "";
+    if (!shouldEmitDelta(accumulated, lastSent)) return;
+    reasoningLastSent.set(reasoningId, accumulated);
+    noteReadableReasoning(accumulated);
+    await postThought(activeMsg, { reasoningId, text: accumulated, done: false, subagentRunId });
+  }
+
+  async function onMessage(event) {
+    const activeMsg = relayContext();
+    if (!activeMsg) return;
+    const subagentRunId = extractAgentId(event);
+    if (subagentRunId) await notifySubagentAgentId?.(subagentRunId);
+    const messageId = String(event?.data?.messageId || event?.messageId || "").trim();
+    const phase = String(event?.data?.phase || event?.phase || "").trim().toLowerCase();
+    const toolRequests = Array.isArray(event?.data?.toolRequests) ? event.data.toolRequests : [];
+    const messageContent = String(event?.data?.content ?? event?.data?.text ?? "");
+    const reasoningText = String(event?.data?.reasoningText ?? "");
+    if (!messageId) return;
+
+    const lastSent = messageReasoningLastSent.get(messageId) || "";
+    const hasToolThought = toolRequests.length > 0 && !phase.includes("final") && !!messageContent;
+    if (hasToolThought) {
+      if (lastSent === messageContent) return;
+      messageReasoningLastSent.set(messageId, messageContent);
+      noteReadableReasoning(messageContent);
+      await postThought(activeMsg, {
+        reasoningId: toolThoughtReasoningId(messageId, phase, toolRequests, messageContent),
+        text: messageContent,
+        done: true,
+        subagentRunId,
+      });
+      return;
+    }
+
+    if (!reasoningText || lastSent === reasoningText) return;
+
+    const previousMax = maxReadableReasoningChars;
+    const reasoningChars = reasoningText.length;
+    const readableReasoningAlreadySeen = previousMax > 0;
+    const isMeaningfulUpgrade = reasoningChars > (previousMax + REASONING_DELTA_MIN_CHARS);
+    const shouldPublish = !readableReasoningAlreadySeen || (!isClaudeModel(event) && isMeaningfulUpgrade);
+    if (!shouldPublish) return;
+
+    messageReasoningLastSent.set(messageId, reasoningText);
+    noteReadableReasoning(reasoningText);
+    await postThought(activeMsg, {
+      reasoningId: `message:${messageId}`,
+      text: reasoningText,
+      done: true,
+      subagentRunId,
+    });
+  }
+
+  async function onMessageDelta(event) {
+    const activeMsg = relayContext();
+    if (!activeMsg) return;
+    const subagentRunId = extractAgentId(event);
+    if (subagentRunId) await notifySubagentAgentId?.(subagentRunId);
+    const deltaContent = String(event?.data?.deltaContent ?? event?.data?.delta ?? "");
+    if (!deltaContent) return;
+    messageTextAccum += deltaContent;
+    if (!shouldEmitDelta(messageTextAccum, messageTextLastSent)) return;
+    messageTextLastSent = messageTextAccum;
+    try {
+      await api("POST", "/api/stream", {
+        messageId: activeMsg.id,
+        conversationId: activeMsg.conversationId,
+        mode: activeMsg.relayMode || "agent",
+        text: messageTextAccum,
+        done: false,
+        subagentRunId: subagentRunId || undefined,
+      });
+    } catch (error) {
+      dbg("relay stream (message_delta) publish failed", `msgId=${activeMsg.id}`, error?.message || String(error));
+    }
+  }
+
+  // Clear per-turn accumulators. Call when a relay turn ends.
+  function reset() {
+    reasoningAccum.clear();
+    reasoningLastSent.clear();
+    messageReasoningLastSent.clear();
+    messageTextAccum = "";
+    messageTextLastSent = "";
+    maxReadableReasoningChars = 0;
+  }
+
+  // Subscribe to the session events. Returns an unsubscribe function.
+  function attach(session) {
+    if (!session || typeof session.on !== "function") {
+      dbg("reasoning-stream attach skipped: session.on unavailable");
+      return () => {};
+    }
+    const subscriptions = [
+      session.on("assistant.reasoning", onReasoning),
+      session.on("assistant.reasoning_delta", onReasoningDelta),
+      session.on("assistant.message", onMessage),
+      session.on("assistant.message_delta", onMessageDelta),
+    ];
+    dbg("reasoning-stream attached", `sessionId=${session?.sessionId || "(none)"}`);
+    return () => {
+      for (const unsubscribe of subscriptions) {
+        try {
+          if (typeof unsubscribe === "function") unsubscribe();
+        } catch (error) {
+          dbg("reasoning-stream unsubscribe failed", error?.message || String(error));
+        }
+      }
+    };
+  }
+
+  return { onReasoning, onReasoningDelta, onMessage, onMessageDelta, reset, attach };
+}

package/.github/extensions/web-relay/skills/subagent-lifecycle.mjs

@@ -0,0 +1,345 @@
+import { extractToolName, toolArgsSnapshot, parseMaybeJson } from "./tool-activity.mjs";
+
+function extractAgentIdFromRequest(request) {
+  const agentId = request?.agentId || request?.data?.agentId || null;
+  return agentId ? String(agentId).trim() : null;
+}
+
+function extractToolCallId(request) {
+  const candidates = [
+    request?.toolCallId,
+    request?.id,
+    request?.toolCall?.id,
+    request?.toolCall?.toolCallId,
+  ];
+  for (const value of candidates) {
+    const id = String(value || "").trim();
+    if (id) return id;
+  }
+  return null;
+}
+
+function isSubagentSpawnTool(request) {
+  const name = extractToolName(request).toLowerCase();
+  if (!name) return false;
+  return name.includes("execution_subagent")
+    || name === "task"
+    || name.includes("subagent")
+    || name.includes("launch_subagent");
+}
+
+function extractSubagentDisplayName(request) {
+  const args = toolArgsSnapshot(request);
+  const candidates = [
+    args?.description,
+    args?.subagent_type,
+    args?.subagentType,
+    args?.name,
+    args?.title,
+    args?.agent_type,
+    args?.agentType,
+  ];
+  for (const value of candidates) {
+    const text = String(value || "").trim();
+    if (text) return text.slice(0, 120);
+  }
+  return null;
+}
+
+function extractSubagentRunIdFromArgs(request) {
+  const args = toolArgsSnapshot(request);
+  const candidates = [
+    args?.subagentRunId,
+    args?.runId,
+    args?.agentId,
+    args?.resume,
+    args?.id,
+  ];
+  for (const value of candidates) {
+    const id = String(value || "").trim();
+    if (id) return id;
+  }
+  return null;
+}
+
+function extractSubagentRunIdFromResult(result) {
+  const parsed = parseMaybeJson(result);
+  const sources = [result, parsed, parsed?.data, parsed?.result, parsed?.output].filter(Boolean);
+  for (const source of sources) {
+    if (typeof source === "string") {
+      const id = source.trim();
+      if (/^[0-9a-f-]{8,}$/i.test(id)) return id;
+      continue;
+    }
+    if (!source || typeof source !== "object") continue;
+    const candidates = [
+      source.subagentRunId,
+      source.agentId,
+      source.runId,
+      source.id,
+      source.agent?.id,
+      source.agent?.agentId,
+    ];
+    for (const value of candidates) {
+      const id = String(value || "").trim();
+      if (id) return id;
+    }
+  }
+  return null;
+}
+
+export function createSubagentLifecycleHandlers({
+  api,
+  dbg = () => {},
+  getRelayTurnActive,
+  getActiveMessage,
+} = {}) {
+  /** @type {Map<string, { status: string, parentSubagentId: string|null, displayName: string|null, messageId: string }>} */
+  const knownRuns = new Map();
+  /** @type {Map<string, { parentSubagentId: string|null, displayName: string|null }>} */
+  const pendingByToolCallId = new Map();
+  /** @type {Array<{ parentSubagentId: string|null, displayName: string|null, toolCallId: string|null }>} */
+  const pendingSpawns = [];
+
+  async function postSubagentRun(activeMsg, payload) {
+    if (!activeMsg?.id || !activeMsg?.conversationId) return;
+    const subagentRunId = String(payload?.subagentRunId || "").trim();
+    if (!subagentRunId) return;
+    try {
+      await api("POST", "/api/subagent-run", {
+        messageId: activeMsg.id,
+        conversationId: activeMsg.conversationId,
+        subagentRunId,
+        parentSubagentId: payload?.parentSubagentId || undefined,
+        displayName: payload?.displayName || undefined,
+        status: payload?.status || "running",
+      });
+    } catch (error) {
+      dbg(
+        "subagent-run publish failed",
+        `msgId=${activeMsg.id}`,
+        `runId=${subagentRunId.slice(0, 8)}`,
+        error?.message || String(error),
+      );
+    }
+  }
+
+  async function registerSubagentRun(activeMsg, subagentRunId, {
+    parentSubagentId = null,
+    displayName = null,
+    status = "running",
+  } = {}) {
+    const id = String(subagentRunId || "").trim();
+    if (!id || !activeMsg?.id) return;
+
+    const normalizedParent = parentSubagentId ? String(parentSubagentId).trim() : null;
+    const normalizedName = displayName ? String(displayName).trim().slice(0, 120) : null;
+    const existing = knownRuns.get(id);
+    const nextStatus = String(status || "running").trim().toLowerCase();
+
+    if (existing
+      && existing.status === nextStatus
+      && existing.parentSubagentId === normalizedParent
+      && existing.displayName === normalizedName
+      && existing.messageId === activeMsg.id) {
+      return;
+    }
+
+    knownRuns.set(id, {
+      status: nextStatus,
+      parentSubagentId: normalizedParent,
+      displayName: normalizedName,
+      messageId: activeMsg.id,
+    });
+
+    await postSubagentRun(activeMsg, {
+      subagentRunId: id,
+      parentSubagentId: normalizedParent,
+      displayName: normalizedName,
+      status: nextStatus,
+    });
+  }
+
+  function consumePendingSpawn({ parentSubagentId = null, toolCallId = null } = {}) {
+    if (toolCallId && pendingByToolCallId.has(toolCallId)) {
+      const pending = pendingByToolCallId.get(toolCallId);
+      pendingByToolCallId.delete(toolCallId);
+      return pending;
+    }
+    if (pendingSpawns.length === 1) {
+      return pendingSpawns.shift();
+    }
+    if (pendingSpawns.length > 1) {
+      const idx = pendingSpawns.findIndex((entry) => entry.parentSubagentId === parentSubagentId);
+      if (idx >= 0) return pendingSpawns.splice(idx, 1)[0];
+    }
+    return null;
+  }
+
+  async function ensureFromAgentId(subagentRunId, {
+    parentSubagentId = null,
+    displayName = null,
+    toolCallId = null,
+  } = {}) {
+    if (!getRelayTurnActive?.()) return;
+    const activeMsg = getActiveMessage?.();
+    if (!activeMsg?.id) return;
+
+    const id = String(subagentRunId || "").trim();
+    if (!id) return;
+
+    let resolvedParent = parentSubagentId ? String(parentSubagentId).trim() : null;
+    let resolvedName = displayName ? String(displayName).trim().slice(0, 120) : null;
+
+    if (!knownRuns.has(id)) {
+      const pending = consumePendingSpawn({ parentSubagentId: resolvedParent, toolCallId });
+      if (pending) {
+        resolvedParent = resolvedParent || pending.parentSubagentId || null;
+        resolvedName = resolvedName || pending.displayName || null;
+      }
+    } else {
+      // Re-discovery of a known run (e.g. its next tool call) must not demote
+      // it to a root or rename it — keep the established parent/name.
+      const existing = knownRuns.get(id);
+      resolvedParent = resolvedParent || existing.parentSubagentId || null;
+      resolvedName = resolvedName || existing.displayName || null;
+    }
+
+    await registerSubagentRun(activeMsg, id, {
+      parentSubagentId: resolvedParent,
+      displayName: resolvedName || `Subagent ${id.slice(0, 8)}`,
+      status: "running",
+    });
+  }
+
+  async function onPreToolUse(request) {
+    if (!getRelayTurnActive?.()) return;
+    const activeMsg = getActiveMessage?.();
+    if (!activeMsg?.id) return;
+
+    const callerAgentId = extractAgentIdFromRequest(request);
+    if (callerAgentId) {
+      await ensureFromAgentId(callerAgentId, { parentSubagentId: null });
+    }
+
+    if (!isSubagentSpawnTool(request)) return;
+
+    const toolCallId = extractToolCallId(request);
+    const parentSubagentId = callerAgentId || null;
+    const displayName = extractSubagentDisplayName(request);
+    const runIdFromArgs = extractSubagentRunIdFromArgs(request);
+
+    const pending = { parentSubagentId, displayName, toolCallId };
+    pendingSpawns.push(pending);
+    if (toolCallId) pendingByToolCallId.set(toolCallId, pending);
+
+    if (runIdFromArgs) {
+      await registerSubagentRun(activeMsg, runIdFromArgs, {
+        parentSubagentId,
+        displayName: displayName || `Subagent ${runIdFromArgs.slice(0, 8)}`,
+        status: "running",
+      });
+      if (toolCallId) pendingByToolCallId.delete(toolCallId);
+      const idx = pendingSpawns.indexOf(pending);
+      if (idx >= 0) pendingSpawns.splice(idx, 1);
+    }
+  }
+
+  async function onPostToolUse(request, result) {
+    if (!getRelayTurnActive?.()) return;
+    const activeMsg = getActiveMessage?.();
+    if (!activeMsg?.id) return;
+
+    if (!isSubagentSpawnTool(request)) return;
+
+    const toolCallId = extractToolCallId(request);
+    const parentSubagentId = extractAgentIdFromRequest(request) || null;
+    const displayName = extractSubagentDisplayName(request);
+    const runId = extractSubagentRunIdFromResult(result) || extractSubagentRunIdFromArgs(request);
+    if (!runId) return;
+
+    if (toolCallId) pendingByToolCallId.delete(toolCallId);
+    const idx = pendingSpawns.findIndex((entry) => entry.toolCallId === toolCallId);
+    if (idx >= 0) pendingSpawns.splice(idx, 1);
+
+    await registerSubagentRun(activeMsg, runId, {
+      parentSubagentId,
+      displayName: displayName || `Subagent ${runId.slice(0, 8)}`,
+      status: "running",
+    });
+  }
+
+  async function finalizeTurn(activeMsg) {
+    if (!activeMsg?.id) return;
+    const messageId = activeMsg.id;
+    for (const [runId, entry] of knownRuns.entries()) {
+      if (entry.messageId !== messageId) continue;
+      if (entry.status === "cancelled" || entry.status === "failed") continue;
+      if (entry.status === "completed") continue;
+      await postSubagentRun(activeMsg, {
+        subagentRunId: runId,
+        parentSubagentId: entry.parentSubagentId,
+        displayName: entry.displayName,
+        status: "completed",
+      });
+    }
+  }
+
+  function reset() {
+    knownRuns.clear();
+    pendingByToolCallId.clear();
+    pendingSpawns.length = 0;
+  }
+
+  function attach(session) {
+    if (!session || typeof session.on !== "function") return () => {};
+    const eventNames = [
+      "agent.start",
+      "agent.end",
+      "agent.spawn",
+      "execution.subagent.start",
+      "execution.subagent.end",
+    ];
+    const subscriptions = [];
+    for (const eventName of eventNames) {
+      subscriptions.push(session.on(eventName, async (event) => {
+        const activeMsg = getActiveMessage?.();
+        if (!getRelayTurnActive?.() || !activeMsg?.id) return;
+        const subagentRunId = extractAgentIdFromRequest(event)
+          || String(event?.data?.subagentRunId || event?.data?.runId || "").trim()
+          || null;
+        if (!subagentRunId) return;
+        const parentSubagentId = String(event?.data?.parentAgentId || event?.data?.parentSubagentId || "").trim() || null;
+        const displayName = String(event?.data?.displayName || event?.data?.name || "").trim() || null;
+        const isEnd = eventName.includes(".end");
+        if (isEnd) {
+          await registerSubagentRun(activeMsg, subagentRunId, {
+            parentSubagentId,
+            displayName,
+            status: "completed",
+          });
+          return;
+        }
+        await ensureFromAgentId(subagentRunId, { parentSubagentId, displayName });
+      }));
+    }
+    return () => {
+      for (const unsubscribe of subscriptions) {
+        try {
+          if (typeof unsubscribe === "function") unsubscribe();
+        } catch {
+          // ignore
+        }
+      }
+    };
+  }
+
+  return {
+    ensureFromAgentId,
+    onPreToolUse,
+    onPostToolUse,
+    finalizeTurn,
+    reset,
+    attach,
+  };
+}