@karmaniverous/jeeves-meta 0.16.1 → 0.16.2

package/README.md

@@ -14,6 +14,8 @@ HTTP service for the Jeeves knowledge synthesis engine. Provides a Fastify API,
 - **Cross-meta references** — `_crossRefs` declares relationships to other metas; referenced `_content` included as architect/builder context
 - **Archive management** — timestamped snapshots with configurable pruning
 - **Lock staging** — write to `.lock` → copy to `meta.json` → archive (crash-safe)
+- **Staging file retry** — configurable retries (`stagingRetries`, `stagingRetryDelayMs`) when sub-agent output file is not yet visible after session completion (network/NFS latency)
+- **Preview delta cap** — `/preview` response includes `deltaFilesTruncated` flag and `deltaCount` total when delta files exceed `previewDeltaFilesCap`
 - **Virtual rule registration** — registers 3 watcher inference rules at startup with retry
 - **Progress reporting** — real-time synthesis events via gateway channel messages
 - **Graceful shutdown** — stop scheduler, release locks, close server

package/dist/cli/jeeves-meta/index.js

@@ -806,6 +806,14 @@ const serviceConfigSchema = metaConfigSchema.extend({
      * Rules are evaluated in order; last match wins for steer/crossRefs.
      */
     autoSeed: z.array(autoSeedRuleSchema).optional().default([]),
+    /** Optional workspace directory for synthesis staging files. Defaults to `os.tmpdir() + '/jeeves-meta'`. */
+    workspaceDir: z.string().optional(),
+    /** Max retries when staging file not yet visible after session completion. Default: 10. */
+    stagingRetries: z.number().int().min(0).default(10),
+    /** Delay between staging file retries in ms. Default: 250. */
+    stagingRetryDelayMs: z.number().int().min(0).default(250),
+    /** Maximum number of delta files returned in /preview response. Default: 50. */
+    previewDeltaFilesCap: z.number().int().min(1).default(50),
 });
 
 /**
@@ -933,12 +941,16 @@ class GatewayExecutor {
     apiKey;
     pollIntervalMs;
     workspaceDir;
+    stagingRetries;
+    stagingRetryDelayMs;
     controller = new AbortController();
     constructor(options = {}) {
         this.gatewayUrl = (options.gatewayUrl ?? 'http://127.0.0.1:18789').replace(/\/+$/, '');
         this.apiKey = options.apiKey;
         this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
         this.workspaceDir = options.workspaceDir ?? join(tmpdir(), 'jeeves-meta');
+        this.stagingRetries = options.stagingRetries ?? 10;
+        this.stagingRetryDelayMs = options.stagingRetryDelayMs ?? 250;
     }
     /** Remove a temp output file if it exists. */
     cleanupOutputFile(outputPath) {
@@ -1168,10 +1180,23 @@ class GatewayExecutor {
                         // No output or partial output — throw for _state recovery (§3.16.6)
                         throw new SpawnTimeoutError('Gateway-side timeout detected (session status: timeout)', outputPath);
                     }
-                    // Normal completion — read output from file
+                    // Normal completion — read staging file with retry for delayed visibility
                     const output = this.readStagingFile(outputPath);
                     if (output !== undefined)
                         return { output, tokens };
+                    // Staging file not yet visible — retry with bounded grace window
+                    for (let i = 0; i < this.stagingRetries; i++) {
+                        await sleepAsync(this.stagingRetryDelayMs);
+                        // Check abort after yield point — signal may have been
+                        // set externally (e.g. operator abort) during the sleep.
+                        if (this.aborted) {
+                            this.cleanupOutputFile(outputPath);
+                            throw new SpawnAbortedError();
+                        }
+                        const retryOutput = this.readStagingFile(outputPath);
+                        if (retryOutput !== undefined)
+                            return { output: retryOutput, tokens };
+                    }
                     // Fallback: extract from message content if file wasn't written.
                     // Skip ANNOUNCE_SKIP sentinel messages — the real output is in
                     // a preceding assistant message (the file write).
@@ -4452,9 +4477,10 @@ function registerPreviewRoute(app, deps) {
                 ownedFiles: scopeFiles.length,
                 childMetas: targetNode.children.length,
                 deltaFiles: deltaFiles
-                    .slice(0, 50)
+                    .slice(0, config.previewDeltaFilesCap)
                     .map((f) => ({ path: f, action: 'modified' })),
                 deltaCount: deltaFiles.length,
+                deltaFilesTruncated: deltaFiles.length > config.previewDeltaFilesCap,
             },
             estimatedTokens,
             // New phase-state fields (additive)
@@ -5156,6 +5182,9 @@ async function startService(config, configPath) {
     const executor = new GatewayExecutor({
         gatewayUrl: config.gatewayUrl,
         apiKey: config.gatewayApiKey,
+        workspaceDir: config.workspaceDir,
+        stagingRetries: config.stagingRetries,
+        stagingRetryDelayMs: config.stagingRetryDelayMs,
     });
     // Runtime stats (mutable, shared with routes)
     const stats = {

package/dist/executor/GatewayExecutor.d.ts

@@ -18,6 +18,10 @@ export interface GatewayExecutorOptions {
     pollIntervalMs?: number;
     /** Workspace directory for output staging. Default: OS temp dir + /jeeves-meta. */
     workspaceDir?: string;
+    /** Max retries when staging file not yet visible after session completion. Default: 10. */
+    stagingRetries?: number;
+    /** Delay between retries in ms. Default: 250. */
+    stagingRetryDelayMs?: number;
 }
 /**
  * MetaExecutor that spawns OpenClaw sessions via the gateway's
@@ -32,6 +36,8 @@ export declare class GatewayExecutor implements MetaExecutor {
     private readonly apiKey;
     private readonly pollIntervalMs;
     private readonly workspaceDir;
+    private readonly stagingRetries;
+    private readonly stagingRetryDelayMs;
     private controller;
     constructor(options?: GatewayExecutorOptions);
     /** Remove a temp output file if it exists. */

package/dist/index.js

@@ -1295,6 +1295,14 @@ const serviceConfigSchema = metaConfigSchema.extend({
      * Rules are evaluated in order; last match wins for steer/crossRefs.
      */
     autoSeed: z.array(autoSeedRuleSchema).optional().default([]),
+    /** Optional workspace directory for synthesis staging files. Defaults to `os.tmpdir() + '/jeeves-meta'`. */
+    workspaceDir: z.string().optional(),
+    /** Max retries when staging file not yet visible after session completion. Default: 10. */
+    stagingRetries: z.number().int().min(0).default(10),
+    /** Delay between staging file retries in ms. Default: 250. */
+    stagingRetryDelayMs: z.number().int().min(0).default(250),
+    /** Maximum number of delta files returned in /preview response. Default: 50. */
+    previewDeltaFilesCap: z.number().int().min(1).default(50),
 });
 
 /**
@@ -1467,12 +1475,16 @@ class GatewayExecutor {
     apiKey;
     pollIntervalMs;
     workspaceDir;
+    stagingRetries;
+    stagingRetryDelayMs;
     controller = new AbortController();
     constructor(options = {}) {
         this.gatewayUrl = (options.gatewayUrl ?? 'http://127.0.0.1:18789').replace(/\/+$/, '');
         this.apiKey = options.apiKey;
         this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
         this.workspaceDir = options.workspaceDir ?? join(tmpdir(), 'jeeves-meta');
+        this.stagingRetries = options.stagingRetries ?? 10;
+        this.stagingRetryDelayMs = options.stagingRetryDelayMs ?? 250;
     }
     /** Remove a temp output file if it exists. */
     cleanupOutputFile(outputPath) {
@@ -1702,10 +1714,23 @@ class GatewayExecutor {
                         // No output or partial output — throw for _state recovery (§3.16.6)
                         throw new SpawnTimeoutError('Gateway-side timeout detected (session status: timeout)', outputPath);
                     }
-                    // Normal completion — read output from file
+                    // Normal completion — read staging file with retry for delayed visibility
                     const output = this.readStagingFile(outputPath);
                     if (output !== undefined)
                         return { output, tokens };
+                    // Staging file not yet visible — retry with bounded grace window
+                    for (let i = 0; i < this.stagingRetries; i++) {
+                        await sleepAsync(this.stagingRetryDelayMs);
+                        // Check abort after yield point — signal may have been
+                        // set externally (e.g. operator abort) during the sleep.
+                        if (this.aborted) {
+                            this.cleanupOutputFile(outputPath);
+                            throw new SpawnAbortedError();
+                        }
+                        const retryOutput = this.readStagingFile(outputPath);
+                        if (retryOutput !== undefined)
+                            return { output: retryOutput, tokens };
+                    }
                     // Fallback: extract from message content if file wasn't written.
                     // Skip ANNOUNCE_SKIP sentinel messages — the real output is in
                     // a preceding assistant message (the file write).
@@ -4710,9 +4735,10 @@ function registerPreviewRoute(app, deps) {
                 ownedFiles: scopeFiles.length,
                 childMetas: targetNode.children.length,
                 deltaFiles: deltaFiles
-                    .slice(0, 50)
+                    .slice(0, config.previewDeltaFilesCap)
                     .map((f) => ({ path: f, action: 'modified' })),
                 deltaCount: deltaFiles.length,
+                deltaFilesTruncated: deltaFiles.length > config.previewDeltaFilesCap,
             },
             estimatedTokens,
             // New phase-state fields (additive)
@@ -5386,6 +5412,9 @@ async function startService(config, configPath) {
     const executor = new GatewayExecutor({
         gatewayUrl: config.gatewayUrl,
         apiKey: config.gatewayApiKey,
+        workspaceDir: config.workspaceDir,
+        stagingRetries: config.stagingRetries,
+        stagingRetryDelayMs: config.stagingRetryDelayMs,
     });
     // Runtime stats (mutable, shared with routes)
     const stats = {

package/dist/schema/config.d.ts

@@ -49,6 +49,10 @@ export declare const serviceConfigSchema: z.ZodObject<{
         crossRefs: z.ZodOptional<z.ZodArray<z.ZodString>>;
         parentDepth: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>>>;
+    workspaceDir: z.ZodOptional<z.ZodString>;
+    stagingRetries: z.ZodDefault<z.ZodNumber>;
+    stagingRetryDelayMs: z.ZodDefault<z.ZodNumber>;
+    previewDeltaFilesCap: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
 /** Inferred type for service configuration. */
 export type ServiceConfig = z.infer<typeof serviceConfigSchema>;

package/package.json

@@ -8,7 +8,7 @@
   },
   "dependencies": {
     "@karmaniverous/jeeves": "^0.5.12",
-    "@karmaniverous/jeeves-meta-core": "^0.2.0",
+    "@karmaniverous/jeeves-meta-core": "^0.2.1",
     "commander": "^14",
     "croner": "^10",
     "fastify": "^5.8",
@@ -110,5 +110,5 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "0.16.1"
+  "version": "0.16.2"
 }