@etzelm/openclaw-memory-hindsight 0.0.0-stage → 0.1.1

package/dist/index.js

@@ -0,0 +1,253 @@
+import { createHash } from "node:crypto";
+import { formatErrorMessage } from "openclaw/plugin-sdk/error-runtime";
+import { definePluginEntry, } from "openclaw/plugin-sdk/plugin-entry";
+import { isIncognitoSessionKey } from "openclaw/plugin-sdk/routing";
+import { asOptionalRecord } from "openclaw/plugin-sdk/string-coerce-runtime";
+import { hasUnresolvedToken, hindsightConfigSchema, isPlainHttpRemote, RECALL_MAX_TOKENS, RECALL_TIMEOUT_MS, RETAIN_SOURCE, RETAIN_TIMEOUT_MS, } from "./config.js";
+import { createLearnContribution, createLegacyLearnFields, createProviderFlushPlanResolver, RECALL_TOOL_NAMES, } from "./memory-capability.js";
+import { createHindsightProviderRuntime } from "./provider-runtime.js";
+import { routeAudience, sessionUsesMemory } from "./routing.js";
+import { resolveLearnRegistrar } from "./sdk-types.js";
+import { createHindsightService } from "./service.js";
+import { createFlushDeduper, createRecallTool, createReflectTool, createRetainTool, RECALL_TOOL, REFLECT_TOOL, RETAIN_TOOL, } from "./tools.js";
+import { buildRecallContext, extractRecallQuery, isEphemeralOperationalText, prepareRetentionTranscript, retainStartIndex, runStartMarker, } from "./transcript.js";
+export const PLUGIN_ID = "hindsight-native";
+// Bounds per-session run markers; one entry per active session is enough.
+const MAX_RUN_MARKERS = 1_000;
+/**
+ * Reads `plugins.entries[<id>].config` from a runtime config snapshot. Returns undefined when the
+ * snapshot has no entry, so callers fall back to the register-time `api.pluginConfig`.
+ */
+export function readPluginConfigEntry(config, pluginId) {
+    const plugins = asOptionalRecord(asOptionalRecord(config)?.plugins);
+    const entry = asOptionalRecord(asOptionalRecord(plugins?.entries)?.[pluginId]);
+    return asOptionalRecord(entry?.config);
+}
+function sanitizeDocumentIdPart(value, fallback) {
+    const cleaned = (value ?? "")
+        .trim()
+        .replace(/[^a-zA-Z0-9:_-]+/g, "_")
+        .replace(/_+/g, "_")
+        .replace(/^_+|_+$/g, "");
+    return cleaned || fallback;
+}
+/** Short stable digest of the raw key, so keys that sanitize to the same text stay distinct. */
+export function sessionKeyDigest(sessionKey) {
+    return createHash("sha256")
+        .update(sessionKey ?? "")
+        .digest("hex")
+        .slice(0, 12);
+}
+export default definePluginEntry({
+    id: PLUGIN_ID,
+    name: "Memory (Hindsight)",
+    description: "Hindsight-backed long-term memory with auto-recall, auto-retain and agent tools",
+    kind: "memory",
+    configSchema: hindsightConfigSchema,
+    register(api) {
+        let startupConfig;
+        try {
+            startupConfig = hindsightConfigSchema.parse(api.pluginConfig);
+        }
+        catch (error) {
+            api.registerService({
+                id: PLUGIN_ID,
+                start: () => {
+                    api.logger.warn(`memory-hindsight: disabled until configured (${formatErrorMessage(error)})`);
+                },
+            });
+            return;
+        }
+        // Live config so `openclaw config set` and secret reloads apply without a restart. Reads the
+        // host's current snapshot (api.runtime.config.current), falling back to api.pluginConfig.
+        const currentConfig = () => {
+            let live;
+            try {
+                live = readPluginConfigEntry(api.runtime?.config?.current?.(), PLUGIN_ID);
+            }
+            catch {
+                live = undefined;
+            }
+            if (!live || live === api.pluginConfig) {
+                return startupConfig;
+            }
+            try {
+                return hindsightConfigSchema.parse(live);
+            }
+            catch (error) {
+                api.logger.warn?.(`memory-hindsight: ignoring invalid live config (${formatErrorMessage(error)})`);
+                return startupConfig;
+            }
+        };
+        const service = createHindsightService({ config: currentConfig, logger: api.logger });
+        const flushDeduper = createFlushDeduper();
+        const runStartBySession = new Map();
+        const capability = {
+            providerRuntime: createHindsightProviderRuntime({ providerId: PLUGIN_ID, service }),
+            providerFlushPlanResolver: createProviderFlushPlanResolver(currentConfig),
+            recallToolNames: RECALL_TOOL_NAMES,
+        };
+        // /learn: the generic seam where the host has it (openclaw#191665), else the memory-only
+        // capability fields that main builds before that change read. Tagged releases through
+        // 2026.10.10 have neither, so /learn there does not route lessons to this plugin.
+        const registerLearnContribution = resolveLearnRegistrar(api);
+        if (!registerLearnContribution) {
+            Object.assign(capability, createLegacyLearnFields());
+        }
+        api.registerMemoryCapability(capability);
+        registerLearnContribution?.(createLearnContribution());
+        const registerTool = (name, create) => {
+            api.registerTool((ctx) => {
+                const body = create(ctx);
+                return body ? { name, ...body } : null;
+            }, { name });
+        };
+        registerTool(RETAIN_TOOL, (ctx) => createRetainTool(service, flushDeduper, ctx));
+        registerTool(RECALL_TOOL, (ctx) => createRecallTool(service, ctx));
+        registerTool(REFLECT_TOOL, (ctx) => createReflectTool(service, ctx));
+        api.on("before_prompt_build", async (event, ctx) => {
+            const config = currentConfig();
+            const sessionKey = ctx.sessionKey;
+            // Marks the run start for agent_end even when recall is skipped.
+            if (sessionKey && !runStartBySession.has(sessionKey) && Array.isArray(event.messages)) {
+                runStartBySession.set(sessionKey, runStartMarker(event.messages, event.currentUserMessage));
+                if (runStartBySession.size > MAX_RUN_MARKERS) {
+                    runStartBySession.delete(runStartBySession.keys().next().value);
+                }
+            }
+            if (service.stopped() ||
+                !config.autoRecall ||
+                config.memoryMode === "tools" ||
+                isIncognitoSessionKey(sessionKey) ||
+                !sessionUsesMemory(config, { sessionKey, messageProvider: ctx.messageProvider })) {
+                return undefined;
+            }
+            const route = routeAudience(ctx.agentId, ctx.memoryAudience, config.agentBankMap);
+            if (!route.ok) {
+                api.logger.debug?.(`memory-hindsight: auto-recall skipped: ${route.reason}`);
+                return undefined;
+            }
+            const query = extractRecallQuery(event.currentUserMessage, event.prompt);
+            if (!query || isEphemeralOperationalText(query)) {
+                return undefined;
+            }
+            try {
+                ctx.assertMemoryAudienceCurrent?.();
+                const results = await service.client.recall(route.bankId, query, {
+                    budget: config.recallBudget,
+                    maxTokens: RECALL_MAX_TOKENS,
+                    ...(config.recallTypes ? { types: config.recallTypes } : {}),
+                    ...(config.preferObservations === undefined
+                        ? {}
+                        : { preferObservations: config.preferObservations }),
+                    signal: AbortSignal.timeout(RECALL_TIMEOUT_MS),
+                });
+                ctx.assertMemoryAudienceCurrent?.();
+                ctx.hookInvocation?.assertActive();
+                if (results.length === 0) {
+                    return undefined;
+                }
+                api.logger.info?.(`memory-hindsight: injecting ${results.length} memories`);
+                // Before the user message, outside the system prompt, so the cached prefix stays stable.
+                return { prependContext: buildRecallContext(results, config.recallPromptPreamble) };
+            }
+            catch (error) {
+                api.logger.warn?.(`memory-hindsight: auto-recall skipped: ${formatErrorMessage(error)}`);
+                return undefined;
+            }
+        });
+        api.on("agent_end", async (event, ctx) => {
+            const sessionKey = ctx.sessionKey;
+            // Taken before any skip so the next run marks its own start.
+            const runStart = sessionKey ? runStartBySession.get(sessionKey) : undefined;
+            if (sessionKey) {
+                runStartBySession.delete(sessionKey);
+            }
+            const config = currentConfig();
+            if (service.stopped() ||
+                !config.autoRetain ||
+                !event.success ||
+                !Array.isArray(event.messages) ||
+                event.messages.length === 0 ||
+                isIncognitoSessionKey(sessionKey) ||
+                !sessionUsesMemory(config, { sessionKey, messageProvider: ctx.messageProvider })) {
+                return;
+            }
+            const route = routeAudience(ctx.agentId, ctx.memoryAudience, config.agentBankMap);
+            if (!route.ok) {
+                api.logger.debug?.(`memory-hindsight: auto-retain skipped: ${route.reason}`);
+                return;
+            }
+            const retention = prepareRetentionTranscript(event.messages, retainStartIndex(event.messages, runStart));
+            if (!retention || isEphemeralOperationalText(retention.transcript)) {
+                return;
+            }
+            const { tags } = retention;
+            // One document per run: a re-delivered agent_end for the same run replaces, not duplicates.
+            const runPart = sanitizeDocumentIdPart(event.runId ?? ctx.runId, `${Date.now()}`);
+            const documentId = `openclaw:${sanitizeDocumentIdPart(sessionKey, "session")}-${sessionKeyDigest(sessionKey)}:run:${runPart}`;
+            try {
+                // No ctx.assertMemoryAudienceCurrent() here. The host starts agent_end handlers without
+                // awaiting them (runAgentEndSideEffectsAsync -> void runAgentEnd, after awaiting the
+                // completed-turn snapshot and message loader), while the attempt releases the run's
+                // audience in its finally. The check would race that release and drop most retains.
+                // The audience was current when the run produced these messages, and the bank comes
+                // from that host-minted audience, so the write stays in the right partition.
+                const signal = AbortSignal.timeout(RETAIN_TIMEOUT_MS);
+                await service.ensureBank(route.bankId, signal);
+                await service.client.retain(route.bankId, {
+                    content: retention.transcript,
+                    context: config.retainContext,
+                    document_id: documentId,
+                    update_mode: "replace",
+                    ...(tags.length > 0 ? { tags } : {}),
+                    metadata: {
+                        retained_at: new Date().toISOString(),
+                        message_count: String(retention.messageCount),
+                        source: RETAIN_SOURCE,
+                        retention_scope: "turn",
+                        audience: route.audience.kind,
+                        ...(sessionKey ? { session_key: sessionKey } : {}),
+                        ...(ctx.agentId ? { agent_id: ctx.agentId } : {}),
+                        ...(ctx.messageProvider ? { provider: ctx.messageProvider } : {}),
+                        ...(ctx.channelId ? { channel_id: ctx.channelId } : {}),
+                    },
+                }, { signal });
+                api.logger.debug?.(`memory-hindsight: retained ${retention.messageCount} messages (${route.audience.kind})`);
+            }
+            catch (error) {
+                api.logger.warn?.(`memory-hindsight: auto-retain failed: ${formatErrorMessage(error)}`);
+            }
+        });
+        api.on("session_end", async (event, ctx) => {
+            // Compaction rotates the transcript inside a live run; agent_end still needs its marker.
+            if (event.reason === "compaction") {
+                return;
+            }
+            const key = ctx.sessionKey ?? event.sessionKey;
+            if (key) {
+                runStartBySession.delete(key);
+            }
+        });
+        api.registerService({
+            id: PLUGIN_ID,
+            start: () => {
+                service.start();
+                const raw = readPluginConfigEntry(api.runtime?.config?.current?.(), PLUGIN_ID) ?? api.pluginConfig;
+                const config = currentConfig();
+                if (hasUnresolvedToken(raw)) {
+                    api.logger.warn("memory-hindsight: hindsightApiToken not resolved; requests go unauthenticated");
+                }
+                else if (config.apiToken && isPlainHttpRemote(config.apiUrl)) {
+                    api.logger.warn("memory-hindsight: hindsightApiUrl is plain http to a non-loopback host; the bearer token is sent unencrypted");
+                }
+                api.logger.info(`memory-hindsight: initialized (mode: ${currentConfig().memoryMode})`);
+            },
+            stop: () => {
+                service.stop();
+                runStartBySession.clear();
+                api.logger.info("memory-hindsight: stopped");
+            },
+        });
+    },
+});

package/dist/memory-capability.js

@@ -0,0 +1,61 @@
+import { RECALL_TOOL, REFLECT_TOOL, RETAIN_TOOL } from "./tools.js";
+export const FLUSH_SYSTEM_PROMPT = [
+    "Pre-compaction memory flush.",
+    "The conversation is about to be compacted. Save durable context with hindsight_retain before older turns leave the context window.",
+    "Use hindsight_recall only to check whether something is already stored. Do not reply to the user.",
+].join(" ");
+export const FLUSH_PROMPT = [
+    "Review the conversation so far and call hindsight_retain once per durable item that is not already in long-term memory:",
+    "decisions and their reasons, user preferences and rules, facts about people, hosts, services and repositories, task outcomes, and lessons from failures.",
+    "Skip greetings, progress chatter, command output and anything that is only true right now. Never store credential values.",
+    "Pass occurred_at when an item refers to a specific time. If nothing needs saving, reply with NO_REPLY.",
+].join(" ");
+/**
+ * The tools arm persists through the plugin's own retain tool. Auto-retain already stores each
+ * finished turn, so the flush only needs to catch what the model knows but has not said in a
+ * completed turn. Mode "context" registers no tools, so there is nothing to flush with.
+ */
+export function createProviderFlushPlanResolver(config) {
+    return () => {
+        if (config().memoryMode === "context") {
+            return null;
+        }
+        return {
+            prompt: FLUSH_PROMPT,
+            systemPrompt: FLUSH_SYSTEM_PROMPT,
+            persistenceToolNames: [RETAIN_TOOL],
+            lookupToolNames: [RECALL_TOOL],
+        };
+    };
+}
+function learnGuidanceLines(availableTools) {
+    if (!availableTools.has(RETAIN_TOOL)) {
+        return [];
+    }
+    const lines = [
+        "Persist each lesson with hindsight_retain: one call per lesson, written as a self-contained statement (what to do, when, and why).",
+        "Add context such as 'lesson' or 'user preference', and occurred_at when the lesson comes from a dated event.",
+    ];
+    if (availableTools.has(RECALL_TOOL)) {
+        lines.push("Check with hindsight_recall first and skip lessons that are already stored in the same words.");
+    }
+    return lines;
+}
+/** `/learn` contribution for hosts with `api.registerLearnContribution` (openclaw#191665). */
+export function createLearnContribution() {
+    return {
+        medium: "memory",
+        toolNames: LEARN_TOOL_NAMES,
+        requiredToolNames: LEARN_TOOL_NAMES,
+        buildGuidance: ({ availableTools }) => ({ lines: learnGuidanceLines(availableTools) }),
+    };
+}
+/** Capability fields for hosts built from main before openclaw#191665. */
+export function createLegacyLearnFields() {
+    return {
+        learnToolNames: LEARN_TOOL_NAMES,
+        learnGuidanceBuilder: ({ availableTools }) => learnGuidanceLines(availableTools),
+    };
+}
+export const RECALL_TOOL_NAMES = [RECALL_TOOL, REFLECT_TOOL];
+export const LEARN_TOOL_NAMES = [RETAIN_TOOL];

