@gmickel/gno 2.4.0 → 2.6.0

package/src/sdk/client.ts

@@ -1,13 +1,16 @@
+import { mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+
+import type { Config } from "../config/types";
 /**
  * GNO SDK client.
  *
  * @module src/sdk/client
  */
-
-import { mkdir } from "node:fs/promises";
-import { dirname } from "node:path";
-
-import type { Config } from "../config/types";
+import type {
+  CompiledContextPreviewInput,
+  CompiledContextCheckInput,
+} from "../core/compiled-context";
 import type { DownloadPolicy } from "../llm/policy";
 import type { EmbeddingPort, GenerationPort, RerankPort } from "../llm/types";
 import type { AskResult, SearchResults } from "../pipeline/types";
@@ -18,6 +21,7 @@ import type {
   GnoCaptureOptions,
   GnoCaptureResult,
   GnoClient,
+  GnoRequestStatusResult,
   GnoCreateFolderOptions,
   GnoCreateFolderResult,
   GnoCreateNoteOptions,
@@ -46,6 +50,11 @@ import type {
   GnoRenameNoteApplyOptions,
   GnoRenameNoteOptions,
   GnoSearchOptions,
+  GnoSessionsAutomationRunResult,
+  GnoSessionsDiscovery,
+  GnoSessionsImportInput,
+  GnoSessionsImportReceipt,
+  GnoSessionsStatus,
   GnoUpdateOptions,
   GnoVectorSearchOptions,
   KnowledgeChangesResult,
@@ -59,6 +68,15 @@ import type {
   SectionTargetV1,
 } from "./types";
 
+import {
+  previewCompiledContext,
+  checkCompiledContext,
+} from "../app/compiled-context";
+import {
+  compileContextFile,
+  checkContextFile,
+  refreshContextFile,
+} from "../app/compiled-context-files";
 import {
   decorateUriForIndex,
   DEFAULT_INDEX_NAME,
@@ -78,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";
@@ -128,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,
@@ -157,7 +181,6 @@ import {
   normalizeMetadataPredicate,
   type MetadataPredicate,
 } from "../core/typed-metadata";
-import { writeLeasePath } from "../core/write-lease";
 import {
   defaultSyncService,
   type SyncResult,
@@ -181,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";
@@ -302,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();
@@ -325,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>> =
   {
@@ -351,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 },
@@ -1255,6 +1324,61 @@ class GnoClientImpl implements GnoClient {
     }
   }
 
+  compiledContextPreview(
+    input: CompiledContextPreviewInput
+  ): ReturnType<typeof previewCompiledContext> {
+    this.assertOpen();
+    return previewCompiledContext(input, {
+      store: this.store,
+      config: this.config,
+      indexName: this.indexName,
+    });
+  }
+
+  compiledContextCheck(
+    input: CompiledContextCheckInput
+  ): ReturnType<typeof checkCompiledContext> {
+    this.assertOpen();
+    return checkCompiledContext(input, {
+      store: this.store,
+      config: this.config,
+      indexName: this.indexName,
+    });
+  }
+
+  compileContextFile(
+    input: Parameters<typeof compileContextFile>[0]
+  ): ReturnType<typeof compileContextFile> {
+    this.assertOpen();
+    return compileContextFile(input, {
+      store: this.store,
+      config: this.config,
+      indexName: this.indexName,
+    });
+  }
+
+  checkContextFile(
+    input: Parameters<typeof checkContextFile>[0]
+  ): ReturnType<typeof checkContextFile> {
+    this.assertOpen();
+    return checkContextFile(input, {
+      store: this.store,
+      config: this.config,
+      indexName: this.indexName,
+    });
+  }
+
+  refreshContextFile(
+    input: Parameters<typeof refreshContextFile>[0]
+  ): ReturnType<typeof refreshContextFile> {
+    this.assertOpen();
+    return refreshContextFile(
+      input,
+      { store: this.store, config: this.config, indexName: this.indexName },
+      (request) => this.context(request)
+    );
+  }
+
   async verifyContext(
     capsule: GnoContextResult
   ): Promise<GnoContextVerificationResult> {
@@ -1278,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(
@@ -1317,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(
@@ -1723,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,
         })
@@ -1735,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)
@@ -1756,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,
@@ -128,3 +134,10 @@ export type {
   RetrievalTracePurgeResult,
   RetrievalTraceSummary,
 } from "../core/retrieval-trace-management";
+
+export type {
+  CompiledContextPreviewInput,
+  CompiledContextCheckInput,
+  CompiledContextPreview,
+  CompiledContextCheck,
+} from "../core/compiled-context";

package/src/sdk/types.ts

@@ -1,9 +1,17 @@
+import type {
+  previewCompiledContext,
+  checkCompiledContext,
+} from "../app/compiled-context";
+import type {
+  compileContextFile,
+  checkContextFile,
+  refreshContextFile,
+} from "../app/compiled-context-files";
 /**
  * Public SDK types.
  *
  * @module src/sdk/types
  */
-
 import type {
   ContextCapsuleBuildInput,
   ContextRuntimeErrorCode,
@@ -18,6 +26,10 @@ import type {
   CollectionEgressPolicyState,
   EgressRelaxationConfirmation,
 } from "../core/collection-egress-policy-service";
+import type {
+  CompiledContextPreviewInput,
+  CompiledContextCheckInput,
+} from "../core/compiled-context";
 import type {
   ContextCapsuleErrorCode,
   ContextCapsuleV1,
@@ -55,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,
@@ -82,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 {
@@ -251,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 & {
+  /** Present when the call carried a requestId. */
+  request?: RequestReceiptInfo;
+};
 
-export type GnoCaptureResult = CaptureReceipt;
+/** 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;
@@ -328,6 +365,21 @@ export interface GnoClient {
   query(query: string, options?: GnoQueryOptions): Promise<SearchResults>;
   ask(query: string, options?: GnoAskOptions): Promise<AskResult>;
   context(input: GnoContextInput): Promise<GnoContextResult>;
+  compiledContextPreview(
+    input: CompiledContextPreviewInput
+  ): ReturnType<typeof previewCompiledContext>;
+  compiledContextCheck(
+    input: CompiledContextCheckInput
+  ): ReturnType<typeof checkCompiledContext>;
+  compileContextFile(
+    input: Parameters<typeof compileContextFile>[0]
+  ): ReturnType<typeof compileContextFile>;
+  checkContextFile(
+    input: Parameters<typeof checkContextFile>[0]
+  ): ReturnType<typeof checkContextFile>;
+  refreshContextFile(
+    input: Parameters<typeof refreshContextFile>[0]
+  ): ReturnType<typeof refreshContextFile>;
   verifyContext(
     capsule: ContextCapsuleV1
   ): Promise<GnoContextVerificationResult>;
@@ -387,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
@@ -398,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(