v2.6.0 — Orchestrator V2 & CI Stability

Highlights

• Added Orchestrator V2 with retry policies, conditional execution rules, output projection, progress tracking, and improved result aggregation.
• Expanded orchestrator test coverage with unit + integration suites and validated real skill invocation paths.
• Improved OpenCode bridge integration for orchestrated workflows, including progress metadata in responses.
• Fixed CI reliability by versioning missing template skills required in clean environments: test-generator, doc-generator, and code-formatter.
• Updated template manifest and setup flow so generated .agents directories are complete and consistent in local/CI installs.

Quality

• CI matrix and smoke workflow are green on this release line.
• Full test suite passes locally (47 suites passed, 658 tests passed, 21 skipped).

Notes

• No breaking API changes are introduced in this release.

v2.5.0 — Autonomous Skill Discovery System

What's New in v2.5.0

🎯 Autonomous Skill Discovery System

Automatic skill detection from filesystem with zero-configuration setup. Create a skill in .agents/my-skill/SKILL.md, run npm run setup, and it's automatically discovered and registered!

Key Features:

• Scans .agents/ for SKILL.md files
• Interactive skill selection during setup (all pre-selected by default)
• Runtime validation of registered skills at engine startup
• Helpful hints when skills are unregistered or orphaned

For Users:

npm run setup
# Skills automatically discovered → manifest.json auto-generated

For Developers:
See .agents/SKILL_DISCOVERY.md for complete API reference, troubleshooting, and best practices.

📊 Release Stats

• 1,390 lines of production code added
• 10 new unit tests (all passing, 293 total tests)
• 100% backward compatible — All existing projects work unchanged
• Zero breaking changes — Safe to upgrade
• Production ready — Fully tested and documented

📦 Installation

npm install agents-runtime@2.5.0

🔗 Documentation

• SKILL_DISCOVERY.md — Complete developer guide
• README.md — Getting started
• CHANGELOG.md — Full release history

🙏 Credits

This release includes the complete Autonomous Skill Discovery System with comprehensive testing and documentation. All 293 tests passing on first release.

v2.3.0 - Default Skills Library

Release v2.3.0 - Default Skills Library with Security Framework

Overview

agents-runtime v2.3.0 introduces a comprehensive default skills library with 5 professional-grade utility skills, complete security framework, and production-ready documentation.

All skills are designed for safety first, with built-in protection against:

• Unauthorized access (authorization level enforcement)
• Resource exhaustion (size limits on all operations)
• Code injection (safe parameter passing, no shell interpolation)
• Sensitive data exposure (automatic masking in logs)
• Timeout hangs (timeout protection on all I/O)

---

🎯 New Skills (5)

1. http-request (Level 0 - Public)

Make secure HTTP/HTTPS API calls with professional features.

Features:

• Automatic retries with exponential backoff
• Timeout protection (default 30s, configurable 100ms-5min)
• SSL/TLS verification always enabled
• Credential masking (no auth headers in logs)
• Response streaming with size limits (50MB max)
• 3xx redirect handling (max 5 redirects)
• Comprehensive error codes (TIMEOUT, SSL_ERROR, HTTP_ERROR, etc.)

Example:

const result = await execute({
  method: 'POST',
  url: 'https://api.example.com/data',
  headers: { 'Authorization': 'Bearer token' },
  body: { message: 'hello' },
  retry: { maxAttempts: 3 }
});

---

2. file-operations (Level 1 - Internal)

Read, write, append, delete files with sandbox protection.

Features:

• Sandbox mode: confined to /.agents/workspace/ directory
• Path traversal prevention (../ blocked)
• Blocked file list (.env, .git, .key, etc.)
• Size limit: 10MB per file
• Safe UTF-8 encoding
• File metadata capture (size, created, modified dates)

Operations:

• read: Get file contents
• write: Create/overwrite file
• append: Add content to file
• delete: Remove file
• exists: Check existence
• list: Directory contents

Example:

const result = await execute({
  operation: 'read',
  path: 'config.json'
});

---

3. system-command (Level 2 - Admin Only)

Execute shell commands safely with whitelist protection.

Features:

