@pegma/knowledge-base-mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pegma
+
+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

@@ -1,3 +1,82 @@
-# Temporary Holding Version
+# @pegma/knowledge-base-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Optional KB-04 agent transport source for Pegma Knowledge Base. This package
+adapts the authorized application API to bounded agent commands and the Model
+Context Protocol. It is unpublished at `0.1.0`; merging its source does not
+publish it or establish a live hosted Knowledge Base.
+
+The contracts, core, and application packages remain independent of MCP, HTTP,
+provider SDKs, and login flows. Hosts choose this adapter when exposing agent
+access. The adapter pins `@modelcontextprotocol/sdk` at `1.32.2` and `zod` at
+`4.6.7`; it composes the same exact `0.1.0` Knowledge Base packages.
+
+The MCP adapter explicitly uses the SDK's Workers-compatible JSON Schema
+validator, which requires no generated code. Its `@cfworker/json-schema`
+dependency is pinned at `4.1.6` and required by this package even though the
+SDK declares it as an optional peer. Packed consumers receive the validator
+without needing to discover or install that peer themselves.
+
+## Trust and composition
+
+The host owns credential issuance, authentication, resource binding, current
+authorization, and evidence verification. Compose the adapter with the
+Knowledge Base application and host authentication ports. Agent Access is a
+separate producer; it is not a runtime dependency of this package. An opaque
+credential, caller-supplied actor, or claimed evidence result does not establish
+an authenticated `AccessContext` or trusted evidence.
+
+Agent operations use the same current-resource authorization, application
+generation, immutable evidence, replay, and publication rules as other
+application callers. Agents can prepare drafts and submit evidence through the
+declared tool surface. Review and publication remain separate staff authority.
+The adapter never executes article steps, fetches evidence URLs, provisions a
+runner, or creates a second database or identity system.
+
+`createKnowledgeAgentDispatcher` provides the shared operation boundary.
+`knowledgeAgentScopes`, `knowledgeAgentOperations`, and
+`knowledgeAgentToolNames` declare its finite surface. Inputs are validated
+against shared internal schemas and fixed component ceilings before dispatch.
+Errors use bounded public responses rather than exposing internal exceptions
+or private evidence and provenance.
+
+`createKnowledgeAgentHttp` and `createKnowledgeAgentMcp` expose that dispatcher
+through host-configured protected endpoints. Both require fresh host
+authentication and admission control on every request; neither issues tokens.
+
+The [host composition contract](https://github.com/pegma-dev/knowledge-base/blob/main/docs/HOST_COMPOSITION.md)
+describes authenticated contexts, trusted evidence, replay, and safe DTOs. The
+[retrieval contract](https://github.com/pegma-dev/knowledge-base/blob/main/docs/RETRIEVAL.md)
+describes authoritative current-publication confirmation and audience boundaries.
+
+## Local verification and release
+
+Repository development uses Node 22.6.0+ or 24 with pnpm 10.34.5:
+
+```sh
+pnpm install --frozen-lockfile
+pnpm run format:check
+pnpm run check
+pnpm test
+pnpm example
+pnpm run release:check
+pnpm run agent:proof
+```
+
+`release:check` packs and installs all four unpublished Knowledge Base packages
+in an isolated temporary consumer, verifies their actual artifact bytes and
+inventory, and imports their public entry points without workspace links.
+`agent:proof` exercises the authenticated SDK path with a pinned public Agent
+Access producer packed only into a temporary test consumer. That producer
+source is a test fixture, not a production release substitute or package
+dependency. These local checks establish neither live host acceptance nor npm
+publication.
+
+Each package has its own README, MIT LICENSE, build-on-prepack hook, and
+compiled-test exclusion. All four package versions remain synchronized at
+`0.1.0`. First publication, release tags, trusted-publisher configuration, and
+host activation are separate maintainer operations in the
+[release procedure](https://github.com/pegma-dev/knowledge-base/blob/main/docs/RELEASING.md).
+Development links above track `main`; release preparation must pin verified
+release documentation before first publication.
+
+Built in the open by RetireGolden, LLC.

package/dist/dispatcher.d.ts

@@ -0,0 +1,7 @@
+import { type KnowledgeAgentDispatcher, type KnowledgeAgentDispatcherOptions } from "./types.js";
+/**
+ * One versioned least-authority boundary shared by HTTP and MCP. Authentication,
+ * credential issuance, current access resolution, and rate limits are host work.
+ */
+export declare function createKnowledgeAgentDispatcher(options: KnowledgeAgentDispatcherOptions): KnowledgeAgentDispatcher;
+//# sourceMappingURL=dispatcher.d.ts.map

package/dist/dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../src/dispatcher.ts"],"names":[],"mappings":"AAaA,OAAO,EAEL,KAAK,wBAAwB,EAC7B,KAAK,+BAA+B,EAKrC,MAAM,YAAY,CAAC;AAyHpB;;;GAGG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,+BAA+B,GACvC,wBAAwB,CA0E1B"}

package/dist/dispatcher.js

@@ -0,0 +1,155 @@
+import { createKnowledgeAgentErrorResponse, KnowledgeAgentBoundaryError, mapKnowledgeAgentError, } from "./errors.js";
+import { knowledgeAgentEnvelopeSchema, knowledgeAgentResultSchemas, resolveKnowledgeAgentLimits, snapshotKnowledgeAgentJson, } from "./schemas.js";
+import { knowledgeAgentScopes, } from "./types.js";
+const initialPermissions = Object.freeze(Object.values(knowledgeAgentScopes));
+// Trusted host authority is independently bounded. Client payload array limits
+// must not reject an administrator's broad context before it can be attenuated.
+const maximumAuthorityItems = 256;
+const maximumAuthorityCharacters = 1_024;
+function own(value, key) {
+    if (value === null ||
+        typeof value !== "object" ||
+        ![Object.prototype, null].includes(Object.getPrototypeOf(value))) {
+        throw new KnowledgeAgentBoundaryError("forbidden");
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (descriptor === undefined || !("value" in descriptor))
+        throw new KnowledgeAgentBoundaryError("forbidden");
+    return descriptor.value;
+}
+function trustedText(value, maximum) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > maximum ||
+        value.trim() !== value ||
+        /[\u0000-\u001f\u007f\ud800-\udfff]/u.test(value)) {
+        throw new KnowledgeAgentBoundaryError("forbidden");
+    }
+    return value;
+}
+function knownPermissions(value) {
+    if (!Array.isArray(value) ||
+        Object.getPrototypeOf(value) !== Array.prototype) {
+        throw new KnowledgeAgentBoundaryError("forbidden");
+    }
+    const length = Object.getOwnPropertyDescriptor(value, "length");
+    if (length === undefined ||
+        !("value" in length) ||
+        typeof length.value !== "number" ||
+        length.value > maximumAuthorityItems ||
+        Reflect.ownKeys(value).length !== length.value + 1) {
+        throw new KnowledgeAgentBoundaryError("forbidden");
+    }
+    const result = new Set();
+    for (let index = 0; index < length.value; index += 1) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+        if (descriptor === undefined ||
+            !("value" in descriptor) ||
+            !descriptor.enumerable) {
+            throw new KnowledgeAgentBoundaryError("forbidden");
+        }
+        const permission = descriptor.value;
+        if (typeof permission !== "string" ||
+            permission.length > maximumAuthorityCharacters) {
+            throw new KnowledgeAgentBoundaryError("forbidden");
+        }
+        if (initialPermissions.some((known) => known === permission))
+            result.add(permission);
+    }
+    return result;
+}
+/** Snapshot the exact least-authority context without reading host role data. */
+function effectiveAccess(identity, resource) {
+    if (trustedText(own(identity, "resource"), 2_048) !== resource)
+        throw new KnowledgeAgentBoundaryError("forbidden");
+    trustedText(own(identity, "clientId"), 200);
+    const scopes = knownPermissions(own(identity, "scopes"));
+    const access = own(identity, "access");
+    const principalId = trustedText(own(access, "principalId"), 200);
+    const policyVersion = trustedText(own(access, "policyVersion"), 200);
+    const currentPermissions = knownPermissions(own(access, "permissions"));
+    return Object.freeze({
+        principalId,
+        policyVersion,
+        roles: Object.freeze([]),
+        entitlements: Object.freeze([]),
+        permissions: Object.freeze(initialPermissions.filter((permission) => scopes.has(permission) && currentPermissions.has(permission))),
+    });
+}
+function requireOperation(access, operation) {
+    const has = (permission) => access.permissions.includes(permission);
+    const allowed = operation === "getValidationRequirements"
+        ? has(knowledgeAgentScopes.draftWrite) ||
+            has(knowledgeAgentScopes.evidenceSubmit)
+        : has(operation === "getDraft"
+            ? knowledgeAgentScopes.draftRead
+            : operation === "submitEvidence"
+                ? knowledgeAgentScopes.evidenceSubmit
+                : knowledgeAgentScopes.draftWrite);
+    if (!allowed)
+        throw new KnowledgeAgentBoundaryError("forbidden");
+}
+/**
+ * One versioned least-authority boundary shared by HTTP and MCP. Authentication,
+ * credential issuance, current access resolution, and rate limits are host work.
+ */
+export function createKnowledgeAgentDispatcher(options) {
+    const limits = resolveKnowledgeAgentLimits(options.limits);
+    const resource = trustedText(options.resource, 2_048);
+    const application = options.application;
+    return Object.freeze({
+        limits,
+        async dispatch(identity, request) {
+            let operation = null;
+            try {
+                // All caller-owned objects are detached before the first application
+                // await. The application still performs current resource/replay checks.
+                const access = effectiveAccess(identity, resource);
+                const snapshot = snapshotKnowledgeAgentJson(request, limits);
+                const parsed = knowledgeAgentEnvelopeSchema.safeParse(snapshot);
+                if (!parsed.success)
+                    throw new KnowledgeAgentBoundaryError("invalid_request");
+                const envelope = snapshotKnowledgeAgentJson(parsed.data, limits);
+                operation = envelope.operation;
+                requireOperation(access, operation);
+                let result;
+                switch (envelope.operation) {
+                    case "getDraft":
+                        result = await application.getDraft(access, envelope.input);
+                        break;
+                    case "createDraft":
+                        result = await application.createDraft(access, envelope.input);
+                        break;
+                    case "updateDraft":
+                        result = await application.updateDraft(access, envelope.input);
+                        break;
+                    case "getValidationRequirements":
+                        result = await application.getValidationRequirements(access, envelope.input);
+                        break;
+                    case "submitEvidence":
+                        result = await application.submitEvidence(access, envelope.input);
+                        break;
+                }
+                let detached;
+                try {
+                    detached = snapshotKnowledgeAgentJson(result, limits, limits.maxResponseBytes);
+                }
+                catch (error) {
+                    if (error instanceof KnowledgeAgentBoundaryError &&
+                        error.code === "capacity") {
+                        throw error;
+                    }
+                    throw new KnowledgeAgentBoundaryError("unavailable");
+                }
+                const safe = knowledgeAgentResultSchemas[operation].safeParse(detached);
+                if (!safe.success)
+                    throw new KnowledgeAgentBoundaryError("unavailable");
+                return snapshotKnowledgeAgentJson({ apiVersion: "1", operation, result: safe.data }, limits, limits.maxResponseBytes);
+            }
+            catch (error) {
+                return createKnowledgeAgentErrorResponse(mapKnowledgeAgentError(error).code, operation);
+            }
+        },
+    });
+}
+//# sourceMappingURL=dispatcher.js.map

package/dist/dispatcher.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,10 @@
+import type { KnowledgeAgentError, KnowledgeAgentErrorCode, KnowledgeAgentFailure, KnowledgeAgentOperation } from "./types.js";
+/** Internal classification only; never exposes an exception or its message. */
+export declare class KnowledgeAgentBoundaryError extends Error {
+    readonly code: KnowledgeAgentErrorCode;
+    constructor(code: KnowledgeAgentErrorCode);
+}
+/** Unknown application/storage/verifier failures become content-free 503s. */
+export declare function mapKnowledgeAgentError(error: unknown): KnowledgeAgentError;
+export declare function createKnowledgeAgentErrorResponse(code: KnowledgeAgentErrorCode, operation?: KnowledgeAgentOperation | null): KnowledgeAgentFailure;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EACV,mBAAmB,EACnB,uBAAuB,EACvB,qBAAqB,EACrB,uBAAuB,EACxB,MAAM,YAAY,CAAC;AAyCpB,+EAA+E;AAC/E,qBAAa,2BAA4B,SAAQ,KAAK;IACxC,QAAQ,CAAC,IAAI,EAAE,uBAAuB;IAAlD,YAAqB,IAAI,EAAE,uBAAuB,EAGjD;CACF;AAED,8EAA8E;AAC9E,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CAc1E;AAED,wBAAgB,iCAAiC,CAC/C,IAAI,EAAE,uBAAuB,EAC7B,SAAS,GAAE,uBAAuB,GAAG,IAAW,GAC/C,qBAAqB,CAEvB"}

package/dist/errors.js

@@ -0,0 +1,75 @@
+import { KnowledgeBaseAuthorizationError, KnowledgeBaseNotFoundError, KnowledgeBasePrerequisiteError, RepositoryCapacityError, RepositoryConflictError, } from "@pegma/knowledge-base-application";
+import { KnowledgeBaseError } from "@pegma/knowledge-base-core";
+const errors = Object.freeze({
+    invalid_request: Object.freeze({
+        code: "invalid_request",
+        status: 400,
+        message: "Invalid knowledge request.",
+    }),
+    forbidden: Object.freeze({
+        code: "forbidden",
+        status: 403,
+        message: "Knowledge access is forbidden.",
+    }),
+    not_found: Object.freeze({
+        code: "not_found",
+        status: 404,
+        message: "Knowledge resource is unavailable.",
+    }),
+    conflict: Object.freeze({
+        code: "conflict",
+        status: 409,
+        message: "Knowledge command conflicts with current state.",
+    }),
+    capacity: Object.freeze({
+        code: "capacity",
+        status: 413,
+        message: "Knowledge request or result exceeds capacity.",
+    }),
+    prerequisite: Object.freeze({
+        code: "prerequisite",
+        status: 412,
+        message: "Knowledge prerequisite is not ready.",
+    }),
+    unavailable: Object.freeze({
+        code: "unavailable",
+        status: 503,
+        message: "Knowledge service is unavailable.",
+    }),
+});
+/** Internal classification only; never exposes an exception or its message. */
+export class KnowledgeAgentBoundaryError extends Error {
+    code;
+    constructor(code) {
+        super("Knowledge agent boundary rejected data");
+        this.code = code;
+        this.name = "KnowledgeAgentBoundaryError";
+    }
+}
+/** Unknown application/storage/verifier failures become content-free 503s. */
+export function mapKnowledgeAgentError(error) {
+    if (error instanceof KnowledgeAgentBoundaryError)
+        return errors[error.code];
+    if (error instanceof KnowledgeBaseAuthorizationError)
+        return errors.forbidden;
+    if (error instanceof KnowledgeBaseNotFoundError)
+        return errors.not_found;
+    if (error instanceof RepositoryConflictError)
+        return errors.conflict;
+    if (error instanceof RepositoryCapacityError)
+        return errors.capacity;
+    if (error instanceof KnowledgeBasePrerequisiteError)
+        return errors.prerequisite;
+    if (error instanceof KnowledgeBaseError) {
+        if (error.code === "invalid")
+            return errors.invalid_request;
+        if (error.code === "conflict")
+            return errors.conflict;
+        return errors.prerequisite;
+    }
+    return errors.unavailable;
+}
+export function createKnowledgeAgentErrorResponse(code, operation = null) {
+    return Object.freeze({ apiVersion: "1", operation, error: errors[code] });
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,+BAA+B,EAC/B,0BAA0B,EAC1B,8BAA8B,EAC9B,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAShE,MAAM,MAAM,GACV,MAAM,CAAC,MAAM,CAAC;IACZ,eAAe,EAAE,MAAM,CAAC,MAAM,CAAC;QAC7B,IAAI,EAAE,iBAAiB;QACvB,MAAM,EAAE,GAAG;QACX,OAAO,EAAE,4BAA4B;KACtC,CAAC;IACF,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC;QACvB,IAAI,EAAE,WAAW;QACjB,MAAM,EAAE,GAAG;QACX,OAAO,EAAE,gCAAgC;KAC1C,CAAC;IACF,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC;QACvB,IAAI,EAAE,WAAW;QACjB,MAAM,EAAE,GAAG;QACX,OAAO,EAAE,oCAAoC;KAC9C,CAAC;IACF,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC;QACtB,IAAI,EAAE,UAAU;QAChB,MAAM,EAAE,GAAG;QACX,OAAO,EAAE,iDAAiD;KAC3D,CAAC;IACF,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC;QACtB,IAAI,EAAE,UAAU;QAChB,MAAM,EAAE,GAAG;QACX,OAAO,EAAE,+CAA+C;KACzD,CAAC;IACF,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC;QAC1B,IAAI,EAAE,cAAc;QACpB,MAAM,EAAE,GAAG;QACX,OAAO,EAAE,sCAAsC;KAChD,CAAC;IACF,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC;QACzB,IAAI,EAAE,aAAa;QACnB,MAAM,EAAE,GAAG;QACX,OAAO,EAAE,mCAAmC;KAC7C,CAAC;CACH,CAAC,CAAC;AAEL,+EAA+E;AAC/E,MAAM,OAAO,2BAA4B,SAAQ,KAAK;IAC/B,IAAI;IAAzB,YAAqB,IAA6B;QAChD,KAAK,CAAC,wCAAwC,CAAC,CAAC;oBAD7B,IAAI;QAEvB,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAC;IAC5C,CAAC;CACF;AAED,8EAA8E;AAC9E,MAAM,UAAU,sBAAsB,CAAC,KAAc;IACnD,IAAI,KAAK,YAAY,2BAA2B;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5E,IAAI,KAAK,YAAY,+BAA+B;QAAE,OAAO,MAAM,CAAC,SAAS,CAAC;IAC9E,IAAI,KAAK,YAAY,0BAA0B;QAAE,OAAO,MAAM,CAAC,SAAS,CAAC;IACzE,IAAI,KAAK,YAAY,uBAAuB;QAAE,OAAO,MAAM,CAAC,QAAQ,CAAC;IACrE,IAAI,KAAK,YAAY,uBAAuB;QAAE,OAAO,MAAM,CAAC,QAAQ,CAAC;IACrE,IAAI,KAAK,YAAY,8BAA8B;QACjD,OAAO,MAAM,CAAC,YAAY,CAAC;IAC7B,IAAI,KAAK,YAAY,kBAAkB,EAAE,CAAC;QACxC,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;YAAE,OAAO,MAAM,CAAC,eAAe,CAAC;QAC5D,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU;YAAE,OAAO,MAAM,CAAC,QAAQ,CAAC;QACtD,OAAO,MAAM,CAAC,YAAY,CAAC;IAC7B,CAAC;IACD,OAAO,MAAM,CAAC,WAAW,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,iCAAiC,CAC/C,IAA6B,EAC7B,SAAS,GAAmC,IAAI;IAEhD,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAC5E,CAAC"}

package/dist/http.d.ts

@@ -0,0 +1,14 @@
+import type { KnowledgeAgentDispatcher } from "./types.js";
+import type { KnowledgeAgentTransportOptions } from "./transport-common.js";
+export interface KnowledgeAgentHttpOptions extends KnowledgeAgentTransportOptions {
+    /** Exact canonical versioned API URL; the protected resource remains MCP. */
+    readonly apiUrl: string;
+    readonly dispatcher: KnowledgeAgentDispatcher;
+}
+export interface KnowledgeAgentHttp {
+    /** Null leaves unmatched paths to the host's router. */
+    handle(request: Request): Promise<Response | null>;
+}
+/** Portable Fetch adapter: host credentials and admission, shared application law. */
+export declare function createKnowledgeAgentHttp(options: KnowledgeAgentHttpOptions): KnowledgeAgentHttp;
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAU3D,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,uBAAuB,CAAC;AAE5E,MAAM,WAAW,yBAA0B,SAAQ,8BAA8B;IAC/E,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,wBAAwB,CAAC;CAC/C;AAED,MAAM,WAAW,kBAAkB;IACjC,wDAAwD;IACxD,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;CACpD;AAED,sFAAsF;AACtF,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,yBAAyB,GACjC,kBAAkB,CA6CpB"}

package/dist/http.js

@@ -0,0 +1,28 @@
+import { authorizeKnowledgeAgentRequest, knowledgeAgentJsonResponse, knowledgeAgentRequestMatches, knowledgeAgentTransportError, readKnowledgeAgentJsonRequest, secureKnowledgeAgentResponse, validateKnowledgeAgentTransportOptions, } from "./transport-common.js";
+/** Portable Fetch adapter: host credentials and admission, shared application law. */
+export function createKnowledgeAgentHttp(options) {
+    const configuration = validateKnowledgeAgentTransportOptions(options, options.apiUrl, "http");
+    const dispatcher = options.dispatcher;
+    return Object.freeze({
+        async handle(request) {
+            if (!knowledgeAgentRequestMatches(request, configuration))
+                return null;
+            const identity = await authorizeKnowledgeAgentRequest(request, configuration);
+            if (identity instanceof Response)
+                return identity;
+            if (request.method !== "POST")
+                return knowledgeAgentTransportError("method_not_allowed", request, configuration);
+            const parsed = await readKnowledgeAgentJsonRequest(request, dispatcher.limits);
+            if (parsed instanceof Response)
+                return secureKnowledgeAgentResponse(parsed, request, configuration);
+            try {
+                const response = await dispatcher.dispatch(identity, parsed.value);
+                return knowledgeAgentJsonResponse(response, "error" in response ? response.error.status : 200, dispatcher.limits.maxResponseBytes, request, configuration);
+            }
+            catch {
+                return knowledgeAgentTransportError("unavailable", request, configuration);
+            }
+        },
+    });
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AACA,OAAO,EACL,8BAA8B,EAC9B,0BAA0B,EAC1B,4BAA4B,EAC5B,4BAA4B,EAC5B,6BAA6B,EAC7B,4BAA4B,EAC5B,sCAAsC,GACvC,MAAM,uBAAuB,CAAC;AAc/B,sFAAsF;AACtF,MAAM,UAAU,wBAAwB,CACtC,OAAkC;IAElC,MAAM,aAAa,GAAG,sCAAsC,CAC1D,OAAO,EACP,OAAO,CAAC,MAAM,EACd,MAAM,CACP,CAAC;IACF,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IACtC,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,KAAK,CAAC,MAAM,CAAC,OAAgB;YAC3B,IAAI,CAAC,4BAA4B,CAAC,OAAO,EAAE,aAAa,CAAC;gBAAE,OAAO,IAAI,CAAC;YACvE,MAAM,QAAQ,GAAG,MAAM,8BAA8B,CACnD,OAAO,EACP,aAAa,CACd,CAAC;YACF,IAAI,QAAQ,YAAY,QAAQ;gBAAE,OAAO,QAAQ,CAAC;YAClD,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM;gBAC3B,OAAO,4BAA4B,CACjC,oBAAoB,EACpB,OAAO,EACP,aAAa,CACd,CAAC;YACJ,MAAM,MAAM,GAAG,MAAM,6BAA6B,CAChD,OAAO,EACP,UAAU,CAAC,MAAM,CAClB,CAAC;YACF,IAAI,MAAM,YAAY,QAAQ;gBAC5B,OAAO,4BAA4B,CAAC,MAAM,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC;YACtE,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,MAAM,UAAU,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;gBACnE,OAAO,0BAA0B,CAC/B,QAAQ,EACR,OAAO,IAAI,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,EACjD,UAAU,CAAC,MAAM,CAAC,gBAAgB,EAClC,OAAO,EACP,aAAa,CACd,CAAC;YACJ,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,4BAA4B,CACjC,aAAa,EACb,OAAO,EACP,aAAa,CACd,CAAC;YACJ,CAAC;QACH,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { createKnowledgeAgentDispatcher } from "./dispatcher.js";
+export { createKnowledgeAgentHttp } from "./http.js";
+export { createKnowledgeAgentMcp } from "./mcp.js";
+export { defaultKnowledgeAgentLimits, knowledgeAgentOperations, knowledgeAgentScopes, knowledgeAgentToolNames, } from "./types.js";
+export type * from "./types.js";
+export type * from "./http.js";
+export type * from "./mcp.js";
+export type { KnowledgeAgentLimitDecision, KnowledgeAgentTransport, KnowledgeAgentTransportOptions, } from "./transport-common.js";
+//# 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":"AAAA,OAAO,EAAE,8BAA8B,EAAE,MAAM,iBAAiB,CAAC;AACjE,OAAO,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAC;AACrD,OAAO,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AACnD,OAAO,EACL,2BAA2B,EAC3B,wBAAwB,EACxB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,YAAY,CAAC;AACpB,mBAAmB,YAAY,CAAC;AAChC,mBAAmB,WAAW,CAAC;AAC/B,mBAAmB,UAAU,CAAC;AAC9B,YAAY,EACV,2BAA2B,EAC3B,uBAAuB,EACvB,8BAA8B,GAC/B,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { createKnowledgeAgentDispatcher } from "./dispatcher.js";
+export { createKnowledgeAgentHttp } from "./http.js";
+export { createKnowledgeAgentMcp } from "./mcp.js";
+export { defaultKnowledgeAgentLimits, knowledgeAgentOperations, knowledgeAgentScopes, knowledgeAgentToolNames, } from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,8BAA8B,EAAE,MAAM,iBAAiB,CAAC;AACjE,OAAO,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAC;AACrD,OAAO,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AACnD,OAAO,EACL,2BAA2B,EAC3B,wBAAwB,EACxB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,YAAY,CAAC"}

package/dist/mcp.d.ts

@@ -0,0 +1,17 @@
+import { type KnowledgeAgentTransportOptions } from "./transport-common.js";
+import { type KnowledgeAgentDispatcher } from "./types.js";
+export interface KnowledgeAgentMcpOptions extends KnowledgeAgentTransportOptions {
+    /** Exact MCP endpoint; it must equal the canonical protected resource. */
+    readonly mcpUrl: string;
+    readonly dispatcher: KnowledgeAgentDispatcher;
+}
+export interface KnowledgeAgentMcp {
+    /** Null leaves unmatched paths to the host's router. */
+    handle(request: Request): Promise<Response | null>;
+}
+/**
+ * Stateless, JSON-response Streamable HTTP. Every request resolves fresh host
+ * authority and owns a short-lived SDK server; no session or credential is cached.
+ */
+export declare function createKnowledgeAgentMcp(options: KnowledgeAgentMcpOptions): KnowledgeAgentMcp;
+//# sourceMappingURL=mcp.d.ts.map

package/dist/mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"AAmBA,OAAO,EAQL,KAAK,8BAA8B,EACpC,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAGL,KAAK,wBAAwB,EAG9B,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,wBAAyB,SAAQ,8BAA8B;IAC9E,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,wBAAwB,CAAC;CAC/C;AAED,MAAM,WAAW,iBAAiB;IAChC,wDAAwD;IACxD,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;CACpD;AAyND;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,wBAAwB,GAChC,iBAAiB,CAuJnB"}