From c11753d0b94d3a8cc379564609a740c5e68599e3 Mon Sep 17 00:00:00 2001 From: haelyra <49814733+haelyra@users.noreply.github.com> Date: Mon, 7 Sep 2026 16:36:10 -0400 Subject: [PATCH] fix(skills): replace invented autonomous harness setup instructions Resolve #2957 using the verified MCP reference memory package, native session scheduling, supported CLI invocation and documented computer-use integration. Incorporates the corrective direction from #2977 and #2958, including package-version pinning and regression checks for executable examples. Co-authored-by: ilkmajans-cpu Co-authored-by: kavish-19 <63698788+kavish-19@users.noreply.github.com> --- skills/autonomous-agent-harness/SKILL.md | 75 ++++++++++----------- tests/docs/autonomous-harness-setup.test.js | 46 +++++++++++++ 2 files changed, 82 insertions(+), 39 deletions(-) create mode 100644 tests/docs/autonomous-harness-setup.test.js diff --git a/skills/autonomous-agent-harness/SKILL.md b/skills/autonomous-agent-harness/SKILL.md index f2e3929ab..2f92a5a17 100644 --- a/skills/autonomous-agent-harness/SKILL.md +++ b/skills/autonomous-agent-harness/SKILL.md @@ -7,7 +7,7 @@ metadata: # Autonomous Agent Harness -Turn Claude Code into a persistent, self-directing agent system using only native features and MCP servers. +Combine Claude Code's session tools with separately configured scheduling, memory, and computer-use integrations. This is a setup pattern, not a bundled always-on runtime. ## Consent and Safety Boundaries @@ -85,23 +85,23 @@ Use mcp__memory__add_observations for new facts about known entities ### 2. Scheduled Operations (Crons) -Use Claude Code's scheduled tasks to create recurring agent operations. +Use Claude Code's native [scheduled tasks](https://code.claude.com/docs/en/scheduled-tasks) for recurring prompts within an interactive session. These tasks are session-scoped; an external scheduler is required for work that must run independently of an open session. No scheduling MCP server is required for `/loop`. **Setting up a cron:** ``` -# Via MCP tool -mcp__scheduled-tasks__create_scheduled_task({ - name: "daily-pr-review", - schedule: "0 9 * * 1-5", # 9 AM weekdays - prompt: "Review all open PRs in affaan-m/everything-claude-code. For each: check CI status, review changes, flag issues. Post summary to memory.", - project_dir: "/path/to/repo" -}) - -# Via claude -p (programmatic mode) -echo "Review open PRs and summarize" | claude -p --project /path/to/repo +# In an interactive Claude Code session +/loop 30m Review open PRs in this repository and summarize CI failures. ``` +For a one-shot run from a shell, set the working directory before invoking the CLI: + +```bash +cd "/path/to/repo" && claude -p "Review open PRs and summarize" +``` + +Use an OS scheduler or CI schedule to invoke that command repeatedly when no interactive session is running. Configure the runner's authentication and tool permissions separately. + **Useful cron patterns:** | Pattern | Schedule | Use Case | @@ -114,18 +114,16 @@ echo "Review open PRs and summarize" | claude -p --project /path/to/repo ### 3. Dispatch / Remote Agents -Trigger Claude Code agents remotely for event-driven workflows. +Have an authenticated CI job or webhook receiver invoke Claude Code in a workspace it owns. The supported entrypoint is [programmatic CLI mode](https://code.claude.com/docs/en/headless), not a public Anthropic dispatch endpoint. **Dispatch patterns:** ```bash -# Trigger from CI/CD -curl -X POST "https://api.anthropic.com/dispatch" \ - -H "Authorization: Bearer $ANTHROPIC_API_KEY" \ - -d '{"prompt": "Build failed on main. Diagnose and fix.", "project": "/repo"}' +# Run inside the CI workspace +cd "/path/to/repo" && claude -p "Build failed on main. Diagnose the failure." # Trigger from webhook -# GitHub webhook → dispatch → Claude agent → fix → PR +# GitHub webhook -> authenticated CI runner -> claude -p -> reviewable result # Trigger from another agent claude -p "Analyze the output of the security scan and create issues for findings" @@ -133,7 +131,7 @@ claude -p "Analyze the output of the security scan and create issues for finding ### 4. Computer Use -Leverage Claude's computer-use MCP for physical world interaction. +Computer control needs a separately configured integration. Anthropic's [computer-use tool and reference environment](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool) require an application to execute tool calls in an isolated desktop environment. Adding an MCP package name does not supply that environment. **Capabilities:** - Browser automation (navigate, click, fill forms, screenshot) @@ -176,11 +174,11 @@ description: Persistent task queue for autonomous operation | Hermes Component | ECC Equivalent | How | |------------------|---------------|-----| -| Gateway/Router | Claude Code dispatch + crons | Scheduled tasks trigger agent sessions | +| Gateway/Router | CLI + external scheduler | An authenticated runner starts agent sessions | | Memory System | Claude memory + MCP memory server | Built-in persistence + knowledge graph | | Tool Registry | MCP servers | Dynamically loaded tool providers | | Orchestration | ECC skills + agents | Skill definitions direct agent behavior | -| Computer Use | computer-use MCP | Native browser and desktop control | +| Computer Use | Separately configured integration | Browser or desktop control in an isolated environment | | Context Manager | Session management + memory | ECC 2.0 session lifecycle | | Task Queue | Memory-persisted task list | TodoWrite + memory files | @@ -188,37 +186,36 @@ description: Persistent task queue for autonomous operation ### Step 1: Configure MCP Servers -Ensure these are in `~/.claude.json`: +Memory MCP is optional. The [MCP reference memory server](https://github.com/modelcontextprotocol/servers/tree/main/src/memory) is published as `@modelcontextprotocol/server-memory`; version `2026.8.31` was verified on the public npm registry on 2026-09-07. It is a reference implementation, not an ECC-bundled service. + +After reviewing that package and approving its use, merge this entry into the user-scoped MCP configuration in `~/.claude.json`, preserving existing settings. Replace `MEMORY_FILE_PATH` with an absolute path in a private directory you own. See [Claude Code MCP configuration](https://code.claude.com/docs/en/mcp) for CLI registration and Windows `cmd /c npx` configuration. ```json { "mcpServers": { "memory": { "command": "npx", - "args": ["-y", "@anthropic/memory-mcp-server"] - }, - "scheduled-tasks": { - "command": "npx", - "args": ["-y", "@anthropic/scheduled-tasks-mcp-server"] - }, - "computer-use": { - "command": "npx", - "args": ["-y", "@anthropic/computer-use-mcp-server"] + "args": ["-y", "@modelcontextprotocol/server-memory@2026.8.31"], + "env": { + "MEMORY_FILE_PATH": "/absolute/path/to/private/memory.jsonl" + } } } } ``` +Do not register guessed or unpublished npm packages: `npx -y` would execute whatever is later published under that name. Verify the exact package, publisher, and version before adding another server. Scheduling and computer use do not require the three unpublished package names previously listed here. + ### Step 2: Create Base Crons -```bash -# Daily morning briefing -claude -p "Create a scheduled task: every weekday at 9am, review my GitHub notifications, open PRs, and calendar. Write a morning briefing to memory." +For polling during an interactive session, enter: -# Continuous learning -claude -p "Create a scheduled task: every Sunday at 8pm, extract patterns from this week's sessions and update the learned skills." +```text +/loop 30m Review open PRs in this repository and summarize CI failures. ``` +For daily or weekly work that must survive a closed session, configure an external scheduler, such as an OS cron job or GitHub Actions, to run the one-shot command from Step 2 of Core Components. Calling `claude -p` to request a schedule does not provision an always-on scheduler. Choose the schedule, workspace, and allowed actions explicitly before enabling it. + ### Step 3: Initialize Memory Graph ```bash @@ -228,7 +225,7 @@ claude -p "Create memory entities for: me (user profile), my projects, my key co ### Step 4: Enable Computer Use (Optional) -Grant computer-use MCP the necessary permissions for browser and desktop control. +Follow the computer-use reference environment linked above, or the documentation for a specific browser integration you have reviewed. Grant only the required permissions and verify a harmless action in the isolated environment before adding it to scheduled workflows. ## Example Workflows @@ -267,8 +264,8 @@ Trigger: 30 min before each calendar event ## Constraints -- Cron tasks run in isolated sessions — they don't share context with interactive sessions unless through memory. +- Native scheduled prompts share their interactive session. External scheduler invocations start separate sessions unless explicitly resumed. - Computer use requires explicit permission grants. Don't assume access. -- Remote dispatch may have rate limits. Design crons with appropriate intervals. +- CLI automation still consumes model usage and is subject to the configured provider's limits. Choose appropriate scheduler intervals. - Memory files should be kept concise. Archive old data rather than letting files grow unbounded. - Always verify that scheduled tasks completed successfully. Add error handling to cron prompts. diff --git a/tests/docs/autonomous-harness-setup.test.js b/tests/docs/autonomous-harness-setup.test.js new file mode 100644 index 000000000..75e8fe855 --- /dev/null +++ b/tests/docs/autonomous-harness-setup.test.js @@ -0,0 +1,46 @@ +#!/usr/bin/env node +'use strict'; + +const assert = require('assert'); +const fs = require('fs'); +const path = require('path'); + +const source = fs.readFileSync(path.resolve(__dirname, '../../skills/autonomous-agent-harness/SKILL.md'), 'utf8'); +const blocks = [...source.matchAll(/```[^\n]*\n([\s\S]*?)```/g)].map(match => match[1]).join('\n'); +const checks = [ + ['executable examples omit unpublished packages and the invented dispatch endpoint', () => { + assert.doesNotMatch(blocks, /@anthropic\/(?:memory|scheduled-tasks|computer-use)-mcp-server/); + assert.doesNotMatch(blocks, /api\.anthropic\.com\/dispatch/); + }], + ['CLI examples use the working directory and native session scheduling', () => { + assert.doesNotMatch(blocks, /--project\b|mcp__scheduled-tasks__/); + assert.match(blocks, /cd "\/path\/to\/repo" && claude -p/); + assert.match(blocks, /\/loop 30m/); + assert.match(source, /session-scoped/); + assert.match(source, /external scheduler/); + }], + ['optional memory configuration uses a pinned reference package and explicit data location', () => { + const jsonBlock = source.match(/```json\n([\s\S]*?)```/); + assert.ok(jsonBlock); + const memory = JSON.parse(jsonBlock[1]).mcpServers.memory; + assert.strictEqual(memory.command, 'npx'); + assert.match(memory.args[1], /^@modelcontextprotocol\/server-memory@\d{4}\.\d+\.\d+$/); + assert.ok(path.posix.isAbsolute(memory.env.MEMORY_FILE_PATH)); + }], + ['setup links to upstream memory, scheduling, CLI, and computer-use documentation', () => { + for (const link of [ + 'https://github.com/modelcontextprotocol/servers/tree/main/src/memory', + 'https://code.claude.com/docs/en/scheduled-tasks', + 'https://code.claude.com/docs/en/headless', + 'https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool' + ]) assert.ok(source.includes(link), `missing primary source ${link}`); + }] +]; + +let failed = 0; +for (const [name, check] of checks) { + try { check(); console.log(` PASS ${name}`); } + catch (error) { failed++; console.error(` FAIL ${name}: ${error.message}`); } +} +console.log(`Passed: ${checks.length - failed}\nFailed: ${failed}`); +process.exitCode = failed ? 1 : 0;