@karmaniverous/jeeves-meta 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -41,6 +41,8 @@ declare function pruneArchive(metaPath: string, maxArchive: number): number;
 declare const synthConfigSchema: z.ZodObject<{
     watchPaths: z.ZodArray<z.ZodString>;
     watcherUrl: z.ZodURL;
+    gatewayUrl: z.ZodDefault<z.ZodURL>;
+    gatewayApiKey: z.ZodOptional<z.ZodString>;
     architectEvery: z.ZodDefault<z.ZodNumber>;
     depthWeight: z.ZodDefault<z.ZodNumber>;
     maxArchive: z.ZodDefault<z.ZodNumber>;
@@ -151,6 +153,28 @@ declare function readLatestArchive(metaPath: string): MetaJson | null;
  */
 declare function createSnapshot(metaPath: string, meta: MetaJson): string;
 
+/**
+ * Load and resolve jeeves-meta config with \@file: indirection.
+ *
+ * @module configLoader
+ */
+
+/**
+ * Load synth config from a JSON file, resolving \@file: references.
+ *
+ * @param configPath - Path to jeeves-meta.config.json.
+ * @returns Validated SynthConfig with resolved prompt strings.
+ */
+declare function loadSynthConfig(configPath: string): SynthConfig;
+/**
+ * Resolve config path from --config flag or JEEVES_META_CONFIG env var.
+ *
+ * @param args - CLI arguments (process.argv.slice(2)).
+ * @returns Resolved config path.
+ * @throws If no config path found.
+ */
+declare function resolveConfigPath(args: string[]): string;
+
 /**
  * Ensure meta.json exists in each .meta/ directory.
  *
@@ -226,6 +250,14 @@ interface OwnershipTree {
  * @returns The ownership tree with parent/child relationships.
  */
 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.
+ */
+declare function findNode(tree: OwnershipTree, targetPath: string): MetaNode | undefined;
 
 /**
  * Compute the file scope owned by a meta node.
@@ -372,8 +404,10 @@ interface ScanFile {
 }
 /** Parameters for a scan request. */
 interface ScanParams {
-    /** Required file path prefix to match. */
-    pathPrefix: string;
+    /** File path prefix to match. Required unless filter is provided. */
+    pathPrefix?: string;
+    /** Qdrant filter object for structural queries. */
+    filter?: Record<string, unknown>;
     /** Filter files modified after this Unix timestamp (seconds). */
     modifiedAfter?: number;
     /** Which payload fields to return (default: all). */
@@ -646,6 +680,40 @@ declare function createSynthEngine(config: SynthConfig, executor: SynthExecutor,
  */
 declare function toSynthError(step: SynthError['step'], err: unknown, code?: string): SynthError;
 
+/**
+ * SynthExecutor 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, polls for completion,
+ * and extracts output text.
+ *
+ * @module executor/GatewayExecutor
+ */
+
+/** Options for the GatewayExecutor. */
+interface GatewayExecutorOptions {
+    /** OpenClaw gateway base URL. Default: http://127.0.0.1:3000 */
+    gatewayUrl?: string;
+    /** API key for gateway authentication. */
+    apiKey?: string;
+    /** Polling interval in ms. Default: 5000. */
+    pollIntervalMs?: number;
+}
+/**
+ * SynthExecutor that spawns OpenClaw sessions via the gateway HTTP API.
+ *
+ * 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 `SynthConfig`.
+ */
+declare class GatewayExecutor implements SynthExecutor {
+    private readonly gatewayUrl;
+    private readonly apiKey;
+    private readonly pollIntervalMs;
+    constructor(options?: GatewayExecutorOptions);
+    spawn(task: string, options?: SynthSpawnOptions): Promise<SynthSpawnResult>;
+}
+
 /**
  * File-system lock for preventing concurrent synthesis on the same meta.
  *
@@ -675,6 +743,23 @@ declare function releaseLock(metaPath: string): void;
  */
 declare function isLocked(metaPath: string): boolean;
 
+/**
+ * Normalize file paths to forward slashes for consistency with watcher-indexed paths.
+ *
+ * Watcher indexes paths with forward slashes (`j:/domains/...`). This utility
+ * ensures all paths in the library use the same convention, regardless of
+ * the platform's native separator.
+ *
+ * @module normalizePath
+ */
+/**
+ * Normalize a file path to forward slashes.
+ *
+ * @param p - File path (may contain backslashes).
+ * @returns Path with all backslashes replaced by forward slashes.
+ */
+declare function normalizePath(p: string): string;
+
 /**
  * Paginated scan helper for exhaustive scope enumeration.
  *
@@ -768,6 +853,25 @@ declare function isStale(scopePrefix: string, meta: MetaJson, watcher: WatcherCl
  * @returns Staleness in seconds, or Infinity if never synthesized.
  */
 declare function actualStaleness(meta: MetaJson): number;
+/**
+ * Check whether the architect step should be triggered.
+ *
+ * @param meta - Current meta.json.
+ * @param structureChanged - Whether the structure hash changed.
+ * @param steerChanged - Whether the steer directive changed.
+ * @param architectEvery - Config: run architect every N cycles.
+ * @returns True if the architect step should run.
+ */
+declare function isArchitectTriggered(meta: MetaJson, structureChanged: boolean, steerChanged: boolean, architectEvery: number): boolean;
+/**
+ * Detect whether the steer directive changed since the last archive.
+ *
+ * @param currentSteer - Current _steer value (or undefined).
+ * @param archiveSteer - Archive _steer value (or undefined).
+ * @param hasArchive - Whether an archive snapshot exists.
+ * @returns True if steer changed.
+ */
+declare function hasSteerChanged(currentSteer: string | undefined, archiveSteer: string | undefined, hasArchive: boolean): boolean;
 
 /**
  * Compute a structure hash from a sorted file listing.
@@ -821,5 +925,5 @@ declare class HttpWatcherClient implements WatcherClient {
     unregisterRules(source: string): Promise<void>;
 }
 
-export { HttpWatcherClient, acquireLock, actualStaleness, buildArchitectTask, buildBuilderTask, buildContextPackage, buildCriticTask, buildOwnershipTree, computeEffectiveStaleness, computeEma, computeStructureHash, createSnapshot, createSynthEngine, ensureMetaJson, filterInScope, getScopeExclusions, getScopePrefix, globMetas, isLocked, isStale, listArchiveFiles, mergeAndWrite, metaJsonSchema, orchestrate, paginatedScan, parseArchitectOutput, parseBuilderOutput, parseCriticOutput, pruneArchive, readLatestArchive, releaseLock, selectCandidate, synthConfigSchema, synthErrorSchema, toSynthError };
-export type { BuilderOutput, HttpWatcherClientOptions, InferenceRuleSpec, MergeOptions, MetaJson, MetaNode, OrchestrateResult, OwnershipTree, ScanFile, ScanParams, ScanResponse, StalenessCandidate, SynthConfig, SynthContext, SynthEngine, SynthError, SynthExecutor, SynthSpawnOptions, SynthSpawnResult, WatcherClient };
+export { GatewayExecutor, HttpWatcherClient, acquireLock, actualStaleness, buildArchitectTask, buildBuilderTask, buildContextPackage, buildCriticTask, buildOwnershipTree, computeEffectiveStaleness, computeEma, computeStructureHash, createSnapshot, createSynthEngine, ensureMetaJson, filterInScope, findNode, getScopeExclusions, getScopePrefix, globMetas, hasSteerChanged, isArchitectTriggered, isLocked, isStale, listArchiveFiles, loadSynthConfig, mergeAndWrite, metaJsonSchema, normalizePath, orchestrate, paginatedScan, parseArchitectOutput, parseBuilderOutput, parseCriticOutput, pruneArchive, readLatestArchive, releaseLock, resolveConfigPath, selectCandidate, synthConfigSchema, synthErrorSchema, toSynthError };
+export type { BuilderOutput, GatewayExecutorOptions, HttpWatcherClientOptions, InferenceRuleSpec, MergeOptions, MetaJson, MetaNode, OrchestrateResult, OwnershipTree, ScanFile, ScanParams, ScanResponse, StalenessCandidate, SynthConfig, SynthContext, SynthEngine, SynthError, SynthExecutor, SynthSpawnOptions, SynthSpawnResult, WatcherClient };