op_log#

The store's operations, newest first: each write transaction, numbered as undo takes it, with its kind, the changesets it recorded and the refs it moved; pass a limit of 20 or less and page on with before, since clients limit long tool results.

Metadata

Since: 0.1.0
Mutates: no
Identity required: no
Envelope op: op_log
Cli command: swarmops op log
Request type: OpLogReq
Annotations: {"destructiveHint":false,"idempotentHint":true,"openWorldHint":false,"readOnlyHint":true}
Max result chars: null
CLI command: swarmops op log

Input schema#

arguments is a OpLogReq: swarmops schema OpLogReq 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 ones 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 operations to return: at least 1 (0 is `E_INVALID_ARG`).
`max_changesets`	integer	no	`20`	The most changesets to list for each operation; `changesets_total` counts them all.

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": "`op_log` (CLI `op log`): the store's operations, newest first, a page at a time. An operation\nis one write transaction: a frame of the journal, numbered from 0 in commit order.",
  "properties": {
    "before": {
      "description": "Start below this operation: the page holds the ones numbered less than it, so the last\n`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 operations to return: at least 1 (0 is `E_INVALID_ARG`).",
      "format": "uint",
      "minimum": 1,
      "type": "integer"
    },
    "max_changesets": {
      "default": 20,
      "description": "The most changesets to list for each operation; `changesets_total` counts them all.",
      "format": "uint",
      "minimum": 0,
      "type": "integer"
    }
  },
  "title": "OpLogReq",
  "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 op log runs the same operation and prints the same envelope.

Examples#

{
  "id": 19,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "limit": 2
    },
    "name": "op_log"
  }
}

{
  "id": 19,
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "text": "{\"ok\":true,\"op\":\"op_log\",\"api\":1,\"result\":{\"ops\":[{\"op\":6,\"kind\":\"ref_move\",\"changesets\":[],\"changesets_total\":0,\"ref_moves\":[{\"name\":\"release/v1\",\"old\":\"[c1]\",\"actor\":\"agent/worker-17\",\"at\":\"[at]\"}]},{\"op\":5,\"kind\":\"ref_move\",\"changesets\":[],\"changesets_total\":0,\"ref_moves\":[{\"name\":\"release/v1\",\"new\":\"[c1]\",\"actor\":\"agent/worker-17\",\"at\":\"[at]\"}]}],\"truncated\":true},\"meta\":{\"repo\":\"[tmp]/store\",\"elapsed_ms\":\"[elapsed_ms]\",\"resolved\":{},\"auth\":\"trust\"}}",
        "type": "text"
      }
    ],
    "isError": false,
    "structuredContent": {
      "api": 1,
      "meta": {
        "auth": "trust",
        "elapsed_ms": "[elapsed_ms]",
        "repo": "[tmp]/store",
        "resolved": {}
      },
      "ok": true,
      "op": "op_log",
      "result": {
        "ops": [
          {
            "changesets": [],
            "changesets_total": 0,
            "kind": "ref_move",
            "op": 6,
            "ref_moves": [
              {
                "actor": "agent/worker-17",
                "at": "[at]",
                "name": "release/v1",
                "old": "[c1]"
              }
            ]
          },
          {
            "changesets": [],
            "changesets_total": 0,
            "kind": "ref_move",
            "op": 5,
            "ref_moves": [
              {
                "actor": "agent/worker-17",
                "at": "[at]",
                "name": "release/v1",
                "new": "[c1]"
              }
            ]
          }
        ],
        "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.

Details#

Each entry is one write transaction of the store, newest first, numbered as undo takes it, with its kind, the changesets it recorded and the refs it moved. Pass a limit of 20 or less and page on with before.

Return information#

A tool result: the envelope, whose op is op_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 op 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 OpLogReq, 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 op log lists them.