Page kind: Reference
ref_log#
One ref's moves, newest first: the op_log entries that moved it, each with its op, old and new value, actor and time; a deleted ref lists its moves, and a name that never moved is E_REF_NOT_FOUND. Pass a limit of 20 or less and page on with before, since clients limit long tool results.
- Since
0.11.0- Mutates
- no
- Identity required
- no
- Envelope op
ref_log- Cli command
swarmops ref log- Request type
RefLogReq- Annotations
{"destructiveHint":false,"idempotentHint":true,"openWorldHint":false,"readOnlyHint":true}- Max result chars
null- CLI command
swarmops ref log
Input schema#
arguments is a RefLogReq: swarmops schema RefLogReq prints the type. A field the type does not know is ignored.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
before | integer or null | no | Start below this operation: the page holds the moves of operations numbered less than it, so the last op of a page reads on from there. When omitted, from the newest. | |
limit | integer | no | 50 | The most moves to return: at least 1 (0 is E_INVALID_ARG). |
name | string | yes | The ref. |
JSON Schema#
As tools/list gives it: each $ref replaced by its definition, so that it stands alone.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "`ref_log` (CLI `ref log`): one ref's moves, newest first, a page at a time, as the journal\nrecorded them: the op log filtered to the ref. A deleted ref lists its moves; a name the\njournal records no move of is `E_REF_NOT_FOUND`.",
"properties": {
"before": {
"description": "Start below this operation: the page holds the moves of operations numbered less than\nit, so the last `op` of a page reads on from there. When omitted, from the newest.",
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"limit": {
"default": 50,
"description": "The most moves to return: at least 1 (0 is `E_INVALID_ARG`).",
"format": "uint",
"minimum": 1,
"type": "integer"
},
"name": {
"description": "The ref.",
"type": "string"
}
},
"required": [
"name"
],
"title": "RefLogReq",
"type": "object"
}Annotations#
It only reads the store.
| Annotation | Value | Meaning |
|---|---|---|
destructiveHint | false | True: a tool that changes the store may overwrite or delete what is there, not only add to it. |
idempotentHint | true | True: calling it again with the same arguments changes nothing more. |
openWorldHint | false | True: it reaches beyond a closed set of things. Every tool here stays inside the store. |
readOnlyHint | true | True: the tool does not change its environment, the store. |
Its entry in tools/list carries no _meta.
CLI command#
swarmops ref log runs the same operation and prints the same envelope.
Examples#
{
"id": 25,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"limit": 2,
"name": "release/v1"
},
"name": "ref_log"
}
}{
"id": 25,
"jsonrpc": "2.0",
"result": {
"content": [
{
"text": "{\"api\":1,\"meta\":{\"auth\":\"trust\",\"elapsed_ms\":\"[elapsed_ms]\",\"repo\":\"[tmp]/store\",\"resolved\":{}},\"ok\":true,\"op\":\"ref_log\",\"result\":{\"moves\":[{\"actor\":\"agent/worker-17\",\"at\":\"[at]\",\"new\":\"[c1]\",\"op\":8},{\"actor\":\"agent/worker-17\",\"at\":\"[at]\",\"old\":\"[c1]\",\"op\":7}],\"name\":\"release/v1\",\"truncated\":true}}",
"type": "text"
}
],
"isError": false,
"structuredContent": {
"api": 1,
"meta": {
"auth": "trust",
"elapsed_ms": "[elapsed_ms]",
"repo": "[tmp]/store",
"resolved": {}
},
"ok": true,
"op": "ref_log",
"result": {
"moves": [
{
"actor": "agent/worker-17",
"at": "[at]",
"new": "[c1]",
"op": 8
},
{
"actor": "agent/worker-17",
"at": "[at]",
"old": "[c1]",
"op": 7
}
],
"name": "release/v1",
"truncated": true
}
}
}
}The server ran as swarmops mcp --repo [tmp]/store --as agent/worker-17, after initialize. Recorded by the MCP tests. A name in square brackets, such as [tmp] or [c1], stands for what differs from run to run: the test's temporary directory, an id, a time, the version.
Return information#
A tool result: the envelope, whose op is ref_log, as structuredContent and again as the text of its one content block. isError is true exactly when the envelope's ok is false. On success the envelope's result is what swarmops ref log returns.
Errors#
A failed call is a tool result with isError: true; the envelope's error.code is one of the error codes.
- E_INVALID_ARG: arguments that do not fit
RefLogReq, a field named twice among them included, or that break one of the server's own rules. - E_NOT_A_REPO: the server's store is not there; the server serves on.
- E_INTERNAL: the operation panicked, a bug.
Then the errors of the operation, as swarmops ref log lists them.