@keel_flow/pack-agent-topology 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jglasskatz
+
+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,15 @@
+# @keel_flow/pack-agent-topology
+
+Agent and tool architecture principles for Keel multi-agent systems: seven opinionated principles covering single-source-of-truth per tool, bounded-context ownership, agent isolation, and tool call determinism — each with a machine-checkable `check` function that plugs into `keel verify`.
+
+Part of the [Keel](https://github.com/jglasskatz/keel) framework.
+
+## Install
+
+```
+npm install @keel_flow/pack-agent-topology
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import type { PrincipleWithCheck, PrinciplePack } from "@keel_flow/schema";
+export declare const agentTopologyPrinciples: PrincipleWithCheck[];
+export declare const agentTopologyPack: PrinciplePack;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,aAAa,EAAa,MAAM,mBAAmB,CAAC;AAGtF,eAAO,MAAM,uBAAuB,EAAE,kBAAkB,EA8GvD,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,aAK/B,CAAC"}

package/dist/index.js

@@ -0,0 +1,124 @@
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { isTemplateFile } from "@keel_flow/pack-general-se/scope-filters";
+export const agentTopologyPrinciples = [
+    {
+        id: "single-source-of-truth-per-tool",
+        description: "Each tool reads/writes through exactly one data path",
+        rationale: "Multiple paths create state drift; tool answers diverge from reality when a second path exists",
+        severity: "critical",
+    },
+    {
+        id: "no-cross-agent-state-mutation",
+        description: "Agents must not mutate state owned by another agent",
+        rationale: "Cross-agent mutation couples agents implicitly; the coupling manifests as unreproducible bugs",
+        severity: "critical",
+    },
+    {
+        id: "explicit-handoff-contracts",
+        description: "Agent-to-agent handoffs are typed; the receiving agent validates the payload at its boundary",
+        rationale: "Untyped handoffs are the primary source of cascading failures in multi-agent systems",
+        severity: "critical",
+    },
+    {
+        id: "tool-schemas-are-load-bearing",
+        description: "Tool input and output schemas are the source of truth for what a tool does",
+        rationale: "Prose descriptions drift; schemas are machine-checked and therefore always accurate",
+        severity: "critical",
+        check({ diff, cwd }) {
+            // Honor the verify cwd so file reads resolve against the target project
+            // rather than the runner's working directory.
+            const root = cwd ?? process.cwd();
+            const violations = [];
+            for (const file of diff.files) {
+                if (!file.path.includes("/tools/") && !file.path.includes("tool.ts"))
+                    continue;
+                if (file.status === "removed")
+                    continue;
+                if (file.path.endsWith(".test.ts"))
+                    continue;
+                if (isTemplateFile(file.path))
+                    continue;
+                const absPath = join(root, file.path);
+                if (!existsSync(absPath))
+                    continue;
+                try {
+                    const content = readFileSync(absPath, "utf-8");
+                    const hasZod = content.includes("inputSchema") || content.includes("z.object");
+                    const hasTypeBox = content.includes("Type.Object") || /parameters\s*:/.test(content);
+                    if (!hasZod && !hasTypeBox) {
+                        violations.push({
+                            principleId: "tool-schemas-are-load-bearing",
+                            file: file.path,
+                            severity: "critical",
+                            message: `Tool file "${file.path}" appears to define a tool without a typed parameter schema (Zod inputSchema or TypeBox Type.Object). Every tool must have a typed schema.`,
+                        });
+                    }
+                }
+                catch {
+                    // File unreadable; skip
+                }
+            }
+            return violations;
+        },
+    },
+    {
+        id: "one-agent-one-bounded-context",
+        description: "Each agent is assigned to exactly one bounded context in the architecture map",
+        rationale: "An agent crossing contexts is an agent without a clear owner, and an architecture without clear seams",
+        severity: "warning",
+    },
+    {
+        id: "tool-failures-are-typed",
+        description: "Every tool must return a typed error variant on failure; tools must not throw unstructured exceptions",
+        rationale: "Unstructured exceptions escape the type system and force callers to catch and inspect unknown shapes; typed errors allow exhaustive handling",
+        severity: "critical",
+        check({ diff, cwd }) {
+            // Honor the verify cwd so file reads resolve against the target project
+            // rather than the runner's working directory.
+            const root = cwd ?? process.cwd();
+            const violations = [];
+            for (const file of diff.files) {
+                if (!file.path.includes("/tools/") && !file.path.includes("tool.ts"))
+                    continue;
+                if (file.status === "removed")
+                    continue;
+                if (file.path.endsWith(".test.ts"))
+                    continue;
+                if (isTemplateFile(file.path))
+                    continue;
+                const absPath = join(root, file.path);
+                if (!existsSync(absPath))
+                    continue;
+                try {
+                    const content = readFileSync(absPath, "utf-8");
+                    if (content.includes("throw new Error") && !content.match(/error[Tt]ype|ErrorType|ToolError|ResultError|errorKind/)) {
+                        violations.push({
+                            principleId: "tool-failures-are-typed",
+                            file: file.path,
+                            severity: "critical",
+                            message: `Tool file "${file.path}" throws unstructured errors. Return a typed error variant instead.`,
+                        });
+                    }
+                }
+                catch {
+                    // File unreadable; skip
+                }
+            }
+            return violations;
+        },
+    },
+    {
+        id: "kb-retrieval-before-creativity",
+        description: "An agent with KB access must retrieve relevant context before generating a response; it must not speculate first",
+        rationale: "Generating before retrieving produces responses anchored to training priors rather than workspace reality; retrieval-first grounds the agent",
+        severity: "critical",
+    },
+];
+export const agentTopologyPack = {
+    id: "@keel_flow/pack-agent-topology",
+    version: "0.1.0",
+    description: "Agent and tool architecture principles for Keel multi-agent systems.",
+    principles: agentTopologyPrinciples,
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@keel_flow/pack-agent-topology",
+  "version": "0.2.0",
+  "private": false,
+  "type": "module",
+  "description": "Agent and tool architecture principles for Keel multi-agent systems",
+  "keywords": [
+    "keel",
+    "principles",
+    "agents",
+    "tools"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "@keel_flow/schema": "0.2.0",
+    "@keel_flow/pack-general-se": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": "^9.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint src"
+  }
+}