@gmickel/gno 2.5.1 → 2.7.0

package/spec/mcp.md

@@ -153,7 +153,7 @@ the resident gateway applies one profile to every connected client.
 
 | Profile          | Without `--enable-write`                                                                              | With `--enable-write`                                   |
 | ---------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
-| `full` (default) | Every read tool below (34)                                                                            | Every read tool plus every write tool (53)              |
+| `full` (default) | Every read tool below (37)                                                                            | Every read tool plus every write tool (59)              |
 | `core`           | `gno_query`, `gno_search`, `gno_get`, `gno_multi_get`, `gno_context`, `gno_changes`, `gno_recall` (7) | The 7 read tools plus `gno_capture`, `gno_remember` (9) |
 
 Both lists are exact: `core` advertises nothing else, and `full` is byte-for-byte
@@ -232,6 +232,10 @@ the core memory service acquires the same `.mcp-write.lock` lease for every
 memory write, so an MCP remember and a CLI writer serialise on one lease. A
 lease that stays busy past the wait window returns `MEMORY_WRITE_LEASE_BUSY`.
 
+With a `requestId`, `gno_capture` and `gno_remember` admit the request under
+this same lease; there is no second lock. A request whose earlier attempt
+still holds the lease past the wait window returns `REQUEST_PENDING`.
+
 ### Resident Streamable HTTP boundary
 
 `gno serve` and `gno daemon` mount the same stateful MCP surface at `/mcp`.
@@ -263,6 +267,15 @@ Because `gno serve` shares this listener with its Web UI and REST API, it
 remains loopback-only. Use the headless `gno daemon` command for an explicitly
 authenticated non-loopback MCP listener.
 
+HTTP MCP results never carry a host absolute path, whatever the peer zone:
+every `absPath` field (`source.absPath` on search/query/ask/get/multi-get
+results, top-level `absPath` on `gno_capture` and `gno_remember` receipts,
+`similar[].absPath`, peek `recent[].absPath`) is removed from both
+`structuredContent` and the text content, and a resource header's `source:`
+line names the collection-relative path. Callers address documents by `uri`
+and `relPath`. Stdio callers keep host paths. The field inventory lives in
+[docs/API.md](../docs/API.md#host-paths-and-remote-callers).
+
 HTTP MCP remains read-only unless `gateway.enableWrite: true` or
 `--mcp-enable-write` is explicitly set. Bearer authentication alone does not
 authorize mutation. Unauthorized calls to write tools fail with HTTP 403 before
@@ -1339,6 +1352,21 @@ counters; it never claims attachment to another process.
     "totalDocuments": 150,
     "totalChunks": 800,
     "embeddingBacklog": 0,
+    "vectorPartitions": [
+      {
+        "id": "3f2a9c1b2d4e...",
+        "model": "hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf",
+        "dimensions": 1024,
+        "state": "active",
+        "legacy": false,
+        "retrieval": true,
+        "droppable": false,
+        "owners": 500,
+        "provenance": "CUDA, Bun 1.4.2",
+        "compatibleRuntimes": ["CUDA, Bun 1.4.2", "CPU, Bun 1.3.14"],
+        "incompatibleRuntimes": []
+      }
+    ],
     "contentTypeBoost": {
       "rulesFingerprint": "<sha256>",
       "rules": [{ "id": "decision", "searchBoost": 2 }]
@@ -1348,6 +1376,16 @@ counters; it never claims attachment to another process.
 }
 ```
 
+`vectorPartitions` (omitted when none exist) lists the embedding model's
+vector partitions; `embeddingBacklog` and per-collection embedded counts use
+the one with `retrieval: true`, the partition this server process's queries
+read under the same selection rule as retrieval (`vectorRuntime` reports
+`vectors`, `unavailable` with a reason, or `unresolved` before its first query
+or embed). `droppable` marks what `gno vec drop` accepts. Other partitions carry `state`, `owners` and a
+readable `provenance`; `compatibleRuntimes` names the runtimes that read a
+partition and `incompatibleRuntimes` names runtimes measured unable to
+reproduce the stored vectors, whose queries use lexical retrieval only.
+
 `contentTypeBoost` is a redacted ranking-status projection. It exposes only
 normalized IDs/factors plus the rules fingerprint; path prefixes are never
 returned.
@@ -1531,6 +1569,10 @@ Create a new document in a collection (write-enabled).
         "capturedAt": { "type": "string", "format": "date-time" },
         "externalId": { "type": "string" }
       }
+    },
+    "requestId": {
+      "type": "string",
+      "description": "Optional caller request ID (1-128 of A-Z a-z 0-9 . _ : -). Reuse the same ID when retrying the same write after a lost response; a new intent needs a new ID"
     }
   },
   "required": ["collection"]
@@ -1585,6 +1627,13 @@ Create a new document in a collection (write-enabled).
   writing
 - Writes run under the MCP write lock and are only registered when the server
   starts with `--enable-write` or `GNO_MCP_ENABLE_WRITE=1`
+- `requestId` (optional) makes a retry of the same call safe; look it up with
+  [`gno_request_status`](#gno_request_status). Semantics:
+  `docs/guides/retries-and-request-ids.md`
+- With a `requestId`, the result adds
+  `request: { requestId, status: "committed", replayed, committedAt }` and the
+  text output adds `Request: <id> committed` (`(replayed)` on a replay). The
+  field is absent when no `requestId` was sent
 
 **Output Schema:** `gno://schemas/mcp-capture-result@1.0`, compatible with the
 shared `gno://schemas/capture-receipt@1.0` contract.
@@ -1651,6 +1700,10 @@ file edits update existing notes, `gno_remember` upserts a fact.
     "source": {
       "type": "string",
       "description": "Free-text evidence for the fact"
+    },
+    "requestId": {
+      "type": "string",
+      "description": "Optional caller request ID (1-128 of A-Z a-z 0-9 . _ : -). Reuse the same ID when retrying the same write after a lost response; a new intent needs a new ID"
     }
   },
   "required": ["text", "collection", "scopes"]
