@gajae-code/coding-agent 0.1.1

package/dist/types/hashline/hash.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Core hash utilities shared by hashline edit mode, read/search output,
+ * and prompt helpers.
+ */
+/**
+ * 647 single-token BPE bigrams for hashline anchors. Every entry tokenizes as
+ * exactly one token in modern BPE vocabularies (cl100k / o200k / Anthropic model family),
+ * so a hashline anchor built from one bigram is exactly 1 token.
+ *
+ * This is the complete set of 2-letter lowercase combinations that are single
+ * tokens — the 29 missing combinations are rare-letter pairs (q/x/z heavy)
+ * that no major BPE vocabulary merges into a single token.
+ *
+ * Order is stable forever — changing it would invalidate every saved
+ * `LINE+ID` reference in transcripts and prompts.
+ */
+export declare const HL_BIGRAMS: readonly string[];
+export declare const HL_BIGRAMS_COUNT: number;
+/**
+ * Decoration prefix that may precede a `LINE+HASH` anchor in tool output:
+ * `>` (context line in grep), `+` (added line in diff), `-` (removed line),
+ * `*` (match line). Any combination, in any order, surrounded by optional
+ * whitespace. Output formatters emit at most one decoration per anchor; the
+ * regex stays liberal because anchor-ref parsers accept whatever the model
+ * echoes back.
+ */
+export declare const HL_ANCHOR_DECORATION_RE_RAW = "\\s*[>+\\-*]*\\s*";
+/**
+ * Capture-group regex source for a decorated `LINE+HASH` anchor. Group 1
+ * captures the line number (digits only); group 2 captures the hash. The
+ * source is intentionally unanchored — anchoring with `^` (or composing into a
+ * larger pattern) is the caller's responsibility.
+ */
+export declare const HL_ANCHOR_RE_RAW = "\\s*[>+\\-*]*\\s*(\\d+)([a-z]{2})";
+/**
+ * Bare `LINE+HASH` Lid (no decorations, no captures, no anchors). Use for
+ * embedding inside larger patterns where the line+hash unit appears as a
+ * literal (e.g. range bounds, alternation arms, op-line heuristics).
+ */
+export declare const HL_HASH_RE_RAW = "[1-9]\\d*[a-z]{2}";
+/**
+ * Capture-group form of {@link HL_HASH_RE_RAW}: group 1 captures the
+ * line number, group 2 captures the hash.
+ */
+export declare const HL_HASH_CAPTURE_RE_RAW = "([1-9]\\d*)([a-z]{2})";
+/** Width of a hash in display characters. */
+export declare const HL_HASH_WIDTH = 2;
+/**
+ * Representative hash suffixes for use in user-facing error messages and
+ * prompt examples.
+ */
+export declare const HL_HASH_EXAMPLES: readonly ["sr", "ab", "th"];
+/**
+ * Format a comma-separated list of example anchors with an optional line-number
+ * prefix, quoted for inclusion in error messages: `"160sr", "160ab", "160th"`.
+ */
+export declare function describeAnchorExamples(linePrefix?: string): string;
+/**
+ * Substitute every grammar placeholder with the value derived from its
+ * TypeScript counterpart. Grammars that don't reference these placeholders
+ * pass through unchanged.
+ */
+export declare function resolveHashlineGrammarPlaceholders(grammar: string): string;
+/** @deprecated Use {@link resolveHashlineGrammarPlaceholders}. */
+export declare const resolveLarkLidPlaceholders: typeof resolveHashlineGrammarPlaceholders;
+/**
+ * Hashline edit input markers. File section headers start with {@link HL_FILE_PREFIX};
+ * op lines start with a direction/action sigil: {@link HL_OP_INSERT_BEFORE},
+ * {@link HL_OP_INSERT_AFTER}, or {@link HL_OP_REPLACE}. Payload lines are
+ * verbatim file content and have no per-line marker.
+ *
+ * These constants are the single source of truth for the edit parser, grammar,
+ * renderer, and prompt.
+ */
+export declare const HL_OP_INSERT_BEFORE = "\u00AB";
+export declare const HL_OP_INSERT_AFTER = "\u00BB";
+export declare const HL_OP_REPLACE = "\u2254";
+/** All hashline edit op sigils, concatenated for fast membership tests. */
+export declare const HL_OP_CHARS = "\u00AB\u00BB\u2254";
+/** Hashline edit file section header marker. */
+export declare const HL_FILE_PREFIX = "\u00A7";
+/** Stable separator for read/search/hashline display output. Intentionally not configurable. */
+export declare const HL_BODY_SEP = "|";
+/** Regex-escaped form of {@link HL_BODY_SEP}, safe for embedding inside a regex. */
+export declare const HL_BODY_SEP_RE_RAW: string;
+/**
+ * Compute a 2-character hash of a single line via xxHash32 mod 647 over
+ * {@link HL_BIGRAMS}. The hash depends only on the line's content (after
+ * stripping CR and trailing whitespace); the `idx` parameter is accepted
+ * for call-site symmetry with line numbers but is intentionally unused so
+ * that anchors remain stable across line shifts caused by sibling edits.
+ *
+ * The line input should not include a trailing newline.
+ */
+export declare function computeLineHash(idx: number, line: string): string;
+/**
+ * Formats an anchor reference given a line number and its text.
+ * Returns `LINE+ID` (e.g., `42sr`) — no separator between
+ * number and hash.
+ */
+export declare function formatLineHash(line: number, lines: string): string;
+/**
+ * Formats a single line with a hashline anchor.
+ * Returns `LINE+ID|TEXT` (e.g., `42sr|function hi() {`, `3ab|}`).
+ */
+export declare function formatHashLine(lineNumber: number, line: string): string;
+/**
+ * Format file text with hashline prefixes for display.
+ *
+ * Each line becomes `LINE+ID|TEXT` where LINENUM is 1-indexed.
+ * No padding on line numbers; pipe separator between anchor and content.
+ *
+ * @param text - Raw file text string
+ * @param startLine - First line number (1-indexed, defaults to 1)
+ * @returns Formatted string with one hashline-prefixed line per input line
+ *
+ * @example
+ * ```
+ * formatHashLines("function hi() {\n  return;\n}")
+ * // "1bm|function hi() {\n2er|  return;\n3ab|}"
+ * ```
+ */
+export declare function formatHashLines(text: string, startLine?: number): string;

