@xn-intenton-z2a/agentic-lib 7.1.6

package/src/actions/agentic-step/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@xn-intenton-z2a/agentic-step",
+  "version": "0.1.0",
+  "description": "GitHub Action wrapping the Copilot SDK for autonomous code evolution",
+  "type": "module",
+  "main": "index.js",
+  "scripts": {
+    "test": "vitest --run",
+    "build": "echo 'No build step required'"
+  },
+  "dependencies": {
+    "@actions/core": "^3.0.0",
+    "@actions/github": "^9.0.0",
+    "@github/copilot-sdk": "0.1.29",
+    "js-yaml": "^4.1.0",
+    "smol-toml": "^1.6.0"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.18"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "license": "GPL-3.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/xn-intenton-z2a/agentic-lib"
+  }
+}

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

@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2025-2026 Polycode Limited
+// safety.js — WIP limits, attempt tracking, and path enforcement
+//
+// Provides safety checks that prevent the agentic system from:
+// - Exceeding WIP (work-in-progress) limits on issues
+// - Retrying failed branches/issues beyond configured limits
+// - Writing to paths outside the allowed set
+
+import { logSafetyCheck } from "./logging.js";
+
+/**
+ * Check if the number of open issues with a given label is below the WIP limit.
+ *
+ * @param {import('@actions/github').GitHub} octokit - GitHub API client
+ * @param {Object} repo - { owner, repo } identifying the repository
+ * @param {string} label - Issue label to count (e.g. 'feature', 'maintenance')
+ * @param {number} limit - Maximum allowed open issues
+ * @returns {Promise<{allowed: boolean, count: number}>}
+ */
+export async function checkWipLimit(octokit, repo, label, limit) {
+  const { data: issues } = await octokit.rest.issues.listForRepo({
+    ...repo,
+    state: "open",
+    labels: label,
+    per_page: limit + 1,
+  });
+  const count = issues.length;
+  const allowed = count < limit;
+  logSafetyCheck("wip-limit", allowed, { label, count, limit });
+  return { allowed, count };
+}
+
+/**
+ * Count how many branches exist for a given issue (by naming convention).
+ *
+ * @param {import('@actions/github').GitHub} octokit - GitHub API client
+ * @param {Object} repo - { owner, repo } identifying the repository
+ * @param {string|number} issueNumber - The issue number
+ * @param {string} branchPrefix - Branch naming prefix (e.g. 'agentic-lib-issue-')
+ * @returns {Promise<number>} Number of branches matching the pattern
+ */
+export async function countBranchAttempts(octokit, repo, issueNumber, branchPrefix) {
+  const pattern = `${branchPrefix}${issueNumber}`;
+  const { data: refs } = await octokit.rest.git.listMatchingRefs({
+    ...repo,
+    ref: `heads/${pattern}`,
+  });
+  return refs.length;
+}
+
+/**
+ * Check if the number of attempts for an issue is below the limit.
+ *
+ * @param {import('@actions/github').GitHub} octokit - GitHub API client
+ * @param {Object} repo - { owner, repo }
+ * @param {string|number} issueNumber - The issue number
+ * @param {string} branchPrefix - Branch naming prefix
+ * @param {number} maxAttempts - Maximum allowed attempts
+ * @returns {Promise<{allowed: boolean, attempts: number}>}
+ */
+export async function checkAttemptLimit(octokit, repo, issueNumber, branchPrefix, maxAttempts) {
+  const attempts = await countBranchAttempts(octokit, repo, issueNumber, branchPrefix);
+  const allowed = attempts < maxAttempts;
+  logSafetyCheck("attempt-limit", allowed, { issueNumber, attempts, maxAttempts });
+  return { allowed, attempts };
+}
+
+/**
+ * Validate that a target path is within the allowed writable paths.
+ *
+ * @param {string} targetPath - The path being written to
+ * @param {string[]} writablePaths - Allowed writable paths
+ * @returns {boolean} True if the path is allowed
+ */
+export function isPathWritable(targetPath, writablePaths) {
+  const writable = writablePaths.some((allowed) => {
+    if (targetPath === allowed) return true;
+    if (allowed.endsWith("/") && targetPath.startsWith(allowed)) return true;
+    if (targetPath.startsWith(allowed + "/")) return true;
+    return false;
+  });
+  logSafetyCheck("path-writable", writable, { targetPath });
+  return writable;
+}
+
+/**
+ * Check if an issue is already resolved (closed).
+ *
+ * @param {import('@actions/github').GitHub} octokit - GitHub API client
+ * @param {Object} repo - { owner, repo }
+ * @param {string|number} issueNumber - The issue number
+ * @returns {Promise<boolean>} True if the issue is closed
+ */
+export async function isIssueResolved(octokit, repo, issueNumber) {
+  const { data: issue } = await octokit.rest.issues.get({
+    ...repo,
+    issue_number: Number(issueNumber),
+  });
+  const resolved = issue.state === "closed";
+  logSafetyCheck("issue-resolved", !resolved, { issueNumber, state: issue.state });
+  return resolved;
+}

