@xn-intenton-z2a/agentic-lib 7.2.5 → 7.2.7

package/src/copilot/context.js

@@ -0,0 +1,318 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2025-2026 Polycode Limited
+// src/copilot/context.js — Context gathering and user prompt assembly
+//
+// Builds user prompts for each agent type from available local and GitHub context.
+// Works with or without GitHub data — local-only context is always sufficient.
+
+import { resolve } from "path";
+import { execSync } from "child_process";
+import { scanDirectory, readOptionalFile, extractFeatureSummary, formatPathsSection, summariseIssue, filterIssues } from "./session.js";
+import { defaultLogger } from "./logger.js";
+
+/**
+ * Context requirements per agent. Defines what context each agent needs.
+ * All fields are optional — the builder includes whatever is available.
+ */
+const AGENT_CONTEXT = {
+  "agent-iterate": { mission: true, source: true, tests: true, features: true },
+  "agent-discovery": { source: true, tests: true },
+  "agent-issue-resolution": { mission: true, source: true, tests: true, features: true, issues: true },
+  "agent-apply-fix": { source: true, tests: true },
+  "agent-maintain-features": { mission: true, features: true, issues: true },
+  "agent-maintain-library": { library: true, librarySources: true },
+  "agent-ready-issue": { mission: true, features: true, issues: true },
+  "agent-review-issue": { source: true, tests: true, issues: true },
+  "agent-discussion-bot": { mission: true, features: true },
+  "agent-supervisor": { mission: true, features: true, issues: true },
+  "agent-director": { mission: true, features: true, issues: true, source: true, tests: true },
+};
+
+/**
+ * Gather local context from the workspace filesystem.
+ *
+ * @param {string} workspacePath - Path to the workspace
+ * @param {Object} config - Parsed agentic config (from config.js)
+ * @param {Object} [options]
+ * @param {Object} [options.logger]
+ * @returns {Object} Context object with all available local data
+ */
+export function gatherLocalContext(workspacePath, config, { logger = defaultLogger } = {}) {
+  const wsPath = resolve(workspacePath);
+  const paths = config.paths || {};
+  const tuning = config.tuning || {};
+
+  const context = {};
+
+  // Mission
+  const missionPath = paths.mission?.path || "MISSION.md";
+  context.mission = readOptionalFile(resolve(wsPath, missionPath));
+
+  // Source files
+  const sourcePath = paths.source?.path || "src/lib/";
+  const sourceDir = resolve(wsPath, sourcePath);
+  context.sourceFiles = scanDirectory(sourceDir, [".js", ".ts", ".mjs", ".cjs"], {
+    fileLimit: tuning.sourceScan || 10,
+    contentLimit: tuning.sourceContent || 5000,
+    sortByMtime: true,
+    clean: true,
+    outline: true,
+  }, logger);
+
+  // Test files
+  const testsPath = paths.tests?.path || "tests/";
+  const testsDir = resolve(wsPath, testsPath);
+  context.testFiles = scanDirectory(testsDir, [".js", ".ts", ".test.js", ".test.ts", ".spec.js"], {
+    fileLimit: tuning.sourceScan || 10,
+    contentLimit: tuning.testContent || 3000,
+    sortByMtime: true,
+    clean: true,
+  }, logger);
+
+  // Features
+  const featuresPath = paths.features?.path || "features/";
+  const featuresDir = resolve(wsPath, featuresPath);
+  const featureFiles = scanDirectory(featuresDir, [".md"], {
+    fileLimit: tuning.featuresScan || 10,
+    sortByMtime: true,
+  }, logger);
+  context.features = featureFiles.map((f) => extractFeatureSummary(f.content, f.name));
+
+  // Library
+  const libraryPath = paths.library?.path || "library/";
+  const libraryDir = resolve(wsPath, libraryPath);
+  context.libraryFiles = scanDirectory(libraryDir, [".md"], {
+    fileLimit: 10,
+    contentLimit: tuning.documentSummary || 2000,
+  }, logger);
+
+  // Library sources
+  const sourcesPath = paths.librarySources?.path || "SOURCES.md";
+  context.librarySources = readOptionalFile(resolve(wsPath, sourcesPath));
+
+  // Contributing guide
+  const contributingPath = paths.contributing?.path || "CONTRIBUTING.md";
+  context.contributing = readOptionalFile(resolve(wsPath, contributingPath), 2000);
+
+  // Package.json
+  context.packageJson = config.packageJson || readOptionalFile(resolve(wsPath, "package.json"), 3000);
+
+  // Config TOML
+  context.configToml = config.configToml || "";
+
+  // Paths
+  context.writablePaths = config.writablePaths || [];
+  context.readOnlyPaths = config.readOnlyPaths || [];
+
+  // Initial test output
+  try {
+    context.testOutput = execSync("npm test 2>&1", { cwd: wsPath, encoding: "utf8", timeout: 120000 });
+  } catch (err) {
+    context.testOutput = `STDOUT:\n${err.stdout || ""}\nSTDERR:\n${err.stderr || ""}`;
+  }
+
+  return context;
+}
+
+/**
+ * Fetch GitHub context using the `gh` CLI.
+ * Returns null fields when gh is unavailable or data can't be fetched.
+ *
+ * @param {Object} options
+ * @param {number} [options.issueNumber] - Issue number to fetch
+ * @param {number} [options.prNumber] - PR number to fetch
+ * @param {string} [options.discussionUrl] - Discussion URL to fetch
+ * @param {string} [options.workspacePath] - CWD for gh commands
+ * @param {Object} [options.logger]
+ * @returns {Object} GitHub context
+ */
+export function gatherGitHubContext({ issueNumber, prNumber, discussionUrl, workspacePath, logger = defaultLogger } = {}) {
+  const github = { issues: [], issueDetail: null, prDetail: null, discussionDetail: null };
+  const cwd = workspacePath || process.cwd();
+
+  try {
+    // Fetch open issues list
+    const issuesJson = execSync("gh issue list --state open --limit 20 --json number,title,labels,body,createdAt,updatedAt", {
+      cwd,
+      encoding: "utf8",
+      timeout: 30000,
+    });
+    const rawIssues = JSON.parse(issuesJson);
+    github.issues = filterIssues(rawIssues.map((i) => ({
+      number: i.number,
+      title: i.title,
+      body: i.body,
+      labels: i.labels,
+      created_at: i.createdAt,
+      updated_at: i.updatedAt,
+    })));
+  } catch (err) {
+    logger.info(`[context] Could not fetch issues: ${err.message}`);
+  }
+
+  // Fetch specific issue detail
+  if (issueNumber) {
+    try {
+      const issueJson = execSync(`gh issue view ${issueNumber} --json number,title,body,labels,comments,createdAt`, {
+        cwd,
+        encoding: "utf8",
+        timeout: 30000,
+      });
+      github.issueDetail = JSON.parse(issueJson);
+    } catch (err) {
+      logger.info(`[context] Could not fetch issue #${issueNumber}: ${err.message}`);
+    }
+  }
+
+  // Fetch specific PR detail
+  if (prNumber) {
+    try {
+      const prJson = execSync(`gh pr view ${prNumber} --json number,title,body,files,statusCheckRollup`, {
+        cwd,
+        encoding: "utf8",
+        timeout: 30000,
+      });
+      github.prDetail = JSON.parse(prJson);
+    } catch (err) {
+      logger.info(`[context] Could not fetch PR #${prNumber}: ${err.message}`);
+    }
+  }
+
+  // Fetch discussion
+  if (discussionUrl) {
+    try {
+      // Extract discussion number from URL
+      const match = discussionUrl.match(/discussions\/(\d+)/);
+      if (match) {
+        const num = match[1];
+        const discussionJson = execSync(
+          `gh api graphql -f query='{ repository(owner:"{owner}", name:"{repo}") { discussion(number: ${num}) { title body comments(last: 10) { nodes { body author { login } createdAt } } } } }'`,
+          { cwd, encoding: "utf8", timeout: 30000 },
+        );
+        github.discussionDetail = JSON.parse(discussionJson);
+      }
+    } catch (err) {
+      logger.info(`[context] Could not fetch discussion: ${err.message}`);
+    }
+  }
+
+  return github;
+}
+
+/**
+ * Build a user prompt for the given agent from available context.
+ *
+ * @param {string} agentName - Agent name (e.g. "agent-iterate")
+ * @param {Object} localContext - From gatherLocalContext()
+ * @param {Object} [githubContext] - From gatherGitHubContext() (optional)
+ * @param {Object} [options]
+ * @param {Object} [options.tuning] - Tuning config for limits
+ * @returns {string} Assembled user prompt
+ */
+export function buildUserPrompt(agentName, localContext, githubContext, { tuning } = {}) {
+  const needs = AGENT_CONTEXT[agentName] || AGENT_CONTEXT["agent-iterate"];
+  const sections = [];
+
+  // Mission
+  if (needs.mission && localContext.mission) {
+    sections.push(`# Mission\n\n${localContext.mission}`);
+  }
+
+  // Current test state
+  if (localContext.testOutput) {
+    const testPreview = localContext.testOutput.substring(0, 4000);
+    sections.push(`# Current Test State\n\n\`\`\`\n${testPreview}\n\`\`\``);
+  }
+
+  // Source files
+  if (needs.source && localContext.sourceFiles?.length > 0) {
+    const sourceSection = [`# Source Files (${localContext.sourceFiles.length})`];
+    for (const f of localContext.sourceFiles) {
+      sourceSection.push(`## ${f.name}\n\`\`\`\n${f.content}\n\`\`\``);
+    }
+    sections.push(sourceSection.join("\n\n"));
+  }
+
+  // Test files
+  if (needs.tests && localContext.testFiles?.length > 0) {
+    const testSection = [`# Test Files (${localContext.testFiles.length})`];
+    for (const f of localContext.testFiles) {
+      testSection.push(`## ${f.name}\n\`\`\`\n${f.content}\n\`\`\``);
+    }
+    sections.push(testSection.join("\n\n"));
+  }
+
+  // Features
+  if (needs.features && localContext.features?.length > 0) {
+    const featureSection = [`# Features (${localContext.features.length})`];
+    for (const f of localContext.features) {
+      featureSection.push(f);
+    }
+    sections.push(featureSection.join("\n\n"));
+  }
+
+  // Library
+  if (needs.library && localContext.libraryFiles?.length > 0) {
+    const libSection = [`# Library Files (${localContext.libraryFiles.length})`];
+    for (const f of localContext.libraryFiles) {
+      libSection.push(`## ${f.name}\n${f.content}`);
+    }
+    sections.push(libSection.join("\n\n"));
+  }
+
+  // Library sources
+  if (needs.librarySources && localContext.librarySources) {
+    sections.push(`# Sources\n\n${localContext.librarySources}`);
+  }
+
+  // Issues (from GitHub context)
+  if (needs.issues && githubContext?.issues?.length > 0) {
+    const issueSection = [`# Open Issues (${githubContext.issues.length})`];
+    for (const issue of githubContext.issues) {
+      issueSection.push(summariseIssue(issue, tuning?.issueBodyLimit || 500));
+    }
+    sections.push(issueSection.join("\n\n"));
+  }
+
+  // Specific issue detail
+  if (githubContext?.issueDetail) {
+    const issue = githubContext.issueDetail;
+    const issueSection = [`# Issue #${issue.number}: ${issue.title}\n\n${issue.body || "(no body)"}`];
+    if (issue.comments?.length > 0) {
+      issueSection.push("## Comments");
+      for (const c of issue.comments.slice(-10)) {
+        issueSection.push(`**${c.author?.login || "unknown"}**: ${c.body}`);
+      }
+    }
+    sections.push(issueSection.join("\n\n"));
+  }
+
+  // Specific PR detail
+  if (githubContext?.prDetail) {
+    const pr = githubContext.prDetail;
+    const prSection = [`# PR #${pr.number}: ${pr.title}\n\n${pr.body || "(no body)"}`];
+    if (pr.files?.length > 0) {
+      prSection.push(`## Changed Files\n${pr.files.map((f) => `- ${f.path}`).join("\n")}`);
+    }
+    sections.push(prSection.join("\n\n"));
+  }
+
+  // File paths section
+  if (localContext.writablePaths?.length > 0 || localContext.readOnlyPaths?.length > 0) {
+    sections.push(formatPathsSection(
+      localContext.writablePaths || [],
+      localContext.readOnlyPaths || [],
+      { configToml: localContext.configToml, packageJson: localContext.packageJson },
+    ));
+  }
+
+  // Instructions
+  sections.push([
+    "Implement this mission. Read the existing source code and tests,",
+    "make the required changes, run run_tests to verify, and iterate until all tests pass.",
+    "",
+    "Start by reading the existing files, then implement the solution.",
+  ].join("\n"));
+
+  return sections.join("\n\n");
+}