package/dist/types/hashline/index.d.ts

@@ -0,0 +1,13 @@
+export * from "./anchors";
+export * from "./apply";
+export * from "./constants";
+export * from "./diff";
+export * from "./diff-preview";
+export * from "./execute";
+export * from "./hash";
+export * from "./input";
+export * from "./parser";
+export * from "./prefixes";
+export * from "./recovery";
+export * from "./stream";
+export * from "./types";

package/dist/types/hashline/input.d.ts

@@ -0,0 +1,11 @@
+import type { SplitHashlineOptions } from "./types";
+export interface HashlineInputSection {
+    path: string;
+    diff: string;
+}
+export declare function containsRecognizableHashlineOperations(input: string): boolean;
+export declare function splitHashlineInput(input: string, options?: SplitHashlineOptions): {
+    path: string;
+    diff: string;
+};
+export declare function splitHashlineInputs(input: string, options?: SplitHashlineOptions): HashlineInputSection[];

package/dist/types/hashline/parser.d.ts

@@ -0,0 +1,7 @@
+import type { HashlineCursor, HashlineEdit } from "./types";
+export declare function cloneCursor(cursor: HashlineCursor): HashlineCursor;
+export declare function parseHashline(diff: string): HashlineEdit[];
+export declare function parseHashlineWithWarnings(diff: string): {
+    edits: HashlineEdit[];
+    warnings: string[];
+};

package/dist/types/hashline/prefixes.d.ts

@@ -0,0 +1,7 @@
+export declare function stripNewLinePrefixes(lines: string[]): string[];
+export declare function stripHashlinePrefixes(lines: string[]): string[];
+/**
+ * Normalize line payloads by stripping read/search line prefixes. `null` /
+ * `undefined` yield `[]`; a single multiline string is split on `\n`.
+ */
+export declare function hashlineParseText(edit: string[] | string | null | undefined): string[];

package/dist/types/hashline/recovery.d.ts