package/src/actions/agentic-step/tasks/discussions.js

@@ -0,0 +1,141 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2025-2026 Polycode Limited
+// tasks/discussions.js — GitHub Discussions bot
+//
+// Responds to GitHub Discussions, creates features, seeds repositories,
+// and provides status updates. Uses the Copilot SDK for natural conversation.
+
+import * as core from "@actions/core";
+import { existsSync } from "fs";
+import { runCopilotTask, readOptionalFile, scanDirectory } from "../copilot.js";
+
+/**
+ * Respond to a GitHub Discussion using the Copilot SDK.
+ *
+ * @param {Object} context - Task context from index.js
+ * @returns {Promise<Object>} Result with outcome, action, tokensUsed, model
+ */
+export async function discussions(context) {
+  const { octokit, config, instructions, model, discussionUrl } = context;
+
+  if (!discussionUrl) {
+    throw new Error("discussions task requires discussion-url input");
+  }
+
+  // Parse discussion URL and fetch content via GraphQL
+  const urlMatch = discussionUrl.match(/github\.com\/([^/]+)\/([^/]+)\/discussions\/(\d+)/);
+  let discussionTitle = "";
+  let discussionBody = "";
+  let discussionComments = [];
+
+  if (urlMatch) {
+    const [, urlOwner, urlRepo, discussionNumber] = urlMatch;
+    try {
+      const query = `query {
+        repository(owner: "${urlOwner}", name: "${urlRepo}") {
+          discussion(number: ${discussionNumber}) {
+            title
+            body
+            comments(last: 10) {
+              nodes {
+                body
+                author { login }
+                createdAt
+              }
+            }
+          }
+        }
+      }`;
+      const result = await octokit.graphql(query);
+      const discussion = result.repository.discussion;
+      discussionTitle = discussion.title || "";
+      discussionBody = discussion.body || "";
+      discussionComments = discussion.comments.nodes || [];
+      core.info(
+        `Fetched discussion #${discussionNumber}: "${discussionTitle}" (${discussionComments.length} comments)`,
+      );
+    } catch (err) {
+      core.warning(`Failed to fetch discussion content via GraphQL: ${err.message}. Falling back to URL-only.`);
+    }
+  } else {
+    core.warning(`Could not parse discussion URL: ${discussionUrl}`);
+  }
+
+  const mission = readOptionalFile(config.paths.mission.path);
+  const contributing = readOptionalFile(config.paths.contributing.path, 1000);
+
+  const featuresPath = config.paths.features.path;
+  let featureNames = [];
+  if (existsSync(featuresPath)) {
+    featureNames = scanDirectory(featuresPath, ".md").map((f) => f.name.replace(".md", ""));
+  }
+
+  const intentionPath = config.intentionBot.intentionFilepath;
+  const recentActivity = readOptionalFile(intentionPath).split("\n").slice(-20).join("\n");
+
+  const agentInstructions = instructions || "Respond to the GitHub Discussion as the repository bot.";
+
+  const prompt = [
+    "## Instructions",
+    agentInstructions,
+    "",
+    "## Discussion",
+    `URL: ${discussionUrl}`,
+    discussionTitle ? `### ${discussionTitle}` : "",
+    discussionBody || "(no body)",
+    discussionComments.length > 0 ? `### Comments (${discussionComments.length})` : "",
+    ...discussionComments.map((c) => `**${c.author?.login || "unknown"}** (${c.createdAt}):\n${c.body}`),
+    "",
+    "## Context",
+    `### Mission\n${mission}`,
+    contributing ? `### Contributing\n${contributing}` : "",
+    `### Current Features\n${featureNames.join(", ") || "none"}`,
+    recentActivity ? `### Recent Activity\n${recentActivity}` : "",
+    "",
+    "## Available Actions",
+    "Respond with one of these action tags in your response:",
+    "- `[ACTION:seed-repository]` — Reset the sandbox to initial state",
+    "- `[ACTION:create-feature] <name>` — Create a new feature",
+    "- `[ACTION:update-feature] <name>` — Update an existing feature",
+    "- `[ACTION:delete-feature] <name>` — Delete a feature that is no longer needed",
+    "- `[ACTION:create-issue] <title>` — Create a new issue",
+    "- `[ACTION:nop]` — No action needed, just respond conversationally",
+    "- `[ACTION:mission-complete]` — Declare the current mission complete",
+    "- `[ACTION:stop]` — Halt automation",
+    "",
+    "Include exactly one action tag. The rest of your response is the discussion reply.",
+    "",
+    "## Mission Protection",
+    "If the user requests something that contradicts or would undermine the mission,",
+    "you MUST push back. Explain why the request conflicts with the mission and suggest",
+    "an alternative that aligns with it. Use `[ACTION:nop]` in this case.",
+    "The mission is the non-negotiable foundation of this repository.",
+  ].join("\n");
+
+  const { content, tokensUsed } = await runCopilotTask({
+    model,
+    systemMessage:
+      "You are a repository bot that responds to GitHub Discussions. You are self-aware — you refer to yourself as the repository. Be helpful, adaptive, and proactive about suggesting features. You can update and delete features proactively when they are outdated or completed. You MUST protect the mission: if a user requests something that contradicts the mission, push back politely and suggest an aligned alternative.",
+    prompt,
+    writablePaths: [],
+  });
+
+  // Parse action from response
+  const actionMatch = content.match(/\[ACTION:(\S+?)\](.+)?/);
+  const action = actionMatch ? actionMatch[1] : "nop";
+  const actionArg = actionMatch && actionMatch[2] ? actionMatch[2].trim() : "";
+  const replyBody = content.replace(/\[ACTION:\S+?\].+/, "").trim();
+
+  core.info(`Discussion bot action: ${action}, arg: ${actionArg}`);
+
+  const argSuffix = actionArg ? ` (${actionArg})` : "";
+  return {
+    outcome: `discussion-${action}`,
+    tokensUsed,
+    model,
+    details: `Action: ${action}${argSuffix}\nReply: ${replyBody.substring(0, 200)}`,
+    action,
+    actionArg,
+    replyBody,
+  };
+}

