@karmaniverous/jeeves-meta 0.4.0 → 0.4.2

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 import { z } from 'zod';
 import pino, { Logger } from 'pino';
-import { FastifyInstance } from 'fastify';
+import * as fastify from 'fastify';
+import { FastifyInstance, FastifyBaseLogger } from 'fastify';
+import * as node_http from 'node:http';
 
 /**
  * List archive snapshot files in chronological order.
@@ -183,6 +185,20 @@ declare function readLatestArchive(metaPath: string): MetaJson | null;
  */
 declare function createSnapshot(metaPath: string, meta: MetaJson): string;
 
+/**
+ * Shared constants for the jeeves-meta service package.
+ *
+ * @module constants
+ */
+/** Default HTTP port for the jeeves-meta service. */
+declare const DEFAULT_PORT = 1938;
+/** Default port as a string (for Commander CLI defaults). */
+declare const DEFAULT_PORT_STR: string;
+/** Service name identifier. */
+declare const SERVICE_NAME = "jeeves-meta";
+/** Service version, read from package.json at startup. */
+declare const SERVICE_VERSION: string;
+
 /**
  * Load and resolve jeeves-meta service config.
  *
@@ -369,6 +385,34 @@ interface WatcherClient {
     unregisterRules(source: string): Promise<void>;
 }
 
+/**
+ * Pino logger factory.
+ *
+ * @module logger
+ */
+
+/** Minimal logger interface accepted by library functions. */
+interface MinimalLogger {
+    debug: (obj: Record<string, unknown>, msg: string) => void;
+    info: (obj: Record<string, unknown>, msg: string) => void;
+    warn: (obj: Record<string, unknown>, msg: string) => void;
+    error: (obj: Record<string, unknown>, msg: string) => void;
+}
+/** Logger configuration options. */
+interface LoggerConfig {
+    /** Log level (default: 'info'). */
+    level?: string;
+    /** Optional file path to write logs to. */
+    file?: string;
+}
+/**
+ * Create a pino logger instance.
+ *
+ * @param config - Optional logger configuration.
+ * @returns Configured pino logger.
+ */
+declare function createLogger(config?: LoggerConfig): pino.Logger;
+
 /**
  * Discover .meta/ directories via watcher scan.
  *
@@ -399,7 +443,7 @@ declare function buildMetaFilter(config: MetaConfig): Record<string, unknown>;
  * @param watcher - WatcherClient for scan queries.
  * @returns Array of normalized .meta/ directory paths.
  */
-declare function discoverMetas(config: MetaConfig, watcher: WatcherClient): Promise<string[]>;
+declare function discoverMetas(config: MetaConfig, watcher: WatcherClient, logger?: MinimalLogger): Promise<string[]>;
 
 /**
  * Types for meta discovery and ownership tree.
@@ -499,7 +543,7 @@ interface MetaListResult {
  * @param watcher - Watcher HTTP client for discovery.
  * @returns Enriched meta list with summary statistics and ownership tree.
  */
-declare function listMetas(config: MetaConfig, watcher: WatcherClient): Promise<MetaListResult>;
+declare function listMetas(config: MetaConfig, watcher: WatcherClient, logger?: MinimalLogger): Promise<MetaListResult>;
 
 /**
  * Build the ownership tree from discovered .meta/ paths.
@@ -530,31 +574,27 @@ declare function findNode(tree: OwnershipTree, targetPath: string): MetaNode | u
 /**
  * Compute the file scope owned by a meta node.
  *
- * A meta owns: parent dir + all descendants, minus child .meta/ subtrees.
- * For child subtrees, it consumes the child's .meta/meta.json as a rollup input.
+ * A meta owns: parent dir + all descendants, minus:
+ * - Its own .meta/ subtree (outputs, not inputs)
+ * - Child meta ownerPath subtrees (except their .meta/meta.json for rollups)
+ *
+ * Uses filesystem walks instead of watcher scans for performance.
  *
  * @module discovery/scope
  */
 
 /**
  * Get the scope path prefix for a meta node.
- *
- * This is the ownerPath — all files under this path are in scope,
- * except subtrees owned by child metas.
- *
- * @param node - The meta node to compute scope for.
- * @returns The scope path prefix.
  */
 declare function getScopePrefix(node: MetaNode): string;
 /**
  * Filter a list of file paths to only those in scope for a meta node.
  *
- * Includes files under ownerPath, excludes files under child meta ownerPaths,
- * but includes child .meta/meta.json files as rollup inputs.
+ * Excludes:
+ * - The node's own .meta/ subtree (synthesis outputs are not scope inputs)
+ * - Child meta ownerPath subtrees (except child .meta/meta.json for rollups)
  *
- * @param node - The meta node.
- * @param files - Array of file paths to filter.
- * @returns Filtered array of in-scope file paths.
+ * walkFiles already returns normalized forward-slash paths.
  */
 declare function filterInScope(node: MetaNode, files: string[]): string[];
 
