hippo-memory 1.60.0 → 1.61.0

package/dist/server/routes/processes.js

@@ -0,0 +1,161 @@
+// /v1/processes routes.
+import { closeProcess, loadProcessById, loadProcesses, saveProcess, VALID_PROCESS_STATES } from '../../processes.js';
+import { HttpError, sendJson } from '../../http-util.js';
+import { buildContextWithAuth } from '../auth.js';
+import { byCreatedAt, pageOf, parseCursor } from '../cursor.js';
+import { isJsonString, isSetMember, parseJsonBody, parseListLimit } from '../validation.js';
+// HTTP-boundary validation for a process `steps` body (untrusted). Returns the
+// step strings (saveProcess re-validates + trims, this is the fail-fast 400
+// gate). Caps mirror src/processes.ts MAX_PROCESS_STEPS / MAX_PROCESS_STEP_LEN.
+function validateProcessStepsBody(raw) {
+    if (raw === undefined || raw === null)
+        return [];
+    if (!Array.isArray(raw)) {
+        throw new HttpError(400, 'steps must be an array of strings');
+    }
+    if (raw.length > 200) {
+        throw new HttpError(400, 'steps exceeds 200-step cap');
+    }
+    for (const item of raw) {
+        if (!isJsonString(item)) {
+            throw new HttpError(400, 'each step must be a string');
+        }
+        if (item.trim().length === 0) {
+            throw new HttpError(400, 'a step is empty');
+        }
+        if (item.length > 2000) {
+            throw new HttpError(400, 'a step exceeds the 2000-character cap');
+        }
+    }
+    // SAFETY: every item in raw was confirmed to be a string in the loop above.
+    return raw;
+}
+// ── processes (E2 first-class object) ──
+//
+// 5 routes: POST /v1/processes (new; body processName + steps[] + description),
+// GET /v1/processes (list, status filter), GET /v1/processes/:id (show),
+// POST /v1/processes/:id/supersede (active -> superseded by a new version; body
+// steps[] + changeSummary + description; reuses the predecessor's name),
+// POST /v1/processes/:id/close (active -> closed). Bearer-authed + tenant-scoped
+// via buildContextWithAuth. status validated against VALID_PROCESS_STATES. DoS
+// caps: processName/description/changeSummary 4096, steps 200x2000
+// (validateProcessStepsBody). Mirrors /v1/decisions; the delta lifecycle is the
+// decision supersede path.
+export async function handleCreateProcess({ req, res, opts }) {
+    const ctx = await buildContextWithAuth(req, opts);
+    const body = await parseJsonBody(req, ctx);
+    const processName = body['processName'];
+    if (!isJsonString(processName) || processName.trim().length === 0) {
+        throw new HttpError(400, 'processName is required (non-empty string)');
+    }
+    if (processName.length > 4096) {
+        throw new HttpError(400, 'processName exceeds 4096-character cap');
+    }
+    const steps = validateProcessStepsBody(body['steps']);
+    const descriptionRaw = body['description'];
+    let description;
+    if (descriptionRaw !== undefined && descriptionRaw !== null) {
+        if (!isJsonString(descriptionRaw)) {
+            throw new HttpError(400, 'description must be a string');
+        }
+        if (descriptionRaw.length > 4096) {
+            throw new HttpError(400, 'description exceeds 4096-character cap');
+        }
+        description = descriptionRaw;
+    }
+    const process = saveProcess(opts.hippoRoot, ctx.tenantId, {
+        processName,
+        steps,
+        description,
+    }, ctx.actor.subject);
+    sendJson(res, 201, { process });
+    return;
+}
+export async function handleListProcesses({ req, res, opts, query }) {
+    const status = query.get('status') ?? 'all';
+    const limit = parseListLimit(query.get('limit'));
+    const after = parseCursor(query.get('cursor'), 'string', 'integer');
+    const ctx = await buildContextWithAuth(req, opts);
+    let processes;
+    if (status === 'all') {
+        processes = loadProcesses(opts.hippoRoot, ctx.tenantId, { limit: limit + 1, after });
+    }
+    else {
+        if (!isSetMember(VALID_PROCESS_STATES, status)) {
+            throw new HttpError(400, `status must be one of: active | superseded | closed | all (got "${status}")`);
+        }
+        processes = loadProcesses(opts.hippoRoot, ctx.tenantId, {
+            status,
+            limit: limit + 1,
+            after,
+        });
+    }
+    const page = pageOf(processes, limit, byCreatedAt);
+    sendJson(res, 200, { processes: page.items, next_cursor: page.nextCursor });
+    return;
+}
+export async function handleSupersedeProcess({ req, res, opts }, processSupersedeMatch) {
+    const id = parseInt(processSupersedeMatch[1], 10);
+    const ctx = await buildContextWithAuth(req, opts);
+    const body = await parseJsonBody(req, ctx);
+    const steps = validateProcessStepsBody(body['steps']);
+    if (steps.length === 0) {
+        throw new HttpError(400, 'steps is required (at least one step) for a supersession');
+    }
+    const changeRaw = body['changeSummary'];
+    let changeSummary;
+    if (changeRaw !== undefined && changeRaw !== null) {
+        if (!isJsonString(changeRaw)) {
+            throw new HttpError(400, 'changeSummary must be a string');
+        }
+        if (changeRaw.length > 4096) {
+            throw new HttpError(400, 'changeSummary exceeds 4096-character cap');
+        }
+        changeSummary = changeRaw;
+    }
+    const descRaw = body['description'];
+    let description;
+    if (descRaw !== undefined && descRaw !== null) {
+        if (!isJsonString(descRaw)) {
+            throw new HttpError(400, 'description must be a string');
+        }
+        if (descRaw.length > 4096) {
+            throw new HttpError(400, 'description exceeds 4096-character cap');
+        }
+        description = descRaw;
+    }
+    // A supersession is a new version of the SAME process: reuse the
+    // predecessor's name. 404 if the target does not exist; saveProcess's
+    // in-SAVEPOINT preflight is the authoritative active-state check (409).
+    const existing = loadProcessById(opts.hippoRoot, ctx.tenantId, id);
+    if (!existing) {
+        throw new HttpError(404, `process ${id} not found`);
+    }
+    const process = saveProcess(opts.hippoRoot, ctx.tenantId, {
+        processName: existing.processName,
+        steps,
+        description,
+        changeSummary,
+        supersedesProcessId: id,
+    }, ctx.actor.subject);
+    sendJson(res, 200, { process });
+    return;
+}
+export async function handleCloseProcess({ req, res, opts }, processCloseMatch) {
+    const id = parseInt(processCloseMatch[1], 10);
+    const ctx = await buildContextWithAuth(req, opts);
+    const process = closeProcess(opts.hippoRoot, ctx.tenantId, id, ctx.actor.subject);
+    sendJson(res, 200, { process });
+    return;
+}
+export async function handleGetProcess({ req, res, opts }, processByIdMatch) {
+    const id = parseInt(processByIdMatch[1], 10);
+    const ctx = await buildContextWithAuth(req, opts);
+    const process = loadProcessById(opts.hippoRoot, ctx.tenantId, id);
+    if (!process) {
+        throw new HttpError(404, `process ${id} not found`);
+    }
+    sendJson(res, 200, { process });
+    return;
+}
+//# sourceMappingURL=processes.js.map

