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

package/bin/agentic-lib.js

@@ -30,12 +30,6 @@ const flags = args.slice(1);
 
 let initChanges = 0;
 const TASK_COMMANDS = ["transform", "maintain-features", "maintain-library", "fix-code"];
-const TASK_AGENT_MAP = {
-  "transform": "agent-issue-resolution",
-  "fix-code": "agent-apply-fix",
-  "maintain-features": "agent-maintain-features",
-  "maintain-library": "agent-maintain-library",
-};
 const INIT_COMMANDS = ["init", "update", "reset"];
 const ALL_COMMANDS = [...INIT_COMMANDS, ...TASK_COMMANDS, "version", "mcp", "iterate"];
 
@@ -372,30 +366,21 @@ async function runIterate() {
 // ─── Task Runner ─────────────────────────────────────────────────────
 
 async function runTask(taskName) {
-  // Task commands are now aliases for iterate --agent <agent-name>
-  const agentName = TASK_AGENT_MAP[taskName];
-  if (!agentName) {
-    console.error(`Unknown task: ${taskName}`);
-    return 1;
-  }
-
   console.log("");
-  console.log(`=== agentic-lib ${taskName} (→ iterate --agent ${agentName}) ===`);
+  console.log(`=== agentic-lib ${taskName} ===`);
   console.log(`Target:  ${target}`);
   console.log(`Model:   ${model}`);
   console.log(`Dry-run: ${dryRun}`);
   console.log("");
 
+  // Load config from shared module
   const { loadConfig } = await import("../src/copilot/config.js");
-  let config;
-  try {
-    config = loadConfig(resolve(target, "agentic-lib.toml"));
-  } catch {
-    config = { tuning: {}, model: "gpt-5-mini", paths: {}, writablePaths: [], readOnlyPaths: [] };
-  }
-  const effectiveModel = model || config.model || "gpt-5-mini";
+  const config = loadConfig(resolve(target, "agentic-lib.toml"));
+  const effectiveModel = model || config.model;
 
-  console.log(`[config] writable=${(config.writablePaths || []).join(", ")}`);
+  console.log(`[config] supervisor=${config.supervisor}`);
+  console.log(`[config] writable=${config.writablePaths.join(", ")}`);
+  console.log(`[config] test=${config.testScript}`);
   console.log("");
 
   if (dryRun) {
@@ -403,50 +388,62 @@ async function runTask(taskName) {
     return 0;
   }
 
-  try {
-    const { loadAgentPrompt } = await import("../src/copilot/agents.js");
-    const { runHybridSession } = await import("../src/copilot/hybrid-session.js");
-    const { gatherLocalContext, gatherGitHubContext, buildUserPrompt } = await import("../src/copilot/context.js");
-
-    const agentPrompt = loadAgentPrompt(agentName);
-    const localContext = gatherLocalContext(target, config);
-
-    let githubContext;
-    if (issueNumber || prNumber) {
-      githubContext = gatherGitHubContext({
-        issueNumber: issueNumber || undefined,
-        prNumber: prNumber || undefined,
-        workspacePath: target,
-      });
-    }
-
-    const userPrompt = buildUserPrompt(agentName, localContext, githubContext, { tuning: config.tuning });
+  // Change to target directory so relative paths in config work
+  const originalCwd = process.cwd();
+  process.chdir(target);
 
-    const result = await runHybridSession({
-      workspacePath: target,
+  try {
+    const context = {
+      config,
+      writablePaths: config.writablePaths,
       model: effectiveModel,
-      tuning: config.tuning || {},
-      timeoutMs,
-      agentPrompt,
-      userPrompt,
-      writablePaths: config.writablePaths?.length > 0 ? config.writablePaths : undefined,
-    });
+      testCommand: config.testScript,
+      logger: { info: console.log, warning: console.warn, error: console.error, debug: () => {} },
+    };
+
+    let result;
+    switch (taskName) {
+      case "transform": {
+        const { transform } = await import("../src/copilot/tasks/transform.js");
+        result = await transform(context);
+        break;
+      }
+      case "maintain-features": {
+        const { maintainFeatures } = await import("../src/copilot/tasks/maintain-features.js");
+        result = await maintainFeatures(context);
+        break;
+      }
+      case "maintain-library": {
+        const { maintainLibrary } = await import("../src/copilot/tasks/maintain-library.js");
+        result = await maintainLibrary(context);
+        break;
+      }
+      case "fix-code": {
+        const { fixCode } = await import("../src/copilot/tasks/fix-code.js");
+        result = await fixCode(context);
+        break;
+      }
+      default:
+        console.error(`Unknown task: ${taskName}`);
+        return 1;
+    }
 
     console.log("");
     console.log(`=== ${taskName} completed ===`);
-    console.log(`Success:       ${result.success}`);
-    console.log(`Session time:  ${result.sessionTime}s`);
-    console.log(`Tool calls:    ${result.toolCalls}`);
-    console.log(`Tokens:        ${result.tokensIn + result.tokensOut} (in=${result.tokensIn} out=${result.tokensOut})`);
+    console.log(`Outcome: ${result.outcome}`);
+    if (result.details) console.log(`Details: ${result.details}`);
+    if (result.tokensUsed) console.log(`Tokens: ${result.tokensUsed} (in=${result.inputTokens} out=${result.outputTokens})`);
     if (result.narrative) console.log(`Narrative: ${result.narrative}`);
     console.log("");
-    return result.success ? 0 : 1;
+    return 0;
   } catch (err) {
     console.error("");
     console.error(`=== ${taskName} FAILED ===`);
     console.error(err.message);
     if (err.stack) console.error(err.stack);
     return 1;
+  } finally {
+    process.chdir(originalCwd);
   }
 }
 
@@ -1232,7 +1229,6 @@ function runInit() {
 
   initWorkflows();
   initActions(agenticDir);
-  initDirContents("copilot", resolve(agenticDir, "copilot"), "Copilot (shared modules)");
   initDirContents("agents", resolve(agenticDir, "agents"), "Agents");
   initDirContents("seeds", resolve(agenticDir, "seeds"), "Seeds");
   initScripts(agenticDir);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xn-intenton-z2a/agentic-lib",
-  "version": "7.2.22",
+  "version": "7.4.0",
   "description": "Agentic-lib Agentic Coding Systems SDK powering automated GitHub workflows.",
   "type": "module",
   "scripts": {

package/src/actions/agentic-step/config-loader.js

@@ -1,9 +1,9 @@
 // SPDX-License-Identifier: GPL-3.0-only
 // Copyright (C) 2025-2026 Polycode Limited
-// config-loader.js — Thin re-export from shared src/copilot/config.js
+// config-loader.js — Parse agentic-lib.toml and resolve paths
 //
-// Phase 4: Configuration logic now lives in src/copilot/config.js.
-// This file re-exports for backwards compatibility with existing imports.
+// TOML-only configuration. The config file is required.
+// All defaults are defined here in one place.
 
 import { readFileSync, existsSync } from "fs";
 import { dirname, join } from "path";
@@ -306,4 +306,3 @@ export function getWritablePaths(config, override) {
   }
   return config.writablePaths;
 }
-export { loadConfig, getWritablePaths } from "../../copilot/config.js";

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

@@ -1,63 +1,545 @@
 // SPDX-License-Identifier: GPL-3.0-only
 // Copyright (C) 2025-2026 Polycode Limited
-// copilot.js — Thin re-export layer from shared src/copilot/ module.
+// copilot.js — Shared utilities for Copilot SDK task handlers
 //
-// Phase 4: All Copilot SDK logic now lives in src/copilot/.
-// This file re-exports with an @actions/core logger for backwards compatibility
-// with existing task handlers that import from "../copilot.js".
+// Extracts repeated patterns from the 8 task handlers into reusable functions.
 
+import { CopilotClient, approveAll } from "@github/copilot-sdk";
+import { readFileSync, readdirSync, existsSync, statSync } from "fs";
+import { join } from "path";
+import { createAgentTools } from "./tools.js";
 import * as core from "@actions/core";
 
-// Re-export pure functions directly — no logger needed
-export {
-  cleanSource,
-  generateOutline,
-  filterIssues,
-  summariseIssue,
-  extractFeatureSummary,
-  extractNarrative,
-  NARRATIVE_INSTRUCTION,
-  isRateLimitError,
-  retryDelayMs,
-  supportsReasoningEffort,
-} from "../../copilot/session.js";
-
-// Re-export path formatting directly — pure function
-export { formatPathsSection } from "../../copilot/session.js";
-
-// Logger that delegates to @actions/core
-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(" ")),
-};
-
-// Wrap functions that take a logger parameter to inject the @actions/core logger
-import {
-  readOptionalFile as _readOptionalFile,
-  scanDirectory as _scanDirectory,
-  buildClientOptions as _buildClientOptions,
-  logTuningParam as _logTuningParam,
-  runCopilotTask as _runCopilotTask,
-} from "../../copilot/session.js";
+// Models known to support the reasoningEffort SessionConfig parameter.
+// Updated from Copilot SDK ModelInfo.supportedReasoningEfforts (v0.1.30).
+// When in doubt, omit reasoning-effort — the SDK uses its default.
+const MODELS_SUPPORTING_REASONING_EFFORT = new Set(["gpt-5-mini", "o4-mini"]);
 
-export function readOptionalFile(filePath, limit) {
-  return _readOptionalFile(filePath, limit);
+/**
+ * Strip noise from source code that has zero information value.
+ * Removes license headers, collapses blank lines, strips linter directives.
+ *
+ * @param {string} raw - Raw source code
+ * @returns {string} Cleaned source code
+ */
+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 scanDirectory(dirPath, extensions, options = {}) {
-  return _scanDirectory(dirPath, extensions, options, actionsLogger);
+/**
+ * Generate a structural outline of a source file using regex-based extraction.
+ * Captures imports, exports, function/class declarations with line numbers.
+ *
+ * @param {string} raw - Raw source code
+ * @param {string} filePath - File path for the header line
+ * @returns {string} Structural outline
+ */
+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");
+}
+
+/**
+ * Filter issues by recency, init epoch, and label quality.
+ *
+ * @param {Array} issues - GitHub issue objects
+ * @param {Object} [options]
+ * @param {number} [options.staleDays=30] - Issues older than this with no activity are excluded
+ * @param {boolean} [options.excludeBotOnly=true] - Exclude issues with only bot labels
+ * @param {string} [options.initTimestamp] - ISO timestamp; exclude issues created before this epoch
+ * @returns {Array} Filtered issues
+ */
+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) => {
+    // Exclude issues created before the most recent init
+    if (initEpoch > 0) {
+      const created = new Date(issue.created_at).getTime();
+      if (created < 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;
+  });
+}
+
+/**
+ * Create a compact summary of an issue for inclusion in prompts.
+ *
+ * @param {Object} issue - GitHub issue object
+ * @param {number} [bodyLimit=500] - Max chars for issue body
+ * @returns {string} Compact issue summary
+ */
+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}` : ""}`;
+}
+
+/**
+ * Extract a structured summary from a feature markdown file.
+ *
+ * @param {string} content - Feature file content
+ * @param {string} fileName - Feature file name
+ * @returns {string} Structured feature summary
+ */
+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");
 }
 
