Skip to content

Epic: Assimilate Hermes Agent as an Ouroboros-native AgentOS capability #40

Open
#86
Open
Epic: Assimilate Hermes Agent as an Ouroboros-native AgentOS capability#40
#86
Labels
enhancementNew feature or request
@shaun0927

Description

@shaun0927
shaun0927
opened on May 20, 2026

Epic: Assimilate Hermes Agent as an Ouroboros-native AgentOS capability while preserving the Hermes user experience

Status

Proposed epic / implementation umbrella.

Related context

Core thesis

Hermes Agent should not be reduced to a thin shell:execute wrapper, nor should its user experience be flattened into a generic plugin command. The goal is to make Hermes run smoothly inside the Ouroboros execution ecosystem while preserving the Hermes experience users already understand:

  • interactive hermes-style agent sessions,
  • skills and skill bundles,
  • model/provider switching,
  • messaging gateway semantics,
  • cron/scheduled automations,
  • persistent memory and self-improvement loops,
  • subagent/delegation workflows,
  • terminal/backend flexibility,
  • and long-running agent continuity.

The Ouroboros plugin layer should act as the assimilation boundary: Hermes remains a rich external agent runtime, while Ouroboros provides permissioning, audit, provenance, handoff, state, ledger, recovery, and Seed/Run integration around it.

The intended end state is an AgentOS-style bridge: from Ouroboros, users can launch, inspect, resume, schedule, audit, and hand off Hermes work without losing the native Hermes workflow.

Why this belongs in ouroboros-plugins

Issue #27 defines plugins as the capability assimilation layer, not a marketplace and not a dumping ground for command wrappers. Hermes is a strong test case because it is not a small CLI utility. It is a full agent runtime with its own plugin system, skills, memory, gateway, scheduling, providers, and subagents.

A Hermes adapter can prove several contract boundaries:

  • how a large external agent runtime becomes Ouroboros-native without entering core;
  • how broad external capability surfaces are permissioned conservatively;
  • how long-running/background agent sessions become auditable and resumable;
  • how external skill systems map into Seed/handoff artifacts;
  • how user-level plugin trust handles model providers, shell execution, filesystem access, and messaging gateways;
  • how an external agent OS can interoperate with Ouroboros without bypassing the firewall.

This should be designed as a reference-grade capability adapter, not as a marketplace listing and not as a one-command wrapper.

Product goal

A user who already knows Hermes should be able to use Hermes through Ouroboros with minimal conceptual loss.

Examples of desired UX:

ooo hermes chat

Starts or attaches to an interactive Hermes session with Ouroboros-managed provenance, session state, audit events, and permission checks.

ooo hermes run "review this repository and produce a migration plan"

Runs a bounded Hermes task and attaches the result as an Ouroboros handoff artifact.

ooo hermes skills inspect ./hermes-agent

Inspects Hermes skills without executing them and produces a permission/risk/capability map.

ooo hermes skills import ./hermes-agent/skills/research/domain-intel

Converts a Hermes skill into an Ouroboros-readable capability/handoff artifact.

ooo hermes cron import ~/.hermes/cron/jobs.json

Converts Hermes scheduled jobs into Seed-compatible workflow drafts, preserving schedule metadata and delivery semantics as explicit, reviewable artifacts.

ooo hermes resume <session-id>

Resumes a previously launched Hermes-backed task with Ouroboros state/provenance continuity.

Non-goals

  • Do not copy the full Hermes runtime into Ouroboros core.
  • Do not add Hermes-specific branching to ooo auto.
  • Do not treat Q00/ouroboros-plugins as a hosted marketplace for all Hermes plugins.
  • Do not grant broad shell/network/messaging/model-provider permissions implicitly.
  • Do not auto-run imported Hermes skills or cron jobs during inspection/import.
  • Do not bypass the Ouroboros plugin firewall for convenience.
  • Do not require schema expansion until a reference implementation proves current fields cannot represent the required behavior.

Proposed architecture

Implement this as a staged plugin family, with a conservative read/convert phase before execution.

