@dotdotgod/context 0.2.25 → 0.2.27

package/src/html-normalize.mjs

@@ -0,0 +1,195 @@
+const DEFAULT_INPUT_BYTES = 10 * 1024 * 1024;
+const DEFAULT_OUTPUT_BYTES = 10 * 1024 * 1024;
+const EXTRACTOR = 'html-v1';
+const ACCEPTED_MIME = new Set(['text/html', 'application/xhtml+xml']);
+const ACCEPTED_CHARSET = new Set(['utf-8', 'utf8', 'us-ascii']);
+const MAX_LINKS = 100;
+const MAX_LINK_METADATA_BYTES = 64 * 1024;
+const BLOCK_TAGS = new Set(['address', 'article', 'aside', 'blockquote', 'br', 'dd', 'div', 'dl', 'dt', 'figcaption', 'figure', 'footer', 'header', 'hr', 'main', 'nav', 'p', 'section', 'tr']);
+const DROP_CONTENT = new Set(['script', 'style', 'noscript', 'template', 'svg', 'math', 'iframe', 'object', 'embed', 'form']);
+
+function positiveLimit(value, fallback) {
+  if (value === undefined) return fallback;
+  if (!Number.isFinite(value) || value <= 0) throw new TypeError('HTML byte limits must be positive finite numbers.');
+  return Math.floor(value);
+}
+
+function parseMediaType(value) {
+  const raw = String(value ?? 'text/html');
+  const [type, ...parameters] = raw.split(';');
+  const mimeType = type.trim().toLowerCase();
+  if (!ACCEPTED_MIME.has(mimeType)) throw new Error(`Unsupported HTML MIME type: ${mimeType || '(empty)'}`);
+  let charset = 'utf-8';
+  for (const parameter of parameters) {
+    const match = /^\s*charset\s*=\s*(?:"([^"]+)"|'([^']+)'|([^\s;]+))\s*$/iu.exec(parameter);
+    if (match) charset = (match[1] || match[2] || match[3]).toLowerCase();
+  }
+  if (!ACCEPTED_CHARSET.has(charset)) throw new Error(`Unsupported HTML charset: ${charset}`);
+  return { mimeType, charset: charset === 'utf8' ? 'utf-8' : charset };
+}
+
+function decodeEntities(value) {
+  const named = { amp: '&', apos: "'", gt: '>', lt: '<', nbsp: ' ', quot: '"' };
+  return value.replace(/&(#(?:x[0-9a-f]+|\d+)|[a-z]+);/giu, (whole, entity) => {
+    if (entity[0] !== '#') return named[entity.toLowerCase()] ?? whole;
+    const hexadecimal = entity[1]?.toLowerCase() === 'x';
+    const number = Number.parseInt(entity.slice(hexadecimal ? 2 : 1), hexadecimal ? 16 : 10);
+    if (!Number.isInteger(number) || number < 0 || number > 0x10ffff || (number >= 0xd800 && number <= 0xdfff)) return '\uFFFD';
+    return String.fromCodePoint(number);
+  });
+}
+
+function normalizeWhitespace(value) {
+  return value
+    .replace(/[\t\f\v ]+/gu, ' ')
+    .replace(/ *\n */gu, '\n')
+    .replace(/\n{3,}/gu, '\n\n')
+    .trim();
+}
+
+function boundedUtf8(value, maxBytes) {
+  if (Buffer.byteLength(value) <= maxBytes) return { value, truncated: false };
+  let output = '';
+  let bytes = 0;
+  for (const point of value) {
+    const size = Buffer.byteLength(point);
+    if (bytes + size > maxBytes) break;
+    output += point;
+    bytes += size;
+  }
+  return { value: output.trimEnd(), truncated: true };
+}
+
+function tagInfo(raw) {
+  const closing = /^<\s*\//u.test(raw);
+  const match = /^<\s*\/?\s*([a-z][a-z0-9:-]*)/iu.exec(raw);
+  if (!match) return null;
+  const name = match[1].toLowerCase();
+  return { name, closing, selfClosing: /\/\s*>$/u.test(raw), attributes: closing ? '' : raw.slice(match[0].length, -1) };
+}
+
+function hiddenElement(attributes) {
+  return /(?:^|\s)hidden(?:\s|=|$)/iu.test(attributes)
+    || /(?:^|\s)aria-hidden\s*=\s*(?:["']?true["']?)/iu.test(attributes)
+    || /(?:^|\s)type\s*=\s*(?:["']?hidden["']?)/iu.test(attributes)
+    || /(?:^|\s)style\s*=\s*(["'])[^"']*(?:display\s*:\s*none|visibility\s*:\s*hidden)[^"']*\1/iu.test(attributes);
+}
+
+function hrefFrom(attributes) {
+  const match = /(?:^|\s)href\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+))/iu.exec(attributes);
+  return decodeEntities(match ? (match[1] ?? match[2] ?? match[3] ?? '') : '').trim();
+}
+
+export function normalizeHtml(value, options = {}) {
+  const maxInputBytes = positiveLimit(options.maxInputBytes, DEFAULT_INPUT_BYTES);
+  const maxOutputBytes = positiveLimit(options.maxOutputBytes, DEFAULT_OUTPUT_BYTES);
+  const { mimeType, charset } = parseMediaType(options.contentType);
+  const input = Buffer.isBuffer(value) ? value : Buffer.from(String(value ?? ''), 'utf8');
+  const inputBytes = input.length;
+  if (inputBytes > maxInputBytes) throw new Error(`HTML input exceeds maximum size: ${inputBytes} bytes`);
+  if (charset === 'us-ascii' && input.some((byte) => byte > 0x7f)) throw new Error('HTML body contains bytes outside the declared US-ASCII charset.');
+  let html;
+  try { html = new TextDecoder('utf-8', { fatal: true }).decode(input); }
+  catch { throw new Error('HTML body is not valid UTF-8.'); }
+  const declaredCharsets = [...html.matchAll(/<meta\b[^>]*charset\s*=\s*["']?([^\s"'/>;]+)/giu)].map((match) => match[1].toLowerCase().replace('utf8', 'utf-8'));
+  for (const match of html.matchAll(/<meta\b(?=[^>]*http-equiv\s*=\s*["']?content-type["']?)[^>]*content\s*=\s*(?:"[^"]*charset\s*=\s*([^\s";]+)[^"]*"|'[^']*charset\s*=\s*([^\s';]+)[^']*'|[^>]*charset\s*=\s*([^\s;>]+))[^>]*>/giu)) {
+    declaredCharsets.push((match[1] || match[2] || match[3]).toLowerCase().replace('utf8', 'utf-8'));
+  }
+  if (declaredCharsets.some((declared) => !ACCEPTED_CHARSET.has(declared) || declared !== charset)) throw new Error('HTML document charset conflicts with the response charset.');
+  html = html.replace(/\0/gu, '\uFFFD').replace(/\r\n?/gu, '\n');
+  const lower = html.toLowerCase();
+  const output = [];
+  const headings = [];
+  const links = [];
+  const skip = [];
+  const anchors = [];
+  let title = null;
+  let titleStart = -1;
+  let preDepth = 0;
+  let malformed = false;
+  let cursor = 0;
+
+  const append = (text) => { if (!skip.length && text) output.push(text); };
+  while (cursor < html.length) {
+    const open = html.indexOf('<', cursor);
+    if (open < 0) {
+      append(decodeEntities(html.slice(cursor)));
+      break;
+    }
+    append(decodeEntities(html.slice(cursor, open)));
+    if (lower.startsWith('<!--', open)) {
+      const end = lower.indexOf('-->', open + 4);
+      if (end < 0) { malformed = true; break; }
+      cursor = end + 3;
+      continue;
+    }
+    const close = html.indexOf('>', open + 1);
+    if (close < 0) { malformed = true; break; }
+    const raw = html.slice(open, close + 1);
+    if (/^<!|^<\?/u.test(raw)) { cursor = close + 1; continue; }
+    const tag = tagInfo(raw);
+    if (!tag) { malformed = true; cursor = close + 1; continue; }
+
+    if (skip.length) {
+      if (!tag.closing && !tag.selfClosing && tag.name === skip.at(-1)) skip.push(tag.name);
+      else if (tag.closing && tag.name === skip.at(-1)) skip.pop();
+      cursor = close + 1;
+      continue;
+    }
+    if (!tag.closing && (DROP_CONTENT.has(tag.name) || hiddenElement(tag.attributes))) {
+      if (!tag.selfClosing) skip.push(tag.name);
+      cursor = close + 1;
+      continue;
+    }
+    if (tag.name === 'title') {
+      if (!tag.closing) titleStart = output.length;
+      else if (titleStart >= 0) {
+        title = normalizeWhitespace(output.splice(titleStart).join('')) || null;
+        titleStart = -1;
+      }
+    } else if (/^h[1-6]$/u.test(tag.name)) {
+      if (!tag.closing) {
+        append(`\n${'#'.repeat(Number(tag.name[1]))} `);
+        headings.push(tag.name);
+      } else if (headings.at(-1) === tag.name) {
+        headings.pop();
+        append('\n');
+      }
+    } else if (tag.name === 'li') append(tag.closing ? '\n' : '\n- ');
+    else if (tag.name === 'pre') {
+      if (tag.closing) { preDepth = Math.max(0, preDepth - 1); append('\n```\n'); }
+      else { append('\n```\n'); preDepth += 1; }
+    } else if (tag.name === 'code' && !tag.closing) append(preDepth ? '' : '`');
+    else if (tag.name === 'code' && tag.closing) append(preDepth ? '' : '`');
+    else if (tag.name === 'a') {
+      if (!tag.closing) anchors.push({ start: output.length, href: hrefFrom(tag.attributes) });
+      else {
+        const anchor = anchors.pop();
+        if (anchor) {
+          const text = normalizeWhitespace(output.slice(anchor.start).join(''));
+          if (text && anchor.href && links.length < MAX_LINKS) {
+            const link = { text: boundedUtf8(text, 500).value, href: boundedUtf8(anchor.href, 2048).value };
+            if (Buffer.byteLength(JSON.stringify([...links, link])) <= MAX_LINK_METADATA_BYTES) links.push(link);
+          }
+        }
+      }
+    } else if (tag.name === 'td' || tag.name === 'th') append(tag.closing ? ' | ' : '| ');
+    else if (BLOCK_TAGS.has(tag.name)) append(tag.name === 'br' || tag.closing ? '\n' : '\n');
+    cursor = close + 1;
+  }
+  if (skip.length || titleStart >= 0 || anchors.length || headings.length) malformed = true;
+  const normalized = normalizeWhitespace(output.join(''));
+  const bounded = boundedUtf8(normalized, maxOutputBytes);
+  return {
+    text: bounded.value,
+    title,
+    links,
+    extractor: EXTRACTOR,
+    fallbackReason: malformed ? 'malformed-html' : null,
+    mimeType,
+    charset,
+    inputBytes,
+    outputBytes: Buffer.byteLength(bounded.value),
+    truncated: bounded.truncated,
+  };
+}

package/src/index.d.ts

@@ -1,20 +1,54 @@
+export type ContextScope = 'transient' | 'session' | 'project';
+export type DirectoryReason = 'excluded-path' | 'extension-filter' | 'file-byte-limit' | 'file-count-limit' | 'aggregate-byte-limit' | 'visited-entry-limit' | 'depth-limit' | 'file-symlink' | 'directory-symlink' | 'symlink-outside-root' | 'symlink-unresolvable' | 'special-file' | 'directory-read-failed' | 'entry-stat-failed' | 'index-failed';
+export interface EnvironmentPolicy { mode: 'inherit-filtered-v1' | 'allowlist-v1'; platform: 'win32' | 'darwin' | 'posix'; allowedNames?: string[]; filteredNames: string[] }
+export interface DirectoryManifestEntry { path: string; absolutePath: string; size: number; identity: { dev: number; ino: number; size: number; mtimeMs: number }; symlink: boolean }
+export interface DirectoryManifest { root: string; directory: string; files: DirectoryManifestEntry[]; skipped: Array<{ path: string; reason: DirectoryReason }>; failed: Array<{ path: string; reason: DirectoryReason; error?: string }>; aborted: boolean; truncated: boolean; visitedEntries: number; aggregateBytes: number }
+export interface HtmlNormalization { text: string; title: string | null; links: Array<{ text: string; href: string }>; extractor: 'html-v1'; fallbackReason: 'malformed-html' | null; mimeType: 'text/html' | 'application/xhtml+xml'; charset: 'utf-8' | 'us-ascii'; inputBytes: number; outputBytes: number; truncated: boolean }
+export interface ExecutionInput { label?: string; command?: string; executable?: string; args?: string[]; shell?: boolean; cwd?: string; timeoutMs?: number; outputLimit?: number; directLimit?: number; outputMode?: 'auto' | 'direct' | 'indexed' | 'discard'; scope?: ContextScope; ttlMs?: number; env?: Record<string, string | null>; environmentMode?: 'inherit-filtered-v1' | 'allowlist-v1'; allowedEnv?: string[] }
+export interface IndexInput { path: string; root?: string; source?: string; scope?: ContextScope; ttlMs?: number; maxBytes?: number; includeExtensions?: string[]; excludePaths?: string[]; followFileSymlinks?: boolean; maxDepth?: number; maxVisitedEntries?: number; maxFiles?: number; maxAggregateBytes?: number }
+export interface FetchInput { url: string; source?: string; scope?: ContextScope; ttlMs?: number; timeoutMs?: number; maxBytes?: number; browser?: boolean }
+export interface IndexResult { id: string; chunks: number; bytes: number; scope: ContextScope; expiresAt: number | null }
+export interface FetchResult extends IndexResult {}
+export interface IngestionJob { id: string; state: 'queued' | 'running' | 'completed' | 'failed' | 'cancelled'; kind: 'index' | 'fetch'; input: Record<string, unknown>; sessionId: string | null; result: unknown; error: string | null; createdAt: number; updatedAt: number }
+export interface DoctorResult { ok: boolean; status: 'OK' | 'WARN' | 'FAIL'; node: string; platform: string; root: string; dbPath: string; checks: Array<{ id: string; status: 'OK' | 'WARN' | 'FAIL'; message: string; details?: unknown }> }
+
 export function contextDbPath(root?: string): string;
 export class ContextStore {
   constructor(root?: string);
   root: string;
   path: string;
   close(): void;
-  index(input: Record<string, unknown>): Record<string, unknown>;
-  search(input: Record<string, unknown>): unknown[];
-  stats(): Record<string, unknown>;
-  purge(input: Record<string, unknown>): Record<string, unknown>;
+  index(input: { id?: string; scope?: ContextScope; sessionId?: string | null; label?: string; kind?: string; text: string; metadata?: Record<string, unknown>; ttlMs?: number | null; provenance?: Record<string, unknown> }): Record<string, unknown>;
+  search(input: { query: string; scope?: ContextScope; sessionId?: string; source?: string; limit?: number }): unknown[];
+  stats(): { path: string; sources: number; chunks: number; byScope: Array<{ scope: ContextScope; count: number }> };
+  purge(input: { scope?: ContextScope; sessionId?: string; sourceId?: string }): { removed: number };
+  createJob(input: { id?: string; kind: 'index' | 'fetch'; input: Record<string, unknown>; sessionId?: string | null }): IngestionJob;
+  getJob(id: string): IngestionJob | null;
+  claimNextJob(): IngestionJob | null;
+  finishJob(id: string, state: 'completed' | 'failed' | 'cancelled', value?: unknown): IngestionJob | null;
+  cancelJob(id: string): { changed: number; job: IngestionJob | null };
+  listPendingJobs(limit?: number): IngestionJob[];
 }
-export function executeCommand(input: Record<string, any>, options?: Record<string, any>): Promise<Record<string, any>>;
-export function executeBatch(input: Record<string, any>, options?: Record<string, any>): Promise<Record<string, any>>;
-export function executeFile(input: Record<string, any>, options?: Record<string, any>): Promise<Record<string, any>>;
-export function indexFile(store: ContextStore, input: Record<string, any>, sessionId?: string): Record<string, any>;
-export function fetchAndIndex(store: ContextStore, input: Record<string, any>, sessionId?: string, signal?: AbortSignal): Promise<Record<string, any>>;
-export function runDoctor(input?: Record<string, any>): Record<string, any>;
+export function healContextDatabase(root?: string): { ok: true; backupPath: string; fromVersion: number; toVersion: number; rebuilt: true };
+export function validateSessionId(value: unknown): string;
+export function resolveSessionId(value?: unknown): string;
+export class IngestionJobRunner { sessionId?: string; constructor(store: ContextStore, options?: { sessionId?: string; renderer?: BrowserRenderer; root?: string }); enqueue(kind: 'index' | 'fetch', input: Record<string, unknown>): IngestionJob; status(id: string): IngestionJob | null; cancel(id: string): { changed: number; job: IngestionJob | null }; pump(): Promise<void> }
+export interface BrowserRendererResult { body?: Buffer; text?: string; url?: string; contentType?: string; status?: number }
+export type BrowserRenderer = (input: Readonly<{ url: string; signal: AbortSignal; timeoutMs: number; maxBytes: number }>) => Promise<BrowserRendererResult>;
+export const INGESTION_JOB_LIMITS: Readonly<{ maxPendingJobs: number; concurrency: 1 }>;
+export const PHASE3_TOOL_INPUT_SCHEMAS: Readonly<Record<'session_resume' | 'ingestion_job_start' | 'ingestion_job_status' | 'ingestion_job_cancel' | 'context_heal', Readonly<Record<string, unknown>>>>;
+export function executeCommand(input: ExecutionInput, options?: { root?: string; store?: ContextStore; sessionId?: string; signal?: AbortSignal | undefined; env?: Record<string, string | undefined>; captureLimitBytes?: number }): Promise<Record<string, any>>;
+export function executeBatch(input: { commands: ExecutionInput[]; concurrency?: number; cwd?: string; timeoutMs?: number }, options?: Record<string, any>): Promise<Record<string, any>>;
+export function executeFile(input: ExecutionInput & { path: string; language: 'javascript' | 'python' | 'shell'; code: string }, options?: Record<string, any>): Promise<Record<string, any>>;
+export function indexFile(store: ContextStore, input: IndexInput, sessionId?: string, signal?: AbortSignal): IndexResult | (Record<string, unknown> & { indexed: IndexResult[] });
+export function fetchAndIndex(store: ContextStore, input: FetchInput, sessionId?: string, signal?: AbortSignal, capabilities?: { renderer?: BrowserRenderer }): Promise<FetchResult>;
+export function composeEnvironment(input?: { inherited?: Record<string, string | undefined>; overrides?: Record<string, string | null>; platform?: string; mode?: 'inherit-filtered-v1' | 'allowlist-v1'; allow?: string[] }): { env: Record<string, string>; policy: EnvironmentPolicy };
+export const DIRECTORY_INGESTION_LIMITS: Readonly<{ maxDepth: number; maxVisitedEntries: number; maxFiles: number; maxFileBytes: number; maxAggregateBytes: number }>;
+export function walkDirectoryManifest(input: IndexInput & { signal?: AbortSignal }): DirectoryManifest;
+export function verifyManifestFile(entry: DirectoryManifestEntry, root: string): string;
+export function readManifestFile(entry: DirectoryManifestEntry, root: string, maxBytes?: number): Buffer;
+export function normalizeHtml(value: unknown, options?: { contentType?: string; maxInputBytes?: number; maxOutputBytes?: number }): HtmlNormalization;
+export function runDoctor(input?: { root?: string; dbPath?: string; stats?: Record<string, unknown>; fetchPolicy?: { mode?: string; encodings?: string[] } }): DoctorResult;
 export function projectLoad(input: Record<string, any>): Promise<Record<string, any>>;
 export function projectImpact(input: Record<string, any>): Promise<Record<string, any>>;
 export function projectInitialize(input: Record<string, any>): Promise<Record<string, any>>;

package/src/index.mjs

@@ -1,7 +1,13 @@
 export { chunkContent, chunkJson, chunkMarkdown, chunkText, excerpt, normalizeText } from './chunks.mjs';
-export { ContextStore, contextDbPath } from './store.mjs';
+export { ContextStore, contextDbPath, healContextDatabase } from './store.mjs';
 export { executeBatch, executeCommand, executeFile } from './execute.mjs';
 export { fetchAndIndex, indexFile } from './content.mjs';
+export { composeEnvironment } from './environment-policy.mjs';
+export { INGESTION_JOB_LIMITS, IngestionJobRunner } from './jobs.mjs';
+export { resolveSessionId, validateSessionId } from './session.mjs';
+export { PHASE3_TOOL_INPUT_SCHEMAS } from './tool-contracts.mjs';
+export { DIRECTORY_INGESTION_LIMITS, readManifestFile, verifyManifestFile, walkDirectoryManifest } from './directory-ingestion.mjs';
+export { normalizeHtml } from './html-normalize.mjs';
 export { runDoctor } from './doctor.mjs';
 export { createProvenanceMetadata, readProvenanceMetadata, sha256Content } from './provenance.mjs';
 export { normalizeSearchTerms, reciprocalRankFusion, rerankCandidates } from './rank.mjs';

package/src/jobs.mjs

@@ -0,0 +1,62 @@
+import { fetchAndIndex, indexFile } from './content.mjs';
+
+const MAX_PENDING_JOBS = 100;
+
+export class IngestionJobRunner {
+  constructor(store, { sessionId, renderer, root } = {}) {
+    this.store = store;
+    this.sessionId = sessionId;
+    this.root = root ?? store.root;
+    this.renderer = renderer;
+    this.running = false;
+    this.scheduled = false;
+    this.controllers = new Map();
+    this.schedule();
+  }
+
+  enqueue(kind, input) {
+    if (!['index', 'fetch'].includes(kind)) throw new Error('Unsupported ingestion job kind.');
+    const job = this.store.createJob({ kind, input, sessionId: this.sessionId ?? null });
+    this.schedule();
+    return job;
+  }
+
+  status(id) { return this.store.getJob(id); }
+
+  cancel(id) {
+    this.controllers.get(id)?.abort();
+    return this.store.cancelJob(id);
+  }
+
+  schedule() {
+    if (this.scheduled || this.running) return;
+    this.scheduled = true;
+    queueMicrotask(() => { this.scheduled = false; void this.pump(); });
+  }
+
+  async pump() {
+    if (this.running) return;
+    this.running = true;
+    try {
+      for (;;) {
+        const job = this.store.claimNextJob();
+        if (!job) break;
+        const controller = new AbortController();
+        this.controllers.set(job.id, controller);
+        try {
+          const value = job.kind === 'index'
+            ? indexFile(this.store, { ...job.input, root: this.root }, job.sessionId ?? undefined, controller.signal)
+            : await fetchAndIndex(this.store, job.input, job.sessionId ?? undefined, controller.signal, { renderer: this.renderer });
+          const current = this.store.getJob(job.id);
+          if (current?.state === 'running') this.store.finishJob(job.id, 'completed', value);
+        } catch (error) {
+          const current = this.store.getJob(job.id);
+          if (current?.state === 'running') this.store.finishJob(job.id, controller.signal.aborted ? 'cancelled' : 'failed', error instanceof Error ? error.message : String(error));
+        } finally { this.controllers.delete(job.id); }
+        await new Promise((resolve) => setImmediate(resolve));
+      }
+    } finally { this.running = false; }
+  }
+}
+
+export const INGESTION_JOB_LIMITS = Object.freeze({ maxPendingJobs: MAX_PENDING_JOBS, concurrency: 1 });

package/src/provenance.mjs

@@ -11,7 +11,7 @@ const TRUST_BY_SOURCE_TYPE = Object.freeze({
   unknown: 'unknown',
 });
 
-const EXTRACTORS = new Set(['plain', 'markdown-v1', 'json-v1']);
+const EXTRACTORS = new Set(['plain', 'markdown-v1', 'json-v1', 'html-v1']);
 const HASH_PATTERN = /^[a-f0-9]{64}$/u;
 
 function asMetadata(value) {

package/src/server.mjs

@@ -1,21 +1,26 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
-import { ContextStore, contextDbPath } from './store.mjs';
+import { ContextStore, contextDbPath, healContextDatabase } from './store.mjs';
 import { executeBatch, executeCommand, executeFile } from './execute.mjs';
 import { fetchAndIndex, indexFile } from './content.mjs';
 import { runDoctor } from './doctor.mjs';
 import { projectImpact, projectInitialize, projectLoad } from './project.mjs';
 import { resolveWithinRoot } from './paths.mjs';
+import { IngestionJobRunner } from './jobs.mjs';
+import { resolveSessionId, validateSessionId } from './session.mjs';
+import { PHASE3_TOOL_INPUT_SCHEMAS } from './tool-contracts.mjs';
 
 const root = process.env.DOTDOTGOD_PROJECT_ROOT || process.cwd();
-const sessionId = process.env.DOTDOTGOD_SESSION_ID || crypto.randomUUID();
+let sessionId = resolveSessionId(process.env.DOTDOTGOD_SESSION_ID);
 let contextStore;
+let jobRunner;
 function getStore() {
   contextStore ??= new ContextStore(root);
   return contextStore;
 }
-const server = new McpServer({ name: 'dotdotgod-context', version: '0.2.25' });
+function getJobs() { jobRunner ??= new IngestionJobRunner(getStore(), { sessionId }); return jobRunner; }
+const server = new McpServer({ name: 'dotdotgod-context', version: '0.2.27' });
 
 const scopeSchema = z.enum(['transient', 'session', 'project']).optional();
 const outputModeSchema = z.enum(['auto', 'direct', 'indexed', 'discard']).optional();
@@ -23,6 +28,7 @@ const commandSchema = {
   label: z.string().optional(), command: z.string().optional(), executable: z.string().optional(), args: z.array(z.string()).optional(),
   shell: z.boolean().optional(), cwd: z.string().optional(), timeoutMs: z.number().int().positive().optional(), outputLimit: z.number().int().positive().optional(),
   directLimit: z.number().int().positive().optional(), outputMode: outputModeSchema, scope: scopeSchema, ttlMs: z.number().int().nonnegative().optional(),
+  env: z.record(z.string(), z.string().nullable()).optional(), environmentMode: z.enum(['inherit-filtered-v1', 'allowlist-v1']).optional(), allowedEnv: z.array(z.string()).max(100).optional(),
 };
 
 function success(value) {
@@ -49,9 +55,11 @@ register('batch_execute', 'Run labeled local commands sequentially or with bound
 register('execute_file', 'Process a local file in an isolated child process; only bounded stdout/stderr is returned.', {
   path: z.string(), language: z.enum(['javascript', 'python', 'shell']).default('javascript'), code: z.string(), ...commandSchema,
 }, (input, extra) => executeFile(input, { root, store: getStore(), sessionId, signal: extra.signal }), { openWorldHint: false, destructiveHint: true });
-register('index', 'Index a local text file into the project-local FTS5 store without returning its raw bytes.', {
+register('index', 'Index a local text file or bounded directory into the project-local FTS5 store without returning raw bytes.', {
   path: z.string(), root: z.string().optional(), source: z.string().optional(), scope: scopeSchema, ttlMs: z.number().int().nonnegative().optional(), maxBytes: z.number().int().positive().optional(),
-}, (input) => ({ ok: true, ...indexFile(getStore(), { ...input, root }, sessionId) }), { readOnlyHint: true });
+  includeExtensions: z.array(z.string()).max(100).optional(), excludePaths: z.array(z.string()).max(500).optional(), followFileSymlinks: z.boolean().optional(),
+  maxDepth: z.number().int().nonnegative().optional(), maxVisitedEntries: z.number().int().nonnegative().optional(), maxFiles: z.number().int().nonnegative().optional(), maxAggregateBytes: z.number().int().nonnegative().optional(),
+}, (input, extra) => ({ ok: true, ...indexFile(getStore(), { ...input, root }, sessionId, extra.signal) }), { readOnlyHint: true });
 register('search', 'Search indexed command, file, and fetched content and return bounded excerpts.', {
   query: z.string().min(1), scope: scopeSchema, source: z.string().optional(), limit: z.number().int().min(1).max(50).optional(), sessionOnly: z.boolean().optional(),
 }, (input) => ({
@@ -60,8 +68,32 @@ register('search', 'Search indexed command, file, and fetched content and return
   results: getStore().search({ ...input, sessionId: input.sessionOnly ? sessionId : undefined }),
 }), { readOnlyHint: true });
 register('fetch_and_index', 'Fetch an HTTP(S) URL locally, index bounded text, and return metadata only.', {
-  url: z.string().url(), source: z.string().optional(), scope: scopeSchema, ttlMs: z.number().int().nonnegative().optional(), timeoutMs: z.number().int().positive().optional(), maxBytes: z.number().int().positive().optional(),
+  url: z.string().url(), source: z.string().optional(), scope: scopeSchema, ttlMs: z.number().int().nonnegative().optional(), timeoutMs: z.number().int().positive().optional(), maxBytes: z.number().int().positive().optional(), browser: z.boolean().optional(),
 }, (input, extra) => fetchAndIndex(getStore(), input, sessionId, extra.signal).then((value) => ({ ok: true, ...value })), { openWorldHint: true, readOnlyHint: true });
+function zodFromContract(schema) {
+  if (schema.const !== undefined) return z.literal(schema.const);
+  if (schema.enum) return z.enum(schema.enum);
+  if (schema.type === 'string') {
+    let value = z.string();
+    if (schema.minLength !== undefined) value = value.min(schema.minLength);
+    if (schema.maxLength !== undefined) value = value.max(schema.maxLength);
+    if (schema.pattern) value = value.regex(new RegExp(schema.pattern, 'u'));
+    if (schema.format === 'uuid') value = value.uuid();
+    return value;
+  }
+  if (schema.type === 'object') {
+    if (!schema.properties) return z.record(z.string(), z.unknown());
+    const required = new Set(schema.required ?? []);
+    return z.object(Object.fromEntries(Object.entries(schema.properties).map(([key, value]) => [key, required.has(key) ? zodFromContract(value) : zodFromContract(value).optional()]))).strict();
+  }
+  throw new Error('Unsupported shared tool contract schema.');
+}
+const phase3Shape = (name) => zodFromContract(PHASE3_TOOL_INPUT_SCHEMAS[name]).shape;
+register('session_resume', 'Use an explicit opaque session ID for subsequent context operations; historical sessions are not listed.', phase3Shape('session_resume'), (input) => { sessionId = validateSessionId(input.sessionId); if (jobRunner) jobRunner.sessionId = sessionId; return { ok: true, sessionId }; });
+register('ingestion_job_start', 'Queue one durable bounded background index or strict-fetch ingestion job.', phase3Shape('ingestion_job_start'), (input) => ({ ok: true, job: getJobs().enqueue(input.kind, input.input) }));
+register('ingestion_job_status', 'Return bounded status for one background ingestion job.', phase3Shape('ingestion_job_status'), (input) => ({ ok: true, job: getJobs().status(input.id) }), { readOnlyHint: true });
+register('ingestion_job_cancel', 'Cancel one queued or running background ingestion job.', phase3Shape('ingestion_job_cancel'), (input) => ({ ok: true, ...getJobs().cancel(input.id) }), { destructiveHint: true });
+register('context_heal', 'Explicitly back up and migrate only a recognized recoverable context database.', phase3Shape('context_heal'), () => { contextStore?.close(); contextStore = undefined; jobRunner = undefined; return healContextDatabase(root); }, { destructiveHint: true });
 register('stats', 'Report local context store counts and location.', {}, () => ({ ok: true, sessionId, ...getStore().stats() }), { readOnlyHint: true });
 register('doctor', 'Run local read-only Node.js, SQLite FTS5, storage, schema, and fetch-policy checks without network or repair actions.', {}, () => ({ sessionId, ...runDoctor({ root, dbPath: contextDbPath(root) }) }), { readOnlyHint: true });
 register('purge', 'Permanently delete one explicit context scope, session, or source.', {

package/src/session.mjs

@@ -0,0 +1,12 @@
+const SESSION_ID = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,127}$/;
+
+export function validateSessionId(value) {
+  if (typeof value !== 'string' || !SESSION_ID.test(value)) {
+    throw new TypeError('sessionId must be an opaque 1-128 character identifier using letters, digits, dot, underscore, tilde, or hyphen.');
+  }
+  return value;
+}
+
+export function resolveSessionId(value) {
+  return value == null ? crypto.randomUUID() : validateSessionId(value);
+}