@vectorize-io/hindsight-openclaw 0.5.1 → 0.6.0

package/dist/retain-queue.d.ts

@@ -0,0 +1,54 @@
+/**
+ * JSONL-backed retain queue for buffering failed HTTP retains.
+ *
+ * When the remote Hindsight API is unreachable, retain requests are stashed
+ * in a local JSONL file and flushed later. Only used in external API mode —
+ * the local daemon handles its own persistence.
+ *
+ * Zero runtime dependencies; uses only Node built-ins.
+ */
+/** The subset of a retain payload the queue needs to persist and replay. */
+export interface QueuedRetainPayload {
+    content: string;
+    documentId?: string;
+    metadata?: Record<string, unknown>;
+    tags?: string[];
+}
+export interface QueuedRetain {
+    id: string;
+    bankId: string;
+    content: string;
+    documentId: string;
+    metadata: Record<string, unknown>;
+    tags?: string[];
+    createdAt: string;
+}
+export interface RetainQueueOptions {
+    /** Path to the JSONL queue file. The parent directory must already exist. */
+    filePath: string;
+    /** Max age in ms for queued items. `-1` (default) keeps items forever. */
+    maxAgeMs?: number;
+}
+export declare class RetainQueue {
+    private readonly filePath;
+    private readonly maxAgeMs;
+    private cachedSize;
+    constructor(opts: RetainQueueOptions);
+    /** Append a failed retain for later delivery. */
+    enqueue(bankId: string, request: QueuedRetainPayload, metadata?: Record<string, unknown>): void;
+    /** Get up to `limit` oldest pending items (FIFO). */
+    peek(limit?: number): QueuedRetain[];
+    /** Remove a single item by id. */
+    remove(id: string): void;
+    /** Remove multiple items by id in a single file rewrite. */
+    removeMany(ids: string[]): void;
+    /** Number of items waiting (cached, O(1)). */
+    size(): number;
+    /** Drop items older than `maxAgeMs`. No-op when `maxAgeMs < 0`. */
+    cleanup(): number;
+    /** No-op — kept for API symmetry with DB-backed queues. */
+    close(): void;
+    private readAll;
+    /** Atomically rewrite the file with the given items. */
+    private writeAll;
+}

package/dist/retain-queue.js

@@ -0,0 +1,105 @@
+/**
+ * JSONL-backed retain queue for buffering failed HTTP retains.
+ *
+ * When the remote Hindsight API is unreachable, retain requests are stashed
+ * in a local JSONL file and flushed later. Only used in external API mode —
+ * the local daemon handles its own persistence.
+ *
+ * Zero runtime dependencies; uses only Node built-ins.
+ */
+import { readFileSync, writeFileSync, appendFileSync, existsSync, renameSync, unlinkSync, } from 'fs';
+import { randomBytes } from 'crypto';
+export class RetainQueue {
+    filePath;
+    maxAgeMs;
+    cachedSize;
+    constructor(opts) {
+        this.filePath = opts.filePath;
+        this.maxAgeMs = opts.maxAgeMs ?? -1;
+        this.cachedSize = this.readAll().length;
+    }
+    /** Append a failed retain for later delivery. */
+    enqueue(bankId, request, metadata) {
+        const item = {
+            id: `${Date.now()}-${randomBytes(4).toString('hex')}`,
+            bankId,
+            content: request.content,
+            documentId: request.documentId || 'conversation',
+            metadata: metadata || request.metadata || {},
+            tags: request.tags,
+            createdAt: new Date().toISOString(),
+        };
+        appendFileSync(this.filePath, JSON.stringify(item) + '\n', 'utf8');
+        this.cachedSize++;
+    }
+    /** Get up to `limit` oldest pending items (FIFO). */
+    peek(limit = 50) {
+        return this.readAll().slice(0, limit);
+    }
+    /** Remove a single item by id. */
+    remove(id) {
+        const items = this.readAll().filter((i) => i.id !== id);
+        this.writeAll(items);
+    }
+    /** Remove multiple items by id in a single file rewrite. */
+    removeMany(ids) {
+        const idSet = new Set(ids);
+        const items = this.readAll().filter((i) => !idSet.has(i.id));
+        this.writeAll(items);
+    }
+    /** Number of items waiting (cached, O(1)). */
+    size() {
+        return this.cachedSize;
+    }
+    /** Drop items older than `maxAgeMs`. No-op when `maxAgeMs < 0`. */
+    cleanup() {
+        if (this.maxAgeMs < 0)
+            return 0;
+        const cutoff = Date.now() - this.maxAgeMs;
+        const items = this.readAll();
+        const kept = items.filter((i) => new Date(i.createdAt).getTime() >= cutoff);
+        const removed = items.length - kept.length;
+        if (removed > 0)
+            this.writeAll(kept);
+        return removed;
+    }
+    /** No-op — kept for API symmetry with DB-backed queues. */
+    close() {
+        /* nothing to close */
+    }
+    // -------------------------------------------------------------------------
+    readAll() {
+        if (!existsSync(this.filePath))
+            return [];
+        const content = readFileSync(this.filePath, 'utf8').trim();
+        if (!content)
+            return [];
+        const items = [];
+        for (const line of content.split('\n')) {
+            try {
+                items.push(JSON.parse(line));
+            }
+            catch {
+                // skip malformed lines
+            }
+        }
+        return items;
+    }
+    /** Atomically rewrite the file with the given items. */
+    writeAll(items) {
+        if (items.length === 0) {
+            try {
+                unlinkSync(this.filePath);
+            }
+            catch {
+                /* already gone */
+            }
+            this.cachedSize = 0;
+            return;
+        }
+        const tmpPath = this.filePath + '.tmp';
+        writeFileSync(tmpPath, items.map((i) => JSON.stringify(i)).join('\n') + '\n', 'utf8');
+        renameSync(tmpPath, this.filePath);
+        this.cachedSize = items.length;
+    }
+}

