@xn-intenton-z2a/agentic-lib 7.2.20 → 7.2.22

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/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;

package/src/seeds/zero-package.json

@@ -17,7 +17,7 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "@xn-intenton-z2a/agentic-lib": "^7.2.20"
+    "@xn-intenton-z2a/agentic-lib": "^7.2.22"
   },
   "devDependencies": {
     "@playwright/test": "^1.58.0",

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

@@ -1,73 +0,0 @@
-// 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

@@ -1,61 +0,0 @@
-// 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

@@ -1,66 +0,0 @@
-// 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."),
-  };
-}

package/src/copilot/tasks/transform.js

@@ -1,120 +0,0 @@
-// SPDX-License-Identifier: GPL-3.0-only
-// Copyright (C) 2025-2026 Polycode Limited
-// src/copilot/tasks/transform.js — Transform task (shared)
-//
-// Ported from src/actions/agentic-step/tasks/transform.js.
-// GitHub context (octokit, issues) is optional for local CLI use.
-
-import { existsSync } from "fs";
-import {
-  runCopilotTask, readOptionalFile, scanDirectory, formatPathsSection,
-  filterIssues, summariseIssue, extractFeatureSummary, extractNarrative, NARRATIVE_INSTRUCTION,
-} from "../session.js";
-import { defaultLogger } from "../logger.js";
-
-export async function transform(context) {
-  const { config, instructions, writablePaths, testCommand, model, logger = defaultLogger } = context;
-  // octokit + repo are optional (absent in CLI mode)
-  const octokit = context.octokit || null;
-  const repo = context.repo || null;
-  const issueNumber = context.issueNumber || null;
-  const t = config.tuning || {};
-
-  const mission = readOptionalFile(config.paths.mission.path);
-  if (!mission) {
-    logger.warning(`No mission file found at ${config.paths.mission.path}`);
-    return { outcome: "nop", details: "No mission file found" };
-  }
-
-  if (existsSync("MISSION_COMPLETE.md") && config.supervisor !== "maintenance") {
-    logger.info("Mission complete — skipping transformation");
-    return { outcome: "nop", details: "Mission already complete" };
-  }
-
-  const features = scanDirectory(config.paths.features.path, ".md", { fileLimit: t.featuresScan || 10 }, logger);
-  const sourceFiles = scanDirectory(config.paths.source.path, [".js", ".ts"], {
-    fileLimit: t.sourceScan || 10,
-    contentLimit: t.sourceContent || 5000,
-    recursive: true, sortByMtime: true, clean: true, outline: true,
-  }, logger);
-  const webFiles = scanDirectory(config.paths.web?.path || "src/web/", [".html", ".css", ".js"], {
-    fileLimit: t.sourceScan || 10,
-    contentLimit: t.sourceContent || 5000,
-    recursive: true, sortByMtime: true, clean: true,
-  }, logger);
-
-  // GitHub issues (optional)
-  let openIssues = [];
-  let rawIssuesCount = 0;
-  if (octokit && repo) {
-    const { data: rawIssues } = await octokit.rest.issues.listForRepo({ ...repo, state: "open", per_page: t.issuesScan || 20 });
-    rawIssuesCount = rawIssues.length;
-    openIssues = filterIssues(rawIssues, { staleDays: t.staleDays || 30 });
-  }
-
-  let targetIssue = null;
-  if (issueNumber && octokit && repo) {
-    try {
-      const { data: issue } = await octokit.rest.issues.get({ ...repo, issue_number: Number(issueNumber) });
-      targetIssue = issue;
-    } catch (err) {
-      logger.warning(`Could not fetch target issue #${issueNumber}: ${err.message}`);
-    }
-  }
-
-  const agentInstructions = instructions || "Transform the repository toward its mission by identifying the next best action.";
-
-  const prompt = [
-    "## Instructions", agentInstructions, "",
-    ...(targetIssue ? [
-      `## Target Issue #${targetIssue.number}: ${targetIssue.title}`,
-      targetIssue.body || "(no description)",
-      `Labels: ${targetIssue.labels.map((l) => l.name).join(", ") || "none"}`,
-      "", "**Focus your transformation on resolving this specific issue.**", "",
-    ] : []),
-    "## Mission", mission, "",
-    `## Current Features (${features.length})`,
-    ...features.map((f) => `### ${f.name}\n${extractFeatureSummary(f.content, f.name)}`), "",
-    `## Current Source Files (${sourceFiles.length})`,
-    ...sourceFiles.map((f) => `### ${f.name}\n\`\`\`\n${f.content}\n\`\`\``), "",
-    ...(webFiles.length > 0 ? [
-      `## Website Files (${webFiles.length})`,
-      ...webFiles.map((f) => `### ${f.name}\n\`\`\`\n${f.content}\n\`\`\``), "",
-    ] : []),
-    ...(openIssues.length > 0 ? [
-      `## Open Issues (${openIssues.length})`,
-      ...openIssues.slice(0, t.issuesScan || 20).map((i) => summariseIssue(i, t.issueBodyLimit || 500)), "",
-    ] : []),
-    "## Output Artifacts",
-    `Save output artifacts to \`${config.paths.examples?.path || "examples/"}\`.`, "",
-    "## Your Task",
-    "Analyze the mission, features, source code, and open issues.",
-    "Determine the single most impactful next step to transform this repository.", "Then implement that step.", "",
-    "## When NOT to make changes",
-    "If the existing code already satisfies all requirements:", "- Do NOT make cosmetic changes", "- Instead, report that the mission is satisfied", "",
-    formatPathsSection(writablePaths, config.readOnlyPaths, config), "",
-    "## Constraints", `- Run \`${testCommand}\` to validate your changes`,
-  ].join("\n");
-
-  logger.info(`Transform prompt length: ${prompt.length} chars`);
-
-  const { content: resultContent, tokensUsed, inputTokens, outputTokens, cost } = await runCopilotTask({
-    model,
-    systemMessage: "You are an autonomous code transformation agent. Your goal is to advance the repository toward its mission by making the most impactful change possible in a single step." + NARRATIVE_INSTRUCTION,
-    prompt, writablePaths, tuning: t, logger,
-  });
-
-  const promptBudget = [
-    { section: "mission", size: mission.length, files: "1", notes: "full" },
-    { section: "features", size: features.reduce((s, f) => s + f.content.length, 0), files: `${features.length}`, notes: "" },
-    { section: "source", size: sourceFiles.reduce((s, f) => s + f.content.length, 0), files: `${sourceFiles.length}`, notes: "" },
-    { section: "issues", size: openIssues.length * 80, files: `${openIssues.length}`, notes: `${rawIssuesCount - openIssues.length} filtered` },
-  ];
-
-  return {
-    outcome: "transformed", tokensUsed, inputTokens, outputTokens, cost, model,
-    details: resultContent.substring(0, 500),
-    narrative: extractNarrative(resultContent, "Transformation step completed."),
-    promptBudget,
-  };
-}