sdtk-agent-hermes-adapter

Hermes live-dispatch adapter for sdtk-agent — dry-run, mock, and live.

This package implements the sdtk-agent lifecycle adapter contract (submit / poll / preflight / cancel) for the hermes-live adapter name. It maps workflow roles to HerBot profiles and compiles the Hermes Kanban card dispatch payload each task creates.

Live status (important). The mode: "live" real-dispatch path is implemented in source (lib/gateway.js + lib/live.js) and verified offline against a mock gateway. It is NOT public-ready and NOT enabled for npm users: public Hermes Live requires a coordinated publish (sdtk-agent-kit with the BK-296 recovery verbs → this live-capable adapter → the sdtk-kit umbrella), real-box evidence, and an independent security review — none of which have happened yet. Until that publish, treat this package as dry-run + mock for any installed/npm use; the live code is source-only and gated.

Install

npm install -g sdtk-agent-kit sdtk-agent-hermes-adapter

Use

sdtk-agent core loads this adapter by name through its adapter registry, via a user-declared module path in the runtime map (core never statically requires this package):

{
  "schema_version": "sdtk.agent-runtime-map.v1",
  "environment_id": "hermes-mock",
  "hermes": { "profiles_source": "/opt/data/hermes-profiles" },  // optional roster source
  "roles": {
    "knowledge_retriever": {
      "adapter": "hermes-live",
      "module": "sdtk-agent-hermes-adapter",
      "mode": "mock",                                   // dry-run | mock  (live: source-only, not public-ready)
      "config": {
        "profile": "herwiki",
        "prompt_template": "templates/herwiki-search.md",
        "deadline_ms": 900000,
        "mock_evidence_file": "fixtures/wiki-evidence.json"  // mock: fixture evidence to complete with
      }
    }
  }
}

• dry-run — submit compiles the card payload and simulates assignment; nothing is sent.
• mock — additionally, poll completes the task from config.mock_evidence_file (or synthesized evidence), so a full workflow runs deterministically offline.
• live — real gateway dispatch (lib/gateway.js + lib/live.js): fail-closed preflight, idempotent card create/adopt, and cancel. Source-only and gated — not enabled for npm users until the coordinated publish + real-box evidence + independent review land (see Live status above).
• Use config.complete_when_file to keep a task running_external until a signal file appears (to exercise resume/deadline).

Per-stage task instruction (params.instruction)

By default every Hermes worker in a run receives the same run-global goal. A multi-stage workflow (e.g. herresearch -> hersocial -> herorches) can give each stage its own instruction by setting params.instruction on the workflow stage:

{ "id": "research", "role": "researcher", "params": {
    "instruction": "Produce a concise, source-backed research brief. Do not browse, purchase, post, send messages, or modify files."
} }

params is a plain pass-through field already supported by sdtk-agent core for every stage — no workflow-schema change is required. When a stage sets a non-empty params.instruction, it becomes that worker's card body requested_task and the compiled/dry-run payload's card.instruction field; a stage that omits it falls back to the run's goal, unchanged from prior releases. Scrub boundary: the resolved instruction is redacted (secret/Bearer-shaped text stripped) both in the native Kanban card body (requested_task) and in compileTaskPayload's card.instruction — a credential accidentally placed in params.instruction never reaches dry-run, plan, or live output unredacted. The legacy card.goal field is left unscrubbed, exactly as every pre-BK-313 release — it exists only for backward compatibility; do not read goal off a compiled payload for anything that might carry a credential, read instruction instead.

Only the text of params.instruction is scrubbed for known secret shapes (a literal Bearer <token> pattern). This is not evidence handoff: a stage's instruction is a static string the workflow author writes ahead of time — it does not automatically carry an upstream stage's output/evidence into a downstream stage. depends_on controls dispatch ordering only. If a downstream instruction needs to reference an upstream result (e.g. "use the approved research facts"), an operator must place that content into the instruction themselves before the downstream stage dispatches — see the BK-313 Phase 3 operator packet for the attended two-run handoff pattern this implies.

Live backends (config.backend)

mode: "live" dispatches through a selectable backend. backend defaults to rest, so existing configs are unchanged.

• rest (default) — the zero-dep REST binding (lib/gateway.js + lib/live.js) from BK-299. Needs a Hermes REST gateway (gateway_url, token_env, board_id).
• kanban-cli (BK-310) — the native hermes kanban CLI on the Hermes box. No REST gateway or token. env.HERMES_HOME must be the native dispatcher's kanban home — the DB where dispatched tasks and worker completions live (e.g. /opt/data/hermes), not a per-assignee profile home (a profile-local DB does not contain dispatcher-created tasks). The adapter injects HERMES_HOME and strips any ambient HERMES_KANBAN_HOME so the kanban DB always resolves from the injected HERMES_HOME. --assignee <profile> routes the card to a worker; it is independent of which DB HERMES_HOME selects. Every created card carries an explicit --body with an imperative, tool-named procedure (call kanban_show → do the task → kanban_comment → kanban_complete, with a safe no-op fallback and run/task/ idempotency ids) — a title-only or merely descriptive card makes the native worker drift into open-ended repo research and never complete. All calls are argv-only (no shell) through a validated absolute hermes_bin; the adapter never opens the SQLite DB.

{
  "adapter": "hermes-live",
  "module": "sdtk-agent-hermes-adapter",
  "mode": "live",
  "config": {
    "backend": "kanban-cli",
    "profile": "herwiki",                                   // → kanban --assignee
    "hermes_bin": "/workspace/.venvs/hermes-agent/bin/hermes", // absolute, validated
    "env": { "HERMES_HOME": "/opt/data/hermes" },               // dispatcher kanban home (not a profile home)
    "board": "default",
    "live_ack": true,
    "cancel_action": "reclaim"                              // reclaim | block | archive
  }
}

Status mapping (native Kanban → SDTK): done/completed → completed; blocked → failed(HERMES_TASK_BLOCKED); archived → failed(HERMES_TASK_ARCHIVED); triage/todo/scheduled/ready/running/review/in_progress/queued → keep polling; any unexpected status fails closed (HERMES_STATUS_UNKNOWN). Cancel is least-destructive (reclaim → block → archive) and report-only — archive ≠ terminate, block ≠ cancel; local SDTK cancel is authoritative.

Gated / validation-only. Like the REST backend, kanban-cli live dispatch is source-only and not public-ready until native-Kanban real-box evidence + independent review land. Tests substitute a fake CLI ONLY via the test-gated SDTK_HERMES_CLI_FOR_TESTS seam (requires SDTK_HERMES_TEST_MODE=1).

Profile roster

The allowed HerBot roster is resolved from, in order:

1. runtimeMap.hermes.profiles_source — a directory of profile folders or a JSON array file,
2. core config.hermes.profiles (the sdtk-agent config roster),
3. the reference default herwiki, herresearch, herorches, herdev.

An unknown or missing config.profile fails closed before any dispatch.

Boundary

Everything Hermes-specific lives here; sdtk-agent core stays Hermes-unaware. Live card/message dispatch and gateway health checks are implemented in this package's source (lib/gateway.js + lib/live.js) but remain unpublished and gated — not exposed to npm users until the coordinated publish. Telegram/operator glue stays in the deployment repo, never in this package or in core.

License

MIT