sdtk-agent-kit

Runtime-neutral, durable, file-driven DAG orchestration controller. Drives multi-stage agent workflows (agent-team, shell commands, sdtk-cli binaries, Hermes Kanban) with a resumable on-disk ledger, human-gate approvals, and skip-when conditional stages. Zero new runtime dependency (Node.js stdlib only).

Package

• Package: sdtk-agent-kit
• Version in this source snapshot: 0.5.0
• CLI: sdtk-agent
• Latest published version lookup: npm view sdtk-agent-kit version

Install

npm install -g sdtk-agent-kit

Then verify the installed command:

sdtk-agent --version
sdtk-agent --help

What it is

sdtk-agent is a DAG controller layered above sdtk-code agent-team — it does not rebuild execution or governance, it orchestrates it. Each run is a stateless-CLI-over-file-ledger: every command reads/writes disk under .sdtk/agent-runtime/, so a run can be paused, resumed from a different process, or inspected at any point without an in-memory session.

Core concepts:

• Workflow — a JSON DAG of task and human_gate stages with depends_on edges, optional skip_when conditional-skip rules, retry/timeout policy, and declared output paths.
• Runtime map — binds each workflow role to an adapter (manual, shell, sdtk-cli, hermes-kanban) for a given environment.
• Run ledger — .sdtk/agent-runtime/runs/<run_id>/ holds request.md, workflow.json, runtime-map.json, state.json, events.ndjson, tasks/, evidence/, approvals/, reports/. This is the single source of truth; the CLI never holds state in memory across invocations.
• State machine — a pure reducer (state + evidence + approvals → next state) drives task readiness, skip_when evaluation, human-gate blocking, and retry-bounded failure handling.

Supported Command Surface

| Command | Purpose | |---|---| | sdtk-agent init | Initialize .sdtk/agent-runtime/ in a project | | sdtk-agent workflow validate | Validate a workflow JSON file (cycle detection, unsafe paths, schema) | | sdtk-agent run start | Create a new run (ledger-only, does not execute) | | sdtk-agent run continue | Execute the run driver loop until it blocks, waits, or completes | | sdtk-agent run status | Show current run state as JSON | | sdtk-agent run report | Generate and print the run report | | sdtk-agent gate approve | Approve a human gate, unblocking downstream tasks | | sdtk-agent gate reject | Reject (or request changes on) a human gate | | sdtk-agent adapter hermes-kanban plan | Compile a workflow into a Hermes Kanban card create/link plan (dry-run only — no live gateway) |

Run sdtk-agent <command> --help for command-specific options.

Adapters

| Adapter | Behavior | |---|---| | manual | Waits for a human/agent to write an evidence file to evidence/<task_id>.evidence.json | | shell | Runs an allowlisted binary via spawnSync (shell:false), rejects shell metacharacters, denies network-mutating flags | | sdtk-cli | Dispatches to an allowlisted sdtk-* binary (sdtk-wiki, sdtk-spec, sdtk-code, sdtk-ops) and normalizes its output into evidence fields | | hermes-kanban | Pure dry-run plan compiler — turns a workflow graph into a Kanban card/link plan; validates configured profiles (herwiki/herresearch/herorches/herdev); no live card is ever created by this adapter |

Quick Start

# 1. Initialize the runtime ledger in a project
sdtk-agent init --project-path ./my-project

# 2. Validate a workflow file
sdtk-agent workflow validate --file ./workflow.json

# 3. Start a run (creates the ledger, does not execute)
sdtk-agent run start \
  --project-path ./my-project \
  --workflow ./workflow.json \
  --runtime-map ./runtime-map.json \
  --feature-key MY_FEATURE \
  --goal "Describe the goal" \
  --json

# 4. Drive the run forward
sdtk-agent run continue --project-path ./my-project --run-id <run_id>

# 5. Approve a human gate when the run is waiting
sdtk-agent gate approve --project-path ./my-project --run-id <run_id> \
  --gate <gate_id> --approved-by <name>

# 6. Check status or generate the final report
sdtk-agent run status --project-path ./my-project --run-id <run_id> --json
sdtk-agent run report --project-path ./my-project --run-id <run_id>

Safety

• Path containment guard: all writes are checked against the ledger root before touching disk.
• Shell/sdtk-cli adapters use an explicit binary allowlist — unknown binaries fail closed with no evidence written.
• Shell metacharacters and network-mutating flags are rejected before dispatch.
• Windows dispatch: allowlisted commands are resolved across PATH×PATHEXT. .exe/.com targets spawn directly (shell:false); npm-style .cmd/.bat shims (how sdtk-wiki, npx, … land on Windows) run through %ComSpec% /d /s /c under a strict argument policy — any token containing %, ^, " or control characters fails closed before a shell ever sees the command line. .ps1-only shims are not supported.
• Secrets are redacted (parity-tested against sdtk-code's trust-redact.js) before evidence or reports are written to disk.
• .env and other project files outside the ledger are never touched by the controller itself.

Product Boundary

sdtk-agent is the DAG orchestration layer above sdtk-code agent-team. It is:

• runtime-neutral (works with agent-team, raw shell commands, sdtk-cli binaries, or a human operator via the manual adapter)
• file-driven and resumable — no in-memory session, no daemon
• zero new runtime dependency (Node.js stdlib only)

It is not:

• a replacement for agent-team's execution/governance (it delegates to it via adapters)
• a live Hermes Kanban client (the hermes-kanban adapter is dry-run only in this release)
• a scheduler or cron system

Documentation

• Spec: governance/ai/reviews/shared/SDTK_AGENT_RUNTIME_CONTROLLER_SPEC_R1_20260630.md
• Implementation plan: governance/ai/reviews/shared/SDTK_AGENT_RUNTIME_CONTROLLER_IMPL_PLAN_R1_20260630.md
• Benchmark scenario: governance/ai/reviews/shared/SDTK_AGENT_RUNTIME_CONTROLLER_BENCHMARK_TEST_SCENARIO.md