@bevel-software/platform-core-backend 0.1.0

package/dist/shared/token-crypto.d.ts

@@ -0,0 +1,16 @@
+/**
+ * AES-256-GCM encryption for at-rest secrets. Output format is
+ * `<ivB64>:<tagB64>:<ciphertextB64>` so all three parts travel together in one
+ * text column. A DB leak alone yields only ciphertext; the key lives in the
+ * app's env, not the database. Shared primitive with several consumers, each
+ * bringing its own key: the secrets vault + MCP OAuth store (core), and the
+ * SharePoint token cache / connector configs (enterprise).
+ */
+export declare class TokenCrypto {
+    private readonly key;
+    /** @param rawKey 32-byte key as hex (64 chars) or base64. */
+    constructor(rawKey: string);
+    encrypt(plaintext: string): string;
+    decrypt(blob: string): string;
+}
+//# sourceMappingURL=token-crypto.d.ts.map

package/dist/shared/token-crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-crypto.d.ts","sourceRoot":"","sources":["../../src/shared/token-crypto.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAE7B,6DAA6D;gBACjD,MAAM,EAAE,MAAM;IAW1B,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAQlC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;CAa9B"}

package/dist/shared/token-crypto.js

@@ -0,0 +1,49 @@
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+/**
+ * AES-256-GCM encryption for at-rest secrets. Output format is
+ * `<ivB64>:<tagB64>:<ciphertextB64>` so all three parts travel together in one
+ * text column. A DB leak alone yields only ciphertext; the key lives in the
+ * app's env, not the database. Shared primitive with several consumers, each
+ * bringing its own key: the secrets vault + MCP OAuth store (core), and the
+ * SharePoint token cache / connector configs (enterprise).
+ */
+export class TokenCrypto {
+    key;
+    /** @param rawKey 32-byte key as hex (64 chars) or base64. */
+    constructor(rawKey) {
+        const key = decodeKey(rawKey);
+        if (key.length !== 32) {
+            throw new Error(`SHAREPOINT_TOKEN_ENC_KEY must decode to 32 bytes (got ${key.length}). ` +
+                'Generate one with: `node -e "console.log(require(\'crypto\').randomBytes(32).toString(\'base64\'))"`.');
+        }
+        this.key = key;
+    }
+    encrypt(plaintext) {
+        const iv = randomBytes(12);
+        const cipher = createCipheriv('aes-256-gcm', this.key, iv);
+        const ct = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+        const tag = cipher.getAuthTag();
+        return `${iv.toString('base64')}:${tag.toString('base64')}:${ct.toString('base64')}`;
+    }
+    decrypt(blob) {
+        const parts = blob.split(':');
+        if (parts.length !== 3) {
+            throw new Error('TokenCrypto.decrypt: malformed ciphertext blob (expected iv:tag:ct)');
+        }
+        const [ivB64, tagB64, ctB64] = parts;
+        if (!ivB64 || !tagB64 || !ctB64) {
+            throw new Error('TokenCrypto.decrypt: malformed ciphertext blob');
+        }
+        const decipher = createDecipheriv('aes-256-gcm', this.key, Buffer.from(ivB64, 'base64'));
+        decipher.setAuthTag(Buffer.from(tagB64, 'base64'));
+        return Buffer.concat([decipher.update(Buffer.from(ctB64, 'base64')), decipher.final()]).toString('utf8');
+    }
+}
+function decodeKey(raw) {
+    // Accept hex (64 chars, hex alphabet) or base64. Hex first to avoid a 64-char
+    // hex string being misread as base64.
+    if (/^[0-9a-fA-F]{64}$/.test(raw))
+        return Buffer.from(raw, 'hex');
+    return Buffer.from(raw, 'base64');
+}
+//# sourceMappingURL=token-crypto.js.map

