@a5c-ai/babysitter-github 0.1.1-staging.0825aadb → 0.1.1-staging.11cb9e78

package/README.md

@@ -1,6 +1,9 @@
 # @a5c-ai/babysitter-github
 
-Babysitter orchestration plugin for [GitHub Copilot CLI](https://docs.github.com/en/copilot/using-github-copilot/using-github-copilot-in-the-command-line).
+Babysitter orchestration plugin for GitHub Copilot. It supports both:
+
+- **GitHub Copilot CLI** via the local plugin and hook model
+- **GitHub Copilot coding agent / cloud agent** via repository-installed skills and instructions
 
 This package ships a complete Copilot CLI plugin bundle -- skills, lifecycle
 hooks, and SDK integration -- that lets you run Babysitter's event-sourced,
@@ -71,6 +74,30 @@ Install into a specific workspace:
 babysitter-github install --workspace /path/to/repo
 ```
 
+### GitHub Copilot cloud agent installation
+
+For GitHub Copilot's cloud-hosted coding agent, install repository-scoped
+Babysitter support instead of the local `~/.copilot` CLI plugin surface:
+
+```bash
+babysitter-github install --cloud-agent --workspace /path/to/repo
+```
+
+This installs:
+
+- a mirrored Babysitter GitHub plugin bundle under `.github/babysitter/github-plugin/`
+- Babysitter skills under `.github/skills/`
+- a managed Babysitter block in `AGENTS.md`
+- a managed Babysitter block in `.github/copilot-instructions.md`
+- a `copilot-setup-steps` workflow, or a generated merge candidate if the repo already has one
+
+If the repository already has a custom `copilot-setup-steps.yml`, the
+installer preserves it and writes a merge candidate to:
+
+```text
+.github/workflows/copilot-setup-steps.babysitter.generated.yml
+```
+
 If the workspace does not already have an active process-library binding, the
 installer bootstraps the shared global SDK process library automatically:
 
@@ -101,6 +128,11 @@ The plugin provides:
 - Plugin-level lifecycle hooks for `sessionStart`, `sessionEnd`, and
   `userPromptSubmitted`
 
+For Copilot cloud agent, the hook scripts are mirrored into the repository as
+part of the installed plugin bundle for reference and parity, but the hosted
+agent path is driven by repository instructions, skills, and setup workflow
+instead of local `~/.copilot/hooks.json`.
+
 The process library is fetched and bound through the SDK CLI in
 `~/.a5c/active/process-library.json`.
 
@@ -173,8 +205,21 @@ preserving semantic content.
 ### AGENTS.md
 
 The plugin uses `AGENTS.md` (the Copilot CLI equivalent of `CLAUDE.md`) for
-custom agent instructions. This file is read by Copilot CLI to configure
-agent behavior within sessions.
+custom agent instructions. The cloud-agent installer appends a managed
+Babysitter section to the repository root `AGENTS.md` so the hosted agent can
+see the same orchestration guidance.
+
+### .github/copilot-instructions.md
+
+The cloud-agent installer also appends a managed Babysitter block to
+`.github/copilot-instructions.md`. This gives GitHub-hosted Copilot sessions a
+repository-wide entrypoint for the Babysitter skills and setup workflow.
+
+### copilot-setup-steps workflow
+
+The cloud-agent path seeds `.github/workflows/copilot-setup-steps.yml` with a
+`copilot-setup-steps` job that installs the Babysitter SDK and initializes the
+active process library before the cloud agent starts working.
 
 ### Environment Variables
 
@@ -446,6 +491,22 @@ plugins/babysitter-github/
   AGENTS.md                # Custom instructions for Copilot CLI
 ```
 
+Cloud-agent installation additionally writes into the target repository:
+
+```
+.github/
+  babysitter/github-plugin/                # Mirrored plugin bundle for repo-local visibility
+  skills/
+    babysitter-babysit/SKILL.md            # Installed Babysitter cloud skills
+    babysitter-call/SKILL.md
+    ...
+  copilot-instructions.md                  # Managed Babysitter block appended
+  workflows/
+    copilot-setup-steps.yml                # Managed workflow when no custom file exists
+    copilot-setup-steps.babysitter.generated.yml  # Merge candidate when a custom file already exists
+AGENTS.md                                  # Managed Babysitter block appended
+```
+
 ## Verification
 
 Verify marketplace registration:

package/bin/cli.js

@@ -11,6 +11,7 @@ function printUsage() {
     'Usage:',
     '  babysitter-github install [--global]',
     '  babysitter-github install --workspace [path]',
+    '  babysitter-github install --cloud-agent [--workspace [path]]',
     '  babysitter-github uninstall',
   ].join('\n'));
 }