package/src/actions/agentic-step/tasks/enhance-issue.js

@@ -0,0 +1,102 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2025-2026 Polycode Limited
+// tasks/enhance-issue.js — Add testable acceptance criteria to issues
+//
+// Takes an issue and enhances it with clear, testable acceptance criteria
+// so that the resolve-issue task can implement it effectively.
+
+import * as core from "@actions/core";
+import { isIssueResolved } from "../safety.js";
+import { runCopilotTask, readOptionalFile, scanDirectory } from "../copilot.js";
+
+/**
+ * Enhance a GitHub issue with testable acceptance criteria.
+ *
+ * @param {Object} context - Task context from index.js
+ * @returns {Promise<Object>} Result with outcome, tokensUsed, model
+ */
+export async function enhanceIssue(context) {
+  const { octokit, repo, config, issueNumber, instructions, model } = context;
+
+  if (!issueNumber) {
+    throw new Error("enhance-issue task requires issue-number input");
+  }
+
+  if (await isIssueResolved(octokit, repo, issueNumber)) {
+    return { outcome: "nop", details: "Issue already resolved" };
+  }
+
+  const { data: issue } = await octokit.rest.issues.get({
+    ...repo,
+    issue_number: Number(issueNumber),
+  });
+
+  if (issue.labels.some((l) => l.name === "ready")) {
+    return { outcome: "nop", details: "Issue already has ready label" };
+  }
+
+  const contributing = readOptionalFile(config.paths.contributing.path);
+  const features = scanDirectory(config.paths.features.path, ".md", { contentLimit: 500 });
+
+  const agentInstructions = instructions || "Enhance this issue with clear, testable acceptance criteria.";
+
+  const prompt = [
+    "## Instructions",
+    agentInstructions,
+    "",
+    `## Issue #${issueNumber}: ${issue.title}`,
+    issue.body || "(no description)",
+    "",
+    contributing ? `## Contributing Guidelines\n${contributing.substring(0, 1000)}` : "",
+    features.length > 0 ? `## Related Features\n${features.map((f) => f.content).join("\n---\n")}` : "",
+    "",
+    "## Your Task",
+    "Write an enhanced version of this issue body that includes:",
+    "1. Clear problem statement or feature description",
+    "2. Testable acceptance criteria (Given/When/Then or checkbox format)",
+    "3. Implementation hints if applicable",
+    "",
+    "Output ONLY the new issue body text, no markdown code fences.",
+  ].join("\n");
+
+  const { content: enhancedBody, tokensUsed } = await runCopilotTask({
+    model,
+    systemMessage: "You are a requirements analyst. Enhance GitHub issues with clear, testable acceptance criteria.",
+    prompt,
+    writablePaths: [],
+  });
+
+  if (enhancedBody.trim()) {
+    await octokit.rest.issues.update({
+      ...repo,
+      issue_number: Number(issueNumber),
+      body: enhancedBody.trim(),
+    });
+    await octokit.rest.issues.addLabels({
+      ...repo,
+      issue_number: Number(issueNumber),
+      labels: ["ready"],
+    });
+    await octokit.rest.issues.createComment({
+      ...repo,
+      issue_number: Number(issueNumber),
+      body: [
+        "**Automated Enhancement:** This issue has been enhanced with testable acceptance criteria.",
+        "",
+        `**Task:** enhance-issue`,
+        `**Model:** ${model}`,
+        `**Features referenced:** ${features.length}`,
+        "",
+        "The issue body has been updated. The `ready` label has been added to indicate it is ready for implementation.",
+      ].join("\n"),
+    });
+    core.info(`Issue #${issueNumber} enhanced and labeled 'ready'`);
+  }
+
+  return {
+    outcome: "issue-enhanced",
+    tokensUsed,
+    model,
+    details: `Enhanced issue #${issueNumber} with acceptance criteria`,
+  };
+}