@@ -1663,11 +1716,14 @@ file edits update existing notes, `gno_remember` upserts a fact.
   fact, nothing written
 - `outcome: "candidates"` — likely matches and no `decision`; `candidates[]`
   carry `similarity` and `match` (`exact` | `likely` | `weak`), nothing written
-- `outcome: "added" | "superseded"` — `record`, `absPath`, and
+- `outcome: "added" | "superseded"` — `record`, `absPath` (stdio only), and
   `sync.status` (`completed` before the call returns; the fact is lexically
   searchable)
 - `matching` — `mode` (`semantic` | `lexical`), `threshold`, and
   `semanticUnavailable` when lexical matching was used
+- `request` — present on `existing`, `added`, and `superseded` results when a
+  `requestId` was sent: `{ requestId, status: "committed", replayed,
+committedAt }`
 
 **Notes:**
 
@@ -1682,6 +1738,10 @@ file edits update existing notes, `gno_remember` upserts a fact.
 - The core service holds the shared write lease for the write and lexical
   sync; the MCP adapter takes no lock of its own
 - Identity mapping is the same as `gno_recall`
+- `requestId` requires `decision` (`add` or `supersede`); a candidates-only
+  call with a `requestId` returns `REQUEST_ID_INVALID`. `caller`, `session`,
+  and the MCP session are not part of the request identity. Semantics:
+  `docs/guides/retries-and-request-ids.md`
 - Annotations: `readOnlyHint: false`, `destructiveHint: false`,
   `idempotentHint: false`
 
@@ -1693,10 +1753,178 @@ file edits update existing notes, `gno_remember` upserts a fact.
 `MEMORY_PREDECESSOR_NOT_FOUND`, `MEMORY_PREDECESSOR_HASH_MISMATCH`,
 `MEMORY_SUPERSEDE_CONFLICT`, `MEMORY_FENCED_REPLAY`, `MEMORY_FENCED_DERIVED`,
 `MEMORY_WRITE_LEASE_BUSY`, `MEMORY_SYNC_FAILED`,