@@ -18,6 +19,7 @@ function printUsage() {
 function parseInstallArgs(argv) {
   let scope = 'global';
   let workspace = null;
+  let cloudAgent = false;
   const passthrough = [];
 
   for (let i = 0; i < argv.length; i += 1) {
@@ -43,10 +45,16 @@ function parseInstallArgs(argv) {
       }
       continue;
     }
+    if (arg === '--cloud-agent') {
+      cloudAgent = true;
+      passthrough.push(arg);
+      continue;
+    }
     passthrough.push(arg);
   }
 
   return {
+    cloudAgent,
     scope,
     workspace,
     passthrough,
@@ -75,6 +83,10 @@ function main() {
 
   if (command === 'install') {
     const parsed = parseInstallArgs(rest);
+    if (parsed.cloudAgent) {
+      runNodeScript(path.join(PACKAGE_ROOT, 'bin', 'install.js'), parsed.passthrough);
+      return;
+    }
     if (parsed.scope === 'workspace') {
       const args = [];
       if (parsed.workspace) {

package/bin/install-shared.js

@@ -35,6 +35,22 @@ const PLUGIN_BUNDLE_ENTRIES = [
   'versions.json',
   'AGENTS.md',
 ];
+const CLOUD_AGENT_BUNDLE_ENTRIES = [
+  '.github',
+  'AGENTS.md',
+  'README.md',
+  'bin',
+  'commands',
+  'hooks',
+  'hooks.json',
+  'package.json',
+  'plugin.json',
+  'scripts',
+  'skills',
+  'versions.json',
+];
+const MANAGED_BLOCK_START = '<!-- BEGIN BABYSITTER GITHUB CLOUD AGENT -->';
+const MANAGED_BLOCK_END = '<!-- END BABYSITTER GITHUB CLOUD AGENT -->';
 
 function getCopilotHome() {
   if (process.env.COPILOT_HOME) return path.resolve(process.env.COPILOT_HOME);
@@ -145,6 +161,79 @@ function writeJson(filePath, value) {
   writeFileIfChanged(filePath, `${JSON.stringify(value, null, 2)}\n`);
 }
 
+function replaceManagedMarkdownBlock(existing, block) {
+  const normalized = String(existing || '').replace(/\r\n/g, '\n');
+  const managedBlock = `${MANAGED_BLOCK_START}\n${block.trim()}\n${MANAGED_BLOCK_END}`;
+  const escapedStart = MANAGED_BLOCK_START.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const escapedEnd = MANAGED_BLOCK_END.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const managedPattern = new RegExp(`${escapedStart}[\\s\\S]*?${escapedEnd}`, 'm');
+
+  if (managedPattern.test(normalized)) {
+    return normalized.replace(managedPattern, managedBlock).replace(/\n{3,}/g, '\n\n').trimEnd() + '\n';
+  }
+
+  if (normalized.trim().length === 0) {
+    return `${managedBlock}\n`;
+  }
+
+  return `${normalized.trimEnd()}\n\n${managedBlock}\n`;
+}
+
+function writeManagedMarkdown(filePath, block) {
+  const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
+  return writeFileIfChanged(filePath, replaceManagedMarkdownBlock(existing, block));
+}
+
+function readSdkVersion(packageRoot) {
+  const versionsPath = path.join(packageRoot, 'versions.json');
+  if (!fs.existsSync(versionsPath)) {
+    return 'latest';
+  }
+  try {
+    const parsed = readJson(versionsPath);
+    return typeof parsed.sdkVersion === 'string' && parsed.sdkVersion.trim() !== ''
+      ? parsed.sdkVersion.trim()
+      : 'latest';
+  } catch {
+    return 'latest';
+  }
+}
+
+function toLowerHyphenName(name) {
+  return String(name)
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+function rewriteCloudSkill(skillId, contents) {
+  const normalized = String(contents).replace(/\r\n/g, '\n');
+  const prefixedName = `babysitter-${skillId}`;
+  let next = normalized;
+
+  if (next.startsWith('---\n')) {
+    next = next.replace(/^---\n([\s\S]*?)\n---\n?/, (_match, frontmatter) => {
+      const lines = String(frontmatter).split('\n');
+      let sawName = false;
+      const updatedLines = lines.map((line) => {
+        if (/^name:\s*/.test(line)) {
+          sawName = true;
+          return `name: ${prefixedName}`;
+        }
+        return line;
+      });
+      if (!sawName) {
+        updatedLines.push(`name: ${prefixedName}`);
+      }
+      return `---\n${updatedLines.join('\n')}\n---\n`;
+    });
+  }
+
+  next = next.replace(/^#\s+.+$/m, `# ${prefixedName}`);
+  return next.replace(/\n{3,}/g, '\n\n').trimEnd() + '\n';
+}
+
 function ensureMarketplaceEntry(marketplacePath, pluginSourcePath) {
   const marketplace = fs.existsSync(marketplacePath)
     ? readJson(marketplacePath)
@@ -369,6 +458,167 @@ function installCopilotSurface(packageRoot, copilotHome) {
   installManagedHooks(packageRoot, copilotHome);
 }
 
+function renderCloudAgentAgentsBlock() {
+  return [
+    '## Babysitter Cloud Agent',
+    '',
+    'This repository is configured to let GitHub Copilot cloud agent use Babysitter orchestration assets.',
+    '',
+    '- For complex multi-step work, use the Babysitter skills installed under `.github/skills/` when relevant.',
+    '- The cloud-agent setup workflow installs the Babysitter SDK before work begins.',
+    '- If you need the full orchestration instructions, run `babysitter instructions:babysit-skill --harness github-copilot --json`.',
+    '- Execute requested shell and Node tasks directly and report the results instead of describing what should be done.',
+    '- Do not revert unrelated user changes.',
+  ].join('\n');
+}
+
+function renderCloudAgentCopilotInstructionsBlock() {
+  return [
+    '# Babysitter Copilot Cloud Agent Support',
+    '',
+    'This repository includes Babysitter support for GitHub Copilot cloud agent.',
+    '',
+    '- Read the nearest `AGENTS.md` instructions before making changes.',
+    '- Consider the Babysitter skills under `.github/skills/` when the task is a multi-step workflow, orchestration run, diagnosis, planning, or retrospective.',
+    '- The `copilot-setup-steps` workflow installs the Babysitter SDK and initializes the active process library before the agent starts working.',
+    '- Add repository-specific build, test, and validation commands below this managed section if they are not already documented elsewhere in the repo.',
+  ].join('\n');
+}
+
+function renderCloudAgentSetupWorkflow(packageRoot) {
+  const sdkVersion = readSdkVersion(packageRoot);
+  return [
+    'name: "Copilot Setup Steps"',
+    '',
+    'on:',
+    '  workflow_dispatch:',
+    '  push:',
+    '    paths:',
+    '      - .github/workflows/copilot-setup-steps.yml',
+    '      - .github/copilot-instructions.md',
+    '      - .github/skills/**',
+    '      - AGENTS.md',
+    '  pull_request:',
+    '    paths:',
+    '      - .github/workflows/copilot-setup-steps.yml',
+    '      - .github/copilot-instructions.md',
+    '      - .github/skills/**',
+    '      - AGENTS.md',
+    '',
+    'jobs:',
+    '  copilot-setup-steps:',
+    '    runs-on: ubuntu-latest',
+    '    permissions:',
+    '      contents: read',
+    '    steps:',
+    '      - name: Check out repository',
+    '        uses: actions/checkout@v4',
+    '',
+    '      - name: Set up Node.js',
+    '        uses: actions/setup-node@v4',
+    '        with:',
+    '          node-version: 22',
+    '          cache: npm',
+    '',
+    '      - name: Install Babysitter SDK',
+    `        run: npm install -g @a5c-ai/babysitter-sdk@${sdkVersion}`,
+    '',
+    '      - name: Initialize active process library',
+    '        run: babysitter process-library:active --json',
+  ].join('\n') + '\n';
+}
+
+function installCloudAgentBundle(packageRoot, workspaceRoot) {
+  const bundleRoot = path.join(workspaceRoot, '.github', 'babysitter', 'github-plugin');
+  fs.rmSync(bundleRoot, { recursive: true, force: true });
+  fs.mkdirSync(bundleRoot, { recursive: true });
+  for (const entry of CLOUD_AGENT_BUNDLE_ENTRIES) {
+    const sourcePath = path.join(packageRoot, entry);
+    if (!fs.existsSync(sourcePath)) {
+      continue;
+    }
+    copyRecursive(sourcePath, path.join(bundleRoot, entry));
+  }
+  return bundleRoot;
+}
+
+function installCloudAgentSkills(packageRoot, workspaceRoot) {
+  const sourceRoot = path.join(packageRoot, 'skills');
+  if (!fs.existsSync(sourceRoot)) return [];
+
+  const targetRoot = path.join(workspaceRoot, '.github', 'skills');
+  fs.mkdirSync(targetRoot, { recursive: true });
+  const installed = [];
+
+  for (const entry of fs.readdirSync(sourceRoot, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const sourceDir = path.join(sourceRoot, entry.name);
+    const skillId = toLowerHyphenName(entry.name);
+    const targetDir = path.join(targetRoot, `babysitter-${skillId}`);
+    fs.rmSync(targetDir, { recursive: true, force: true });
+    copyRecursive(sourceDir, targetDir);
+    const skillPath = path.join(targetDir, 'SKILL.md');
+    if (fs.existsSync(skillPath)) {
+      const rewritten = rewriteCloudSkill(skillId, fs.readFileSync(skillPath, 'utf8'));
+      fs.writeFileSync(skillPath, rewritten, 'utf8');
+    }
+    installed.push(targetDir);
+  }
+
+  return installed;
+}
+
+function installCloudAgentInstructions(packageRoot, workspaceRoot) {
+  const agentsPath = path.join(workspaceRoot, 'AGENTS.md');
+  const copilotInstructionsPath = path.join(workspaceRoot, '.github', 'copilot-instructions.md');
+
+  writeManagedMarkdown(agentsPath, renderCloudAgentAgentsBlock(packageRoot));
+  writeManagedMarkdown(copilotInstructionsPath, renderCloudAgentCopilotInstructionsBlock(packageRoot));
+
+  return {
+    agentsPath,
+    copilotInstructionsPath,
+  };
+}
+
+function installCloudAgentSetupSteps(packageRoot, workspaceRoot) {
+  const workflowsDir = path.join(workspaceRoot, '.github', 'workflows');
+  const workflowPath = path.join(workflowsDir, 'copilot-setup-steps.yml');
+  const examplePath = path.join(workflowsDir, 'copilot-setup-steps.babysitter.generated.yml');
+  const contents = renderCloudAgentSetupWorkflow(packageRoot);
+
+  fs.mkdirSync(workflowsDir, { recursive: true });
+
+  if (!fs.existsSync(workflowPath)) {
+    writeFileIfChanged(workflowPath, contents);
+    fs.rmSync(examplePath, { force: true });
+    return { workflowPath, examplePath: null, managed: true, needsManualMerge: false };
+  }
+
+  const existing = fs.readFileSync(workflowPath, 'utf8');
+  if (existing.includes('copilot-setup-steps') && existing.includes('@a5c-ai/babysitter-sdk')) {
+    writeFileIfChanged(workflowPath, contents);
+    fs.rmSync(examplePath, { force: true });
+    return { workflowPath, examplePath: null, managed: true, needsManualMerge: false };
+  }
+
+  writeFileIfChanged(examplePath, contents);
+  return { workflowPath, examplePath, managed: false, needsManualMerge: true };
+}
+
+function installCloudAgentSurface(packageRoot, workspaceRoot) {
+  const bundleRoot = installCloudAgentBundle(packageRoot, workspaceRoot);
+  const skillDirs = installCloudAgentSkills(packageRoot, workspaceRoot);
+  const instructions = installCloudAgentInstructions(packageRoot, workspaceRoot);
+  const setupWorkflow = installCloudAgentSetupSteps(packageRoot, workspaceRoot);
+  return {
+    bundleRoot,
+    skillDirs,
+    ...instructions,
+    setupWorkflow,
+  };
+}
+
 function resolveBabysitterCommand(packageRoot) {
   if (process.env.BABYSITTER_SDK_CLI) {
     return {
@@ -442,6 +692,7 @@ module.exports = {
   getHomeMarketplacePath,
   getHomePluginRoot,
   installCopilotSurface,
+  installCloudAgentSurface,
   registerCopilotPlugin,
   removeLegacyHooks,
   removeMarketplaceEntry,

package/bin/install.js

@@ -10,12 +10,39 @@ const {
   getCopilotHome,
   getHomeMarketplacePath,
   getHomePluginRoot,
+  installCloudAgentSurface,
   installCopilotSurface,
   warnWindowsHooks,
 } = require('./install-shared');
 
 const PACKAGE_ROOT = path.resolve(__dirname, '..');
 
+function parseArgs(argv) {
+  const args = {
+    cloudAgent: false,
+    workspace: process.cwd(),
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--cloud-agent') {
+      args.cloudAgent = true;
+      continue;
+    }
+    if (arg === '--workspace') {
+      const next = argv[i + 1];
+      if (next && !next.startsWith('-')) {
+        args.workspace = path.resolve(next);
+        i += 1;
+      } else {
+        args.workspace = process.cwd();
+      }
+    }
+  }
+
+  return args;
+}
+
 /**
  * Attempt to register the plugin via `copilot plugin install ./path`.
  * Falls back to manual config.json registration if the CLI is not available.
@@ -43,10 +70,31 @@ function registerViaCopilotCli(pluginRoot) {
 }
 
 function main() {
+  const args = parseArgs(process.argv.slice(2));
   const copilotHome = getCopilotHome();
   const pluginRoot = getHomePluginRoot();
   const marketplacePath = getHomeMarketplacePath();
 
+  if (args.cloudAgent) {
+    const active = ensureGlobalProcessLibrary(PACKAGE_ROOT);
+    const installed = installCloudAgentSurface(PACKAGE_ROOT, args.workspace);
+    console.log(`[babysitter] Installed Copilot cloud-agent support into ${args.workspace}`);
+    console.log(`[babysitter]   plugin bundle: ${installed.bundleRoot}`);
+    console.log(`[babysitter]   skills: ${path.join(args.workspace, '.github', 'skills')}`);
+    console.log(`[babysitter]   instructions: ${installed.copilotInstructionsPath}`);
+    console.log(`[babysitter]   agents: ${installed.agentsPath}`);
+    if (installed.setupWorkflow.needsManualMerge) {
+      console.warn(`[babysitter] Existing copilot-setup-steps workflow preserved: ${installed.setupWorkflow.workflowPath}`);
+      console.warn(`[babysitter] Merge Babysitter setup steps from: ${installed.setupWorkflow.examplePath}`);
+    } else {
+      console.log(`[babysitter]   setup workflow: ${installed.setupWorkflow.workflowPath}`);
+    }
+    console.log(`[babysitter]   process library: ${active.binding?.dir}`);
+    console.log(`[babysitter]   process library state: ${active.stateFile}`);
+    console.log('[babysitter] Cloud-agent installation complete!');
+    return;
+  }
+
   console.log(`[babysitter] Installing plugin to ${pluginRoot}`);
 
   try {

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@a5c-ai/babysitter-github",
-  "version": "0.1.1-staging.0825aadb",
+  "version": "0.1.1-staging.11cb9e78",
   "description": "Babysitter orchestration plugin for GitHub Copilot CLI with lifecycle hooks and SDK-managed process-library bootstrapping",
   "scripts": {
-    "test": "node scripts/sync-command-surfaces.js --check",
+    "test": "node scripts/sync-command-surfaces.js --check && node test/cloud-agent-install.test.js",
     "sync:commands": "node scripts/sync-command-surfaces.js",
     "postinstall": "node bin/install.js",
     "preuninstall": "node bin/uninstall.js",
@@ -45,6 +45,6 @@
   },
   "homepage": "https://github.com/a5c-ai/babysitter/tree/main/plugins/babysitter-github#readme",
   "dependencies": {
-    "@a5c-ai/babysitter-sdk": "0.0.184-staging.0825aadb"
+    "@a5c-ai/babysitter-sdk": "0.0.184-staging.11cb9e78"
   }
 }

package/scripts/team-install.js

@@ -16,11 +16,14 @@ const {
 function parseArgs(argv) {
   const args = {
     workspace: process.cwd(),
+    cloudAgent: false,
     dryRun: false,
   };
   for (let i = 2; i < argv.length; i += 1) {
     if (argv[i] === '--workspace' && argv[i + 1]) {
       args.workspace = path.resolve(argv[++i]);
+    } else if (argv[i] === '--cloud-agent') {
+      args.cloudAgent = true;
     } else if (argv[i] === '--dry-run') {
       args.dryRun = true;
     }
@@ -58,6 +61,10 @@ function main() {
   ensureMarketplaceEntry(workspaceMarketplacePath, workspacePluginRoot);
   registerCopilotPlugin(workspacePluginRoot);
   installCopilotSurface(packageRoot, workspaceCopilotDir);
+  if (args.cloudAgent) {
+    const { installCloudAgentSurface } = require('../bin/install-shared');
+    installInfo.cloudAgent = installCloudAgentSurface(packageRoot, workspaceRoot);
+  }
 
   const active = ensureGlobalProcessLibrary(packageRoot);
   installInfo.processLibraryStateFile = active.stateFile;

package/versions.json

@@ -1,3 +1,3 @@
 {
-  "sdkVersion": "0.0.184-staging.0825aadb"
+  "sdkVersion": "0.0.184-staging.11cb9e78"
 }