1. hermes-skill-assimilator — read-only/import-first reference plugin

Purpose: inspect Hermes SKILL.md files, optional skills, and plugin metadata, then emit Ouroboros-native handoff artifacts.

Initial commands:

  • ooo hermes-skill inspect <repo-or-skill-path>
  • ooo hermes-skill convert <skill-path> --out <output-dir>
  • ooo hermes-skill catalog <repo-path> --out <report>

Required behavior:

  • Read Hermes skill frontmatter and body.
  • Detect referenced files, setup requirements, shell snippets, environment variables, and external tools.
  • Classify each skill by risk:
    • read-only guidance,
    • filesystem write,
    • shell execution,
    • network access,
    • credential-dependent external mutation,
    • destructive or production-affecting behavior.
  • Emit a human-readable conversion report.
  • Emit a machine-readable handoff artifact that downstream Ouroboros workflows can consume.
  • Preserve the original Hermes skill text as provenance, not as blindly trusted instructions.
  • Never execute skill instructions during inspection.

Expected artifacts:

  • hermes-skill-report.md
  • hermes-skill-capability-map.json
  • seed-handoff.md
  • permission-review.md
  • optional ouroboros.plugin.draft.json

Why this should come first:

It proves the #27 external capability assimilation path with low operational risk. It also gives us concrete evidence before deciding whether manifest/schema expansion is needed.

2. hermes-automation-adapter — cron/job/workflow bridge

Purpose: map Hermes scheduled jobs and automations into Ouroboros Seed/Run/handoff concepts without immediately executing them.

Initial commands:

  • ooo hermes-cron inspect <jobs-json-or-hermes-home>
  • ooo hermes-cron import <jobs-json-or-hermes-home> --out <output-dir>
  • ooo hermes-cron plan <job-id> --out <seed-draft>

Required behavior:

  • Read Hermes cron job definitions.
  • Preserve schedule, prompt, skills, scripts, delivery targets, workdir, profile, repeat policy, and no-agent mode.
  • Classify side effects and external delivery risk.
  • Produce Seed-compatible workflow drafts for explicit review.
  • Do not schedule or run imported jobs by default.