-`MEMORY_SUPERSEDE_PROJECTION_FAILED`, `MEMORY_QUERY_FAILED`.
+`MEMORY_SUPERSEDE_PROJECTION_FAILED`, `MEMORY_QUERY_FAILED`, and the
+`REQUEST_*` codes listed under [`gno_request_status`](#gno_request_status).
 
 ---
 
+### gno_request_status
+
+Look up a `requestId` sent with `gno_capture` or `gno_remember` before retrying
+the write (write-enabled server).
+
+The tool is read-only but registered only when the server starts with
+`--enable-write` (or `GNO_MCP_ENABLE_WRITE=1`), and only on the `full` tool
+profile; `core` does not advertise it.
+
+**Input Schema:**
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "requestId": {
+      "type": "string",
+      "description": "Request ID previously sent with gno_capture or gno_remember"
+    }
+  },
+  "required": ["requestId"]
+}
+```
+
+**Response (`structuredContent`):** `gno://schemas/request-status@1.0`
+
+```json
+{
+  "requestId": "0f8e5c1a-3c1e-4d0b-9a57-2f4f3b8f2c11",
+  "status": "committed",
+  "operation": "capture",
+  "createdAt": "2026-09-24T08:00:00.000Z",
+  "updatedAt": "2026-09-24T08:00:00.120Z",
+  "result": {
+    "uri": "gno://notes/inbox/2026-09-24/capture-3f9c.md",
+    "docid": "#a1b2c3",
+    "contentHash": "<sha256>"
+  }
+}
+```
+
+- `status`: `pending` | `committed` | `expired` | `not_found`.
+- `operation`: `capture` | `remember` | `document.update`. `result` appears
+  only for `committed` and carries `uri`, `docid`, and `contentHash` (or
+  `sourceHash` for a document update). Never note or fact content. A
+  `not_found` result has only `requestId` and `status`.
+- Text output: `Request:`, `Status:`, and, when present, `Operation:`,
+  `Updated:`, `URI:` lines.
+
+**Namespaces:** stdio uses the local-owner namespace shared with the CLI, SDK,
+and `gno serve` REST; resident Streamable HTTP uses the authorized identity
+(loopback, or the configured bearer token), not the MCP session. Visibility
+and token-rotation rules: `docs/guides/retries-and-request-ids.md`.
+
+**Annotations:** `readOnlyHint: true`, `destructiveHint: false`,
+`idempotentHint: true`, `openWorldHint: false`.
+
+**Request error codes** (on `gno_capture`, `gno_remember`, and this tool; tool
+error text `CODE: message`, `structuredContent.error` = `CODE`):
+`REQUEST_ID_INVALID`, `REQUEST_ID_CONFLICT`, `REQUEST_EXPIRED`,
+`REQUEST_PENDING`, `REQUEST_RECOVERY_CONFLICT`, `REQUEST_CAPACITY_EXHAUSTED`,
+`REQUEST_LEDGER_UNAVAILABLE`. Meanings:
+`docs/guides/retries-and-request-ids.md#errors`.
+
+---
+
+### gno_sessions_status
+
+Read-only status of a session-archive server (a server started with the
+dedicated archive `--config` and `--index`). Registered with the `full`
+profile only; not part of `core`.
+
+**Input Schema:** `{}` (no arguments).
+
+**Output:** the shared `sessions-status` schema
+(`spec/output-schemas/sessions-status.schema.json`): archive collections with
+thread counts and, per owner-registered source, its ID, harness, destination
+collection, availability, unit counts (complete, incomplete, failed,
+pending), `sourceUnavailable`, `staleParser` and last import time, and the
+`automation` block (daemon state, per-profile state, hook and schedule
+switches, pending and running work, last run, last success, next due time,
+recovery action). The result contains no host paths.
+
+**Errors:** `SESSIONS_NOT_CONFIGURED` when the server's config has no
+`sessions` block.
+
+### gno_sessions_import
+
+Manually import one owner-registered session source into the archive and sync
+the changed archive files (write-enabled; `full` profile only). There is no
+MCP discovery tool: remote clients never learn host directories.
+
+**Input Schema:**
+
+```json
+{
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["sourceId"],
+  "properties": {
+    "sourceId": {
+      "type": "string",
+      "description": "ID of an owner-registered session source (see gno_sessions_status)"
+    },
+    "dryRun": {
+      "type": "boolean",
+      "description": "Parse and report without writing archive or index state"
+    },
+    "limit": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 100000,
+      "description": "Maximum changed units processed this call; the rest are deferred"
+    }
+  }
+}
+```
+
+Unknown keys (for example `paths`) are rejected: MCP imports name a
+registered source ID only.
+
+**Output:** the shared `sessions-import-receipt` schema. Partial imports
+(`status: "partial"`) stay visible and are retried by the next call; the
+receipt carries no host paths or session content.
+
+Registered only with `--enable-write` (like `gno_capture` and
+`gno_remember`); without it the tool is not advertised. A dispatch while
+writes are disabled returns `WRITE_DISABLED`.
+
+### gno_sessions_automation_run
+
+Run one owner-configured automation profile now through the manual importer
+and record the outcome in automation status (write-enabled; `full` profile
+only). It cannot enable hooks or schedules, add sources, or change
+destinations; those stay local-owner operations.
+
+**Input Schema:**
+
+```json
+{
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["profileId"],
+  "properties": {
+    "profileId": {
+      "type": "string",
+      "description": "ID of an owner-configured automation profile (see gno_sessions_status)"
+    }
+  }
+}
+```
+
+**Output:** the shared `sessions-automation-run` schema
+(`spec/output-schemas/sessions-automation-run.schema.json`): `ran`,
+`outcome` (`complete`, `up_to_date`, `partial`, `failed`, or `not_started`),
+`reason`, `pending`, and one `sessions-import-receipt` per source. No host
+paths or session content.
+
+**Errors:** `SESSIONS_UNKNOWN_PROFILE`, `SESSIONS_NOT_CONFIGURED`,
+`WRITE_DISABLED`; unknown keys are rejected.
+
+**Errors:** `SESSIONS_UNKNOWN_SOURCE`, `SESSIONS_SOURCE_UNAVAILABLE`,
+`SESSIONS_UNKNOWN_COLLECTION`, `SESSIONS_INVALID_INPUT`,
+`SESSIONS_NOT_CONFIGURED`; `SESSIONS_BUSY` when another import holds the
+archive lock; `SESSIONS_RUNTIME_FAILURE` (fixed, path-free message) for filesystem or
+index failures.
+
 ### gno_list_tags
 
 List all tags with document counts.