package/dist/provider-runtime.js

@@ -0,0 +1,169 @@
+import { formatErrorMessage } from "openclaw/plugin-sdk/error-runtime";
+import { normalizeAgentId } from "openclaw/plugin-sdk/routing";
+import { boundedSignal, isBankNotFound } from "./client.js";
+import { GET_TIMEOUT_MS, RECALL_MAX_TOKENS, RECALL_TIMEOUT_MS } from "./config.js";
+import { ownerBankId, routeAudience } from "./routing.js";
+const DEFAULT_MAX_RESULTS = 5;
+const MAX_RESULTS = 50;
+/**
+ * Operators read the opened agent's owner bank. A session reads only the bank its host-minted
+ * audience selects (owner-private or its own conversation). Host authority reads nothing.
+ */
+export function resolveBankGrant(authority, agentId, bankMap) {
+    if (authority.kind === "operator") {
+        return { bankId: ownerBankId(agentId, bankMap) };
+    }
+    if (authority.kind === "host") {
+        return { denial: "host operations cannot read stored memories" };
+    }
+    const route = routeAudience(agentId, authority.audience, bankMap);
+    return route.ok ? { bankId: route.bankId } : { denial: route.reason };
+}
+function sliceLines(text, from, lines) {
+    const all = text.split("\n");
+    const start = Math.max(1, Math.floor(from ?? 1));
+    const count = lines === undefined ? all.length : Math.max(1, Math.floor(lines));
+    const selected = all.slice(start - 1, start - 1 + count);
+    const end = start - 1 + selected.length;
+    const truncated = end < all.length;
+    return {
+        text: selected.join("\n"),
+        from: start,
+        lines: selected.length,
+        truncated,
+        ...(truncated ? { nextFrom: end + 1 } : {}),
+    };
+}
+export function createHindsightProviderRuntime(params) {
+    const { providerId, service } = params;
+    return {
+        async open({ agentId: rawAgentId, context }) {
+            if (!rawAgentId?.trim()) {
+                return { provider: null, error: "An agent id is required for Hindsight memory." };
+            }
+            const agentId = normalizeAgentId(rawAgentId);
+            const grant = resolveBankGrant(context.authority, agentId, service.config().agentBankMap);
+            const assertCurrent = () => {
+                context.assertCurrent();
+                context.signal?.throwIfAborted();
+                if (service.stopped()) {
+                    throw new Error("memory-hindsight: the plugin has stopped");
+                }
+            };
+            const readableBank = () => {
+                if ("denial" in grant) {
+                    throw new Error(`memory-hindsight: memory access denied: ${grant.denial}`);
+                }
+                assertCurrent();
+                return grant.bankId;
+            };
+            const reference = (id) => ({ providerId, id });
+            const provider = {
+                capabilities: {
+                    sources: ["memory"],
+                    pagination: false,
+                    candidates: [],
+                    projectFilter: false,
+                },
+                async search(request) {
+                    if ("denial" in grant) {
+                        // Like an owner filtering every hit: cross-session consumers get no rows, no failure.
+                        assertCurrent();
+                        return {
+                            hits: [],
+                            warning: `memory-hindsight: stored memories were not searched: ${grant.denial}`,
+                        };
+                    }
+                    const bankId = readableBank();
+                    const query = request.query.trim();
+                    if (!query) {
+                        return { hits: [], coverage: "complete" };
+                    }
+                    const config = service.config();
+                    const maxResults = Math.min(MAX_RESULTS, Math.max(1, Math.floor(request.maxResults ?? DEFAULT_MAX_RESULTS)));
+                    const minScore = request.minScore;
+                    let results;
+                    try {
+                        results = await service.client.recall(bankId, query, {
+                            budget: config.recallBudget,
+                            maxTokens: RECALL_MAX_TOKENS,
+                            ...(config.recallTypes ? { types: config.recallTypes } : {}),
+                            ...(minScore === undefined ? {} : { minScores: { final: minScore } }),
+                            signal: AbortSignal.any([context.signal, AbortSignal.timeout(RECALL_TIMEOUT_MS)].filter((signal) => Boolean(signal))),
+                        });
+                    }
+                    catch (error) {
+                        if (isBankNotFound(error)) {
+                            assertCurrent();
+                            return { hits: [], coverage: "complete" };
+                        }
+                        throw new Error(`memory-hindsight: memory search failed: ${formatErrorMessage(error)}`, {
+                            cause: error,
+                        });
+                    }
+                    assertCurrent();
+                    const hits = results
+                        // An unscored hit cannot be shown to clear a floor, so a floor drops it.
+                        .filter((r) => {
+                        const score = r.scores?.final;
+                        return minScore === undefined || (typeof score === "number" && score >= minScore);
+                    })
+                        .slice(0, maxResults)
+                        .map((r) => {
+                        const ref = reference(r.id);
+                        const hit = {
+                            reference: ref,
+                            excerpt: r.text,
+                            source: "memory",
+                            citations: [{ label: `hindsight:${r.id}`, reference: ref }],
+                        };
+                        const score = r.scores?.final;
+                        if (typeof score === "number") {
+                            hit.score = score;
+                        }
+                        return hit;
+                    });
+                    return { hits, coverage: "complete" };
+                },
+                async get(request) {
+                    const bankId = readableBank();
+                    const { id, revision } = request.reference;
+                    // Hindsight memories carry no revisions; a revisioned reference names nothing current.
+                    if (request.reference.providerId !== providerId || revision !== undefined || !id) {
+                        return { status: "not_found" };
+                    }
+                    const memory = await service.client.getMemory(bankId, id, boundedSignal(GET_TIMEOUT_MS, context.signal));
+                    assertCurrent();
+                    if (!memory) {
+                        return { status: "not_found" };
+                    }
+                    const ref = reference(id);
+                    return {
+                        status: "ok",
+                        reference: ref,
+                        citations: [{ label: `hindsight:${id}`, reference: ref }],
+                        ...sliceLines(memory.text, request.from, request.lines),
+                    };
+                },
+                async health() {
+                    assertCurrent();
+                    const { autoRecall, autoRetain, memoryMode } = service.config();
+                    // Health reaches every authenticated caller: no memory text, URLs or tokens.
+                    const details = { backend: "hindsight", autoRecall, autoRetain, memoryMode };
+                    const healthy = await service.client.healthy();
+                    assertCurrent();
+                    return healthy
+                        ? { status: "ready", details }
+                        : {
+                            status: "unavailable",
+                            message: "The Hindsight API is not reachable. Check the Gateway log.",
+                            details,
+                        };
+                },
+                // The HTTP client is shared with hooks and tools; nothing is leased per caller.
+                async close() { },
+            };
+            return { provider };
+        },
+    };
+}