package/dist/shared/token-crypto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-crypto.js","sourceRoot":"","sources":["../../src/shared/token-crypto.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE5E;;;;;;;GAOG;AACH,MAAM,OAAO,WAAW;IACL,GAAG,CAAS;IAE7B,6DAA6D;IAC7D,YAAY,MAAc;QACxB,MAAM,GAAG,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;QAC9B,IAAI,GAAG,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CACb,yDAAyD,GAAG,CAAC,MAAM,KAAK;gBACtE,uGAAuG,CAC1G,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACjB,CAAC;IAED,OAAO,CAAC,SAAiB;QACvB,MAAM,EAAE,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;QAC3B,MAAM,MAAM,GAAG,cAAc,CAAC,aAAa,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QAC3D,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QAC7E,MAAM,GAAG,GAAG,MAAM,CAAC,UAAU,EAAE,CAAC;QAChC,OAAO,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;IACvF,CAAC;IAED,OAAO,CAAC,IAAY;QAClB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,qEAAqE,CAAC,CAAC;QACzF,CAAC;QACD,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,GAAG,KAAK,CAAC;QACrC,IAAI,CAAC,KAAK,IAAI,CAAC,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;YAChC,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;QACpE,CAAC;QACD,MAAM,QAAQ,GAAG,gBAAgB,CAAC,aAAa,EAAE,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC;QACzF,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;QACnD,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC3G,CAAC;CACF;AAED,SAAS,SAAS,CAAC,GAAW;IAC5B,8EAA8E;IAC9E,sCAAsC;IACtC,IAAI,mBAAmB,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAClE,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;AACpC,CAAC"}

package/dist/shared/ttl-cache.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The ONE tiny TTL cache for single-value catalog caches (tool manuals, skills):
+ * hold a value for `ttlMs`, drop it on `invalidate()`. Caches that need more
+ * (per-key entries, single-flight, generation guards — kb-graph, access-control)
+ * deliberately keep their own.
+ */
+export declare class TtlCache<T> {
+    private readonly ttlMs;
+    private readonly now;
+    private entry;
+    constructor(ttlMs: number, now?: () => number);
+    get(): T | null;
+    set(value: T): void;
+    invalidate(): void;
+}
+//# sourceMappingURL=ttl-cache.d.ts.map

package/dist/shared/ttl-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ttl-cache.d.ts","sourceRoot":"","sources":["../../src/shared/ttl-cache.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,qBAAa,QAAQ,CAAC,CAAC;IAInB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAJtB,OAAO,CAAC,KAAK,CAAyC;gBAGnC,KAAK,EAAE,MAAM,EACb,GAAG,GAAE,MAAM,MAAiB;IAG/C,GAAG,IAAI,CAAC,GAAG,IAAI;IAKf,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;IAInB,UAAU,IAAI,IAAI;CAGnB"}

package/dist/shared/ttl-cache.js

@@ -0,0 +1,27 @@
+/**
+ * The ONE tiny TTL cache for single-value catalog caches (tool manuals, skills):
+ * hold a value for `ttlMs`, drop it on `invalidate()`. Caches that need more
+ * (per-key entries, single-flight, generation guards — kb-graph, access-control)
+ * deliberately keep their own.
+ */
+export class TtlCache {
+    ttlMs;
+    now;
+    entry = null;
+    constructor(ttlMs, now = Date.now) {
+        this.ttlMs = ttlMs;
+        this.now = now;
+    }
+    get() {
+        if (this.entry && this.now() - this.entry.at < this.ttlMs)
+            return this.entry.value;
+        return null;
+    }
+    set(value) {
+        this.entry = { at: this.now(), value };
+    }
+    invalidate() {
+        this.entry = null;
+    }
+}
+//# sourceMappingURL=ttl-cache.js.map