package/src/actions/agentic-step/tasks/fix-code.js

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2025-2026 Polycode Limited
+// tasks/fix-code.js — Fix failing tests on a PR
+//
+// Given a PR number with failing tests, analyzes the test output,
+// generates fixes using the Copilot SDK, and pushes a commit.
+
+import * as core from "@actions/core";
+import { runCopilotTask, formatPathsSection } from "../copilot.js";
+
+/**
+ * Fix failing code on a pull request.
+ *
+ * @param {Object} context - Task context from index.js
+ * @returns {Promise<Object>} Result with outcome, tokensUsed, model
+ */
+export async function fixCode(context) {
+  const { octokit, repo, config, prNumber, instructions, writablePaths, testCommand, model } = context;
+
+  if (!prNumber) {
+    throw new Error("fix-code task requires pr-number input");
+  }
+
+  // Fetch the PR and check runs
+  const { data: pr } = await octokit.rest.pulls.get({ ...repo, pull_number: Number(prNumber) });
+  const { data: checkRuns } = await octokit.rest.checks.listForRef({ ...repo, ref: pr.head.sha, per_page: 10 });
+
+  const failedChecks = checkRuns.check_runs.filter((cr) => cr.conclusion === "failure");
+  if (failedChecks.length === 0) {
+    core.info(`PR #${prNumber} has no failing checks. Returning nop.`);
+    return { outcome: "nop", details: "No failing checks found" };
+  }
+
+  const failureDetails = failedChecks.map((cr) => `**${cr.name}:** ${cr.output?.summary || "Failed"}`).join("\n");
+  const agentInstructions = instructions || "Fix the failing tests by modifying the source code.";
+  const readOnlyPaths = config.readOnlyPaths;
+
+  const prompt = [
+    "## Instructions",
+    agentInstructions,
+    "",
+    `## Pull Request #${prNumber}: ${pr.title}`,
+    "",
+    pr.body || "(no description)",
+    "",
+    "## Failing Checks",
+    failureDetails,
+    "",
+    formatPathsSection(writablePaths, readOnlyPaths),
+    "",
+    "## Constraints",
+    `- Run \`${testCommand}\` to validate your fixes`,
+    "- Make minimal changes to fix the failing tests",
+  ].join("\n");
+
+  const { tokensUsed } = await runCopilotTask({
+    model,
+    systemMessage: `You are an autonomous coding agent fixing failing tests on PR #${prNumber}. Make minimal, targeted changes to fix the test failures.`,
+    prompt,
+    writablePaths,
+  });
+
+  core.info(`Copilot SDK fix response received (${tokensUsed} tokens)`);
+
+  return {
+    outcome: "fix-applied",
+    tokensUsed,
+    model,
+    details: `Applied fix for ${failedChecks.length} failing check(s) on PR #${prNumber}`,
+  };
+}

package/src/actions/agentic-step/tasks/maintain-features.js

