jeopi-cli 16.2.14 → 16.2.15

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;
+};

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

@@ -0,0 +1,69 @@
+/**
+ * Pure content utilities for the Hindsight backend.
+ *
+ * Ports the semantics of the upstream OpenCode plugin
+ * (vectorize-io/hindsight @ hindsight-integrations/opencode/src/content.ts):
+ *   - tag stripping for anti-feedback (a recalled <memories> block must
+ *     never end up retained as a new memory)
+ *   - recall query composition + truncation under a character budget
+ *   - retention transcript framing
+ */
+export interface HindsightMessage {
+    role: string;
+    content: string;
+}
+export interface RecallResultLike {
+    text: string;
+    type?: string | null;
+    mentioned_at?: string | null;
+}
+/**
+ * Strip `<memories>`, `<mental_models>`, and legacy memory blocks.
+ *
+ * Both `<memories>` (per-turn recall) and `<mental_models>` (curated semantic
+ * memory) are injected into the system prompt. If either leaks into the
+ * retention transcript, every retain becomes a tighter feedback loop —
+ * paraphrased memories feed the next consolidation, which feeds the next
+ * mental-model refresh, which feeds the next retain. Always strip before
+ * retaining.
+ */
+export declare function stripMemoryTags(content: string): string;
+/**
+ * True when `content` carries at least one letter or digit. Used by retain
+ * and recall paths to drop placeholder assistant turns ("." / "..." / pure
+ * whitespace) that would otherwise pollute the bank and waste tokens on
+ * embeddings with no semantic content.
+ */
+export declare function hasSubstantiveContent(content: string): boolean;
+/** Format recall results into a bullet list for context injection. */
+export declare function formatMemories(results: RecallResultLike[]): string;
+/** Format current UTC time for the recall preamble. */
+export declare function formatCurrentTime(now?: Date): string;
+/**
+ * Slice messages to the last N turns, where a turn boundary is a user message.
+ * Returns the trailing tail starting at the (N-th from the end) user message.
+ */
+export declare function sliceLastTurnsByUserBoundary(messages: HindsightMessage[], turns: number): HindsightMessage[];
+/**
+ * Compose a recall query from the latest user prompt plus optional prior context.
+ *
+ * When `recallContextTurns <= 1` the query is just the trimmed latest prompt.
+ * Otherwise we prepend a `Prior context:` block built from the trailing
+ * `recallContextTurns` user-bounded turns (memory tags stripped, latest prompt
+ * suppressed to avoid duplicating it inside the context block).
+ */
+export declare function composeRecallQuery(latestQuery: string, messages: HindsightMessage[], recallContextTurns: number): string;
+/**
+ * Truncate a composed recall query to `maxChars`.
+ *
+ * Always preserves the latest user message. Drops oldest context lines first
+ * and degrades gracefully when even the latest message exceeds the budget.
+ */
+export declare function truncateRecallQuery(query: string, latestQuery: string, maxChars: number): string;
+export interface RetentionTranscript {
+    transcript: string | null;
+    messageCount: number;
+}
+export declare function prepareRetentionTranscript(messages: HindsightMessage[], retainFullWindow?: boolean): RetentionTranscript;
+/** Format only user-authored messages for memory fact/entity extraction. */
+export declare function prepareUserRetentionTranscript(messages: HindsightMessage[]): RetentionTranscript;

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

@@ -0,0 +1,8 @@
+export * from "./backend";
+export * from "./bank";
+export * from "./client";
+export * from "./config";
+export * from "./content";
+export * from "./mental-models";
+export * from "./state";
+export * from "./transcript";

package/dist/types/hindsight/mental-models.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Mental-model bootstrap, caching, and rendering for the Hindsight backend.
+ *
+ * Mental models are persisted, named summaries on the Hindsight server. They
+ * are populated by a background reflect at create time and refreshed
+ * automatically when consolidation runs (`refresh_after_consolidation: true`).
+ *
+ * This module:
+ *   1. **Seeds** a small, curated set of mental models on first session boot
+ *      for a given bank (idempotent: never modifies an existing model).
+ *   2. **Loads** the seeded + any operator-curated models into a cached
+ *      `<mental_models>` block that the backend splices into developer
+ *      instructions on every prompt rebuild — bypassing per-turn recall HTTP
+ *      cost for stable knowledge.
+ *   3. **Renders** content blocks with anti-feedback wrappers so the LLM
+ *      treats them as background knowledge, not as commands (mirrors the
+ *      `<memories>` warning).
+ *
+ * Tag discipline (foot-gun):
+ * The Hindsight refresh path filters source memories with `all_strict` tag
+ * matching against the model's tags. A seed tagged with something we never
+ * write at retain time will refresh empty. Therefore seed tags MUST be a
+ * subset of the tags actually attached by `retainSession` / `enqueueRetain`
+ * for the active scoping mode. In `per-project-tagged` we only carry
+ * `project:<cwd>`; do not invent new tag axes here without first wiring the
+ * retain side to emit them.
+ *
+ * Seed tags are baked from `seeds.json` plus, for `projectTagged: true`
+ * entries, the active scope's `retainTags` (i.e. `project:<cwd>`). In
+ * `per-project-tagged`, those project seeds also get project-suffixed ids so
+ * each tag can own its conventions/decisions models in the shared bank.
+ * Untagged seeds (e.g. `user-preferences`) read every memory in the bank — the
+ * reflect call applies no tag filter when `tags` is empty.
+ *
+ * Seed lifecycle is **create-only**: changes to `source_query`, `tags`,
+ * `max_tokens`, or `trigger` in `seeds.json` will NOT propagate to existing
+ * models on the server. Operators who want a structural change must
+ * `/memory mm refresh <id>` (content-only) or `/memory mm delete <id>`
+ * followed by a re-seed.
+ */
+import type { BankScope } from "./bank";
+import type { HindsightApi, MentalModelMode, MentalModelSummary, MentalModelTrigger } from "./client";
+import type { HindsightScoping } from "./config";
+interface RawSeed {
+    id: string;
+    name: string;
+    source_query: string;
+    scopes: HindsightScoping[];
+    projectTagged: boolean;
+    trigger?: {
+        mode?: MentalModelMode;
+        refresh_after_consolidation?: boolean;
+    };
+    max_tokens?: number;
+    extra_tags?: string[];
+}
+export interface MentalModelSeed {
+    id: string;
+    name: string;
+    sourceQuery: string;
+    tags: string[];
+    maxTokens?: number;
+    /** Legacy unqualified seed ids accepted as already-present when tags match. */
+    legacyIds?: string[];
+    trigger?: MentalModelTrigger;
+}
+/**
+ * Resolve the seed list that applies to the active bank scope. Per-project
+ * seeds are skipped in `global` mode (where there is no project axis) and
+ * `projectTagged` seeds inherit the scope's `retainTags`. In shared tagged
+ * banks, project seeds use project-suffixed ids and accept matching legacy
+ * bare ids as already present.
+ */
+export declare function resolveSeedsForScope(scope: BankScope, scoping: HindsightScoping): MentalModelSeed[];
+/**
+ * Idempotently create any seed mental models that don't already exist on the
+ * bank. Best-effort: a list/create failure does not throw — mental models are
+ * an optimization, not a precondition for retain/recall, and we mirror the
+ * swallow-on-failure pattern used by `ensureBankExists`.
+ *
+ * Existing models are NEVER modified. See module docstring.
+ */
+export declare function ensureMentalModels(client: HindsightApi, bankId: string, seeds: MentalModelSeed[], debug: boolean): Promise<void>;
+/** Return whether a seed is already represented by current bank metadata. */
+export declare function seedAlreadyExists(seed: MentalModelSeed, models: readonly MentalModelSummary[]): boolean;
+/**
+ * Default character budget for the rendered `<mental_models>` block. Mental
+ * models are injected on every prompt rebuild; an unbounded block can crowd
+ * out the user's actual context (and we cannot trust a curated/operator
+ * model to stay small without enforcement). The budget is a coarse char cap
+ * — token-accurate accounting would require a model-specific tokenizer we
+ * don't carry here.
+ */
+export declare const MENTAL_MODEL_RENDER_BUDGET_CHARS_DEFAULT = 16000;
+/**
+ * Pull the current mental-model snapshot from the server and render it into a
+ * `<mental_models>` block ready to be appended to developer instructions.
+ *
+ * Returns `undefined` when the server has no models yet, when the API call
+ * fails, or when every model still has empty content (e.g. the background
+ * reflect for a freshly-seeded model hasn't completed yet).
+ *
+ * The rendered block is bounded by `budgetChars` (default
+ * MENTAL_MODEL_RENDER_BUDGET_CHARS_DEFAULT). When `visibleTags` is supplied,
+ * tagged models must match at least one active tag; untagged models remain
+ * visible in every scope. Per-model content is truncated before assembly; if
+ * assembly still exceeds the budget, trailing models are dropped. A budget
+ * overflow leaves a `…` marker so the LLM can tell the snapshot is truncated.
+ */
+export declare function loadMentalModelsBlock(client: HindsightApi, bankId: string, budgetChars?: number, visibleTags?: readonly string[]): Promise<string | undefined>;
+export declare function renderMentalModelsBlock(models: MentalModelSummary[], budgetChars: number): string;
+/** Inventory line used by the `/memory mm list` command. */
+export declare function summarizeMentalModel(model: MentalModelSummary): string;
+/**
+ * Render a unified-style line diff between the previous and current content
+ * of a mental model. Hindsight's history endpoint returns the previous
+ * snapshot only; the diff is computed locally for display purposes.
+ *
+ * This is intentionally minimal — for "what changed" at a glance, not for a
+ * full structural diff. Each side is capped at `MAX_LCS_LINES` lines BEFORE
+ * the O(n*m) LCS table is built so a long curated model can never hang the
+ * TUI; output is then capped at `maxLines` so the rendered diff stays
+ * readable. The cap is signalled inline.
+ */
+/** Hard cap on input line count per side before LCS. Keeps the O(n*m) table tractable. */
+export declare const MAX_LCS_LINES = 1000;
+export declare function diffMentalModelContent(previous: string | null, current: string, maxLines?: number): string;
+/** Awaited only by the first-turn race in `beforeAgentStartPrompt`. */
+export declare const MENTAL_MODEL_FIRST_TURN_DEADLINE_MS = 1500;
+/** Cache TTL: re-list models on `agent_end` once this many ms have elapsed. */
+export declare const MENTAL_MODEL_REFRESH_INTERVAL_MS: number;
+/** Need-only export of the raw seed list for tests. */
+export declare const builtinSeedsForTest: ReadonlyArray<Readonly<RawSeed>>;
+export {};

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