package/dist/server/routes/project-briefs.d.ts

@@ -0,0 +1,8 @@
+import type { RouteRequest } from '../types.js';
+export declare function handleCreateProjectBrief({ req, res, opts }: RouteRequest): Promise<void>;
+export declare function handleListProjectBriefs({ req, res, opts, query }: RouteRequest): Promise<void>;
+export declare function handleRefreshProjectBrief({ req, res, opts }: RouteRequest): Promise<void>;
+export declare function handleSupersedeProjectBrief({ req, res, opts }: RouteRequest, briefSupersedeMatch: RegExpMatchArray): Promise<void>;
+export declare function handleCloseProjectBrief({ req, res, opts }: RouteRequest, briefCloseMatch: RegExpMatchArray): Promise<void>;
+export declare function handleGetProjectBrief({ req, res, opts }: RouteRequest, briefByIdMatch: RegExpMatchArray): Promise<void>;
+//# sourceMappingURL=project-briefs.d.ts.map

package/dist/server/routes/project-briefs.js

@@ -0,0 +1,136 @@
+// /v1/project-briefs routes.
+import { assembleBriefFromReceipts, closeProjectBrief, loadProjectBriefById, loadProjectBriefs, refreshBrief, saveProjectBrief, VALID_BRIEF_STATES } from '../../project-briefs.js';
+import { HttpError, sendJson } from '../../http-util.js';
+import { buildContextWithAuth } from '../auth.js';
+import { byCreatedAt, pageOf, parseCursor } from '../cursor.js';
+import { isJsonString, isSetMember, parseJsonBody, parseListLimit } from '../validation.js';
+// ── E2 project_brief routes ──
+//
+// 6 routes: POST /v1/project-briefs (new; body repo + summary), GET
+// /v1/project-briefs (list; status + repo filter; shared parseListLimit), POST
+// /v1/project-briefs/refresh (body {repo, dryRun?} -> auto-assemble the brief
+// from the repo's receipts; dryRun returns {markdown} without writing; ordered
+// before /:id), GET /v1/project-briefs/:id, POST /v1/project-briefs/:id/supersede,
+// POST /v1/project-briefs/:id/close. DoS caps: repo 256, summary 8192,
+// changeSummary 4096. The store validates + throws; the boundary maps validation
+// -> 400, not-found -> 404, not-active -> 409. Mirrors /v1/skills.
+export async function handleCreateProjectBrief({ req, res, opts }) {
+    const ctx = await buildContextWithAuth(req, opts);
+    const body = await parseJsonBody(req, ctx);
+    const repo = body['repo'];
+    if (!isJsonString(repo) || repo.trim().length === 0) {
+        throw new HttpError(400, 'repo is required (non-empty string)');
+    }
+    if (repo.length > 256) {
+        throw new HttpError(400, 'repo exceeds 256-character cap');
+    }
+    const summary = body['summary'];
+    if (!isJsonString(summary) || summary.trim().length === 0) {
+        throw new HttpError(400, 'summary is required (non-empty string)');
+    }
+    if (summary.length > 8192) {
+        throw new HttpError(400, 'summary exceeds 8192-character cap');
+    }
+    const brief = saveProjectBrief(opts.hippoRoot, ctx.tenantId, {
+        repo,
+        summary,
+    }, ctx.actor.subject);
+    sendJson(res, 201, { brief });
+    return;
+}
+export async function handleListProjectBriefs({ req, res, opts, query }) {
+    const status = query.get('status') ?? 'all';
+    const repoFilter = query.get('repo');
+    const limit = parseListLimit(query.get('limit'));
+    const after = parseCursor(query.get('cursor'), 'string', 'integer');
+    const ctx = await buildContextWithAuth(req, opts);
+    const listOpts = { limit: limit + 1, after };
+    if (repoFilter !== null && repoFilter.trim().length > 0) {
+        listOpts.repo = repoFilter.trim();
+    }
+    if (status !== 'all') {
+        if (!isSetMember(VALID_BRIEF_STATES, status)) {
+            throw new HttpError(400, `status must be one of: active | superseded | closed | all (got "${status}")`);
+        }
+        listOpts.status = status;
+    }
+    const briefs = loadProjectBriefs(opts.hippoRoot, ctx.tenantId, listOpts);
+    const page = pageOf(briefs, limit, byCreatedAt);
+    sendJson(res, 200, { briefs: page.items, next_cursor: page.nextCursor });
+    return;
+}
+// The refresh op: must precede the /:id routes (literal 'refresh' is non-numeric
+// so the /(\d+)/ routes would not match it, but order it first).
+export async function handleRefreshProjectBrief({ req, res, opts }) {
+    const ctx = await buildContextWithAuth(req, opts);
+    const body = await parseJsonBody(req, ctx);
+    const repo = body['repo'];
+    if (!isJsonString(repo) || repo.trim().length === 0) {
+        throw new HttpError(400, 'repo is required (non-empty string)');
+    }
+    if (repo.length > 256) {
+        throw new HttpError(400, 'repo exceeds 256-character cap');
+    }
+    const dryRun = body['dryRun'] === true;
+    if (dryRun) {
+        const { markdown, receiptCount } = assembleBriefFromReceipts(opts.hippoRoot, ctx.tenantId, repo);
+        sendJson(res, 200, { markdown, receiptCount });
+        return;
+    }
+    const brief = refreshBrief(opts.hippoRoot, ctx.tenantId, repo, ctx.actor.subject);
+    sendJson(res, 200, { brief });
+    return;
+}
+export async function handleSupersedeProjectBrief({ req, res, opts }, briefSupersedeMatch) {
+    const id = parseInt(briefSupersedeMatch[1], 10);
+    const ctx = await buildContextWithAuth(req, opts);
+    const body = await parseJsonBody(req, ctx);
+    const summary = body['summary'];
+    if (!isJsonString(summary) || summary.trim().length === 0) {
+        throw new HttpError(400, 'summary is required (non-empty string)');
+    }
+    if (summary.length > 8192) {
+        throw new HttpError(400, 'summary exceeds 8192-character cap');
+    }
+    const changeRaw = body['changeSummary'];
+    let changeSummary;
+    if (changeRaw !== undefined && changeRaw !== null) {
+        if (!isJsonString(changeRaw)) {
+            throw new HttpError(400, 'changeSummary must be a string');
+        }
+        if (changeRaw.length > 4096) {
+            throw new HttpError(400, 'changeSummary exceeds 4096-character cap');
+        }
+        changeSummary = changeRaw;
+    }
+    const existing = loadProjectBriefById(opts.hippoRoot, ctx.tenantId, id);
+    if (!existing) {
+        throw new HttpError(404, `project brief ${id} not found`);
+    }
+    const brief = saveProjectBrief(opts.hippoRoot, ctx.tenantId, {
+        repo: existing.repo,
+        summary,
+        changeSummary,
+        supersedesBriefId: id,
+    }, ctx.actor.subject);
+    sendJson(res, 200, { brief });
+    return;
+}
+export async function handleCloseProjectBrief({ req, res, opts }, briefCloseMatch) {
+    const id = parseInt(briefCloseMatch[1], 10);
+    const ctx = await buildContextWithAuth(req, opts);
+    const brief = closeProjectBrief(opts.hippoRoot, ctx.tenantId, id, ctx.actor.subject);
+    sendJson(res, 200, { brief });
+    return;
+}
+export async function handleGetProjectBrief({ req, res, opts }, briefByIdMatch) {
+    const id = parseInt(briefByIdMatch[1], 10);
+    const ctx = await buildContextWithAuth(req, opts);
+    const brief = loadProjectBriefById(opts.hippoRoot, ctx.tenantId, id);
+    if (!brief) {
+        throw new HttpError(404, `project brief ${id} not found`);
+    }
+    sendJson(res, 200, { brief });
+    return;
+}
+//# sourceMappingURL=project-briefs.js.map