package/src/copilot/hybrid-session.js

@@ -0,0 +1,330 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2025-2026 Polycode Limited
+// src/copilot/hybrid-session.js — Single-session hybrid iterator (Phase 2)
+//
+// Replaces the old multi-session runIterationLoop with a single persistent
+// Copilot SDK session that drives its own tool loop. Hooks provide
+// observability and budget control.
+//
+// Phase 1b: Full tool set, writable-path safety, narrative extraction,
+// rate-limit retry, config-driven context.
+
+import { existsSync, readFileSync } from "fs";
+import { resolve } from "path";
+import { execSync } from "child_process";
+import { defaultLogger } from "./logger.js";
+import { getSDK } from "./sdk.js";
+import { createAgentTools, isPathWritable } from "./tools.js";
+import { readOptionalFile, extractNarrative, NARRATIVE_INSTRUCTION, isRateLimitError, retryDelayMs } from "./session.js";
+
+/**
+ * Format tool arguments for human-readable logging.
+ */
+function formatToolArgs(toolName, args) {
+  if (!args) return "";
+  switch (toolName) {
+    case "view":
+      return args.filePath ? ` → ${args.filePath}` : (args.path ? ` → ${args.path}` : "");
+    case "bash":
+      return args.command ? ` → ${args.command.substring(0, 120)}` : "";
+    case "write_file":
+    case "create_file":
+    case "edit_file":
+      return args.file_path ? ` → ${args.file_path}` : (args.path ? ` → ${args.path}` : "");
+    case "read_file":
+      return args.file_path ? ` → ${args.file_path}` : (args.path ? ` → ${args.path}` : "");
+    case "run_tests":
+      return "";
+    case "run_command":
+      return args.command ? ` → ${args.command.substring(0, 120)}` : "";
+    case "list_files":
+      return args.path ? ` → ${args.path}` : "";
+    case "report_intent":
+      return args.intent ? ` → "${args.intent.substring(0, 80)}"` : "";
+    default: {
+      // Generic: show first string-valued arg
+      const firstVal = Object.values(args).find((v) => typeof v === "string");
+      return firstVal ? ` → ${firstVal.substring(0, 100)}` : "";
+    }
+  }
+}
+
+/**
+ * Run a hybrid iteration: single Copilot SDK session drives mission to completion.
+ *
+ * @param {Object} options
+ * @param {string} options.workspacePath - Path to the workspace
+ * @param {string} [options.model="gpt-5-mini"] - Copilot SDK model
+ * @param {string} [options.githubToken] - COPILOT_GITHUB_TOKEN
+ * @param {Object} [options.tuning] - Tuning config (reasoningEffort, infiniteSessions)
+ * @param {number} [options.timeoutMs=600000] - Session timeout
+ * @param {string} [options.agentPrompt] - Agent system prompt (loaded from agent .md file)
+ * @param {string} [options.userPrompt] - Override user prompt (instead of default mission prompt)
+ * @param {string[]} [options.writablePaths] - Writable paths for tool safety (default: workspace)
+ * @param {number} [options.maxRetries=2] - Max retries on rate-limit errors
+ * @param {Object} [options.logger]
+ * @returns {Promise<HybridResult>}
+ */
+export async function runHybridSession({
+  workspacePath,
+  model = "gpt-5-mini",
+  githubToken,
+  tuning = {},
+  timeoutMs = 600000,
+  agentPrompt,
+  userPrompt,
+  writablePaths,
+  maxRetries = 2,
+  logger = defaultLogger,
+}) {
+  const { CopilotClient, approveAll, defineTool } = await getSDK();
+
+  const copilotToken = githubToken || process.env.COPILOT_GITHUB_TOKEN;
+  if (!copilotToken) {
+    throw new Error("COPILOT_GITHUB_TOKEN is required. Set it in your environment.");
+  }
+
+  const wsPath = resolve(workspacePath);
+
+  // ── Writable paths ──────────────────────────────────────────────────
+  // Default: entire workspace is writable (local CLI mode)
+  const effectiveWritablePaths = writablePaths || [wsPath + "/"];
+
+  // ── Read mission context (only if no userPrompt override) ─────────
+  let missionText;
+  let initialTestOutput;
+  if (!userPrompt) {
+    const missionPath = resolve(wsPath, "MISSION.md");
+    missionText = existsSync(missionPath) ? readFileSync(missionPath, "utf8") : "No MISSION.md found";
+
+    try {
+      initialTestOutput = execSync("npm test 2>&1", { cwd: wsPath, encoding: "utf8", timeout: 120000 });
+    } catch (err) {
+      initialTestOutput = `STDOUT:\n${err.stdout || ""}\nSTDERR:\n${err.stderr || ""}`;
+    }
+  }
+
+  // ── Metrics ─────────────────────────────────────────────────────────
+  const metrics = {
+    toolCalls: [],
+    testRuns: 0,
+    filesWritten: new Set(),
+    errors: [],
+    startTime: Date.now(),
+  };
+
+  // ── Define run_tests tool ───────────────────────────────────────────
+  const runTestsTool = defineTool("run_tests", {
+    description: "Run the test suite (npm test) and return pass/fail with output. Call this after making changes to verify correctness.",
+    parameters: { type: "object", properties: {}, required: [] },
+    handler: async () => {
+      metrics.testRuns++;
+      try {
+        const stdout = execSync("npm test 2>&1", { cwd: wsPath, encoding: "utf8", timeout: 120000 });
+        return { textResultForLlm: `TESTS PASSED:\n${stdout}`, resultType: "success" };
+      } catch (err) {
+        const output = `STDOUT:\n${err.stdout || ""}\nSTDERR:\n${err.stderr || ""}`;
+        return { textResultForLlm: `TESTS FAILED:\n${output}`, resultType: "success" };
+      }
+    },
+  });
+
+  // ── Build full tool set ─────────────────────────────────────────────
+  // 4 standard tools (read_file, write_file, list_files, run_command) + run_tests
+  const agentTools = createAgentTools(effectiveWritablePaths, logger, defineTool);
+  const allTools = [...agentTools, runTestsTool];
+
+  // ── Build system prompt with narrative instruction ─────────────────
+  const basePrompt = agentPrompt || [
+    "You are an autonomous code transformation agent.",
+    "Your workspace is the current working directory.",
+    "Implement the MISSION described in the user prompt.",
+    "Read existing code, write implementations and tests, then run run_tests to verify.",
+    "Keep going until all tests pass or you've exhausted your options.",
+  ].join("\n");
+  const systemPrompt = basePrompt + NARRATIVE_INSTRUCTION;
+
+  // ── Session config ─────────────────────────────────────────────────
+  logger.info(`[hybrid] Creating session (model=${model}, workspace=${wsPath})`);
+
+  const client = new CopilotClient({
+    env: { ...process.env, GITHUB_TOKEN: copilotToken, GH_TOKEN: copilotToken },
+  });
+
+  const sessionConfig = {
+    model,
+    systemMessage: { mode: "replace", content: systemPrompt },
+    tools: allTools,
+    onPermissionRequest: approveAll,
+    workingDirectory: wsPath,
+    hooks: {
+      onPreToolUse: (input) => {
+        const n = metrics.toolCalls.length + 1;
+        const elapsed = ((Date.now() - metrics.startTime) / 1000).toFixed(0);
+        metrics.toolCalls.push({ tool: input.toolName, time: Date.now(), args: input.toolArgs });
+        const detail = formatToolArgs(input.toolName, input.toolArgs);
+        logger.info(`  [tool #${n} +${elapsed}s] ${input.toolName}${detail}`);
+      },
+      onPostToolUse: (input) => {
+        if (/write|edit|create/i.test(input.toolName)) {
+          const path = input.toolArgs?.file_path || input.toolArgs?.path || "unknown";
+          metrics.filesWritten.add(path);
+          logger.info(`    → wrote ${path}`);
+        }
+        if (input.toolName === "run_tests" || input.toolName === "run_command" || input.toolName === "bash") {
+          const result = input.toolResult?.textResultForLlm || input.toolResult || "";
+          const resultStr = typeof result === "string" ? result : JSON.stringify(result);
+          const passed = /TESTS PASSED|passed|✓|0 fail/i.test(resultStr);
+          const failed = /TESTS FAILED|failed|✗|FAIL/i.test(resultStr);
+          if (passed && !failed) {
+            logger.info(`    → tests PASSED`);
+          } else if (failed) {
+            const failMatch = resultStr.match(/(\d+)\s*(failed|fail)/i);
+            logger.info(`    → tests FAILED${failMatch ? ` (${failMatch[1]} failures)` : ""}`);
+          }
+        }
+      },
+      onErrorOccurred: (input) => {
+        metrics.errors.push({ error: input.error, context: input.errorContext, time: Date.now() });
+        logger.error(`  [error] ${input.errorContext}: ${input.error}`);
+        if (input.recoverable) return { errorHandling: "retry", retryCount: 2 };
+        return { errorHandling: "abort" };
+      },
+    },
+  };
+
+  // Infinite sessions for context management
+  if (tuning.infiniteSessions !== false) {
+    sessionConfig.infiniteSessions = { enabled: true };
+  }
+
+  // Reasoning effort
+  if (tuning.reasoningEffort && tuning.reasoningEffort !== "none") {
+    const SUPPORTED = new Set(["gpt-5-mini", "o4-mini"]);
+    if (SUPPORTED.has(model)) {
+      sessionConfig.reasoningEffort = tuning.reasoningEffort;
+    }
+  }
+
+  // ── Create session with rate-limit retry ───────────────────────────
+  let session;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      session = await client.createSession(sessionConfig);
+      logger.info(`[hybrid] Session: ${session.sessionId}`);
+      break;
+    } catch (err) {
+      if (isRateLimitError(err) && attempt < maxRetries) {
+        const delayMs = retryDelayMs(err, attempt);
+        logger.warning(`[hybrid] Rate limit on session creation — waiting ${Math.round(delayMs / 1000)}s (retry ${attempt + 1}/${maxRetries})`);
+        await new Promise((r) => setTimeout(r, delayMs));
+      } else {
+        logger.error(`[hybrid] Failed to create session: ${err.message}`);
+        await client.stop();
+        throw err;
+      }
+    }
+  }
+
+  // ── Token tracking ──────────────────────────────────────────────────
+  let tokensIn = 0;
+  let tokensOut = 0;
+
+  session.on("assistant.usage", (event) => {
+    const inTok = event.data?.inputTokens || 0;
+    const outTok = event.data?.outputTokens || 0;
+    tokensIn += inTok;
+    tokensOut += outTok;
+    if (inTok || outTok) {
+      logger.info(`  [tokens] +${inTok} in / +${outTok} out (cumulative: ${tokensIn} in / ${tokensOut} out)`);
+    }
+  });
+  session.on("assistant.message", (event) => {
+    const content = (event.data?.content || "").trim();
+    if (content) {
+      const firstLine = content.split("\n")[0];
+      const preview = firstLine.length > 200 ? firstLine.substring(0, 200) + "..." : firstLine;
+      logger.info(`  [assistant] ${preview}`);
+    }
+  });
+
+  // ── Try autopilot mode ──────────────────────────────────────────────
+  try {
+    await session.rpc.mode.set({ mode: "autopilot" });
+    logger.info("[hybrid] Autopilot mode: active");
+  } catch {
+    logger.info("[hybrid] Autopilot mode not available — using default mode");
+  }
+
+  // ── Send mission prompt ─────────────────────────────────────────────
+  logger.info("[hybrid] Sending mission...\n");
+
+  const prompt = userPrompt || [
+    `# Mission\n\n${missionText}`,
+    `# Current test state\n\n\`\`\`\n${initialTestOutput.substring(0, 4000)}\n\`\`\``,
+    "",
+    "Implement this mission. Read the existing source code and tests,",
+    "make the required changes, run run_tests to verify, and iterate until all tests pass.",
+    "",
+    "Start by reading the existing files, then implement the solution.",
+  ].join("\n\n");
+
+  const t0 = Date.now();
+  let response;
+  let endReason = "complete";
+
+  // Send with rate-limit retry
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      response = await session.sendAndWait({ prompt }, timeoutMs);
+      break;
+    } catch (err) {
+      if (isRateLimitError(err) && attempt < maxRetries) {
+        const delayMs = retryDelayMs(err, attempt);
+        logger.warning(`[hybrid] Rate limit on sendAndWait — waiting ${Math.round(delayMs / 1000)}s (retry ${attempt + 1}/${maxRetries})`);
+        await new Promise((r) => setTimeout(r, delayMs));
+      } else {
+        logger.error(`[hybrid] Session error: ${err.message}`);
+        response = null;
+        endReason = "error";
+        break;
+      }
+    }
+  }
+  const sessionTime = (Date.now() - t0) / 1000;
+
+  // ── Extract narrative from response ────────────────────────────────
+  const agentContent = response?.data?.content || "";
+  const narrative = extractNarrative(agentContent, null);
+
+  // ── Final test run ──────────────────────────────────────────────────
+  let finalTestsPassed = false;
+  try {
+    execSync("npm test 2>&1", { cwd: wsPath, encoding: "utf8", timeout: 120000 });
+    finalTestsPassed = true;
+  } catch {
+    // Tests still failing
+  }
+
+  // ── Cleanup ─────────────────────────────────────────────────────────
+  await client.stop();
+
+  const totalTime = (Date.now() - metrics.startTime) / 1000;
+
+  return {
+    success: finalTestsPassed,
+    testsPassed: finalTestsPassed,
+    sessionTime: Math.round(sessionTime),
+    totalTime: Math.round(totalTime),
+    toolCalls: metrics.toolCalls.length,
+    testRuns: metrics.testRuns,
+    filesWritten: metrics.filesWritten.size,
+    tokensIn,
+    tokensOut,
+    errors: metrics.errors,
+    endReason,
+    model,
+    narrative,
+    agentMessage: agentContent.substring(0, 500) || null,
+  };
+}

