@vauban-org/agent-sdk 0.16.0

package/dist/permissions/sdk-permissions.js

@@ -0,0 +1,94 @@
+/**
+ * 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.
+ */
+const EMPTY_PERMISSIONS = Object.freeze({
+    bash: false,
+    fileIO: "none",
+    web: false,
+    mcp: Object.freeze([]),
+});
+const READ_ONLY_PERMISSIONS = Object.freeze({
+    bash: false,
+    fileIO: "ro",
+    web: false,
+    mcp: Object.freeze([
+        "brain:read",
+        "citadel:read",
+    ]),
+});
+const EXECUTE_PERMISSIONS = Object.freeze({
+    bash: "restricted",
+    fileIO: "sandboxed",
+    web: false,
+    mcp: Object.freeze([
+        "brain:read",
+        "brain:write",
+        "citadel:read",
+        "citadel:write",
+    ]),
+});
+const ADMIN_PERMISSIONS = Object.freeze({
+    bash: "restricted",
+    fileIO: "sandboxed",
+    web: true,
+    mcp: Object.freeze([
+        "brain:read",
+        "brain:write",
+        "brain:admin",
+        "citadel:read",
+        "citadel:write",
+        "citadel:admin",
+    ]),
+});
+/**
+ * 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) {
+    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, capability) {
+    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, required) {
+    if (required.length === 0)
+        return true;
+    return required.every((r) => permissions.mcp.includes(r));
+}
+//# sourceMappingURL=sdk-permissions.js.map

package/dist/permissions/sdk-permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-permissions.js","sourceRoot":"","sources":["../../src/permissions/sdk-permissions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAsBH,MAAM,iBAAiB,GAAmB,MAAM,CAAC,MAAM,CAAC;IACtD,IAAI,EAAE,KAAc;IACpB,MAAM,EAAE,MAAe;IACvB,GAAG,EAAE,KAAK;IACV,GAAG,EAAE,MAAM,CAAC,MAAM,CAAC,EAAW,CAAsB;CACrD,CAAC,CAAC;AAEH,MAAM,qBAAqB,GAAmB,MAAM,CAAC,MAAM,CAAC;IAC1D,IAAI,EAAE,KAAc;IACpB,MAAM,EAAE,IAAa;IACrB,GAAG,EAAE,KAAK;IACV,GAAG,EAAE,MAAM,CAAC,MAAM,CAAC;QACjB,YAAY;QACZ,cAAc;KACN,CAAsB;CACjC,CAAC,CAAC;AAEH,MAAM,mBAAmB,GAAmB,MAAM,CAAC,MAAM,CAAC;IACxD,IAAI,EAAE,YAAqB;IAC3B,MAAM,EAAE,WAAoB;IAC5B,GAAG,EAAE,KAAK;IACV,GAAG,EAAE,MAAM,CAAC,MAAM,CAAC;QACjB,YAAY;QACZ,aAAa;QACb,cAAc;QACd,eAAe;KACP,CAAsB;CACjC,CAAC,CAAC;AAEH,MAAM,iBAAiB,GAAmB,MAAM,CAAC,MAAM,CAAC;IACtD,IAAI,EAAE,YAAqB;IAC3B,MAAM,EAAE,WAAoB;IAC5B,GAAG,EAAE,IAAI;IACT,GAAG,EAAE,MAAM,CAAC,MAAM,CAAC;QACjB,YAAY;QACZ,aAAa;QACb,aAAa;QACb,cAAc;QACd,eAAe;QACf,eAAe;KACP,CAAsB;CACjC,CAAC,CAAC;AAEH;;;;;;;;GAQG;AACH,MAAM,UAAU,yBAAyB,CACvC,MAAyB;IAEzB,IAAI,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC;QAAE,OAAO,iBAAiB,CAAC;IAC1D,IAAI,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC;QAAE,OAAO,mBAAmB,CAAC;IAC9D,IAAI,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC;QAAE,OAAO,qBAAqB,CAAC;IAC7D,OAAO,iBAAiB,CAAC;AAC3B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,WAA2B,EAC3B,UAAyB;IAEzB,QAAQ,UAAU,EAAE,CAAC;QACnB,KAAK,MAAM;YACT,OAAO,WAAW,CAAC,IAAI,KAAK,KAAK,CAAC;QACpC,KAAK,QAAQ;YACX,OAAO,WAAW,CAAC,MAAM,KAAK,MAAM,CAAC;QACvC,KAAK,KAAK;YACR,OAAO,WAAW,CAAC,GAAG,CAAC;QACzB,KAAK,KAAK;YACR,OAAO,WAAW,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;IACtC,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC9B,WAA2B,EAC3B,QAA2B;IAE3B,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACvC,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;AAC5D,CAAC"}

package/dist/ports/agent-registry.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 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
+ */
+/**
+ * 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;
+}
+/**
+ * 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>;
+}
+//# sourceMappingURL=agent-registry.d.ts.map

package/dist/ports/agent-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-registry.d.ts","sourceRoot":"","sources":["../../src/ports/agent-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,wFAAwF;IACxF,EAAE,EAAE,MAAM,CAAC;IACX,wFAAwF;IACxF,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAC/C,uDAAuD;IACvD,eAAe,CAAC,EAAE;QAChB,wCAAwC;QACxC,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,0DAA0D;QAC1D,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,CAAC;IACF,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAID;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,UAAU,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErD;;;;;;;OAOG;IACH,IAAI,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;IAEpE;;;;;;OAMG;IACH,OAAO,CACL,UAAU,EAAE,MAAM,EAClB,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAC3B,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;IAE9B;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC"}

package/dist/ports/agent-registry.js

@@ -0,0 +1,16 @@
+/**
+ * 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
+ */
+export {};
+//# sourceMappingURL=agent-registry.js.map