• Whitelist pattern: only pre-approved commands (node, npm, git, curl, jq, etc.)
• NO shell interpolation: arguments passed as array
• Timeout protection (default 60s)
• Stderr captured separately
• Output size limit (2MB per stream)
• Process exit code capture

Safe Command Execution:

const result = await execute({
  command: 'npm',
  args: ['install', '--save', 'express'],
  timeout: 60000
});

Blocked Patterns:

• No sudo, su, chmod, rm -rf, mkfs, etc.
• No string concatenation: git clone ${userUrl} → ERROR
• Arguments only as array: prevents all injection attacks

---

4. data-transform (Level 0 - Public)

Safe JSON parsing, transformation, filtering, validation.

Features:

• Safe JSON parsing (no eval(), no Function constructor)
• Circular reference detection ([Circular] marker)
• Size limit: 50MB JSON
• Deep object merging
• Array filtering with safe predicates
• JSON Schema validation (draft 2020-12)
• Data extraction by path

Operations:

• parse: JSON string → object
• stringify: Object → JSON string
• transform: Rename/filter/extract keys
• filter: Filter array by predicate
• merge: Deep merge objects
• validate: JSON Schema validation
• extract: Get nested value by path

Example:

const result = await execute({
  operation: 'filter',
  data: [1, 2, 3, 4, 5],
  rules: { predicate: 'x > 2' }
});
// Result: [3, 4, 5]

---

5. logging (Level 0 - Public)

Structured logging with automatic sensitive data masking.

Features:

• Automatic masking: passwords, tokens, API keys, secrets
• Audit trail: who logged what, when
• Log levels: DEBUG, INFO, WARN, ERROR
• Log rotation: 100MB max per file (10 files retained)
• Tail logs: get last N lines
• Search logs: regex pattern search
• Clear logs: permanent deletion

Masked Patterns:

• password / passwd
• token / auth
• api_key / apiKey
• secret
• authorization

Example:

const result = await execute({
  operation: 'log',
  level: 'WARN',
  message: 'Failed login',
  data: { password: 'secret123' }
});
// password automatically masked: '***MASKED***'

---

🔒 Security Framework

Authorization Levels

Level	Skills	Use Case
0	http-request, data-transform, logging	Public, read-only
1	file-operations, code-analysis	Internal operations
2	system-command, refactor	Admin/system operations

Input Validation

All skills validate input against JSON Schema manifest:

• Type checking
• Size limit enforcement
• Format validation
• Required field verification

Consistent Error Handling

All skills return:

{
  success: boolean,
  data: any,
  error: { code: string, message: string, details?: any } | null,
  metadata: { executionTime: number, timestamp: string }
}

Sensitive Data Protection

• Automatic masking in logs
• No credentials in error messages
• No debug info leakage
• Audit trail without secrets

Resource Limits

Operation	Limit	Purpose
http-request body	5MB	Prevent server overload
http-request response	50MB	Prevent memory exhaustion
file-operations	10MB	Memory/disk protection
system-command output	2MB each	Output size control
data-transform JSON	50MB	Memory protection
logging message	4096 chars	Log file efficiency

Timeout Protection

• http-request: default 30s (100ms - 5min)
• system-command: default 60s (100ms - 10min)
• All I/O operations protected from hangs

---

📚 Documentation

Each skill includes:

1. manifest.json — Input/output schema, examples, security notes
2. SKILL.md — User guide with examples, parameters, error codes, best practices
3. handler.js — Implementation with security built-in
4. handler.test.js — Unit tests covering security scenarios

Overall Documentation:

• .agents/skills/README.md — Skills library overview
• .agents/skills/SECURITY.md — Security best practices for developers

---

📊 Skill Statistics

Skill	Lines	File Ops	Security Checks	Tests
http-request	330	✅ Retry logic	SSL, timeout, creds masking	5
file-operations	280	✅ Sandbox	Path traversal, blocked files	6
system-command	250	✅ Whitelist	No injection, timeout	7
data-transform	270	✅ Safe parse	Circular refs, safe eval	7
logging	240	✅ Masking	7 patterns, audit trail	6
Total	1,370	✅ All	30+ checks	31 tests

---

🔄 Distribution

All 5 new skills automatically included in:

• template/.agents/ — Used by setup.sh for new projects
• examples/simple-js-app — Available for testing

