@karmaniverous/jeeves-meta 0.15.4 → 0.15.6

package/dist/constants.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared constants for the jeeves-meta service package.
+ *
+ * @module constants
+ */
+/** Default HTTP port for the jeeves-meta service. */
+export declare const DEFAULT_PORT: 1938;
+/** Default port as a string (for Commander CLI defaults). */
+export declare const DEFAULT_PORT_STR: string;
+/** Service name identifier. */
+export declare const SERVICE_NAME = "jeeves-meta";
+/** Service version, read from package.json at startup. */
+export declare const SERVICE_VERSION: string;

package/dist/customCliCommands.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Custom CLI commands for the jeeves-meta service.
+ *
+ * Registered via `descriptor.customCliCommands` and added to the
+ * standard service CLI produced by `createServiceCli`.
+ *
+ * @module customCliCommands
+ */
+import { type Command } from 'commander';
+/** Build the full API URL for a given port string and path. */
+export declare function apiUrl(port: string, apiPath: string): string;
+/** Register all custom meta commands on the parent program. */
+export declare function registerCustomCliCommands(program: Command): void;

package/dist/descriptor.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Jeeves component descriptor for jeeves-meta.
+ *
+ * Single source of truth consumed by the service CLI, plugin writer, and
+ * config-apply pipeline.
+ *
+ * @module descriptor
+ */
+import { type JeevesComponentDescriptor } from '@karmaniverous/jeeves';
+import { RESTART_REQUIRED_FIELDS } from './configHotReload.js';
+import { loadServiceConfig } from './configLoader.js';
+import { type ServiceConfig } from './schema/config.js';
+export { RESTART_REQUIRED_FIELDS };
+/**
+ * Parsed jeeves-meta component descriptor.
+ */
+export declare const metaDescriptor: JeevesComponentDescriptor;
+export type { ServiceConfig };
+export { loadServiceConfig };

package/dist/discovery/buildMinimalNode.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Build a minimal MetaNode from a known meta path using watcher walk.
+ *
+ * Used for targeted synthesis (when a specific path is requested) to avoid
+ * the full discovery + ownership tree build. Discovers only immediate child
+ * `.meta/` directories.
+ *
+ * @module discovery/buildMinimalNode
+ */
+import type { WatcherClient } from '../interfaces/index.js';
+import type { MetaNode } from './types.js';
+/**
+ * Build a minimal MetaNode for a known meta path.
+ *
+ * Walks the owner directory for child `.meta/meta.json` files and constructs
+ * a shallow ownership tree (self + direct children only).
+ *
+ * @param metaPath - Absolute path to the `.meta/` directory.
+ * @param watcher - WatcherClient for filesystem enumeration.
+ * @returns MetaNode with direct children wired.
+ */
+export declare function buildMinimalNode(metaPath: string, watcher: WatcherClient): Promise<MetaNode>;

package/dist/discovery/computeSummary.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Compute summary statistics from an array of MetaEntry objects.
+ *
+ * Shared between listMetas() (full list) and route handlers (filtered lists).
+ *
+ * @module discovery/computeSummary
+ */
+import type { MetaListSummary } from '@karmaniverous/jeeves-meta-core';
+import type { MetaEntry } from './listMetas.js';
+/**
+ * Compute summary statistics from a list of meta entries.
+ *
+ * @param entries - Enriched meta entries (full or filtered).
+ * @param depthWeight - Config depth weight for effective staleness calculation.
+ * @returns Aggregated summary statistics.
+ */
+export declare function computeSummary(entries: MetaEntry[], depthWeight: number): MetaListSummary;

package/dist/discovery/discoverMetas.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Discover .meta/ directories via watcher `/walk` endpoint.
+ *
+ * Uses filesystem enumeration through the watcher (not Qdrant) to find
+ * all `.meta/meta.json` files and returns deduplicated meta directory paths.
+ *
+ * @module discovery/discoverMetas
+ */
+import type { WatcherClient } from '../interfaces/index.js';
+/**
+ * Discover all .meta/ directories via watcher walk.
+ *
+ * Uses the watcher's `/walk` endpoint to find all `.meta/meta.json` files
+ * and returns deduplicated meta directory paths.
+ *
+ * @param watcher - WatcherClient for walk queries.
+ * @returns Array of normalized .meta/ directory paths.
+ */
+export declare function discoverMetas(watcher: WatcherClient): Promise<string[]>;

