# Agentmanager

> Agent Manager skill

- Skill: `javimosch/agentmanager` (Agent Skill)
- Install (CLI): `npx skillmds@latest add javimosch/agentmanager`
- Raw SKILL.md: https://api.skillmd.com/api/skills/javimosch/agentmanager/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: javimosch (https://skillmd.com/u/javimosch)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/javimosch/agentmanager

---

# Agent Manager skill

## What this file is for

This file is a concise integration contract for AI tool callers and gateway implementers.

This `skill.md` is a compact integration guide for Clawhub and other AI clients.

Agent Manager is an orchestration kernel for external AI planners. External AI builds plans, and Agent Manager validates, schedules, executes tools, enforces budgets, and provides replayable telemetry.

## Authentication

Use `X-Run-Token` for owner attribution and optional access control.

- `REQUIRE_RUN_TOKEN=1` enables token enforcement.
- `RUN_TOKENS` contains allowed token values.

Example header:

```http
X-Run-Token: tenant-a
```

## Capability discovery and endpoint map

Start with:

- `GET /v1/capabilities`
- `GET /v1/provider-adapter/schema`

Core endpoints:

- `POST /v1/plan` (validate plus recommendations)
- `POST /v1/plan/validate`
- `POST /v1/plan/generate`
- `POST /v1/run`
- `POST /v1/run/sync`
- `GET /v1/run/:id`
- `GET /v1/run/:id/events?after=`
- `GET /v1/run/:id/stream`
- `GET /v1/run/:id/replay`
- `GET /v1/run/:id/report` (if enabled)
- `GET /v1/runs`
- `POST /v1/run/:id/cancel`
- `POST /v1/run/:id/task/:name/inject`
- `POST /v1/tools/register` (only when enabled)

## Provider selection

Provider choice follows this order:

1. `task.provider_id`
2. `run.options.provider_id`
3. `DEFAULT_PROVIDER_ID`
4. `mock`

Read provider availability from `capabilities.llm_providers.providers` and `capabilities.llm_providers.default_provider_id`.

## Recommended client flow

1. `GET /v1/capabilities`
2. `POST /v1/plan` with `{ plan, options }`
3. `POST /v1/run` (async) or `POST /v1/run/sync`
4. Stream with `GET /v1/run/:id/stream` or poll `GET /v1/run/:id/events?after=<seq>`
5. Read final run from `GET /v1/run/:id`
6. Export replay from `GET /v1/run/:id/replay`
7. Use `POST /v1/run/:id/task/:name/inject` for deterministic overrides when needed

## Tool-calling protocol rule

When a provider returns `tool_calls`, Agent Manager appends exactly one `role="tool"` message for each `tool_call_id` before the next provider round.

This prevents protocol errors in model APIs.

## SSE reliability and resume

`GET /v1/run/:id/stream` sends event `id` from event sequence numbers.

- Resume with `Last-Event-ID` header or `?after=` query.
- If idle and run is non-terminal, heartbeat comments are emitted:

```text
: ping
```

Heartbeat interval uses `SSE_HEARTBEAT_MS` (default `15000`).

## Event types

Common emitted event types include:

- `task_start`, `task_end`, `task_retry`
- `tool_call_requested`, `tool_call_start`, `tool_call_end`, `tool_call_failed`, `tool_call_started`, `tool_call_finished`
- `llm_step_start`, `llm_step_tool_calls`, `llm_step_final`
- `llm_round_start`, `llm_round_tool_calls`, `llm_round_final`
- `budget_violation`, `fallback_start`, `fallback_end`
- `run_complete`, `run_cancel_requested`
- `dependency_truncated`, `artifact_limit`

## Replay and report data

`GET /v1/run/:id/replay` returns stable replay JSON:

```json
{
  "run": { "id": "run_123", "created_at": 1700000000000, "status": "succeeded" },
  "plan_digest": "sha256:...",
  "events": [{ "seq": 1, "type": "task_start", "run_id": "run_123" }],
  "results_index": { "task_a": { "digest_hash": "sha256:..." } }
}
```

Run cost attribution is exposed per task in `run.metrics.cost_breakdown`:

```json
{
  "metrics": {
    "cost_breakdown": {
      "task_a": {
        "cost_est": 0.0021,
        "tier": "cheap",
        "tool_calls": 1
      }
    }
  }
}
```

## HTTP callback tools and timeout enforcement

Callback tools use `callback_url` and enforce `ToolSpec.timeout_ms`.

The execution signal combines run abort plus timeout. On timeout, tool result is structured with `error_code` as `TOOL_TIMEOUT` and `retryable: true`.


## Provider adapter contract

Use `GET /v1/provider-adapter/schema` to fetch `schema_version`, request and response schemas, and examples for your gateway implementation.


## Outbound security defaults

Outbound traffic is blocked by default until allowlists are configured.

- Provider and gateway calls require `OUTBOUND_ALLOWLIST`.
- Callback tools require `TOOL_CALLBACK_ALLOWLIST`.
- IP literal hostnames and redirect chains are blocked.

## Telemetry redaction

Enable `REDACT_TELEMETRY=1` with mode `hash` or `truncate` to redact sensitive event and replay fields for shared deployments.


## Environment variables

This service uses validated configuration from `src/config.ts`. Critical outbound controls: `OUTBOUND_HOST_ALLOWLIST`, `OUTBOUND_ALLOW_ALL`, `ALLOW_INSECURE_HTTP`, `TOOL_CALLBACK_ALLOWLIST`, `MAX_PROVIDER_REQUEST_BYTES`, `MAX_TOOL_CALLBACK_REQUEST_BYTES`, and redaction flags.

## Outbound data disclosure

When gateway or callback tools are enabled, task inputs, dependency payloads, and tool payloads may be sent outbound to allowed destinations. Keep allowlists strict in shared deployments.