@inixiative/foundry-core 0.1.0

package/src/bounded-set.ts

@@ -0,0 +1,42 @@
+/**
+ * A set with bounded capacity that evicts oldest entries when full.
+ * Used for message deduplication at harness ingress.
+ */
+export class BoundedSet<T> {
+  private _items: T[] = [];
+  private _set: Set<T> = new Set();
+  private _capacity: number;
+
+  constructor(capacity: number = 1000) {
+    this._capacity = capacity;
+  }
+
+  /** Check if item exists in the set. */
+  has(item: T): boolean {
+    return this._set.has(item);
+  }
+
+  /** Add item. Returns true if newly added, false if already present. */
+  add(item: T): boolean {
+    if (this._set.has(item)) return false;
+
+    this._set.add(item);
+    this._items.push(item);
+
+    if (this._items.length > this._capacity) {
+      const evicted = this._items.shift()!;
+      this._set.delete(evicted);
+    }
+
+    return true;
+  }
+
+  get size(): number {
+    return this._set.size;
+  }
+
+  clear(): void {
+    this._items = [];
+    this._set.clear();
+  }
+}

package/src/cache-lifecycle.ts

@@ -0,0 +1,187 @@
+import { ContextLayer, type LayerState } from "./context-layer";
+import { ContextStack } from "./context-stack";
+
+export interface LifecycleEvent {
+  readonly type: string;
+  readonly layerId: string;
+  readonly timestamp: number;
+  readonly meta?: Record<string, unknown>;
+}
+
+export type LifecycleHandler = (
+  event: LifecycleEvent
+) => void | false | Promise<void | false>;
+
+export interface LifecycleRule {
+  readonly id: string;
+  readonly triggers: LayerState[];
+  readonly layerIds?: string[];
+  action(
+    layer: ContextLayer,
+    state: LayerState,
+    stack: ContextStack
+  ): Promise<void>;
+}
+
+/**
+ * Manages the lifecycle of layers within a stack.
+ *
+ * This is the "when things happen" primitive. It doesn't decide
+ * what triggers matter — you register rules that do.
+ *
+ * Events are queued and processed sequentially to prevent
+ * re-entrant recursion from state changes triggering more state changes.
+ */
+export class CacheLifecycle {
+  private _stack: ContextStack;
+  private _rules: LifecycleRule[] = [];
+  private _handlers: Map<string, LifecycleHandler[]> = new Map();
+  private _unsubscribes: Array<() => void> = [];
+  private _running = false;
+
+  // Event queue to prevent re-entrant recursion
+  private _queue: Array<{ state: LayerState; layer: ContextLayer }> = [];
+  private _processing = false;
+
+  constructor(stack: ContextStack) {
+    this._stack = stack;
+  }
+
+  // -- Rules --
+
+  addRule(rule: LifecycleRule): void {
+    this._rules.push(rule);
+  }
+
+  removeRule(id: string): boolean {
+    const idx = this._rules.findIndex((r) => r.id === id);
+    if (idx === -1) return false;
+    this._rules.splice(idx, 1);
+    return true;
+  }
+
+  // -- Event handlers --
+
+  on(eventType: string, handler: LifecycleHandler): () => void {
+    if (!this._handlers.has(eventType)) {
+      this._handlers.set(eventType, []);
+    }
+    this._handlers.get(eventType)!.push(handler);
+
+    return () => {
+      const handlers = this._handlers.get(eventType);
+      if (handlers) {
+        const idx = handlers.indexOf(handler);
+        if (idx !== -1) handlers.splice(idx, 1);
+      }
+    };
+  }
+
+  async emit(event: LifecycleEvent): Promise<void> {
+    const handlers = this._handlers.get(event.type) ?? [];
+    for (const handler of handlers) {
+      const result = await handler(event);
+      if (result === false) break;
+    }
+  }
+
+  // -- Activation --
+
+  start(): void {
+    if (this._running) return;
+    this._running = true;
+
+    for (const layer of this._stack.layers) {
+      this._observe(layer);
+    }
+
+    // Auto-observe layers added after start
+    const unsub = this._stack.onLayerAdded((layer) => {
+      if (this._running) this._observe(layer);
+    });
+    this._unsubscribes.push(unsub);
+  }
+
+  stop(): void {
+    this._running = false;
+    for (const unsub of this._unsubscribes) {
+      unsub();
+    }
+    this._unsubscribes = [];
+  }
+
+  observe(layer: ContextLayer): void {
+    if (this._running) {
+      this._observe(layer);
+    }
+  }
+
+  // -- Internal --
+
+  private _observe(layer: ContextLayer): void {
+    const unsub = layer.onStateChange((state, l) => {
+      // Enqueue instead of processing inline — prevents re-entrant recursion
+      this._queue.push({ state, layer: l });
+      this._drain();
+    });
+
+    this._unsubscribes.push(unsub);
+  }
+
+  private _drain(): void {
+    if (this._processing) return;
+    this._processing = true;
+
+    // Use queueMicrotask so the drain runs after the current synchronous
+    // state mutation completes, but before the next macrotask.
+    queueMicrotask(async () => {
+      try {
+        while (this._queue.length > 0) {
+          const { state, layer } = this._queue.shift()!;
+
+          try {
+            await this.emit({
+              type: `layer:${state}`,
+              layerId: layer.id,
+              timestamp: Date.now(),
+            });
+
+            for (const rule of this._rules) {
+              if (!rule.triggers.includes(state)) continue;
+              if (rule.layerIds && !rule.layerIds.includes(layer.id)) continue;
+
+              try {
+                await rule.action(layer, state, this._stack);
+              } catch (err) {
+                // Best-effort error event — if this also throws, outer catch handles it
+                try {
+                  await this.emit({
+                    type: "rule:error",
+                    layerId: layer.id,
+                    timestamp: Date.now(),
+                    meta: { ruleId: rule.id, error: err },
+                  });
+                } catch (emitErr) {
+                  console.warn(`[CacheLifecycle] failed to emit rule:error for ${layer.id}:`, (emitErr as Error).message);
+                }
+              }
+            }
+          } catch (err) {
+            try {
+              await this.emit({
+                type: "lifecycle:error",
+                layerId: layer.id,
+                timestamp: Date.now(),
+                meta: { error: err },
+              });
+            } catch (emitErr) {
+              console.warn(`[CacheLifecycle] failed to emit lifecycle:error for ${layer.id}:`, (emitErr as Error).message);
+            }
+          }
+        }
+      } finally {
+        this._processing = false;
+      }
+    });
+  }
+}