package/dist/session-patterns.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Compile a session glob into a regex.
+ *
+ * `*` matches any non-colon characters, while `**` can span colons.
+ */
+export declare function compileSessionPattern(pattern: string): RegExp;
+/** Compile all configured ignore patterns once at startup. */
+export declare function compileSessionPatterns(patterns: string[]): RegExp[];
+/** Check whether a session key matches any compiled ignore pattern. */
+export declare function matchesSessionPattern(sessionKey: string, patterns: RegExp[]): boolean;

package/dist/session-patterns.js

@@ -0,0 +1,21 @@
+/**
+ * Compile a session glob into a regex.
+ *
+ * `*` matches any non-colon characters, while `**` can span colons.
+ */
+export function compileSessionPattern(pattern) {
+    const escaped = pattern
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*\*/g, "\u0000")
+        .replace(/\*/g, "[^:]*")
+        .replace(/\u0000/g, ".*");
+    return new RegExp(`^${escaped}$`);
+}
+/** Compile all configured ignore patterns once at startup. */
+export function compileSessionPatterns(patterns) {
+    return patterns.map((pattern) => compileSessionPattern(pattern));
+}
+/** Check whether a session key matches any compiled ignore pattern. */
+export function matchesSessionPattern(sessionKey, patterns) {
+    return patterns.some((pattern) => pattern.test(sessionKey));
+}