+/**
+ * Build the CopilotClient options for authentication.
+ *
+ * Auth strategy (in order of preference):
+ * 1. COPILOT_GITHUB_TOKEN env var → override GITHUB_TOKEN/GH_TOKEN in subprocess env
+ *    so the Copilot CLI's auto-login finds the PAT instead of the Actions token.
+ * 2. Fall back to whatever auth is available (GITHUB_TOKEN, gh CLI login, etc.)
+ *
+ * Note: Passing githubToken directly to CopilotClient causes 400 on models.list.
+ * Instead we override the env vars so the CLI subprocess picks up the right token
+ * via its auto-login flow (useLoggedInUser: true).
+ *
+ * @param {string} [githubToken] - Optional token; falls back to COPILOT_GITHUB_TOKEN env var.
+ */
 export function buildClientOptions(githubToken) {
-  return _buildClientOptions(githubToken, actionsLogger);
+  const copilotToken = githubToken || process.env.COPILOT_GITHUB_TOKEN;
+  if (!copilotToken) {
+    throw new Error("COPILOT_GITHUB_TOKEN is required. Set it as a repository secret.");
+  }
+  core.info("[copilot] COPILOT_GITHUB_TOKEN found — overriding subprocess env");
+  const env = { ...process.env };
+  // Override both GITHUB_TOKEN and GH_TOKEN so the Copilot CLI
+  // subprocess uses the Copilot PAT for its auto-login flow
+  env.GITHUB_TOKEN = copilotToken;
+  env.GH_TOKEN = copilotToken;
+  return { env };
 }
 
+/**
+ * Log tuning parameter application with profile context.
+ *
+ * @param {string} param - Parameter name
+ * @param {*} value - Resolved value being applied
+ * @param {string} profileName - Profile the default came from
+ * @param {string} model - Model being used
+ * @param {Object} [clip] - Optional clipping info { available, requested }
+ */
 export function logTuningParam(param, value, profileName, model, clip) {
-  return _logTuningParam(param, value, profileName, model, clip, actionsLogger);
+  const clipInfo = clip
+    ? ` (requested=${clip.requested}, available=${clip.available}, excess=${clip.requested - clip.available})`
+    : "";
+  core.info(`[tuning] ${param}=${value} profile=${profileName} model=${model}${clipInfo}`);
+}
+
+/**
+ * Check if a model supports reasoningEffort.
+ * Uses the static allowlist; at runtime the SDK's models.list() could be used
+ * but that requires an authenticated client which isn't available at config time.
+ *
+ * @param {string} model - Model name
+ * @returns {boolean}
+ */
+export function supportsReasoningEffort(model) {
+  return MODELS_SUPPORTING_REASONING_EFFORT.has(model);
+}
+
+/**
+ * Detect whether an error is an HTTP 429 Too Many Requests (rate limit) response.
+ * The Copilot SDK may surface this as an Error with a status, statusCode, or message.
+ *
+ * @param {unknown} err - The error to test
+ * @returns {boolean}
+ */
+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");
+}
+
+/**
+ * Extract the retry delay in milliseconds from a rate-limit error.
+ * Tries the Retry-After header (seconds) first, then falls back to exponential backoff.
+ *
+ * @param {unknown} err - The error (may have headers or retryAfter)
+ * @param {number} attempt - Zero-based attempt number (0 = first retry)
+ * @param {number} [baseDelayMs=60000] - Base delay for exponential backoff (ms)
+ * @returns {number} Milliseconds to wait before retrying
+ */
+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);
+}
+
+/**
+ * Run a Copilot SDK session and return the response.
+ * Handles the full lifecycle: create client → create session → send → stop.
+ * Retries automatically on HTTP 429 rate-limit responses (up to maxRetries times).
+ *
+ * @param {Object} options
+ * @param {string} options.model - Copilot SDK model name
+ * @param {string} options.systemMessage - System message content
+ * @param {string} options.prompt - The prompt to send
+ * @param {string[]} options.writablePaths - Paths the agent may modify
+ * @param {string} [options.githubToken] - Optional token; falls back to COPILOT_GITHUB_TOKEN env var.
+ * @param {Object} [options.tuning] - Tuning config (reasoningEffort, infiniteSessions)
+ * @param {string} [options.profileName] - Profile name for logging
+ * @param {number} [options.maxRetries=3] - Maximum number of retry attempts on rate-limit errors
+ * @returns {Promise<{content: string, tokensUsed: number}>}
+ */
+export async function runCopilotTask({
+  model,
+  systemMessage,
+  prompt,
+  writablePaths,
+  githubToken,
+  tuning,
+  profileName,
+  maxRetries = 3,
+}) {
+  const profile = profileName || tuning?.profileName || "unknown";
+
+  // Attempt 0 is the initial call; attempts 1..maxRetries are retries after 429s.
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await _runCopilotTaskOnce({ model, systemMessage, prompt, writablePaths, githubToken, tuning, profileName: profile });
+    } catch (err) {
+      if (isRateLimitError(err) && attempt < maxRetries) {
+        const delayMs = retryDelayMs(err, attempt);
+        core.warning(
+          `[copilot] Rate limit (429) hit — waiting ${Math.round(delayMs / 1000)}s before retry ${attempt + 1}/${maxRetries}`,
+        );
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+      } else {
+        throw err;
+      }
+    }
+  }
+  // Unreachable: loop always returns or throws, but satisfies static analysis.
+  throw new Error("[copilot] runCopilotTask: all retry attempts exhausted");
+}
+
+async function _runCopilotTaskOnce({
+  model,
+  systemMessage,
+  prompt,
+  writablePaths,
+  githubToken,
+  tuning,
+  profileName,
+}) {
+  const profile = profileName || tuning?.profileName || "unknown";
+  core.info(
+    `[copilot] Creating client (model=${model}, promptLen=${prompt.length}, writablePaths=${writablePaths.length}, tuning=${tuning?.reasoningEffort || "default"}, profile=${profile})`,
+  );
+
+  const clientOptions = buildClientOptions(githubToken);
+  const client = new CopilotClient(clientOptions);
+
+  try {
+    core.info("[copilot] Creating session...");
+    const sessionConfig = {
+      model,
+      systemMessage: { content: systemMessage },
+      tools: createAgentTools(writablePaths),
+      onPermissionRequest: approveAll,
+      workingDirectory: process.cwd(),
+    };
+
+    // Only set reasoningEffort for models that support it
+    if (tuning?.reasoningEffort && tuning.reasoningEffort !== "none") {
+      if (supportsReasoningEffort(model)) {
+        sessionConfig.reasoningEffort = tuning.reasoningEffort;
+        logTuningParam("reasoningEffort", tuning.reasoningEffort, profile, model);
+      } else {
+        core.info(
+          `[copilot] Skipping reasoningEffort="${tuning.reasoningEffort}" — not supported by model "${model}". Only supported by: ${[...MODELS_SUPPORTING_REASONING_EFFORT].join(", ")}`,
+        );
+      }
+    }
+
+    if (tuning?.infiniteSessions === true) {
+      sessionConfig.infiniteSessions = {};
+      logTuningParam("infiniteSessions", true, profile, model);
+    }
+
+    // Log scan/context tuning params
+    if (tuning?.featuresScan) logTuningParam("featuresScan", tuning.featuresScan, profile, model);
+    if (tuning?.sourceScan) logTuningParam("sourceScan", tuning.sourceScan, profile, model);
+    if (tuning?.sourceContent) logTuningParam("sourceContent", tuning.sourceContent, profile, model);
+    if (tuning?.issuesScan) logTuningParam("issuesScan", tuning.issuesScan, profile, model);
+    if (tuning?.documentSummary) logTuningParam("documentSummary", tuning.documentSummary, profile, model);
+    if (tuning?.discussionComments) logTuningParam("discussionComments", tuning.discussionComments, profile, model);
+
+    const session = await client.createSession(sessionConfig);
+    core.info(`[copilot] Session created: ${session.sessionId}`);
+
+    // Check auth status now that client is connected
+    try {
+      const authStatus = await client.getAuthStatus();
+      core.info(`[copilot] Auth status: ${JSON.stringify(authStatus)}`);
+    } catch (authErr) {
+      core.warning(`[copilot] Auth check failed: ${authErr.message}`);
+    }
+
+    // Accumulate usage from assistant.usage events (tokens are NOT on the sendAndWait response)
+    let totalInputTokens = 0;
+    let totalOutputTokens = 0;
+    let totalCost = 0;
+
+    // Register wildcard event handler for ALL events
+    session.on((event) => {
+      const eventType = event?.type || "unknown";
+      if (eventType === "assistant.message") {
+        const preview = event?.data?.content?.substring(0, 100) || "(no content)";
+        core.info(`[copilot] event=${eventType}: ${preview}...`);
+      } else if (eventType === "assistant.usage") {
+        const d = event?.data || {};
+        const input = d.inputTokens || 0;
+        const output = d.outputTokens || 0;
+        const cacheRead = d.cacheReadTokens || 0;
+        const cost = d.cost || 0;
+        totalInputTokens += input;
+        totalOutputTokens += output;
+        totalCost += cost;
+        core.info(
+          `[copilot] event=${eventType}: model=${d.model} input=${input} output=${output} cacheRead=${cacheRead} cost=${cost}`,
+        );
+      } else if (eventType === "session.idle") {
+        core.info(`[copilot] event=${eventType}`);
+      } else if (eventType === "session.error") {
+        core.error(`[copilot] event=${eventType}: ${JSON.stringify(event?.data || event)}`);
+      } else {
+        core.info(`[copilot] event=${eventType}: ${JSON.stringify(event?.data || event).substring(0, 200)}`);
+      }
+    });
+
+    core.info("[copilot] Sending prompt and waiting for idle...");
+    const response = await session.sendAndWait({ prompt }, 600000);
+    core.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();
+  }
+}
+
+/**
+ * Extract a [NARRATIVE] line from an LLM response.
+ * Returns the text after the tag, or a fallback summary.
+ *
+ * @param {string} content - Raw LLM response content
+ * @param {string} [fallback] - Fallback if no [NARRATIVE] tag found
+ * @returns {string} The narrative sentence
+ */
+export function extractNarrative(content, fallback) {
+  if (!content) return fallback || "";
+  const match = content.match(/\[NARRATIVE\]\s*(.+)/);
+  if (match) return match[1].trim();
+  return fallback || "";
+}
+
+/**
+ * Narrative solicitation to append to system messages.
+ * Asks the LLM to end its response with a one-sentence summary.
+ */
+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.";
+
+/**
+ * Read a file, returning empty string on failure. For optional context files.
+ *
+ * @param {string} filePath - Path to read
+ * @param {number} [limit] - Maximum characters to return
+ * @returns {string}
+ */
+export function readOptionalFile(filePath, limit) {
+  try {
+    const content = readFileSync(filePath, "utf8");
+    return limit ? content.substring(0, limit) : content;
+  } catch (err) {
+    core.debug(`[readOptionalFile] ${filePath}: ${err.message}`);
+    return "";
+  }
+}
+
+/**
+ * Scan a directory for files matching an extension, returning name+content pairs.
+ *
+ * @param {string} dirPath - Directory to scan
+ * @param {string|string[]} extensions - File extension(s) to match (e.g. '.md', ['.js', '.ts'])
+ * @param {Object} [options]
+ * @param {number} [options.fileLimit=10] - Max files to return
+ * @param {number} [options.contentLimit] - Max chars per file content
+ * @param {boolean} [options.recursive=false] - Scan recursively
+ * @param {boolean} [options.sortByMtime=false] - Sort files by modification time (most recent first)
+ * @param {boolean} [options.clean=false] - Strip source noise (license headers, blank lines, linter directives)
+ * @param {boolean} [options.outline=false] - Generate structural outline when content exceeds limit
+ * @returns {Array<{name: string, content: string}>}
+ */
+export function scanDirectory(dirPath, extensions, options = {}) {
+  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) {
+    core.info(
+      `[scanDirectory] Clipped ${dirPath}: ${allFiles.length} files found, returning ${fileLimit} (excess=${allFiles.length - 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);
+        core.info(
+          `[scanDirectory] Outlined ${fileName}: ${raw.length} chars → outline + ${halfLimit} chars`,
+        );
+      } else {
+        content = contentLimit ? raw.substring(0, contentLimit) : raw;
+        if (contentLimit && raw.length > contentLimit) {
+          core.info(
+            `[scanDirectory] Clipped ${fileName}: ${raw.length} chars, returning ${contentLimit} (excess=${raw.length - contentLimit})`,
+          );
+        }
+      }
+      return { name: fileName, content };
+    } catch (err) {
+      core.debug(`[scanDirectory] ${join(dirPath, fileName)}: ${err.message}`);
+      return { name: fileName, content: "" };
+    }
+  });
 }
 
-export async function runCopilotTask(options) {
-  return _runCopilotTask({ ...options, logger: actionsLogger });
+/**
+ * Format the writable/read-only paths section for a prompt.
+ *
+ * @param {string[]} writablePaths
+ * @param {string[]} [readOnlyPaths=[]]
+ * @param {Object} [contextFiles] - Optional raw file contents to include
+ * @param {string} [contextFiles.configToml] - Raw agentic-lib.toml text
+ * @param {string} [contextFiles.packageJson] - Raw package.json text
+ * @returns {string}
+ */
+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");
 }

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

@@ -1,27 +1,142 @@
 // SPDX-License-Identifier: GPL-3.0-only
 // Copyright (C) 2025-2026 Polycode Limited
-// tools.js — Thin re-export from shared src/copilot/tools.js
+// tools.js — Shared tool definitions for agentic-step task handlers
 //
-// 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.
+// 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.
 
-import * as core from "@actions/core";
 import { defineTool } from "@github/copilot-sdk";
-import { createAgentTools as _createAgentTools, isPathWritable } from "../../copilot/tools.js";
-
-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(" ")),
-};
+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";
 
+/**
+ * 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) {
-  return _createAgentTools(writablePaths, actionsLogger, defineTool);
-}
+  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}` };
+      }
+    },
+  });
 
-export { isPathWritable };
+  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,
+        };
+      }
+    },
+  });
+
+  return [readFile, writeFile, listFiles, runCommand];
+}

package/src/copilot/sdk.js

@@ -10,13 +10,11 @@ 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(__dirname, "../../node_modules/@github/copilot-sdk/dist/index.js"),
-  resolve(__dirname, "../actions/agentic-step/node_modules/@github/copilot-sdk/dist/index.js"),
+  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;

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."),
+  };
+}

package/src/copilot/tasks/transform.js

@@ -0,0 +1,120 @@
+// 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,
+  };
+}

package/src/seeds/zero-package.json

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