@@ -690,7 +730,7 @@ declare function normalizePath(p: string): string;
  * @param params - Base scan parameters (cursor is managed internally).
  * @returns All matching files across all pages.
  */
-declare function paginatedScan(watcher: WatcherClient, params: Omit<ScanParams, 'cursor'>): Promise<ScanFile[]>;
+declare function paginatedScan(watcher: WatcherClient, params: Omit<ScanParams, 'cursor'>, logger?: MinimalLogger): Promise<ScanFile[]>;
 
 /**
  * Compute a structure hash from a sorted file listing.
@@ -708,6 +748,32 @@ declare function paginatedScan(watcher: WatcherClient, params: Omit<ScanParams,
  */
 declare function computeStructureHash(filePaths: string[]): string;
 
+/**
+ * Recursive filesystem walker for file enumeration.
+ *
+ * Replaces paginated watcher scans for scope/delta/staleness checks.
+ * Returns normalized forward-slash paths.
+ *
+ * @module walkFiles
+ */
+/** Options for walkFiles. */
+interface WalkFilesOptions {
+    /** Directory names to exclude (in addition to defaults). */
+    exclude?: string[];
+    /** Only include files modified after this Unix timestamp (seconds). */
+    modifiedAfter?: number;
+    /** Maximum recursion depth. Default: 50. */
+    maxDepth?: number;
+}
+/**
+ * Recursively walk a directory and return all file paths.
+ *
+ * @param root - Root directory to walk.
+ * @param options - Walk options.
+ * @returns Array of normalized file paths.
+ */
+declare function walkFiles(root: string, options?: WalkFilesOptions): string[];
+
 /**
  * MetaExecutor implementation using the OpenClaw gateway HTTP API.
  *
@@ -726,6 +792,8 @@ interface GatewayExecutorOptions {
     apiKey?: string;
     /** Polling interval in ms. Default: 5000. */
     pollIntervalMs?: number;
+    /** Workspace directory for output staging. Default: OS temp dir + /jeeves-meta. */
+    workspaceDir?: string;
 }
 /**
  * MetaExecutor that spawns OpenClaw sessions via the gateway's
@@ -739,33 +807,15 @@ declare class GatewayExecutor implements MetaExecutor {
     private readonly gatewayUrl;
     private readonly apiKey;
     private readonly pollIntervalMs;
+    private readonly workspaceDir;
     constructor(options?: GatewayExecutorOptions);
     /** Invoke a gateway tool via the /tools/invoke HTTP endpoint. */
     private invoke;
+    /** Look up totalTokens for a session via sessions_list. */
+    private getSessionTokens;
     spawn(task: string, options?: MetaSpawnOptions): Promise<MetaSpawnResult>;
 }
 
-/**
- * Pino logger factory.
- *
- * @module logger
- */
-
-/** Logger configuration options. */
-interface LoggerConfig {
-    /** Log level (default: 'info'). */
-    level?: string;
-    /** Optional file path to write logs to. */
-    file?: string;
-}
-/**
- * Create a pino logger instance.
- *
- * @param config - Optional logger configuration.
- * @returns Configured pino logger.
- */
-declare function createLogger(config?: LoggerConfig): pino.Logger;
-
 /**
  * Build task prompts for each synthesis step.
  *
@@ -817,7 +867,7 @@ declare function buildCriticTask(ctx: MetaContext, meta: MetaJson, config: MetaC
  * @param watcher - WatcherClient for scope enumeration.
  * @returns The computed context package.
  */
-declare function buildContextPackage(node: MetaNode, meta: MetaJson, watcher: WatcherClient): Promise<MetaContext>;
+declare function buildContextPackage(node: MetaNode, meta: MetaJson): MetaContext;
 
 /**
  * Parse subprocess outputs for each synthesis step.
@@ -918,7 +968,8 @@ declare function mergeAndWrite(options: MergeOptions): MetaJson;
 type ProgressPhase = 'architect' | 'builder' | 'critic';
 type ProgressEvent = {
     type: 'synthesis_start' | 'phase_start' | 'phase_complete' | 'synthesis_complete' | 'error';
-    metaPath: string;
+    /** Owner path (not .meta path) of the entity being synthesized. */
+    path: string;
     phase?: ProgressPhase;
     tokens?: number;
     durationMs?: number;
@@ -970,7 +1021,7 @@ interface OrchestrateResult {
  * @param targetPath - Optional: specific meta/owner path to synthesize instead of stalest candidate.
  * @returns Array with a single result.
  */
-declare function orchestrate(config: MetaConfig, executor: MetaExecutor, watcher: WatcherClient, targetPath?: string, onProgress?: ProgressCallback): Promise<OrchestrateResult[]>;
+declare function orchestrate(config: MetaConfig, executor: MetaExecutor, watcher: WatcherClient, targetPath?: string, onProgress?: ProgressCallback, logger?: MinimalLogger): Promise<OrchestrateResult[]>;
 
 /**
  * Weighted staleness formula for candidate selection.
@@ -1042,12 +1093,16 @@ declare function selectCandidate(candidates: StalenessCandidate[]): StalenessCan
  * @param watcher - WatcherClient instance.
  * @returns True if any file in scope was modified after _generatedAt.
  */
-declare function isStale(scopePrefix: string, meta: MetaJson, watcher: WatcherClient): Promise<boolean>;
+declare function isStale(scopePrefix: string, meta: MetaJson): boolean;
 /**
  * Compute actual staleness in seconds (now minus _generatedAt).
  *
+ * Never-synthesized metas are capped at {@link MAX_STALENESS_SECONDS}
+ * (1 year) so that depth weighting can differentiate them. Without
+ * bounding, `Infinity * depthFactor` = `Infinity` for all depths.
+ *
  * @param meta - Current meta.json content.
- * @returns Staleness in seconds, or Infinity if never synthesized.
+ * @returns Staleness in seconds, capped at 1 year for never-synthesized metas.
  */
 declare function actualStaleness(meta: MetaJson): number;
 /**
@@ -1233,6 +1288,8 @@ interface HttpWatcherClientOptions {
     backoffBaseMs?: number;
     /** Multiplier for backoff. Default: 4 (1s, 4s, 16s). */
     backoffFactor?: number;
+    /** Per-request timeout in ms. Default: 10000. */
+    timeoutMs?: number;
 }
 /**
  * HTTP-based WatcherClient implementation with retry.
@@ -1242,6 +1299,7 @@ declare class HttpWatcherClient implements WatcherClient {
     private readonly maxRetries;
     private readonly backoffBaseMs;
     private readonly backoffFactor;
+    private readonly timeoutMs;
     constructor(options: HttpWatcherClientOptions);
     /** POST JSON with retry. */
     private post;
@@ -1332,12 +1390,6 @@ declare function registerRoutes(app: FastifyInstance, deps: RouteDeps): void;
 /** Sleep for a given number of milliseconds. */
 declare function sleep(ms: number): Promise<void>;
 
-/**
- * Minimal Fastify HTTP server for jeeves-meta service.
- *
- * @module server
- */
-
 /** Options for creating the server. */
 interface ServerOptions {
     /** Pino logger instance. */
@@ -1359,7 +1411,9 @@ interface ServerOptions {
  * @param options - Server creation options.
  * @returns Configured Fastify instance (not yet listening).
  */
-declare function createServer(options: ServerOptions): FastifyInstance;
+declare function createServer(options: ServerOptions): fastify.FastifyInstance<node_http.Server<typeof node_http.IncomingMessage, typeof node_http.ServerResponse>, node_http.IncomingMessage, node_http.ServerResponse<node_http.IncomingMessage>, FastifyBaseLogger, fastify.FastifyTypeProviderDefault> & PromiseLike<fastify.FastifyInstance<node_http.Server<typeof node_http.IncomingMessage, typeof node_http.ServerResponse>, node_http.IncomingMessage, node_http.ServerResponse<node_http.IncomingMessage>, FastifyBaseLogger, fastify.FastifyTypeProviderDefault>> & {
+    __linterBrands: "SafePromiseLike";
+};
 
 /**
  * Graceful shutdown handler.
@@ -1370,7 +1424,9 @@ declare function createServer(options: ServerOptions): FastifyInstance;
  */
 
 interface ShutdownDeps {
-    server: FastifyInstance;
+    server: {
+        close: () => Promise<void>;
+    };
     scheduler: Scheduler | null;
     queue: SynthesisQueue;
     logger: Logger;
@@ -1403,5 +1459,5 @@ declare function registerShutdownHandlers(deps: ShutdownDeps): void;
  */
 declare function startService(config: ServiceConfig, configPath?: string): Promise<void>;
 
-export { GatewayExecutor, HttpWatcherClient, ProgressReporter, RuleRegistrar, Scheduler, SynthesisQueue, acquireLock, actualStaleness, buildArchitectTask, buildBuilderTask, buildContextPackage, buildCriticTask, buildMetaFilter, buildOwnershipTree, cleanupStaleLocks, computeEffectiveStaleness, computeEma, computeStructureHash, createLogger, createServer, createSnapshot, discoverMetas, filterInScope, findNode, formatProgressEvent, getScopePrefix, hasSteerChanged, isArchitectTriggered, isLocked, isStale, listArchiveFiles, listMetas, loadServiceConfig, mergeAndWrite, metaConfigSchema, metaErrorSchema, metaJsonSchema, normalizePath, orchestrate, paginatedScan, parseArchitectOutput, parseBuilderOutput, parseCriticOutput, pruneArchive, readLatestArchive, readLockState, registerRoutes, registerShutdownHandlers, releaseLock, resolveConfigPath, resolveMetaDir, selectCandidate, serviceConfigSchema, sleep, startService, toMetaError };
-export type { BuilderOutput, EnqueueResult, GatewayExecutorOptions, HttpWatcherClientOptions, InferenceRuleSpec, LockState, LoggerConfig, MergeOptions, MetaConfig, MetaContext, MetaEntry, MetaError, MetaExecutor, MetaJson, MetaListResult, MetaListSummary, MetaNode, MetaSpawnOptions, MetaSpawnResult, OrchestrateResult, OwnershipTree, ProgressCallback, ProgressEvent, ProgressPhase, ProgressReporterConfig, QueueItem, QueueState, RouteDeps, ScanFile, ScanParams, ScanResponse, ServerOptions, ServiceConfig, ServiceStats, StalenessCandidate, WatcherClient };
+export { DEFAULT_PORT, DEFAULT_PORT_STR, GatewayExecutor, HttpWatcherClient, ProgressReporter, RuleRegistrar, SERVICE_NAME, SERVICE_VERSION, Scheduler, SynthesisQueue, acquireLock, actualStaleness, buildArchitectTask, buildBuilderTask, buildContextPackage, buildCriticTask, buildMetaFilter, buildOwnershipTree, cleanupStaleLocks, computeEffectiveStaleness, computeEma, computeStructureHash, createLogger, createServer, createSnapshot, discoverMetas, filterInScope, findNode, formatProgressEvent, getScopePrefix, hasSteerChanged, isArchitectTriggered, isLocked, isStale, listArchiveFiles, listMetas, loadServiceConfig, mergeAndWrite, metaConfigSchema, metaErrorSchema, metaJsonSchema, normalizePath, orchestrate, paginatedScan, parseArchitectOutput, parseBuilderOutput, parseCriticOutput, pruneArchive, readLatestArchive, readLockState, registerRoutes, registerShutdownHandlers, releaseLock, resolveConfigPath, resolveMetaDir, selectCandidate, serviceConfigSchema, sleep, startService, toMetaError, walkFiles };
+export type { BuilderOutput, EnqueueResult, GatewayExecutorOptions, HttpWatcherClientOptions, InferenceRuleSpec, LockState, LoggerConfig, MergeOptions, MetaConfig, MetaContext, MetaEntry, MetaError, MetaExecutor, MetaJson, MetaListResult, MetaListSummary, MetaNode, MetaSpawnOptions, MetaSpawnResult, MinimalLogger, OrchestrateResult, OwnershipTree, ProgressCallback, ProgressEvent, ProgressPhase, ProgressReporterConfig, QueueItem, QueueState, RouteDeps, ScanFile, ScanParams, ScanResponse, ServerOptions, ServiceConfig, ServiceStats, StalenessCandidate, WatcherClient };