@inixiative/foundry-core 0.1.0

package/src/hooks.ts

@@ -0,0 +1,133 @@
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type HookPoint =
+  | "pre:dispatch"
+  | "post:dispatch"
+  | "pre:classify"
+  | "post:classify"
+  | "pre:route"
+  | "post:route"
+  | "pre:compact"
+  | "post:compact"
+  | "session:create"
+  | "session:archive"
+  | "budget:warning"
+  | "budget:exceeded"
+  | "plan:enter"
+  | "plan:exit"
+  | "error:agent"
+  | "error:provider";
+
+export interface HookContext {
+  hookPoint: HookPoint;
+  threadId?: string;
+  agentId?: string;
+  payload?: unknown;
+  result?: unknown;
+  meta: Record<string, unknown>;
+  timestamp: number;
+}
+
+export interface HookResult {
+  action: "continue" | "skip" | "abort" | "redirect";
+  redirectTo?: string;
+  modified?: Partial<HookContext>;
+  annotations?: Record<string, unknown>;
+}
+
+export interface HookHandler {
+  id: string;
+  points: HookPoint[];
+  priority?: number;
+  handler: (ctx: HookContext) => Promise<HookResult>;
+}
+
+export interface PlanModeTrigger {
+  kind: "complexity" | "newDomain" | "largeDiff" | "custom";
+  threshold?: number;
+  detect?: (ctx: HookContext) => boolean;
+}
+
+export interface PlanModeConfig {
+  triggers: PlanModeTrigger[];
+  plannerAgentId: string;
+  requireApproval?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// HookRegistry — engine mechanism, no built-in behaviors
+// ---------------------------------------------------------------------------
+
+const DEFAULT_PRIORITY = 100;
+
+export class HookRegistry {
+  private _handlers: Map<string, HookHandler> = new Map();
+
+  register(handler: HookHandler): () => void {
+    this._handlers.set(handler.id, handler);
+    return () => { this._handlers.delete(handler.id); };
+  }
+
+  unregister(id: string): boolean {
+    return this._handlers.delete(id);
+  }
+
+  async execute(
+    point: HookPoint,
+    ctx: HookContext
+  ): Promise<HookContext & { action: HookResult["action"] }> {
+    const handlers = this.forPoint(point);
+    let current = { ...ctx };
+    let action: HookResult["action"] = "continue";
+
+    for (const handler of handlers) {
+      const result = await handler.handler(current);
+      action = result.action;
+
+      if (result.modified) {
+        current = {
+          ...current,
+          ...result.modified,
+          meta: { ...current.meta, ...result.modified.meta },
+        };
+      }
+
+      if (result.annotations) {
+        current.meta = { ...current.meta, ...result.annotations };
+      }
+
+      if (result.redirectTo) {
+        current.meta = { ...current.meta, redirectTo: result.redirectTo };
+      }
+
+      if (action === "abort" || action === "skip" || action === "redirect") {
+        break;
+      }
+    }
+
+    return { ...current, action };
+  }
+
+  forPoint(point: HookPoint): ReadonlyArray<HookHandler> {
+    const matching: HookHandler[] = [];
+    for (const handler of this._handlers.values()) {
+      if (handler.points.includes(point)) {
+        matching.push(handler);
+      }
+    }
+    matching.sort(
+      (a, b) => (a.priority ?? DEFAULT_PRIORITY) - (b.priority ?? DEFAULT_PRIORITY)
+    );
+    return matching;
+  }
+
+  get size(): number {
+    return this._handlers.size;
+  }
+
+  get handlers(): ReadonlyArray<HookHandler> {
+    return [...this._handlers.values()];
+  }
+}

package/src/hydrator.ts

@@ -0,0 +1,148 @@
+import type { ContextSource } from "./context-layer";
+
+/**
+ * A ref is a pointer into a knowledge system.
+ * It carries just enough to locate the content — not the content itself.
+ * Agents pass refs around, and adapters hydrate them on demand.
+ */
+export interface ContextRef {
+  /** Which system this ref points into (e.g. "docs", "memory", "corpus", "api") */
+  readonly system: string;
+
+  /** Location within that system (path, key, query, URI — system-specific) */
+  readonly locator: string;
+
+  /** Optional version/revision for pinning */
+  readonly version?: string;
+
+  /** Arbitrary system-specific metadata */
+  readonly meta?: Record<string, unknown>;
+}
+
+/**
+ * An adapter knows how to hydrate refs from a specific system.
+ * Each knowledge system (docs, memory, MuninnDB, etc.) implements one.
+ */
+export interface HydrationAdapter {
+  /** Which system this adapter handles — must match ContextRef.system */
+  readonly system: string;
+
+  /** Hydrate a single ref into content. */
+  hydrate(ref: ContextRef): Promise<string>;
+
+  /** Hydrate multiple refs (batch optimization). Default: serial hydrate. */
+  hydrateBatch?(refs: ContextRef[]): Promise<string[]>;
+}
+
+/**
+ * A ContextSource backed by refs + adapters.
+ * Drop this into a ContextLayer as a source — it hydrates on warm().
+ */
+export class RefSource implements ContextSource {
+  readonly id: string;
+  private _refs: ContextRef[];
+  private _registry: HydrationRegistry;
+
+  constructor(id: string, refs: ContextRef[], registry: HydrationRegistry) {
+    this.id = id;
+    this._refs = refs;
+    this._registry = registry;
+  }
+
+  async load(): Promise<string> {
+    return this._registry.hydrateAll(this._refs);
+  }
+
+  get refs(): ReadonlyArray<ContextRef> {
+    return this._refs;
+  }
+
+  addRef(ref: ContextRef): void {
+    this._refs.push(ref);
+  }
+
+  removeRef(locator: string): boolean {
+    const idx = this._refs.findIndex((r) => r.locator === locator);
+    if (idx === -1) return false;
+    this._refs.splice(idx, 1);
+    return true;
+  }
+}
+
+/**
+ * Registry of hydration adapters.
+ *
+ * You register one adapter per system. When refs come in,
+ * the registry routes each ref to the right adapter and hydrates.
+ * Refs from different systems in the same batch are hydrated
+ * in parallel (one batch per system).
+ */
+export class HydrationRegistry {
+  private _adapters: Map<string, HydrationAdapter> = new Map();
+
+  register(adapter: HydrationAdapter): void {
+    this._adapters.set(adapter.system, adapter);
+  }
+
+  unregister(system: string): boolean {
+    return this._adapters.delete(system);
+  }
+
+  getAdapter(system: string): HydrationAdapter | undefined {
+    return this._adapters.get(system);
+  }
+
+  /** Hydrate a single ref. */
+  async hydrate(ref: ContextRef): Promise<string> {
+    const adapter = this._adapters.get(ref.system);
+    if (!adapter) {
+      throw new Error(`No hydration adapter registered for system: ${ref.system}`);
+    }
+    return adapter.hydrate(ref);
+  }
+
+  /**
+   * Hydrate multiple refs, grouped by system for batch efficiency.
+   * Returns concatenated content in ref order.
+   */
+  async hydrateAll(refs: ContextRef[]): Promise<string> {
+    if (refs.length === 0) return "";
+
+    // Group by system
+    const bySystem = new Map<string, { idx: number; ref: ContextRef }[]>();
+    for (let i = 0; i < refs.length; i++) {
+      const ref = refs[i];
+      if (!bySystem.has(ref.system)) bySystem.set(ref.system, []);
+      bySystem.get(ref.system)!.push({ idx: i, ref });
+    }
+
+    // Hydrate each system's batch in parallel
+    const results: string[] = new Array(refs.length);
+
+    await Promise.all(
+      [...bySystem.entries()].map(async ([system, entries]) => {
+        const adapter = this._adapters.get(system);
+        if (!adapter) {
+          throw new Error(`No hydration adapter registered for system: ${system}`);
+        }
+
+        if (adapter.hydrateBatch && entries.length > 1) {
+          const batchResults = await adapter.hydrateBatch(
+            entries.map((e) => e.ref)
+          );
+          for (let i = 0; i < entries.length; i++) {
+            results[entries[i].idx] = batchResults[i];
+          }
+        } else {
+          await Promise.all(
+            entries.map(async (entry) => {
+              results[entry.idx] = await adapter.hydrate(entry.ref);
+            })
+          );
+        }
+      })
+    );
+
+    return results.join("\n\n");
+  }
+}

package/src/id.ts

@@ -0,0 +1,39 @@
+import { uuidv7 } from "uuidv7";
+
+/**
+ * Mint a new UUID v7 identifier, optionally prefixed.
+ *
+ * UUID v7 encodes a millisecond Unix timestamp in its first 48 bits, so IDs are
+ * lexicographically sortable by creation time. That's why the system stores no
+ * `created_at` columns — the ID itself carries the timestamp.
+ *
+ * Prefixes are cosmetic (for log readability). Sort order is preserved because
+ * the prefix is constant within a given table.
+ */
+export function newId(prefix?: string): string {
+  const id = uuidv7();
+  return prefix ? `${prefix}_${id}` : id;
+}
+
+/**
+ * Synthesize a UUID v7 at the given point in time, for range queries.
+ *
+ * Used to translate `createdAt < cutoff` into `id < idAtTime(prefix, cutoff)`
+ * when cleaning up stale rows by age.
+ */
+export function idAtTime(prefix: string | undefined, date: Date): string {
+  const ms = date.getTime();
+  if (ms < 0 || ms > 0xffffffffffff) {
+    throw new RangeError(`timestamp ${ms} out of UUID v7 range`);
+  }
+  const hex = ms.toString(16).padStart(12, "0");
+  const uuid = `${hex.slice(0, 8)}-${hex.slice(8, 12)}-7000-8000-000000000000`;
+  return prefix ? `${prefix}_${uuid}` : uuid;
+}
+
+/** Extract the millisecond timestamp encoded in a UUID v7 id (with or without prefix). */
+export function timeFromId(id: string): number {
+  const uuid = id.includes("_") ? id.slice(id.lastIndexOf("_") + 1) : id;
+  const hex = uuid.slice(0, 8) + uuid.slice(9, 13);
+  return parseInt(hex, 16);
+}

package/src/index.ts

@@ -0,0 +1,273 @@
+// ---------------------------------------------------------------------------
+// @inixiative/foundry-core — the engine
+// ---------------------------------------------------------------------------
+
+// Shared types
+export type {
+  InvocationCondition,
+  AgentModeConfig,
+  LayerModeConfig,
+  LLMMessage,
+  CompletionOpts,
+  CompletionResult,
+  ToolDefinition,
+  ToolCall,
+  ToolCallResult,
+  EmbeddingResult,
+  LLMStreamEvent,
+  LLMProvider,
+  EmbeddingProvider,
+} from "./types";
+
+// Ownership scope — which thread/project owns a source read or tool call
+export { normalizeScope, type OwnershipScope } from "./scope";
+
+// Message utilities
+export {
+  assembledToMessages,
+  buildInjectionArtifact,
+  splitSystemMessage,
+  type BuildInjectionArtifactOpts,
+  type InjectionArtifact,
+  type InjectionBlock,
+  type InjectionSegmentKind,
+  type MessageDecoration,
+  type DecorationParticipant,
+  type ParticipantRequest,
+  type DeliveryRecord,
+} from "./messages";
+
+// Context primitives
+export {
+  ContextLayer,
+  computeHash,
+  copyMessageIdentity,
+  type LogicalMessageIdentity,
+  type ContextSource,
+  type ContextLayerConfig,
+  type LayerDefinition,
+  type LayerInstanceState,
+  type LayerVersionMark,
+  type LayerSegment,
+  LAYER_SEGMENTS,
+  isLayerSegment,
+  type LayerMutationEvent,
+  type LayerSelectionState,
+  type LayerState,
+  type SourceLoadHint,
+  type SourceSelectionReport,
+  type VersionEntry,
+  type VersionLog,
+} from "./context-layer";
+
+export {
+  ContextStack,
+  type LayerFilter,
+  type ContextSnapshot,
+  type ContextStackView,
+  type PromptBlock,
+  type AssembledContext,
+} from "./context-stack";
+
+export {
+  CacheLifecycle,
+  type LifecycleEvent,
+  type LifecycleHandler,
+  type LifecycleRule,
+} from "./cache-lifecycle";
+
+export {
+  HydrationRegistry,
+  RefSource,
+  type ContextRef,
+  type HydrationAdapter,
+} from "./hydrator";
+
+// Agent primitives
+export {
+  BaseAgent,
+  type ExecutionResult,
+  type AgentConfig,
+  type AgentLLMConfig,
+} from "./base-agent";
+
+export { Executor, type ExecuteHandler, type ExecuteMeta, type ExecutorConfig } from "./executor";
+export { Decider, type Decision, type DecideHandler, type DeciderConfig } from "./decider";
+export { Classifier, type Classification, type ClassifyHandler, type ClassifierConfig } from "./classifier";
+export { Router, type Route, type RouteHandler, type RouterConfig } from "./router";
+
+// Middleware
+export {
+  MiddlewareChain,
+  type Middleware,
+  type MiddlewareTier,
+  type MiddlewareEntry,
+  type DispatchContext,
+  type DispatchOutcome,
+  type MiddlewareNext,
+} from "./middleware";
+
+// Signals
+export { SignalBus, type Signal, type SignalKind, type SignalHandler } from "./signal";
+
+// Orchestration
+export {
+  Thread,
+  type ThreadStatus,
+  type ThreadMeta,
+  type ThreadConfig,
+  type Dispatch,
+  type DispatchOptions,
+  type DispatchObservation,
+  type FanResult,
+} from "./thread";
+
+export {
+  Harness,
+  matchesCondition,
+  type Message,
+  type HarnessResult,
+  type PipelineStep,
+  type FlowStage,
+  type FlowConfig,
+  type RequestContext,
+} from "./harness";
+
+// Tracing
+export { Trace, type Span, type SpanKind, type SpanStatus, type TraceSummary, type StageSummary } from "./trace";
+
+// Interventions
+export { InterventionLog, type Intervention } from "./intervention";
+
+// Observability
+export { EventStream, type StreamEvent, type SessionEvent } from "./event-stream";
+
+// Token & Cost Tracking
+export {
+  TokenTracker,
+  BudgetExceededError,
+  estimateTokens,
+  DEFAULT_COST_TABLE,
+  type TokenUsage,
+  type UsageEntry,
+  type ModelPricing,
+  type CostTable,
+  type BudgetConfig,
+  type BudgetStatus,
+  type UsageBreakdown,
+  type UsageSummary,
+} from "./token-tracker";
+
+// Lifecycle Hooks (registry only — built-in hooks in @inixiative/foundry)
+export {
+  HookRegistry,
+  type HookPoint,
+  type HookContext,
+  type HookResult,
+  type HookHandler,
+  type PlanModeConfig,
+  type PlanModeTrigger,
+} from "./hooks";
+
+// Action Prompts (agent→human interaction)
+export {
+  ActionQueue,
+  type ActionPrompt,
+  type ActionResolution,
+  type ActionOption,
+  type PromptKind,
+  type PromptUrgency,
+  type PromptStatus,
+  type PromptOpts,
+  type PromptListener,
+  type PromptPolicy,
+} from "./action-prompt";
+
+// Capabilities (permission flags + gating)
+export {
+  CapabilityGate,
+  CapabilityDeniedError,
+  UNATTENDED_POLICY,
+  SUPERVISED_POLICY,
+  RESTRICTED_POLICY,
+  BROWSER_POLICY,
+  type Capability,
+  type BuiltinCapability,
+  type PermissionLevel,
+  type PermissionPolicy,
+  type GateContext,
+} from "./capability";
+
+// Lightweight adapters (zero external deps)
+export {
+  FileMemory,
+  MemoryView,
+  entryVisibleTo,
+  inlineSource,
+  fileSource,
+  selectMemory,
+  focusTerms,
+  DEFAULT_MEMORY_SELECTION, validateMemorySelection,
+  type MemoryEntry,
+  type MemoryReadScope,
+  type MemorySourceOpts,
+  type MemorySelectionPolicy,
+  type MemorySelectionReport,
+} from "./adapters/file-memory";
+
+export { SqliteMemory, type SqliteEntry } from "./adapters/sqlite-memory";
+export { HttpMemory } from "./adapters/http-memory";
+export { MarkdownDocs, claudemdSource } from "./adapters/markdown-docs";
+
+// Tools — typed execution interfaces
+export {
+  ToolRegistry,
+  type Tool,
+  type ToolKind,
+  type ToolInfo,
+  type ToolResult,
+  type ToolCallObservation,
+  type BrowserTool,
+  type PageSnapshot,
+  type PageElement,
+  type NavigateOpts,
+  type ApiTool,
+  type ApiRequest,
+  type ApiResponse,
+  type ApiToolConfig,
+  type ShellTool,
+  type ShellResult,
+  type ShellOpts,
+  type OutputFilter,
+  type ScriptTool,
+  type ScriptResult,
+  type ScriptOpts,
+  type MemoryTool,
+  type MemoryEntry as ToolMemoryEntry,
+  type MemoryVisibility,
+  type MemorySearchOpts,
+} from "./tools";
+
+// Bounded data structures
+export { BoundedSet } from "./bounded-set";
+
+// IDs (UUID v7 — carries its own creation timestamp)
+export { newId, idAtTime, timeFromId } from "./id";
+
+// Retry middleware
+export { retryMiddleware, type RetryConfig } from "./retry";
+
+// Permission middleware
+export {
+  permissionMiddleware,
+  type PermissionMiddlewareConfig,
+  type PermissionCheck,
+  type PermissionCheckResult,
+} from "./permission-middleware";
+
+export { REQUIRED_CONTEXT_BLOCKED } from "./context-layer";
+export * from "./native-evidence";
+export type { CredentialReference, CredentialScope, CredentialResolver } from "./credentials";
+export { evidenceDigest, assemblyDigest, boundaryReceipt, verifyExpertDelivery } from "./delivery-evidence";
+export type { ProviderBoundaryReceipt, DeliveryOwner, ExpertDeliveryProof } from "./delivery-evidence";
+export { type TokenCounts, totalTokenCount, sumTokenCounts } from "./token-counts";