Expected artifacts:

  • hermes-cron-report.md
  • hermes-cron-risk-map.json
  • seed-drafts/*.md
  • handoff.md

3. hermes-agent-runner — bounded runtime execution bridge

Purpose: run Hermes as an external agent runtime under Ouroboros supervision while preserving native Hermes behavior.

This should be implemented only after the read/import plugins prove the permission and artifact model.

Initial commands:

  • ooo hermes chat
  • ooo hermes run <prompt>
  • ooo hermes resume <session-id>
  • ooo hermes status <session-id>
  • ooo hermes stop <session-id>
  • ooo hermes export <session-id> --out <handoff-dir>

Required behavior:

  • Launch Hermes in a bounded subprocess or managed terminal/session.
  • Record invocation metadata, selected working directory, environment contract, and session id.
  • Capture stdout/stderr/transcript locations as provenance.
  • Attach final or partial outputs as handoff artifacts.
  • Respect Ouroboros cancellation and resume semantics.
  • Preserve the Hermes interactive experience where possible.
  • Require explicit trust for broad shell/network/model/messaging permissions.

Hard requirement:

This must not become an unbounded python -m hermes wrapper. It must expose a structured lifecycle and auditable result model.

Permission model

Minimum read/import phase

Likely capabilities:

  • state:write — persist inspection/import state.
  • provenance:write — record source repo, commit, file paths, and conversion decisions.
  • handoff:attach — attach generated artifacts.
  • progress:write — report import progress.

Likely permissions:

  • filesystem:read — read Hermes repo, skills, plugin manifests, and job definitions.
  • filesystem:write — write reports and handoff artifacts.

Runtime phase

Likely additional capabilities:

  • runtime:execute — launch bounded Hermes subprocess/session.
  • ledger:write — record task decisions and permission usage.
  • state:read/write — resume/inspect sessions.

Likely additional permissions:

  • shell:execute — launch Hermes.
  • network:read / network:write — model providers, web tools, plugin backends.
  • filesystem:read / filesystem:write — workspace access.
  • provider-specific scopes where feasible:
    • github:read, github:pull_request:write
    • slack:write
    • telegram:write
    • discord:write
    • email:write
    • etc.

Destructive or externally mutating permissions must require explicit trust and command-level confirmation.

Audit and provenance requirements

Every command must emit enough evidence to answer:

  • Which Hermes source was used?
  • Which commit/version/path was inspected or executed?
  • Which files were read?
  • Which files were written?
  • Which permissions were used?
  • Which external systems were contacted or mutated?
  • Which model/provider credentials were required?
  • What artifacts were produced?
  • What is the resume/inspection path for partial results?
  • What can a downstream ooo auto or harness consume?

Minimum audit events should include:

  • plugin.invoked
  • plugin.permission_used
  • plugin.completed
  • plugin.failed

The runtime bridge may justify additional lifecycle/audit events in a later schema discussion, such as:

  • plugin.session.started
  • plugin.session.resumed
  • plugin.session.stopped
  • plugin.artifact.attached
  • plugin.external_process.spawned

Do not add these until a concrete implementation proves the need.

Manifest/schema questions to validate

Start with the existing v0.1 contract if possible. Track any pressure that cannot be represented cleanly.

Potential future manifest fields, if proven necessary:

  • runtime_requirements
  • dependencies
  • env
  • secrets
  • allowed_paths
  • network_endpoints
  • timeouts
  • background_services
  • session_lifecycle
  • artifact_schema
  • resume_contract
  • cancellation_contract

Schema expansion should follow the #27 rule: expand the manifest only when a reference plugin demonstrably needs the field and existing capabilities/permissions/audit/handoff cannot represent it.

Proposed initial manifest shape

A first pass can be represented without schema expansion:

{
  "schema_version": "0.1",
  "name": "hermes-skill-assimilator",
  "version": "0.1.0",
  "description": "Inspect and convert Hermes Agent skills/plugin metadata into Ouroboros-native capability handoff artifacts.",
  "source": {
    "type": "local_path",
    "path": "plugins/hermes-skill-assimilator"
  },
  "commands": [
    {
      "namespace": "hermes-skill",
      "name": "inspect",
      "summary": "Inspect Hermes skills and plugin metadata without executing them.",
      "usage": "ooo hermes-skill inspect <repo-path>",
      "risk": "read_only",
      "requires_confirmation": false,
      "arguments": [
        {
          "name": "repo_path",
          "type": "path",
          "required": true,
          "description": "Local Hermes Agent repository path or exported Hermes skill directory."
        }
      ]
    },
    {
      "namespace": "hermes-skill",
      "name": "convert",
      "summary": "Generate Ouroboros handoff artifacts from selected Hermes skills.",
      "usage": "ooo hermes-skill convert <skill-path> --out <output-dir>",
      "risk": "write",
      "requires_confirmation": false
    }
  ],
  "capabilities": [
    {
      "name": "state",
      "access": "write",
      "reason": "Persist inspection/import state between invocations."
    },
    {
      "name": "provenance",
      "access": "write",
      "reason": "Record Hermes source paths, versions, and conversion decisions."
    },
    {
      "name": "handoff",
      "access": "attach",
      "reason": "Attach generated Seed-compatible handoff artifacts."
    },
    {
      "name": "progress",
      "access": "write",
      "reason": "Report long-running scan/import progress."
    }
  ],
  "permissions": [
    {
      "scope": "filesystem:read",
      "risk": "read_only",
      "required": true,
      "reason": "Read Hermes skills and plugin manifests."
    },
    {
      "scope": "filesystem:write",
      "risk": "write",
      "required": true,
      "reason": "Write conversion reports and handoff artifacts."
    }
  ],
  "entrypoint": {
    "type": "command",
    "command": "python -m hermes_skill_assimilator"
  }
}

Implementation phases

Phase 0 — Research and contract fit

  • Pin a Hermes Agent commit/version for fixture analysis.
  • Document Hermes surfaces relevant to Ouroboros:
    • skills,
    • optional skills,
    • plugin manifests,
    • cron jobs,
    • memory providers,
    • gateway/platforms,
    • model providers,
    • subagent/delegation tools.
  • Write a contract-fit note explaining what can use v0.1 and what may need future schema changes.

Phase 1 — Read-only skill/plugin inspector

  • Add plugins/hermes-skill-assimilator/ouroboros.plugin.json.
  • Implement inspect command.
  • Parse Hermes SKILL.md files.
  • Parse Hermes plugin.yaml files.
  • Produce risk/capability reports without executing Hermes code.
  • Add fixtures based on a small representative Hermes subset.
  • Validate manifest with scripts/validate_contract.py.

Phase 2 — Conversion and handoff artifacts

  • Implement convert command.
  • Generate human-readable handoff artifacts.
  • Generate machine-readable capability maps.
  • Preserve source provenance.
  • Mark unresolved trust decisions explicitly.
  • Add tests for deterministic output.

Phase 3 — Cron/job importer

  • Add hermes-cron inspect.
  • Add hermes-cron import.
  • Convert Hermes jobs into Seed-compatible drafts.
  • Preserve schedule/delivery/workdir/profile/script/no-agent metadata.
  • Classify external delivery and script execution risks.

Phase 4 — Bounded Hermes runtime bridge

  • Design runtime lifecycle contract.
  • Define session id, transcript path, artifact path, cancellation, and resume behavior.
  • Implement ooo hermes run as non-interactive bounded execution first.
  • Implement ooo hermes chat or attach mode only after lifecycle evidence exists.
  • Emit audit/provenance events for process spawn, permission usage, completion/failure.
  • Attach partial results on failure/cancel.

Phase 5 — AgentOS integration polish

  • Make Hermes sessions visible in Ouroboros status/progress surfaces.
  • Support smooth handoff from Hermes output into ooo auto or other harness flows.
  • Support resume from generated artifacts.
  • Document trust model and usage examples.
  • Decide whether any manifest/schema extension is justified by implementation evidence.

Acceptance criteria

This epic is complete when:

  • Hermes capabilities can be inspected from Ouroboros without executing untrusted code.
  • At least one Hermes skill can be converted into an Ouroboros-readable handoff artifact.
  • Generated artifacts include source provenance, permission/risk classification, and downstream handoff guidance.
  • Hermes cron/job definitions can be converted into reviewable Seed-compatible drafts without scheduling them by default.
  • A bounded Hermes runtime command can run under Ouroboros supervision with explicit permissions and auditable results.
  • A user can resume or inspect a Hermes-backed Ouroboros run from saved state/artifacts.
  • The implementation preserves Hermes user experience where possible instead of replacing it with a generic wrapper.
  • The plugin passes the repository contract validator.
  • Any proposed schema changes are backed by concrete reference-plugin evidence.
  • Documentation explains why this is an Ouroboros-native capability adapter and not a marketplace entry or arbitrary command wrapper.

Open questions

  • Should the first reference plugin live in this repository, while the full runner lives in a separate third-party plugin repository?
  • What is the minimal interactive attach model needed to preserve hermes UX without bypassing Ouroboros audit/state?
  • Should model-provider access be represented as generic network:* permissions initially, or should provider-specific permission scopes be introduced later?
  • How should long-running gateway/cron/background services map to the current plugin lifecycle?
  • What is the canonical handoff format for imported Hermes skills and scheduled jobs?
  • Should Hermes memory providers be treated as external services, local state, or both depending on provider?

Design guardrail

The success metric is not “Hermes can be launched from Ouroboros.”

The success metric is:

Hermes can operate as a first-class external AgentOS capability under Ouroboros control, while preserving the Hermes user experience and adding Ouroboros-native permissioning, audit, provenance, resumability, handoff, and Seed/Run interoperability.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions