hippo-memory 1.60.0 → 1.61.0

package/dist/api/assemble.js

@@ -0,0 +1,152 @@
+// Session context assembly under a token budget.
+import { loadEntriesByIds, loadSessionRawMemories, countSessionRawMemories } from '../store/entry-reads.js';
+import { estimateTokens } from '../token-ledger.js';
+import { passesScopeFilterForRecall, assertScopeRequestAllowed } from '../recall-scope.js';
+/**
+ * Build a chronologically-ordered context window for a session. Adapts the
+ * lossless-claw context-engine pattern to Hippo's score-ranked memory store.
+ *
+ * Algorithm:
+ *   1. Load all kind='raw' rows for the session, tenant + scope filtered.
+ *   2. Split: newest `freshTailCount` are protected (fresh tail).
+ *   3. For older rows, when ≥2 share a level-2 parent, substitute the
+ *      summary; everything else passes through as raw.
+ *   4. Hippo-additive eviction: when over-budget, drop the lowest-strength
+ *      non-fresh-tail item first. Fresh-tail rows are never evicted.
+ *
+ * Strength-weighted eviction is the differentiator from lossless-claw,
+ * which evicts oldest-first. A high-strength older row (high retrieval
+ * count, slow decay) survives; a low-strength recent row (newer but
+ * unimportant) goes first.
+ *
+ * Returns `items: []` cleanly when:
+ *   - sessionId is empty
+ *   - no raws exist for the session
+ *   - all rows fail the scope/tenant filter
+ */
+export function assemble(ctx, sessionId, opts = {}) {
+    assertScopeRequestAllowed(ctx.actor, opts.scope);
+    const budget = opts.budget ?? 4000;
+    const freshTailCount = opts.freshTailCount ?? 10;
+    const summarizeOlder = opts.summarizeOlder ?? true;
+    const rowCap = opts.rowCap ?? 5000;
+    if (!sessionId) {
+        return { sessionId, items: [], tokens: 0, totalRaw: 0, summarized: 0, evicted: 0, truncated: false };
+    }
+    const rows = loadSessionRawMemories(ctx.hippoRoot, sessionId, ctx.tenantId, rowCap);
+    const truncated = rows.length === rowCap;
+    // v1.6.3 senior-review P0-1: report the FULL post-filter row count even
+    // when the cap windows the loaded set. Pre-v1.6.3 used `scoped.length`
+    // which under-reported on long sessions and made consumers render
+    // wrong "session has N msgs" UX.
+    const scoped = rows.filter((r) => passesScopeFilterForRecall(r.scope ?? null, opts.scope));
+    let totalRaw;
+    if (truncated) {
+        // v1.6.3 codex P1 / senior P0: scope-aware unbounded COUNT. The helper
+        // SQL-encodes the same default-deny rule passesScopeFilterForRecall
+        // applies in TS, so a no-scope caller cannot infer private rows by
+        // comparing totalRaw to items.length on a truncated session.
+        totalRaw = countSessionRawMemories(ctx.hippoRoot, sessionId, ctx.tenantId, opts.scope);
+    }
+    else {
+        totalRaw = scoped.length;
+    }
+    if (scoped.length === 0) {
+        return { sessionId, items: [], tokens: 0, totalRaw, summarized: 0, evicted: 0, truncated };
+    }
+    // Split newest N into fresh tail; rest is older.
+    const tailStartIdx = Math.max(0, scoped.length - freshTailCount);
+    const olderRows = scoped.slice(0, tailStartIdx);
+    const tailRows = scoped.slice(tailStartIdx);
+    // Substitute parent summaries for older rows that share one.
+    const olderItems = [];
+    let summarized = 0;
+    if (summarizeOlder && olderRows.length > 0) {
+        const olderByParent = new Map();
+        for (const r of olderRows) {
+            if (!r.dag_parent_id)
+                continue;
+            const list = olderByParent.get(r.dag_parent_id) ?? [];
+            list.push(r);
+            olderByParent.set(r.dag_parent_id, list);
+        }
+        const eligibleParentIds = Array.from(olderByParent.keys()).filter((pid) => (olderByParent.get(pid)?.length ?? 0) >= 2);
+        const parents = eligibleParentIds.length > 0
+            ? loadEntriesByIds(ctx.hippoRoot, eligibleParentIds, ctx.tenantId)
+                .filter((p) => (p.dag_level ?? 0) === 2 && !p.superseded_by)
+                .filter((p) => passesScopeFilterForRecall(p.scope ?? null, opts.scope))
+            : [];
+        const claimedRawIds = new Set();
+        for (const parent of parents) {
+            const claimed = (olderByParent.get(parent.id) ?? []).map((r) => r.id);
+            claimed.forEach((id) => claimedRawIds.add(id));
+            olderItems.push({
+                id: parent.id,
+                content: parent.content,
+                createdAt: parent.earliest_at ?? parent.created,
+                isSummary: true,
+                substitutedFor: claimed,
+                strength: parent.strength,
+            });
+            summarized += claimed.length;
+        }
+        for (const r of olderRows) {
+            if (claimedRawIds.has(r.id))
+                continue;
+            olderItems.push({
+                id: r.id,
+                content: r.content,
+                createdAt: r.created,
+                strength: r.strength,
+            });
+        }
+    }
+    else {
+        for (const r of olderRows) {
+            olderItems.push({
+                id: r.id,
+                content: r.content,
+                createdAt: r.created,
+                strength: r.strength,
+            });
+        }
+    }
+    const tailItems = tailRows.map((r) => ({
+        id: r.id,
+        content: r.content,
+        createdAt: r.created,
+        isFreshTail: true,
+        strength: r.strength,
+    }));
+    // F4 (v1.6.5): byte compare canonical UTC ISO timestamps. ~50× faster than
+    // localeCompare and chronological by virtue of the timestamp invariant
+    // documented in src/memory.ts above MemoryEntry.
+    const cmpIso = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+    olderItems.sort((a, b) => cmpIso(a.createdAt, b.createdAt));
+    tailItems.sort((a, b) => cmpIso(a.createdAt, b.createdAt));
+    let items = [...olderItems, ...tailItems];
+    const itemCost = opts.cost?.item ?? ((it) => estimateTokens(it.content));
+    const room = budget - (opts.cost?.fixed(Math.max(budget, totalRaw)) ?? 0);
+    let tokens = items.reduce((acc, it) => acc + itemCost(it), 0);
+    let evicted = 0;
+    while (tokens > room && items.length > 0) {
+        let worstIdx = -1;
+        let worstStrength = Infinity;
+        for (let i = 0; i < items.length; i++) {
+            if (items[i].isFreshTail)
+                continue;
+            if (items[i].strength < worstStrength) {
+                worstStrength = items[i].strength;
+                worstIdx = i;
+            }
+        }
+        if (worstIdx === -1)
+            break;
+        const cost = itemCost(items[worstIdx]);
+        items = items.filter((_, i) => i !== worstIdx);
+        tokens -= cost;
+        evicted++;
+    }
+    return { sessionId, items, tokens, totalRaw, summarized, evicted, truncated };
+}
+//# sourceMappingURL=assemble.js.map

