@vauban-org/agent-sdk 0.16.0

package/src/patterns/quality-gate/types.ts

@@ -0,0 +1,45 @@
+/**
+ * Pattern B: Quality Gate — types.
+ *
+ * Evaluates OODA output quality using weighted evaluator functions before
+ * action dispatch. Routes to auto / async_review / hitl_block.
+ *
+ * @public
+ */
+import type { BrainPort } from "../../ports/brain.js";
+import type { LoggerPort } from "../../ports/logger.js";
+
+export type QualityRouting = "auto" | "async_review" | "hitl_block";
+
+export interface QualityEvaluator<T> {
+  readonly name: string;
+  readonly weight?: number;
+  evaluate(subject: T): Promise<number>; // must return [0, 1]
+}
+
+export interface QualityScore {
+  readonly overall: number; // [0, 1] weighted mean
+  readonly routing: QualityRouting;
+  readonly dimensions: ReadonlyArray<{
+    readonly name: string;
+    readonly score: number;
+    readonly weight: number;
+  }>;
+}
+
+export interface QualityGateConfig<T> {
+  readonly name: string;
+  readonly evaluators: ReadonlyArray<QualityEvaluator<T>>;
+  /** Score >= this → auto. Default: 0.8 */
+  readonly autoProceedThreshold?: number;
+  /** Score >= this (and < auto) → async_review. Default: 0.5 */
+  readonly asyncReviewThreshold?: number;
+  readonly brain?: BrainPort;
+  readonly logger?: LoggerPort;
+  /** Called when routing = hitl_block. Must not throw. */
+  readonly onHitlBlock?: (score: QualityScore, subject: T) => void;
+}
+
+export interface QualityGate<T> {
+  evaluate(subject: T): Promise<QualityScore>;
+}

package/src/permissions/capability-gate.ts

@@ -0,0 +1,63 @@
+/**
+ * CapabilityGate — pre-dispatch hook for tool calls.
+ *
+ * Decouples the SDK loops from the concrete Biscuit/JWT implementation.
+ * Hosts (e.g. the Command Center) wire a `CapabilityGate` whose
+ * `verify(call)` consults a Biscuit capability token (and optionally
+ * intersects with the SDK's pinned `cc:*` scopes).
+ *
+ * Contract:
+ *  - `verify` MUST be synchronous-or-promise, but MUST NOT throw — every
+ *    failure mode is encoded in the returned `CapabilityGateVerdict`.
+ *  - `allowed: true` is the only path that authorises a tool call.
+ *  - Any non-`allowed:true` verdict denies the call AND emits a structured
+ *    reason that the loop relays via the `tool_denied` event hook.
+ */
+
+export interface CapabilityGateCall {
+  /** Tool name about to be invoked. */
+  readonly toolName: string;
+  /** Cumulative budget already spent (USD). Loop maintains the counter. */
+  readonly budgetUsed: number;
+  /** Optional MCP sub-scopes the tool declares (intersected by the host). */
+  readonly mcpScopes?: readonly string[];
+}
+
+export type CapabilityGateVerdict =
+  | { readonly allowed: true }
+  | { readonly allowed: false; readonly reason: string };
+
+export interface CapabilityGate {
+  verify(
+    call: CapabilityGateCall,
+  ): CapabilityGateVerdict | Promise<CapabilityGateVerdict>;
+  /**
+   * OPTIONAL — current token expiry (epoch seconds). Hosts that
+   * implement automatic renewal expose this so the loop can detect when
+   * 80% of the token's lifetime has elapsed and trigger a re-issue.
+   */
+  getExpiresAt?(): number;
+  /**
+   * OPTIONAL — current token issuance time (epoch seconds). Used with
+   * `getExpiresAt()` to compute the 80% threshold.
+   */
+  getIssuedAt?(): number;
+  /**
+   * OPTIONAL — replace the current capability token. Hosts that support
+   * auto-renewal call this with the freshly issued token. The gate MUST
+   * preserve cumulative `budgetUsed` across token rotations (per-session,
+   * not per-token).
+   */
+  rotateToken?(newTokenB64: string, newExpiresAt: number): void;
+}
+
+/**
+ * A no-op gate that allows every call. Suitable for tests and for
+ * agents running behind external authorisation (e.g. tier-1 read-only
+ * loops where Biscuit is enforced upstream).
+ */
+export const ALLOW_ALL_GATE: CapabilityGate = Object.freeze({
+  verify(): CapabilityGateVerdict {
+    return { allowed: true };
+  },
+});

