@xn-intenton-z2a/agentic-lib 7.4.5 → 7.4.7

package/src/actions/agentic-step/tools.js

@@ -1,142 +1,27 @@
 // SPDX-License-Identifier: GPL-3.0-only
 // Copyright (C) 2025-2026 Polycode Limited
-// tools.js — Shared tool definitions for agentic-step task handlers
+// tools.js — Thin re-export from shared src/copilot/tools.js
 //
-// Defines file I/O and shell tools using the Copilot SDK's defineTool().
-// The agent has no built-in filesystem access — these tools give it the
-// ability to read, write, list files, and run commands.
+// Phase 4: Tool definitions now live in src/copilot/tools.js.
+// This file re-exports for backwards compatibility.
+//
+// Note: The shared tools.js uses a (writablePaths, logger, defineToolFn) signature.
+// The old Actions tools.js used (writablePaths) with @actions/core and @github/copilot-sdk.
+// This wrapper adapts the signature for existing callers in copilot.js.
 
-import { defineTool } from "@github/copilot-sdk";
-import { readFileSync, writeFileSync, readdirSync, existsSync, mkdirSync } from "fs";
-import { execSync } from "child_process";
-import { dirname, resolve } from "path";
-import { isPathWritable } from "./safety.js";
 import * as core from "@actions/core";
+import { defineTool } from "@github/copilot-sdk";
+import { createAgentTools as _createAgentTools, isPathWritable } from "../../copilot/tools.js";
 
