@xn-intenton-z2a/agentic-lib 7.2.6 → 7.2.8

package/src/copilot/sdk.js

@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2025-2026 Polycode Limited
+// src/copilot/sdk.js — Find and import the Copilot SDK
+//
+// The SDK may be in the root node_modules or nested under
+// src/actions/agentic-step/node_modules/. This module handles discovery.
+
+import { existsSync } from "fs";
+import { resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = resolve(__dirname, "../..");
+
+const SDK_LOCATIONS = [
+  resolve(pkgRoot, "node_modules/@github/copilot-sdk/dist/index.js"),
+  resolve(pkgRoot, "src/actions/agentic-step/node_modules/@github/copilot-sdk/dist/index.js"),
+];
+
+let _sdk = null;
+
+/**
+ * Dynamically import the Copilot SDK, searching known locations.
+ * @returns {Promise<{CopilotClient: *, approveAll: *, defineTool: *}>}
+ */
+export async function getSDK() {
+  if (_sdk) return _sdk;
+  const sdkPath = SDK_LOCATIONS.find((p) => existsSync(p));
+  if (!sdkPath) {
+    throw new Error(
+      "@github/copilot-sdk not found. Run: npm ci\nSearched: " + SDK_LOCATIONS.join(", "),
+    );
+  }
+  _sdk = await import(sdkPath);
+  return _sdk;
+}

package/src/copilot/session.js

@@ -0,0 +1,372 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2025-2026 Polycode Limited
+// src/copilot/session.js — Copilot SDK session management (shared between Actions + CLI)
+//
+// Ported from src/actions/agentic-step/copilot.js with logger abstraction
+// replacing direct @actions/core imports.
+
+import { readFileSync, readdirSync, existsSync, statSync } from "fs";
+import { join } from "path";
+import { defaultLogger } from "./logger.js";
+
+// Models known to support the reasoningEffort SessionConfig parameter.
+const MODELS_SUPPORTING_REASONING_EFFORT = new Set(["gpt-5-mini", "o4-mini"]);
+
+// ── Source utilities ────────────────────────────────────────────────
+
+export function cleanSource(raw) {
+  let cleaned = raw;
+  cleaned = cleaned.replace(/^\/\/\s*SPDX-License-Identifier:.*\n/gm, "");
+  cleaned = cleaned.replace(/^\/\/\s*Copyright.*\n/gm, "");
+  cleaned = cleaned.replace(/\n{3,}/g, "\n\n");
+  cleaned = cleaned.replace(/^\s*\/\/\s*eslint-disable.*\n/gm, "");
+  cleaned = cleaned.replace(/^\s*\/\*\s*eslint-disable[\s\S]*?\*\/\s*\n/gm, "");
+  return cleaned.trimStart();
+}
+
+export function generateOutline(raw, filePath) {
+  const lines = raw.split("\n");
+  const sizeKB = (raw.length / 1024).toFixed(1);
+  const parts = [`// file: ${filePath} (${lines.length} lines, ${sizeKB}KB)`];
+
+  const importSources = [];
+  for (const l of lines) {
+    const m = l.match(/^import\s.*from\s+["']([^"']+)["']/);
+    if (m) importSources.push(m[1]);
+  }
+  if (importSources.length > 0) parts.push(`// imports: ${importSources.join(", ")}`);
+
+  const exportNames = [];
+  for (const l of lines) {
+    const m = l.match(/^export\s+(?:default\s+)?(?:async\s+)?(?:function|class|const|let|var)\s+(\w+)/);
+    if (m) exportNames.push(m[1]);
+  }
+  if (exportNames.length > 0) parts.push(`// exports: ${exportNames.join(", ")}`);
+
+  parts.push("//");
+  for (let i = 0; i < lines.length; i++) {
+    const l = lines[i];
+    const funcMatch = l.match(/^(export\s+)?(async\s+)?function\s+(\w+)\s*\(/);
+    if (funcMatch) { parts.push(`// function ${funcMatch[3]}() — line ${i + 1}`); continue; }
+    const classMatch = l.match(/^(export\s+)?(default\s+)?class\s+(\w+)/);
+    if (classMatch) { parts.push(`// class ${classMatch[3]} — line ${i + 1}`); continue; }
+    const methodMatch = l.match(/^\s+(async\s+)?(\w+)\s*\([^)]*\)\s*\{/);
+    if (methodMatch && !["if", "for", "while", "switch", "catch", "try"].includes(methodMatch[2])) {
+      parts.push(`//   ${methodMatch[2]}() — line ${i + 1}`);
+    }
+  }
+  return parts.join("\n");
+}
+
+// ── Issue/feature utilities ─────────────────────────────────────────
+
+export function filterIssues(issues, options = {}) {
+  const { staleDays = 30, excludeBotOnly = true, initTimestamp } = options;
+  const cutoff = Date.now() - staleDays * 86400000;
+  const initEpoch = initTimestamp ? new Date(initTimestamp).getTime() : 0;
+
+  return issues.filter((issue) => {
+    if (initEpoch > 0 && new Date(issue.created_at).getTime() < initEpoch) return false;
+    const lastActivity = new Date(issue.updated_at || issue.created_at).getTime();
+    if (lastActivity < cutoff) return false;
+    if (excludeBotOnly) {
+      const labels = (issue.labels || []).map((l) => (typeof l === "string" ? l : l.name));
+      const botLabels = ["automated", "stale", "bot", "wontfix"];
+      if (labels.length > 0 && labels.every((l) => botLabels.includes(l))) return false;
+    }
+    return true;
+  });
+}
+
+export function summariseIssue(issue, bodyLimit = 500) {
+  const labels = (issue.labels || []).map((l) => (typeof l === "string" ? l : l.name)).join(", ") || "no labels";
+  const age = Math.floor((Date.now() - new Date(issue.created_at).getTime()) / 86400000);
+  const body = (issue.body || "").substring(0, bodyLimit).replace(/\n+/g, " ").trim();
+  return `#${issue.number}: ${issue.title} [${labels}] (${age}d old)${body ? `\n  ${body}` : ""}`;
+}
+
+export function extractFeatureSummary(content, fileName) {
+  const lines = content.split("\n");
+  const title = lines.find((l) => l.startsWith("#"))?.replace(/^#+\s*/, "") || fileName;
+  const checked = (content.match(/- \[x\]/gi) || []).length;
+  const unchecked = (content.match(/- \[ \]/g) || []).length;
+  const total = checked + unchecked;
+  const parts = [`Feature: ${title}`];
+  if (total > 0) {
+    parts.push(`Status: ${checked}/${total} items complete`);
+    const remaining = [];
+    for (const line of lines) {
+      if (/- \[ \]/.test(line)) remaining.push(line.replace(/^[\s-]*\[ \]\s*/, "").trim());
+    }
+    if (remaining.length > 0) parts.push(`Remaining: ${remaining.map((r) => `[ ] ${r}`).join(", ")}`);
+  }
+  return parts.join("\n");
+}
+
+// ── File utilities ──────────────────────────────────────────────────
+
+export function readOptionalFile(filePath, limit) {
+  try {
+    const content = readFileSync(filePath, "utf8");
+    return limit ? content.substring(0, limit) : content;
+  } catch {
+    return "";
+  }
+}
+
+export function scanDirectory(dirPath, extensions, options = {}, logger = defaultLogger) {
+  const { fileLimit = 10, contentLimit, recursive = false, sortByMtime = false, clean = false, outline = false } = options;
+  const exts = Array.isArray(extensions) ? extensions : [extensions];
+  if (!existsSync(dirPath)) return [];
+
+  const allFiles = readdirSync(dirPath, recursive ? { recursive: true } : undefined).filter((f) =>
+    exts.some((ext) => String(f).endsWith(ext)),
+  );
+
+  if (sortByMtime) {
+    allFiles.sort((a, b) => {
+      try { return statSync(join(dirPath, String(b))).mtimeMs - statSync(join(dirPath, String(a))).mtimeMs; }
+      catch { return 0; }
+    });
+  }
+
+  const clipped = allFiles.slice(0, fileLimit);
+  if (allFiles.length > fileLimit) {
+    logger.info(`[scanDirectory] Clipped ${dirPath}: ${allFiles.length} files, returning ${fileLimit}`);
+  }
+
+  return clipped.map((f) => {
+    const fileName = String(f);
+    try {
+      let raw = readFileSync(join(dirPath, fileName), "utf8");
+      if (clean) raw = cleanSource(raw);
+      let content;
+      if (outline && contentLimit && raw.length > contentLimit) {
+        const outlineText = generateOutline(raw, fileName);
+        const halfLimit = Math.floor(contentLimit / 2);
+        content = outlineText + "\n\n" + raw.substring(0, halfLimit);
+      } else {
+        content = contentLimit ? raw.substring(0, contentLimit) : raw;
+      }
+      return { name: fileName, content };
+    } catch {
+      return { name: fileName, content: "" };
+    }
+  });
+}
+
+export function formatPathsSection(writablePaths, readOnlyPaths = [], contextFiles) {
+  const lines = [
+    "## File Paths",
+    "### Writable (you may modify these)",
+    writablePaths.length > 0 ? writablePaths.map((p) => `- ${p}`).join("\n") : "- (none)",
+    "",
+    "### Read-Only (for context only, do NOT modify)",
+    readOnlyPaths.length > 0 ? readOnlyPaths.map((p) => `- ${p}`).join("\n") : "- (none)",
+  ];
+  if (contextFiles?.configToml) {
+    lines.push("", "### Configuration (agentic-lib.toml)", "```toml", contextFiles.configToml, "```");
+  }
+  if (contextFiles?.packageJson) {
+    lines.push("", "### Dependencies (package.json)", "```json", contextFiles.packageJson, "```");
+  }
+  return lines.join("\n");
+}
+
+// ── Narrative ───────────────────────────────────────────────────────
+
+export function extractNarrative(content, fallback) {
+  if (!content) return fallback || "";
+  const match = content.match(/\[NARRATIVE\]\s*(.+)/);
+  if (match) return match[1].trim();
+  return fallback || "";
+}
+
+export const NARRATIVE_INSTRUCTION =
+  "\n\nAfter completing your task, end your response with a line starting with [NARRATIVE] followed by one plain English sentence describing what you did and why, for the activity log.";
+
+// ── Auth ────────────────────────────────────────────────────────────
+
+export function buildClientOptions(githubToken, logger = defaultLogger) {
+  const copilotToken = githubToken || process.env.COPILOT_GITHUB_TOKEN;
+  if (!copilotToken) {
+    throw new Error("COPILOT_GITHUB_TOKEN is required. Set it in your environment.");
+  }
+  logger.info("[copilot] COPILOT_GITHUB_TOKEN found — overriding subprocess env");
+  const env = { ...process.env };
+  env.GITHUB_TOKEN = copilotToken;
+  env.GH_TOKEN = copilotToken;
+  return { env };
+}
+
+// ── Tuning helpers ──────────────────────────────────────────────────
+
+export function supportsReasoningEffort(model) {
+  return MODELS_SUPPORTING_REASONING_EFFORT.has(model);
+}
+
+export function logTuningParam(param, value, profileName, model, clip, logger = defaultLogger) {
+  const clipInfo = clip ? ` (requested=${clip.requested}, available=${clip.available})` : "";
+  logger.info(`[tuning] ${param}=${value} profile=${profileName} model=${model}${clipInfo}`);
+}
+
+// ── Rate limit ──────────────────────────────────────────────────────
+
+export function isRateLimitError(err) {
+  if (!err || typeof err !== "object") return false;
+  const status = err.status ?? err.statusCode ?? err.code;
+  if (status === 429 || status === "429") return true;
+  const msg = (err.message || "").toLowerCase();
+  return msg.includes("429") || msg.includes("too many requests") || msg.includes("rate limit");
+}
+
+export function retryDelayMs(err, attempt, baseDelayMs = 60000) {
+  const retryAfterHeader = err?.headers?.["retry-after"] ?? err?.retryAfter ?? err?.response?.headers?.["retry-after"];
+  if (retryAfterHeader != null) {
+    const parsed = Number(retryAfterHeader);
+    if (!isNaN(parsed) && parsed > 0) return parsed * 1000;
+  }
+  return baseDelayMs * Math.pow(2, attempt);
+}
+
+// ── Core session runner ─────────────────────────────────────────────
+
+/**
+ * Run a Copilot SDK task: create client → session → send prompt → return result.
+ * Retries on 429 rate limits.
+ *
+ * @param {Object} options
+ * @param {string} options.model
+ * @param {string} options.systemMessage
+ * @param {string} options.prompt
+ * @param {string[]} options.writablePaths
+ * @param {string} [options.githubToken]
+ * @param {Object} [options.tuning]
+ * @param {string} [options.profileName]
+ * @param {string} [options.workingDirectory]
+ * @param {number} [options.maxRetries=3]
+ * @param {number} [options.timeoutMs=600000]
+ * @param {Object} [options.hooks] - SDK lifecycle hooks
+ * @param {Object} [options.logger]
+ * @param {Function} [options.createTools] - (defineTool, writablePaths, logger) => Tool[]
+ * @returns {Promise<{content: string, tokensUsed: number, inputTokens: number, outputTokens: number, cost: number}>}
+ */
+export async function runCopilotTask({
+  model,
+  systemMessage,
+  prompt,
+  writablePaths,
+  githubToken,
+  tuning,
+  profileName,
+  workingDirectory,
+  maxRetries = 3,
+  timeoutMs = 600000,
+  hooks,
+  logger = defaultLogger,
+  createTools,
+}) {
+  const profile = profileName || tuning?.profileName || "unknown";
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await _runOnce({
+        model, systemMessage, prompt, writablePaths, githubToken,
+        tuning, profileName: profile, workingDirectory, timeoutMs, hooks, logger, createTools,
+      });
+    } catch (err) {
+      if (isRateLimitError(err) && attempt < maxRetries) {
+        const delayMs = retryDelayMs(err, attempt);
+        logger.warning(`[copilot] Rate limit (429) — waiting ${Math.round(delayMs / 1000)}s before retry ${attempt + 1}/${maxRetries}`);
+        await new Promise((r) => setTimeout(r, delayMs));
+      } else {
+        throw err;
+      }
+    }
+  }
+  throw new Error("[copilot] runCopilotTask: all retry attempts exhausted");
+}
+
+async function _runOnce({
+  model, systemMessage, prompt, writablePaths, githubToken,
+  tuning, profileName, workingDirectory, timeoutMs, hooks, logger, createTools,
+}) {
+  const { getSDK } = await import("./sdk.js");
+  const { CopilotClient, approveAll, defineTool } = await getSDK();
+  const { createAgentTools } = await import("./tools.js");
+
+  logger.info(`[copilot] Creating client (model=${model}, promptLen=${prompt.length}, profile=${profileName})`);
+
+  const clientOptions = buildClientOptions(githubToken, logger);
+  const client = new CopilotClient(clientOptions);
+
+  try {
+    const tools = createTools
+      ? createTools(defineTool, writablePaths, logger)
+      : createAgentTools(writablePaths, logger, defineTool);
+
+    const sessionConfig = {
+      model,
+      systemMessage: { content: systemMessage },
+      tools,
+      onPermissionRequest: approveAll,
+      workingDirectory: workingDirectory || process.cwd(),
+    };
+
+    // Conditional tuning params
+    if (tuning?.reasoningEffort && tuning.reasoningEffort !== "none") {
+      if (supportsReasoningEffort(model)) {
+        sessionConfig.reasoningEffort = tuning.reasoningEffort;
+        logTuningParam("reasoningEffort", tuning.reasoningEffort, profileName, model, null, logger);
+      } else {
+        logger.info(`[copilot] Skipping reasoningEffort="${tuning.reasoningEffort}" — not supported by "${model}"`);
+      }
+    }
+    if (tuning?.infiniteSessions === true) {
+      sessionConfig.infiniteSessions = {};
+      logTuningParam("infiniteSessions", true, profileName, model, null, logger);
+    }
+
+    // Lifecycle hooks (Phase 2)
+    if (hooks) {
+      sessionConfig.hooks = hooks;
+    }
+
+    const session = await client.createSession(sessionConfig);
+    logger.info(`[copilot] Session created: ${session.sessionId}`);
+
+    // Token accumulation via events
+    let totalInputTokens = 0;
+    let totalOutputTokens = 0;
+    let totalCost = 0;
+
+    session.on((event) => {
+      const eventType = event?.type || "unknown";
+      if (eventType === "assistant.message") {
+        const preview = event?.data?.content?.substring(0, 100) || "(no content)";
+        logger.info(`[copilot] event=${eventType}: ${preview}...`);
+      } else if (eventType === "assistant.usage") {
+        const d = event?.data || {};
+        totalInputTokens += d.inputTokens || 0;
+        totalOutputTokens += d.outputTokens || 0;
+        totalCost += d.cost || 0;
+        logger.info(`[copilot] event=${eventType}: input=${d.inputTokens || 0} output=${d.outputTokens || 0}`);
+      } else if (eventType === "session.error") {
+        logger.error(`[copilot] event=${eventType}: ${JSON.stringify(event?.data || event)}`);
+      } else if (eventType !== "session.idle") {
+        logger.debug(`[copilot] event=${eventType}`);
+      }
+    });
+
+    logger.info("[copilot] Sending prompt...");
+    const response = await session.sendAndWait({ prompt }, timeoutMs);
+    logger.info("[copilot] sendAndWait resolved");
+
+    const tokensUsed = totalInputTokens + totalOutputTokens;
+    const content = response?.data?.content || "";
+
+    return { content, tokensUsed, inputTokens: totalInputTokens, outputTokens: totalOutputTokens, cost: totalCost };
+  } finally {
+    await client.stop();
+  }
+}

package/src/copilot/tasks/fix-code.js

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2025-2026 Polycode Limited
+// src/copilot/tasks/fix-code.js — Fix failing tests (shared)
+//
+// In CLI/local mode: runs tests, feeds failures to agent.
+// In Actions mode: can also resolve merge conflicts and PR check failures.
+
+import { execSync } from "child_process";
+import {
+  runCopilotTask, readOptionalFile, scanDirectory, formatPathsSection,
+  extractNarrative, NARRATIVE_INSTRUCTION,
+} from "../session.js";
+import { defaultLogger } from "../logger.js";
+
+/**
+ * Fix failing code — local mode (no GitHub context needed).
+ * Runs tests, feeds failure output to the agent.
+ */
+export async function fixCode(context) {
+  const { config, instructions, writablePaths, testCommand, model, logger = defaultLogger } = context;
+  const t = config.tuning || {};
+  const workDir = context.workingDirectory || process.cwd();
+
+  // Run tests to get failure output
+  let testOutput;
+  let testsPassed = false;
+  try {
+    testOutput = execSync(testCommand, { cwd: workDir, encoding: "utf8", timeout: 120000 });
+    testsPassed = true;
+  } catch (err) {
+    testOutput = `STDOUT:\n${err.stdout || ""}\nSTDERR:\n${err.stderr || ""}`;
+  }
+
+  if (testsPassed) {
+    logger.info("Tests already pass — nothing to fix");
+    return { outcome: "nop", details: "Tests already pass" };
+  }
+
+  const mission = readOptionalFile(config.paths.mission.path);
+  const sourceFiles = scanDirectory(config.paths.source.path, [".js", ".ts"], {
+    fileLimit: t.sourceScan || 10,
+    contentLimit: t.sourceContent || 5000,
+    recursive: true, sortByMtime: true, clean: true,
+  }, logger);
+
+  const agentInstructions = instructions || "Fix the failing tests by modifying the source code.";
+
+  const prompt = [
+    "## Instructions", agentInstructions, "",
+    ...(mission ? ["## Mission", mission, ""] : []),
+    "## Failing Test Output",
+    "```", testOutput.substring(0, 8000), "```", "",
+    `## Current Source Files (${sourceFiles.length})`,
+    ...sourceFiles.map((f) => `### ${f.name}\n\`\`\`\n${f.content}\n\`\`\``), "",
+    formatPathsSection(writablePaths, config.readOnlyPaths, config), "",
+    "## Constraints",
+    `- Run \`${testCommand}\` to validate your fixes`,
+    "- Make minimal changes to fix the failing tests",
+    "- Do not introduce new features — focus on making the build green",
+  ].join("\n");
+
+  const { content: resultContent, tokensUsed, inputTokens, outputTokens, cost } = await runCopilotTask({
+    model,
+    systemMessage: "You are an autonomous coding agent fixing failing tests. Analyze the error output and make minimal, targeted changes to fix it." + NARRATIVE_INSTRUCTION,
+    prompt, writablePaths, tuning: t, logger, workingDirectory: workDir,
+  });
+
+  return {
+    outcome: "fix-applied", tokensUsed, inputTokens, outputTokens, cost, model,
+    details: `Applied fix based on test failures`,
+    narrative: extractNarrative(resultContent, "Fixed failing tests."),
+  };
+}

package/src/copilot/tasks/maintain-features.js

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2025-2026 Polycode Limited
+// src/copilot/tasks/maintain-features.js — Feature lifecycle (shared)
+
+import { existsSync } from "fs";
+import {
+  runCopilotTask, readOptionalFile, scanDirectory, formatPathsSection,
+  extractFeatureSummary, extractNarrative, NARRATIVE_INSTRUCTION,
+} from "../session.js";
+import { defaultLogger } from "../logger.js";
+
+export async function maintainFeatures(context) {
+  const { config, instructions, writablePaths, model, logger = defaultLogger } = context;
+  const t = config.tuning || {};
+
+  if (existsSync("MISSION_COMPLETE.md") && config.supervisor !== "maintenance") {
+    return { outcome: "nop", details: "Mission already complete" };
+  }
+
+  const mission = readOptionalFile(config.paths.mission.path);
+  const featuresPath = config.paths.features.path;
+  const featureLimit = config.paths.features.limit;
+  const features = scanDirectory(featuresPath, ".md", { fileLimit: t.featuresScan || 10 }, logger);
+
+  features.sort((a, b) => {
+    const aInc = /- \[ \]/.test(a.content) ? 0 : 1;
+    const bInc = /- \[ \]/.test(b.content) ? 0 : 1;
+    return aInc - bInc || a.name.localeCompare(b.name);
+  });
+
+  const libraryDocs = scanDirectory(config.paths.library.path, ".md", { contentLimit: t.documentSummary || 1000 }, logger);
+
+  const prompt = [
+    "## Instructions", instructions || "Maintain the feature set by creating, updating, or pruning features.", "",
+    "## Mission", mission, "",
+    `## Current Features (${features.length}/${featureLimit} max)`,
+    ...features.map((f) => `### ${f.name}\n${f.content}`), "",
+    ...(libraryDocs.length > 0 ? [
+      `## Library Documents (${libraryDocs.length})`,
+      ...libraryDocs.map((d) => `### ${d.name}\n${d.content}`), "",
+    ] : []),
+    "## Your Task",
+    `1. Review each existing feature — delete if implemented or irrelevant.`,
+    `2. If fewer than ${featureLimit} features, create new ones aligned with the mission.`,
+    "3. Ensure each feature has clear, testable acceptance criteria.", "",
+    formatPathsSection(writablePaths, config.readOnlyPaths, config), "",
+    "## Constraints", `- Maximum ${featureLimit} feature files`,
+  ].join("\n");
+
+  const { content: resultContent, tokensUsed, inputTokens, outputTokens, cost } = await runCopilotTask({
+    model,
+    systemMessage: "You are a feature lifecycle manager. Create, update, and prune feature specification files to keep the project focused on its mission." + NARRATIVE_INSTRUCTION,
+    prompt, writablePaths, tuning: t, logger,
+  });
+
+  return {
+    outcome: "features-maintained", tokensUsed, inputTokens, outputTokens, cost, model,
+    details: `Maintained features (${features.length} existing, limit ${featureLimit})`,
+    narrative: extractNarrative(resultContent, `Maintained ${features.length} features.`),
+  };
+}

package/src/copilot/tasks/maintain-library.js

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2025-2026 Polycode Limited
+// src/copilot/tasks/maintain-library.js — Library management (shared)
+
+import { existsSync } from "fs";
+import {
+  runCopilotTask, readOptionalFile, scanDirectory, formatPathsSection,
+  extractNarrative, NARRATIVE_INSTRUCTION,
+} from "../session.js";
+import { defaultLogger } from "../logger.js";
+
+export async function maintainLibrary(context) {
+  const { config, instructions, writablePaths, model, logger = defaultLogger } = context;
+  const t = config.tuning || {};
+
+  if (existsSync("MISSION_COMPLETE.md") && config.supervisor !== "maintenance") {
+    logger.info("Mission complete — skipping library maintenance");
+    return { outcome: "nop", details: "Mission already complete" };
+  }
+
+  const sourcesPath = config.paths.librarySources.path;
+  const sources = readOptionalFile(sourcesPath);
+  const mission = readOptionalFile(config.paths.mission.path);
+  const hasUrls = /https?:\/\//.test(sources);
+
+  const libraryPath = config.paths.library.path;
+  const libraryLimit = config.paths.library.limit;
+  const libraryDocs = scanDirectory(libraryPath, ".md", { contentLimit: t.documentSummary || 500 }, logger);
+
+  let prompt;
+  if (!hasUrls) {
+    prompt = [
+      "## Instructions", instructions || "Maintain the library by updating documents from sources.", "",
+      "## Mission", mission || "(no mission)", "",
+      "## Current SOURCES.md", sources || "(empty)", "",
+      "## Your Task",
+      `Populate ${sourcesPath} with 3-8 relevant reference URLs.`, "",
+      formatPathsSection(writablePaths, config.readOnlyPaths, config),
+    ].join("\n");
+  } else {
+    prompt = [
+      "## Instructions", instructions || "Maintain the library by updating documents from sources.", "",
+      "## Sources", sources, "",
+      `## Current Library Documents (${libraryDocs.length}/${libraryLimit} max)`,
+      ...libraryDocs.map((d) => `### ${d.name}\n${d.content}`), "",
+      "## Your Task",
+      "1. Read each URL in SOURCES.md and extract technical content.",
+      "2. Create or update library documents.", "",
+      formatPathsSection(writablePaths, config.readOnlyPaths, config), "",
+      "## Constraints", `- Maximum ${libraryLimit} library documents`,
+    ].join("\n");
+  }
+
+  const { content: resultContent, tokensUsed, inputTokens, outputTokens, cost } = await runCopilotTask({
+    model,
+    systemMessage: "You are a knowledge librarian. Maintain a library of technical documents extracted from web sources." + NARRATIVE_INSTRUCTION,
+    prompt, writablePaths, tuning: t, logger,
+  });
+
+  return {
+    outcome: hasUrls ? "library-maintained" : "sources-discovered",
+    tokensUsed, inputTokens, outputTokens, cost, model,
+    details: hasUrls ? `Maintained library (${libraryDocs.length} docs)` : "Discovered sources from mission",
+    narrative: extractNarrative(resultContent, hasUrls ? "Maintained library." : "Discovered sources."),
+  };
+}