@@ -0,0 +1,27 @@
+import type { FileReadCache } from "../edit/file-read-cache";
+import type { HashlineApplyOptions, HashlineEdit } from "./types";
+export interface HashlineRecoveryArgs {
+    cache: FileReadCache;
+    absolutePath: string;
+    currentText: string;
+    edits: HashlineEdit[];
+    options: HashlineApplyOptions;
+}
+export interface HashlineRecoveryResult {
+    lines: string;
+    firstChangedLine: number | undefined;
+    warnings: string[];
+}
+/**
+ * Attempt to recover from a `HashlineMismatchError` by replaying the edits
+ * against a cached pre-edit snapshot of the file and 3-way-merging the result
+ * onto the current on-disk content. Returns `null` when no recovery is
+ * possible — callers should propagate the original mismatch error in that
+ * case.
+ *
+ * Recovery is gated on a strict precondition: every line the model anchored
+ * MUST be present in the cached snapshot AND its content MUST hash to the
+ * model-supplied hash. This prevents 3-way merges from silently sliding onto
+ * the wrong site when only tangential parts of the file went stale.
+ */
+export declare function tryRecoverHashlineWithCache(args: HashlineRecoveryArgs): HashlineRecoveryResult | null;

package/dist/types/hashline/stream.d.ts

@@ -0,0 +1,2 @@
+import type { HashlineStreamOptions } from "./types";
+export declare function streamHashLinesFromUtf8(source: ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>, options?: HashlineStreamOptions): AsyncGenerator<string>;

package/dist/types/hashline/types.d.ts