package/src/permissions/index.ts

@@ -0,0 +1,11 @@
+export {
+  mapScopesToSdkPermissions,
+  permitsCapability,
+  permitsMcpScopes,
+} from "./sdk-permissions.js";
+export type {
+  SdkCapability,
+  SdkPermissions,
+  FileIOMode,
+  BashMode,
+} from "./sdk-permissions.js";

package/src/permissions/renewal-manager.ts

@@ -0,0 +1,89 @@
+/**
+ * RenewalManager — coordinates capability-token auto-renewal.
+ *
+ * Triggers a re-issue when ≥80% of the token lifetime has elapsed.
+ * Debounced: a renewal in flight blocks duplicate triggers; once it
+ * resolves, the gate is rotated and the timer is reset.
+ *
+ * The manager is loop-agnostic: any caller (minimal-loop, sdk-loop, or
+ * a long-running background job) can `await maybeRenew()` between tool
+ * calls. The decision is purely time-based; no per-call cost reset.
+ */
+
+import type { CapabilityGate } from "./capability-gate.js";
+
+export interface RenewalRequest {
+  readonly currentToken?: string;
+  readonly issuedAtEpochSeconds: number;
+  readonly expiresAtEpochSeconds: number;
+}
+
+export interface RenewedToken {
+  readonly token: string;
+  readonly issuedAtEpochSeconds: number;
+  readonly expiresAtEpochSeconds: number;
+}
+
+export interface RenewalManagerOptions {
+  /** Capability gate exposing getExpiresAt / getIssuedAt / rotateToken. */
+  readonly gate: CapabilityGate;
+  /** Re-issue callback — host computes the new token (e.g. via boot_agent). */
+  readonly reissue: (req: RenewalRequest) => Promise<RenewedToken>;
+  /**
+   * Lifetime fraction at which renewal triggers. Default 0.80. Must be
+   * in (0, 1).
+   */
+  readonly thresholdFraction?: number;
+  /** Clock injection for tests. Default `() => Date.now() / 1000`. */
+  readonly now?: () => number;
+}
+
+export class RenewalManager {
+  private readonly gate: CapabilityGate;
+  private readonly reissue: RenewalManagerOptions["reissue"];
+  private readonly thresholdFraction: number;
+  private readonly now: () => number;
+  private inFlight: Promise<void> | null = null;
+
+  constructor(opts: RenewalManagerOptions) {
+    this.gate = opts.gate;
+    this.reissue = opts.reissue;
+    this.thresholdFraction = opts.thresholdFraction ?? 0.8;
+    if (this.thresholdFraction <= 0 || this.thresholdFraction >= 1) {
+      throw new RangeError("thresholdFraction must be in (0, 1)");
+    }
+    this.now = opts.now ?? (() => Date.now() / 1000);
+  }
+
+  /**
+   * Trigger renewal if the current token is past the threshold. Idempotent
+   * across concurrent callers via the in-flight promise.
+   */
+  async maybeRenew(): Promise<boolean> {
+    if (this.inFlight) {
+      await this.inFlight;
+      return true;
+    }
+    const expiresAt = this.gate.getExpiresAt?.();
+    const issuedAt = this.gate.getIssuedAt?.();
+    if (expiresAt === undefined || issuedAt === undefined) return false;
+
+    const lifetime = expiresAt - issuedAt;
+    if (lifetime <= 0) return false;
+    const elapsed = this.now() - issuedAt;
+    if (elapsed / lifetime < this.thresholdFraction) return false;
+
+    const promise = (async () => {
+      const renewed = await this.reissue({
+        issuedAtEpochSeconds: issuedAt,
+        expiresAtEpochSeconds: expiresAt,
+      });
+      this.gate.rotateToken?.(renewed.token, renewed.expiresAtEpochSeconds);
+    })();
+    this.inFlight = promise.finally(() => {
+      this.inFlight = null;
+    });
+    await this.inFlight;
+    return true;
+  }
+}

package/src/permissions/sdk-permissions.ts