package/dist/discovery/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Discovery module — glob .meta/ directories and build ownership tree.
+ *
+ * @module discovery
+ */
+export { computeSummary } from './computeSummary.js';
+export { discoverMetas } from './discoverMetas.js';
+export { listMetas, type MetaEntry, type MetaListResult, type MetaListSummary, } from './listMetas.js';
+export { buildOwnershipTree, findNode } from './ownershipTree.js';
+export { filterInScope, getDeltaFiles, getScopeFiles, getScopePrefix, } from './scope.js';
+export type { MetaNode, OwnershipTree } from './types.js';

package/dist/discovery/listMetas.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Unified meta listing: scan, dedup, enrich.
+ *
+ * Single source of truth for all consumers that need a list of metas
+ * with enriched metadata. Replaces duplicated scan+dedup logic in
+ * plugin tools, CLI, and prompt injection.
+ *
+ * @module discovery/listMetas
+ */
+import type { MetaListSummary } from '@karmaniverous/jeeves-meta-core';
+import type { WatcherClient } from '../interfaces/index.js';
+import type { MetaConfig, MetaJson } from '../schema/index.js';
+import type { MetaNode, OwnershipTree } from './types.js';
+/** Enriched meta entry returned by listMetas(). */
+export interface MetaEntry {
+    /** Normalized .meta/ directory path. */
+    path: string;
+    /** Tree depth (0 = leaf, higher = more abstract). */
+    depth: number;
+    /** Scheduling emphasis multiplier. */
+    emphasis: number;
+    /** Seconds since last synthesis, or Infinity if never synthesized. */
+    stalenessSeconds: number;
+    /** ISO timestamp of last synthesis, or null. */
+    lastSynthesized: string | null;
+    /** Whether the last synthesis had an error. */
+    hasError: boolean;
+    /** Whether this meta is currently locked. */
+    locked: boolean;
+    /** Whether this meta is disabled (skipped during staleness scheduling). */
+    disabled: boolean;
+    /** Cumulative architect tokens, or null if never run. */
+    architectTokens: number | null;
+    /** Cumulative builder tokens, or null if never run. */
+    builderTokens: number | null;
+    /** Cumulative critic tokens, or null if never run. */
+    criticTokens: number | null;
+    /** Number of direct children in the ownership tree. */
+    children: number;
+    /** The underlying MetaNode from the ownership tree. */
+    node: MetaNode;
+    /** The parsed meta.json content. */
+    meta: MetaJson;
+}
+export type { MetaListSummary };
+/** Full result from listMetas(). */
+export interface MetaListResult {
+    summary: MetaListSummary;
+    entries: MetaEntry[];
+    tree: OwnershipTree;
+}
+/**
+ * Discover, deduplicate, and enrich all metas.
+ *
+ * This is the single consolidated function that replaces all duplicated
+ * scan+dedup+enrich logic across the codebase. All enrichment comes from
+ * reading meta.json on disk (the canonical source).
+ *
+ * @param config - Validated synthesis config.
+ * @param watcher - Watcher HTTP client for discovery.
+ * @returns Enriched meta list with summary statistics and ownership tree.
+ */
+export declare function listMetas(config: MetaConfig, watcher: WatcherClient): Promise<MetaListResult>;

package/dist/discovery/ownershipTree.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Build the ownership tree from discovered .meta/ paths.
+ *
+ * Each .meta/ directory owns its parent directory and all descendants,
+ * except subtrees that contain their own .meta/. For those subtrees,
+ * the parent meta consumes the child meta's synthesis output.
+ *
+ * @module discovery/ownershipTree
+ */
+import type { MetaNode, OwnershipTree } from './types.js';
+/**
+ * Build an ownership tree from an array of .meta/ directory paths.
+ *
+ * @param metaPaths - Absolute paths to .meta/ directories.
+ * @returns The ownership tree with parent/child relationships.
+ */
+export declare function buildOwnershipTree(metaPaths: string[]): OwnershipTree;
+/**
+ * Find a node in the ownership tree by meta path or owner path.
+ *
+ * @param tree - The ownership tree to search.
+ * @param targetPath - Path to search for (meta path or owner path).
+ * @returns The matching node, or undefined if not found.
+ */
+export declare function findNode(tree: OwnershipTree, targetPath: string): MetaNode | undefined;