Existing projects: Copy skills from template or update from this release.

---

📈 Performance Baseline

Skill	Typical Time	Notes
http-request (GET)	200-500ms	Network dependent
file-operations (read)	5-50ms	File size dependent
system-command	50-500ms	Command dependent
data-transform	1-100ms	Data size dependent
logging (write)	2-10ms	Async, non-blocking

---

✅ Backward Compatibility

• ✅ No breaking changes to existing skills (code-analysis, security-audit, refactor)
• ✅ manifest.json extended (not modified)
• ✅ settings.json compatible
• ✅ Existing projects continue to work unchanged

---

🚀 Getting Started

Using in New Project

./setup.sh  # Skills included automatically

Using in Existing Project

All 8 skills available (5 new + 3 existing). Copy or reference from template:

cp -r template/.agents/skills/* .agents/skills/

Calling Skills

const { execute } = require('./.agents/skills/http-request/handler');
const result = await execute({ method: 'GET', url: '...' });

---

📋 Checklist for v2.3.0

• ✅ 5 professional-grade utility skills
• ✅ Comprehensive security framework (30+ patterns)
• ✅ Complete documentation with examples
• ✅ Unit tests covering security scenarios
• ✅ Skills synced to template for distribution
• ✅ manifest.json updated with all skills
• ✅ CHANGELOG.md documented
• ✅ No breaking changes
• ✅ Backward compatible

---

📢 What's Next?

Future releases may include:

• Additional skills (database, cache, message queue)
• Skills marketplace/registry
• Skill composition/workflow engine
• Performance optimization
• Extended monitoring/observability

---

🐛 Known Limitations

1. file-operations: Sandbox restricted to /.agents/workspace/
2. system-command: Only whitelisted commands
3. http-request: HTTPS recommended (HTTP supported)
4. data-transform: No arbitrary code execution (safe by design)
5. logging: Pattern-based masking (unusual var names may not match)

---

📞 Support

See documentation in:

• .agents/skills/README.md — Overview
• .agents/skills/SECURITY.md — Security details
• skill-name/SKILL.md — Detailed user guides
• CHANGELOG.md — Version history

---

Release Date: April 7, 2026
Version: 2.3.0
Status: Stable ✅

v2.2.0 — AI Agent Startup Protocol & Initialization Framework

v2.2.0 — AI Agent Startup Protocol & Initialization Framework

This release introduces a mandatory startup protocol for AI agents (Claude, GPT, Gemini, etc.), ensuring secure initialization and proper authorization verification before user interaction.

🤖 Major Features

AI Agent Startup Protocol

A five-step mandatory initialization sequence for AI-based agents:

1. Locate Configuration — Find agent.yaml via configurable search paths
2. Run Compliance Check — Validate agent identity, authorization level, and skills
3. Load Settings — Initialize memory backend and security rules
4. Emit Event — Log AGENT_INITIALIZED event for audit trail
5. Announce Capabilities — Tell user what the agent can do

Key Benefits:

• ✅ Hard-fail on errors (agent stops if initialization fails)
• ✅ No silent failures — errors are explicit and debuggable
• ✅ Framework-level enforcement (pre-interaction hook blocks user interaction until startup completes)
• ✅ Comprehensive documentation (agent-startup.md, AI_AGENT_GUIDE.md)

🔒 Security Enhancements

• Pre-interaction Hook (pre-interaction.hook.js) — Verifies agent initialization before responding to users
• Compliance Check JSON Output — Structured verification for AI agents (status, timestamp, checks_passed/failed)
• Configuration Discovery — Automatic search for agent.yaml with clear error messages
• Updated Contract — AGENT_CONTRACT.md Section 9 defines AI agent requirements

📋 Documentation

• .agents/agent-startup.md (8.6 KB) — Complete 5-step initialization guide
• .agents/AI_AGENT_GUIDE.md (16 KB) — Best practices, authorization reference, troubleshooting
• Updated AGENT_CONTRACT.md — Section 9: AI Agent Initialization Protocol

🔧 Technical Changes

New Files

• pre-interaction.hook.js — Startup verification hook (4.5 KB)
• agent-startup.md — Mandatory initialization guide (8.6 KB)
• AI_AGENT_GUIDE.md — Best practices and troubleshooting (16 KB)

Updated Files

• manifest.json — Added startup_sequence schema and pre-interaction hook definition
• settings.json — Added ai_agent_discovery configuration with search paths
• AGENT_CONTRACT.md — Section 9: AI Agent Initialization Protocol
• compliance-check.js — Added --json flag for structured output
• skill-lifecycle.hook.js — Added AI agent startup verification
• README.md — New "For AI Agents" section with authorization reference

✅ Testing

All scenarios tested in real project setup (examples/simple-js-app):

Test	Result	Details
Setup Installation	✅ PASS	All files copied correctly
Compliance Check	✅ PASS	Exit code 0, 7/7 checks passed
JSON Output	✅ PASS	Structured format with agent metadata
Startup Simulation	✅ PASS	5-step protocol fully functional
Manifest Schema	✅ PASS	startup_sequence and hook definitions valid
Settings Schema	✅ PASS	ai_agent_discovery configuration valid

📦 Installation

# Update to latest
npm install agents-runtime@latest

# Or run setup in any project
bash setup-agents.sh /path/to/project --agent observer

🔄 Migration Guide

No action required — All changes are backward compatible.

Existing agent.yaml files work without modification. To get new files in existing projects:

# Re-run setup with --force to overwrite
bash setup-agents.sh /path/to/project --agent observer --force

🐛 Breaking Changes

None. This is a minor version bump (2.1.0 → 2.2.0) with full backward compatibility.

📚 Resources

• CHANGELOG.md — Full changelog
• .agents/agent-startup.md — Mandatory startup guide
• .agents/AI_AGENT_GUIDE.md — Best practices
• .agents/AGENT_CONTRACT.md — Full contract (Section 9)
• README.md — "For AI Agents" section

✨ What's Next

• Upcoming: Enhanced authorization enforcement at skill execution level
• Roadmap: Distributed agent coordination framework
• Planning: Advanced memory persistence backends

---

Made with ❤️ by the agents-runtime team

v2.1.0: Enterprise-Grade Security Audit Handler

🎉 Release v2.1.0 - Enterprise-Grade Security Audit Handler

✨ What's New

Security Audit Handler v2.0.0 - Complete Refactor

• Professional 5-Layer Architecture
  • lib/rules.js - Structured OWASP rule database
  • lib/analyzer.js - Context-aware pattern detection
  • lib/suppression.js - Professional suppression management
  • lib/report.js - Comprehensive reporting engine

🐛 Bug Fixes

• ✅ Eliminated SQLite .exec() false positives
• ✅ Fixed rate limiting suppression comments (now OWASP-based: A04:2021)
• ✅ Corrected health endpoint authentication checks
• ✅ Improved command injection detection accuracy

📊 Improvements

• False Positive Rate: 13% → 0% (100% accuracy)
• Test Coverage: 47 → 212 tests (+350%)
• Performance: 12% faster, 16% less memory
• Code Quality: Cyclomatic complexity reduced 50%
• Documentation: 1,600+ lines of comprehensive guides

🔒 Security Features

• OWASP Top 10 (2021) coverage (A01-A10)
• 20+ CWE identifiers
• Context-aware pattern matching
• 50+ false positive exclusions
• Audit trails for suppressions

📝 Breaking Changes

None - Fully backward compatible

📚 Documentation

• ENTERPRISE_GUIDE.md - Architecture and complete usage
• MIGRATION_GUIDE.md - v1.0 → v2.0 comparison
• QUICK_REFERENCE.md - Common patterns and examples

🧪 Testing

• ✅ 212 tests passing (100% pass rate)
• ✅ 30 test suites
• ✅ Zero regressions
• ✅ Full module coverage

📊 Stats

• Lines Added: 2,600+
• Files Modified: 10
• Commits: 2
• Test Coverage: 100%

🚀 Status

PRODUCTION READY ✅

v2.0.0

Summary

• Added v2 orchestration layer with cognitive memory, sandbox abstraction, external MCP client support, reasoning-loop middleware, and HITL approval tokens.
• Added SQLite cognitive memory persistence, MCP retry/circuit-breaker resilience, and the end-to-end MCP -> sandbox -> memory pipeline.
• Added secure filesystem MCP tools with write-mode gating and project-root enforcement.

Verification

• npm test

v1.3.0 — AST Analysis, Executor Pattern & Security Hardening

What's New in v1.3.0

This release is a significant architectural and security upgrade. It introduces AST-based Python analysis, the Executor Strategy pattern, and hardens multiple security boundaries.

✨ Added

• — deep security analysis using Python's native ast module; detects exec(), eval(), pickle.loads(), subprocess calls, and dangerous imports that regex cannot catch
  • Graceful degradation if Python 3.8+ is not available
• Executor Strategy Pattern (src/executors/) — pluggable skill executors; decomposes _executeSkill() from CC=13 to CC=4
• SemanticMemoryClient (src/memory/semantic-memory.js) — SRP extraction from MemoryStoreClient
• ComplianceValidator (src/mcp/validators/compliance-validator.js) — extracted from mcp-server.js; CC reduced from 12 to 3
• EXPORT_NAMES_MAP / ALLOWED_HOOK_EVENTS constants in hook-registry.js for O(1) lookup

🔒 Fixed

• CWE-362 Race Condition: FileMemoryDriver now properly awaits _ensureReady() in all write paths
• Stack Overflow: redact() has a maxDepth=10 recursion guard
• CWE-78 Docker Injection: Docker binary validated against ALLOWED_DOCKER_PATHS whitelist before spawn
• URL Validation: Network request URLs validated (null + format) before hook dispatch
• semanticSearch() input guard: rejects non-string or empty queries early

⚡ Changed

• spawnAsync() replaces execFile/promisify in agent-runner.js — non-blocking, concurrent-safe subprocess execution
• Python analyzers are now async — analyzeCodePython() and auditSecurityPython() return Promise<Finding[]>

🧪 Tests

	Before	After
Test Suites	8	12
Tests	39	87

New suites: executor-factory, compliance-validator, semantic-memory, python-ast-analyzer

⚙️ CI

• CI matrix now includes Python 3.x setup for full AST analysis capability

---

Full Changelog: v1.2.1...v1.3.0

v1.2.1 — Test Stability and Sandbox Timer Cleanup

Overview

v1.2.1 is a focused patch release that improves runtime and test stability by removing lingering timer handles and eliminating the need for forced Jest shutdown.

Fixed

• Replaced unmanaged timeout race logic in sandbox execution with a managed timeout wrapper that guarantees timer cleanup.
• Removed --forceExit from test scripts now that open-handle leakage has been resolved.

Quality Improvements

• Verified clean test process shutdown with open-handle detection.
• Confirmed all checks pass in standard mode:
  • Test suites: 8/8 passed
  • Tests: 39/39 passed
  • Lint: passed

Notes

• This release does not change public APIs.
• It improves CI reliability and local developer ergonomics by ensuring deterministic test teardown.

v1.2.0 — Async Core Hardening, Semantic Memory, and Multi-Agent Task Lifecycle

Overview

v1.2.0 extends the runtime from feature-complete foundations into stronger operational maturity across async execution, sandbox controls, semantic event memory, and multi-agent task lifecycle management.

Highlights

• Hardened non-blocking execution in core compliance and runtime flows.
• Expanded sandbox controls with Docker feature-gating and resource constraints.
• Added semantic event persistence and query capabilities for trace-aware historical retrieval.
• Extended MCP with multi-agent task lifecycle tooling (status, ack, retry) and semantic event query APIs.

Added

• MCP task lifecycle tools:
  • task_status
  • ack_task
  • retry_task
  • semantic_events
• Runtime semantic APIs:
  • AgentRuntime.semanticEventHistory(query, topK)
  • EventBus.semanticHistory(query, topK)
• Semantic event persistence hooks in memory store:
  • appendSemanticEvent(...)
  • semanticSearch(...)
• Trace-linked result metadata propagation in skill execution outputs.

Changed

• src/agent-runner.js
  • Compliance temp config write/unlink now uses fs/promises.
  • Async cleanup path improved for non-blocking operation.
  • Run-level trace_id is propagated through logs/events/results.
• src/sandbox/executor.js
  • Docker strategy now supports controlled execution attempts with:
    • docker_enabled
    • docker_image
    • docker_cpus
    • docker_memory
  • Safe fallback to local process execution remains in place when Docker is unavailable/fails.
• src/memory/memory-store.js
  • Added semantic event indexing and retrieval semantics.
  • Added vector-like similarity fallback behavior over stored event payloads.
• src/events/event-bus.js
  • Event dispatch can now persist envelopes into semantic memory when enabled.
• src/mcp-server.js
  • Added multi-agent task lifecycle tools and semantic event query endpoint.

Configuration Updates

• Added/extended runtime defaults in settings:
  • runtime.sandbox.docker_enabled
  • runtime.sandbox.docker_cpus
  • runtime.sandbox.docker_memory
  • memory.semantic_events.enabled
  • memory.semantic_events.top_k

Quality and Verification

• Test suites: 8 passed / 8 total
• Tests: 39 passed / 39 total
• Lint/syntax checks: passed

Notes

• Docker sandbox mode is intentionally feature-gated and defaults to safe fallback behavior to preserve local developer ergonomics.
• Semantic event search currently includes deterministic text-matching/vector-fallback semantics and is designed for future provider-backed vector DB integration.

v1.1.0 — Memory Adapters, Sandbox Controls, Multi-Agent Delegation, and Report Export

Overview

This release evolves agents-runtime toward a more production-ready Agent Operating System model, with major upgrades across persistence architecture, security isolation, orchestration, observability, and reporting.

Highlights

• Introduced a pluggable memory adapter architecture with backend scaffolding for Redis, PostgreSQL, and vector-oriented context retrieval.
• Added sandbox execution orchestration with strategy support (process, docker, wasm) and timeout controls.
• Added outbound network policy enforcement via a new pre-network hook and runtime hook wiring.
• Extended multi-agent coordination with event-bus messaging and task delegation APIs.
• Added OpenTelemetry-compatible tracing bootstrap with graceful no-op fallback when OTel is unavailable.
• Added report export support in CLI (--export, --format) with JSON, HTML, and PDF output options.

Added

• src/memory/memory-store.js
  • Adapter-based design with:
    • InProcessMemoryDriver
    • FileMemoryDriver
    • RedisMemoryDriver (scaffold)
    • PostgresMemoryDriver (scaffold)
    • VectorMemoryDriver (scaffold)
• src/sandbox/executor.js
  • Sandbox strategy routing and execution timeout handling.
• template/hooks/pre-network.hook.js
  • Endpoint allowlist + authorization-level enforcement before outbound requests.
• src/telemetry/tracer.js
  • OTel-compatible tracer bootstrap with runtime-safe fallback.
• src/report/exporter.js
  • JSON/HTML/PDF report generation.
• Event bus extensions:
  • sendMessage(...)
  • delegateTask(...) (emits TaskDelegated domain events).

Changed

• src/agent-runner.js
  • Skill execution now runs through sandbox orchestration.
  • Pre-network lifecycle checks enforced for declared network requests.
  • Tracing spans added around skill execution.
• src/engine.js
  • Added runtime tracer initialization.
  • Added checkNetworkAccess(...) and delegateTask(...) APIs.
• src/loader/settings-loader.js
  • Added defaults for runtime.sandbox and backend-specific memory sections (redis, postgres, vector).
• template/manifest.json and template/settings.json
  • Added before_network_access lifecycle and sandbox/memory backend config examples.
• Test fixtures updated under tests/fixtures/project/.agents/ to reflect new network and runtime policies.

CLI

agents run now supports:

• --export <path>
• --format <json|html|pdf>

Example:

node bin/agents.js run \
  --config ./agent.yaml \
  --skill code-analysis \
  --input '{"files":["src/"],"project_root":"."}' \
  --project . \
  --export ./reports/latest.html \
  --format html

Test Coverage

• Test suites: 8
• Tests: 35
• Status: ✅ all passing

New suites include:

• tests/event-bus.test.js
• tests/exporter.test.js
• tests/sandbox.test.js

Plus extended coverage in engine, hook, and memory tests for delegation, network gating, and backend selection behavior.

Notes

• Redis/PostgreSQL/Vector drivers are intentionally scaffolded to preserve compatibility with the current dependency profile and enable incremental hardening in upcoming releases.
• Security policy enforcement remains aligned with AGENT_CONTRACT.md and lifecycle hook controls.