package/src/capability.ts

@@ -0,0 +1,252 @@
+// ---------------------------------------------------------------------------
+// Capability — permission flags and gating for dangerous operations
+// ---------------------------------------------------------------------------
+//
+// Every operation that could be dangerous (file writes, network calls,
+// expensive LLM calls, data deletion, shell execution) is a "capability."
+//
+// A PermissionPolicy maps capabilities to permission levels:
+//   - "allow"  → proceed silently
+//   - "prompt" → emit an ActionPrompt and wait for approval
+//   - "deny"   → reject immediately
+//
+// CapabilityGate checks permissions before operations. When a check
+// results in "prompt", the gate uses the ActionQueue to block until
+// a human (or policy hook) approves.
+// ---------------------------------------------------------------------------
+
+import { ActionQueue, type ActionResolution } from "./action-prompt";
+
+// ---------------------------------------------------------------------------
+// Built-in capabilities
+// ---------------------------------------------------------------------------
+
+/**
+ * Known capability categories. Adapters and providers use these
+ * to declare what they need. Custom capabilities use string literals.
+ */
+export type BuiltinCapability =
+  // File system
+  | "file:read"
+  | "file:write"
+  | "file:delete"
+  // Network
+  | "net:fetch"
+  | "net:api"
+  // LLM
+  | "llm:call"
+  | "llm:expensive"
+  // Data stores
+  | "data:read"
+  | "data:write"
+  | "data:delete"
+  // Execution
+  | "exec:shell"
+  | "exec:process"
+  // Browser
+  | "browser:navigate"
+  | "browser:interact"
+  | "browser:execute"
+  | "browser:screenshot"
+  // Meta
+  | "prompt:auto-resolve";
+
+/** Any string is a valid capability. Builtins are just conventions. */
+export type Capability = BuiltinCapability | (string & {});
+
+export type PermissionLevel = "allow" | "prompt" | "deny";
+
+// ---------------------------------------------------------------------------
+// PermissionPolicy
+// ---------------------------------------------------------------------------
+
+export interface PermissionPolicy {
+  /** Default for capabilities not explicitly listed. */
+  defaults: PermissionLevel;
+  /** Per-capability overrides. */
+  capabilities: Partial<Record<string, PermissionLevel>>;
+  /** Auto-prompt for LLM calls estimated above this dollar amount. */
+  costThreshold?: number;
+  /** Auto-prompt for operations touching these path patterns. */
+  protectedPaths?: string[];
+}
+
+/** Convenience: everything allowed, no prompts. */
+export const UNATTENDED_POLICY: PermissionPolicy = {
+  defaults: "allow",
+  capabilities: {},
+};
+
+/** Convenience: prompt for writes/deletes/exec/expensive, allow reads. */
+export const SUPERVISED_POLICY: PermissionPolicy = {
+  defaults: "prompt",
+  capabilities: {
+    "file:read": "allow",
+    "data:read": "allow",
+    "net:fetch": "allow",
+    "llm:call": "allow",
+  },
+};
+
+/** Convenience: deny dangerous ops, allow reads and cheap LLM. */
+export const RESTRICTED_POLICY: PermissionPolicy = {
+  defaults: "deny",
+  capabilities: {
+    "file:read": "allow",
+    "data:read": "allow",
+    "net:fetch": "allow",
+    "llm:call": "allow",
+    "llm:expensive": "deny",
+    "exec:shell": "deny",
+    "exec:process": "deny",
+    "file:delete": "deny",
+    "data:delete": "deny",
+    "browser:navigate": "deny",
+    "browser:interact": "deny",
+    "browser:execute": "deny",
+    "browser:screenshot": "deny",
+  },
+};
+
+/** Convenience: browser-capable agent — allows navigation and interaction, prompts for JS execution. */
+export const BROWSER_POLICY: PermissionPolicy = {
+  defaults: "prompt",
+  capabilities: {
+    "file:read": "allow",
+    "data:read": "allow",
+    "net:fetch": "allow",
+    "llm:call": "allow",
+    "browser:navigate": "allow",
+    "browser:interact": "allow",
+    "browser:execute": "prompt",
+    "browser:screenshot": "allow",
+    "exec:shell": "deny",
+    "exec:process": "deny",
+    "file:delete": "deny",
+    "data:delete": "deny",
+  },
+};
+
+// ---------------------------------------------------------------------------
+// CapabilityGate
+// ---------------------------------------------------------------------------
+
+export class CapabilityDeniedError extends Error {
+  readonly capability: string;
+  readonly level: PermissionLevel;
+  constructor(capability: string, level: PermissionLevel) {
+    super(`Capability "${capability}" is ${level}`);
+    this.name = "CapabilityDeniedError";
+    this.capability = capability;
+    this.level = level;
+  }
+}
+
+export interface GateContext {
+  agentId: string;
+  threadId: string;
+  /** Extra info for the prompt message (path, cost, model, etc.). */
+  detail?: string;
+  meta?: Record<string, unknown>;
+}
+
+export class CapabilityGate {
+  private _policy: PermissionPolicy;
+  private _queue: ActionQueue;
+
+  constructor(policy: PermissionPolicy, queue: ActionQueue) {
+    this._policy = policy;
+    this._queue = queue;
+  }
+
+  get policy(): PermissionPolicy { return this._policy; }
+
+  /** Update policy at runtime (e.g. operator toggles supervised mode). */
+  setPolicy(policy: PermissionPolicy): void {
+    this._policy = policy;
+  }
+
+  /**
+   * Check a capability. Returns the resolution if prompted, or
+   * a synthetic resolution for allow/deny.
+   */
+  async check(capability: Capability, ctx: GateContext): Promise<ActionResolution> {
+    const level = this._resolve(capability, ctx);
+
+    if (level === "allow") {
+      return { by: "policy", action: "approved", timestamp: Date.now() };
+    }
+
+    if (level === "deny") {
+      return { by: "policy", action: "rejected", timestamp: Date.now() };
+    }
+
+    // level === "prompt"
+    const message = this._buildMessage(capability, ctx);
+    return this._queue.prompt({
+      kind: "approval",
+      message,
+      agentId: ctx.agentId,
+      threadId: ctx.threadId,
+      capability,
+      urgency: this._urgencyFor(capability),
+      meta: ctx.meta,
+    });
+  }
+
+  /**
+   * Check and throw if denied or rejected.
+   * Use this as a guard before dangerous operations.
+   */
+  async require(capability: Capability, ctx: GateContext): Promise<void> {
+    const resolution = await this.check(capability, ctx);
+    if (resolution.action !== "approved") {
+      throw new CapabilityDeniedError(capability, "deny");
+    }
+  }
+
+  /**
+   * Synchronous check — returns the permission level without prompting.
+   * Use this when you need to know the level but can't block.
+   */
+  levelFor(capability: Capability, ctx?: Partial<GateContext>): PermissionLevel {
+    return this._resolve(capability, ctx as GateContext);
+  }
+
+  // -- Internal --
+
+  private _resolve(capability: Capability, ctx?: GateContext): PermissionLevel {
+    // Explicit capability override
+    const explicit = this._policy.capabilities[capability];
+    if (explicit) return explicit;
+
+    // Cost threshold check for LLM calls
+    if (capability === "llm:call" && this._policy.costThreshold != null && ctx?.meta?.estimatedCost != null) {
+      if ((ctx.meta.estimatedCost as number) > this._policy.costThreshold) {
+        return "prompt";
+      }
+    }
+
+    // Protected paths check for file ops
+    if ((capability === "file:write" || capability === "file:delete") && this._policy.protectedPaths?.length && ctx?.meta?.path) {
+      const path = ctx.meta.path as string;
+      if (this._policy.protectedPaths.some((p) => path.includes(p))) {
+        return "prompt";
+      }
+    }
+
+    return this._policy.defaults;
+  }
+
+  private _buildMessage(capability: Capability, ctx: GateContext): string {
+    const detail = ctx.detail ? ` — ${ctx.detail}` : "";
+    return `Agent "${ctx.agentId}" requires capability "${capability}"${detail}`;
+  }
+
+  private _urgencyFor(capability: Capability): "low" | "normal" | "high" | "critical" {
+    if (capability === "exec:shell" || capability === "exec:process") return "high";
+    if (capability.endsWith(":delete")) return "high";
+    if (capability === "llm:expensive") return "normal";
+    return "normal";
+  }
+}