package/dist/discovery/scope.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Compute the file scope owned by a meta node.
+ *
+ * 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)
+ *
+ * All filesystem enumeration delegated to the watcher's `/walk` endpoint.
+ *
+ * @module discovery/scope
+ */
+import type { WatcherClient } from '../interfaces/index.js';
+import type { MinimalLogger } from '../logger/index.js';
+import type { MetaNode } from './types.js';
+/**
+ * Get the scope path prefix for a meta node.
+ */
+export declare function getScopePrefix(node: MetaNode): string;
+/**
+ * Filter a list of file paths to only those in scope for a meta node.
+ *
+ * Excludes:
+ * - The node's own .meta/ subtree (synthesis outputs are not scope inputs)
+ * - Child meta ownerPath subtrees (except child .meta/meta.json for rollups)
+ *
+ * Watcher walk returns normalized forward-slash paths.
+ */
+export declare function filterInScope(node: MetaNode, files: string[]): string[];
+/** Result of getScopeFiles. */
+interface ScopeFilesResult {
+    /** Files directly owned by this meta (excluding child subtrees and own .meta/). */
+    scopeFiles: string[];
+    /** All files under the owner path (including child subtrees). */
+    allFiles: string[];
+}
+/**
+ * Get all files in scope for a meta node via watcher walk.
+ */
+export declare function getScopeFiles(node: MetaNode, watcher: WatcherClient, logger?: MinimalLogger): Promise<ScopeFilesResult>;
+/**
+ * Get files modified since a given timestamp within a meta node's scope.
+ *
+ * If no generatedAt is provided (first run), returns all scope files.
+ * Reuses scope files from getScopeFiles() and filters locally by mtime.
+ */
+export declare function getDeltaFiles(generatedAt: string | undefined, scopeFiles: string[]): string[];
+export {};

package/dist/discovery/types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Types for meta discovery and ownership tree.
+ *
+ * @module discovery/types
+ */
+/** A discovered meta node in the ownership tree. */
+export interface MetaNode {
+    /** Absolute path to the .meta directory. */
+    metaPath: string;
+    /** Absolute path to the parent directory that this meta owns. */
+    ownerPath: string;
+    /** Depth in the ownership tree (root = 0). */
+    treeDepth: number;
+    /** Child meta nodes (subtrees with their own .meta/). */
+    children: MetaNode[];
+    /** Parent meta node, or null for roots. */
+    parent: MetaNode | null;
+}
+/** The full ownership tree discovered from watchPaths. */
+export interface OwnershipTree {
+    /** All discovered meta nodes, keyed by metaPath. */
+    nodes: Map<string, MetaNode>;
+    /** Root nodes (metas with no parent meta). */
+    roots: MetaNode[];
+}

package/dist/ema.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Exponential moving average helper for token tracking.
+ *
+ * @module ema
+ */
+/**
+ * Compute exponential moving average.
+ *
+ * @param current - New observation.
+ * @param previous - Previous EMA value, or undefined for first observation.
+ * @param decay - Decay factor (0-1). Higher = more weight on new value. Default 0.3.
+ * @returns Updated EMA.
+ */
+export declare function computeEma(current: number, previous: number | undefined, decay?: number): number;

package/dist/errors.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared error utilities.
+ *
+ * @module errors
+ */
+import type { MetaError } from './schema/index.js';
+/**
+ * Wrap an unknown caught value into a MetaError.
+ *
+ * @param step - Which synthesis step failed.
+ * @param err - The caught error value.
+ * @param code - Error classification code.
+ * @returns A structured MetaError.
+ */
+export declare function toMetaError(step: MetaError['step'], err: unknown, code?: string): MetaError;

