@inixiative/foundry-core 0.1.0

package/src/adapters/http-memory.ts

@@ -0,0 +1,141 @@
+import type { ContextSource } from "../context-layer";
+import type { HydrationAdapter, ContextRef } from "../hydrator";
+import type { Signal } from "../signal";
+
+/**
+ * HTTP/REST adapter.
+ *
+ * Talks to any API that returns text or JSON. Zero deps — uses fetch.
+ * Use this for:
+ * - Notion, Confluence, or any knowledge base API
+ * - Custom internal tools
+ * - MCP servers
+ * - Vector DB APIs (Qdrant, Pinecone, Weaviate)
+ * - Any external system with an HTTP interface
+ */
+export class HttpMemory {
+  readonly baseUrl: string;
+  private _headers: Record<string, string>;
+  private _timeout: number;
+
+  constructor(
+    baseUrl: string,
+    opts?: {
+      headers?: Record<string, string>;
+      timeout?: number;
+    }
+  ) {
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+    this._headers = opts?.headers ?? {};
+    this._timeout = opts?.timeout ?? 10_000;
+  }
+
+  /** GET a path and return the response body as text. */
+  async get(path: string, params?: Record<string, string>): Promise<string> {
+    const url = new URL(path, this.baseUrl);
+    if (params) {
+      for (const [k, v] of Object.entries(params)) {
+        url.searchParams.set(k, v);
+      }
+    }
+
+    const res = await fetch(url.toString(), {
+      headers: this._headers,
+      signal: AbortSignal.timeout(this._timeout),
+    });
+
+    if (!res.ok) {
+      throw new Error(`HTTP ${res.status}: ${res.statusText} (${url.pathname})`);
+    }
+
+    const ct = res.headers.get("content-type") ?? "";
+    if (ct.includes("application/json")) {
+      const json = await res.json();
+      return typeof json === "string" ? json : JSON.stringify(json, null, 2);
+    }
+
+    return res.text();
+  }
+
+  /** POST to a path with a JSON body. */
+  async post(path: string, body: unknown): Promise<string> {
+    const url = new URL(path, this.baseUrl);
+
+    const res = await fetch(url.toString(), {
+      method: "POST",
+      headers: { ...this._headers, "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(this._timeout),
+    });
+
+    if (!res.ok) {
+      throw new Error(`HTTP ${res.status}: ${res.statusText} (${url.pathname})`);
+    }
+
+    const ct = res.headers.get("content-type") ?? "";
+    if (ct.includes("application/json")) {
+      const json = await res.json();
+      return typeof json === "string" ? json : JSON.stringify(json, null, 2);
+    }
+
+    return res.text();
+  }
+
+  /**
+   * Create a ContextSource that fetches from a GET endpoint.
+   * The response body becomes the context content.
+   */
+  asSource(
+    id: string,
+    path: string,
+    params?: Record<string, string>
+  ): ContextSource {
+    const http = this;
+    return {
+      id,
+      async load() {
+        try {
+          return await http.get(path, params);
+        } catch (err) {
+          console.warn(`[HttpMemory] source load failed for "${id}":`, (err as Error).message);
+          return "";
+        }
+      },
+    };
+  }
+
+  /**
+   * Create a HydrationAdapter.
+   * Refs use paths as locators, fetched via GET.
+   */
+  asAdapter(system: string = "http"): HydrationAdapter {
+    const http = this;
+    return {
+      system,
+      async hydrate(ref: ContextRef): Promise<string> {
+        try {
+          const params = ref.meta as Record<string, string> | undefined;
+          return await http.get(ref.locator, params);
+        } catch (err) {
+          console.warn(`[HttpMemory] hydrate failed for "${ref.locator}":`, (err as Error).message);
+          return "";
+        }
+      },
+    };
+  }
+
+  /**
+   * Create a signal writer that POSTs signals to an endpoint.
+   * Use this to forward signals to an external system.
+   */
+  signalWriter(path: string = "/signals") {
+    const http = this;
+    return async (signal: Signal): Promise<void> => {
+      try {
+        await http.post(path, signal);
+      } catch (err) {
+        console.warn(`[HttpMemory] signal forwarding failed:`, (err as Error).message);
+      }
+    };
+  }
+}

package/src/adapters/index.ts

@@ -0,0 +1,4 @@
+export { FileMemory, inlineSource, fileSource, type MemoryEntry } from "./file-memory";
+export { SqliteMemory, type SqliteEntry } from "./sqlite-memory";
+export { HttpMemory } from "./http-memory";
+export { MarkdownDocs, claudemdSource } from "./markdown-docs";

package/src/adapters/markdown-docs.ts

@@ -0,0 +1,213 @@
+import { join, relative, basename, extname } from "node:path";
+import type { ContextSource } from "../context-layer";
+import type { HydrationAdapter, ContextRef } from "../hydrator";
+
+/**
+ * Markdown directory adapter.
+ *
+ * Reads a directory of .md files as context. Perfect for:
+ * - CLAUDE.md and project docs
+ * - Architecture decision records
+ * - Convention files
+ * - Any docs/ directory
+ *
+ * Zero external deps — just filesystem.
+ */
+export class MarkdownDocs {
+  readonly dir: string;
+  readonly glob: string;
+  private _cache: Map<string, { content: string; mtime: number }> = new Map();
+
+  /**
+   * @param dir — root directory to scan
+   * @param glob — file pattern (default: all .md files recursively)
+   */
+  constructor(dir: string, glob: string = "**/*.md") {
+    this.dir = dir;
+    this.glob = glob;
+  }
+
+  /** Scan and load all matching files. */
+  async load(): Promise<Map<string, string>> {
+    const results = new Map<string, string>();
+    const scanner = new Bun.Glob(this.glob).scan({ cwd: this.dir, absolute: false });
+
+    for await (const relPath of scanner) {
+      const absPath = join(this.dir, relPath);
+      const file = Bun.file(absPath);
+      const stat = await file.stat();
+      const cached = this._cache.get(relPath);
+
+      // Use cache if file hasn't changed
+      if (cached && cached.mtime === stat.mtimeMs) {
+        results.set(relPath, cached.content);
+      } else {
+        const content = await file.text();
+        this._cache.set(relPath, { content, mtime: stat.mtimeMs });
+        results.set(relPath, content);
+      }
+    }
+
+    return results;
+  }
+
+  /** Read a single file by relative path. */
+  async readFile(relPath: string): Promise<string> {
+    const absPath = join(this.dir, relPath);
+    const file = Bun.file(absPath);
+    if (!(await file.exists())) return "";
+    return file.text();
+  }
+
+  /** List all matching files. */
+  async list(): Promise<string[]> {
+    const paths: string[] = [];
+    const scanner = new Bun.Glob(this.glob).scan({ cwd: this.dir, absolute: false });
+    for await (const relPath of scanner) {
+      paths.push(relPath);
+    }
+    return paths;
+  }
+
+  /**
+   * Create a ContextSource that loads all docs as one string.
+   * Each file is prefixed with its path as a header.
+   */
+  asSource(id: string): ContextSource {
+    const docs = this;
+    return {
+      id,
+      async load() {
+        const files = await docs.load();
+        if (files.size === 0) return "";
+
+        const parts: string[] = [];
+        for (const [path, content] of files) {
+          parts.push(`## ${path}\n\n${content}`);
+        }
+        return parts.join("\n\n---\n\n");
+      },
+    };
+  }
+
+  /**
+   * Create a ContextSource for a single file.
+   */
+  fileSource(id: string, relPath: string): ContextSource {
+    const docs = this;
+    return {
+      id,
+      async load() {
+        return docs.readFile(relPath);
+      },
+    };
+  }
+
+  /**
+   * Create a ContextSource that emits a compact topology of the corpus —
+   * one line per file with its H1 title and H2 headings. No full content.
+   *
+   * This is the docs-warden warm-cache substrate for corpora too large to
+   * hold inline (400KB+). The warden's advise LLM sees this ~50-tokens-per-file
+   * index and picks file paths; the orchestrator hydrates selected files
+   * on demand via HydrationAdapter.
+   *
+   * Output format (stable, deterministic — safe to diff across warm cycles):
+   *
+   *   docs/claude/API_ROUTES.md — API Routes
+   *     H2: Overview, Naming, Validation, Error shapes
+   *
+   *   docs/claude/AUTH.md — Authentication
+   *     H2: Session model, Token storage, Refresh flow
+   *
+   * Files with no H1 fall back to the file basename. Files with no H2s omit
+   * the headings line entirely. Empty files are skipped.
+   */
+  topologySource(id: string, opts: { maxHeadings?: number } = {}): ContextSource {
+    const docs = this;
+    const maxHeadings = opts.maxHeadings ?? 12;
+    return {
+      id,
+      async load() {
+        const files = await docs.load();
+        if (files.size === 0) return "";
+
+        const lines: string[] = [];
+        const paths = [...files.keys()].sort();
+
+        for (const path of paths) {
+          const content = files.get(path) ?? "";
+          if (!content.trim()) continue;
+
+          const { title, headings } = extractHeadings(content, maxHeadings);
+          const displayTitle = title ?? basename(path, extname(path));
+          lines.push(`${path} — ${displayTitle}`);
+          if (headings.length > 0) {
+            lines.push(`  H2: ${headings.join(", ")}`);
+          }
+          lines.push("");
+        }
+
+        return lines.join("\n").trimEnd();
+      },
+    };
+  }
+
+  /** Create a HydrationAdapter. Refs use relative paths as locators. */
+  asAdapter(): HydrationAdapter {
+    const docs = this;
+    return {
+      system: "markdown",
+      async hydrate(ref: ContextRef): Promise<string> {
+        return docs.readFile(ref.locator);
+      },
+      async hydrateBatch(refs: ContextRef[]): Promise<string[]> {
+        return Promise.all(refs.map((r) => docs.readFile(r.locator)));
+      },
+    };
+  }
+}
+
+/**
+ * Extract the first H1 and all H2 headings from markdown content.
+ * Returns `{ title: null, headings: [] }` if no structure is found.
+ */
+function extractHeadings(
+  content: string,
+  maxHeadings: number,
+): { title: string | null; headings: string[] } {
+  let title: string | null = null;
+  const headings: string[] = [];
+  const lines = content.split("\n");
+
+  for (const line of lines) {
+    if (title === null) {
+      const h1 = /^#\s+(.+?)\s*$/.exec(line);
+      if (h1) {
+        title = h1[1];
+        continue;
+      }
+    }
+    const h2 = /^##\s+(.+?)\s*$/.exec(line);
+    if (h2) {
+      headings.push(h2[1]);
+      if (headings.length >= maxHeadings) break;
+    }
+  }
+
+  return { title, headings };
+}
+
+/**
+ * Convenience: create a ContextSource from a single CLAUDE.md or similar file.
+ */
+export function claudemdSource(id: string, path: string): ContextSource {
+  return {
+    id,
+    async load() {
+      const file = Bun.file(path);
+      if (!(await file.exists())) return "";
+      return file.text();
+    },
+  };
+}

package/src/adapters/sqlite-memory.ts

@@ -0,0 +1,188 @@
+import { Database } from "bun:sqlite";
+import type { ContextSource } from "../context-layer";
+import type { HydrationAdapter, ContextRef } from "../hydrator";
+import type { Signal } from "../signal";
+
+/**
+ * SQLite-backed memory system.
+ *
+ * Zero external deps — uses bun:sqlite. Supports full-text search
+ * via SQLite FTS5. Good for local dev and single-machine deployments.
+ */
+export class SqliteMemory {
+  readonly db: Database;
+
+  constructor(path: string = ":memory:") {
+    this.db = new Database(path, { create: true });
+    this._init();
+  }
+
+  private _init() {
+    this.db.run(`
+      CREATE TABLE IF NOT EXISTS entries (
+        id TEXT PRIMARY KEY,
+        kind TEXT NOT NULL,
+        content TEXT NOT NULL,
+        source TEXT,
+        timestamp INTEGER NOT NULL,
+        meta TEXT
+      )
+    `);
+
+    // FTS5 for full-text search
+    this.db.run(`
+      CREATE VIRTUAL TABLE IF NOT EXISTS entries_fts
+      USING fts5(id, kind, content, content=entries, content_rowid=rowid)
+    `);
+
+    // Triggers to keep FTS in sync
+    this.db.run(`
+      CREATE TRIGGER IF NOT EXISTS entries_ai AFTER INSERT ON entries BEGIN
+        INSERT INTO entries_fts(rowid, id, kind, content) VALUES (NEW.rowid, NEW.id, NEW.kind, NEW.content);
+      END
+    `);
+    this.db.run(`
+      CREATE TRIGGER IF NOT EXISTS entries_ad AFTER DELETE ON entries BEGIN
+        INSERT INTO entries_fts(entries_fts, rowid, id, kind, content) VALUES ('delete', OLD.rowid, OLD.id, OLD.kind, OLD.content);
+      END
+    `);
+    this.db.run(`
+      CREATE TRIGGER IF NOT EXISTS entries_au AFTER UPDATE ON entries BEGIN
+        INSERT INTO entries_fts(entries_fts, rowid, id, kind, content) VALUES ('delete', OLD.rowid, OLD.id, OLD.kind, OLD.content);
+        INSERT INTO entries_fts(rowid, id, kind, content) VALUES (NEW.rowid, NEW.id, NEW.kind, NEW.content);
+      END
+    `);
+  }
+
+  /** Write an entry. Upserts. */
+  write(entry: SqliteEntry): void {
+    this.db.run(
+      `INSERT OR REPLACE INTO entries (id, kind, content, source, timestamp, meta) VALUES (?, ?, ?, ?, ?, ?)`,
+      [entry.id, entry.kind, entry.content, entry.source ?? null, entry.timestamp, entry.meta ? JSON.stringify(entry.meta) : null]
+    );
+  }
+
+  /** Read by id. */
+  get(id: string): SqliteEntry | undefined {
+    const row = this.db.query("SELECT * FROM entries WHERE id = ?").get(id) as any;
+    return row ? this._rowToEntry(row) : undefined;
+  }
+
+  /** Get all entries, optionally filtered by kind. */
+  all(kind?: string): SqliteEntry[] {
+    const query = kind
+      ? this.db.query("SELECT * FROM entries WHERE kind = ? ORDER BY timestamp DESC")
+      : this.db.query("SELECT * FROM entries ORDER BY timestamp DESC");
+    const rows = kind ? query.all(kind) : query.all();
+    return (rows as any[]).map(this._rowToEntry);
+  }
+
+  /** Full-text search. */
+  search(query: string, limit: number = 20): SqliteEntry[] {
+    const rows = this.db
+      .query(
+        `SELECT entries.* FROM entries_fts JOIN entries ON entries_fts.id = entries.id WHERE entries_fts MATCH ? ORDER BY rank LIMIT ?`
+      )
+      .all(query, limit);
+    return (rows as any[]).map(this._rowToEntry);
+  }
+
+  /** Delete by id. */
+  delete(id: string): boolean {
+    const result = this.db.run("DELETE FROM entries WHERE id = ?", [id]);
+    return result.changes > 0;
+  }
+
+  /** Count entries, optionally by kind. */
+  count(kind?: string): number {
+    const query = kind
+      ? this.db.query("SELECT COUNT(*) as c FROM entries WHERE kind = ?")
+      : this.db.query("SELECT COUNT(*) as c FROM entries");
+    const row = (kind ? query.get(kind) : query.get()) as any;
+    return row.c;
+  }
+
+  /** Recent entries. */
+  recent(limit: number = 50, kind?: string): SqliteEntry[] {
+    const query = kind
+      ? this.db.query("SELECT * FROM entries WHERE kind = ? ORDER BY timestamp DESC LIMIT ?")
+      : this.db.query("SELECT * FROM entries ORDER BY timestamp DESC LIMIT ?");
+    const rows = kind ? query.all(kind, limit) : query.all(limit);
+    return (rows as any[]).map(this._rowToEntry);
+  }
+
+  /** Create a ContextSource that loads entries as context. */
+  asSource(id: string, kind?: string, limit: number = 100): ContextSource {
+    const mem = this;
+    return {
+      id,
+      async load() {
+        const entries = mem.recent(limit, kind);
+        if (entries.length === 0) return "";
+        return entries
+          .map((e) => `[${e.kind}] ${e.id}: ${e.content}`)
+          .join("\n");
+      },
+    };
+  }
+
+  /** Create a HydrationAdapter. */
+  asAdapter(): HydrationAdapter {
+    const mem = this;
+    return {
+      system: "sqlite",
+      async hydrate(ref: ContextRef): Promise<string> {
+        const entry = mem.get(ref.locator);
+        return entry ? entry.content : "";
+      },
+      async hydrateBatch(refs: ContextRef[]): Promise<string[]> {
+        return refs.map((r) => {
+          const entry = mem.get(r.locator);
+          return entry ? entry.content : "";
+        });
+      },
+    };
+  }
+
+  /** Signal handler that writes signals to SQLite. */
+  signalWriter() {
+    const mem = this;
+    return async (signal: Signal): Promise<void> => {
+      mem.write({
+        id: signal.id,
+        kind: signal.kind,
+        content:
+          typeof signal.content === "string"
+            ? signal.content
+            : JSON.stringify(signal.content),
+        source: signal.source,
+        timestamp: signal.timestamp,
+        meta: { confidence: signal.confidence, refs: signal.refs },
+      });
+    };
+  }
+
+  close(): void {
+    this.db.close();
+  }
+
+  private _rowToEntry(row: any): SqliteEntry {
+    return {
+      id: row.id,
+      kind: row.kind,
+      content: row.content,
+      source: row.source ?? undefined,
+      timestamp: row.timestamp,
+      meta: row.meta ? JSON.parse(row.meta) : undefined,
+    };
+  }
+}
+
+export interface SqliteEntry {
+  readonly id: string;
+  readonly kind: string;
+  readonly content: string;
+  readonly source?: string;
+  readonly timestamp: number;
+  readonly meta?: Record<string, unknown>;
+}

package/src/base-agent.ts

@@ -0,0 +1,137 @@
+import type { TokenCounts } from "./token-counts";
+import { computeHash } from "./context-layer";
+import { ContextStack, type LayerFilter, type AssembledContext } from "./context-stack";
+
+export interface ExecutionResult<T = unknown> {
+  readonly output: T;
+  readonly tokens?: TokenCounts;
+  readonly contextHash: string;
+  readonly meta?: Record<string, unknown>;
+}
+
+/**
+ * Per-agent LLM configuration.
+ *
+ * Each agent can specify its own provider, model, and inference settings.
+ * This allows tuning each part of the composition independently:
+ * - Fast/cheap models for middleware (classify, route)
+ * - Powerful models for executors (code generation, planning)
+ */
+export interface AgentLLMConfig {
+  /** Provider ID — which LLM provider to use (e.g. "anthropic", "openai", "gemini"). */
+  readonly provider?: string;
+  /** Model override (e.g. "claude-haiku-4-5-20251001", "gpt-4o-mini"). */
+  readonly model?: string;
+  /** Temperature (0 = deterministic, 1 = creative). */
+  readonly temperature?: number;
+  /** Max tokens for response. */
+  readonly maxTokens?: number;
+  /** Data source IDs this agent can access (layer filter by source). */
+  readonly sources?: string[];
+  /** Maximum call-chain depth to prevent infinite agent delegation. */
+  readonly maxDepth?: number;
+}
+
+export interface AgentConfig {
+  readonly id: string;
+  stack: ContextStack;
+  layerFilter?: LayerFilter;
+  /** System prompt defining this agent's role. */
+  prompt?: string;
+  /** LLM configuration for this agent. */
+  llm?: AgentLLMConfig;
+  /** IDs of peer agents this agent knows about (for delegation). */
+  peers?: string[];
+}
+
+/**
+ * Base agent primitive.
+ *
+ * An agent has a context stack and receives payloads.
+ * Subclasses define what happens — Executors go do work,
+ * Deciders make decisions and return slim results.
+ *
+ * The agent doesn't own the stack — the Thread does.
+ * The agent gets a reference and a filter that scopes what it sees.
+ */
+export abstract class BaseAgent<TPayload = unknown, TResult = unknown> {
+  readonly id: string;
+  readonly prompt: string | undefined;
+  readonly llm: AgentLLMConfig | undefined;
+  readonly peers: string[];
+  protected _stack: ContextStack;
+  protected _layerFilter: LayerFilter | undefined;
+
+  constructor(config: AgentConfig) {
+    this.id = config.id;
+    this.prompt = config.prompt;
+    this.llm = config.llm;
+    this.peers = config.peers ?? [];
+    this._stack = config.stack;
+    this._layerFilter = config.layerFilter;
+  }
+
+  getContext(): string {
+    return this._layerFilter
+      ? this._stack.slice(this._layerFilter)
+      : this._stack.merge();
+  }
+
+  /**
+   * Assemble structured prompt blocks from agent prompt + layer prompts + content.
+   * Use this instead of getContext() when you want the full prompt-layer pairing.
+   */
+  assembleContext(filterOverride?: LayerFilter): AssembledContext {
+    const effective = filterOverride ?? this._layerFilter;
+    return this._stack.assemble(this.prompt, effective);
+  }
+
+  getContextHash(): string {
+    return computeHash(this.getContext());
+  }
+
+  /**
+   * Run this agent with a payload and optional per-dispatch layer filter override.
+   * If filterOverride is provided, it scopes context for this run only
+   * without mutating the agent's permanent filter.
+   * Meta carries runtime context (cwd, threadId) from the dispatching thread.
+   */
+  abstract run(
+    payload: TPayload,
+    filterOverride?: LayerFilter,
+    meta?: Record<string, unknown>
+  ): Promise<ExecutionResult<TResult>>;
+
+  /**
+   * Create an independent instance of this agent bound to another stack.
+   * Handler, prompt, LLM config, peers, and layer filter carry over; the
+   * original keeps its own stack. Used to give each thread its own agents.
+   */
+  abstract withStack(stack: ContextStack): BaseAgent<TPayload, TResult>;
+
+  /** Config needed to re-instantiate this agent on a different stack. */
+  protected agentConfig(stack: ContextStack): AgentConfig {
+    return {
+      id: this.id,
+      stack,
+      layerFilter: this._layerFilter,
+      prompt: this.prompt,
+      llm: this.llm,
+      peers: [...this.peers],
+    };
+  }
+
+  setLayerFilter(filter: LayerFilter): void {
+    this._layerFilter = filter;
+  }
+
+  setStack(stack: ContextStack): void {
+    this._stack = stack;
+  }
+
+  /** Get context with a temporary filter (doesn't mutate agent state). */
+  protected getContextWith(filter?: LayerFilter): string {
+    const effective = filter ?? this._layerFilter;
+    return effective ? this._stack.slice(effective) : this._stack.merge();
+  }
+}