@@ -0,0 +1,77 @@
+import * as z from "zod/v4";
+import type { LspBatchRequest } from "../edit/renderer";
+import type { WritethroughCallback, WritethroughDeferredHandle } from "../lsp";
+import type { ToolSession } from "../tools";
+export interface HashMismatch {
+    line: number;
+    expected: string;
+    actual: string;
+}
+export type Anchor = {
+    line: number;
+    hash: string;
+    contentHint?: string;
+};
+export type HashlineCursor = {
+    kind: "bof";
+} | {
+    kind: "eof";
+} | {
+    kind: "before_anchor";
+    anchor: Anchor;
+} | {
+    kind: "after_anchor";
+    anchor: Anchor;
+};
+export type HashlineEdit = {
+    kind: "insert";
+    cursor: HashlineCursor;
+    text: string;
+    lineNum: number;
+    index: number;
+} | {
+    kind: "delete";
+    anchor: Anchor;
+    lineNum: number;
+    index: number;
+    oldAssertion?: string;
+};
+/** `path` is accepted by the edit tool runtime; other extra keys are preserved. */
+export declare const hashlineEditParamsSchema: z.ZodObject<{
+    input: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export type HashlineParams = z.infer<typeof hashlineEditParamsSchema>;
+export interface HashlineStreamOptions {
+    /** First line number to use when formatting (1-indexed). */
+    startLine?: number;
+    /** Maximum formatted lines per yielded chunk (default: 200). */
+    maxChunkLines?: number;
+    /** Maximum UTF-8 bytes per yielded chunk (default: 64 KiB). */
+    maxChunkBytes?: number;
+}
+export interface CompactHashlineDiffPreview {
+    preview: string;
+    addedLines: number;
+    removedLines: number;
+}
+export interface CompactHashlineDiffOptions {
+    /** Maximum entries kept on each side of an unchanged-context truncation (default: 2). */
+    maxUnchangedRun?: number;
+}
+export interface HashlineApplyOptions {
+    autoDropPureInsertDuplicates?: boolean;
+}
+export interface SplitHashlineOptions {
+    cwd?: string;
+    path?: string;
+}
+export interface ExecuteHashlineSingleOptions {
+    session: ToolSession;
+    input: string;
+    path?: string;
+    signal?: AbortSignal;
+    batchRequest?: LspBatchRequest;
+    writethrough: WritethroughCallback;
+    beginDeferredDiagnosticsForPath: (path: string) => WritethroughDeferredHandle;
+}

package/dist/types/hindsight/backend.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Hindsight memory backend.
+ *
+ * Wires the per-session lifecycle (recall on first turn, retain every Nth
+ * agent_end, etc.) on top of the AgentSession event stream. Hindsight runtime
+ * state is owned by the AgentSession so lifetime follows the actual domain
+ * owner instead of a parallel session-id registry.
+ */
+import type { MemoryBackend } from "../memory-backend/types";
+import type { AgentSession } from "../session/agent-session";
+/** Reload the active session's mental-model cache and prompt. */
+export declare function reloadMentalModelsForSession(session: AgentSession): Promise<boolean>;
+export declare const hindsightBackend: MemoryBackend;

package/dist/types/hindsight/bank.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Bank ID derivation, project-tag scoping, and first-use mission setup.
+ *
+ * Three scoping modes (`HindsightConfig.scoping`):
+ *   - `global`              — single shared bank, no per-project filter.
+ *   - `per-project`         — one bank per cwd basename, hard isolation.
+ *   - `per-project-tagged`  — single shared bank, retains carry a `project:<name>`
+ *                              tag and recall filters on it but still surfaces
+ *                              untagged ("global") memories alongside.
+ *
+ * The base bank id is `bankIdPrefix-bankId` (default `gjc`). Per-project mode
+ * appends `-<project>`; tagged mode leaves the bank untouched and uses tags.
+ *
+ * Mission setup is idempotent at module level — a missionsSet keeps track of
+ * banks we've already POSTed to so each session boundary doesn't fire a fresh
+ * `createBank` call. Failures are swallowed: missions are an optimisation, not
+ * a precondition for retain/recall.
+ */
+import type { HindsightApi } from "./client";
+import type { HindsightConfig } from "./config";
+export type RecallTagsMatch = "any" | "all" | "any_strict" | "all_strict";
+/**
+ * Resolved bank target for a session: which bank to talk to, plus optional
+ * tags to attach to retains and to filter recalls by.
+ */
+export interface BankScope {
+    bankId: string;
+    /** Tags applied to every retain. Undefined when scoping does not use tags. */
+    retainTags?: string[];
+    /** Tags filter for recall/reflect. Undefined when scoping does not use tags. */
+    recallTags?: string[];
+    /** Match mode for `recallTags`. Defaults to `any` so untagged ("global") memories surface too. */
+    recallTagsMatch?: RecallTagsMatch;
+}
+/**
+ * Resolve the active bank target plus optional tag scoping.
+ *
+ * Always returns a non-empty `bankId`. Tag fields are populated only for
+ * `per-project-tagged`.
+ */
+export declare function computeBankScope(config: HindsightConfig, directory: string): BankScope;
+/**
+ * Backwards-compatible thin wrapper: just return the bank id portion of the
+ * scope. New code should prefer `computeBankScope` directly so it can also
+ * apply the tag fields.
+ */
+export declare function deriveBankId(config: HindsightConfig, directory: string): string;
+/**
+ * Ensure a bank's reflect/retain mission is set, exactly once per process.
+ *
+ * Tracked via the supplied set; on overflow we drop the oldest half so the set
+ * cannot grow unboundedly across long-lived processes.
+ */
+export declare function ensureBankMission(client: HindsightApi, bankId: string, config: HindsightConfig, missionsSet: Set<string>): Promise<void>;

package/dist/types/hindsight/client.d.ts

@@ -0,0 +1,224 @@
+/**
+ * Minimal fetch-based client for the Hindsight HTTP API.
+ *
+ * Replaces the `@vectorize-io/hindsight-client` SDK with hand-rolled fetch
+ * calls so we depend on nothing more than the API endpoints we actually use:
+ * `retain`, `retainBatch`, `recall`, `reflect`, bank + document management,
+ * and bulk listing. Centralising construction here keeps a single seam for
+ * tests to spy on.
+ */
+import type { HindsightConfig } from "./config";
+export type Budget = "low" | "mid" | "high" | string;
+export type TagsMatch = "any" | "all" | "any_strict" | "all_strict";
+export type UpdateMode = "replace" | "append";
+export type ConsolidationState = "failed" | "pending" | "done";
+export interface HindsightApiOptions {
+    baseUrl: string;
+    apiKey?: string;
+    userAgent?: string;
+}
+export interface RecallResult {
+    id?: string;
+    text: string;
+    type?: string | null;
+    mentioned_at?: string | null;
+    [key: string]: unknown;
+}
+export interface RecallResponse {
+    results: RecallResult[];
+    [key: string]: unknown;
+}
+export interface ReflectResponse {
+    text?: string;
+    [key: string]: unknown;
+}
+export interface RetainResponse {
+    [key: string]: unknown;
+}
+export interface BankProfileResponse {
+    [key: string]: unknown;
+}
+export interface ListMemoriesResponse {
+    [key: string]: unknown;
+}
+export interface DocumentResponse {
+    [key: string]: unknown;
+}
+export interface ListDocumentsResponse {
+    [key: string]: unknown;
+}
+/** Mirrors the shape accepted by `POST /v1/default/banks/{bank_id}/memories`. */
+export interface MemoryItemInput {
+    content: string;
+    timestamp?: Date | string;
+    context?: string;
+    metadata?: Record<string, string>;
+    documentId?: string;
+    tags?: string[];
+    /** Scoping policy for observations derived from this item. */
+    observationScopes?: "per_tag" | "combined" | "all_combinations" | string[][];
+    /** Per-item extraction strategy override. */
+    strategy?: string;
+    updateMode?: UpdateMode;
+}
+export interface RetainOptions {
+    timestamp?: Date | string;
+    context?: string;
+    metadata?: Record<string, string>;
+    documentId?: string;
+    async?: boolean;
+    tags?: string[];
+    updateMode?: UpdateMode;
+}
+export interface RetainBatchOptions {
+    /** Document id applied to every item that doesn't carry its own. */
+    documentId?: string;
+    /** Tags attached to the resulting document(s), not individual items. */
+    documentTags?: string[];
+    async?: boolean;
+}
+export interface RecallOptions {
+    types?: string[];
+    maxTokens?: number;
+    budget?: Budget;
+    tags?: string[];
+    tagsMatch?: TagsMatch;
+}
+export interface ReflectOptions {
+    context?: string;
+    budget?: Budget;
+    tags?: string[];
+    tagsMatch?: TagsMatch;
+}
+export interface CreateBankOptions {
+    reflectMission?: string;
+    retainMission?: string;
+}
+export interface ListMemoriesOptions {
+    limit?: number;
+    offset?: number;
+    type?: string;
+    q?: string;
+    consolidationState?: ConsolidationState;
+}
+export interface ListDocumentsOptions {
+    limit?: number;
+    offset?: number;
+}
+export interface UpdateDocumentOptions {
+    tags?: string[];
+}
+export type MentalModelDetail = "metadata" | "content" | "full";
+export type MentalModelMode = "full" | "delta";
+export interface MentalModelTrigger {
+    mode?: MentalModelMode;
+    refresh_after_consolidation?: boolean;
+}
+/** Shape returned by list/get on the mental-models endpoint. Fields are populated by `detail`. */
+export interface MentalModelSummary {
+    id: string;
+    bank_id: string;
+    name: string;
+    tags?: string[];
+    last_refreshed_at?: string | null;
+    created_at?: string | null;
+    source_query?: string;
+    content?: string;
+    max_tokens?: number;
+    trigger?: MentalModelTrigger;
+    [key: string]: unknown;
+}
+export interface MentalModelListResponse {
+    items: MentalModelSummary[];
+    [key: string]: unknown;
+}
+export interface MentalModelHistoryEntry {
+    previous_content: string | null;
+    changed_at: string;
+    [key: string]: unknown;
+}
+export interface CreateMentalModelOptions {
+    id?: string;
+    tags?: string[];
+    maxTokens?: number;
+    trigger?: MentalModelTrigger;
+}
+export interface CreateMentalModelResponse {
+    operation_id?: string;
+    [key: string]: unknown;
+}
+export interface RefreshMentalModelResponse {
+    operation_id?: string;
+    [key: string]: unknown;
+}
+export interface ListMentalModelsOptions {
+    detail?: MentalModelDetail;
+}
+export interface GetMentalModelOptions {
+    detail?: MentalModelDetail;
+}
+export declare class HindsightError extends Error {
+    statusCode?: number;
+    details?: unknown;
+    constructor(message: string, statusCode?: number, details?: unknown);
+}
+export declare class HindsightApi {
+    #private;
+    constructor(options: HindsightApiOptions);
+    retain(bankId: string, content: string, options?: RetainOptions): Promise<RetainResponse>;
+    /**
+     * Retain multiple memories in a single request. Mirrors the official
+     * client's `retainBatch` — items hit `POST /memories` together so the
+     * server can dedupe and consolidate as a batch instead of N round-trips.
+     *
+     * Per-item `documentId` wins; `options.documentId` only fills the gaps.
+     */
+    retainBatch(bankId: string, items: MemoryItemInput[], options?: RetainBatchOptions): Promise<RetainResponse>;
+    recall(bankId: string, query: string, options?: RecallOptions): Promise<RecallResponse>;
+    reflect(bankId: string, query: string, options?: ReflectOptions): Promise<ReflectResponse>;
+    createBank(bankId: string, options?: CreateBankOptions): Promise<BankProfileResponse>;
+    /**
+     * Bulk-list memory units in a bank with optional filters and pagination.
+     * Endpoint: `GET /v1/default/banks/{bank_id}/memories/list`.
+     */
+    listMemories(bankId: string, options?: ListMemoriesOptions): Promise<ListMemoriesResponse>;
+    /** Bulk-list documents in a bank. */
+    listDocuments(bankId: string, options?: ListDocumentsOptions): Promise<ListDocumentsResponse>;
+    /** Fetch a document. Returns `null` on 404 instead of throwing. */
+    getDocument(bankId: string, documentId: string): Promise<DocumentResponse | null>;
+    /** Update a document's mutable fields (currently just tags). */
+    updateDocument(bankId: string, documentId: string, options: UpdateDocumentOptions): Promise<DocumentResponse>;
+    /**
+     * Delete a document and every memory derived from it. Returns `true` on
+     * success, `false` if the document was already gone (404).
+     */
+    deleteDocument(bankId: string, documentId: string): Promise<boolean>;
+    /**
+     * List mental models in a bank. Default `detail=content` includes the
+     * generated `content` text but excludes the heavyweight `reflect_response`
+     * provenance chain (which can exceed 200KB). Use `detail=metadata` for
+     * inventory and `detail=full` only for debug surfaces.
+     */
+    listMentalModels(bankId: string, options?: ListMentalModelsOptions): Promise<MentalModelListResponse>;
+    /** Fetch a single mental model. Returns `null` on 404. */
+    getMentalModel(bankId: string, mentalModelId: string, options?: GetMentalModelOptions): Promise<MentalModelSummary | null>;
+    /**
+     * Create a mental model. Asynchronous on the server: returns an
+     * `operation_id`; the model's `content` populates after the background
+     * reflect completes.
+     */
+    createMentalModel(bankId: string, name: string, sourceQuery: string, options?: CreateMentalModelOptions): Promise<CreateMentalModelResponse>;
+    /** Trigger an out-of-band refresh of a mental model. Returns the operation handle. */
+    refreshMentalModel(bankId: string, mentalModelId: string): Promise<RefreshMentalModelResponse>;
+    /** Delete a mental model. Returns `true` on success, `false` if it was already gone (404). */
+    deleteMentalModel(bankId: string, mentalModelId: string): Promise<boolean>;
+    /**
+     * Fetch the change history of a mental model. Each entry captures the
+     * content snapshot BEFORE that change; the current content is read via
+     * `getMentalModel`. Most-recent first.
+     */
+    getMentalModelHistory(bankId: string, mentalModelId: string): Promise<MentalModelHistoryEntry[]>;
+}
+export declare function createHindsightClient(config: HindsightConfig & {
+    hindsightApiUrl: string;
+}): HindsightApi;

package/dist/types/hindsight/config.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Resolved Hindsight runtime configuration.
+ *
+ * Source of truth precedence (last wins):
+ *   1. Built-in defaults
+ *   2. Settings (`hindsight.*` schema entries via `Settings.get(...)`)
+ *   3. `HINDSIGHT_*` environment variables
+ *
+ * Env wins because operators frequently override per-shell (CI, prod) without
+ * touching the persisted settings file.
+ */
+import type { Settings } from "../config/settings";
+export type HindsightScoping = "global" | "per-project" | "per-project-tagged";
+export interface HindsightConfig {
+    hindsightApiUrl: string | null;
+    hindsightApiToken: string | null;
+    bankId: string | null;
+    bankIdPrefix: string;
+    scoping: HindsightScoping;
+    bankMission: string;
+    retainMission: string | null;
+    autoRecall: boolean;
+    autoRetain: boolean;
+    retainMode: "full-session" | "last-turn";
+    retainEveryNTurns: number;
+    retainOverlapTurns: number;
+    retainContext: string;
+    recallBudget: "low" | "mid" | "high";
+    recallMaxTokens: number;
+    recallTypes: string[];
+    recallContextTurns: number;
+    recallMaxQueryChars: number;
+    recallPromptPreamble: string;
+    debug: boolean;
+    mentalModelsEnabled: boolean;
+    mentalModelAutoSeed: boolean;
+    mentalModelRefreshIntervalMs: number;
+    mentalModelMaxRenderChars: number;
+}
+/**
+ * Load the resolved Hindsight config.
+ *
+ * Pure (no I/O) aside from reading from `process.env` and the supplied
+ * Settings instance. Tests can pass `Settings.isolated({...})` and stub
+ * `process.env` per case.
+ */
+export declare function loadHindsightConfig(settings: Settings, env?: NodeJS.ProcessEnv): HindsightConfig;
+/** Whether the caller has enough config to talk to a Hindsight server. */
+export declare function isHindsightConfigured(config: HindsightConfig): config is HindsightConfig & {
+    hindsightApiUrl: string;
+};