@gmickel/gno 2.5.1 → 2.6.0

package/src/mcp/tools/sessions.ts

@@ -0,0 +1,208 @@
+/**
+ * MCP session-archive tools: bounded status (including opt-in automation),
+ * import of owner-registered sources, and a run request for a configured
+ * automation profile. Thin adapters over the core sessions services. Hooks,
+ * schedules and source access are managed only by the local owner.
+ *
+ * Remote callers never discover host directories and never name paths:
+ * import accepts a registered source ID only. Import is registered only with
+ * `--enable-write`, and neither tool is part of the core profile.
+ *
+ * @module src/mcp/tools/sessions
+ */
+
+import { z } from "zod";
+
+import type { ToolContext } from "../server";
+
+import { runAutomationProfile } from "../../sessions/automation";
+import {
+  formatAutomationRunText,
+  formatImportReceiptText,
+  formatStatusText,
+} from "../../sessions/format";
+import { importInChildProcess } from "../../sessions/import-child";
+import { SessionsService } from "../../sessions/service";
+import {
+  MAX_IMPORT_LIMIT,
+  type SessionAutomationRunResult,
+  type SessionImportReceipt,
+  remoteSafeSessionsError,
+} from "../../sessions/types";
+import { runTool, type ToolResult } from "./index";
+
+export const sessionsStatusInputSchema = z.object({});
+
+export const sessionsImportInputSchema = z
+  .object({
+    sourceId: z
+      .string()
+      .trim()
+      .min(1)
+      .max(64)
+      .describe(
+        "ID of an owner-registered session source (see gno_sessions_status)"
+      ),
+    dryRun: z
+      .boolean()
+      .optional()
+      .describe("Parse and report without writing archive or index state"),
+    limit: z
+      .number()
+      .int()
+      .min(1)
+      .max(MAX_IMPORT_LIMIT)
+      .optional()
+      .describe(
+        "Maximum changed units processed this call; the rest are deferred"
+      ),
+  })
+  .strict();
+
+export type SessionsImportToolInput = z.infer<typeof sessionsImportInputSchema>;
+
+export const sessionsAutomationRunInputSchema = z
+  .object({
+    profileId: z
+      .string()
+      .trim()
+      .min(1)
+      .max(64)
+      .describe(
+        "ID of an owner-configured automation profile (see gno_sessions_status)"
+      ),
+  })
+  .strict();
+
+export type SessionsAutomationRunToolInput = z.infer<
+  typeof sessionsAutomationRunInputSchema
+>;
+
+export const SESSIONS_AUTOMATION_RUN_MCP_ANNOTATIONS = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false,
+} as const;
+
+export const SESSIONS_STATUS_MCP_ANNOTATIONS = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false,
+} as const;
+
+export const SESSIONS_IMPORT_MCP_ANNOTATIONS = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false,
+} as const;
+
+function service(ctx: ToolContext): SessionsService {
+  return new SessionsService({
+    config: ctx.config,
+    configPath: ctx.actualConfigPath,
+    indexName: ctx.indexName,
+    store: ctx.store,
+  });
+}
+
+/** Re-throw as `CODE: message` (the shape runTool parses), never with host paths. */
+function rethrowSessionsError(error: unknown): never {
+  const typed = remoteSafeSessionsError(error);
+  throw new Error(`${typed.code}: ${typed.message}`);
+}
+
+export function handleSessionsStatus(ctx: ToolContext): Promise<ToolResult> {
+  return runTool(
+    ctx,
+    "gno_sessions_status",
+    async () => {
+      try {
+        return await service(ctx).status();
+      } catch (error) {
+        return rethrowSessionsError(error);
+      }
+    },
+    formatStatusText
+  );
+}
+
+export function handleSessionsImport(
+  args: SessionsImportToolInput,
+  ctx: ToolContext
+): Promise<ToolResult> {
+  return runTool(
+    ctx,
+    "gno_sessions_import",
+    async () => {
+      if (!ctx.enableWrite) {
+        throw new Error(
+          "WRITE_DISABLED: gno_sessions_import requires --enable-write or GNO_MCP_ENABLE_WRITE=1"
+        );
+      }
+      let receipt: SessionImportReceipt;
+      try {
+        // A child process keeps this server answering during a long import.
+        receipt = await importInChildProcess({
+          config: ctx.config,
+          configPath: ctx.actualConfigPath,
+          indexName: ctx.indexName,
+          sourceId: args.sourceId,
+          dryRun: args.dryRun === true,
+          limit: args.limit,
+        });
+      } catch (error) {
+        return rethrowSessionsError(error);
+      }
+      if (!receipt.dryRun && receipt.lexical.collections.length > 0) {
+        ctx.markContentMutation?.();
+        ctx.markIndexMutation?.();
+      }
+      return receipt;
+    },
+    formatImportReceiptText
+  );
+}
+
+export function handleSessionsAutomationRun(
+  args: SessionsAutomationRunToolInput,
+  ctx: ToolContext
+): Promise<ToolResult> {
+  return runTool(
+    ctx,
+    "gno_sessions_automation_run",
+    async () => {
+      if (!ctx.enableWrite) {
+        throw new Error(
+          "WRITE_DISABLED: gno_sessions_automation_run requires --enable-write or GNO_MCP_ENABLE_WRITE=1"
+        );
+      }
+      let result: SessionAutomationRunResult;
+      try {
+        result = await runAutomationProfile(
+          {
+            configPath: ctx.actualConfigPath,
+            indexName: ctx.indexName,
+            store: ctx.store,
+            // A child process keeps this server answering during the run.
+            inChildProcess: true,
+          },
+          args.profileId,
+          { trigger: "manual" }
+        );
+      } catch (error) {
+        return rethrowSessionsError(error);
+      }
+      if (
+        result.receipts.some((receipt) => receipt.lexical.collections.length)
+      ) {
+        ctx.markContentMutation?.();
+        ctx.markIndexMutation?.();
+      }
+      return result;
+    },
+    formatAutomationRunText
+  );
+}