package/src/classifier.ts

@@ -0,0 +1,43 @@
+import { Decider, type DeciderConfig, type Decision } from "./decider";
+import type { AgentConfig } from "./base-agent";
+import type { ContextStack } from "./context-stack";
+import type { ExecuteMeta } from "./executor";
+
+/**
+ * A classification — "what is this thing?"
+ */
+export interface Classification {
+  readonly category: string;
+  readonly subcategory?: string;
+  readonly tags?: string[];
+}
+
+export type ClassifyHandler<TPayload> = (
+  context: string,
+  payload: TPayload,
+  meta?: ExecuteMeta
+) => Promise<Decision<Classification>>;
+
+export interface ClassifierConfig<TPayload = unknown> extends AgentConfig {
+  handler: ClassifyHandler<TPayload>;
+}
+
+/**
+ * A Classifier is a Decider that returns a category.
+ *
+ * "Given everything you know about the taxonomy, what IS this?"
+ * The Classifier has the full taxonomy loaded in its context layers.
+ * The caller sends a payload and gets back a category — not the taxonomy.
+ */
+export class Classifier<TPayload = unknown> extends Decider<
+  TPayload,
+  Classification
+> {
+  constructor(config: ClassifierConfig<TPayload>) {
+    super(config as DeciderConfig<TPayload, Classification>);
+  }
+
+  override withStack(stack: ContextStack): Classifier<TPayload> {
+    return new Classifier<TPayload>({ ...this.agentConfig(stack), handler: this._handler });
+  }
+}