package/dist/escapeGlob.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Escape special glob characters in a path so it can be used as a literal
+ * prefix in glob patterns.
+ *
+ * Glob metacharacters `* ? [ ] { } ( ) !` are escaped with a backslash so
+ * that paths containing parentheses (e.g. Slack channel IDs) or other
+ * special characters are matched literally by the watcher's walk endpoint.
+ *
+ * @module escapeGlob
+ */
+/**
+ * Escape glob metacharacters in a string using character-class wrapping.
+ *
+ * Backslash escaping (`\(`) does not work reliably on Windows where `\` is
+ * the path separator. Instead, each metacharacter is wrapped in a character
+ * class (e.g. `(` → `[(]`) which is universally supported by glob libraries.
+ *
+ * Square brackets themselves are escaped as `[[]` and `[]]`.
+ *
+ * @param s - Raw path string.
+ * @returns String with glob metacharacters wrapped in character classes.
+ */
+export declare function escapeGlob(s: string): string;

package/dist/executor/GatewayExecutor.d.ts

@@ -0,0 +1,48 @@
+/**
+ * MetaExecutor implementation using the OpenClaw gateway HTTP API.
+ *
+ * Lives in the library package so both plugin and runner can import it.
+ * Spawns sub-agent sessions via the gateway's `/tools/invoke` endpoint,
+ * polls for completion, and extracts output text.
+ *
+ * @module executor/GatewayExecutor
+ */
+import type { MetaExecutor, MetaSpawnOptions, MetaSpawnResult } from '../interfaces/index.js';
+/** Options for the GatewayExecutor. */
+export interface GatewayExecutorOptions {
+    /** OpenClaw gateway base URL. Default: http://127.0.0.1:18789 */
+    gatewayUrl?: string;
+    /** Bearer token for gateway authentication. */
+    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
+ * `/tools/invoke` endpoint.
+ *
+ * Used by both the OpenClaw plugin (in-process tool calls) and the
+ * runner/CLI (external invocation). Constructs from `gatewayUrl` and
+ * optional `apiKey` — typically sourced from `MetaConfig`.
+ */
+export declare class GatewayExecutor implements MetaExecutor {
+    private readonly gatewayUrl;
+    private readonly apiKey;
+    private readonly pollIntervalMs;
+    private readonly workspaceDir;
+    private controller;
+    constructor(options?: GatewayExecutorOptions);
+    /** Remove a temp output file if it exists. */
+    private cleanupOutputFile;
+    /** Invoke a gateway tool via the /tools/invoke HTTP endpoint. */
+    private invoke;
+    /** Look up session metadata (tokens, completion status) via sessions_list. */
+    private getSessionInfo;
+    /** Whether this executor has been aborted by the operator. */
+    get aborted(): boolean;
+    /** Abort the currently running spawn, if any. */
+    abort(): void;
+    spawn(task: string, options?: MetaSpawnOptions): Promise<MetaSpawnResult>;
+}

package/dist/executor/SpawnAbortedError.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Error thrown when a spawned subprocess is aborted via AbortController.
+ *
+ * @module executor/SpawnAbortedError
+ */
+/** Error indicating a spawn was deliberately aborted. */
+export declare class SpawnAbortedError extends Error {
+    constructor(message?: string);
+}

package/dist/executor/SpawnTimeoutError.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Error thrown when a spawned subprocess times out.
+ *
+ * Carries the output file path so callers can attempt partial output recovery.
+ *
+ * @module executor/SpawnTimeoutError
+ */
+/** Error indicating a spawn timeout with a recoverable output path. */
+export declare class SpawnTimeoutError extends Error {
+    /** Path to the (possibly partial) output file written before timeout. */
+    readonly outputPath: string;
+    constructor(message: string, outputPath: string);
+}

package/dist/executor/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Re-exports for the executor module.
+ *
+ * @module executor
+ */
+export { GatewayExecutor, type GatewayExecutorOptions, } from './GatewayExecutor.js';
+export { SpawnAbortedError } from './SpawnAbortedError.js';
+export { SpawnTimeoutError } from './SpawnTimeoutError.js';