Agentd

agentd

Use this skill when building, operating, documenting, or integrating with agentd.

agentd is a local-first state machine daemon for AI agents. It runs out of process, stores durable state in SQLite, and exposes a Unix Domain Socket JSON Lines API so multiple runtimes can coordinate long-running work without becoming the source of truth themselves.

Capabilities

• Durable state: stores tasks, DAG nodes, results, resource locks, and event history under ~/.agentd.
• Task DAGs: registers work as nodes with dependencies so agents can run independent steps concurrently and join later.
• Node leases: grants runnable nodes with lease_id, lease owner, and expiry.
• Heartbeats: extends active node or resource leases while a worker is alive.
• Timeout rollback: stale running nodes return to PENDING; stale lease writes are rejected.
• Event journal: records append-only task events for intent, progress, results, failures, and conflicts.
• Cross-provider locks: leases named resources such as file:src/lib.rs, dir:src, artifact:docs/api.json, or tool:cargo-fmt.
• Runtime discovery: DescribeInterface returns supported methods and payload shapes.
• Health checks: Health reports daemon and database readiness.
• Metrics: Metrics reports runtime counters and database gauges.
• Provider-neutral coordination: Codex, Claude, Antigravity, DeepSeek scripts, shell workers, and custom clients use the same socket protocol.
• Conflict resolution: overlapping provider edits are coordinated with locks, events, and patch bundles instead of last-writer-wins.

Default Paths

IPC Basics

Transport is Unix Domain Socket JSON Lines: send one JSON request per line and read one JSON response per line.

Query the runtime contract:

printf '%s\n' '{"id":1,"method":"DescribeInterface","params":{}}' \
  | nc -U ~/.agentd/agentd.sock \
  | python3 -m json.tool

Core methods:

Task DAG Workflow

1. Register a task with RegisterTask, including initial_nodes.
2. Workers call AcquireNextNode with a lease_owner.
3. A worker may append CommitEvent entries while running.
4. A worker must call HeartbeatNode before lease expiry for long work.
5. Finish with CompleteNode or FailNode using the current lease_id.
6. Inspect overall state with TaskStatus or Metrics.

Minimal task registration:

printf '%s\n' '{
  "id": 1,
  "method": "RegisterTask",
  "params": {
    "goal": "multi-agent docs update",
    "context": {"repo": "agentd"},
    "initial_nodes": [
      {"dependencies": [], "payload_schema": {"role": "writer"}},
      {"dependencies": [], "payload_schema": {"role": "reviewer"}}
    ]
  }
}' | nc -U ~/.agentd/agentd.sock | python3 -m json.tool

Acquire work:

printf '%s\n' '{
  "id": 2,
  "method": "AcquireNextNode",
  "params": {
    "task_id": "current-task-uuid",
    "lease_owner": "codex-worker-a"
  }
}' | nc -U ~/.agentd/agentd.sock | python3 -m json.tool

Complete work:

printf '%s\n' '{
  "id": 3,
  "method": "CompleteNode",
  "params": {
    "task_id": "current-task-uuid",
    "node_id": "current-node-uuid",
    "lease_id": "current-node-lease-uuid",
    "result_payload": {"ok": true, "summary": "docs updated"}
  }
}' | nc -U ~/.agentd/agentd.sock | python3 -m json.tool

Resource Lock Workflow

Use resource locks when multiple providers may write the same file, directory, generated artifact, or external tool.

Recommended keys:

Acquire a lock:

printf '%s\n' '{
  "id": 4,
  "method": "AcquireResourceLock",
  "params": {
    "resource_key": "file:src/lib.rs",
    "owner": "codex-cli",
    "provider": "openai",
    "ttl_secs": 300,
    "metadata": {"intent": "edit"}
  }
}' | nc -U ~/.agentd/agentd.sock | python3 -m json.tool

If the result is null, another worker holds the resource. Wait, narrow scope, or ask the coordinator to resolve.

Heartbeat and release:

printf '%s\n' '{
  "id": 5,
  "method": "HeartbeatResourceLock",
  "params": {
    "resource_key": "file:src/lib.rs",
    "lease_id": "current-resource-lock-lease-uuid",
    "ttl_secs": 300
  }
}' | nc -U ~/.agentd/agentd.sock | python3 -m json.tool

