Read-only query operations for swarm state.
Query functions for:
Read-only query operations for swarm state. Query functions for: - Slave queries (get, list, filter by status) - Task queries (get, list for slave, completed tasks) - Claim queries (get, list, conflict detection) - Statistics and debugging
(check-file-conflicts requesting-slave files)Check for conflicts on multiple files.
Arguments: requesting-slave - Slave wanting to claim files files - Collection of file paths to check
Returns: Seq of {:file :held-by} for conflicting files (empty if no conflicts)
Check for conflicts on multiple files.
Arguments:
requesting-slave - Slave wanting to claim files
files - Collection of file paths to check
Returns:
Seq of {:file :held-by} for conflicting files (empty if no conflicts)A claim-history row with keys renamed to the unqualified projection.
A claim-history row with keys renamed to the unqualified projection.
A file claim projection (see get-claims-for-file / get-all-claims).
A file claim projection (see get-claims-for-file / get-all-claims).
(db-stats)Get statistics about the current swarm state.
Get statistics about the current swarm state.
Counts of each entity kind in the swarm db.
Counts of each entity kind in the swarm db.
(dump-db)Dump the current database state for debugging. Includes stale/zombie slaves so the dump is exhaustive.
Dump the current database state for debugging. Includes stale/zombie slaves so the dump is exhaustive.
(get-all-claims)Get all current file claims.
Returns: Seq of {:file :slave-id :task-id :created-at :prior-hash :qn :mode} maps. :prior-hash is the file content hash captured at claim acquire time (CC.3).
:qn and :mode describe a SPAN claim (see hive-mcp.swarm.claim.span) and are nil for a whole-file claim. They are projected explicitly because this map is a closed list: an attribute absent here is invisible to every caller no matter what the entity holds, which is how span modes were being persisted and then silently read back as :body.
Get all current file claims.
Returns:
Seq of {:file :slave-id :task-id :created-at :prior-hash :qn :mode} maps.
:prior-hash is the file content hash captured at claim acquire time (CC.3).
:qn and :mode describe a SPAN claim (see hive-mcp.swarm.claim.span) and are
nil for a whole-file claim. They are projected explicitly because this map
is a closed list: an attribute absent here is invisible to every caller no
matter what the entity holds, which is how span modes were being persisted
and then silently read back as :body.(get-all-slaves & {:keys [include-stale?] :or {include-stale? false}})Get all slaves in the swarm.
Options: :include-stale? — when true, returns ALL rows (incl. :alive? false + activity-stale). Default false: filters out zombies + stale rows. Legacy rows (no :slave/alive? attr) treated as alive.
Rows come from slave-index, read once and advanced per transaction; a
test connection reads them fresh.
Returns: Seq of maps with slave attributes
Get all slaves in the swarm.
Options:
:include-stale? — when true, returns ALL rows (incl. :alive? false + activity-stale).
Default false: filters out zombies + stale rows.
Legacy rows (no :slave/alive? attr) treated as alive.
Rows come from `slave-index`, read once and advanced per transaction; a
test connection reads them fresh.
Returns:
Seq of maps with slave attributes(get-child-project-ids parent-project-id)Get unique project-ids of slaves whose parent belongs to the given project.
Used by piggyback assembly to include cross-project descendant shouts. A coordinator in project A that spawned lings into project B will get B in the returned set, so piggyback can include those lings' messages.
Arguments: parent-project-id - Project ID of the parent/coordinator
Returns: Set of project-id strings (may be empty, never includes nil or parent-project-id)
Get unique project-ids of slaves whose parent belongs to the given project. Used by piggyback assembly to include cross-project descendant shouts. A coordinator in project A that spawned lings into project B will get B in the returned set, so piggyback can include those lings' messages. Arguments: parent-project-id - Project ID of the parent/coordinator Returns: Set of project-id strings (may be empty, never includes nil or parent-project-id)
(get-claims-for-file file-path)Get claim info for a file.
Returns: Map with :slave-id, :task-id, :prior-hash or nil if unclaimed. :prior-hash is the file content hash captured at claim acquire time (CC.3).
Get claim info for a file. Returns: Map with :slave-id, :task-id, :prior-hash or nil if unclaimed. :prior-hash is the file content hash captured at claim acquire time (CC.3).
(get-completed-tasks & {:keys [slave-id since limit] :or {limit 100}})Get all completed tasks, optionally filtered by slave or time range.
Options:
Returns: Seq of task maps sorted by completion time (most recent first)
Get all completed tasks, optionally filtered by slave or time range. Options: - :slave-id - Filter by specific slave - :since - Only tasks completed after this timestamp (java.util.Date) - :limit - Maximum number to return (default 100) Returns: Seq of task maps sorted by completion time (most recent first)
(get-recent-claim-history & {:keys [file slave-id since limit] :or {limit 50}})Get recent claim history entries.
CC.6: Tracks file changes made during claim periods for auditing and context propagation.
Options:
Returns: Seq of claim history maps sorted by release time (most recent first)
Get recent claim history entries. CC.6: Tracks file changes made during claim periods for auditing and context propagation. Options: - :file - Filter by specific file path - :slave-id - Filter by specific slave - :since - Only entries after this timestamp (java.util.Date) - :limit - Maximum number to return (default 50) Returns: Seq of claim history maps sorted by release time (most recent first)
(get-slave slave-id)Get a slave by ID.
Returns: Map with slave attributes or nil if not found
Get a slave by ID. Returns: Map with slave attributes or nil if not found
(get-slave-by-kanban-task kanban-task-id)Get the slave that is assigned to a kanban task.
Arguments: kanban-task-id - Kanban task ID to look up
Returns: Map with slave attributes or nil if no slave is assigned to this task
Get the slave that is assigned to a kanban task. Arguments: kanban-task-id - Kanban task ID to look up Returns: Map with slave attributes or nil if no slave is assigned to this task
(get-slave-by-name name)Get a slave by name (fallback lookup).
Used when exact :slave/id match fails. Searches for a slave where :slave/name matches the given identifier. Returns the most recently created slave if multiple matches exist.
Arguments: name - The slave name to search for (e.g., 'github-connector')
Returns: Map with slave attributes or nil if not found
Get a slave by name (fallback lookup). Used when exact :slave/id match fails. Searches for a slave where :slave/name matches the given identifier. Returns the most recently created slave if multiple matches exist. Arguments: name - The slave name to search for (e.g., 'github-connector') Returns: Map with slave attributes or nil if not found
(get-slave-by-name-or-id identifier)Get a slave by ID, with fallback to name lookup and fuzzy keyword matching.
BUG FIX: Resolves agent-id mismatch between hivemind shouts (which may use short IDs like 'ling-wave-fix') and DataScript (which stores full spawn IDs like 'swarm-fix-wave-race-condition-1770230187').
BUG FIX 2: Strips 'agent:' prefix from headless ling auto-shouts. The NATS bridge's auto-shout-agent-event! may pass 'agent:ling-xyz' but DataScript stores the bare 'ling-xyz'. Without stripping, the lookup fails silently and status sync is lost.
Resolution order: 0. Strip 'agent:' prefix if present (headless ling bridge IDs)
Arguments: identifier - Either a slave ID or name
Returns: Map with slave attributes or nil if not found
Get a slave by ID, with fallback to name lookup and fuzzy keyword matching. BUG FIX: Resolves agent-id mismatch between hivemind shouts (which may use short IDs like 'ling-wave-fix') and DataScript (which stores full spawn IDs like 'swarm-fix-wave-race-condition-1770230187'). BUG FIX 2: Strips 'agent:' prefix from headless ling auto-shouts. The NATS bridge's auto-shout-agent-event! may pass 'agent:ling-xyz' but DataScript stores the bare 'ling-xyz'. Without stripping, the lookup fails silently and status sync is lost. Resolution order: 0. Strip 'agent:' prefix if present (headless ling bridge IDs) 1. Exact match on :slave/id 2. Exact match on :slave/name (with prefix stripping) 3. Fuzzy match: keyword overlap between shout ID and spawn IDs (e.g., 'ling-wave-fix' matches 'swarm-fix-wave-race-condition-...' via 'fix'+'wave') Arguments: identifier - Either a slave ID or name Returns: Map with slave attributes or nil if not found
(get-slave-ids-by-project project-id)Get slave IDs for a project (optimized for kill operations).
Arguments: project-id - Project ID to filter by
Returns: Seq of slave ID strings
Get slave IDs for a project (optimized for kill operations). Arguments: project-id - Project ID to filter by Returns: Seq of slave ID strings
(get-slaves-by-project project-id
&
{:keys [include-stale?] :or {include-stale? false}})Get slaves filtered by project-id.
Arguments: project-id - Project ID to filter by
Options: :include-stale? — bypass alive/last-active filter (default false). See get-all-slaves.
Returns: Seq of slave maps belonging to the project
Get slaves filtered by project-id. Arguments: project-id - Project ID to filter by Options: :include-stale? — bypass alive/last-active filter (default false). See get-all-slaves. Returns: Seq of slave maps belonging to the project
(get-slaves-by-status status)Get slaves filtered by status.
Arguments: status - Status to filter by
Returns: Seq of slave maps
Get slaves filtered by status. Arguments: status - Status to filter by Returns: Seq of slave maps
(get-task task-id)Get a task by ID.
Returns: Map with task attributes or nil if not found
Get a task by ID. Returns: Map with task attributes or nil if not found
(get-tasks-for-slave slave-id & [status])Get all tasks for a slave.
Arguments: slave-id - Slave to get tasks for status - Optional status filter
Returns: Seq of task maps
Get all tasks for a slave. Arguments: slave-id - Slave to get tasks for status - Optional status filter Returns: Seq of task maps
(has-conflict? file-path requesting-slave)Check if a file claim would conflict with existing claims.
Arguments: file-path - File to check requesting-slave - Slave wanting to claim (conflicts if different)
Returns: {:conflict? bool :held-by slave-id} or {:conflict? false}
Check if a file claim would conflict with existing claims.
Arguments:
file-path - File to check
requesting-slave - Slave wanting to claim (conflicts if different)
Returns:
{:conflict? bool :held-by slave-id} or {:conflict? false}Trailing keyword options: k v pairs, or a single trailing opts map.
Trailing keyword options: `k v` pairs, or a single trailing opts map.
A slave row projected out of DataScript: refs resolved to ids, no :db/id.
A slave row projected out of DataScript: refs resolved to ids, no :db/id.
A task row: :task/slave resolved to the owning slave id.
A task row: :task/slave resolved to the owning slave id.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |