@adhd/agent-engine-compiler 2.1.8 → 2.1.10

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+## 2.1.10 (2026-07-26)
+
+Re-publish fixing 2.1.9's own defects: an unsatisfiable `@adhd/agent-store-tools: ^2.1.9` dependency range (captured during a transient phantom-version-bump window on agent-store-tools that was later reverted — the real max published is 2.1.8) and a missing `README.md` in the published tarball (BUG-BUILD-ASSETS-CACHE-STALE-AFTER-CLEAN-001) — no code changes to this package itself.
+
+## 2.1.9 (2026-07-26)
+
+Re-publish fixing an empty (1-file) tarball at 2.1.8, caused by BUG-BUILD-PUBLISH-DISTMANIFEST-CLOBBERED-001 in the shared `@adhd/nx-build:publish`/`:version` executors (see tools/nx-plugins/build/executors/publish/impl.js and .../version/impl.js) — no code changes to this package itself.
+
+## 2.1.8 (2026-07-26)
+
+This was a version bump only for agent-engine-compiler to align it with other projects, there were no code changes.
+
+## 2.1.7 (2026-07-25)
+
+This was a version bump only for agent-engine-compiler to align it with other projects, there were no code changes.
+
+## 2.1.6 (2026-07-25)
+
+This was a version bump only for agent-engine-compiler to align it with other projects, there were no code changes.
+
+## 2.1.5 (2026-07-24)
+
+This was a version bump only for agent-engine-compiler to align it with other projects, there were no code changes.
+
+## 2.1.4 (2026-07-24)
+
+This was a version bump only for agent-engine-compiler to align it with other projects, there were no code changes.
+
+## 2.1.3 (2026-07-23)
+
+
+### 🚀 Features
+
+- **agent-core-env:** shared registry-DB resolver + DI kills import-time DB-open side effect
+
+
+### ❤️  Thank You
+
+- pseudosky

package/README.md

@@ -0,0 +1,72 @@
+# @adhd/agent-engine-compiler
+
+Compiles agent configurations from the registry into runtime-ready manifests. Resolves component compositions, tool bindings, policy constraints, and model specifications. Part of the agent registry family.
+
+**Status:** Shipped v2.1.2  
+**Platform:** `platform:node` (runs in Node/CLI, not browser)  
+**Consumers:** `@adhd/agent-mcp`, `@adhd/dispatch-cli`
+
+## What it does
+
+- **Body Resolution** — Assembles agent components from the registry composition store into a complete prompt body
+- **Tool Resolution** — Resolves tool aliases and platform-specific bindings (HTTP, MCP, CLI, etc.)
+- **Model Resolution** — Looks up model capabilities and configurations
+- **Policy Constraint Resolution** — Evaluates effective authorization policies
+- **Output Emission** — Compiles agent definitions into YAML frontmatter, JSON objects, or Markdown documents
+- **Database Migrations** — Runs schema setup via `runMigrationsOn(db)`
+
+## Usage
+
+First, resolve the shared registry database path:
+
+```typescript
+import { resolveRegistryDbPath } from '@adhd/agent-core-env';
+import Database from 'better-sqlite3';
+import { runMigrationsOn, compileAgent } from '@adhd/agent-engine-compiler';
+
+const dbPath = resolveRegistryDbPath(); // e.g., ~/.adhd/agent-registry/production/data/registry.db
+const db = new Database(dbPath);
+
+// Run migrations
+await runMigrationsOn(db);
+
+// Compile an agent from the registry
+const compiled = await compileAgent(db, {
+  agentId: 'my-agent',
+  platform: 'mcp', // or 'http', 'cli', 'json'
+  models: modelStore,
+  tools: toolStore,
+  policies: policyStore,
+  composition: compositionStore,
+});
+
+// Emit as YAML or JSON
+const yaml = emitYamlFrontmatter({
+  agentId: compiled.agentId,
+  tools: compiled.tools,
+  modelAlias: compiled.modelAlias,
+  policyConstraints: compiled.policyConstraints,
+});
+```
+
+## Key exports
+
+| Export | Purpose |
+|--------|---------|
+| `resolveBody(db, ...)` | Assemble component composition into prompt body |
+| `resolveTools(db, ...)` | Resolve tools and platform bindings |
+| `resolveModel(db, ...)` | Look up model and capabilities |
+| `resolvePolicyConstraints(db, ...)` | Resolve effective policies |
+| `compileAgent(db, input)` | Complete compilation orchestrator |
+| `emitYamlFrontmatter(input)` | Emit as YAML frontmatter + body |
+| `emitJsonObject(input)` | Emit as JSON (e.g., for REST API) |
+| `runMigrationsOn(db)` | Initialize database schema |
+
+## Architecture
+
+- **Tier**: `engine` (depends on base + core + stores)
+- **Consumption**: Reads from all registry family stores (prompts, tools, policy, provider)
+- **No import-time side effects** — DB path and connection are external (via `agent-core-env`)
+- **Part of agent registry family**: `agent-store-prompts` + `agent-store-tools` + `agent-core-policy` + `agent-core-provider` + `agent-engine-compiler`
+
+See `/entrypoint/agent-mcp/` for the agent MCP server (primary consumer).

package/drizzle/meta/_journal.json

@@ -0,0 +1,5 @@
+{
+  "version": "7",
+  "dialect": "sqlite",
+  "entries": []
+}

package/package.json

@@ -1,49 +1,29 @@
 {
   "name": "@adhd/agent-engine-compiler",
-  "version": "2.1.8",
+  "version": "2.1.10",
   "description": "Registry-family store for agent-compiler: drizzle-backed SQLite tables sharing the one registry database.",
   "type": "module",
   "publishConfig": {
     "access": "public"
   },
-  "files": [
-    "dist",
-    "CHANGELOG.md"
-  ],
   "bin": {
-    "agent-compiler": "./dist/src/cli/compile.js"
+    "agent-compiler": "src/cli/compile.js"
   },
   "exports": {
     ".": {
-      "types": "./dist/src/index.d.ts",
-      "default": "./dist/src/index.js"
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
     }
   },
-  "scripts": {
-    "build": "nx build agent-compiler",
-    "typecheck": "tsc -p tsconfig.lib.json --noEmit",
-    "db:generate": "drizzle-kit generate",
-    "db:migrate": "drizzle-kit migrate"
-  },
   "dependencies": {
     "better-sqlite3": "12.10.0",
     "drizzle-orm": "0.45.2",
-    "@adhd/agent-store-prompts": "^2.1.8",
-    "@adhd/agent-store-tools": "^2.1.9",
-    "@adhd/agent-core-provider": "^2.1.10",
-    "@adhd/agent-core-policy": "^2.1.10",
+    "@adhd/agent-store-prompts": "^2.1.7",
+    "@adhd/agent-store-tools": "^2.1.8",
+    "@adhd/agent-core-provider": "^2.1.9",
+    "@adhd/agent-core-policy": "^2.1.9",
     "@adhd/agent-core-env": "^0.0.8"
   },
-  "devDependencies": {
-    "@types/better-sqlite3": "^7.6.13",
-    "@vitest/coverage-v8": "^1.0.4",
-    "drizzle-kit": "^0.31.10",
-    "tslib": "^2.6.0",
-    "typescript": "^5.5.0",
-    "vite": "~5.0.13",
-    "vite-plugin-dts": "~3.8.3",
-    "vitest": "^1.6.0"
-  },
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -53,7 +33,5 @@
   "homepage": "https://github.com/PseudoSky/adhd/tree/main/packages/agent/agent-engine-compiler#readme",
   "bugs": {
     "url": "https://github.com/PseudoSky/adhd/issues"
-  },
-  "module": "./src/index.js",
-  "main": "./src/index.js"
+  }
 }

package/src/cache/composed-prompt-cache.d.ts

@@ -0,0 +1,60 @@
+import type { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3';
+import type { ComposedPrompt } from '@adhd/agent-store-prompts';
+import type { ComponentVersionMap } from '../resolve/composition.js';
+/**
+ * Compute the combined `context_hash` for the `registry_composed_prompts` cache.
+ *
+ * Decision D (decisions.md): `context_hash = SHA-256(sortedJSON(context) + " " +
+ * sortedJSON(componentVersions) + " " + platform)`.
+ *
+ * The `registryContextHash` (from @adhd/agent-registry) handles sorted-key JSON
+ * canonicalization of the context part.  We apply the same sorted-key approach to
+ * `componentVersions` and append the `platform` string as a third field so that any
+ * of the three inputs changing produces a distinct hash.
+ *
+ * A ` ` (space) field separator is used between parts — plain JSON can never contain
+ * an unescaped space at the top level, so the three blobs cannot collide by
+ * concatenation.
+ *
+ * @param context           - Runtime context key/value map (e.g. `{ticket_type:"security"}`).
+ * @param componentVersions - Resolved component-version map from `resolveComposition`.
+ * @param platform          - Target platform id (e.g. `claude_code`, `claude_api`).
+ * @returns 64-character lowercase hex SHA-256 string.
+ */
+export declare function computeContextHash(context: Record<string, string>, componentVersions: ComponentVersionMap, platform: string): string;
+/**
+ * Look up a `registry_composed_prompts` row by `(agentSlug, platform, context_hash)`.
+ *
+ * The `context_hash` encodes `(context, componentVersions, platform)` per Decision D.
+ * Returns the cached row (with its `id`) on a HIT, or `null` on a MISS.
+ *
+ * A cache hit means `compileAgent` can return the persisted `{id, content}` WITHOUT
+ * re-running the resolve layers (the assembly step is bypassed).  This is the
+ * `[dod.4]` negative-control guarantee: removing this SELECT before assembly causes
+ * a duplicate row on every compile.
+ *
+ * @param db                - Shared Drizzle handle (all four table prefixes).
+ * @param agentSlug         - Agent to look up.
+ * @param platform          - Target platform id.
+ * @param context           - Runtime context key/value map.
+ * @param componentVersions - Resolved component-version map from `resolveComposition`.
+ * @returns The cached `ComposedPrompt` row on a HIT, or `null` on a MISS.
+ */
+export declare function lookup(db: BetterSQLite3Database<any>, agentSlug: string, platform: string, context: Record<string, string>, componentVersions: ComponentVersionMap): ComposedPrompt | null;
+/**
+ * Write a new `registry_composed_prompts` row for `(agentSlug, platform, context_hash)`.
+ *
+ * Called on a cache MISS: after assembly is complete, persists the composed prompt
+ * so subsequent compiles can hit the cache.  Returns the inserted row, including the
+ * generated `id` (the [def:composed-output].id audit/cache handle).
+ *
+ * @param db                - Shared Drizzle handle (all four table prefixes).
+ * @param agentSlug         - Agent the row belongs to.
+ * @param platform          - Target platform id (folded into the hash).
+ * @param context           - Runtime context key/value map used for assembly.
+ * @param componentVersions - Resolved component-version map (audit trail).
+ * @param content           - The assembled platform artifact (markdown, JSON, etc.).
+ * @returns The inserted `ComposedPrompt` row with its generated `id`.
+ */
+export declare function write(db: BetterSQLite3Database<any>, agentSlug: string, platform: string, context: Record<string, string>, componentVersions: ComponentVersionMap, content: string): ComposedPrompt;
+//# sourceMappingURL=composed-prompt-cache.d.ts.map

package/src/cache/composed-prompt-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composed-prompt-cache.d.ts","sourceRoot":"","sources":["../../../src/cache/composed-prompt-cache.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAMxE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAMrE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,iBAAiB,EAAE,mBAAmB,EACtC,QAAQ,EAAE,MAAM,GACf,MAAM,CAiBR;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,MAAM,CAEpB,EAAE,EAAE,qBAAqB,CAAC,GAAG,CAAC,EAC9B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,iBAAiB,EAAE,mBAAmB,GACrC,cAAc,GAAG,IAAI,CAIvB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,KAAK,CAEnB,EAAE,EAAE,qBAAqB,CAAC,GAAG,CAAC,EAC9B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,iBAAiB,EAAE,mBAAmB,EACtC,OAAO,EAAE,MAAM,GACd,cAAc,CAShB"}

package/src/cache/composed-prompt-cache.js

@@ -0,0 +1,120 @@
+// ──────────────────────────────────────────────
+// composed-prompt-cache — cache lookup + write for the composed_prompts table.
+//
+// Implements Decision D (decisions.md [def:context-hash]):
+//   context_hash = SHA-256( sortedJSON(context) + " " + sortedJSON(componentVersions) + " " + platform )
+//
+// The three-part key encodes:
+//   1. The runtime context (any key/value change → different hash → cache miss).
+//   2. The resolved component-version set (an unpinned component advancing to a
+//      new latest → different componentVersions → miss).
+//   3. The target platform (different platform → different content shape → miss).
+//
+// The "context part" reuses @adhd/agent-registry's exported `contextHash` helper
+// for consistent sorted-key JSON canonicalization — do NOT reimplement
+// ([ref:store-read], decisions.md Decision D note).
+//
+// The composed_prompts table comes from @adhd/agent-registry (plan 1,
+// `registry_composed_prompts`).  We use the existing table via the shared DB
+// handle passed by `compileAgent` ([inv:one-db-handle]).  No duplicate table
+// is created here.
+//
+// [def:context-hash]    — the combined cache key algorithm (decisions.md Decision D)
+// [inv:one-db-handle]   — shared Drizzle handle, all four table prefixes
+// [inv:reopen-proves-cache] — persistence proven by CLOSE+REOPEN (test invariant)
+// ──────────────────────────────────────────────
+import { createHash } from 'node:crypto';
+import { ComposedPromptStore, contextHash as registryContextHash, } from '@adhd/agent-store-prompts';
+// ──────────────────────────────────────────────
+// Combined cache-key hash
+// ──────────────────────────────────────────────
+/**
+ * Compute the combined `context_hash` for the `registry_composed_prompts` cache.
+ *
+ * Decision D (decisions.md): `context_hash = SHA-256(sortedJSON(context) + " " +
+ * sortedJSON(componentVersions) + " " + platform)`.
+ *
+ * The `registryContextHash` (from @adhd/agent-registry) handles sorted-key JSON
+ * canonicalization of the context part.  We apply the same sorted-key approach to
+ * `componentVersions` and append the `platform` string as a third field so that any
+ * of the three inputs changing produces a distinct hash.
+ *
+ * A ` ` (space) field separator is used between parts — plain JSON can never contain
+ * an unescaped space at the top level, so the three blobs cannot collide by
+ * concatenation.
+ *
+ * @param context           - Runtime context key/value map (e.g. `{ticket_type:"security"}`).
+ * @param componentVersions - Resolved component-version map from `resolveComposition`.
+ * @param platform          - Target platform id (e.g. `claude_code`, `claude_api`).
+ * @returns 64-character lowercase hex SHA-256 string.
+ */
+export function computeContextHash(context, componentVersions, platform) {
+    // Part 1: sorted-key JSON of context (reuse the upstream helper for parity).
+    const contextPart = registryContextHash(context);
+    // Part 2: sorted-key JSON of componentVersions (apply the same canonicalization).
+    const sortedVersions = Object.fromEntries(Object.keys(componentVersions)
+        .sort()
+        .map((k) => [k, componentVersions[k]]));
+    const versionPart = JSON.stringify(sortedVersions);
+    // Combined: context_hash(context) + " " + sortedJSON(componentVersions) + " " + platform
+    // Field separator is a bare space — JSON strings never contain unescaped spaces
+    // at the outermost level, so the three segments cannot collide.
+    const combined = `${contextPart} ${versionPart} ${platform}`;
+    return createHash('sha256').update(combined, 'utf8').digest('hex');
+}
+// ──────────────────────────────────────────────
+// Cache operations
+// ──────────────────────────────────────────────
+/**
+ * Look up a `registry_composed_prompts` row by `(agentSlug, platform, context_hash)`.
+ *
+ * The `context_hash` encodes `(context, componentVersions, platform)` per Decision D.
+ * Returns the cached row (with its `id`) on a HIT, or `null` on a MISS.
+ *
+ * A cache hit means `compileAgent` can return the persisted `{id, content}` WITHOUT
+ * re-running the resolve layers (the assembly step is bypassed).  This is the
+ * `[dod.4]` negative-control guarantee: removing this SELECT before assembly causes
+ * a duplicate row on every compile.
+ *
+ * @param db                - Shared Drizzle handle (all four table prefixes).
+ * @param agentSlug         - Agent to look up.
+ * @param platform          - Target platform id.
+ * @param context           - Runtime context key/value map.
+ * @param componentVersions - Resolved component-version map from `resolveComposition`.
+ * @returns The cached `ComposedPrompt` row on a HIT, or `null` on a MISS.
+ */
+export function lookup(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+db, agentSlug, platform, context, componentVersions) {
+    const hash = computeContextHash(context, componentVersions, platform);
+    const store = new ComposedPromptStore(db);
+    return store.lookup(agentSlug, hash);
+}
+/**
+ * Write a new `registry_composed_prompts` row for `(agentSlug, platform, context_hash)`.
+ *
+ * Called on a cache MISS: after assembly is complete, persists the composed prompt
+ * so subsequent compiles can hit the cache.  Returns the inserted row, including the
+ * generated `id` (the [def:composed-output].id audit/cache handle).
+ *
+ * @param db                - Shared Drizzle handle (all four table prefixes).
+ * @param agentSlug         - Agent the row belongs to.
+ * @param platform          - Target platform id (folded into the hash).
+ * @param context           - Runtime context key/value map used for assembly.
+ * @param componentVersions - Resolved component-version map (audit trail).
+ * @param content           - The assembled platform artifact (markdown, JSON, etc.).
+ * @returns The inserted `ComposedPrompt` row with its generated `id`.
+ */
+export function write(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+db, agentSlug, platform, context, componentVersions, content) {
+    const hash = computeContextHash(context, componentVersions, platform);
+    const store = new ComposedPromptStore(db);
+    return store.write({
+        agentSlug,
+        contextHash: hash,
+        content,
+        componentVersions,
+    });
+}
+//# sourceMappingURL=composed-prompt-cache.js.map

package/src/cache/composed-prompt-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"composed-prompt-cache.js","sourceRoot":"","sources":["../../../src/cache/composed-prompt-cache.ts"],"names":[],"mappings":"AAAA,iDAAiD;AACjD,+EAA+E;AAC/E,EAAE;AACF,2DAA2D;AAC3D,yGAAyG;AACzG,EAAE;AACF,8BAA8B;AAC9B,iFAAiF;AACjF,gFAAgF;AAChF,yDAAyD;AACzD,kFAAkF;AAClF,EAAE;AACF,iFAAiF;AACjF,uEAAuE;AACvE,oDAAoD;AACpD,EAAE;AACF,sEAAsE;AACtE,6EAA6E;AAC7E,6EAA6E;AAC7E,mBAAmB;AACnB,EAAE;AACF,qFAAqF;AACrF,yEAAyE;AACzE,kFAAkF;AAClF,iDAAiD;AAEjD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAIzC,OAAO,EACL,mBAAmB,EACnB,WAAW,IAAI,mBAAmB,GACnC,MAAM,2BAA2B,CAAC;AAInC,iDAAiD;AACjD,0BAA0B;AAC1B,iDAAiD;AAEjD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAA+B,EAC/B,iBAAsC,EACtC,QAAgB;IAEhB,6EAA6E;IAC7E,MAAM,WAAW,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAEjD,kFAAkF;IAClF,MAAM,cAAc,GAAG,MAAM,CAAC,WAAW,CACvC,MAAM,CAAC,IAAI,CAAC,iBAAiB,CAAC;SAC3B,IAAI,EAAE;SACN,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAU,CAAC,CAClD,CAAC;IACF,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC;IAEnD,yFAAyF;IACzF,gFAAgF;IAChF,gEAAgE;IAChE,MAAM,QAAQ,GAAG,GAAG,WAAW,IAAI,WAAW,IAAI,QAAQ,EAAE,CAAC;IAC7D,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACrE,CAAC;AAED,iDAAiD;AACjD,mBAAmB;AACnB,iDAAiD;AAEjD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,MAAM;AACpB,8DAA8D;AAC9D,EAA8B,EAC9B,SAAiB,EACjB,QAAgB,EAChB,OAA+B,EAC/B,iBAAsC;IAEtC,MAAM,IAAI,GAAG,kBAAkB,CAAC,OAAO,EAAE,iBAAiB,EAAE,QAAQ,CAAC,CAAC;IACtE,MAAM,KAAK,GAAG,IAAI,mBAAmB,CAAC,EAAE,CAAC,CAAC;IAC1C,OAAO,KAAK,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,KAAK;AACnB,8DAA8D;AAC9D,EAA8B,EAC9B,SAAiB,EACjB,QAAgB,EAChB,OAA+B,EAC/B,iBAAsC,EACtC,OAAe;IAEf,MAAM,IAAI,GAAG,kBAAkB,CAAC,OAAO,EAAE,iBAAiB,EAAE,QAAQ,CAAC,CAAC;IACtE,MAAM,KAAK,GAAG,IAAI,mBAAmB,CAAC,EAAE,CAAC,CAAC;IAC1C,OAAO,KAAK,CAAC,KAAK,CAAC;QACjB,SAAS;QACT,WAAW,EAAE,IAAI;QACjB,OAAO;QACP,iBAAiB;KAClB,CAAC,CAAC;AACL,CAAC"}

package/src/cli/compile.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=compile.d.ts.map

package/src/cli/compile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../../src/cli/compile.ts"],"names":[],"mappings":""}