@@ -0,0 +1,124 @@
+/**
+ * SDK permission mapping — projects vauban-auth `cc:*` scopes onto the
+ * capability surface exposed to agent loops.
+ *
+ * Contract: scope hierarchy mirrors cc-scope-middleware.ts
+ *   admin > execute > read
+ *
+ * Worker boot MUST call `mapScopesToSdkPermissions` once at init. Tools that
+ * declare a capability absent from the derived permissions are refused at
+ * dispatch time — fail-closed, never silently downgrade.
+ */
+
+/** Capability surface the SDK loop exposes to tools. */
+export type SdkCapability = "bash" | "fileIO" | "web" | "mcp";
+
+/** Severity of filesystem access granted to tools. */
+export type FileIOMode = "none" | "ro" | "sandboxed";
+
+/** Severity of shell access granted to tools. */
+export type BashMode = false | "restricted";
+
+/**
+ * Runtime permission envelope. An SDK loop instance is pinned to exactly one
+ * of these at construction and never mutates it.
+ */
+export interface SdkPermissions {
+  readonly bash: BashMode;
+  readonly fileIO: FileIOMode;
+  readonly web: boolean;
+  readonly mcp: readonly string[];
+}
+
+const EMPTY_PERMISSIONS: SdkPermissions = Object.freeze({
+  bash: false as const,
+  fileIO: "none" as const,
+  web: false,
+  mcp: Object.freeze([] as const) as readonly string[],
+});
+
+const READ_ONLY_PERMISSIONS: SdkPermissions = Object.freeze({
+  bash: false as const,
+  fileIO: "ro" as const,
+  web: false,
+  mcp: Object.freeze([
+    "brain:read",
+    "citadel:read",
+  ] as const) as readonly string[],
+});
+
+const EXECUTE_PERMISSIONS: SdkPermissions = Object.freeze({
+  bash: "restricted" as const,
+  fileIO: "sandboxed" as const,
+  web: false,
+  mcp: Object.freeze([
+    "brain:read",
+    "brain:write",
+    "citadel:read",
+    "citadel:write",
+  ] as const) as readonly string[],
+});
+
+const ADMIN_PERMISSIONS: SdkPermissions = Object.freeze({
+  bash: "restricted" as const,
+  fileIO: "sandboxed" as const,
+  web: true,
+  mcp: Object.freeze([
+    "brain:read",
+    "brain:write",
+    "brain:admin",
+    "citadel:read",
+    "citadel:write",
+    "citadel:admin",
+  ] as const) as readonly string[],
+});
+
+/**
+ * Project a JWT scope list onto SDK capabilities. Unknown scopes are ignored.
+ *
+ * Rules:
+ * - `cc:admin` → full surface (bash restricted, fileIO sandboxed, web, mcp *)
+ * - `cc:execute` → bash:restricted + fileIO:sandboxed + web:false + mcp R/W
+ * - `cc:read` → bash:false + fileIO:ro + web:false + mcp R only
+ * - no `cc:*` scope → fail-closed: no capabilities at all
+ */
+export function mapScopesToSdkPermissions(
+  scopes: readonly string[],
+): SdkPermissions {
+  if (scopes.includes("cc:admin")) return ADMIN_PERMISSIONS;
+  if (scopes.includes("cc:execute")) return EXECUTE_PERMISSIONS;
+  if (scopes.includes("cc:read")) return READ_ONLY_PERMISSIONS;
+  return EMPTY_PERMISSIONS;
+}
+
+/**
+ * Returns true iff `permissions` authorises `capability`. Canonical gate
+ * used by the SDK loop before dispatching a tool.
+ */
+export function permitsCapability(
+  permissions: SdkPermissions,
+  capability: SdkCapability,
+): boolean {
+  switch (capability) {
+    case "bash":
+      return permissions.bash !== false;
+    case "fileIO":
+      return permissions.fileIO !== "none";
+    case "web":
+      return permissions.web;
+    case "mcp":
+      return permissions.mcp.length > 0;
+  }
+}
+
+/**
+ * Returns true iff the caller holds every MCP permission in `required`.
+ * Used when a tool declares a specific MCP sub-scope (e.g. "brain:write").
+ */
+export function permitsMcpScopes(
+  permissions: SdkPermissions,
+  required: readonly string[],
+): boolean {
+  if (required.length === 0) return true;
+  return required.every((r) => permissions.mcp.includes(r));
+}

package/src/ports/agent-registry.ts