package/dist/setup-lib.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Pure helpers behind the Hindsight OpenClaw setup wizard. Kept separate from
+ * setup.ts (the @clack/prompts entry point) so the mechanical bits are easy to
+ * unit test without simulating an interactive terminal.
+ *
+ * Scanner-safe: imports no subprocess APIs and does not read any environment
+ * variable. All config writing is an atomic rename over the OpenClaw config JSON.
+ */
+export declare const PLUGIN_ID = "hindsight-openclaw";
+/**
+ * Default Hindsight Cloud endpoint. Update this when the hosted service URL is
+ * finalized, or users can override it at the prompt.
+ */
+export declare const HINDSIGHT_CLOUD_URL = "https://api.hindsight.vectorize.io";
+export declare const DEFAULT_OPENCLAW_CONFIG_PATH: string;
+export interface SecretRef {
+    source: 'env' | 'file' | 'exec';
+    provider: string;
+    id: string;
+}
+export interface PluginEntry {
+    enabled?: boolean;
+    config?: Record<string, unknown>;
+}
+export interface OpenClawConfigShape {
+    plugins?: {
+        entries?: Record<string, PluginEntry>;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+export type SetupMode = 'cloud' | 'api' | 'embedded';
+export declare const NO_KEY_PROVIDERS: ReadonlySet<string>;
+export declare function loadConfig(path: string): Promise<OpenClawConfigShape>;
+export declare function saveConfig(path: string, cfg: OpenClawConfigShape): Promise<void>;
+/**
+ * Ensure a `plugins.entries["hindsight-openclaw"].config` object exists, set
+ * `enabled: true`, and return the mutable config record. Idempotent — safe to
+ * call against a fresh or already-configured OpenClaw config.
+ */
+export declare function ensurePluginConfig(cfg: OpenClawConfigShape): Record<string, unknown>;
+export declare function envSecretRef(id: string): SecretRef;
+export declare function clearCloudFields(pluginConfig: Record<string, unknown>): void;
+export declare function clearLocalLlmFields(pluginConfig: Record<string, unknown>): void;
+export declare function isValidEnvVarName(value: string | undefined): boolean;
+export declare function defaultApiKeyEnvVar(provider: string): string;
+export interface CloudSetupInput {
+    apiUrl?: string;
+    tokenEnvVar: string;
+}
+export interface ApiSetupInput {
+    apiUrl: string;
+    tokenEnvVar?: string;
+}
+export interface EmbeddedSetupInput {
+    llmProvider: string;
+    apiKeyEnvVar?: string;
+    llmModel?: string;
+}
+/**
+ * Apply the Cloud mode to a plugin config in place: sets `hindsightApiUrl` and
+ * a `hindsightApiToken` SecretRef, strips any leftover local-LLM fields so we
+ * don't carry stale credentials across mode switches.
+ */
+export declare function applyCloudMode(pluginConfig: Record<string, unknown>, input: CloudSetupInput): void;
+/**
+ * Apply the external-API mode to a plugin config in place: sets a required
+ * `hindsightApiUrl`, optional `hindsightApiToken` SecretRef, and strips any
+ * leftover local-LLM fields so mode switches don't carry stale state.
+ */
+export declare function applyApiMode(pluginConfig: Record<string, unknown>, input: ApiSetupInput): void;
+/**
+ * Apply the embedded-daemon mode to a plugin config in place: sets
+ * `llmProvider`, optional `llmApiKey` SecretRef, optional `llmModel`, and
+ * strips any external-API settings so mode switches don't carry stale state.
+ */
+export declare function applyEmbeddedMode(pluginConfig: Record<string, unknown>, input: EmbeddedSetupInput): void;
+export declare function summarizeCloud(input: CloudSetupInput): string;
+export declare function summarizeApi(input: ApiSetupInput): string;
+export declare function summarizeEmbedded(input: EmbeddedSetupInput): string;

package/dist/setup-lib.js

@@ -0,0 +1,134 @@
+/**
+ * Pure helpers behind the Hindsight OpenClaw setup wizard. Kept separate from
+ * setup.ts (the @clack/prompts entry point) so the mechanical bits are easy to
+ * unit test without simulating an interactive terminal.
+ *
+ * Scanner-safe: imports no subprocess APIs and does not read any environment
+ * variable. All config writing is an atomic rename over the OpenClaw config JSON.
+ */
+import { readFile, writeFile, mkdir, rename } from 'fs/promises';
+import { homedir } from 'os';
+import { join, dirname } from 'path';
+export const PLUGIN_ID = 'hindsight-openclaw';
+/**
+ * Default Hindsight Cloud endpoint. Update this when the hosted service URL is
+ * finalized, or users can override it at the prompt.
+ */
+export const HINDSIGHT_CLOUD_URL = 'https://api.hindsight.vectorize.io';
+export const DEFAULT_OPENCLAW_CONFIG_PATH = join(homedir(), '.openclaw', 'openclaw.json');
+export const NO_KEY_PROVIDERS = new Set([
+    'claude-code',
+    'openai-codex',
+    'ollama',
+]);
+export async function loadConfig(path) {
+    try {
+        const raw = await readFile(path, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT')
+            return {};
+        throw new Error(`Failed to read ${path}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+export async function saveConfig(path, cfg) {
+    await mkdir(dirname(path), { recursive: true });
+    const serialized = `${JSON.stringify(cfg, null, 2)}\n`;
+    const tmpPath = `${path}.tmp-${Date.now()}`;
+    await writeFile(tmpPath, serialized, 'utf8');
+    await rename(tmpPath, path);
+}
+/**
+ * Ensure a `plugins.entries["hindsight-openclaw"].config` object exists, set
+ * `enabled: true`, and return the mutable config record. Idempotent — safe to
+ * call against a fresh or already-configured OpenClaw config.
+ */
+export function ensurePluginConfig(cfg) {
+    const plugins = (cfg.plugins ??= {});
+    const entries = (plugins.entries ??= {});
+    const entry = (entries[PLUGIN_ID] ??= { enabled: true });
+    entry.enabled = true;
+    return (entry.config ??= {});
+}
+export function envSecretRef(id) {
+    return { source: 'env', provider: 'default', id };
+}
+export function clearCloudFields(pluginConfig) {
+    delete pluginConfig.hindsightApiUrl;
+    delete pluginConfig.hindsightApiToken;
+}
+export function clearLocalLlmFields(pluginConfig) {
+    delete pluginConfig.llmProvider;
+    delete pluginConfig.llmModel;
+    delete pluginConfig.llmApiKey;
+    delete pluginConfig.llmBaseUrl;
+}
+const ENV_VAR_RE = /^[A-Z][A-Z0-9_]*$/;
+export function isValidEnvVarName(value) {
+    return !!value && ENV_VAR_RE.test(value.trim());
+}
+export function defaultApiKeyEnvVar(provider) {
+    return `${provider.toUpperCase().replace(/-/g, '_')}_API_KEY`;
+}
+/**
+ * Apply the Cloud mode to a plugin config in place: sets `hindsightApiUrl` and
+ * a `hindsightApiToken` SecretRef, strips any leftover local-LLM fields so we
+ * don't carry stale credentials across mode switches.
+ */
+export function applyCloudMode(pluginConfig, input) {
+    clearLocalLlmFields(pluginConfig);
+    pluginConfig.hindsightApiUrl = (input.apiUrl ?? HINDSIGHT_CLOUD_URL).trim();
+    pluginConfig.hindsightApiToken = envSecretRef(input.tokenEnvVar.trim());
+}
+/**
+ * Apply the external-API mode to a plugin config in place: sets a required
+ * `hindsightApiUrl`, optional `hindsightApiToken` SecretRef, and strips any
+ * leftover local-LLM fields so mode switches don't carry stale state.
+ */
+export function applyApiMode(pluginConfig, input) {
+    clearLocalLlmFields(pluginConfig);
+    pluginConfig.hindsightApiUrl = input.apiUrl.trim();
+    if (input.tokenEnvVar && input.tokenEnvVar.trim().length > 0) {
+        pluginConfig.hindsightApiToken = envSecretRef(input.tokenEnvVar.trim());
+    }
+    else {
+        delete pluginConfig.hindsightApiToken;
+    }
+}
+/**
+ * Apply the embedded-daemon mode to a plugin config in place: sets
+ * `llmProvider`, optional `llmApiKey` SecretRef, optional `llmModel`, and
+ * strips any external-API settings so mode switches don't carry stale state.
+ */
+export function applyEmbeddedMode(pluginConfig, input) {
+    clearCloudFields(pluginConfig);
+    pluginConfig.llmProvider = input.llmProvider;
+    if (NO_KEY_PROVIDERS.has(input.llmProvider)) {
+        delete pluginConfig.llmApiKey;
+    }
+    else {
+        if (!input.apiKeyEnvVar) {
+            throw new Error(`llmProvider "${input.llmProvider}" requires an apiKeyEnvVar`);
+        }
+        pluginConfig.llmApiKey = envSecretRef(input.apiKeyEnvVar.trim());
+    }
+    if (input.llmModel && input.llmModel.trim().length > 0) {
+        pluginConfig.llmModel = input.llmModel.trim();
+    }
+    else {
+        delete pluginConfig.llmModel;
+    }
+}
+export function summarizeCloud(input) {
+    const url = (input.apiUrl ?? HINDSIGHT_CLOUD_URL).trim();
+    return `Cloud → ${url} (token from \${${input.tokenEnvVar.trim()}})`;
+}
+export function summarizeApi(input) {
+    const suffix = input.tokenEnvVar ? ' (authenticated)' : ' (no auth)';
+    return `External API → ${input.apiUrl.trim()}${suffix}`;
+}
+export function summarizeEmbedded(input) {
+    const keyHint = NO_KEY_PROVIDERS.has(input.llmProvider) ? '' : ' (key via SecretRef)';
+    return `Embedded daemon → ${input.llmProvider}${keyHint}`;
+}

package/dist/setup.d.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * Setup wizard for the Hindsight OpenClaw plugin.
+ *
+ * Two modes of operation:
+ *
+ *   1. Interactive — no flags, just run `hindsight-openclaw-setup`. Walks the
+ *      user through picking a mode (Cloud / External API / Embedded daemon)
+ *      via @clack/prompts and writes openclaw.json.
+ *
+ *   2. Non-interactive — pass `--mode cloud|api|embedded` plus the relevant
+ *      flags for that mode. No prompts, intended for CI and scripted installs.
+ *
+ * Scanner-safe: does not import subprocess APIs and does not read environment
+ * variables directly. Pure config manipulation lives in setup-lib.ts.
+ */
+import { type SetupMode } from './setup-lib.js';
+export interface ParsedCliArgs {
+    help: boolean;
+    configPath?: string;
+    mode?: SetupMode;
+    apiUrl?: string;
+    tokenEnv?: string;
+    noToken: boolean;
+    provider?: string;
+    apiKeyEnv?: string;
+    model?: string;
+    positional?: string;
+}
+export declare function parseCliArgs(argv: string[]): ParsedCliArgs;
+export declare function runNonInteractive(args: ParsedCliArgs, configPath: string): Promise<{
+    summary: string;
+    configPath: string;
+}>;