package/dist/routing.js

@@ -0,0 +1,62 @@
+import { createHash } from "node:crypto";
+import { normalizeAgentId } from "openclaw/plugin-sdk/routing";
+/**
+ * The owner's private bank for one agent; matches the third-party plugin's per-agent bank.
+ * `agentBankMap` (same key as the vendor plugin) lets several agents share one owner bank.
+ * The id stays raw here; `HindsightClient` percent-encodes it once when it builds the URL.
+ */
+export function ownerBankId(agentId, bankMap) {
+    const normalized = normalizeAgentId(agentId);
+    return bankMap?.[normalized] ?? normalized;
+}
+/**
+ * A conversation audience gets its own bank per durable root session, so memories formed with
+ * other senders or in groups never surface in the owner's private recall and vice versa.
+ */
+export function conversationBankId(agentId, rootSessionKey, bankMap) {
+    const digest = createHash("sha256").update(rootSessionKey).digest("hex").slice(0, 16);
+    return `${ownerBankId(agentId, bankMap)}::conv::${digest}`;
+}
+/**
+ * Picks the bank from the host-minted audience only. Session keys, ids and record ids never
+ * select a partition, and an audience for another agent is refused.
+ */
+export function routeAudience(agentId, audience, bankMap) {
+    if (!agentId?.trim()) {
+        return { ok: false, reason: "no agent id" };
+    }
+    if (!audience) {
+        return { ok: false, reason: "this session has no memory audience" };
+    }
+    const normalized = normalizeAgentId(agentId);
+    if (normalizeAgentId(audience.agentId) !== normalized) {
+        return { ok: false, reason: "the memory audience belongs to another agent" };
+    }
+    if (audience.kind === "owner-private") {
+        return { ok: true, bankId: ownerBankId(normalized, bankMap), audience };
+    }
+    return {
+        ok: true,
+        bankId: conversationBankId(normalized, audience.sessionKey, bankMap),
+        audience,
+    };
+}
+const OPERATIONAL_SESSION_RE = /^agent:[^:]+:(cron|heartbeat|subagent):/;
+const OPERATIONAL_PROVIDERS = new Set(["cron", "heartbeat", "subagent"]);
+/** Session filter shared by auto-recall, auto-retain and tool registration. */
+export function sessionUsesMemory(config, params) {
+    const { sessionKey, messageProvider } = params;
+    if (messageProvider && config.excludeProviders.includes(messageProvider)) {
+        return false;
+    }
+    if (sessionKey?.startsWith("temp:")) {
+        return false;
+    }
+    if (!config.skipOperationalSessions) {
+        return true;
+    }
+    if (messageProvider && OPERATIONAL_PROVIDERS.has(messageProvider)) {
+        return false;
+    }
+    return !(sessionKey && OPERATIONAL_SESSION_RE.test(sessionKey));
+}