@@ -0,0 +1,104 @@
+/**
+ * AgentRegistryPort — discovery contract for named, capability-tagged agents.
+ *
+ * Enables the Orchestrator and GTM Arbiter (Forge) to discover agents by
+ * capability without depending on a concrete registry implementation. SaaS
+ * clients register their own agents by calling `register()`.
+ *
+ * Two adapters ship with the SDK:
+ *   - `MemoryAgentRegistry`   — zero-dependency, suitable for tests and
+ *                               single-process deployments.
+ *   - `PostgresAgentRegistry` — persistent, multi-tenant via RLS.
+ *
+ * @module ports/agent-registry
+ */
+
+// ─── AgentDescriptor ─────────────────────────────────────────────────────────
+
+/**
+ * Descriptor for a registered agent. All fields are immutable after
+ * `register()`. Use `unregister + register` to update.
+ *
+ * `id` format: `<product>:<slug>` (e.g. `"forge:01-revenue"`).
+ * Callers SHOULD follow that convention but it is not enforced here.
+ */
+export interface AgentDescriptor {
+  /** Stable unique identifier. Format: `<product>:<slug>` (e.g. `"forge:01-revenue"`). */
+  id: string;
+  /** Owning product namespace (e.g. `"forge"`, `"vauban"`, `"cc"`, `"<client-saas>"`). */
+  product: string;
+  /** Declared capabilities (e.g. `["content-generation", "market-analysis"]`). */
+  capabilities: string[];
+  /**
+   * JSON Schema describing the expected input shape for this agent.
+   * Callers SHOULD validate incoming payloads against this schema.
+   */
+  inputSchema: object;
+  /** How this agent is triggered. */
+  trigger: "event" | "cron" | "hitl" | "webhook";
+  /** Optional LLM requirements declared by the agent. */
+  llmRequirements?: {
+    /** Minimum context window in tokens. */
+    minContextWindow?: number;
+    /** Whether the agent requires tool-use capable models. */
+    toolUse?: boolean;
+  };
+  /** Tenant scope. When set, the descriptor is isolated to that tenant. */
+  tenantId?: string;
+}
+
+// ─── AgentRegistryPort ───────────────────────────────────────────────────────
+
+/**
+ * Port interface for agent discovery. Hosts inject a concrete adapter
+ * (Memory, Postgres) at boot; agents depend only on this interface.
+ */
+export interface AgentRegistryPort {
+  /**
+   * Register an agent descriptor in the registry.
+   *
+   * **Upsert semantics**: if an agent with the same `id` already exists,
+   * the previous record is replaced atomically. This makes `register()`
+   * safe to call on every process start (auto-register pattern):
+   *
+   * ```ts
+   * // At agent-module load time — idempotent across restarts.
+   * await registry.register(myAgentDescriptor);
+   * ```
+   *
+   * @param descriptor - The agent to register or update.
+   */
+  register(descriptor: AgentDescriptor): Promise<void>;
+
+  /**
+   * List all registered agents, optionally filtered by descriptor fields.
+   *
+   * Only top-level scalar fields are compared for filtering (`product`,
+   * `trigger`, `tenantId`). Use `resolve()` for capability-based lookup.
+   *
+   * @param filter - Partial descriptor; only provided fields are matched.
+   */
+  list(filter?: Partial<AgentDescriptor>): Promise<AgentDescriptor[]>;
+
+  /**
+   * Resolve agents that declare a given capability.
+   *
+   * @param capability - The capability string to search for.
+   * @param opts.tenantId - When provided, results are scoped to that tenant
+   *   (plus global agents without a `tenantId`).
+   */
+  resolve(
+    capability: string,
+    opts?: { tenantId?: string }
+  ): Promise<AgentDescriptor[]>;
+
+  /**
+   * Remove a registered agent by id.
+   *
+   * Implementations MUST NOT throw if the id is not found — the operation
+   * is idempotent by design.
+   *
+   * @param id - The agent id to remove.
+   */
+  unregister(id: string): Promise<void>;
+}

package/src/ports/brain.ts