@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2025-2026 Polycode Limited
+// tasks/maintain-features.js — Feature lifecycle management
+//
+// Reviews existing features, creates new ones from mission/library analysis,
+// prunes completed/irrelevant features, and ensures quality.
+
+import { runCopilotTask, readOptionalFile, scanDirectory, formatPathsSection } from "../copilot.js";
+
+/**
+ * Maintain the feature set — create, update, or prune feature files.
+ *
+ * @param {Object} context - Task context from index.js
+ * @returns {Promise<Object>} Result with outcome, tokensUsed, model
+ */
+export async function maintainFeatures(context) {
+  const { config, instructions, writablePaths, model, octokit, repo } = context;
+
+  const mission = readOptionalFile(config.paths.mission.path);
+  const featuresPath = config.paths.features.path;
+  const featureLimit = config.paths.features.limit;
+  const features = scanDirectory(featuresPath, ".md");
+  const libraryDocs = scanDirectory(config.paths.library.path, ".md", {
+    contentLimit: 1000,
+  });
+
+  const { data: closedIssues } = await octokit.rest.issues.listForRepo({
+    ...repo,
+    state: "closed",
+    per_page: 20,
+    sort: "updated",
+    direction: "desc",
+  });
+
+  const agentInstructions = instructions || "Maintain the feature set by creating, updating, or pruning features.";
+
+  const prompt = [
+    "## Instructions",
+    agentInstructions,
+    "",
+    "## 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}`),
+    "",
+    `## Recently Closed Issues (${closedIssues.length})`,
+    ...closedIssues.slice(0, 10).map((i) => `- #${i.number}: ${i.title}`),
+    "",
+    "## Your Task",
+    `1. Review each existing feature — if it is already implemented or irrelevant, delete it.`,
+    `2. If there are fewer than ${featureLimit} features, create new features aligned with the mission.`,
+    "3. Ensure each feature has clear, testable acceptance criteria.",
+    "",
+    formatPathsSection(writablePaths, config.readOnlyPaths),
+    "",
+    "## Constraints",
+    `- Maximum ${featureLimit} feature files`,
+    "- Feature files must be markdown with a descriptive filename (e.g. HTTP_SERVER.md)",
+  ].join("\n");
+
+  const { tokensUsed } = 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.",
+    prompt,
+    writablePaths,
+  });
+
+  return {
+    outcome: "features-maintained",
+    tokensUsed,
+    model,
+    details: `Maintained features (${features.length} existing, limit ${featureLimit})`,
+  };
+}

package/src/actions/agentic-step/tasks/maintain-library.js

@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2025-2026 Polycode Limited
+// tasks/maintain-library.js — Library and knowledge management
+//
+// Crawls SOURCES.md, updates library documents, maintains the knowledge base
+// that provides context for feature generation and issue resolution.
+
+import * as core from "@actions/core";
+import { runCopilotTask, readOptionalFile, scanDirectory, formatPathsSection } from "../copilot.js";
+
+/**
+ * Maintain the library of knowledge documents from source URLs.
+ *
+ * @param {Object} context - Task context from index.js
+ * @returns {Promise<Object>} Result with outcome, tokensUsed, model
+ */
+export async function maintainLibrary(context) {
+  const { config, instructions, writablePaths, model } = context;
+
+  const sources = readOptionalFile(config.paths.librarySources.path);
+  if (!sources.trim()) {
+    core.info("No sources found. Returning nop.");
+    return { outcome: "nop", details: "No SOURCES.md or empty" };
+  }
+
+  const libraryPath = config.paths.library.path;
+  const libraryLimit = config.paths.library.limit;
+  const libraryDocs = scanDirectory(libraryPath, ".md", { contentLimit: 500 });
+
+  const agentInstructions = instructions || "Maintain the library by updating documents from sources.";
+
+  const prompt = [
+    "## Instructions",
+    agentInstructions,
+    "",
+    "## 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 based on the source content.",
+    "3. Remove library documents that no longer have corresponding sources.",
+    "",
+    formatPathsSection(writablePaths, config.readOnlyPaths),
+    "",
+    "## Constraints",
+    `- Maximum ${libraryLimit} library documents`,
+  ].join("\n");
+
+  const { tokensUsed } = await runCopilotTask({
+    model,
+    systemMessage:
+      "You are a knowledge librarian. Maintain a library of technical documents extracted from web sources.",
+    prompt,
+    writablePaths,
+  });
+
+  return {
+    outcome: "library-maintained",
+    tokensUsed,
+    model,
+    details: `Maintained library (${libraryDocs.length} docs, limit ${libraryLimit})`,
+  };
+}