@@ -0,0 +1,105 @@
+import type { AgentSession } from "../session/agent-session";
+import { type BankScope } from "./bank";
+import type { HindsightApi } from "./client";
+import type { HindsightConfig } from "./config";
+import { type HindsightMessage } from "./content";
+interface RecallOutcome {
+    context: string | null;
+    ok: boolean;
+}
+export interface HindsightSessionStateOptions {
+    /** Session id used for retain-queue metadata. */
+    sessionId: string;
+    client: HindsightApi;
+    bankId: string;
+    /** Tags applied to every retain — non-empty in per-project-tagged mode. */
+    retainTags?: string[];
+    /** Tag filter applied to every recall/reflect — non-empty in per-project-tagged mode. */
+    recallTags?: string[];
+    recallTagsMatch?: "any" | "all" | "any_strict" | "all_strict";
+    config: HindsightConfig;
+    session: AgentSession;
+    banksSet: Set<string>;
+    lastRetainedTurn?: number;
+    hasRecalledForFirstTurn?: boolean;
+    /**
+     * When set, this entry is a subagent alias that reuses the parent's bank,
+     * scope, config, client, and banksSet. Aliases skip auto-recall and
+     * auto-retain — those run on the parent only — but the recall/retain/reflect
+     * tools resolve via the alias so they persist to the same bank as the parent.
+     */
+    aliasOf?: HindsightSessionState;
+}
+/**
+ * Debounced batch queue for tool-initiated `retain` calls owned by one
+ * Hindsight session state instance.
+ *
+ * Auto-retain (`HindsightSessionState.retainSession`) is intentionally not
+ * routed through this queue — it submits a full transcript as one large item
+ * and already runs `async: true` server-side.
+ */
+export declare class HindsightRetainQueue {
+    #private;
+    constructor(state: HindsightSessionState);
+    get depth(): number;
+    enqueue(content: string, context?: string): void;
+    flush(): Promise<void>;
+    dispose(): void;
+}
+/** Per-session Hindsight runtime state owned by its AgentSession. */
+export declare class HindsightSessionState {
+    #private;
+    /** Session id used for retain-queue metadata. */
+    sessionId: string;
+    client: HindsightApi;
+    bankId: string;
+    /** Tags applied to every retain — non-empty in per-project-tagged mode. */
+    retainTags?: string[];
+    /** Tag filter applied to every recall/reflect — non-empty in per-project-tagged mode. */
+    recallTags?: string[];
+    recallTagsMatch?: "any" | "all" | "any_strict" | "all_strict";
+    config: HindsightConfig;
+    session: AgentSession;
+    banksSet: Set<string>;
+    lastRetainedTurn: number;
+    hasRecalledForFirstTurn: boolean;
+    lastRecallSnippet?: string;
+    /** Cached `<mental_models>` block injected into developer instructions. */
+    mentalModelsSnippet?: string;
+    /** When the cached snippet was last refreshed; gates the agent_end re-list. */
+    mentalModelsLoadedAt?: number;
+    /**
+     * In-flight ensure+load promise. `beforeAgentStartPrompt` awaits this on
+     * the first turn so the MM block lands in the system prompt before the
+     * LLM generates, even though `start()` returns before the load completes.
+     */
+    mentalModelsLoadPromise?: Promise<void>;
+    unsubscribe?: () => void;
+    /**
+     * Releases the `onHindsightScopeChanged` subscription that drives live
+     * rebuilds when `hindsight.bankId` / `bankIdPrefix` / `scoping` change.
+     * Only set on primary states; aliases inherit the parent's subscription.
+     */
+    unsubscribeScope?: () => void;
+    /** Alias states delegate persistence config to a primary parent state. */
+    aliasOf?: HindsightSessionState;
+    readonly retainQueue: HindsightRetainQueue;
+    constructor(options: HindsightSessionStateOptions);
+    setSessionId(sessionId: string): void;
+    resetConversationTracking(): void;
+    enqueueRetain(content: string, context?: string): void;
+    flushRetainQueue(): Promise<void>;
+    recallForContext(query: string, signal?: AbortSignal): Promise<RecallOutcome>;
+    retainSession(messages: HindsightMessage[]): Promise<void>;
+    maybeRetainOnAgentEnd(): Promise<void>;
+    forceRetainCurrentSession(): Promise<void>;
+    maybeRecallOnAgentStart(): Promise<void>;
+    beforeAgentStartPrompt(promptText: string): Promise<string | undefined>;
+    recallForCompaction(messages: HindsightMessage[]): Promise<string | undefined>;
+    runMentalModelLoad(scope: BankScope): Promise<void>;
+    refreshMentalModelsSnippet(): Promise<void>;
+    reloadMentalModels(): Promise<boolean>;
+    attachSessionListeners(): void;
+    dispose(): void;
+}
+export {};

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

