Read a single entry from the shared blackboard by key. Read-only — never modifies the blackboard. Returns {ok:true, key, value, sourceAgent, timestamp} when found, or {ok:true, key, value:null} when the key does not exist or has expired. Returns {ok:false, error:"..."} if the blackboard is unavailable. key uses the same namespaced format as blackboard_write (e.g. "task:analysis:q3"); agent_id is used for scoped access checks and audit logging. Use when you know the exact key; call blackboard_list with a prefix filter first if you need to discover available keys.

Write a JSON-encoded value to the shared blackboard under the given key. Overwrites any existing entry for that key — TTL is also replaced (or removed if omitted). Not idempotent: each call records a new timestamp and sourceAgent. Returns {ok:true, key, value, sourceAgent, timestamp} on success. Returns {ok:false, error:"..."} if value is not valid JSON, agent_id is missing, or the agent token is rejected. value must be a valid JSON string (use JSON.stringify on objects); ttl sets expiry in seconds — omit for a persistent entry; agent_token is required only if the target key is protected. Use namespaced keys (e.g. "task:result:q3") to avoid collisions; confirm with blackboard_read immediately if the consumer agent is already polling.

List all active (non-expired) keys on the shared blackboard, optionally filtered by a key prefix. Read-only — no side effects. Returns {ok:true, keys:["..."], count}. Returns {ok:false, error:"..."} if the blackboard is unavailable. All non-expired keys are returned in one response — on large blackboards use a narrow prefix filter to reduce payload size. Use before blackboard_read when you do not know the exact key name; filter with a prefix such as "task:" to scope results to a specific namespace.

Remove an entry from the shared blackboard by key. Returns {ok:true, deleted:true, key} if found and removed; {ok:true, deleted:false, key} if the key was absent or already expired. Returns {ok:false, error:"..."} if the agent token is rejected or the blackboard is unavailable. key must use the same namespaced format used at write time (e.g. "task:result:q3"); agent_token is required only if the entry was written with a token — omit it for unprotected keys. Call blackboard_exists first to confirm the key is present before deletion.

Check whether a specific key is present and not expired on the shared blackboard. Read-only — no side effects and never modifies state. Returns {ok:true, exists:true} or {ok:true, exists:false}. Returns {ok:false, error:"..."} if the blackboard is unavailable. key must use the same namespaced format as blackboard_read/write/delete (e.g. "task:result:q3"); agent_id is used for scoped access checks. Prefer over blackboard_read when only checking presence — lighter-weight and avoids fetching the full value.

Get a read-only snapshot of the global FederatedBudget: ceiling, total spent, remaining tokens, and per-agent spend breakdown. Never modifies budget state. Returns {ok:true, ceiling, spent, remaining, perAgent:{agentId:tokensSpent}}. Returns {ok:false, error:"Budget not available"} if no budget is configured. agent_id is recorded in the audit log only — it does not filter results. Call before budget_spend to check available capacity; use budget_get_log for a full timestamped transaction history.

Deduct tokens from the global FederatedBudget on behalf of an agent. Returns {ok:true, allowed:true, spent, remaining} when approved, or {ok:true, allowed:false, deniedReason, remaining} when the ceiling would be exceeded. Returns {ok:false, error:"..."} if tokens is not a positive integer. tokens represents the estimated cost of the upcoming LLM call — pass the expected usage before invoking the model; agent_id is tracked individually in the spend log and reported by budget_status. Call budget_status first to check remaining balance; never attempt an LLM call after receiving allowed:false.

Reset all agent spend counters to zero while preserving the ceiling. Returns {ok:true, reset:true, ceiling} on success. Returns {ok:false, error:"confirm must be "yes""} if the confirm parameter is not "yes" — this guard prevents accidental resets. Do not reset mid-task if other agents are actively spending — use only at the start of a new task cycle or after all agents have finished. Call budget_status before and after to verify the reset took effect.

Dynamically change the global token ceiling for all agents. Returns {ok:true, ceiling, previous} on success. Returns {ok:false, error:"..."} if ceiling is not a positive number. Changes take effect immediately — lowering below current spend will deny all future budget_spend calls until counters are reset via budget_reset; raising allows previously blocked agents to resume. ceiling must be a positive integer (total token budget across all agents); agent_id is recorded in the audit log. Avoid lowering the ceiling while agents are actively running; call budget_status first to check the current spend level.

Return a chronological list of all token spend transactions. Read-only — never modifies budget state. Returns {ok:true, log:[{agentId, tokens, timestamp}], count}. Returns {ok:false, error:"..."} if the budget is not available. Use limit to cap the number of entries returned (default 50); prefer budget_status for a summary view. Useful for auditing which agents consumed the most tokens in a task cycle.

Issue a new HMAC/Ed25519-signed security token for an agent scoped to a resource type and permission level. Each call produces a unique token with a fixed expiry managed by the token manager. Returns {ok:true, token:{tokenId, agentId, resourceType, scope, issuedAt, expiresAt, signature}}. Returns {ok:false, error:"..."} if the token manager is unavailable. resource_type is a free-form string identifying the protected resource (e.g. "FILE_SYSTEM", "BLACKBOARD", "API"); scope controls permission level (e.g. "read", "write", "admin"). Pass the full returned token object as token_json to token_validate; call token_revoke with the tokenId when access should be withdrawn.

