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

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/copilot/tools.js

@@ -0,0 +1,141 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2025-2026 Polycode Limited
+// src/copilot/tools.js — Shared tool definitions (Actions + CLI)
+//
+// Ported from src/actions/agentic-step/tools.js with logger abstraction.
+
+import { readFileSync, writeFileSync, readdirSync, existsSync, mkdirSync } from "fs";
+import { execSync } from "child_process";
+import { dirname, resolve } from "path";
+import { defaultLogger } from "./logger.js";
+
+/**
+ * Check if a target path is within the allowed writable paths.
+ */
+export function isPathWritable(targetPath, writablePaths) {
+  const resolvedTarget = resolve(targetPath);
+  return writablePaths.some((allowed) => {
+    const resolvedAllowed = resolve(allowed);
+    if (resolvedTarget === resolvedAllowed) return true;
+    if (allowed.endsWith("/") && resolvedTarget.startsWith(resolvedAllowed)) return true;
+    if (resolvedTarget.startsWith(resolvedAllowed + "/")) return true;
+    return false;
+  });
+}
+
+/**
+ * Create the standard set of agent tools.
+ * Can accept defineTool as a parameter (for dynamic SDK import) or import it.
+ *
+ * @param {string[]} writablePaths
+ * @param {Object} [logger]
+ * @param {Function} [defineToolFn] - SDK defineTool function (optional — auto-imported if not provided)
+ * @returns {Array} Array of tools for createSession()
+ */
+export function createAgentTools(writablePaths, logger = defaultLogger, defineToolFn) {
+  // If defineTool not provided, the caller must pass it.
+  // We can't dynamically import SDK here synchronously.
+  const defineTool = defineToolFn;
+  if (!defineTool) {
+    throw new Error("createAgentTools requires defineToolFn parameter (from Copilot SDK)");
+  }
+
+  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);
+      logger.info(`[tool] read_file: ${resolved}`);
+      if (!existsSync(resolved)) return { error: `File not found: ${resolved}` };
+      try {
+        return { content: readFileSync(resolved, "utf8") };
+      } catch (err) {
+        return { error: `Failed to read ${resolved}: ${err.message}` };
+      }
+    },
+  });
+
+  const writeFile = defineTool("write_file", {
+    description: "Write content to a file. Parent directories created automatically. Only writable paths 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);
+      logger.info(`[tool] write_file: ${resolved}`);
+      if (!isPathWritable(resolved, writablePaths)) {
+        return { error: `Path is not writable: ${path}. Writable: ${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.",
+    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);
+      logger.info(`[tool] list_files: ${resolved}`);
+      if (!existsSync(resolved)) return { error: `Directory not found: ${resolved}` };
+      try {
+        const entries = readdirSync(resolved, { withFileTypes: true, recursive: !!recursive });
+        return { files: entries.map((e) => (e.isDirectory() ? `${e.name}/` : e.name)) };
+      } catch (err) {
+        return { error: `Failed to list ${resolved}: ${err.message}` };
+      }
+    },
+  });
+
+  const runCommand = defineTool("run_command", {
+    description: "Run a shell command and return stdout/stderr.",
+    parameters: {
+      type: "object",
+      properties: {
+        command: { type: "string", description: "The shell command to execute" },
+        cwd: { type: "string", description: "Working directory (default: current)" },
+      },
+      required: ["command"],
+    },
+    handler: ({ command, cwd }) => {
+      const workDir = cwd ? resolve(cwd) : process.cwd();
+      logger.info(`[tool] run_command: ${command} (cwd=${workDir})`);
+      const blocked = /\bgit\s+(commit|push|add|reset|checkout|rebase|merge|stash)\b/;
+      if (blocked.test(command)) {
+        return { error: "Git write commands are not allowed." };
+      }
+      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/mcp/server.js

@@ -482,40 +482,58 @@ async function handleIterate({ workspace, cycles = 3, steps }) {
     return text(`Workspace "${workspace}" not found.`);
   }
 
-  const { runIterationLoop, formatIterationResults } = await import("../iterate.js");
-  const stepsToRun = steps || ["maintain-features", "transform", "fix-code"];
-  const startIterNum = (meta.iterations?.length || 0) + 1;
+  const { runHybridSession } = await import("../copilot/hybrid-session.js");
+
+  let config;
+  try {
+    const { loadConfig } = await import("../copilot/config.js");
+    config = loadConfig(join(wsPath, "agentic-lib.toml"));
+  } catch {
+    config = { tuning: {}, model: meta.model || "gpt-5-mini" };
+  }
 
   meta.status = "iterating";
   writeMetadata(wsPath, meta);
 
-  const { results, totalCost, budget } = await runIterationLoop({
-    targetPath: wsPath,
-    model: meta.model,
-    maxCycles: cycles,
-    steps: stepsToRun,
-    onCycleComplete: (record) => {
-      if (record.stopped) return;
-      // Persist each iteration to workspace metadata
-      meta.iterations.push({
-        number: startIterNum + record.cycle - 1,
-        profile: meta.profile,
-        model: meta.model,
-        steps: record.steps,
-        testsPassed: record.testsPassed,
-        filesChanged: record.filesChanged,
-        elapsed: record.elapsed,
-      });
-      writeMetadata(wsPath, meta);
-    },
+  const result = await runHybridSession({
+    workspacePath: wsPath,
+    model: meta.model || config.model || "gpt-5-mini",
+    tuning: config.tuning || {},
+    timeoutMs: 600000,
   });
 
+  const iterNum = (meta.iterations?.length || 0) + 1;
+  meta.iterations.push({
+    number: iterNum,
+    profile: meta.profile,
+    model: meta.model,
+    testsPassed: result.testsPassed,
+    toolCalls: result.toolCalls,
+    testRuns: result.testRuns,
+    filesWritten: result.filesWritten,
+    elapsed: `${result.totalTime}`,
+    endReason: result.endReason,
+  });
   meta.status = "ready";
   writeMetadata(wsPath, meta);
 
-  const output = formatIterationResults(results, totalCost, budget, `Iterate: ${workspace}`);
-  const extra = `\n- Total iterations for this workspace: ${meta.iterations.length}\n- Profile: ${meta.profile} | Model: ${meta.model}`;
-  return text(output + extra);
+  const lines = [
+    `# Iterate: ${workspace}`,
+    "",
+    `- Success: ${result.success}`,
+    `- Tests passed: ${result.testsPassed}`,
+    `- Session time: ${result.sessionTime}s`,
+    `- Total time: ${result.totalTime}s`,
+    `- Tool calls: ${result.toolCalls}`,
+    `- Test runs: ${result.testRuns}`,
+    `- Files written: ${result.filesWritten}`,
+    `- Tokens: ${result.tokensIn + result.tokensOut} (in=${result.tokensIn} out=${result.tokensOut})`,
+    `- End reason: ${result.endReason}`,
+    "",
+    `- Total iterations for this workspace: ${meta.iterations.length}`,
+    `- Profile: ${meta.profile} | Model: ${meta.model}`,
+  ];
+  return text(lines.join("\n"));
 }
 
 async function handleRunTests({ workspace }) {

package/src/seeds/zero-README.md

@@ -46,6 +46,37 @@ MISSION.md → [supervisor] → dispatch workflows → Issue → Code → Test
 
 The pipeline runs as GitHub Actions workflows. An LLM supervisor gathers repository context (issues, PRs, workflow runs, features) and strategically dispatches other workflows. Each workflow uses the Copilot SDK to make targeted changes.
 
+## File Layout
+
+```
+src/lib/main.js              ← library (Node entry point: identity + mission functions)
+src/web/index.html            ← web page (browser: imports lib-meta.js, demonstrates library)
+tests/unit/main.test.js       ← unit tests (import main.js directly, test API-level detail)
+tests/unit/web.test.js        ← web structure tests (read index.html as text, verify wiring)
+tests/behaviour/              ← Playwright E2E (run page in browser, import main.js for coupling)
+docs/                         ← build output (generated by npm run build:web)
+docs/lib-meta.js              ← generated: exports name, version, description from package.json
+```
+
+These files form a **coupled unit**. Changes to the library must flow through to the web page, and tests verify this coupling:
+
+- `src/lib/main.js` exports `getIdentity()` → returns `{ name, version, description }` from `package.json`
+- `npm run build:web` copies `src/web/*` to `docs/` and generates `docs/lib-meta.js` from `package.json`
+- `src/web/index.html` imports `lib-meta.js` at runtime → displays library identity on the page
+- The behaviour test imports `getIdentity()` from `main.js` AND reads `#lib-version` from the rendered page → asserts they match
+
+This coupling test proves the web page is consuming the real library via the build pipeline. Mission-specific functions should follow the same path — never duplicate library logic inline in the web page.
+
+## Test Strategy
+
+| Test layer | What it tests | How it binds |
+|------------|--------------|--------------|
+| **Unit tests** (`tests/unit/main.test.js`) | Library API: return values, error types, edge cases | Imports directly from `src/lib/main.js` |
+| **Web structure tests** (`tests/unit/web.test.js`) | HTML structure: expected elements, `lib-meta.js` import | Reads `src/web/index.html` as text |
+| **Behaviour tests** (`tests/behaviour/`) | End-to-end: page renders, interactive elements work | Playwright loads the built site; coupling test imports `getIdentity()` from `main.js` and asserts the page displays the same version |
+
+The **coupling test** in the behaviour test is the key invariant: it proves the web page displays values from the actual library, not hardcoded or duplicated values. If the build pipeline breaks, this test fails.
+
 ## Configuration
 
 Edit `agentic-lib.toml` to tune the system:

package/src/seeds/zero-behaviour.test.js

@@ -1,14 +1,22 @@
 // SPDX-License-Identifier: MIT
 // Copyright (C) 2025-2026 Polycode Limited
 import { test, expect } from "@playwright/test";
+import { getIdentity } from "../../src/lib/main.js";
 
 test("homepage returns 200 and renders", async ({ page }) => {
-  const response = await page.goto("/");
+  const response = await page.goto("/", { waitUntil: "networkidle" });
   expect(response.status()).toBe(200);
 
-  await expect(page.locator("#lib-name")).toBeVisible();
-  await expect(page.locator("#lib-version")).toBeVisible();
-  await expect(page.locator("#demo-output")).toBeVisible();
+  await expect(page.locator("#lib-name")).toBeVisible({ timeout: 10000 });
+  await expect(page.locator("#lib-version")).toBeVisible({ timeout: 10000 });
+  await expect(page.locator("#demo-output")).toBeVisible({ timeout: 10000 });
 
   await page.screenshot({ path: "SCREENSHOT_INDEX.png", fullPage: true });
 });
+
+test("page displays the library version from src/lib/main.js", async ({ page }) => {
+  const { version } = getIdentity();
+  await page.goto("/", { waitUntil: "networkidle" });
+  const pageVersion = await page.locator("#lib-version").textContent();
+  expect(pageVersion).toContain(version);
+});

package/src/seeds/zero-package.json

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

package/src/seeds/zero-playwright.config.js

@@ -5,6 +5,7 @@ import { defineConfig } from "@playwright/test";
 export default defineConfig({
   testDir: "tests/behaviour",
   timeout: 30000,
+  retries: 2,
   use: {
     baseURL: "http://localhost:3000",
   },