package/src/sdk/client.ts

@@ -21,6 +21,7 @@ import type {
   GnoCaptureOptions,
   GnoCaptureResult,
   GnoClient,
+  GnoRequestStatusResult,
   GnoCreateFolderOptions,
   GnoCreateFolderResult,
   GnoCreateNoteOptions,
@@ -49,6 +50,11 @@ import type {
   GnoRenameNoteApplyOptions,
   GnoRenameNoteOptions,
   GnoSearchOptions,
+  GnoSessionsAutomationRunResult,
+  GnoSessionsDiscovery,
+  GnoSessionsImportInput,
+  GnoSessionsImportReceipt,
+  GnoSessionsStatus,
   GnoUpdateOptions,
   GnoVectorSearchOptions,
   KnowledgeChangesResult,
@@ -90,17 +96,17 @@ import { buildVerifiedAsk } from "../app/verified-ask";
 import {
   buildContentTypeBoostStatus,
   ConfigSchema,
+  getConfigPaths,
   loadConfig,
   normalizeConfigContentTypes,
   normalizeContentTypes,
 } from "../config";
 import {
-  buildCaptureReceipt,
-  type CapturePlan,
+  CaptureSyncError,
   listCaptureDiskRelPaths,
   planCapture,
 } from "../core/capture";
-import { writeCapturePlanFile } from "../core/capture-write";
+import { publishCapture } from "../core/capture-publish";
 import { projectCollectionEgressPolicy } from "../core/collection-egress-policy-projection";
 import { CollectionEgressPolicyService } from "../core/collection-egress-policy-service";
 import { applyConfigChange } from "../core/config-mutation";
@@ -140,6 +146,12 @@ import {
   ProjectAffinityInputError,
   resolveRemoteProjectAffinity,
 } from "../core/project-affinity-surface";
+import {
+  localRequestLedger,
+  readRequestStatus,
+  RequestReceiptError,
+  type RequestReceiptErrorCode,
+} from "../core/request-receipts";
 import { RetrievalTraceManagementService } from "../core/retrieval-trace-management";
 import {
   finishRetrievalTraceAfterError,
@@ -169,7 +181,6 @@ import {
   normalizeMetadataPredicate,
   type MetadataPredicate,
 } from "../core/typed-metadata";
-import { writeLeasePath } from "../core/write-lease";
 import {
   defaultSyncService,
   type SyncResult,
@@ -193,6 +204,10 @@ import { searchHybrid } from "../pipeline/hybrid";
 import { RequestHydration } from "../pipeline/hydration";
 import { searchBm25 } from "../pipeline/search";
 import { searchVectorWithEmbedding } from "../pipeline/vsearch";
+import { runAutomationProfile } from "../sessions/automation";
+import { assertSessionBinding } from "../sessions/binding";
+import { SessionsService } from "../sessions/service";
+import { SESSIONS_VALIDATION_CODES, SessionsError } from "../sessions/types";
 import { SqliteAdapter } from "../store/sqlite/adapter";
 import { openScopedIndexStore } from "../store/sqlite/scoped-index";
 import { createVectorIndexPort } from "../store/vector";
@@ -314,6 +329,19 @@ async function resolveClientState(
     options.indexName ?? DEFAULT_INDEX_NAME
   );
   const dbPath = options.dbPath ?? getIndexDbPath(indexName);
+  try {
+    await assertSessionBinding({
+      config,
+      configPath:
+        configSource === "inline"
+          ? "<inline-config>"
+          : (options.configPath ?? getConfigPaths().configFile),
+      indexName,
+      dbPath,
+    });
+  } catch (cause) {
+    throw toSessionsSdkError(cause);
+  }
   await mkdir(dirname(dbPath), { recursive: true });
 
   const store = new SqliteAdapter();
@@ -337,6 +365,16 @@ async function resolveClientState(
   };
 }
 
+/** Map a sessions error onto the SDK family; the sessions code survives in `details.code`. */
+function toSessionsSdkError(cause: unknown): unknown {
+  if (!(cause instanceof SessionsError)) return cause;
+  return sdkError(
+    SESSIONS_VALIDATION_CODES.has(cause.code) ? "VALIDATION" : "RUNTIME",
+    cause.message,
+    { cause, details: { code: cause.code } }
+  );
+}
+
 /** SDK error family per memory code; exhaustive so a new code fails to compile. */
 const MEMORY_ERROR_TO_SDK: Readonly<Record<MemoryErrorCode, GnoSdkErrorCode>> =
   {
@@ -363,9 +401,28 @@ const MEMORY_ERROR_TO_SDK: Readonly<Record<MemoryErrorCode, GnoSdkErrorCode>> =
     MEMORY_QUERY_FAILED: "RUNTIME",
   };
 
+const REQUEST_ERROR_TO_SDK: Record<RequestReceiptErrorCode, GnoSdkErrorCode> = {
+  REQUEST_ID_INVALID: "VALIDATION",
+  REQUEST_ID_CONFLICT: "VALIDATION",
+  REQUEST_EXPIRED: "VALIDATION",
+  REQUEST_PENDING: "RUNTIME",
+  REQUEST_RECOVERY_CONFLICT: "RUNTIME",
+  REQUEST_CAPACITY_EXHAUSTED: "RUNTIME",
+  REQUEST_LEDGER_UNAVAILABLE: "RUNTIME",
+};
+
+/** Request receipt errors carry their stable code in `details.code`. */
+function toRequestSdkError(cause: unknown): unknown {
+  if (!(cause instanceof RequestReceiptError)) return cause;
+  return sdkError(REQUEST_ERROR_TO_SDK[cause.code], cause.message, {
+    cause,
+    details: { code: cause.code },
+  });
+}
+
 /** Map a core MemoryError onto the SDK error family; the memory code survives in `details.code`. */
 function toMemorySdkError(cause: unknown): unknown {
-  if (!(cause instanceof MemoryError)) return cause;
+  if (!(cause instanceof MemoryError)) return toRequestSdkError(cause);
   return sdkError(MEMORY_ERROR_TO_SDK[cause.code], cause.message, {
     cause,
     details: { code: cause.code },
@@ -1345,6 +1402,8 @@ class GnoClientImpl implements GnoClient {
       requestedIndexName: resolution.value.indexName,
       config: this.config,
       configPath: this.configPath,
+    }).catch((cause: unknown) => {
+      throw toSessionsSdkError(cause);
     });
     try {
       const result = await getDocumentByRef(
@@ -1384,6 +1443,8 @@ class GnoClientImpl implements GnoClient {
       requestedIndexName: resolution.value.indexName,
       config: this.config,
       configPath: this.configPath,
+    }).catch((cause: unknown) => {
+      throw toSessionsSdkError(cause);
     });
     try {
       const result = await multiGetDocuments(
@@ -1790,7 +1851,8 @@ class GnoClientImpl implements GnoClient {
           store: this.store,
           config: this.config,
           collections: this.config.collections,
-          lockPath: writeLeasePath(this.dbPath),
+          lockPath: this.requestLedger().lockPath,
+          requests: this.requestLedger(),
           embedPort: ports.embedPort,
           vectorIndex: ports.vectorIndex,
         })
@@ -1802,6 +1864,62 @@ class GnoClientImpl implements GnoClient {
     }
   }
 
+  private sessionsService(): SessionsService {
+    this.assertOpen();
+    return new SessionsService({
+      config: this.config,
+      configPath: this.configPath ?? getConfigPaths().configFile,
+      indexName: this.indexName,
+      store: this.store,
+    });
+  }
+
+  async sessionsStatus(): Promise<GnoSessionsStatus> {
+    try {
+      return await this.sessionsService().status();
+    } catch (cause) {
+      throw toSessionsSdkError(cause);
+    }
+  }
+
+  async discoverSessions(): Promise<GnoSessionsDiscovery> {
+    try {
+      return await this.sessionsService().discover();
+    } catch (cause) {
+      throw toSessionsSdkError(cause);
+    }
+  }
+
+  async importSessions(
+    input: GnoSessionsImportInput
+  ): Promise<GnoSessionsImportReceipt> {
+    try {
+      // The SDK runs in the owner's process, so explicit paths are allowed.
+      return await this.sessionsService().import(input, { allowPaths: true });
+    } catch (cause) {
+      throw toSessionsSdkError(cause);
+    }
+  }
+
+  async runSessionsAutomation(input: {
+    profileId: string;
+  }): Promise<GnoSessionsAutomationRunResult> {
+    this.assertOpen();
+    try {
+      return await runAutomationProfile(
+        {
+          configPath: this.configPath ?? getConfigPaths().configFile,
+          indexName: this.indexName,
+          store: this.store,
+        },
+        input.profileId,
+        { trigger: "manual" }
+      );
+    } catch (cause) {
+      throw toSessionsSdkError(cause);
+    }
+  }
+
   async remember(input: GnoRememberInput): Promise<GnoRememberResult> {
     return this.withMemoryService(input?.collection, (service) =>
       service.remember(input)
@@ -1823,98 +1941,76 @@ class GnoClientImpl implements GnoClient {
         `Collection not found: ${options.collection}`
       );
     }
-
-    const existingList = await this.store.listDocuments(collection.name);
-    if (!existingList.ok) {
-      throw sdkError("STORE", existingList.error.message, {
-        cause: existingList.error.cause,
-      });
-    }
-    const { overwrite: _unsupportedOverwrite, ...captureOptions } =
-      options as GnoCaptureOptions & { overwrite?: unknown };
+    const {
+      overwrite: _unsupportedOverwrite,
+      requestId,
+      ...captureOptions
+    } = options as GnoCaptureOptions & { overwrite?: unknown };
     if (_unsupportedOverwrite !== undefined) {
       throw sdkError(
         "VALIDATION",
         "overwrite is not supported by client.capture(); use collisionPolicy instead"
       );
     }
+    const input = { ...captureOptions, collection: collection.name };
 
-    let plan: CapturePlan;
     try {
-      plan = planCapture({
-        input: {
-          ...captureOptions,
-          collection: collection.name,
+      const published = await publishCapture({
+        collection,
+        store: this.store,
+        lockPath: this.requestLedger().lockPath,
+        reportSyncFailure: true,
+        config: this.config,
+        plan: async () => {
+          const existingList = await this.store.listDocuments(collection.name);
+          if (!existingList.ok) {
+            throw sdkError("STORE", existingList.error.message, {
+              cause: existingList.error.cause,
+            });
+          }
+          try {
+            return planCapture({
+              input,
+              existingRelPaths: existingList.value.map((doc) => doc.relPath),
+              diskRelPaths: await listCaptureDiskRelPaths(collection.path),
+            });
+          } catch (error) {
+            throw sdkError(
+              "VALIDATION",
+              error instanceof Error ? error.message : String(error)
+            );
+          }
         },
-        existingRelPaths: existingList.value.map((doc) => doc.relPath),
-        diskRelPaths: await listCaptureDiskRelPaths(collection.path),
+        request:
+          requestId === undefined
+            ? undefined
+            : { ...this.requestLedger(), requestId, input },
       });
-    } catch (error) {
-      throw sdkError(
-        "VALIDATION",
-        error instanceof Error ? error.message : String(error)
-      );
-    }
-
-    const fullPath = `${collection.path}/${plan.relPath}`;
-    if (plan.openedExisting) {
-      const existingDoc = await this.store.getDocument(
-        collection.name,
-        plan.relPath
-      );
-      if (!existingDoc.ok) {
-        throw sdkError("STORE", existingDoc.error.message, {
-          cause: existingDoc.error.cause,
+      return published.request
+        ? { ...published.receipt, request: published.request }
+        : published.receipt;
+    } catch (cause) {
+      if (cause instanceof CaptureSyncError) {
+        throw sdkError("RUNTIME", cause.message, {
+          cause,
+          details: { code: cause.code, absPath: cause.absPath },
         });
       }
-      return buildCaptureReceipt({
-        plan,
-        absPath: fullPath,
-        docid: existingDoc.value?.docid,
-        sync: existingDoc.value
-          ? { status: "completed" }
-          : {
-              status: "skipped",
-              reason: "Existing file is not indexed yet.",
-            },
-      });
+      throw toRequestSdkError(cause);
     }
+  }
 
-    await mkdir(dirname(fullPath), { recursive: true });
-    await writeCapturePlanFile(plan, fullPath);
-    const syncResults = await defaultSyncService.syncFiles(
-      collection,
-      this.store,
-      [plan.relPath],
-      withContentTypeRules(
-        {
-          runUpdateCmd: false,
-          gitPull: false,
-        },
-        this.config
-      )
-    );
-    const syncResult = syncResults[0];
-    const docResult = await this.store.getDocument(
-      collection.name,
-      plan.relPath
-    );
-    const docid = docResult.ok ? docResult.value?.docid : undefined;
-    return buildCaptureReceipt({
-      plan,
-      absPath: fullPath,
-      docid: syncResult?.docid ?? docid,
-      sync:
-        syncResult?.status === "error"
-          ? {
-              status: "failed",
-              error:
-                syncResult.errorMessage ??
-                syncResult.errorCode ??
-                "Unknown sync error",
-            }
-          : { status: "completed" },
-    });
+  private requestLedger() {
+    return localRequestLedger(this.dbPath);
+  }
+
+  async requestStatus(requestId: string): Promise<GnoRequestStatusResult> {
+    this.assertOpen();
+    try {
+      return await readRequestStatus({ ...this.requestLedger(), requestId });
+    } catch (cause) {
+      throw toRequestSdkError(cause);
+    }
   }
 
   async createFolder(

package/src/sdk/index.ts

@@ -62,10 +62,16 @@ export type {
   GnoRecallResult,
   GnoRememberInput,
   GnoRememberResult,
+  GnoRequestStatusResult,
   GnoRenameNoteApplyOptions,
   GnoRenameNoteOptions,
   GnoProjectHintOptions,
   GnoSearchOptions,
+  GnoSessionsDiscovery,
+  GnoSessionsImportInput,
+  GnoSessionsImportReceipt,
+  GnoSessionsAutomationRunResult,
+  GnoSessionsStatus,
   GnoSkippedDocument,
   GnoUpdateOptions,
   GnoVectorSearchOptions,

package/src/sdk/types.ts

@@ -67,6 +67,10 @@ import type {
 } from "../core/memory";
 import type { NoteCollisionPolicy } from "../core/note-creation";
 import type { NotePresetId } from "../core/note-presets";
+import type {
+  RequestReceiptInfo,
+  RequestStatusResult,
+} from "../core/request-receipts";
 import type {
   RetrievalTraceDeleteResult,
   RetrievalTraceDetail,
@@ -94,6 +98,13 @@ import type {
   SearchOptions,
   SearchResults,
 } from "../pipeline/types";
+import type { SessionImportInput } from "../sessions/service";
+import type {
+  SessionAutomationRunResult,
+  SessionImportReceipt,
+  SessionsDiscovery,
+  SessionsStatus,
+} from "../sessions/types";
 import type { IndexStatus } from "../store/types";
 
 export type {
@@ -263,11 +274,25 @@ export interface GnoCreateNoteResult {
   createdWithSuffix?: boolean;
 }
 
-export interface GnoCaptureOptions extends Omit<CaptureInput, "overwrite"> {}
+export interface GnoCaptureOptions extends Omit<CaptureInput, "overwrite"> {
+  /** Opt-in retry identity; reuse it only to retry this same capture. */
+  requestId?: string;
+}
 
-export type GnoCaptureResult = CaptureReceipt;
+export type GnoCaptureResult = CaptureReceipt & {
+  /** Present when the call carried a requestId. */
+  request?: RequestReceiptInfo;
+};
+
+/** Lookup of a capture/remember request ID in the local-owner namespace. */
+export type GnoRequestStatusResult = RequestStatusResult;
 
 /** Shared memory contract (identical on CLI, MCP, REST, and SDK). */
+export type GnoSessionsStatus = SessionsStatus;
+export type GnoSessionsDiscovery = SessionsDiscovery;
+export type GnoSessionsImportReceipt = SessionImportReceipt;
+export type GnoSessionsImportInput = SessionImportInput;
+export type GnoSessionsAutomationRunResult = SessionAutomationRunResult;
 export type GnoRememberInput = RememberInput;
 export type GnoRememberResult = RememberResult;
 export type GnoRecallInput = RecallInput;
@@ -414,6 +439,11 @@ export interface GnoClient {
   embed(options?: GnoEmbedOptions): Promise<GnoEmbedResult>;
   index(options?: GnoIndexOptions): Promise<GnoIndexResult>;
   capture(options: GnoCaptureOptions): Promise<GnoCaptureResult>;
+  /**
+   * Look up a capture/remember `requestId` before retrying it: pending,
+   * committed (with a content-free result pointer), expired, or not_found.
+   */
+  requestStatus(requestId: string): Promise<GnoRequestStatusResult>;
   /**
    * Store one fact in a memory-managed collection, or propose candidates when
    * `decision` is omitted. Requires caller + session identity and explicit
@@ -425,6 +455,28 @@ export interface GnoClient {
    * The result carries a content-free fencing receipt.
    */
   recall(input: GnoRecallInput): Promise<GnoRecallResult>;
+  /**
+   * Session-archive status for a client opened on the dedicated archive
+   * config/index pair. Throws VALIDATION (`details.code`
+   * SESSIONS_NOT_CONFIGURED) on any other config.
+   */
+  sessionsStatus(): Promise<GnoSessionsStatus>;
+  /** Preview supported local session sources on this host. Never imports. */
+  discoverSessions(): Promise<GnoSessionsDiscovery>;
+  /**
+   * Manually import a registered source (`sourceId`) or explicit local paths
+   * (`paths` + `collection`) into the archive. Returns the shared receipt.
+   */
+  importSessions(
+    input: GnoSessionsImportInput
+  ): Promise<GnoSessionsImportReceipt>;
+  /**
+   * Run one configured automation profile now through the manual importer.
+   * Hooks and schedules are enabled only from the CLI or a same-host browser.
+   */
+  runSessionsAutomation(input: {
+    profileId: string;
+  }): Promise<GnoSessionsAutomationRunResult>;
   createNote(options: GnoCreateNoteOptions): Promise<GnoCreateNoteResult>;
   createFolder(options: GnoCreateFolderOptions): Promise<GnoCreateFolderResult>;
   previewRenameNote(