package/dist/ports/agent-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-registry.js","sourceRoot":"","sources":["../../src/ports/agent-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}

package/dist/ports/brain.d.ts

@@ -0,0 +1,147 @@
+/**
+ * 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;
+}
+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 declare class InMemoryWorkingMemory implements WorkingMemoryPort {
+    private store;
+    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 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 declare class InMemoryEpisodicMemory implements EpisodicMemoryPort {
+    private events;
+    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[]>;
+    queryByTrace(traceId: string, opts?: {
+        limit?: number;
+    }): Promise<EpisodicMemoryEntry[]>;
+}
+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 declare class InMemorySemanticMemory implements SemanticMemoryPort {
+    private entries;
+    query(q: string, filters?: BrainQueryFilters): Promise<BrainEntry[]>;
+    archive(entry: BrainEntryInput): Promise<BrainEntry | null>;
+}
+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 declare class InMemoryProceduralMemory implements ProceduralMemoryPort {
+    private skills;
+    private shared;
+    resolveSkills(agentId: string): Promise<ProceduralSkill[]>;
+    registerSkill(agentId: string, skill: ProceduralSkill): Promise<void>;
+    shareSkill(skillName: string, fromAgentId: string, toAgentIds: string[]): Promise<void>;
+}
+export interface BrainPort {
+    archiveKnowledge(entry: BrainEntryInput): Promise<BrainEntry | null>;
+    queryKnowledge?(query: string, filters?: BrainQueryFilters): Promise<BrainEntry[]>;
+    working?: WorkingMemoryPort;
+    episodic?: EpisodicMemoryPort;
+    semantic?: SemanticMemoryPort;
+    procedural?: ProceduralMemoryPort;
+}
+//# sourceMappingURL=brain.d.ts.map

package/dist/ports/brain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain.d.ts","sourceRoot":"","sources":["../../src/ports/brain.ts"],"names":[],"mappings":"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"}

package/dist/ports/brain.js

@@ -0,0 +1,105 @@
+/**
+ * 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 class InMemoryWorkingMemory {
+    store = new Map();
+    async set(runId, key, value, opts) {
+        this.store.set(`${runId}:${key}`, { value, expiresAt: Date.now() + (opts?.ttlMs ?? 300_000) });
+    }
+    async get(runId, key) {
+        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, key) {
+        this.store.delete(`${runId}:${key}`);
+    }
+}
+export class InMemoryEpisodicMemory {
+    events = [];
+    async record(agentId, runId, event, metadata, opts) {
+        this.events.push({
+            agentId,
+            runId,
+            event,
+            metadata,
+            timestamp: Date.now(),
+            traceId: opts?.traceId,
+        });
+    }
+    async since(agentId, sinceMs, opts) {
+        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, opts) {
+        // 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;
+    }
+}
+export class InMemorySemanticMemory {
+    entries = [];
+    async query(q, filters) {
+        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) {
+        const created = {
+            id: `semantic-${this.entries.length + 1}`,
+            content: entry.content,
+            category: entry.category,
+            tags: entry.tags,
+            metadata: entry.metadata,
+            created_at: new Date().toISOString(),
+        };
+        this.entries.push(created);
+        return created;
+    }
+}
+export class InMemoryProceduralMemory {
+    skills = new Map();
+    shared = new Map();
+    async resolveSkills(agentId) {
+        const own = this.skills.get(agentId) ?? [];
+        const sharedSkills = [];
+        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" });
+            }
+        }
+        return [...own, ...sharedSkills];
+    }
+    async registerSkill(agentId, skill) {
+        const existing = this.skills.get(agentId) ?? [];
+        this.skills.set(agentId, [...existing, skill]);
+    }
+    async shareSkill(skillName, fromAgentId, toAgentIds) {
+        for (const _toAgent of toAgentIds) {
+            const shared = this.shared.get(fromAgentId) ?? [];
+            if (!shared.includes(skillName)) {
+                this.shared.set(fromAgentId, [...shared, skillName]);
+            }
+        }
+    }
+}
+//# sourceMappingURL=brain.js.map

package/dist/ports/brain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain.js","sourceRoot":"","sources":["../../src/ports/brain.ts"],"names":[],"mappings":"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"}

package/dist/ports/db.d.ts

@@ -0,0 +1,8 @@
+/**
+ * DbPort — re-export of the existing minimal DbClient shape from
+ * tracking/agent-run-tracker. Alias DbPort is the port-suffixed name
+ * used across other ports; DbClient remains exported for back-compat.
+ */
+export type { DbClient as DbPort } from "../tracking/agent-run-tracker.js";
+export type { DbClient } from "../tracking/agent-run-tracker.js";
+//# sourceMappingURL=db.d.ts.map

package/dist/ports/db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../src/ports/db.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,YAAY,EAAE,QAAQ,IAAI,MAAM,EAAE,MAAM,kCAAkC,CAAC;AAC3E,YAAY,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAC"}

package/dist/ports/db.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=db.js.map

package/dist/ports/db.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.js","sourceRoot":"","sources":["../../src/ports/db.ts"],"names":[],"mappings":""}