@cat-factory/server 0.239.1 → 0.240.0

package/dist/modules/publicApi/openapiDocument.generated.js.map

@@ -1 +1 @@
-{"version":3,"file":"openapiDocument.generated.js","sourceRoot":"","sources":["../../../src/modules/publicApi/openapiDocument.generated.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,EAAE;AACF,0FAA0F;AAC1F,8FAA8F;AAC9F,8FAA8F;AAC9F,8EAA8E;AAE9E,MAAM,CAAC,MAAM,YAAY,GAAG,w6sZAAw6sZ,CAAA"}
+{"version":3,"file":"openapiDocument.generated.js","sourceRoot":"","sources":["../../../src/modules/publicApi/openapiDocument.generated.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,EAAE;AACF,0FAA0F;AAC1F,8FAA8F;AAC9F,8FAA8F;AAC9F,8EAA8E;AAE9E,MAAM,CAAC,MAAM,YAAY,GAAG,wluZAAwluZ,CAAA"}

package/dist/persistence/deploymentDocuments.d.ts

@@ -0,0 +1,42 @@
+import type { DeploymentDocumentResolver, DocumentContent, DocumentSourceKind } from '@cat-factory/kernel';
+/**
+ * A {@link DeploymentDocumentResolver} backed by the mothership's
+ * `POST /internal/prompt-fragments/document-bodies`, presenting the node's machine token.
+ *
+ * **The credential never crosses; the BODY does.** The deployment's document credentials live in
+ * the mothership's environment, and `ENCRYPTION_KEY`-class configuration does not reach a laptop,
+ * so a node cannot authenticate to the vendor itself. That is the same rule that keeps a
+ * decrypting repository off the remote route, applied to a resolver instead of a repository.
+ *
+ * **A failed read THROWS; it never answers "no such document".** An unreachable mothership and a
+ * document this deployment cannot resolve are the same value and opposite facts, and the caller
+ * (`FragmentLibraryService.resolveDocumentBody`) degrades a THROW to the fragment's registered
+ * body with a warning naming the fragment. Answering silently-absent instead would produce the
+ * identical prompt with no warning anywhere, which is exactly the stale-standard failure that is
+ * indistinguishable from a current one.
+ */
+export declare class HttpDeploymentDocumentResolver implements DeploymentDocumentResolver {
+    private readonly opts;
+    constructor(opts: {
+        baseUrl: string;
+        /** Fixed token, or a provider read PER REQUEST (the shape every other machine client takes). */
+        token: string | (() => string | null);
+        /**
+         * The sources the MOTHERSHIP has configured, as reported at connect time.
+         *
+         * A node cannot see the mothership's environment, so `configured()` would otherwise have to
+         * be a network call, and it is asked on a hot path (per document-backed entry, per catalog
+         * resolve) by a caller that only wants to know whether to bother. Absent ⇒ assume every
+         * deployment-scopable source may be served and let the read itself decide, which is the safe
+         * direction: it costs one round trip that returns nothing, where the opposite would silently
+         * skip a document the mothership could have served.
+         */
+        configuredSources?: readonly DocumentSourceKind[];
+        fetchImpl?: typeof fetch;
+    });
+    configured(source: DocumentSourceKind): boolean;
+    fetch(source: DocumentSourceKind, externalId: string): Promise<DocumentContent>;
+    probeVersion(source: DocumentSourceKind, externalId: string): Promise<string>;
+    private read;
+}
+//# sourceMappingURL=deploymentDocuments.d.ts.map

package/dist/persistence/deploymentDocuments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deploymentDocuments.d.ts","sourceRoot":"","sources":["../../src/persistence/deploymentDocuments.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,0BAA0B,EAC1B,eAAe,EACf,kBAAkB,EACnB,MAAM,qBAAqB,CAAA;AAU5B;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,8BAA+B,YAAW,0BAA0B;IAE7E,OAAO,CAAC,QAAQ,CAAC,IAAI;IADvB,YACmB,IAAI,EAAE;QACrB,OAAO,EAAE,MAAM,CAAA;QACf,gGAAgG;QAChG,KAAK,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,IAAI,CAAC,CAAA;QACrC;;;;;;;;;WASG;QACH,iBAAiB,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAA;QACjD,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;KACzB,EACC;IAEJ,UAAU,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAG9C;IAEK,KAAK,CAAC,MAAM,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CASpF;IAEK,YAAY,CAAC,MAAM,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAKlF;YAEa,IAAI;CA8DnB"}

package/dist/persistence/deploymentDocuments.js

@@ -0,0 +1,96 @@
+import { UnavailableError, describeError } from '@cat-factory/kernel';
+import { isDeploymentScopedSource } from '@cat-factory/contracts';
+import { documentBodyRefKey } from '../modules/promptFragments/PromptFragmentsInternalController.js';
+// The client half of the mothership-mode DEPLOYMENT-scoped document read (see
+// `../modules/promptFragments/PromptFragmentsInternalController.ts` for why the body crosses the
+// machine API rather than the credential). The sibling of `promptFragments.ts` and
+// `foundationalBuiltins.ts`, written to the same contract for the same reason.
+/**
+ * A {@link DeploymentDocumentResolver} backed by the mothership's
+ * `POST /internal/prompt-fragments/document-bodies`, presenting the node's machine token.
+ *
+ * **The credential never crosses; the BODY does.** The deployment's document credentials live in
+ * the mothership's environment, and `ENCRYPTION_KEY`-class configuration does not reach a laptop,
+ * so a node cannot authenticate to the vendor itself. That is the same rule that keeps a
+ * decrypting repository off the remote route, applied to a resolver instead of a repository.
+ *
+ * **A failed read THROWS; it never answers "no such document".** An unreachable mothership and a
+ * document this deployment cannot resolve are the same value and opposite facts, and the caller
+ * (`FragmentLibraryService.resolveDocumentBody`) degrades a THROW to the fragment's registered
+ * body with a warning naming the fragment. Answering silently-absent instead would produce the
+ * identical prompt with no warning anywhere, which is exactly the stale-standard failure that is
+ * indistinguishable from a current one.
+ */
+export class HttpDeploymentDocumentResolver {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    configured(source) {
+        if (!isDeploymentScopedSource(source))
+            return false;
+        return this.opts.configuredSources?.includes(source) ?? true;
+    }
+    async fetch(source, externalId) {
+        const content = await this.read(source, externalId);
+        return {
+            externalId,
+            title: '',
+            url: '',
+            body: content.body,
+            version: content.version,
+        };
+    }
+    async probeVersion(source, externalId) {
+        // The mothership's own resolver caches the body, so this is not the extra fetch it looks
+        // like: the node's `documentBodyCache` asks for a version only when its entry enters the
+        // refresh window, and the mothership answers from the copy it just verified.
+        return (await this.read(source, externalId)).version;
+    }
+    async read(source, externalId) {
+        const fetchImpl = this.opts.fetchImpl ?? fetch;
+        const token = typeof this.opts.token === 'function' ? this.opts.token() : this.opts.token;
+        const url = `${this.opts.baseUrl.replace(/\/$/, '')}/internal/prompt-fragments/document-bodies`;
+        let res;
+        try {
+            res = await fetchImpl(url, {
+                method: 'POST',
+                headers: {
+                    authorization: `Bearer ${token ?? ''}`,
+                    'content-type': 'application/json',
+                },
+                body: JSON.stringify({ refs: [{ source, externalId }] }),
+            });
+        }
+        catch (error) {
+            throw new UnavailableError('A deployment-scoped document could not be read from the mothership', 'deployment_document_unreachable', 
+            // Scrubbed through `redactSecrets`, because a fetch failure routinely echoes the request
+            // URL, which here carries the mothership's address.
+            describeError(error));
+        }
+        if (!res.ok) {
+            // Includes a mothership OLDER than this node, which answers 404 for a route it does not
+            // serve. Reading that as "the document is gone" would silently pin the registered body.
+            throw new UnavailableError('The mothership refused a deployment-scoped document read', 'deployment_document_unreachable', { status: res.status });
+        }
+        const payload = (await res.json().catch(() => null));
+        const bodies = payload?.bodies;
+        if (!bodies || typeof bodies !== 'object' || Array.isArray(bodies)) {
+            throw new UnavailableError('The mothership returned an unreadable deployment-document reply', 'deployment_document_unreachable', { field: 'bodies' });
+        }
+        // Indexed with the SERVER's own key function, never a locally re-spelled one: the pair
+        // `(source, externalId)` is what identifies a document, and a client that rebuilds that
+        // string itself is one rename away from silently indexing nothing.
+        const entry = bodies[documentBodyRefKey(source, externalId)];
+        const body = entry?.body;
+        const version = entry?.version;
+        if (typeof body !== 'string' || typeof version !== 'string') {
+            // ABSENT means the mothership could not resolve it either (it omits rather than failing the
+            // whole batch, and logs why on its own side). Throwing keeps the node's disposition the same
+            // as a standalone deployment's: degrade to the registered body AND say so.
+            throw new UnavailableError('The mothership could not resolve this deployment-scoped document', 'deployment_document_unresolved', { source });
+        }
+        return { body, version };
+    }
+}
+//# sourceMappingURL=deploymentDocuments.js.map

package/dist/persistence/deploymentDocuments.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/server",
-  "version": "0.239.1",
+  "version": "0.240.0",
   "description": "Runtime-neutral HTTP layer for the Agent Architecture Board: the Hono controllers, middleware (auth/authz/CORS/error), request helpers and the gateway seams shared by every deployment facade (Cloudflare Worker, Node service).",
   "repository": {
     "type": "git",
@@ -31,13 +31,13 @@
     "jose": "^6.2.8",
     "pino": "^10.3.1",
     "valibot": "^1.4.2",
-    "@cat-factory/agents": "0.116.7",
-    "@cat-factory/integrations": "0.140.1",
-    "@cat-factory/contracts": "0.261.0",
-    "@cat-factory/mcp-server": "0.16.0",
-    "@cat-factory/orchestration": "0.228.1",
-    "@cat-factory/spend": "0.15.26",
-    "@cat-factory/kernel": "0.260.0"
+    "@cat-factory/agents": "0.117.0",
+    "@cat-factory/integrations": "0.141.0",
+    "@cat-factory/kernel": "0.262.0",
+    "@cat-factory/contracts": "0.262.0",
+    "@cat-factory/mcp-server": "0.16.1",
+    "@cat-factory/orchestration": "0.230.0",
+    "@cat-factory/spend": "0.15.28"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",