package/src/copilot/logger.js

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2025-2026 Polycode Limited
+// src/copilot/logger.js — Logger abstraction for shared Copilot module
+//
+// In Actions: wraps @actions/core. In CLI: wraps console.
+
+/**
+ * Create a logger instance.
+ * @param {"actions"|"console"} [backend="console"]
+ * @returns {{ info: Function, warning: Function, error: Function, debug: Function }}
+ */
+export function createLogger(backend = "console") {
+  if (backend === "console") {
+    return {
+      info: (...args) => console.log(...args),
+      warning: (...args) => console.warn(...args),
+      error: (...args) => console.error(...args),
+      debug: () => {},
+    };
+  }
+  // "actions" backend — lazy-load @actions/core
+  let _core;
+  const getCore = () => {
+    if (!_core) {
+      try {
+        // Dynamic require — only available in Actions runtime
+        _core = require("@actions/core");
+      } catch {
+        _core = { info: console.log, warning: console.warn, error: console.error, debug: () => {} };
+      }
+    }
+    return _core;
+  };
+  return {
+    info: (...args) => getCore().info(args.join(" ")),
+    warning: (...args) => getCore().warning(args.join(" ")),
+    error: (...args) => getCore().error(args.join(" ")),
+    debug: (...args) => getCore().debug(args.join(" ")),
+  };
+}
+
+/** Default console logger */
+export const defaultLogger = createLogger("console");