package/dist/server/routes/recall.d.ts

@@ -0,0 +1,8 @@
+import type { RouteRequest } from '../types.js';
+/** Test-only: reset the module-level recall-history Map. Call from beforeEach. */
+export declare function __resetSessionRecallHistoryHttp(): void;
+export declare function handleRecallMemories({ req, res, opts, query }: RouteRequest): Promise<void>;
+export declare function handleAssembleSession({ req, res, opts, query }: RouteRequest, assembleMatch: Record<string, string>): Promise<void>;
+export declare function handleDrillRecall({ req, res, opts, query }: RouteRequest, drillMatch: Record<string, string>): Promise<void>;
+export declare function handleGetContext({ req, res, opts, query }: RouteRequest): Promise<void>;
+//# sourceMappingURL=recall.d.ts.map

package/dist/server/routes/recall.js

@@ -0,0 +1,340 @@
+// Recall routes: /v1/memories search, assemble, drill and /v1/context.
+import { dirname, resolve } from 'node:path';
+import { resolveProjectIdentity } from '../../project-identity.js';
+import { assembleCost, contextCost, drillCost } from '../../context-render.js';
+import { closeHippoDb, openHippoDb } from '../../db.js';
+import { updateStats } from '../../store/index-and-stats.js';
+import { appendRecall, biasHintEnabled, buildSessionKey, getOrCreateRing, hashQueryText, snapshotRing } from '../../recall-history.js';
+import { appendAuditEvent, auditQueryFields } from '../../audit.js';
+import { assemble, drillDown, getContext, recordTokens, retrieve } from '../../api.js';
+import { HttpError, sendJson } from '../../http-util.js';
+import { buildContextWithAuth } from '../auth.js';
+import { parseListLimit, validateIdSegment } from '../validation.js';
+// v0.33 / J1 — Module-level per-(tenant, session) recall-history ring map
+// for the HTTP pipeline. Separate from CLI/MCP rings per plan v3 (per-
+// pipeline rings; no IPC). HTTP is the only caller that threads its
+// snapshot through opts.recallHistory to api.recall — api.recall's
+// anchoringHint on the returned RecallResult IS the user-visible hint
+// here (no separate compute needed).
+const sessionRecallHistoryHttp = new Map();
+/** Test-only: reset the module-level recall-history Map. Call from beforeEach. */
+export function __resetSessionRecallHistoryHttp() {
+    sessionRecallHistoryHttp.clear();
+}
+// GET /v1/memories?q=...&limit=...&mode=...&scope=...&include_continuity=1
+export async function handleRecallMemories({ req, res, opts, query }) {
+    const q = query.get('q');
+    if (!q) {
+        throw new HttpError(400, 'q is required');
+    }
+    const limitRaw = query.get('limit');
+    const limit = limitRaw === null ? undefined : parseListLimit(limitRaw);
+    const mode = query.get('mode');
+    if (mode !== null && mode !== 'bm25' && mode !== 'hybrid' && mode !== 'physics') {
+        throw new HttpError(400, "mode must be 'bm25', 'hybrid', or 'physics'");
+    }
+    const scope = query.get('scope');
+    const includeContinuityRaw = query.get('include_continuity');
+    const includeContinuity = includeContinuityRaw === '1'
+        || includeContinuityRaw === 'true';
+    // v1.6.2: surface the v1.5.0/v1.5.2 RecallOpts additions to HTTP
+    // callers. Pre-v1.6.2 the route silently ignored these so the
+    // session-scoped fresh-tail and summary substitution were JS-only.
+    const freshTailCountRaw = query.get('fresh_tail_count');
+    const freshTailCount = freshTailCountRaw === null ? undefined : Number(freshTailCountRaw);
+    if (freshTailCount !== undefined && (!Number.isFinite(freshTailCount) || freshTailCount < 0)) {
+        throw new HttpError(400, 'fresh_tail_count must be a non-negative number');
+    }
+    // v1.6.3 senior-review P1-3: cap session_id length consistent with the
+    // rest of the API. Untrimmed strings round-trip through the SQL layer
+    // and through any downstream metric/log; 256 is generous for a session
+    // id and matches the rest of this file's id-shaped param parsers.
+    const freshTailSessionIdRaw = query.get('fresh_tail_session_id');
+    if (freshTailSessionIdRaw !== null && freshTailSessionIdRaw.length > 256) {
+        throw new HttpError(400, 'fresh_tail_session_id exceeds 256-character cap');
+    }
+    const freshTailSessionId = freshTailSessionIdRaw && freshTailSessionIdRaw.length > 0
+        ? freshTailSessionIdRaw
+        : undefined;
+    // v1.6.3 senior-review P1-4: tighten parser to match the includeContinuity
+    // convention. Pre-v1.6.3 accepted any non-'0'/'false' value as `true`,
+    // so `?summarize_overflow=banana` and `?summarize_overflow=` both
+    // turned it on. Surface convention drift fixed.
+    const summarizeOverflowRaw = query.get('summarize_overflow');
+    const summarizeOverflow = summarizeOverflowRaw === null
+        ? undefined
+        : (summarizeOverflowRaw === '1' || summarizeOverflowRaw === 'true');
+    // recall() owns the shape rule (NaN, 0 and negatives throw invalid_scorer_window); the transport caps remote cost.
+    const scorerWindowRaw = query.get('scorer_window');
+    const scorerWindow = scorerWindowRaw === null ? undefined : Number(scorerWindowRaw);
+    if (scorerWindow !== undefined && scorerWindow > 1000) {
+        throw new HttpError(400, 'scorer_window must be <= 1000');
+    }
+    // v1.7.4: session_id for the dlPFC goal-stack boost. 256-char cap mirrors
+    // fresh_tail_session_id (above). Trim then drop if empty so api.recall
+    // sees undefined when the param is omitted or whitespace-only.
+    const sessionIdRaw = query.get('session_id');
+    if (sessionIdRaw !== null && sessionIdRaw.length > 256) {
+        throw new HttpError(400, 'session_id exceeds 256-character cap');
+    }
+    const sessionId = sessionIdRaw && sessionIdRaw.trim().length > 0
+        ? sessionIdRaw.trim()
+        : undefined;
+    // A7 recall-trace: opt-in explain flag. When set, api.recall attaches the
+    // lifecycle re-ranking trace (goal-boost step on the api pipeline) +
+    // rerankPipeline:'api' to each result item; the field then rides on the
+    // serialized RecallResult. Mirrors the include_continuity convention.
+    const explainRaw = query.get('explain');
+    const explain = explainRaw === '1' || explainRaw === 'true';
+    const ctx = await buildContextWithAuth(req, opts);
+    // v0.33 / J1 — HTTP per-pipeline anchoring detector. HTTP threads its
+    // ring snapshot via opts.recallHistory so api.recall's own
+    // anchoringHint compute path activates. Unlike CLI (which computes
+    // its own hint separately because cmdRecall runs its own physics/
+    // hybrid pipeline outside api.recall), HTTP's /v1/memories response
+    // body IS api.recall's result directly. So the api.recall-computed
+    // hint flows through. HIPPO_ANCHORING=off short-circuits.
+    let httpRecallHistory;
+    let httpRingKey;
+    if (biasHintEnabled('anchoring')) {
+        if (sessionId) {
+            // Codex round-5 P2 catch: do NOT mutate sessionRecallHistoryHttp
+            // before recall() preflight runs. A request with an invalid
+            // scorer_window / fresh_tail_count would create-or-touch the
+            // session ring (LRU-evicting valid sessions) even though recall
+            // throws 400. Snapshot the EXISTING ring if present; only
+            // create-or-touch after the recall returns successfully.
+            httpRingKey = buildSessionKey(ctx.tenantId, sessionId);
+            const existingRing = sessionRecallHistoryHttp.get(httpRingKey);
+            httpRecallHistory = existingRing ? snapshotRing(existingRing) : [];
+        }
+        else {
+            // Telemetry: caller had no session_id so ring tracking skipped.
+            // Per the normal recall-audit convention (api.ts:854 stores
+            // SHA-256/16 hash of the query, NOT raw text), avoid retaining
+            // prompts in audit_log here too — query content can contain
+            // secrets, PII, or RTBF-restricted material. Codex round-2 P2
+            // catch: hashQueryText is a 32-bit FNV-1a designed for recall
+            // matching, NOT a privacy hash; brute-force trivial for low-
+            // entropy queries. Use the same SHA-256/16 truncation as the
+            // canonical recall audit.
+            const dbForAudit = openHippoDb(opts.hippoRoot);
+            try {
+                appendAuditEvent(dbForAudit, {
+                    tenantId: ctx.tenantId,
+                    actor: ctx.actor.subject,
+                    op: 'recall_anchor_skipped_no_session',
+                    targetId: undefined,
+                    metadata: auditQueryFields(q),
+                });
+            }
+            finally {
+                closeHippoDb(dbForAudit);
+            }
+        }
+    }
+    const recallExtra = {};
+    if (freshTailCount !== undefined)
+        recallExtra.freshTailCount = freshTailCount;
+    if (freshTailSessionId !== undefined)
+        recallExtra.freshTailSessionId = freshTailSessionId;
+    if (summarizeOverflow !== undefined)
+        recallExtra.summarizeOverflow = summarizeOverflow;
+    if (scorerWindow !== undefined)
+        recallExtra.scorerWindow = scorerWindow;
+    if (sessionId !== undefined)
+        recallExtra.sessionId = sessionId;
+    if (httpRecallHistory !== undefined)
+        recallExtra.recallHistory = httpRecallHistory;
+    if (explain)
+        recallExtra.explain = explain;
+    const result = await retrieve(ctx, {
+        query: q,
+        limit,
+        mode: mode ?? undefined,
+        scope: scope ?? undefined,
+        includeContinuity,
+        ...recallExtra,
+    });
+    // v0.33 / J1 — append AFTER recall completes (snapshot was taken before
+    // recall() ran). anchoredOn carries the memoryId of any hint that fired
+    // (api.recall computed it from the same snapshot we passed in), feeding
+    // the cooldown logic for the NEXT recall on this session.
+    // Codex round-5 P2 fix: create-or-touch the ring ONLY HERE, after recall
+    // returns successfully. Invalid requests that throw 400 in recall()
+    // never reach this point, so they cannot LRU-evict valid sessions.
+    if (httpRingKey) {
+        const httpRing = getOrCreateRing(sessionRecallHistoryHttp, httpRingKey);
+        const topId = result.results[0]?.id ?? null;
+        appendRecall(httpRing, hashQueryText(q), topId, result.anchoringHint?.memoryId);
+    }
+    // Each recall surface counts its own hits; api.recall is no chokepoint,
+    // since the CLI never calls it and MCP shows the user a different band.
+    updateStats(opts.hippoRoot, { recalled: result.results.length });
+    // Continuity payloads should never be cached. The caller is asking for
+    // session-state-aware data; intermediaries must not reuse it across users.
+    if (includeContinuity) {
+        res.setHeader('Cache-Control', 'no-store');
+    }
+    recordTokens(ctx, 'http_recall', { items: result.results.length, tokens: result.tokens + (result.continuityTokens ?? 0), sessionId: sessionId ?? null });
+    sendJson(res, 200, result);
+    return;
+}
+// GET /v1/sessions/:id/assemble?budget=N&freshTail=N&summarizeOlder=0|1
+// Phase 2 context-engine API. Returns ordered AssembledContextItem[]
+// with fresh-tail raws + summary substitutions + bio-aware budget fit.
+// Tenant scope from Bearer; default-deny on private rows.
+export async function handleAssembleSession({ req, res, opts, query }, assembleMatch) {
+    validateIdSegment(assembleMatch.id, 'session id');
+    const budgetRaw = query.get('budget');
+    const budget = budgetRaw === null ? undefined : Number(budgetRaw);
+    if (budget !== undefined && (!Number.isFinite(budget) || budget <= 0)) {
+        throw new HttpError(400, 'budget must be a positive number');
+    }
+    const ftRaw = query.get('freshTail');
+    const freshTailCount = ftRaw === null ? undefined : Number(ftRaw);
+    if (freshTailCount !== undefined && (!Number.isFinite(freshTailCount) || freshTailCount < 0)) {
+        throw new HttpError(400, 'freshTail must be a non-negative number');
+    }
+    // v1.6.3 senior review P1: same strict-parse convention as the v1.6.3
+    // summarize_overflow tighten on /v1/memories. Pre-v1.6.3 accepted any
+    // non-'0'/'false' as true; ?summarizeOlder=banana now correctly returns
+    // false (matches includeContinuity convention).
+    const sumOlderRaw = query.get('summarizeOlder');
+    const summarizeOlder = sumOlderRaw === null
+        ? undefined
+        : (sumOlderRaw === '1' || sumOlderRaw === 'true');
+    const scopeQ = query.get('scope');
+    const scope = scopeQ !== null && scopeQ.length > 0 ? scopeQ : undefined;
+    const ctx = await buildContextWithAuth(req, opts);
+    const assembleExtra = {};
+    if (budget !== undefined)
+        assembleExtra.budget = budget;
+    if (freshTailCount !== undefined)
+        assembleExtra.freshTailCount = freshTailCount;
+    if (summarizeOlder !== undefined)
+        assembleExtra.summarizeOlder = summarizeOlder;
+    if (scope !== undefined)
+        assembleExtra.scope = scope;
+    const result = assemble(ctx, assembleMatch.id, { ...assembleExtra, cost: assembleCost(assembleMatch.id) });
+    recordTokens(ctx, 'http_assemble', { items: result.items.length, tokens: result.tokens, sessionId: assembleMatch.id });
+    sendJson(res, 200, result);
+    return;
+}
+// GET /v1/recall/drill/:id?limit=N&budget=N
+// Companion to /v1/memories. When recall surfaces a level-2 summary in
+// place of overflowed children (RecallResultItem.isSummary === true), the
+// caller drills into the summary id to recover the originals. Tenant
+// scoped via Bearer; default-deny on private scopes for both summary
+// and children.
+export async function handleDrillRecall({ req, res, opts, query }, drillMatch) {
+    validateIdSegment(drillMatch.id, 'summary id');
+    const limitRaw = query.get('limit');
+    const limit = limitRaw === null ? undefined : Number(limitRaw);
+    if (limit !== undefined && (!Number.isFinite(limit) || limit <= 0)) {
+        throw new HttpError(400, 'limit must be a positive number');
+    }
+    const budgetRaw = query.get('budget');
+    const budget = budgetRaw === null ? undefined : Number(budgetRaw);
+    if (budget !== undefined && (!Number.isFinite(budget) || budget <= 0)) {
+        throw new HttpError(400, 'budget must be a positive number');
+    }
+    // v0.30 / E5: depth query param walks N levels (default 1, hard cap 10).
+    const depthRaw = query.get('depth');
+    let depth;
+    if (depthRaw !== null) {
+        const parsed = Number(depthRaw);
+        // L4 fold: reject out-of-range explicitly (no silent clamp).
+        if (!Number.isInteger(parsed) || parsed < 1 || parsed > 10) {
+            throw new HttpError(400, 'depth must be a positive integer between 1 and 10');
+        }
+        depth = parsed;
+    }
+    const ctx = await buildContextWithAuth(req, opts);
+    const drillExtra = {};
+    if (limit !== undefined)
+        drillExtra.limit = limit;
+    if (budget !== undefined)
+        drillExtra.budget = budget;
+    if (depth !== undefined)
+        drillExtra.depth = depth;
+    const result = drillDown(ctx, drillMatch.id, { ...drillExtra, cost: drillCost });
+    if ('failure' in result) {
+        // v1.6.4: leaf id maps to 422 (caller-actionable). Other cases stay
+        // as 404 to avoid leaking cross-tenant existence or scope grants.
+        if (result.failure === 'not_drillable') {
+            throw new HttpError(422, 'Id is a leaf row, not a level-2+ summary; nothing to drill into');
+        }
+        throw new HttpError(404, 'No drillable summary at this id');
+    }
+    sendJson(res, 200, result);
+    return;
+}
+// GET /v1/context — assemble a budget-bounded context bundle. Returns
+// ContextResult JSON (entries + tokens + activeSnapshot + sessionHandoff
+// + recentEvents). No server-side rendering; clients render. Tenant-scoped
+// via the Bearer. Pinned-only + '*' fallback skip the recall audit emit
+// (matches cmdContext); real-query hybrid search emits one 'recall' row.
+export async function handleGetContext({ req, res, opts, query }) {
+    const q = query.get('q') ?? undefined;
+    // v1.11.5: DoS cap on q-param length. 1024 covers real multi-clause queries
+    // (pasted error messages, multi-stem searches) while bounding BM25
+    // tokenisation cost (~150 tokens worst case at 1024 chars).
+    if (q !== undefined && q.length > 1024) {
+        throw new HttpError(400, 'q exceeds 1024-character cap');
+    }
+    const budgetRaw = query.get('budget');
+    let budget;
+    if (budgetRaw !== null) {
+        budget = Number(budgetRaw);
+        if (!Number.isFinite(budget) || budget < 0) {
+            throw new HttpError(400, 'budget must be a non-negative number');
+        }
+    }
+    const limitRaw = query.get('limit');
+    let limit;
+    if (limitRaw !== null) {
+        limit = Number(limitRaw);
+        if (!Number.isFinite(limit) || limit <= 0) {
+            throw new HttpError(400, 'limit must be a positive number');
+        }
+    }
+    const pinnedOnlyRaw = query.get('pinned_only');
+    const pinnedOnly = pinnedOnlyRaw === '1' || pinnedOnlyRaw === 'true';
+    const scopeRaw = query.get('scope');
+    if (scopeRaw !== null && scopeRaw.length > 256) {
+        throw new HttpError(400, 'scope exceeds 256-character cap');
+    }
+    const scope = scopeRaw === null ? undefined : scopeRaw;
+    const includeRecentRaw = query.get('include_recent');
+    let includeRecent;
+    if (includeRecentRaw !== null) {
+        includeRecent = Number(includeRecentRaw);
+        if (!Number.isFinite(includeRecent) || includeRecent < 0) {
+            throw new HttpError(400, 'include_recent must be a non-negative number');
+        }
+    }
+    // v39 memory scope isolation: cross_project=1|true re-includes
+    // other-project rows (tagged category 'cross-project' in the response).
+    // The partition identity comes from the SERVED STORE's location, not the
+    // daemon's process cwd - a daemon started from anywhere still isolates
+    // the project it serves.
+    const crossProjectRaw = query.get('cross_project');
+    const crossProject = crossProjectRaw === '1' || crossProjectRaw === 'true';
+    const ctx = await buildContextWithAuth(req, opts);
+    const result = await getContext(ctx, {
+        q,
+        budget,
+        limit,
+        pinnedOnly,
+        scope,
+        includeRecent,
+        crossProject,
+        currentProject: resolveProjectIdentity(dirname(resolve(opts.hippoRoot))).name,
+        cost: contextCost('markdown', 'observe'), // clients render; the budget prices the block `hippo context` would print
+    });
+    recordTokens(ctx, 'http_context', { items: result.entries.length, tokens: result.tokens });
+    sendJson(res, 200, result);
+    return;
+}
+//# sourceMappingURL=recall.js.map

package/dist/server/routes/skills.d.ts

@@ -0,0 +1,8 @@
+import type { RouteRequest } from '../types.js';
+export declare function handleCreateSkill({ req, res, opts }: RouteRequest): Promise<void>;
+export declare function handleListSkills({ req, res, opts, query }: RouteRequest): Promise<void>;
+export declare function handleExportSkills({ req, res, opts }: RouteRequest): Promise<void>;
+export declare function handleSupersedeSkill({ req, res, opts }: RouteRequest, skillSupersedeMatch: RegExpMatchArray): Promise<void>;
+export declare function handleCloseSkill({ req, res, opts }: RouteRequest, skillCloseMatch: RegExpMatchArray): Promise<void>;
+export declare function handleGetSkill({ req, res, opts }: RouteRequest, skillByIdMatch: RegExpMatchArray): Promise<void>;
+//# sourceMappingURL=skills.d.ts.map