printf '%s\n' '{
  "id": 6,
  "method": "ReleaseResourceLock",
  "params": {
    "resource_key": "file:src/lib.rs",
    "lease_id": "current-resource-lock-lease-uuid"
  }
}' | nc -U ~/.agentd/agentd.sock | python3 -m json.tool

Multi-Provider Conflict Resolution

Use this section when multiple agents or providers can touch the same repository, files, generated artifacts, or logical work units. The goal is to avoid blind overwrites and make every merge decision auditable.

Core Policy

Never use last-writer-wins as the default merge rule.

Use three layers:

1. Locks prevent unsafe overlap. Acquire narrow locks for files, directories, generated artifacts, tools, or logical work units.
2. Events explain work. Record intent, progress, result, and conflict events when the environment supports a journal.
3. Patch bundles drive merges. Compare provider outputs by metadata and verification, not by provider name or arrival order.

Patch Bundle

Every provider result should include:

• provider: provider/runtime name, such as openai, anthropic, antigravity, or custom.
• owner: concrete agent identity.
• base_revision: git SHA, branch name, or other stable starting point.
• touched_paths: files or resources the provider read or changed.
• diff_summary: concise behavioral summary.
• assumptions: important constraints the provider relied on.
• confidence: low, medium, or high.
• verification: commands run and outcomes.
• conflicts: observed overlaps, stale bases, failed checks, or incompatible intent.

Workflow

1. Inspect current state with git status -sb and the relevant diff.
2. Assign disjoint ownership when possible.
3. Before editing shared resources, acquire or request a narrow lock.
4. If a lock is unavailable, do not write over the owner. Wait, narrow scope, or submit a patch bundle for coordinator review.
5. Record provider intent before work begins when an event journal is available.
6. On completion, collect patch bundles from every provider.
7. Detect conflicts by comparing base_revision, touched_paths, and intent.
8. Resolve by preserving compatible edits, rejecting stale or unverifiable changes, and recording discarded alternatives.
9. Verify the merged result with the smallest meaningful checks.
10. Release locks and record the final decision.

Conflict Decisions

agentd IPC Pattern

Use resource locks for shared files and put patch-bundle metadata in metadata:

printf '%s\n' '{
  "id": 1,
  "method": "AcquireResourceLock",
  "params": {
    "resource_key": "file:docs/index.html",
    "owner": "codex-docs-agent",
    "provider": "openai",
    "ttl_secs": 600,
    "metadata": {
      "intent": "update docs conflict section",
      "base_revision": "git:HEAD",
      "touched_paths": ["docs/index.html", "docs/styles.css"],
      "diff_summary": "add provider-neutral conflict workflow",
      "assumptions": ["static HTML", "CSS-only animation"],
      "confidence": "medium",
      "verification": ["python3 HTML parser sanity check"]
    }
  }
}' | nc -U ~/.agentd/agentd.sock | python3 -m json.tool

If the response is null, another provider owns the resource. Do not write that resource unless the coordinator explicitly resolves the conflict.

For DAG work, journal the resolution:

printf '%s\n' '{
  "id": 2,
  "method": "CommitEvent",
  "params": {
    "task_id": "current-task-uuid",
    "node_id": "current-node-uuid",
    "lease_id": "current-node-lease-uuid",
    "action_type": "conflict",
    "payload": {
      "resource_key": "file:docs/index.html",
      "providers": ["openai", "antigravity"],
      "resolution": "merged compatible edits from patch bundles",
      "rejected_alternatives": ["last-writer-wins"],
      "verification": "HTML parser sanity check passed"
    }
  }
}' | nc -U ~/.agentd/agentd.sock | python3 -m json.tool

Release the lock after the merge and verification:

printf '%s\n' '{
  "id": 3,
  "method": "ReleaseResourceLock",
  "params": {
    "resource_key": "file:docs/index.html",
    "lease_id": "current-resource-lock-lease-uuid"
  }
}' | nc -U ~/.agentd/agentd.sock | python3 -m json.tool

Coordinator Output

When reporting the result, include:

• Providers involved.
• Files/resources that overlapped.
• Accepted changes.
• Rejected or superseded alternatives.
• Verification performed.
• Any locks left active or follow-up rebases needed.

Source: guozijn/agentd — distributed by TomeVault.