package/dist/shared/ttl-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ttl-cache.js","sourceRoot":"","sources":["../../src/shared/ttl-cache.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,OAAO,QAAQ;IAIA;IACA;IAJX,KAAK,GAAoC,IAAI,CAAC;IAEtD,YACmB,KAAa,EACb,MAAoB,IAAI,CAAC,GAAG;QAD5B,UAAK,GAAL,KAAK,CAAQ;QACb,QAAG,GAAH,GAAG,CAAyB;IAC5C,CAAC;IAEJ,GAAG;QACD,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;QACnF,OAAO,IAAI,CAAC;IACd,CAAC;IAED,GAAG,CAAC,KAAQ;QACV,IAAI,CAAC,KAAK,GAAG,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,CAAC;IACzC,CAAC;IAED,UAAU;QACR,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;CACF"}

package/dist/shared/utcp-namespace.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The key UTCP uses to look up a manual's `${VAR}`. `@utcp/sdk` first SANITIZES
+ * the manual name — every non-word char (`-`, `.`, spaces, …) becomes `_`
+ * (`manualCallTemplate.name.replace(/[^\w]/g, "_")` at registration) — and then
+ * namespaces variables under `<namespace>_<VAR>` where every `_` in the
+ * sanitized namespace is DOUBLED (the variable substitutor), so `my_tool` + `KEY`
+ * → `my__tool_KEY` and `my-tool` + `KEY` → the very same `my__tool_KEY`. Our
+ * secret storage AND scope resolution must derive the exact same key. For an
+ * alphanumeric name (no `_`, no punctuation) this reduces to `<name>_<VAR>`,
+ * so plain tool names are unaffected.
+ */
+export declare function utcpNamespacePrefix(manualName: string): string;
+export declare function utcpNamespacedKey(manualName: string, varName: string): string;
+/**
+ * The synthetic per-user variable MCP OAuth auto-discovery hangs a remote
+ * server's sign-in on (`<manual>_MCP_OAUTH`). Lives here — the one leaf both
+ * sides import — so the tool-manuals decoration and the secrets-vault
+ * discovery service can't drift apart on the name.
+ */
+export declare const MCP_OAUTH_VAR = "MCP_OAUTH";
+/**
+ * The internal ("Bevel") UTCP manual namespace — the ONE manual the in-process
+ * agent's code-mode client fully trusts (it carries the loopback `API_URL` and
+ * the `source:'internal'` token). Single source of truth so the composition root
+ * that seeds it and the tool-manuals scanner that must REFUSE a user `.tool` from
+ * reproducing it (which would let the `.tool` read the seeded internal token +
+ * connector creds under the shared namespace) can't drift.
+ */
+export declare const INTERNAL_MANUAL_NAME = "Bevel";
+/**
+ * Seed the loopback discovery vars (`<ns>_API_URL` + `<ns>_CONNECTION_KEY`) for
+ * every Bevel-HOSTED manual in `manuals` — one whose discovery `url` targets our
+ * own backend with `${API_URL}` as its ORIGIN (the KB manual and inline `.tool`
+ * sub-manuals). A third-party http/mcp `.tool` points at an arbitrary URL, so it
+ * is deliberately NOT seeded: handing it `connectionKey` would leak the bearer to
+ * that endpoint. Keying off the origin (not a bare `includes('${API_URL}')`) is
+ * deliberate — an `http` `.tool`'s URL is author-controlled, so a substring match
+ * would let `http://attacker/?x=${API_URL}` be seeded the bearer and exfiltrate
+ * it. This is the exfiltration-safe seeding rule shared by the external MCP proxy
+ * and the in-process agent factory, so the bearer-leak decision is written ONCE.
+ */
+export declare function seedBevelHostedManualVars(manuals: readonly {
+    name?: unknown;
+    url?: unknown;
+}[], loopbackBaseUrl: string, connectionKey: string): Record<string, string>;
+//# sourceMappingURL=utcp-namespace.d.ts.map

package/dist/shared/utcp-namespace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utcp-namespace.d.ts","sourceRoot":"","sources":["../../src/shared/utcp-namespace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE7E;AAED;;;;;GAKG;AACH,eAAO,MAAM,aAAa,cAAc,CAAC;AAEzC;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,UAAU,CAAC;AAyB5C;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,SAAS;IAAE,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,OAAO,CAAA;CAAE,EAAE,EACrD,eAAe,EAAE,MAAM,EACvB,aAAa,EAAE,MAAM,GACpB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAWxB"}

package/dist/shared/utcp-namespace.js

@@ -0,0 +1,82 @@
+/**
+ * The key UTCP uses to look up a manual's `${VAR}`. `@utcp/sdk` first SANITIZES
+ * the manual name — every non-word char (`-`, `.`, spaces, …) becomes `_`
+ * (`manualCallTemplate.name.replace(/[^\w]/g, "_")` at registration) — and then
+ * namespaces variables under `<namespace>_<VAR>` where every `_` in the
+ * sanitized namespace is DOUBLED (the variable substitutor), so `my_tool` + `KEY`
+ * → `my__tool_KEY` and `my-tool` + `KEY` → the very same `my__tool_KEY`. Our
+ * secret storage AND scope resolution must derive the exact same key. For an
+ * alphanumeric name (no `_`, no punctuation) this reduces to `<name>_<VAR>`,
+ * so plain tool names are unaffected.
+ */
+export function utcpNamespacePrefix(manualName) {
+    return `${manualName.replace(/[^\w]/g, '_').replace(/_/g, '__')}_`;
+}
+export function utcpNamespacedKey(manualName, varName) {
+    return `${utcpNamespacePrefix(manualName)}${varName}`;
+}
+/**
+ * The synthetic per-user variable MCP OAuth auto-discovery hangs a remote
+ * server's sign-in on (`<manual>_MCP_OAUTH`). Lives here — the one leaf both
+ * sides import — so the tool-manuals decoration and the secrets-vault
+ * discovery service can't drift apart on the name.
+ */
+export const MCP_OAUTH_VAR = 'MCP_OAUTH';
+/**
+ * The internal ("Bevel") UTCP manual namespace — the ONE manual the in-process
+ * agent's code-mode client fully trusts (it carries the loopback `API_URL` and
+ * the `source:'internal'` token). Single source of truth so the composition root
+ * that seeds it and the tool-manuals scanner that must REFUSE a user `.tool` from
+ * reproducing it (which would let the `.tool` read the seeded internal token +
+ * connector creds under the shared namespace) can't drift.
+ */
+export const INTERNAL_MANUAL_NAME = 'Bevel';
+/**
+ * The origin template WE mint for every Bevel-hosted manual's discovery URL
+ * (`${API_URL}/api/…`). `${API_URL}` expands to the loopback origin, so a
+ * Bevel-hosted URL always has this exact string as its scheme+authority.
+ */
+const LOOPBACK_ORIGIN_TEMPLATE = '${API_URL}';
+/**
+ * True only when `${API_URL}` is the URL's ORIGIN (scheme+authority) — the shape
+ * we ourselves produce for a Bevel-hosted manual. A third-party `.tool` author
+ * can embed the literal `${API_URL}` anywhere in a path or query
+ * (`http://evil.example/?x=${API_URL}`) but can NOT make it the authority without
+ * pointing the request back at our own loopback, so anchoring the trust decision
+ * to the origin is what a user `.tool`'s URL text cannot forge.
+ */
+function isBevelHostedUrl(url) {
+    if (!url.startsWith(LOOPBACK_ORIGIN_TEMPLATE))
+        return false;
+    // The char right after the origin must delimit the authority; anything else
+    // (`${API_URL}.evil.com`, `${API_URL}evil`) is a different, untrusted host.
+    const next = url.charAt(LOOPBACK_ORIGIN_TEMPLATE.length);
+    return next === '' || next === '/' || next === '?' || next === '#';
+}
+/**
+ * Seed the loopback discovery vars (`<ns>_API_URL` + `<ns>_CONNECTION_KEY`) for
+ * every Bevel-HOSTED manual in `manuals` — one whose discovery `url` targets our
+ * own backend with `${API_URL}` as its ORIGIN (the KB manual and inline `.tool`
+ * sub-manuals). A third-party http/mcp `.tool` points at an arbitrary URL, so it
+ * is deliberately NOT seeded: handing it `connectionKey` would leak the bearer to
+ * that endpoint. Keying off the origin (not a bare `includes('${API_URL}')`) is
+ * deliberate — an `http` `.tool`'s URL is author-controlled, so a substring match
+ * would let `http://attacker/?x=${API_URL}` be seeded the bearer and exfiltrate
+ * it. This is the exfiltration-safe seeding rule shared by the external MCP proxy
+ * and the in-process agent factory, so the bearer-leak decision is written ONCE.
+ */
+export function seedBevelHostedManualVars(manuals, loopbackBaseUrl, connectionKey) {
+    const variables = {};
+    for (const m of manuals) {
+        const name = typeof m.name === 'string' ? m.name : '';
+        if (!name)
+            continue;
+        const url = m.url;
+        if (typeof url !== 'string' || !isBevelHostedUrl(url))
+            continue;
+        variables[utcpNamespacedKey(name, 'API_URL')] = loopbackBaseUrl;
+        variables[utcpNamespacedKey(name, 'CONNECTION_KEY')] = connectionKey;
+    }
+    return variables;
+}
+//# sourceMappingURL=utcp-namespace.js.map