@@ -2721,7 +2949,7 @@ Content includes optional header comment:
 |-------|-------------|
 | URI | Full gno:// URI |
 | docid | Document ID |
-| source | Absolute path to source file |
+| source | Absolute path to source file (stdio); collection-relative path over HTTP |
 | mime | Source file MIME type |
 | language | Document language hint (if available) |
 
@@ -2793,6 +3021,8 @@ Resource errors use standard MCP error responses.
 - `MEMORY_*` — Memory contract errors from `gno_recall` / `gno_remember`;
   the stable code set is `MemoryErrorCode` in `src/core/memory.ts` and each
   tool section above lists the codes it returns
+- `REQUEST_*` — Request ID errors from `gno_capture`, `gno_remember`, and
+  `gno_request_status`; see [`gno_request_status`](#gno_request_status)
 
 ---
 

package/spec/output-schemas/ask.schema.json

@@ -322,7 +322,7 @@
           "properties": {
             "absPath": {
               "type": "string",
-              "description": "Absolute path (included with --source or in MCP)"
+              "description": "Absolute source path. Host path: local callers only (CLI, stdio MCP, same-host Web UI/REST); omitted for remote REST and HTTP MCP callers, which identify the document by uri + relPath."
             },
             "relPath": {
               "type": "string",

package/spec/output-schemas/capture-receipt.schema.json

@@ -43,7 +43,7 @@
     },
     "absPath": {
       "type": "string",
-      "description": "Absolute path when the local surface exposes it."
+      "description": "Absolute path of the written file. Host path: local callers only (CLI, stdio MCP, same-host Web UI/REST); omitted for remote REST and HTTP MCP callers, which identify the document by uri + relPath."
     },
     "serverInstanceId": {
       "type": "string"
@@ -129,6 +129,9 @@
         "overwritten",
         "conflict"
       ]
+    },
+    "request": {
+      "$ref": "gno://schemas/request-status@1.0#/$defs/requestReceipt"
     }
   },
   "definitions": {

package/spec/output-schemas/doctor.schema.json

@@ -243,6 +243,94 @@
               "type": "string"
             }
           },