Verify a security token's HMAC/Ed25519 signature, confirm it has not expired, and check it has not been revoked. Read-only — never modifies token state. Returns {ok:true, valid:true, token:{...}} if the token passes all checks, or {ok:true, valid:false, reason:"..."} if it fails any check (reason indicates which check failed: "invalid_signature", "expired", or "revoked"). Returns {ok:false, error:"..."} if token_json is not valid JSON. Call before granting access to any protected resource; use token_revoke to invalidate a token that should no longer be trusted.

Permanently revoke a security token by its tokenId. Returns {ok:true, revoked:true, tokenId} on success. Returns {ok:false, error:"..."} if the token manager is unavailable. Revocation is immediate and irreversible — the token will fail token_validate on all future attempts. token_id is the tokenId field from the token object returned by token_create; reason is optional but written to the audit log and aids security review. Use when an agent session ends, a permission grant expires by policy, or a token may have been compromised.

Search the append-only audit log with optional filters. Read-only — never modifies the log. Returns {ok:true, entries:[{timestamp, agentId, eventType, outcome, details}], count}. Returns {ok:false, error:"..."} if the log file cannot be read. All filters are optional and combinable; use limit to cap results and avoid large payloads on busy systems (default 100). Use audit_tail for the most recent N entries without filtering; use this tool for compliance review, debugging, or verifying permission grant history.

Return the N most recent audit log entries in ascending timestamp order (oldest-first within the tail window). Read-only — no side effects. Returns {ok:true, entries:[{timestamp, agentId, eventType, outcome, details}], count}. Returns {ok:false, error:"..."} if the log file cannot be read. n defaults to 20 and is capped at 500 — use a larger value only when debugging a busy system. Prefer audit_query for filtered searches by agent, event type, outcome, or time range; use this tool for real-time monitoring or quick post-action verification.

Read one or all live orchestrator configuration values. Returns {ok:true, key, value} for a single key, or {ok:true, config:{...}} for all keys. Returns {ok:false, error:"Unknown config key: "..." Known keys: ..."} if the key is not recognised. Call without a key to discover available config names; use config_set to update values at runtime.

Update a live orchestrator configuration value at runtime. Changes take effect immediately for all subsequent operations and are written to the audit log — there is no undo. Returns {ok:true, key, value, previous} on success. Returns {ok:false, error:"Unknown config key..."} with a list of valid keys if the key is not recognised, or {ok:false, error:"..."} if value is not valid JSON. Call config_get first to read the current value and confirm the key name before updating.

List all agents registered with the orchestrator and their current status. Read-only — no side effects. Returns {ok:true, agents:[{agentId, status, lastSeen, taskCount}], count}. Returns {ok:false, error:"..."} if the registry is unavailable. status_filter accepts one of: "active", "idle", "stopped", or "error" — omit to return all statuses. Call before agent_spawn or agent_stop to confirm the target agent exists and has the expected status.

Write a task record to the blackboard to dispatch work to a named agent on its next poll cycle. Returns {ok:true, taskKey, agentId, instruction, written:true} on success. Returns {ok:false, error:"..."} if agent_id, task_key, or instruction is missing, or if payload_json is malformed. Call agent_list first to confirm the target agent is registered; verify the task was recorded with blackboard_read after spawning.

Signal a running agent to stop by writing a stop record to the blackboard and marking it stopped in the registry. Returns {ok:true, agentId, reason, stopped:true}. Returns {ok:false, error:"..."} if agent_id is missing. agent_id must match a value returned by agent_list; reason is optional but written to the audit log under eventType "agent_stop" and helps trace the cause of the stop. The agent observes the stop signal on its next poll — it does not terminate immediately. Call agent_list first to confirm the agent is currently active.

Advance a named FSM (Finite State Machine) to a new state and record the transition on the blackboard. Transitions are irreversible via this tool — new_state is written directly without validating against a predefined state graph, so the caller must ensure the transition is valid. Returns {ok:true, fsmId, transition:{from, to}, blackboardWritten:true} on success. Returns {ok:false, error:"..."} if fsm_id, new_state, or agent_id is missing, or if metadata_json is not valid JSON. Avoid concurrent transitions to the same FSM from multiple agents; call orchestrator_info first to read the current FSM state before transitioning.

Return a full health snapshot of the orchestrator: version, config values, registered agent count, blackboard key count, and system uptime. Returns {ok:true, version, config:{...}, agentCount, blackboardKeyCount, uptime}. This tool always succeeds — it never returns {ok:false}. Use as the first call when connecting to confirm the server is healthy and to discover current config before calling config_get or agent_list.

Assemble a token-budgeted, relevance-ranked context brief from the shared blackboard for a given task. Use this INSTEAD of blackboard_list + many blackboard_read calls: it returns only the entries most relevant to your task, ranked by semantic/lexical relevance, recency (half-life decay), and namespace affinity, assembled position-aware (strongest items first and last) under a hard token budget. Read-only — never modifies the blackboard. Returns {ok:true, text, used_tokens, budget_tokens, utilization, included:[{key,score,tokens}], excluded:[{key,reason}]}. The text field is ready to use as working context. Entries past their TTL are excluded automatically.

Search the shared blackboard for entries relevant to a query and return the top-K ranked matches. Use this instead of blackboard_list when you need relevant keys rather than all keys — it keeps noise out of your context window. Read-only. Ranks semantically when the server has an embedding provider wired, otherwise by deterministic lexical overlap (response includes which mode was used). Returns {ok:true, mode, results:[{key, score, snippet, sourceAgent}], count}. Follow up with blackboard_read for the full value of a specific key.