golem-debug-agent-history

name	golem-debug-agent-history
description	Querying the operation log. Use when dumping or searching the oplog, or debugging agent behavior from its recorded history.

Debugging Agent History

Both golem and golem-cli can be used — all commands below work with either binary.

The <AGENT_ID> format depends on the agent's language — refer to the language-specific invocation skills for the exact syntax.

To check agent metadata and status, load the golem-get-agent-metadata skill. To revert agent state, load the golem-undo-agent-state skill.

agent oplog — Query the Operation Log

Stream or search an agent's operation log (oplog). The oplog records every operation the agent has performed — invocations, side effects, persistence boundaries, etc.

golem agent oplog <AGENT_ID> [OPTIONS]

Flags

Flag	Description
--from <INDEX>	Start from a specific oplog entry index. Cannot be combined with --query.
--query <LUCENE_QUERY>	Search oplog entries using a Lucene query string. Cannot be combined with --from.

If neither --from nor --query is provided, the entire oplog is streamed.

Output

Each text entry is printed with its index (e.g. #00042:) followed by a labeled header and fields. In structured formats (json, yaml, toon), agent oplog emits one output document per entry with $type: "agent.oplog", index, and entry; parse stdout as a sequence of documents, not as one array or object. The entry types rendered are:

Entry	Description
CREATE	Agent creation — shows timestamp, component revision, env vars, parent, initial plugins
CALL	Host function call — shows function name, input, and result
INVOKE	Agent method invocation started — shows method name, idempotency key, and input
INVOKE COMPLETED	Invocation finished — shows consumed fuel and result
ENQUEUED INVOCATION	Pending method invocation — shows method name and idempotency key
ENQUEUED AGENT INITIALIZATION	Pending agent initialization
ENQUEUED SAVE SNAPSHOT / ENQUEUED LOAD SNAPSHOT	Pending snapshot operations
ENQUEUED MANUAL UPDATE	Pending manual update — shows target revision
SUSPEND	Agent suspended
ERROR	Error with retry info — shows retry-from index and error details
LOG	Log entry — shows level and message
GROW MEMORY	Memory growth — shows size increase
CREATE RESOURCE / DROP RESOURCE	Resource lifecycle — shows resource id
BEGIN ATOMIC REGION / END ATOMIC REGION	Atomic operation boundaries
BEGIN REMOTE WRITE / END REMOTE WRITE	Remote write boundaries
ENQUEUED UPDATE / SUCCESSFUL UPDATE / FAILED UPDATE	Component update lifecycle
ACTIVATE PLUGIN / DEACTIVATE PLUGIN	Plugin lifecycle — shows plugin name, version, priority
REVERT	Oplog revert — shows target oplog index
CANCEL INVOCATION	Cancelled pending invocation — shows idempotency key
START SPAN / FINISH SPAN / SET SPAN ATTRIBUTE	Tracing span operations
CHANGE PERSISTENCE LEVEL	Persistence level change
BEGIN REMOTE TRANSACTION / COMMITTED REMOTE TRANSACTION / ROLLED BACK REMOTE TRANSACTION	Remote transaction lifecycle
SNAPSHOT	Snapshot data — shows mime type and data (JSON or binary size)
OPLOG PROCESSOR CHECKPOINT	Plugin oplog processor checkpoint — shows plugin, target agent, confirmed/sending indices
SET RETRY POLICY / REMOVE RETRY POLICY	Retry policy changes
RESTART	Agent restart
INTERRUPTED / EXITED	Agent interrupted or exited
NOP	No-operation marker
JUMP	Oplog jump — shows from/to indices
STORAGE USAGE UPDATE	Filesystem storage usage change

Examples

Stream the full oplog:

golem agent oplog <AGENT_ID>

Dump starting from entry 100:

golem agent oplog <AGENT_ID> --from 100

Search for specific entries:

golem agent oplog <AGENT_ID> --query "error"