+          "vectorPartitions": {
+            "type": "array",
+            "description": "Vector partitions (vector-partitions check); `retrieval` marks the one status and search use",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "id",
+                "model",
+                "dimensions",
+                "state",
+                "legacy",
+                "retrieval",
+                "droppable",
+                "owners",
+                "provenance",
+                "compatibleRuntimes",
+                "incompatibleRuntimes"
+              ],
+              "properties": {
+                "id": {
+                  "type": "string"
+                },
+                "model": {
+                  "type": "string"
+                },
+                "dimensions": {
+                  "type": "integer",
+                  "minimum": 1
+                },
+                "state": {
+                  "type": "string",
+                  "enum": ["active", "shadow"]
+                },
+                "legacy": {
+                  "type": "boolean"
+                },
+                "retrieval": {
+                  "type": "boolean"
+                },
+                "droppable": {
+                  "type": "boolean"
+                },
+                "owners": {
+                  "type": "integer",
+                  "minimum": 0
+                },
+                "provenance": {
+                  "type": "string"
+                },
+                "compatibleRuntimes": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "incompatibleRuntimes": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          },
+          "vectorRuntime": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["label", "state", "partition"],
+            "description": "This process's runtime, resolved by the same selection rule its queries use",
+            "properties": {
+              "label": {
+                "type": ["string", "null"],
+                "description": "Runtime recorded by this caller's last query or embed"
+              },
+              "state": {
+                "type": "string",
+                "enum": ["vectors", "unavailable", "unresolved"],
+                "description": "vectors: queries read `partition`; unavailable: lexical retrieval only; unresolved: no query or embed has resolved this caller yet"
+              },
+              "partition": {
+                "type": ["string", "null"]
+              },
+              "reason": {
+                "type": "string"
+              }
+            }
+          },
           "embeddingFingerprint": {
             "type": "object",
             "description": "Embedding freshness fingerprint diagnostics",

package/spec/output-schemas/error.schema.json

@@ -12,8 +12,17 @@
       "properties": {
         "code": {
           "type": "string",
-          "description": "Error code matching exit code",
-          "enum": ["VALIDATION", "RUNTIME"]
+          "description": "CLI error code; each maps to one exit code (see spec/cli.md Error Output)",
+          "enum": [
+            "VALIDATION",
+            "RUNTIME",
+            "NOT_RUNNING",
+            "BUSY",
+            "AUDIT_FINDINGS",
+            "AUDIT_PARTIAL",
+            "CONTEXT_STALE",
+            "CONTEXT_CONFLICT"
+          ]
         },
         "message": {
           "type": "string",

package/spec/output-schemas/get.schema.json

@@ -62,7 +62,7 @@
       "properties": {
         "absPath": {
           "type": "string",
-          "description": "Absolute path to source file"
+          "description": "Absolute path to source file. Host path: local callers only (CLI, stdio MCP, same-host Web UI/REST); omitted for remote REST and HTTP MCP callers, which identify the document by uri + relPath."
         },
         "relPath": {
           "type": "string",

package/spec/output-schemas/mcp-capture-result.schema.json

@@ -7,7 +7,6 @@
   "required": [
     "docid",
     "uri",
-    "absPath",
     "collection",
     "relPath",
     "created",
@@ -34,7 +33,7 @@
     },
     "absPath": {
       "type": "string",
-      "description": "Absolute path to the created file"
+      "description": "Absolute path to the created file. Stdio callers only; omitted for HTTP MCP callers, which identify the file by uri + relPath."
     },
     "collection": {
       "type": "string",
@@ -129,6 +128,9 @@
       "type": "string",
       "description": "Server instance UUID",
       "format": "uuid"
+    },
+    "request": {
+      "$ref": "gno://schemas/request-status@1.0#/$defs/requestReceipt"
     }
   },
   "definitions": {

package/spec/output-schemas/memory-remember.schema.json

@@ -12,7 +12,10 @@
       "properties": {
         "outcome": { "const": "existing" },
         "record": { "$ref": "#/$defs/fact" },
-        "matching": { "$ref": "#/$defs/matching" }
+        "matching": { "$ref": "#/$defs/matching" },
+        "request": {
+          "$ref": "gno://schemas/request-status@1.0#/$defs/requestReceipt"
+        }
       }
     },
     {
@@ -31,16 +34,19 @@
     {
       "type": "object",
       "additionalProperties": false,
-      "required": ["outcome", "record", "absPath", "sync", "matching"],
+      "required": ["outcome", "record", "sync", "matching"],
       "properties": {
         "outcome": { "enum": ["added", "superseded"] },
         "record": { "$ref": "#/$defs/fact" },
         "absPath": {
           "type": "string",
-          "description": "Absolute path of the fact file that was written."
+          "description": "Absolute path of the fact file that was written. Host path: local callers only (CLI, stdio MCP, same-host Web UI/REST); omitted for remote REST and HTTP MCP callers, which identify the document by uri + relPath."
         },
         "sync": { "$ref": "#/$defs/sync" },
-        "matching": { "$ref": "#/$defs/matching" }
+        "matching": { "$ref": "#/$defs/matching" },
+        "request": {
+          "$ref": "gno://schemas/request-status@1.0#/$defs/requestReceipt"
+        }
       }
     }
   ],

package/spec/output-schemas/multi-get.schema.json

@@ -40,7 +40,10 @@
             "type": "object",
             "required": ["relPath", "mime", "ext"],
             "properties": {
-              "absPath": { "type": "string" },
+              "absPath": {
+                "type": "string",
+                "description": "Absolute path to source file. Host path: local callers only (CLI, stdio MCP, same-host Web UI/REST); omitted for remote REST and HTTP MCP callers, which identify the document by uri + relPath."
+              },
               "relPath": { "type": "string" },
               "mime": { "type": "string" },
               "ext": { "type": "string", "pattern": "^\\.[a-zA-Z0-9]+$" }

package/spec/output-schemas/peek.schema.json

@@ -99,14 +99,7 @@
       "items": {
         "type": "object",
         "additionalProperties": false,
-        "required": [
-          "docid",
-          "uri",
-          "title",
-          "collection",
-          "absPath",
-          "modifiedAt"
-        ],
+        "required": ["docid", "uri", "title", "collection", "modifiedAt"],
         "properties": {
           "docid": {
             "type": "string",
@@ -129,7 +122,7 @@
           "absPath": {
             "type": "string",
             "minLength": 1,
-            "description": "Absolute source path (collection root + relative path)"
+            "description": "Absolute source path (collection root + relative path). CLI and stdio MCP only; omitted for HTTP MCP callers."
           },
           "modifiedAt": {
             "type": "string",