package/dist/shared/utcp-namespace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utcp-namespace.js","sourceRoot":"","sources":["../../src/shared/utcp-namespace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CAAC,UAAkB;IACpD,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC;AACrE,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,UAAkB,EAAE,OAAe;IACnE,OAAO,GAAG,mBAAmB,CAAC,UAAU,CAAC,GAAG,OAAO,EAAE,CAAC;AACxD,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,WAAW,CAAC;AAEzC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,OAAO,CAAC;AAE5C;;;;GAIG;AACH,MAAM,wBAAwB,GAAG,YAAY,CAAC;AAE9C;;;;;;;GAOG;AACH,SAAS,gBAAgB,CAAC,GAAW;IACnC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,wBAAwB,CAAC;QAAE,OAAO,KAAK,CAAC;IAC5D,4EAA4E;IAC5E,4EAA4E;IAC5E,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,wBAAwB,CAAC,MAAM,CAAC,CAAC;IACzD,OAAO,IAAI,KAAK,EAAE,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,GAAG,CAAC;AACrE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,yBAAyB,CACvC,OAAqD,EACrD,eAAuB,EACvB,aAAqB;IAErB,MAAM,SAAS,GAA2B,EAAE,CAAC;IAC7C,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QACtD,IAAI,CAAC,IAAI;YAAE,SAAS;QACpB,MAAM,GAAG,GAAI,CAAuB,CAAC,GAAG,CAAC;QACzC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC;YAAE,SAAS;QAChE,SAAS,CAAC,iBAAiB,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,GAAG,eAAe,CAAC;QAChE,SAAS,CAAC,iBAAiB,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC,GAAG,aAAa,CAAC;IACvE,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/version.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The git commit the running build was produced from, surfaced by
+ * `GET /api/health` so the deploy pipeline can confirm a staging/production
+ * rollout by sha *before* smoke-testing it.
+ *
+ * Sources, in priority order:
+ *  - `GIT_SHA` — baked at image build time via the Dockerfile `ARG`/`ENV`
+ *    (set from `git rev-parse HEAD` by CI or `docker compose build`).
+ *  - `SOURCE_COMMIT` — Coolify injects this for git-based deploys, so the
+ *    sha is correct on hosted deploys even when no explicit build arg was
+ *    passed. `.git` is in `.dockerignore`, so the sha can't be derived
+ *    inside the build — it has to be passed in.
+ *  - `'unknown'` — local `tsx` runs and any build that wired neither.
+ */
+export declare function resolveGitSha(env?: NodeJS.ProcessEnv): string;
+export declare const GIT_SHA: string;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAE1E;AAED,eAAO,MAAM,OAAO,QAAkB,CAAC"}

