@pylabmit/agent-cmdb 1.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PYLABMIT
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,249 @@
+# Agent CMDB
+
+[![CI](https://github.com/vikas53953/agent-cmdb-policy-brain/actions/workflows/ci.yml/badge.svg)](https://github.com/vikas53953/agent-cmdb-policy-brain/actions/workflows/ci.yml)
+![Tests](https://img.shields.io/badge/tests-153_passing-brightgreen)
+
+Policy enforcement and memory for AI agents.
+
+Agent CMDB gives your agent a preflight check before it acts: policy enforcement, source routing, inventory, graph relationships, and audit trails.
+
+Use it when you need to answer:
+
+- Is this agent allowed to do this action?
+- Which source/tool should it use first?
+- What rule blocked it, and why?
+- What evidence and config changes were recorded?
+- Is my agent control plane healthy enough to run?
+
+## How It Works
+
+Agent CMDB is a library your agent calls before acting. You wire `preflight()` into your agent's tool-call path. It evaluates policy, routes to the best source, and logs the decision. It does not automatically intercept tool calls - you integrate it into your agent framework.
+
+## What This Is NOT
+
+Agent CMDB is not a network proxy or middleware that sits between your agent and its tools. It is a policy evaluation library. For automatic tool-call interception, see Agent Airlock or `airlock-dev/airlock`.
+
+## Install
+
+```bash
+npm install @pylabmit/agent-cmdb
+npx agent-cmdb init
+```
+
+`init` creates:
+
+```text
+agent-cmdb/
+  config/
+    control-plane.yaml
+  state/
+    evidence.jsonl
+    changes.jsonl
+  brain/
+    entities/
+      people/
+      companies/
+      topics/
+      tools/
+      projects/
+    decisions/
+    digest/
+      daily/
+      weekly/
+    index.json
+agent-cmdb.config.ts
+```
+
+## Quick Start
+
+```ts
+import { createAgentCmdb } from '@pylabmit/agent-cmdb';
+
+const cmdb = createAgentCmdb({
+  configPath: './agent-cmdb/config/control-plane.yaml',
+  storeDir: './agent-cmdb/state'
+});
+
+const result = cmdb.preflight({
+  profile: 'research-agent',
+  action: 'web_search',
+  tool: 'serpapi',
+  intent: 'web_research'
+});
+
+if (!result.allowed) {
+  console.log(`Blocked: ${result.decision.reason}`);
+  console.log(`Can escalate: ${result.decision.canEscalate}`);
+  console.log(`Try instead: ${result.decision.suggestedAlternative}`);
+} else {
+  for (const source of result.route?.sources ?? []) {
+    console.log(`Use ${source.id} (${source.kind})`);
+  }
+}
+```
+
+## Agent Memory (Brain)
+
+Agent CMDB includes an optional local knowledge base. No database, no embeddings - just markdown files that agents read before acting and update after.
+
+```ts
+const cmdb = createAgentCmdb({
+  configPath: './agent-cmdb/config/control-plane.yaml',
+  storeDir: './agent-cmdb/state',
+  brainDir: './agent-cmdb/brain'
+});
+
+const knowledge = await cmdb.readEntity('agent-security');
+console.log(knowledge.content);
+console.log(knowledge.stale ? 'Needs refresh' : 'Fresh');
+
+await cmdb.writeEntity({
+  entityId: 'agent-security',
+  content: '## New findings\n\n3 CVEs discovered...',
+  actor: 'research-agent',
+  reason: 'Daily security scan',
+  appendOnly: true
+});
+
+await cmdb.generateDailyDigest('research-agent');
+```
+
+## Control Plane
+
+Agent CMDB reads YAML or JSON.
+
+```yaml
+version: "1.0"
+updatedAt: "2026-05-25"
+
+sources:
+  - id: serpapi
+    label: SerpAPI Web Search
+    kind: tool
+    readOnly: true
+
+  - id: local-docs
+    label: Local Documentation
+    kind: wiki
+    readOnly: true
+    freshnessTtl: 7d
+    brainEntityId: agent-security
+
+profiles:
+  - id: research-agent
+    name: Research Agent
+    purpose: Web research and summarization
+    guardrails:
+      - Do not make purchases or financial transactions
+      - Do not post to social media
+      - Prefer local documentation before external search
+    routes:
+      - intent: web_research
+        sources: [local-docs, serpapi]
+
+policies:
+  - id: deny-social-posting
+    effect: deny
+    actions: [social_post, social_reply, social_dm]
+    reason: Social media posting is disabled for all agents
+
+  - id: allow-research
+    effect: allow
+    profiles: [research-agent]
+    actions: [web_search, summarize, extract]
+    tools: [serpapi, local-docs]
+    reason: Research agent can search and summarize read-only sources
+```
+
+Shipped examples:
+
+- [examples/basic/control-plane.yaml](examples/basic/control-plane.yaml): one profile, a few sources, simple allow/deny rules.
+- [examples/multi-agent/control-plane.yaml](examples/multi-agent/control-plane.yaml): three profiles with different permissions.
+
+Framework integrations are planned for V2. They are intentionally not shown as shipped examples until they import and wrap real framework APIs.
+
+## Roadmap
+
+The product roadmap lives in [docs/agent-cmdb-roadmap.md](docs/agent-cmdb-roadmap.md). It maps production agent problems to release tiers from reliability hardening through central management and dashboard workflows.
+
+| Release | Status | Scope |
+| --- | --- | --- |
+| V1.0 | Shipped | Policy engine, source routing, CMDB inventory, evidence store, graph, brain, digest |
+| V1.5 | Shipped | npm packaging, dry-run, source freshness, doctor command |
+| V2.0 | Planned | Health monitors, circuit breakers, SLOs, cost tracking, checkpoint/resume |
+| V3.0 | Planned | Isolation, rate limiting, DLP inspection, trust scoring, schedules, webhooks |
+| V4.0 | Planned | REST/MCP API, dashboard, policy versioning, templates, incident response |
+
+## CLI
+
+```bash
+npx agent-cmdb init
+npx agent-cmdb doctor
+npx agent-cmdb preflight --profile research-agent --action web_search --tool serpapi --intent web_research
+npx agent-cmdb preflight --profile research-agent --action web_search --tool serpapi --intent web_research --dry-run
+npx agent-cmdb policy --profile research-agent --action social_post --tool x
+npx agent-cmdb route --profile research-agent --intent web_research
+npx agent-cmdb brain list --brain-dir ./agent-cmdb/brain
+npx agent-cmdb brain search --brain-dir ./agent-cmdb/brain --keyword security
+npx agent-cmdb digest --profile research-agent --brain-dir ./agent-cmdb/brain
+npx agent-cmdb report
+```
+
+Use a specific config file:
+
+```bash
+npx agent-cmdb preflight --config ./examples/multi-agent/control-plane.yaml --profile research-agent --action social_post --tool social-media-tool --intent web_research
+```
+
+## Mental Model
+
+If you know infrastructure operations, you already know Agent CMDB:
+
+| Infrastructure concept | Agent CMDB |
+| --- | --- |
+| Firewall policy | Policy engine |
+| Routing table | Source routing |
+| Log management | Evidence timeline |
+| Config backups | Brain entity files |
+| Automated reports | Daily/weekly digests |
+| Operations runbooks | Decision records |
+| Asset inventory | Entity index |
+
+`preflight()` is the packet filter before the agent executes.
+
+## Framework Modules
+
+```text
+src/types.ts
+src/policy-engine.ts
+src/route-resolver.ts
+src/graph-engine.ts
+src/validator.ts
+src/store.ts
+src/brain.ts
+src/digest.ts
+src/interface.ts
+src/loader.ts
+src/preflight.ts
+src/cli.ts
+```
+
+`src/engine.ts` remains as a compatibility barrel for older imports.
+
+## Design Boundary
+
+Agent CMDB combines policy enforcement with local agent memory. The brain is optional - omit `brainDir` if you only need policy evaluation, source routing, and audit trails.
+
+## Development
+
+```bash
+npm test
+npm run typecheck
+npm run build
+```
+
+Current verification target:
+
+- 153 tests passing
+- strict TypeScript clean
+- clean `dist/` build

package/dist/agent-preflight.d.ts

@@ -0,0 +1,6 @@
+import type { PreflightResult } from './types.js';
+export declare function runAgentPreflight(action: string, profile: string, tool?: string, intent?: string, options?: {
+    configPath?: string;
+    dryRun?: boolean;
+}): Promise<PreflightResult>;
+//# sourceMappingURL=agent-preflight.d.ts.map

package/dist/agent-preflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-preflight.d.ts","sourceRoot":"","sources":["../src/agent-preflight.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACtD,OAAO,CAAC,eAAe,CAAC,CAkD1B"}

package/dist/agent-preflight.js

@@ -0,0 +1,55 @@
+import { createAgentCmdb } from './interface.js';
+import { multiAgentExampleControlPlanePath } from './loader.js';
+export async function runAgentPreflight(action, profile, tool, intent, options = {}) {
+    const normalizedAction = requireNonEmptyString(action, 'Agent preflight action');
+    const normalizedProfile = requireNonEmptyString(profile, 'Agent preflight profile');
+    const normalizedTool = tool === undefined ? undefined : requireNonEmptyString(tool, 'Agent preflight tool');
+    const normalizedIntent = intent === undefined ? undefined : requireNonEmptyString(intent, 'Agent preflight intent');
+    const cmdb = createAgentCmdb({
+        configPath: options.configPath ?? multiAgentExampleControlPlanePath
+    });
+    const result = cmdb.preflight({
+        action: normalizedAction,
+        profile: normalizedProfile,
+        tool: normalizedTool,
+        intent: normalizedIntent,
+        dryRun: options.dryRun
+    });
+    const now = new Date().toISOString();
+    if (result.dryRun) {
+        return result;
+    }
+    if (result.decision.effect === 'deny') {
+        await cmdb.logEvidence({
+            profile: normalizedProfile,
+            source: 'agent-cmdb-preflight',
+            intent: normalizedIntent ?? normalizedAction,
+            summary: `Agent preflight ${result.decision.effect}: ${result.decision.ruleId}. ${result.decision.reason}`,
+            trust: 'high',
+            capturedAt: now,
+            tags: ['agent-preflight', result.decision.effect, result.decision.ruleId]
+        });
+    }
+    await cmdb.logChange({
+        target: result.decision.ruleId,
+        targetType: 'policy',
+        action: 'verify',
+        actor: 'agent-preflight',
+        reason: `Preflight ${result.decision.effect} for ${normalizedProfile}/${normalizedAction}.`,
+        changedAt: now,
+        after: {
+            allowed: result.allowed,
+            approvalRequired: result.approvalRequired,
+            routeExecutable: result.routeExecutable,
+            decision: result.decision
+        }
+    });
+    return result;
+}
+function requireNonEmptyString(value, label) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new Error(`${label} must be a non-empty string.`);
+    }
+    return value;
+}
+//# sourceMappingURL=agent-preflight.js.map

package/dist/agent-preflight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-preflight.js","sourceRoot":"","sources":["../src/agent-preflight.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,iCAAiC,EAAE,MAAM,aAAa,CAAC;AAGhE,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,MAAc,EACd,OAAe,EACf,IAAa,EACb,MAAe,EACf,UAAqD,EAAE;IAEvD,MAAM,gBAAgB,GAAG,qBAAqB,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC;IACjF,MAAM,iBAAiB,GAAG,qBAAqB,CAAC,OAAO,EAAE,yBAAyB,CAAC,CAAC;IACpF,MAAM,cAAc,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,qBAAqB,CAAC,IAAI,EAAE,sBAAsB,CAAC,CAAC;IAC5G,MAAM,gBAAgB,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,qBAAqB,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC;IAEpH,MAAM,IAAI,GAAG,eAAe,CAAC;QAC3B,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,iCAAiC;KACpE,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC;QAC5B,MAAM,EAAE,gBAAgB;QACxB,OAAO,EAAE,iBAAiB;QAC1B,IAAI,EAAE,cAAc;QACpB,MAAM,EAAE,gBAAgB;QACxB,MAAM,EAAE,OAAO,CAAC,MAAM;KACvB,CAAC,CAAC;IACH,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAErC,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAClB,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QACtC,MAAM,IAAI,CAAC,WAAW,CAAC;YACrB,OAAO,EAAE,iBAAiB;YAC1B,MAAM,EAAE,sBAAsB;YAC9B,MAAM,EAAE,gBAAgB,IAAI,gBAAgB;YAC5C,OAAO,EAAE,mBAAmB,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE;YAC1G,KAAK,EAAE,MAAM;YACb,UAAU,EAAE,GAAG;YACf,IAAI,EAAE,CAAC,iBAAiB,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC;SAC1E,CAAC,CAAC;IACL,CAAC;IAED,MAAM,IAAI,CAAC,SAAS,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM;QAC9B,UAAU,EAAE,QAAQ;QACpB,MAAM,EAAE,QAAQ;QAChB,KAAK,EAAE,iBAAiB;QACxB,MAAM,EAAE,aAAa,MAAM,CAAC,QAAQ,CAAC,MAAM,QAAQ,iBAAiB,IAAI,gBAAgB,GAAG;QAC3F,SAAS,EAAE,GAAG;QACd,KAAK,EAAE;YACL,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;YACzC,eAAe,EAAE,MAAM,CAAC,eAAe;YACvC,QAAQ,EAAE,MAAM,CAAC,QAAQ;SAC1B;KACF,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,qBAAqB,CAAC,KAAc,EAAE,KAAa;IAC1D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,8BAA8B,CAAC,CAAC;IAC1D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/brain.d.ts

@@ -0,0 +1,12 @@
+import type { BrainEntity, BrainEntityKind, BrainIndex, BrainReadResult, BrainSearchQuery, BrainWriteInput } from './types.js';
+export declare function initBrainDir(brainDir: string): Promise<void>;
+export declare function readBrainIndex(brainDir: string): Promise<BrainIndex>;
+export declare function writeBrainIndex(brainDir: string, index: BrainIndex): Promise<void>;
+export declare function readEntity(brainDir: string, entityId: string): Promise<BrainReadResult>;
+export declare function createEntity(brainDir: string, storeDir: string, entity: Omit<BrainEntity, 'lastUpdated' | 'lastUpdatedBy'>, content: string, actor: string): Promise<BrainEntity>;
+export declare function writeEntity(brainDir: string, storeDir: string, input: BrainWriteInput): Promise<BrainEntity>;
+export declare function deleteEntity(brainDir: string, storeDir: string, entityId: string, actor: string, reason: string): Promise<void>;
+export declare function searchEntities(brainDir: string, query: BrainSearchQuery): Promise<BrainEntity[]>;
+export declare function listEntities(brainDir: string, kind?: BrainEntityKind): Promise<BrainEntity[]>;
+export declare function entityRelativePath(brainDir: string, absolutePath: string): string;
+//# sourceMappingURL=brain.d.ts.map

package/dist/brain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain.d.ts","sourceRoot":"","sources":["../src/brain.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,WAAW,EACX,eAAe,EACf,UAAU,EACV,eAAe,EACf,gBAAgB,EAChB,eAAe,EAEhB,MAAM,YAAY,CAAC;AAiBpB,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBlE;AAED,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAc1E;AAED,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAOxF;AAED,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAkB7F;AAED,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,aAAa,GAAG,eAAe,CAAC,EAC1D,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,WAAW,CAAC,CA8BtB;AAED,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,WAAW,CAAC,CAyCtB;AAED,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAuBf;AAED,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAkBtG;AAED,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAMnG;AA8MD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAEjF"}