@gmickel/gno 2.5.1 → 2.6.0

package/spec/output-schemas/sessions-status.schema.json

@@ -0,0 +1,432 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/sessions-status@1.0",
+  "title": "GNO Session Archive Status",
+  "description": "Shared status of a session archive on every surface (CLI `gno sessions status --json`, MCP gno_sessions_status, REST GET /api/sessions/status, SDK client.sessionsStatus()). Derived from SessionsStatus in src/sessions/types.ts. Includes opt-in automation state. Contains no host paths and no session content.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "configured",
+    "index",
+    "collections",
+    "sources",
+    "automation",
+    "warnings"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "1"
+    },
+    "configured": {
+      "const": true
+    },
+    "index": {
+      "type": "string",
+      "minLength": 1
+    },
+    "collections": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "threads"],
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "threads": {
+            "type": "integer",
+            "minimum": 0
+          }
+        }
+      }
+    },
+    "sources": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "harness",
+          "collection",
+          "available",
+          "units",
+          "archivedThreads",
+          "staleParser",
+          "sourceUnavailable",
+          "lastImportAt"
+        ],
+        "properties": {
+          "id": { "type": "string" },
+          "harness": { "enum": ["codex", "claude-code", "openclaw", "hermes"] },
+          "collection": { "type": "string" },
+          "available": {
+            "type": "boolean",
+            "description": "False when the source root is missing or cannot be listed."
+          },
+          "units": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "total",
+              "complete",
+              "incomplete",
+              "failed",
+              "pending"
+            ],
+            "properties": {
+              "total": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "complete": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "incomplete": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "failed": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "pending": {
+                "type": "integer",
+                "minimum": 0
+              }
+            }
+          },
+          "archivedThreads": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "staleParser": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Archived units produced by an older parser whose source is no longer available to reparse."
+          },
+          "sourceUnavailable": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Archived units whose source no longer exists; their archive is retained until an explicit prune."
+          },
+          "lastImportAt": {
+            "type": ["string", "null"],
+            "format": "date-time"
+          }
+        }
+      }
+    },
+    "automation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["daemon", "timezone", "profiles"],
+      "properties": {
+        "daemon": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["state", "heartbeatAt"],
+          "properties": {
+            "state": {
+              "enum": ["running", "not_running", "stale"],
+              "description": "running only with a fresh heartbeat from a live daemon on this archive; serve never counts."
+            },
+            "heartbeatAt": {
+              "type": ["string", "null"],
+              "format": "date-time"
+            }
+          }
+        },
+        "timezone": {
+          "type": "string",
+          "description": "IANA timezone for human-readable times; stored instants are UTC."
+        },
+        "profiles": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "id",
+              "sources",
+              "collections",
+              "state",
+              "hook",
+              "schedule",
+              "limit",
+              "retries",
+              "pending",
+              "running",
+              "lastTrigger",
+              "lastRun",
+              "lastSuccessAt",
+              "retryAt",
+              "recovery"
+            ],
+            "properties": {
+              "id": {
+                "type": "string"
+              },
+              "sources": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "collections": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "state": {
+                "enum": [
+                  "off",
+                  "idle",
+                  "pending",
+                  "running",
+                  "retrying",
+                  "partial",
+                  "failed"
+                ],
+                "description": "off: no trigger enabled and nothing pending. partial/failed describe the last run."
+              },
+              "hook": {
+                "oneOf": [
+                  {
+                    "type": "null"
+                  },
+                  {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["harness", "enabled", "installed"],
+                    "properties": {
+                      "harness": {
+                        "enum": ["claude-code"]
+                      },
+                      "enabled": {
+                        "type": "boolean"
+                      },
+                      "installed": {
+                        "type": ["boolean", "null"],
+                        "description": "Owned entry present in the host settings file; null when the file cannot be read."
+                      }
+                    }
+                  }
+                ]
+              },
+              "schedule": {
+                "oneOf": [
+                  {
+                    "type": "null"
+                  },
+                  {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["enabled", "cadence", "nextDueAt"],
+                    "properties": {
+                      "enabled": {
+                        "type": "boolean"
+                      },
+                      "cadence": {
+                        "type": "string"
+                      },
+                      "nextDueAt": {
+                        "type": ["string", "null"],
+                        "format": "date-time",
+                        "description": "Null unless enabled and a daemon is running on this archive."
+                      }
+                    }
+                  }
+                ]
+              },
+              "limit": {
+                "type": "integer",
+                "minimum": 1
+              },
+              "retries": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "pending": {
+                "oneOf": [
+                  {
+                    "type": "null"
+                  },
+                  {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["since", "triggers"],
+                    "properties": {
+                      "since": {
+                        "type": "string",
+                        "format": "date-time"
+                      },
+                      "triggers": {
+                        "type": "array",
+                        "items": {
+                          "enum": ["hook", "schedule", "manual"]
+                        }
+                      }
+                    }
+                  }
+                ]
+              },
+              "running": {
+                "oneOf": [
+                  {
+                    "type": "null"
+                  },
+                  {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["startedAt", "triggers"],
+                    "properties": {
+                      "startedAt": {
+                        "type": "string",
+                        "format": "date-time"
+                      },
+                      "triggers": {
+                        "type": "array",
+                        "items": {
+                          "enum": ["hook", "schedule", "manual"]
+                        }
+                      }
+                    }
+                  }
+                ]
+              },
+              "lastTrigger": {
+                "oneOf": [
+                  {
+                    "type": "null"
+                  },
+                  {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["kind", "at"],
+                    "properties": {
+                      "kind": {
+                        "enum": ["hook", "schedule", "manual"]
+                      },
+                      "at": {
+                        "type": "string",
+                        "format": "date-time"
+                      }
+                    }
+                  }
+                ]
+              },
+              "lastRun": {
+                "oneOf": [
+                  {
+                    "type": "null"
+                  },
+                  {
+                    "$ref": "#/definitions/runRecord"
+                  }
+                ]
+              },
+              "lastSuccessAt": {
+                "type": ["string", "null"],
+                "format": "date-time"
+              },
+              "retryAt": {
+                "type": ["string", "null"],
+                "format": "date-time"
+              },
+              "recovery": {
+                "type": ["string", "null"]
+              }
+            }
+          }
+        }
+      }
+    },
+    "warnings": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "definitions": {
+    "runRecord": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "triggers",
+        "startedAt",
+        "finishedAt",
+        "outcome",
+        "reason",
+        "threads",
+        "units"
+      ],
+      "properties": {
+        "triggers": {
+          "type": "array",
+          "items": {
+            "enum": ["hook", "schedule", "manual"]
+          }
+        },
+        "startedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "finishedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "outcome": {
+          "enum": ["complete", "up_to_date", "partial", "failed"]
+        },
+        "reason": {
+          "type": ["string", "null"],
+          "description": "Stable reason code for partial or failed runs, e.g. busy, runtime_error, source_revoked, source_unavailable, invalid_configuration, import_failed, interrupted, deferred, incomplete_units, index_sync_failed, unit_failures."
+        },
+        "threads": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["imported", "updated", "unchanged"],
+          "properties": {
+            "imported": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "updated": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "unchanged": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        },
+        "units": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["incomplete", "failed", "deferred"],
+          "properties": {
+            "incomplete": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "failed": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "deferred": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/src/cli/commands/ask.ts

@@ -15,6 +15,7 @@ import type {
 } from "../../llm/types";
 import type { AskOptions, AskResult, Citation } from "../../pipeline/types";
 
+import { decorateUriForIndex } from "../../app/constants";
 import { buildVerifiedAsk } from "../../app/verified-ask";
 import { resolveCliProjectAffinity } from "../../core/project-affinity-surface";
 import {
@@ -96,7 +97,7 @@ export async function ask(
   const globals = getGlobals();
 
   const initResult = await initStore({
-    configPath: options.configPath,
+    configPath: options.configPath ?? globals.config,
     indexName: globals.index,
     collection: options.collection,
     syncConfig: false,
@@ -434,9 +435,20 @@ export async function ask(
         return { success: false, error: finalized.error.message };
       }
     }
+    // URIs carry `?index=` like search and Capsule results on a named index.
     return {
       success: true,
-      data: askResult,
+      data: {
+        ...askResult,
+        results: askResult.results.map((result) => ({
+          ...result,
+          uri: decorateUriForIndex(result.uri, globals.index),
+        })),
+        citations: askResult.citations?.map((citation) => ({
+          ...citation,
+          uri: decorateUriForIndex(citation.uri, globals.index),
+        })),
+      },
       metadata: traceSession?.metadata(),
     };
   } catch (cause) {

package/src/cli/commands/capture.ts

@@ -4,30 +4,28 @@
  * @module src/cli/commands/capture
  */
 
-// node:fs/promises for mkdir (no Bun equivalent for recursive dir creation)
-import { mkdir } from "node:fs/promises";
-// node:path has no Bun path utilities
-import { dirname, join } from "node:path";
-
 import type {
-  CapturePlan,
+  CaptureInput,
   CaptureReceipt,
   CaptureSourceKind,
 } from "../../core/capture";
 import type { NoteCollisionPolicy } from "../../core/note-creation";
 import type { NotePresetId } from "../../core/note-presets";
+import type { RequestReceiptInfo } from "../../core/request-receipts";
 
 import { getIndexDbPath } from "../../app/constants";
 import {
-  buildCaptureReceipt,
   listCaptureDiskRelPaths,
   planCapture,
   serializeCaptureReceipt,
 } from "../../core/capture";
-import { writeCapturePlanFile } from "../../core/capture-write";
-import { withWriteLock } from "../../core/file-lock";
-import { defaultSyncService, withContentTypeRules } from "../../ingestion";
+import { publishCapture } from "../../core/capture-publish";
+import {
+  formatRequestReceiptLine,
+  localRequestLedger,
+} from "../../core/request-receipts";
 import { CliError } from "../errors";
+import { requestErrorToCli } from "./request-status";
 import { initStore } from "./shared";
 
 export interface CaptureCliOptions {
@@ -49,6 +47,7 @@ export interface CaptureCliOptions {
   sourceAuthor?: string;
   sourceDate?: string;
   sourceId?: string;
+  requestId?: string;
 }
 
 const SOURCE_KINDS = new Set<CaptureSourceKind>([
@@ -130,7 +129,7 @@ function validateCollisionPolicy(
 
 export async function capture(
   options: CaptureCliOptions
-): Promise<CaptureReceipt> {
+): Promise<CaptureReceipt & { request?: RequestReceiptInfo }> {
   const storeInit = await initStore({
     configPath: options.configPath,
     indexName: options.indexName,
@@ -160,102 +159,61 @@ export async function capture(
 
     validateCollisionPolicy(options.collisionPolicy);
     const content = await readContent(options);
-    const existingDocs = await store.listDocuments(collection.name);
-    if (!existingDocs.ok) {
-      throw new Error(existingDocs.error.message);
-    }
-    const diskRelPaths = await listCaptureDiskRelPaths(collection.path);
-    let plan: CapturePlan;
+    const input: CaptureInput = {
+      collection: collection.name,
+      content,
+      title: options.title,
+      relPath: options.path,
+      folderPath: options.folder,
+      collisionPolicy: options.collisionPolicy,
+      presetId: options.preset,
+      tags: parseTags(options.tags),
+      source: buildSource(options),
+    };
+    const ledger = localRequestLedger(getIndexDbPath(options.indexName));
     try {
-      plan = planCapture({
-        input: {
-          collection: collection.name,
-          content,
-          title: options.title,
-          relPath: options.path,
-          folderPath: options.folder,
-          collisionPolicy: options.collisionPolicy,
-          presetId: options.preset,
-          tags: parseTags(options.tags),
-          source: buildSource(options),
+      const published = await publishCapture({
+        collection,
+        store,
+        lockPath: ledger.lockPath,
+        reportSyncFailure: true,
+        config,
+        plan: async () => {
+          const existingDocs = await store.listDocuments(collection.name);
+          if (!existingDocs.ok) {
+            throw new Error(existingDocs.error.message);
+          }
+          try {
+            return planCapture({
+              input,
+              existingRelPaths: existingDocs.value.map((doc) => doc.relPath),
+              diskRelPaths: await listCaptureDiskRelPaths(collection.path),
+            });
+          } catch (error) {
+            throw new CliError(
+              "VALIDATION",
+              error instanceof Error ? error.message : String(error)
+            );
+          }
         },
-        existingRelPaths: existingDocs.value.map((doc) => doc.relPath),
-        diskRelPaths,
+        request:
+          options.requestId === undefined
+            ? undefined
+            : { ...ledger, requestId: options.requestId, input },
       });
+      return published.request
+        ? { ...published.receipt, request: published.request }
+        : published.receipt;
     } catch (error) {
-      throw new CliError(
-        "VALIDATION",
-        error instanceof Error ? error.message : String(error)
-      );
+      throw requestErrorToCli(error);
     }
-    const absPath = join(collection.path, plan.relPath);
-
-    const lockPath = join(
-      dirname(getIndexDbPath(options.indexName)),
-      ".mcp-write.lock"
-    );
-    return await withWriteLock(lockPath, async () => {
-      if (plan.openedExisting) {
-        const existingDoc = await store.getDocument(
-          collection.name,
-          plan.relPath
-        );
-        if (!existingDoc.ok) {
-          throw new Error(existingDoc.error.message);
-        }
-        return buildCaptureReceipt({
-          plan,
-          absPath,
-          docid: existingDoc.value?.docid,
-          sync: existingDoc.value
-            ? { status: "completed" }
-            : {
-                status: "skipped",
-                reason: "Existing file is not indexed yet.",
-              },
-        });
-      }
-
-      await mkdir(dirname(absPath), { recursive: true });
-      await writeCapturePlanFile(plan, absPath);
-      const syncResults = await defaultSyncService.syncFiles(
-        collection,
-        store,
-        [plan.relPath],
-        withContentTypeRules(
-          {
-            runUpdateCmd: false,
-            gitPull: false,
-          },
-          config
-        )
-      );
-      const syncResult = syncResults[0];
-      const docResult = await store.getDocument(collection.name, plan.relPath);
-      const docid = docResult.ok ? docResult.value?.docid : undefined;
-      return buildCaptureReceipt({
-        plan,
-        absPath,
-        docid: syncResult?.docid ?? docid,
-        sync:
-          syncResult?.status === "error"
-            ? {
-                status: "failed",
-                error:
-                  syncResult.errorMessage ??
-                  syncResult.errorCode ??
-                  "Unknown sync error",
-              }
-            : { status: "completed" },
-      });
-    });
   } finally {
     await store.close();
   }
 }
 
 export function formatCaptureReceipt(
-  receipt: CaptureReceipt,
+  receipt: CaptureReceipt & { request?: RequestReceiptInfo },
   options: { json?: boolean; quiet?: boolean } = {}
 ): string {
   if (options.json) {
@@ -278,5 +236,6 @@ export function formatCaptureReceipt(
   if (receipt.source.url) {
     lines.push(`Source: ${receipt.source.url}`);
   }
+  if (receipt.request) lines.push(formatRequestReceiptLine(receipt.request));
   return lines.join("\n");
 }