package/dist/sdk-types.js

@@ -0,0 +1,10 @@
+/** Returns the host's `registerLearnContribution` when this host has the generic seam. */
+export function resolveLearnRegistrar(api) {
+    const candidate = api.registerLearnContribution;
+    if (typeof candidate !== "function") {
+        return undefined;
+    }
+    return (contribution) => {
+        candidate.call(api, contribution);
+    };
+}

package/dist/service.js

@@ -0,0 +1,40 @@
+import { HindsightClient } from "./client.js";
+export function createHindsightService(params) {
+    const preparedBanks = new Map();
+    let stopped = false;
+    const client = new HindsightClient({
+        resolveEndpoint: () => {
+            const { apiUrl, apiToken } = params.config();
+            return { apiUrl, ...(apiToken ? { apiToken } : {}) };
+        },
+        ...(params.fetch ? { fetch: params.fetch } : {}),
+    });
+    return {
+        config: params.config,
+        client,
+        logger: params.logger,
+        async ensureBank(bankId, signal) {
+            let pending = preparedBanks.get(bankId);
+            if (!pending) {
+                const { retainMission } = params.config();
+                pending = client.applyBankDefaults(bankId, { retainMission }, signal);
+                preparedBanks.set(bankId, pending);
+                // A failed setup retries on the next write instead of caching the failure.
+                pending.catch(() => {
+                    if (preparedBanks.get(bankId) === pending) {
+                        preparedBanks.delete(bankId);
+                    }
+                });
+            }
+            await pending;
+        },
+        stopped: () => stopped,
+        stop() {
+            stopped = true;
+            preparedBanks.clear();
+        },
+        start() {
+            stopped = false;
+        },
+    };
+}