log#

History along first parents, newest first, from main unless rev says otherwise; pass a limit of 100 or less and page on with the cursor, since clients limit long tool results.

Metadata

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

Input schema#

arguments is a LogReq: swarmops schema LogReq prints the type. A field the type does not know is ignored.

Field	Type	Required	Default	Description
`cursor`	string or null	no		Resume a log: the previous page's `cursor`. Pass it back exactly as returned; do not construct it (cursors are opaque). This page continues from the first parent of the changeset it names, and `rev` is not used.
`limit`	integer	no	`50`	The most entries to return: at least 1 (0 is `E_INVALID_ARG`).
`paths`	array of string	no		Only the changesets that change one of these paths: a file (its content or kind, or whether it is there), or a directory and anything below it; one trailing `/` is taken. Omitted or empty for every changeset.
`rev`	string or null	no		Where to start; `main` when omitted.

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": "`log`: history along first parents, a page at a time.",
  "properties": {
    "cursor": {
      "description": "Resume a log: the previous page's `cursor`. Pass it back exactly as returned; do not\nconstruct it (cursors are opaque). This page continues from the first parent of the\nchangeset it names, and `rev` is not used.",
      "type": [
        "string",
        "null"
      ]
    },
    "limit": {
      "default": 50,
      "description": "The most entries to return: at least 1 (0 is `E_INVALID_ARG`).",
      "format": "uint",
      "minimum": 1,
      "type": "integer"
    },
    "paths": {
      "description": "Only the changesets that change one of these paths: a file (its content or kind, or\nwhether it is there), or a directory and anything below it; one trailing `/` is taken.\nOmitted or empty for every changeset.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "rev": {
      "anyOf": [
        {
          "description": "A revision as the caller wrote it, for the store to resolve: a ref name (`main`,\n`release/1.2`), a full 64-hex changeset id or a unique prefix of at least 12 hex digits,\noptionally followed by `~N` for the N-th first-parent ancestor.",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Where to start; `main` when omitted."
    }
  },
  "title": "LogReq",
  "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 log runs the same operation and prints the same envelope.

Examples#

{
  "id": 14,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "rev": "main"
    },
    "name": "log"
  }
}

{
  "id": 14,
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "text": "{\"ok\":true,\"op\":\"log\",\"api\":1,\"result\":{\"entries\":[{\"id\":\"[landed]\",\"parents\":[\"[theirs]\"],\"author_agent\":\"agent/worker-17\",\"created_at\":\"[created_at]\",\"title\":\"change f\"},{\"id\":\"[theirs]\",\"parents\":[\"[c1]\"],\"author_agent\":\"agent/worker-17\",\"created_at\":\"[created_at]\",\"title\":\"add docs\"},{\"id\":\"[c1]\",\"parents\":[],\"author_agent\":\"agent/worker-17\",\"created_at\":\"[created_at]\",\"title\":\"first\"}],\"truncated\":false},\"meta\":{\"repo\":\"[tmp]/store\",\"elapsed_ms\":\"[elapsed_ms]\",\"resolved\":{\"main\":\"[landed]\"},\"auth\":\"trust\"}}",
        "type": "text"
      }
    ],
    "isError": false,
    "structuredContent": {
      "api": 1,
      "meta": {
        "auth": "trust",
        "elapsed_ms": "[elapsed_ms]",
        "repo": "[tmp]/store",
        "resolved": {
          "main": "[landed]"
        }
      },
      "ok": true,
      "op": "log",
      "result": {
        "entries": [
          {
            "author_agent": "agent/worker-17",
            "created_at": "[created_at]",
            "id": "[landed]",
            "parents": [
              "[theirs]"
            ],
            "title": "change f"
          },
          {
            "author_agent": "agent/worker-17",
            "created_at": "[created_at]",
            "id": "[theirs]",
            "parents": [
              "[c1]"
            ],
            "title": "add docs"
          },
          {
            "author_agent": "agent/worker-17",
            "created_at": "[created_at]",
            "id": "[c1]",
            "parents": [],
            "title": "first"
          }
        ],
        "truncated": false
      }
    }
  }
}

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#

History runs along first parents, newest first, from main unless rev names another start. Pass a limit of 100 or less and page on with the cursor the result gives. Each entry's id is a full changeset id, which ref_set, ref_delete and commit with advance take.

Return information#

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