@@ -0,0 +1,28 @@
+/**
+ * Pull plain-text user/assistant messages out of a session manager.
+ *
+ * The Hindsight retain/recall API only takes flat `{role, content}` records,
+ * so we drop tool calls, tool results, bash execution wrappers, custom
+ * messages, and anything else that isn't a primary conversation turn. Each
+ * surviving message's `TextContent` parts are joined with newlines.
+ */
+import type { SessionEntry } from "../session/session-entries";
+import { type HindsightMessage } from "./content";
+export interface ReadonlySessionManagerLike {
+    getEntries(): SessionEntry[];
+}
+/**
+ * Walk session entries top-to-bottom, returning a flat user/assistant list.
+ *
+ * Implementation choices:
+ * - Skip entries whose type isn't `"message"` (compaction, branch_summary,
+ *   custom_message, tool exec records, ...). Those don't represent a
+ *   conversational turn, only the LLM's plain-text utterances do.
+ * - Skip messages whose role isn't `"user"` or `"assistant"`. We deliberately
+ *   ignore `toolResult`, `bashExecution`, `hookMessage`, etc. — they're noise
+ *   for memory purposes.
+ * - For assistant messages, only `text` blocks contribute. Thinking and
+ *   toolCall blocks are intentionally dropped: the user never saw them, so
+ *   retaining them would prime recall on internal monologue.
+ */
+export declare function extractMessages(sessionManager: ReadonlySessionManagerLike): HindsightMessage[];

package/dist/types/index.d.ts

@@ -0,0 +1,43 @@
+import { HookEditorComponent, HookInputComponent, HookSelectorComponent } from "./modes/components";
+export { Container, Markdown, Spacer, Text } from "jeopi-tui";
+export { getAgentDir, logger, VERSION } from "jeopi-utils";
+export * as zod from "zod/v4";
+export { z } from "zod/v4";
+export * from "./config/keybindings";
+export * from "./config/model-registry";
+export type * from "./config/prompt-templates";
+export * from "./config/prompt-templates";
+export type { RetrySettings, SkillsSettings } from "./config/settings";
+export { Settings, settings } from "./config/settings";
+export type * from "./extensibility/custom-commands/types";
+export type * from "./extensibility/custom-tools";
+export * from "./extensibility/custom-tools";
+export type * from "./extensibility/extensions";
+export * from "./extensibility/extensions";
+export * from "./extensibility/skills";
+export { type FileSlashCommand, loadSlashCommands as discoverSlashCommands } from "./extensibility/slash-commands";
+export type * from "./lsp";
+export * from "./main";
+export * from "./modes";
+export * from "./modes/components";
+export * from "./modes/theme/theme";
+export * from "./sdk";
+export * from "./session/agent-session";
+export * from "./session/auth-storage";
+export * from "./session/indexed-session-storage";
+export * from "./session/messages";
+export * from "./session/redis-session-storage";
+export * from "./session/session-context";
+export * from "./session/session-dump-format";
+export * from "./session/session-entries";
+export * from "./session/session-listing";
+export * from "./session/session-loader";
+export * from "./session/session-manager";
+export * from "./session/session-migrations";
+export * from "./session/session-storage";
+export * from "./session/sql-session-storage";
+export * from "./task/executor";
+export type * from "./task/types";
+export * from "./tools";
+export * from "./utils/git";
+export { HookEditorComponent as ExtensionEditorComponent, HookInputComponent as ExtensionInputComponent, HookSelectorComponent as ExtensionSelectorComponent, };

package/dist/types/internal-urls/__tests__/ssh-protocol.test.d.ts

@@ -0,0 +1 @@
+export {};