@@ -0,0 +1,255 @@
+/**
+ * BrainPort — knowledge archival + retrieval contract (4 memory tiers).
+ *
+ * Tier 1 — working: get/set with scope='run' + ttlMs auto-expire (A6, sprint-562).
+ * Tier 2 — episodic: since/record per agentId (A6, sprint-562).
+ * Tier 3 — semantic: query/archive shared across agents (C4, sprint-564).
+ * Tier 4 — procedural: resolveSkills for learned/private/shared skills (C4, sprint-564).
+ */
+
+export interface BrainEntryInput {
+  content: string;
+  content_type?: string;
+  author?: string;
+  category?: string;
+  tags?: string[];
+  confidence?: number;
+  metadata?: Record<string, unknown>;
+  brain_id?: string;
+}
+
+export interface BrainEntry {
+  id: string;
+  content: string;
+  category?: string;
+  tags?: string[];
+  metadata?: Record<string, unknown>;
+  created_at?: string;
+}
+
+export interface BrainQueryFilters {
+  category?: string;
+  tags?: string[];
+  limit?: number;
+  [key: string]: unknown;
+}
+
+// ─── Tier 1: Working memory ──────────────────────────────────────────────────
+
+export interface WorkingMemoryPort {
+  set(runId: string, key: string, value: unknown, opts?: { ttlMs?: number }): Promise<void>;
+  get(runId: string, key: string): Promise<unknown>;
+  delete(runId: string, key: string): Promise<void>;
+}
+
+export class InMemoryWorkingMemory implements WorkingMemoryPort {
+  private store = new Map<string, { value: unknown; expiresAt: number }>();
+
+  async set(runId: string, key: string, value: unknown, opts?: { ttlMs?: number }): Promise<void> {
+    this.store.set(`${runId}:${key}`, { value, expiresAt: Date.now() + (opts?.ttlMs ?? 300_000) });
+  }
+
+  async get(runId: string, key: string): Promise<unknown> {
+    const entry = this.store.get(`${runId}:${key}`);
+    if (!entry) return null;
+    if (Date.now() > entry.expiresAt) {
+      this.store.delete(`${runId}:${key}`);
+      return null;
+    }
+    return entry.value;
+  }
+
+  async delete(runId: string, key: string): Promise<void> {
+    this.store.delete(`${runId}:${key}`);
+  }
+}
+
+// ─── Tier 2: Episodic memory ─────────────────────────────────────────────────
+
+export interface EpisodicMemoryEntry {
+  agentId: string;
+  runId: string;
+  event: string;
+  metadata?: Record<string, unknown>;
+  timestamp: number;
+  /**
+   * OTel trace ID associated with the run that produced this entry.
+   * Optional for backward compatibility — existing entries without traceId
+   * are never returned by queryByTrace.
+   *
+   * DB impact: migration 037_episodic_indexed_by_trace.sql adds
+   * `trace_id TEXT` column + `idx_episodic_trace_id` B-tree index
+   * on `episodic_memory(trace_id)`.
+   */
+  traceId?: string;
+}
+
+export interface EpisodicMemoryPort {
+  /**
+   * Record an episodic event.
+   *
+   * @param agentId - Owning agent.
+   * @param runId   - Run (execution) identifier.
+   * @param event   - Event name / label.
+   * @param metadata - Arbitrary structured payload.
+   * @param opts.traceId - OTel trace ID to associate with this entry (optional,
+   *   non-breaking — callers that do not pass it produce entries invisible to queryByTrace).
+   */
+  record(
+    agentId: string,
+    runId: string,
+    event: string,
+    metadata?: Record<string, unknown>,
+    opts?: { traceId?: string },
+  ): Promise<void>;
+  since(
+    agentId: string,
+    sinceMs: number,
+    opts?: { limit?: number },
+  ): Promise<EpisodicMemoryEntry[]>;
+  /**
+   * Retrieve all episodic entries associated with a given OTel trace ID,
+   * ordered by insertion (ascending timestamp).
+   *
+   * @param traceId - OTel W3C trace ID (32 hex chars) or any opaque run-correlation key.
+   * @param opts.limit - Maximum number of entries to return (default: unbounded).
+   * @returns Entries matching traceId, oldest first.
+   */
+  queryByTrace(traceId: string, opts?: { limit?: number }): Promise<EpisodicMemoryEntry[]>;
+}
+
+export class InMemoryEpisodicMemory implements EpisodicMemoryPort {
+  private events: EpisodicMemoryEntry[] = [];
+
+  async record(
+    agentId: string,
+    runId: string,
+    event: string,
+    metadata?: Record<string, unknown>,
+    opts?: { traceId?: string },
+  ): Promise<void> {
+    this.events.push({
+      agentId,
+      runId,
+      event,
+      metadata,
+      timestamp: Date.now(),
+      traceId: opts?.traceId,
+    });
+  }
+
+  async since(
+    agentId: string,
+    sinceMs: number,
+    opts?: { limit?: number },
+  ): Promise<EpisodicMemoryEntry[]> {
+    const filtered = this.events
+      .filter((e) => e.agentId === agentId && e.timestamp >= sinceMs)
+      .sort((a, b) => b.timestamp - a.timestamp);
+    return opts?.limit ? filtered.slice(0, opts.limit) : filtered;
+  }
+
+  async queryByTrace(traceId: string, opts?: { limit?: number }): Promise<EpisodicMemoryEntry[]> {
+    // Insertion order is preserved (Array.filter is stable; events are pushed in order).
+    const filtered = this.events.filter((e) => e.traceId === traceId);
+    return opts?.limit ? filtered.slice(0, opts.limit) : filtered;
+  }
+}
+
+// ─── Tier 3: Semantic memory (C4 — sprint-564) ───────────────────────────────
+
+export interface SemanticMemoryPort {
+  /** Query shared knowledge across agents. */
+  query(q: string, filters?: BrainQueryFilters): Promise<BrainEntry[]>;
+  /** Archive shared knowledge. */
+  archive(entry: BrainEntryInput): Promise<BrainEntry | null>;
+}
+
+export class InMemorySemanticMemory implements SemanticMemoryPort {
+  private entries: BrainEntry[] = [];
+
+  async query(q: string, filters?: BrainQueryFilters): Promise<BrainEntry[]> {
+    let results = this.entries.filter((e) => e.content.toLowerCase().includes(q.toLowerCase()));
+    if (filters?.category) results = results.filter((e) => e.category === filters.category);
+    if (filters?.tags && filters.tags.length > 0) {
+      results = results.filter((e) => e.tags?.some((t) => filters.tags?.includes(t)));
+    }
+    return filters?.limit ? results.slice(0, filters.limit) : results;
+  }
+
+  async archive(entry: BrainEntryInput): Promise<BrainEntry | null> {
+    const created: BrainEntry = {
+      id: `semantic-${this.entries.length + 1}`,
+      content: entry.content,
+      category: entry.category,
+      tags: entry.tags,
+      metadata: entry.metadata as Record<string, unknown> | undefined,
+      created_at: new Date().toISOString(),
+    };
+    this.entries.push(created);
+    return created;
+  }
+}
+
+// ─── Tier 4: Procedural memory (C4 — sprint-564) ─────────────────────────────
+
+export interface ProceduralSkill {
+  name: string;
+  description: string;
+  source: "learning-loop" | "manual" | "shared";
+  confidence: number;
+  chainOfThought?: string;
+}
+
+export interface ProceduralMemoryPort {
+  /** Resolve all skills available to an agent (learned + shared + private). */
+  resolveSkills(agentId: string): Promise<ProceduralSkill[]>;
+  /** Register a learned skill for an agent. */
+  registerSkill(agentId: string, skill: ProceduralSkill): Promise<void>;
+  /** Share a skill with other agents. */
+  shareSkill(skillName: string, fromAgentId: string, toAgentIds: string[]): Promise<void>;
+}
+
+export class InMemoryProceduralMemory implements ProceduralMemoryPort {
+  private skills = new Map<string, ProceduralSkill[]>();
+  private shared = new Map<string, string[]>();
+
+  async resolveSkills(agentId: string): Promise<ProceduralSkill[]> {
+    const own = this.skills.get(agentId) ?? [];
+    const sharedSkills: ProceduralSkill[] = [];
+    for (const [fromAgent, skillNames] of this.shared) {
+      const fromSkills = this.skills.get(fromAgent) ?? [];
+      for (const name of skillNames) {
+        const skill = fromSkills.find((s) => s.name === name);
+        if (skill) sharedSkills.push({ ...skill, source: "shared" as const });
+      }
+    }
+    return [...own, ...sharedSkills];
+  }
+
+  async registerSkill(agentId: string, skill: ProceduralSkill): Promise<void> {
+    const existing = this.skills.get(agentId) ?? [];
+    this.skills.set(agentId, [...existing, skill]);
+  }
+
+  async shareSkill(skillName: string, fromAgentId: string, toAgentIds: string[]): Promise<void> {
+    for (const _toAgent of toAgentIds) {
+      const shared = this.shared.get(fromAgentId) ?? [];
+      if (!shared.includes(skillName)) {
+        this.shared.set(fromAgentId, [...shared, skillName]);
+      }
+    }
+  }
+}
+
+// ─── Full BrainPort (4 tiers, additive non-breaking) ─────────────────────────
+
+export interface BrainPort {
+  archiveKnowledge(entry: BrainEntryInput): Promise<BrainEntry | null>;
+  queryKnowledge?(query: string, filters?: BrainQueryFilters): Promise<BrainEntry[]>;
+
+  working?: WorkingMemoryPort;
+  episodic?: EpisodicMemoryPort;
+  semantic?: SemanticMemoryPort;
+  procedural?: ProceduralMemoryPort;
+}