-/**
- * Create the standard set of agent tools.
- *
- * @param {string[]} writablePaths - Paths the agent is allowed to write to
- * @returns {import('@github/copilot-sdk').Tool[]} Array of tools for createSession()
- */
-export function createAgentTools(writablePaths) {
-  const readFile = defineTool("read_file", {
-    description: "Read the contents of a file at the given path.",
-    parameters: {
-      type: "object",
-      properties: {
-        path: { type: "string", description: "Absolute or relative file path to read" },
-      },
-      required: ["path"],
-    },
-    handler: ({ path }) => {
-      const resolved = resolve(path);
-      core.info(`[tool] read_file: ${resolved}`);
-      if (!existsSync(resolved)) {
-        return { error: `File not found: ${resolved}` };
-      }
-      try {
-        const content = readFileSync(resolved, "utf8");
-        return { content };
-      } catch (err) {
-        return { error: `Failed to read ${resolved}: ${err.message}` };
-      }
-    },
-  });
-
-  const writeFile = defineTool("write_file", {
-    description:
-      "Write content to a file. The file will be created if it does not exist. Parent directories will be created automatically. Only writable paths are allowed.",
-    parameters: {
-      type: "object",
-      properties: {
-        path: { type: "string", description: "Absolute or relative file path to write" },
-        content: { type: "string", description: "The full content to write to the file" },
-      },
-      required: ["path", "content"],
-    },
-    handler: ({ path, content }) => {
-      const resolved = resolve(path);
-      core.info(`[tool] write_file: ${resolved}`);
-      if (!isPathWritable(resolved, writablePaths)) {
-        return { error: `Path is not writable: ${path}. Writable paths: ${writablePaths.join(", ")}` };
-      }
-      try {
-        const dir = dirname(resolved);
-        if (!existsSync(dir)) {
-          mkdirSync(dir, { recursive: true });
-        }
-        writeFileSync(resolved, content, "utf8");
-        return { success: true, path: resolved };
-      } catch (err) {
-        return { error: `Failed to write ${resolved}: ${err.message}` };
-      }
-    },
-  });
-
-  const listFiles = defineTool("list_files", {
-    description: "List files and directories at the given path. Returns names with a trailing / for directories.",
-    parameters: {
-      type: "object",
-      properties: {
-        path: { type: "string", description: "Directory path to list" },
-        recursive: { type: "boolean", description: "Whether to list recursively (default false)" },
-      },
-      required: ["path"],
-    },
-    handler: ({ path, recursive }) => {
-      const resolved = resolve(path);
-      core.info(`[tool] list_files: ${resolved} (recursive=${!!recursive})`);
-      if (!existsSync(resolved)) {
-        return { error: `Directory not found: ${resolved}` };
-      }
-      try {
-        const entries = readdirSync(resolved, { withFileTypes: true, recursive: !!recursive });
-        const names = entries.map((e) => (e.isDirectory() ? `${e.name}/` : e.name));
-        return { files: names };
-      } catch (err) {
-        return { error: `Failed to list ${resolved}: ${err.message}` };
-      }
-    },
-  });
-
-  const runCommand = defineTool("run_command", {
-    description:
-      "Run a shell command and return its stdout and stderr. Use this to run tests, build, lint, or inspect the environment.",
-    parameters: {
-      type: "object",
-      properties: {
-        command: { type: "string", description: "The shell command to execute" },
-        cwd: { type: "string", description: "Working directory for the command (default: current directory)" },
-      },
-      required: ["command"],
-    },
-    handler: ({ command, cwd }) => {
-      const workDir = cwd ? resolve(cwd) : process.cwd();
-      core.info(`[tool] run_command: ${command} (cwd=${workDir})`);
-      const blocked = /\bgit\s+(commit|push|add|reset|checkout|rebase|merge|stash)\b/;
-      if (blocked.test(command)) {
-        core.info(`[tool] BLOCKED git write command: ${command}`);
-        return { error: "Git write commands are not allowed. Use read_file/write_file tools instead." };
-      }
-      try {
-        const stdout = execSync(command, {
-          cwd: workDir,
-          encoding: "utf8",
-          timeout: 120000,
-          maxBuffer: 1024 * 1024,
-        });
-        return { stdout, exitCode: 0 };
-      } catch (err) {
-        return {
-          stdout: err.stdout || "",
-          stderr: err.stderr || "",
-          exitCode: err.status || 1,
-          error: err.message,
-        };
-      }
-    },
-  });
+const actionsLogger = {
+  info: (...args) => core.info(args.join(" ")),
+  warning: (...args) => core.warning(args.join(" ")),
+  error: (...args) => core.error(args.join(" ")),
+  debug: (...args) => core.debug(args.join(" ")),
+};
 
-  return [readFile, writeFile, listFiles, runCommand];
+export function createAgentTools(writablePaths) {
+  return _createAgentTools(writablePaths, actionsLogger, defineTool);
 }
+
+export { isPathWritable };

package/src/copilot/context.js

@@ -8,8 +8,33 @@
 import { resolve } from "path";
 import { execSync } from "child_process";
 import { scanDirectory, readOptionalFile, extractFeatureSummary, formatPathsSection, summariseIssue, filterIssues } from "./session.js";
+import { readCumulativeCost } from "./telemetry.js";
 import { defaultLogger } from "./logger.js";
 
+/**
+ * Per-agent refinements that control context precision and prompt quality.
+ * These restore the tight scoping that existed in the old per-task handlers.
+ */
+const AGENT_REFINEMENTS = {
+  "agent-issue-resolution": {
+    sortFeatures: "incomplete-first",
+    includeWebFiles: true,
+    highlightTargetIssue: true,
+    trackPromptBudget: true,
+  },
+  "agent-apply-fix": {
+    emphasizeTestOutput: true,
+  },
+  "agent-maintain-features": {
+    sortFeatures: "incomplete-first",
+    injectLimit: "features",
+  },
+  "agent-maintain-library": {
+    checkSourcesForUrls: true,
+    injectLimit: "library",
+  },
+};
+
 /**
  * Context requirements per agent. Defines what context each agent needs.
  * All fields are optional — the builder includes whatever is available.
@@ -90,6 +115,16 @@ export function gatherLocalContext(workspacePath, config, { logger = defaultLogg
   const sourcesPath = paths.librarySources?.path || "SOURCES.md";
   context.librarySources = readOptionalFile(resolve(wsPath, sourcesPath));
 
+  // Web files
+  const webPath = paths.web?.path || "src/web/";
+  const webDir = resolve(wsPath, webPath);
+  context.webFiles = scanDirectory(webDir, [".html", ".css", ".js"], {
+    fileLimit: tuning.sourceScan || 10,
+    contentLimit: tuning.sourceContent || 5000,
+    sortByMtime: true,
+    clean: true,
+  }, logger);
+
   // Contributing guide
   const contributingPath = paths.contributing?.path || "CONTRIBUTING.md";
   context.contributing = readOptionalFile(resolve(wsPath, contributingPath), 2000);
@@ -202,26 +237,60 @@ export function gatherGitHubContext({ issueNumber, prNumber, discussionUrl, work
 /**
  * Build a user prompt for the given agent from available context.
  *
+ * Returns an object with the assembled prompt and optional promptBudget metadata.
+ * The prompt includes config-driven limits and per-agent refinements that restore
+ * the context precision from the old per-task handlers.
+ *
  * @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
+ * @param {Object} [options.config] - Full parsed config (for limits injection)
+ * @returns {{ prompt: string, promptBudget: Array|null }}
  */
-export function buildUserPrompt(agentName, localContext, githubContext, { tuning } = {}) {
+export function buildUserPrompt(agentName, localContext, githubContext, { tuning, config } = {}) {
   const needs = AGENT_CONTEXT[agentName] || AGENT_CONTEXT["agent-iterate"];
+  const refinements = AGENT_REFINEMENTS[agentName] || {};
   const sections = [];
+  const promptBudget = refinements.trackPromptBudget ? [] : null;
+
+  // Target issue — placed prominently when highlightTargetIssue is set
+  if (refinements.highlightTargetIssue && githubContext?.issueDetail) {
+    const issue = githubContext.issueDetail;
+    const issueSection = [
+      `# Target Issue #${issue.number}: ${issue.title}`,
+      issue.body || "(no description)",
+      `Labels: ${(issue.labels || []).map((l) => typeof l === "string" ? l : l.name).join(", ") || "none"}`,
+      "",
+      "**Focus your transformation on resolving this specific issue.**",
+    ];
+    if (issue.comments?.length > 0) {
+      issueSection.push("\n## Comments");
+      for (const c of issue.comments.slice(-5)) {
+        issueSection.push(`**${c.author?.login || "unknown"}**: ${c.body}`);
+      }
+    }
+    const text = issueSection.join("\n");
+    sections.push(text);
+    if (promptBudget) promptBudget.push({ section: "target-issue", size: text.length, files: "1", notes: "" });
+  }
 
   // Mission
   if (needs.mission && localContext.mission) {
-    sections.push(`# Mission\n\n${localContext.mission}`);
+    const text = `# Mission\n\n${localContext.mission}`;
+    sections.push(text);
+    if (promptBudget) promptBudget.push({ section: "mission", size: localContext.mission.length, files: "1", notes: "full" });
   }
 
-  // Current test state
+  // Current test state — emphasised for fix-code agent
   if (localContext.testOutput) {
     const testPreview = localContext.testOutput.substring(0, 4000);
-    sections.push(`# Current Test State\n\n\`\`\`\n${testPreview}\n\`\`\``);
+    if (refinements.emphasizeTestOutput) {
+      sections.push(`# Failing Test Output\n\nThe tests are currently failing. Fix the root cause.\n\n\`\`\`\n${testPreview}\n\`\`\``);
+    } else {
+      sections.push(`# Current Test State\n\n\`\`\`\n${testPreview}\n\`\`\``);
+    }
   }
 
   // Source files
@@ -230,7 +299,20 @@ export function buildUserPrompt(agentName, localContext, githubContext, { tuning
     for (const f of localContext.sourceFiles) {
       sourceSection.push(`## ${f.name}\n\`\`\`\n${f.content}\n\`\`\``);
     }
-    sections.push(sourceSection.join("\n\n"));
+    const text = sourceSection.join("\n\n");
+    sections.push(text);
+    if (promptBudget) promptBudget.push({ section: "source", size: text.length, files: `${localContext.sourceFiles.length}`, notes: "" });
+  }
+
+  // Web files — only when refinements request it
+  if (refinements.includeWebFiles && localContext.webFiles?.length > 0) {
+    const webSection = [`# Website Files (${localContext.webFiles.length})`];
+    for (const f of localContext.webFiles) {
+      webSection.push(`## ${f.name}\n\`\`\`\n${f.content}\n\`\`\``);
+    }
+    const text = webSection.join("\n\n");
+    sections.push(text);
+    if (promptBudget) promptBudget.push({ section: "web", size: text.length, files: `${localContext.webFiles.length}`, notes: "" });
   }
 
   // Test files
@@ -239,43 +321,75 @@ export function buildUserPrompt(agentName, localContext, githubContext, { tuning
     for (const f of localContext.testFiles) {
       testSection.push(`## ${f.name}\n\`\`\`\n${f.content}\n\`\`\``);
     }
-    sections.push(testSection.join("\n\n"));
+    const text = testSection.join("\n\n");
+    sections.push(text);
+    if (promptBudget) promptBudget.push({ section: "tests", size: text.length, files: `${localContext.testFiles.length}`, notes: "" });
   }
 
-  // Features
+  // Features — sorted incomplete-first when refinements request it
   if (needs.features && localContext.features?.length > 0) {
-    const featureSection = [`# Features (${localContext.features.length})`];
-    for (const f of localContext.features) {
+    let features = [...localContext.features];
+    if (refinements.sortFeatures === "incomplete-first") {
+      features.sort((a, b) => {
+        const aIncomplete = /Remaining:/.test(a) || /\[ \]/.test(a) ? 0 : 1;
+        const bIncomplete = /Remaining:/.test(b) || /\[ \]/.test(b) ? 0 : 1;
+        return aIncomplete - bIncomplete;
+      });
+    }
+
+    const limit = config?.paths?.features?.limit;
+    const header = limit
+      ? `# Features (${features.length}/${limit} max)`
+      : `# Features (${features.length})`;
+    const featureSection = [header];
+    for (const f of features) {
       featureSection.push(f);
     }
-    sections.push(featureSection.join("\n\n"));
+    const text = featureSection.join("\n\n");
+    sections.push(text);
+    if (promptBudget) promptBudget.push({ section: "features", size: text.length, files: `${features.length}`, notes: "" });
   }
 
   // Library
   if (needs.library && localContext.libraryFiles?.length > 0) {
-    const libSection = [`# Library Files (${localContext.libraryFiles.length})`];
+    const libLimit = config?.paths?.library?.limit;
+    const header = libLimit
+      ? `# Library Files (${localContext.libraryFiles.length}/${libLimit} max)`
+      : `# Library Files (${localContext.libraryFiles.length})`;
+    const libSection = [header];
     for (const f of localContext.libraryFiles) {
       libSection.push(`## ${f.name}\n${f.content}`);
     }
     sections.push(libSection.join("\n\n"));
   }
 
-  // Library sources
+  // Library sources — vary strategy based on URL presence
   if (needs.librarySources && localContext.librarySources) {
-    sections.push(`# Sources\n\n${localContext.librarySources}`);
+    if (refinements.checkSourcesForUrls) {
+      const hasUrls = /https?:\/\//.test(localContext.librarySources);
+      if (!hasUrls) {
+        sections.push(`# Sources\n\n${localContext.librarySources}\n\nPopulate SOURCES.md with 3-8 relevant reference URLs aligned with the mission.`);
+      } else {
+        sections.push(`# Sources\n\n${localContext.librarySources}`);
+      }
+    } else {
+      sections.push(`# Sources\n\n${localContext.librarySources}`);
+    }
   }
 
-  // Issues (from GitHub context)
+  // Issues (from GitHub context) — not duplicated if target issue already shown
   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"));
+    const text = issueSection.join("\n\n");
+    sections.push(text);
+    if (promptBudget) promptBudget.push({ section: "issues", size: text.length, files: `${githubContext.issues.length}`, notes: "" });
   }
 
-  // Specific issue detail
-  if (githubContext?.issueDetail) {
+  // Specific issue detail (only if not already highlighted as target issue)
+  if (!refinements.highlightTargetIssue && githubContext?.issueDetail) {
     const issue = githubContext.issueDetail;
     const issueSection = [`# Issue #${issue.number}: ${issue.title}\n\n${issue.body || "(no body)"}`];
     if (issue.comments?.length > 0) {
@@ -306,6 +420,31 @@ export function buildUserPrompt(agentName, localContext, githubContext, { tuning
     ));
   }
 
+  // Limits section — inject concrete numbers from agentic-lib.toml
+  if (config) {
+    const limitsLines = ["# Limits (from agentic-lib.toml)", ""];
+    const budget = config.transformationBudget || 0;
+    const featLimit = config.paths?.features?.limit;
+    const libLimit = config.paths?.library?.limit;
+
+    if (featLimit) limitsLines.push(`- Maximum feature files: ${featLimit}`);
+    if (libLimit) limitsLines.push(`- Maximum library documents: ${libLimit}`);
+    if (budget > 0) {
+      const intentionPath = config.intentionBot?.intentionFilepath;
+      const cumulativeCost = readCumulativeCost(intentionPath);
+      const remaining = Math.max(0, budget - cumulativeCost);
+      limitsLines.push(`- Transformation budget: ${budget} (used: ${cumulativeCost}, remaining: ${remaining})`);
+    }
+    if (config.featureDevelopmentIssuesWipLimit) limitsLines.push(`- Maximum concurrent feature issues: ${config.featureDevelopmentIssuesWipLimit}`);
+    if (config.maintenanceIssuesWipLimit) limitsLines.push(`- Maximum concurrent maintenance issues: ${config.maintenanceIssuesWipLimit}`);
+    if (config.attemptsPerBranch) limitsLines.push(`- Maximum attempts per branch: ${config.attemptsPerBranch}`);
+    if (config.attemptsPerIssue) limitsLines.push(`- Maximum attempts per issue: ${config.attemptsPerIssue}`);
+
+    if (limitsLines.length > 2) {
+      sections.push(limitsLines.join("\n"));
+    }
+  }
+
   // Instructions
   sections.push([
     "Implement this mission. Read the existing source code and tests,",
@@ -314,5 +453,5 @@ export function buildUserPrompt(agentName, localContext, githubContext, { tuning
     "Start by reading the existing files, then implement the solution.",
   ].join("\n"));
 
-  return sections.join("\n\n");
+  return { prompt: sections.join("\n\n"), promptBudget };
 }

package/src/copilot/guards.js

@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2025-2026 Polycode Limited
+// guards.js — Short-circuit checks that skip LLM invocation when unnecessary
+//
+// Phase 4 Step 10a: Restores the guards that existed in the per-task handlers
+// (transform.js, fix-code.js, maintain-features.js, maintain-library.js)
+// before Phase 4 convergence replaced them with unconditional runHybridSession().
+
+import { existsSync } from "fs";
+import { resolve } from "path";
+import { execSync } from "child_process";
+import { readCumulativeCost } from "./telemetry.js";
+
+/**
+ * Task-to-guard mapping. Each task has an ordered list of guards.
+ * Guards are checked in order; the first that triggers returns skip.
+ */
+const TASK_GUARDS = {
+  "transform": ["no-mission", "mission-complete", "budget-exhausted"],
+  "fix-code": ["tests-pass", "budget-exhausted"],
+  "maintain-features": ["mission-complete", "budget-exhausted"],
+  "maintain-library": ["mission-complete", "budget-exhausted"],
+};
+
+/**
+ * Check whether a task should be skipped before invoking the LLM.
+ *
+ * @param {string} taskName - Task name (e.g. "transform", "fix-code")
+ * @param {Object} config - Parsed agentic-lib config
+ * @param {string} workspacePath - Path to the workspace
+ * @param {Object} [options]
+ * @param {Object} [options.logger] - Logger interface
+ * @returns {{ skip: boolean, reason: string }}
+ */
+export function checkGuards(taskName, config, workspacePath, { logger } = {}) {
+  const guards = TASK_GUARDS[taskName];
+  if (!guards) return { skip: false, reason: "" };
+
+  const wsPath = resolve(workspacePath);
+
+  for (const guard of guards) {
+    switch (guard) {
+      case "no-mission": {
+        const missionPath = config.paths?.mission?.path || "MISSION.md";
+        if (!existsSync(resolve(wsPath, missionPath))) {
+          return { skip: true, reason: `No mission file found at ${missionPath}` };
+        }
+        break;
+      }
+
+      case "mission-complete": {
+        // Match the old behaviour: skip if MISSION_COMPLETE.md exists
+        // unless supervisor is in maintenance mode
+        if (existsSync(resolve(wsPath, "MISSION_COMPLETE.md")) && config.supervisor !== "maintenance") {
+          return { skip: true, reason: "Mission already complete (MISSION_COMPLETE.md exists)" };
+        }
+        break;
+      }
+
+      case "tests-pass": {
+        const testCommand = config.testScript || "npm test";
+        try {
+          execSync(testCommand, { cwd: wsPath, encoding: "utf8", timeout: 120000, stdio: "pipe" });
+          return { skip: true, reason: "Tests already pass — nothing to fix" };
+        } catch {
+          // Tests fail — proceed with fix-code
+        }
+        break;
+      }
+
+      case "budget-exhausted": {
+        const budget = config.transformationBudget || 0;
+        if (budget > 0) {
+          const intentionFilepath = config.intentionBot?.intentionFilepath;
+          const filePath = intentionFilepath ? resolve(wsPath, intentionFilepath) : null;
+          const cumulativeCost = readCumulativeCost(filePath);
+          if (cumulativeCost >= budget) {
+            return { skip: true, reason: `Transformation budget exhausted (${cumulativeCost}/${budget})` };
+          }
+        }
+        break;
+      }
+    }
+  }
+
+  return { skip: false, reason: "" };
+}

package/src/copilot/hybrid-session.js

@@ -62,6 +62,7 @@ function formatToolArgs(toolName, args) {
  * @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 {number} [options.maxToolCalls] - Max tool calls before graceful stop (undefined = unlimited)
  * @param {Object} [options.logger]
  * @returns {Promise<HybridResult>}
  */
@@ -75,6 +76,7 @@ export async function runHybridSession({
   userPrompt,
   writablePaths,
   maxRetries = 2,
+  maxToolCalls,
   logger = defaultLogger,
 }) {
   const { CopilotClient, approveAll, defineTool } = await getSDK();
@@ -145,7 +147,7 @@ export async function runHybridSession({
   const systemPrompt = basePrompt + NARRATIVE_INSTRUCTION;
 
   // ── Session config ─────────────────────────────────────────────────
-  logger.info(`[hybrid] Creating session (model=${model}, workspace=${wsPath})`);
+  logger.info(`[agentic-lib] Creating session (model=${model}, workspace=${wsPath})`);
 
   const client = new CopilotClient({
     env: { ...process.env, GITHUB_TOKEN: copilotToken, GH_TOKEN: copilotToken },
@@ -159,6 +161,11 @@ export async function runHybridSession({
     workingDirectory: wsPath,
     hooks: {
       onPreToolUse: (input) => {
+        // Enforce tool-call budget
+        if (maxToolCalls && metrics.toolCalls.length >= maxToolCalls) {
+          logger.warning(`  [tool] Budget reached (${maxToolCalls} calls) — denying ${input.toolName}`);
+          return { action: "deny", reason: `Tool call budget exhausted (${maxToolCalls} max). Wrap up your work.` };
+        }
         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 });
@@ -211,15 +218,15 @@ export async function runHybridSession({
   for (let attempt = 0; attempt <= maxRetries; attempt++) {
     try {
       session = await client.createSession(sessionConfig);
-      logger.info(`[hybrid] Session: ${session.sessionId}`);
+      logger.info(`[agentic-lib] 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})`);
+        logger.warning(`[agentic-lib] 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}`);
+        logger.error(`[agentic-lib] Failed to create session: ${err.message}`);
         await client.stop();
         throw err;
       }
@@ -251,13 +258,13 @@ export async function runHybridSession({
   // ── Try autopilot mode ──────────────────────────────────────────────
   try {
     await session.rpc.mode.set({ mode: "autopilot" });
-    logger.info("[hybrid] Autopilot mode: active");
+    logger.info("[agentic-lib] Autopilot mode: active");
   } catch {
-    logger.info("[hybrid] Autopilot mode not available — using default mode");
+    logger.info("[agentic-lib] Autopilot mode not available — using default mode");
   }
 
   // ── Send mission prompt ─────────────────────────────────────────────
-  logger.info("[hybrid] Sending mission...\n");
+  logger.info("[agentic-lib] Sending mission...\n");
 
   const prompt = userPrompt || [
     `# Mission\n\n${missionText}`,
@@ -281,10 +288,10 @@ export async function runHybridSession({
     } 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})`);
+        logger.warning(`[agentic-lib] 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}`);
+        logger.error(`[agentic-lib] Session error: ${err.message}`);
         response = null;
         endReason = "error";
         break;

package/src/copilot/sdk.js

@@ -10,11 +10,13 @@ import { resolve, dirname } from "path";
 import { fileURLToPath } from "url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const pkgRoot = resolve(__dirname, "../..");
 
+// Search for the SDK relative to this file's location. Works in both:
+// - npm package: src/copilot/sdk.js → ../../node_modules/ or ../actions/agentic-step/node_modules/
+// - consumer repo: .github/agentic-lib/copilot/sdk.js → ../actions/agentic-step/node_modules/
 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"),
+  resolve(__dirname, "../../node_modules/@github/copilot-sdk/dist/index.js"),
+  resolve(__dirname, "../actions/agentic-step/node_modules/@github/copilot-sdk/dist/index.js"),
 ];
 
 let _sdk = null;