package/dist/api/audit.d.ts

@@ -0,0 +1,17 @@
+import { type AuditEvent, type AuditOp } from '../audit.js';
+import type { KeysetPosition } from '../keyset.js';
+import type { Context } from './types.js';
+export interface AuditListOpts {
+    op?: AuditOp;
+    /** ISO timestamp lower bound. */
+    since?: string;
+    limit?: number;
+    /** Resume after this row: the (ts, id) position the previous page ended on. */
+    after?: KeysetPosition;
+}
+/**
+ * Read audit events scoped to `ctx.tenantId`. Read-only — no audit emit (matches
+ * A5: cmdAuditList does not record a 'recall'-style read event).
+ */
+export declare function auditList(ctx: Context, opts: AuditListOpts): AuditEvent[];
+//# sourceMappingURL=audit.d.ts.map

package/dist/api/audit.js

@@ -0,0 +1,23 @@
+// Audit log queries.
+import { openHippoDb, closeHippoDb } from '../db.js';
+import { queryAuditEvents } from '../audit.js';
+/**
+ * Read audit events scoped to `ctx.tenantId`. Read-only — no audit emit (matches
+ * A5: cmdAuditList does not record a 'recall'-style read event).
+ */
+export function auditList(ctx, opts) {
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        return queryAuditEvents(db, {
+            tenantId: ctx.tenantId,
+            op: opts.op,
+            since: opts.since,
+            limit: opts.limit,
+            after: opts.after,
+        });
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+//# sourceMappingURL=audit.js.map

package/dist/api/auth.d.ts

@@ -0,0 +1,79 @@
+import { type ApiKeyListItem, type ApiKeyListRow } from '../auth.js';
+import type { KeysetPosition } from '../keyset.js';
+import type { Context } from './types.js';
+export interface AuthCreateOpts {
+    label?: string;
+    /**
+     * v1.12.3: authorization role for the new key. Defaults to `'admin'` for
+     * back-compat with v1.12.0-v1.12.2 (the api_keys.role column DEFAULT also
+     * resolves to 'admin' if omitted from the INSERT). Member keys are
+     * 403-blocked from admin-gated routes (e.g. `POST /v1/sleep`).
+     */
+    role?: 'admin' | 'member';
+}
+export interface AuthCreateResult {
+    keyId: string;
+    plaintext: string;
+    tenantId: string;
+    /** v1.12.3: the role bound to the new key (admin | member). */
+    role: 'admin' | 'member';
+}
+/**
+ * Mint a new API key. The new key is ALWAYS bound to `ctx.tenantId`. Callers
+ * cannot override the tenant via the opts bag — a previous `tenantId` field
+ * was removed because the HTTP layer would happily forward `body.tenantId`,
+ * letting tenant A mint a key for tenant B. The HTTP route handler at
+ * `src/server.ts` POST /v1/auth/keys mirrors this: it ignores any body
+ * `tenantId` and uses the resolved Bearer's tenant exclusively.
+ *
+ * Only an admin actor can mint (ForbiddenError otherwise), and a key never
+ * outranks its minter: a resolver admin is tenant-only, so it mints members.
+ */
+export declare function authCreate(ctx: Context, opts: AuthCreateOpts): AuthCreateResult;
+/**
+ * List API keys visible to the calling tenant.
+ *
+ * Divergence from `cmdAuthList` in src/cli.ts: the CLI today returns ALL keys
+ * regardless of tenant (single-tenant deployments). The API surface is tenant-
+ * scoped because future multi-tenant deployments will share a hippoRoot, and
+ * tenant A must not see tenant B's keys. Read-only — no audit emit (matches A5).
+ */
+export declare function authList(ctx: Context, opts: {
+    active: boolean;
+}): ApiKeyListItem[];
+/** One page of the caller's tenant's keys, newest first, with the row ids a next-page cursor is built from. */
+export declare function authListRows(ctx: Context, opts: {
+    active: boolean;
+    limit?: number;
+    after?: KeysetPosition;
+}): ApiKeyListRow[];
+/**
+ * Revoke an API key.
+ *
+ * Security: the key must belong to `ctx.tenantId`. Cross-tenant revoke is
+ * rejected with the "not found" message used for missing keys, and a member may
+ * revoke only its own key (checked first), so no caller can probe other key_ids.
+ *
+ * Audit: emits 'auth_revoke' with `tenantId` set to the KEY ROW's tenant_id
+ * (M1 fix from A5 review, mirrors src/cli.ts:cmdAuthRevoke). Skipped on no-op
+ * revoke (already revoked) so re-running doesn't pad the audit log.
+ */
+export interface AuthRevokeResult {
+    ok: true;
+    revokedAt: string;
+}
+export declare function authRevoke(ctx: Context, keyId: string): AuthRevokeResult;
+/**
+ * The tenant that owns `keyId`, or undefined for an unknown key. Host admin only: it reads across tenants,
+ * so the local CLI can run revoke and grant in the key's own tenant.
+ */
+export declare function authKeyTenant(ctx: Context, keyId: string): string | undefined;
+/** Shared result shape for authGrant/authUngrant, named per the file's oxlint anti-slop rule. */
+export interface AuthGrantResult {
+    ok: true;
+}
+/** Grant `keyId` read access to one restricted `scope` (ROADMAP Part VIII EI2). Admin only. */
+export declare function authGrant(ctx: Context, keyId: string, scope: string): AuthGrantResult;
+/** Revoke `keyId`'s grant on `scope`. Same authorization and lookup rules as authGrant. */
+export declare function authUngrant(ctx: Context, keyId: string, scope: string): AuthGrantResult;
+//# sourceMappingURL=auth.d.ts.map

package/dist/api/auth.js

@@ -0,0 +1,178 @@
+// API key management: create, list, revoke, and grant or ungrant restricted scopes.
+import { openHippoDb, closeHippoDb } from '../db.js';
+import { BadRequestError, ConflictError, ForbiddenError, NotFoundError } from '../api-errors.js';
+import { appendAuditEvent, reportAuditWriteFailure } from '../audit.js';
+import { createApiKey, listApiKeyRows, revokeApiKey, grantScope, ungrantScope } from '../auth.js';
+import { isRestrictedScope } from '../recall-scope.js';
+import { selectApiKeyOwner } from '../store/tenant-lookup.js';
+/**
+ * Mint a new API key. The new key is ALWAYS bound to `ctx.tenantId`. Callers
+ * cannot override the tenant via the opts bag — a previous `tenantId` field
+ * was removed because the HTTP layer would happily forward `body.tenantId`,
+ * letting tenant A mint a key for tenant B. The HTTP route handler at
+ * `src/server.ts` POST /v1/auth/keys mirrors this: it ignores any body
+ * `tenantId` and uses the resolved Bearer's tenant exclusively.
+ *
+ * Only an admin actor can mint (ForbiddenError otherwise), and a key never
+ * outranks its minter: a resolver admin is tenant-only, so it mints members.
+ */
+export function authCreate(ctx, opts) {
+    if (ctx.actor.role !== 'admin') {
+        throw new ForbiddenError('Only an admin key can create API keys');
+    }
+    if (ctx.actor.viaAuthResolver && opts.role === 'admin') {
+        throw new ForbiddenError('A key minted through the auth resolver can only be a member key');
+    }
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        const role = opts.role ?? (ctx.actor.viaAuthResolver ? 'member' : 'admin');
+        const result = createApiKey(db, { tenantId: ctx.tenantId, label: opts.label, role });
+        // v1.12.4: audit emit (closes the gap v1.12.3 CHANGELOG flagged as deferred).
+        // Mirrors the auth_revoke pattern at authRevoke — same try/catch so audit
+        // failure can't crash a successful mint. The plaintext is NEVER logged;
+        // metadata carries label + role + the keyId (which is non-secret).
+        try {
+            appendAuditEvent(db, {
+                tenantId: ctx.tenantId,
+                actor: ctx.actor.subject,
+                op: 'auth_create',
+                targetId: result.keyId,
+                metadata: {
+                    label: opts.label ?? null,
+                    role,
+                },
+            });
+        }
+        catch (error) {
+            // Audit must not crash a successful mint.
+            reportAuditWriteFailure('auth_create', String(error), result.keyId);
+        }
+        return { keyId: result.keyId, plaintext: result.plaintext, tenantId: ctx.tenantId, role };
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * List API keys visible to the calling tenant.
+ *
+ * Divergence from `cmdAuthList` in src/cli.ts: the CLI today returns ALL keys
+ * regardless of tenant (single-tenant deployments). The API surface is tenant-
+ * scoped because future multi-tenant deployments will share a hippoRoot, and
+ * tenant A must not see tenant B's keys. Read-only — no audit emit (matches A5).
+ */
+export function authList(ctx, opts) {
+    return authListRows(ctx, opts).map((r) => r.key);
+}
+/** One page of the caller's tenant's keys, newest first, with the row ids a next-page cursor is built from. */
+export function authListRows(ctx, opts) {
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        return listApiKeyRows(db, { ...opts, tenantId: ctx.tenantId });
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+export function authRevoke(ctx, keyId) {
+    if (ctx.actor.role !== 'admin' && ctx.actor.subject !== `api_key:${keyId}`) {
+        throw new ForbiddenError('A member key can revoke only itself');
+    }
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        const row = selectApiKeyOwner(db, keyId);
+        // Cross-tenant access denied: same message as missing key, no info leak.
+        if (!row || row.tenantId !== ctx.tenantId) {
+            throw new NotFoundError(`Unknown key_id: ${keyId}`);
+        }
+        if (ctx.actor.viaAuthResolver && row.role === 'admin') {
+            throw new ForbiddenError('An auth resolver admin cannot revoke an admin key, which outranks it');
+        }
+        let revokedAt;
+        let alreadyRevoked = false;
+        if (row.revokedAt) {
+            alreadyRevoked = true;
+            revokedAt = row.revokedAt;
+        }
+        else {
+            revokeApiKey(db, keyId);
+            revokedAt = selectApiKeyOwner(db, keyId)?.revokedAt ?? new Date().toISOString();
+        }
+        if (!alreadyRevoked) {
+            try {
+                appendAuditEvent(db, {
+                    tenantId: row.tenantId, // M1: KEY's tenant, not ctx.tenantId.
+                    actor: ctx.actor.subject,
+                    op: 'auth_revoke',
+                    targetId: keyId,
+                });
+            }
+            catch (error) {
+                // Audit must not crash a successful revoke.
+                reportAuditWriteFailure('auth_revoke', String(error), keyId);
+            }
+        }
+        return { ok: true, revokedAt };
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * The tenant that owns `keyId`, or undefined for an unknown key. Host admin only: it reads across tenants,
+ * so the local CLI can run revoke and grant in the key's own tenant.
+ */
+export function authKeyTenant(ctx, keyId) {
+    if (!ctx.actor.hostAdmin) {
+        throw new ForbiddenError('Only the host admin can look up a key across tenants');
+    }
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        return selectApiKeyOwner(db, keyId)?.tenantId;
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/** Grant `keyId` read access to one restricted `scope` (ROADMAP Part VIII EI2). Admin only. */
+export function authGrant(ctx, keyId, scope) {
+    return changeScopeGrant(ctx, keyId, scope, 'auth_grant');
+}
+/** Revoke `keyId`'s grant on `scope`. Same authorization and lookup rules as authGrant. */
+export function authUngrant(ctx, keyId, scope) {
+    return changeScopeGrant(ctx, keyId, scope, 'auth_ungrant');
+}
+function changeScopeGrant(ctx, keyId, scope, op) {
+    if (ctx.actor.role !== 'admin') {
+        throw new ForbiddenError('Only an admin key can change scope grants');
+    }
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        const row = selectApiKeyOwner(db, keyId);
+        if (!row || row.tenantId !== ctx.tenantId) {
+            throw new NotFoundError(`Unknown key_id: ${keyId}`);
+        }
+        if (op === 'auth_grant' && row.revokedAt) {
+            throw new ConflictError(`${keyId} is revoked; a grant on it would never apply`);
+        }
+        if (!isRestrictedScope(scope)) {
+            throw new BadRequestError(`${scope} is not a restricted scope; it is already readable by default`);
+        }
+        if (op === 'auth_grant')
+            grantScope(db, keyId, scope);
+        else
+            ungrantScope(db, keyId, scope);
+        try {
+            appendAuditEvent(db, { tenantId: ctx.tenantId, actor: ctx.actor.subject, op, targetId: keyId, metadata: { scope } });
+        }
+        catch (err) {
+            // Audit must not undo a grant change that already committed; surface it instead.
+            reportAuditWriteFailure(op, String(err), keyId);
+        }
+        return { ok: true };
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+//# sourceMappingURL=auth.js.map

package/dist/api/context-types.d.ts

@@ -0,0 +1,105 @@
+import type { TaskSnapshot, SessionEvent } from '../store/rows.js';
+import type { SessionHandoff } from '../handoff.js';
+import type { MemoryEntry } from '../memory.js';
+import type { DeliveryObserver } from '../delivery-recorder.js';
+import type { AmbientState } from '../ambient.js';
+/**
+ * Options for `getContext` — assemble a budget-bounded context bundle
+ * (recalled memories + active task snapshot + handoff + recent events).
+ * Extracted from `cmdContext` in `cli.ts` in Episode A of the api.ts refactor.
+ *
+ * Named `getContext` (not `context`) to avoid collision with the `Context`
+ * interface above and the ubiquitous `ctx: Context` convention. Follows the
+ * existing `getEntry` naming pattern in store.ts.
+ *
+ * Scope narrow (T5 execute decision): rendering opts (`format`, `framing`,
+ * `rendered`) and host-side opts (`auto`) are NOT included here. The print
+ * helpers (`printContextMarkdown`, `printActiveTaskSnapshot`, `printHandoff`,
+ * `printSessionEvents`) are shared with `cmdRecall` / `cmdSnapshot` /
+ * `cmdHandoffShow` — moving them into api.ts would expand T5 to also rewire
+ * those commands. CLI handles rendering + auto-resolution. Episode B can add
+ * `api.renderContext` once a shared rendering need actually materializes.
+ */
+export interface ContextOpts {
+    q?: string;
+    /** Default 1500 tokens. */
+    budget?: number;
+    limit?: number;
+    pinnedOnly?: boolean;
+    scope?: string;
+    /** Envelope scope to match exactly, as in `recall`: admits that scope even when private, after the actor's scope check. */
+    exactScope?: string;
+    /** With `pinnedOnly`, also inject the N most recent writes that pass the
+     *  quality floor (`isContentWorthStoring`, DF3). Filtering happens BEFORE
+     *  the take-N, so a caller asking for 5 gets 5 qualifying entries rather
+     *  than 5-minus-junk; pinned entries bypass the floor. Entries are only
+     *  skipped for this read, never mutated or deleted. Ignored when
+     *  `pinnedOnly` is false — no other path reads it. */
+    includeRecent?: number;
+    /** v39 memory scope isolation: re-include other-project memories that the
+     *  origin partition excludes by default. They come back tagged
+     *  `category: 'cross-project'` so renderers can demarcate them. */
+    crossProject?: boolean;
+    /** The active project name for the origin partition ('' = not in a
+     *  project). Defaults to `resolveProjectIdentity(process.cwd()).name`;
+     *  surfaces whose process cwd is not the caller's project (HTTP server)
+     *  should pass it explicitly. */
+    currentProject?: string;
+    /** DF1 (docs/plans/2026-08-23-df1-snapshot-lifecycle.md, T2): the calling
+     *  session's id. Stamped on this call's recall trace, and the owner-match input to
+     *  `loadFreshActiveTaskSnapshot` — when it strictly equals the active
+     *  snapshot's `session_id`, the read is unbounded (same-session
+     *  continuity); otherwise the snapshot must pass the freshness bound to
+     *  surface. Absent (undefined/null/'') never short-circuits as a match;
+     *  it just means every snapshot goes through the age check. Host-resolved
+     *  (stdin payload, HIPPO_SESSION_ID, else the host's session var) so this stays host-agnostic. */
+    currentSessionId?: string | null;
+    /** Z1: raw hook-payload prompt; only the pinned-only branch reads it, gated on `pinnedInject.promptRecall`. */
+    prompt?: string;
+    /** What the budget pays for, from the caller that renders the block. Absent = the memory text alone. */
+    cost?: ContextCost;
+    /** @internal The CLI's delivery-ledger observer; it only reads, so selection is the same with or without it. */
+    deliveryObserver?: DeliveryObserver;
+}
+/** Budget prices in the text a caller prints, so the budget bounds what reaches the model. */
+export interface ContextCost {
+    /** Tokens of one entry as printed. */
+    entry: (item: Pick<ContextResultEntry, 'entry' | 'isGlobal' | 'promptRecall' | 'origin' | 'category'>) => number;
+    /** Tokens of the headers and footer the block can print at this budget, reserved before any entry. */
+    fixed: (budget: number, can: {
+        cross: boolean;
+        promptRecall: boolean;
+        ambient: boolean;
+    }) => number;
+    /** Tokens of the sections printed ahead of the memories, each as printed. */
+    snapshot: (s: TaskSnapshot) => number;
+    handoff: (h: SessionHandoff) => number;
+    trail: (events: SessionEvent[]) => number;
+}
+export interface ContextResultEntry {
+    entry: MemoryEntry;
+    score: number;
+    /** What this entry cost the budget: its printed line under `ContextOpts.cost`, else its memory text. */
+    tokens: number;
+    isGlobal?: boolean;
+    isFreshTail?: boolean;
+    /** Z1: admitted by the prompt-recall gate, not the recent-N backfill or a pin. */
+    promptRecall?: boolean;
+    /** v39: the entry's owning project ('' = user-global, null = legacy row). */
+    origin?: string | null;
+    /** v39: how the origin relates to the active project. 'cross-project'
+     *  entries only appear when ContextOpts.crossProject was set (or isolation
+     *  is disabled). */
+    category?: 'project' | 'user-global' | 'cross-project';
+}
+export interface ContextResult {
+    entries: ContextResultEntry[];
+    tokens: number;
+    activeSnapshot?: TaskSnapshot | null;
+    sessionHandoff?: SessionHandoff | null;
+    recentEvents?: SessionEvent[];
+    /** The ambient landscape summary over every live row the read may see in the local and global stores,
+     *  not just the rows loaded. Present only when ambient config is on, the caller is not pinned-only, and an entry was returned. */
+    ambientState?: AmbientState;
+}
+//# sourceMappingURL=context-types.d.ts.map

package/dist/api/context-types.js

@@ -0,0 +1,3 @@
+// Option and result shapes for getContext.
+export {};
+//# sourceMappingURL=context-types.js.map

package/dist/api/context.d.ts

@@ -0,0 +1,31 @@
+import { type MemoryEntry } from '../memory.js';
+import type { ContextOpts, ContextResult } from './context-types.js';
+import type { Context } from './types.js';
+/**
+ * v39 S4: the secret half of the ambient policy on its own, for callers
+ * that apply their own scope rule. A flagged row is only admitted inside its owning project;
+ * flagged rows with no project origin never ambient-inject.
+ */
+export declare function ambientSecretAdmit(e: MemoryEntry, currentProjectName: string): boolean;
+/** Most rows per store a no-query context reads; past it, ranking and ambientState see the strongest by decay. */
+export declare const CONTEXT_CANDIDATE_CAP = 2000;
+export declare function oneCopyPerMemory(local: readonly MemoryEntry[], global: readonly MemoryEntry[], now: Date): [MemoryEntry[], MemoryEntry[]];
+/**
+ * Assemble a context bundle: recalled memories (pinned-only / strength-sorted
+ * fallback / hybrid search) + active task snapshot + session handoff + recent
+ * session events. Budget-bounded, tenant-scoped. Mutates `last_retrieval_ids`
+ * + emits a 'recall' audit row for non-pinned, non-'*' queries.
+ *
+ * Behaves like the pre-extraction `cmdContext` data-loading + selection
+ * pipeline. CLI presentation (markdown / json / additional-context rendering)
+ * stays in `cli.ts`.
+ *
+ * Tenant scope: all `loadAllEntries` / snapshot / handoff / events reads use
+ * `ctx.tenantId`. Cross-tenant rows are filtered out.
+ *
+ * Returns an empty result (`entries: []`, snapshot/handoff/events undefined)
+ * when there's nothing to surface (no memories AND no snapshot AND no handoff
+ * AND no recent events).
+ */
+export declare function getContext(ctx: Context, opts?: ContextOpts): Promise<ContextResult>;
+//# sourceMappingURL=context.d.ts.map