package/dist/version.js

@@ -0,0 +1,19 @@
+/**
+ * The git commit the running build was produced from, surfaced by
+ * `GET /api/health` so the deploy pipeline can confirm a staging/production
+ * rollout by sha *before* smoke-testing it.
+ *
+ * Sources, in priority order:
+ *  - `GIT_SHA` — baked at image build time via the Dockerfile `ARG`/`ENV`
+ *    (set from `git rev-parse HEAD` by CI or `docker compose build`).
+ *  - `SOURCE_COMMIT` — Coolify injects this for git-based deploys, so the
+ *    sha is correct on hosted deploys even when no explicit build arg was
+ *    passed. `.git` is in `.dockerignore`, so the sha can't be derived
+ *    inside the build — it has to be passed in.
+ *  - `'unknown'` — local `tsx` runs and any build that wired neither.
+ */
+export function resolveGitSha(env = process.env) {
+    return (env.GIT_SHA || env.SOURCE_COMMIT || '').trim() || 'unknown';
+}
+export const GIT_SHA = resolveGitSha();
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,aAAa,CAAC,MAAyB,OAAO,CAAC,GAAG;IAChE,OAAO,CAAC,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,SAAS,CAAC;AACtE,CAAC;AAED,MAAM,CAAC,MAAM,OAAO,GAAG,aAAa,EAAE,CAAC"}

package/kb-template/.bevelignore

@@ -0,0 +1,21 @@
+# Entries listed here are hidden from the Bevel file tree / agent view.
+# Syntax is the same as .gitignore — patterns are matched relative to this file.
+
+# Git internals — never surface these in the UI or to the agent.
+.git/
+
+# Tooling / CI configuration that isn't user-editable knowledge.
+.github/
+.claude/
+
+# Repo hygiene files that clutter the tree without being node content.
+.gitignore
+.gitattributes
+# README.md files are the base folders' own documentation — keep them visible.
+CLAUDE.md
+
+# Empty-folder placeholders used only for committing empty dirs.
+**/.gitkeep
+
+**/access.md
+roles.yaml

package/kb-template/Agents/README.md

@@ -0,0 +1,38 @@
+# Agents/
+
+`.agent` files — **role definitions for agents**, and the main way anyone
+(a person's own assistant or a background pipeline) connects to the platform.
+Connecting "as" an `.agent` mints exactly that agent's tool surface — e.g. the
+KB's MCP config is generated per `.agent`, not from everything the identity
+can read.
+
+## Structure
+
+```text
+Agents/
+├── default.agent         ← the safe floor: basic KB access only
+├── developer.agent       ← an admin-authored role: everything developers get
+└── <role-or-pipeline>.agent
+```
+
+One file per role or per pipeline agent. (Exact file format: TBD.)
+
+## What an `.agent` defines
+
+- The **target harness** (e.g. Claude Code) and model / reasoning settings.
+- The **skills** and **tools** composed in — selections from `Skills/` and
+  `Tools/`. The execution layer compiles these into the harness's native
+  plugin format and installs it.
+- Permissions/allowlists, hooks, MCP servers, env vars, session defaults,
+  and injected instructions (the agent's charter).
+- **References** to an identity and a budget — never credentials themselves.
+
+## Rules
+
+- An `.agent` only **narrows** what its identity's permissions already allow —
+  it never widens access. Identity remains the security boundary; `.agent`
+  is configuration.
+- **No secret values** in these files — secrets are referenced by vault name.
+- This folder sits under access control + change requests: editing a role
+  file changes the whole role's tooling, and is reviewed like any other
+  change.