@agentxm/registry-protocol 0.28.4-bootstrap.0

package/dist/src/unstable/content/subagent-content.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Subagent content file module for subagent content parsing.
+ *
+ * The content file's YAML frontmatter is largely free-form: only `name` is
+ * required and validated. `agentOverrides`, when present, is recognized for
+ * use in per-agent rendering. Any other frontmatter keys flow through
+ * verbatim to the agent-native file produced by the renderer.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+declare const SubagentContentError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "SubagentContentError";
+} & Readonly<A>;
+/**
+ * Typed failure produced while parsing a subagent content file. Application
+ * layers translate this into their own error vocabulary.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare class SubagentContentError extends SubagentContentError_base<{
+    readonly reason: "frontmatter-parse" | "missing-frontmatter" | "invalid-frontmatter" | "name-mismatch";
+    readonly detail: string;
+    readonly suggestion?: string;
+    readonly cause?: unknown;
+}> {
+}
+/**
+ * Map of agent-id → merge patch applied during per-agent rendering.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export type SubagentAgentOverrides = Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+/**
+ * Result of parsing a subagent content file.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface SubagentContentResult {
+    /** The full frontmatter map, opaque except for `name`. Empty when no frontmatter. */
+    readonly frontmatter: Option.Option<Readonly<Record<string, unknown>>>;
+    /** The `agentOverrides` map keyed by agent id, when present and structurally valid. */
+    readonly agentOverrides: Option.Option<SubagentAgentOverrides>;
+    /** Content body after the frontmatter block, or full content if no frontmatter. */
+    readonly body: string;
+}
+/**
+ * Parse a subagent content file into validated frontmatter and body.
+ *
+ * Validates only that frontmatter is present and that its `name` matches
+ * the expected name. All other keys are preserved verbatim.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const parseSubagentMd: (content: string, expectedName: string) => Effect.Effect<SubagentContentResult, SubagentContentError>;
+export {};
+//# sourceMappingURL=subagent-content.d.ts.map

package/dist/src/unstable/content/subagent-content.js

@@ -0,0 +1,101 @@
+/**
+ * Subagent content file module for subagent content parsing.
+ *
+ * The content file's YAML frontmatter is largely free-form: only `name` is
+ * required and validated. `agentOverrides`, when present, is recognized for
+ * use in per-agent rendering. Any other frontmatter keys flow through
+ * verbatim to the agent-native file produced by the renderer.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import { parseFrontmatterEffect } from "./frontmatter.js";
+/**
+ * Typed failure produced while parsing a subagent content file. Application
+ * layers translate this into their own error vocabulary.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export class SubagentContentError extends Data.TaggedError("SubagentContentError") {
+}
+/**
+ * Schema for the only required frontmatter field — `name`.
+ *
+ * Used to validate that `name` is present and a string. The full frontmatter
+ * map is preserved verbatim and surfaced as `frontmatter`.
+ */
+const NameOnlySchema = Schema.Struct({
+    name: Schema.String,
+}).annotate({
+    identifier: "SubagentFrontmatterName",
+    description: "Required `name` field for subagent frontmatter.",
+});
+const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const extractAgentOverrides = (fm) => {
+    const raw = fm["agentOverrides"];
+    if (!isPlainObject(raw))
+        return Option.none();
+    const out = {};
+    for (const [agentId, patch] of Object.entries(raw)) {
+        if (isPlainObject(patch))
+            out[agentId] = patch;
+    }
+    return Option.some(out);
+};
+/**
+ * Parse a subagent content file into validated frontmatter and body.
+ *
+ * Validates only that frontmatter is present and that its `name` matches
+ * the expected name. All other keys are preserved verbatim.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const parseSubagentMd = (content, expectedName) => Effect.gen(function* () {
+    const parsed = yield* parseFrontmatterEffect(content).pipe(Effect.mapError((cause) => new SubagentContentError({
+        reason: "frontmatter-parse",
+        detail: "YAML frontmatter could not be parsed",
+        suggestion: "Ensure the frontmatter block contains valid YAML between --- delimiters.",
+        cause,
+    })));
+    if (parsed.frontmatter === undefined) {
+        return yield* new SubagentContentError({
+            reason: "missing-frontmatter",
+            detail: `Missing subagent frontmatter for "${expectedName}"`,
+            suggestion: `Add YAML frontmatter with name: ${expectedName}.`,
+        });
+    }
+    yield* Effect.try({
+        try: () => Schema.decodeUnknownSync(NameOnlySchema)(parsed.frontmatter),
+        catch: (error) => new SubagentContentError({
+            reason: "invalid-frontmatter",
+            detail: "Invalid subagent frontmatter",
+            suggestion: "Frontmatter must include a string `name` field.",
+            cause: error,
+        }),
+    });
+    if (!isPlainObject(parsed.frontmatter)) {
+        return yield* new SubagentContentError({
+            reason: "invalid-frontmatter",
+            detail: "Subagent frontmatter must be a YAML mapping",
+            suggestion: `Add YAML frontmatter with name: ${expectedName}.`,
+        });
+    }
+    const fm = parsed.frontmatter;
+    const name = fm["name"];
+    if (name !== expectedName) {
+        return yield* new SubagentContentError({
+            reason: "name-mismatch",
+            detail: `Subagent frontmatter name "${String(name)}" does not match expected name "${expectedName}"`,
+            suggestion: `Set subagent.json name, frontmatter name, and filename to ${expectedName}.`,
+        });
+    }
+    return {
+        frontmatter: Option.some(fm),
+        agentOverrides: extractAgentOverrides(fm),
+        body: parsed.body,
+    };
+});
+//# sourceMappingURL=subagent-content.js.map

package/dist/src/unstable/knowledge/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Area barrel for the package public surface.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export { KNOWLEDGE_SEARCH_TOKENIZER_PROFILE, type KnowledgeSearchClause, type KnowledgeSearchQuery, type KnowledgeSearchQueryParseResult, matchesKnowledgeSearchQuery, parseKnowledgeSearchQuery, tokenizeKnowledgeSearchText, } from "./knowledge-search.js";
+export { KNOWLEDGE_DIAGNOSTIC_CODES, type KnowledgeActorRecord, type KnowledgeAuthoredLink, type KnowledgeBundleEntry, type KnowledgeConcept, type KnowledgeDiagnostic, type KnowledgeDiagnosticCode, type KnowledgeDocumentKind, type KnowledgeFrontmatterParseDetails, type KnowledgeInspection, type KnowledgeTrustTier, collectKnowledgeBundleEntries, inspectKnowledgeBundle, inspectKnowledgeEntries, openKnowledgeConcept, searchKnowledgeConcepts, } from "./okf.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/unstable/knowledge/index.js

@@ -0,0 +1,8 @@
+/**
+ * Area barrel for the package public surface.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export { KNOWLEDGE_SEARCH_TOKENIZER_PROFILE, matchesKnowledgeSearchQuery, parseKnowledgeSearchQuery, tokenizeKnowledgeSearchText, } from "./knowledge-search.js";
+export { KNOWLEDGE_DIAGNOSTIC_CODES, collectKnowledgeBundleEntries, inspectKnowledgeBundle, inspectKnowledgeEntries, openKnowledgeConcept, searchKnowledgeConcepts, } from "./okf.js";
+//# sourceMappingURL=index.js.map

package/dist/src/unstable/knowledge/knowledge-search.d.ts

@@ -0,0 +1,32 @@
+import type { KnowledgeConcept } from "./okf.js";
+export declare const KNOWLEDGE_SEARCH_TOKENIZER_PROFILE: {
+    readonly id: "axm-knowledge-lexical-v1";
+    readonly unicodeNormalization: "NFKC";
+    readonly caseNormalization: "unicode-case-fold";
+    readonly termBoundary: "unicode-whitespace-punctuation-camel-code";
+    readonly stemming: false;
+};
+export type KnowledgeSearchClause = {
+    readonly kind: "term";
+    readonly token: string;
+} | {
+    readonly kind: "phrase";
+    readonly tokens: ReadonlyArray<string>;
+} | {
+    readonly kind: "literal";
+    readonly value: string;
+};
+export interface KnowledgeSearchQuery {
+    readonly clauses: ReadonlyArray<KnowledgeSearchClause>;
+}
+export type KnowledgeSearchQueryParseResult = {
+    readonly ok: true;
+    readonly query: KnowledgeSearchQuery;
+} | {
+    readonly ok: false;
+    readonly detail: string;
+};
+export declare const tokenizeKnowledgeSearchText: (value: string) => ReadonlyArray<string>;
+export declare const parseKnowledgeSearchQuery: (input: string) => KnowledgeSearchQueryParseResult;
+export declare const matchesKnowledgeSearchQuery: (concept: KnowledgeConcept, query: KnowledgeSearchQuery) => boolean;
+//# sourceMappingURL=knowledge-search.d.ts.map

package/dist/src/unstable/knowledge/knowledge-search.js

@@ -0,0 +1,147 @@
+export const KNOWLEDGE_SEARCH_TOKENIZER_PROFILE = {
+    id: "axm-knowledge-lexical-v1",
+    unicodeNormalization: "NFKC",
+    caseNormalization: "unicode-case-fold",
+    termBoundary: "unicode-whitespace-punctuation-camel-code",
+    stemming: false,
+};
+const normalizeTokenSource = (value) => value
+    .normalize("NFKC")
+    .replace(/([\p{Ll}\p{N}])(\p{Lu})/gu, "$1 $2")
+    .replace(/(\p{Lu})(\p{Lu}\p{Ll})/gu, "$1 $2")
+    .replace(/(\p{L})(\p{N})/gu, "$1 $2")
+    .replace(/(\p{N})(\p{L})/gu, "$1 $2")
+    // ECMAScript does not expose Unicode's CaseFolding.txt operation directly.
+    // Upper-then-lower handles multi-character folds such as ß -> ss while
+    // remaining deterministic and locale-independent.
+    .toUpperCase()
+    .toLowerCase();
+export const tokenizeKnowledgeSearchText = (value) => normalizeTokenSource(value).match(/[\p{L}\p{M}\p{N}]+/gu) ?? [];
+const normalizeLiteral = (value) => value.normalize("NFC").toLowerCase();
+const parseQuotedValue = (input, quoteIndex) => {
+    let value = "";
+    let escaped = false;
+    for (let index = quoteIndex + 1; index < input.length; index += 1) {
+        const character = input[index];
+        if (character === undefined)
+            break;
+        if (escaped) {
+            value += character;
+            escaped = false;
+            continue;
+        }
+        if (character === "\\") {
+            escaped = true;
+            continue;
+        }
+        if (character === '"') {
+            return { ok: true, value, nextIndex: index + 1 };
+        }
+        value += character;
+    }
+    return { ok: false };
+};
+const addOrdinaryTerms = (clauses, value) => {
+    for (const token of tokenizeKnowledgeSearchText(value)) {
+        clauses.push({ kind: "term", token });
+    }
+};
+const startsWithLiteralOperator = (input, index) => input.slice(index, index + "literal:".length).toLowerCase() === "literal:";
+export const parseKnowledgeSearchQuery = (input) => {
+    const clauses = [];
+    let index = 0;
+    while (index < input.length) {
+        if (/\s/u.test(input[index] ?? "")) {
+            index += 1;
+            continue;
+        }
+        if (startsWithLiteralOperator(input, index)) {
+            index += "literal:".length;
+            if (input[index] === '"') {
+                const quoted = parseQuotedValue(input, index);
+                if (!quoted.ok) {
+                    return { ok: false, detail: "Explicit literals must end with a closing quote." };
+                }
+                if (quoted.value.trim().length === 0) {
+                    return { ok: false, detail: "Explicit literals cannot be empty." };
+                }
+                clauses.push({ kind: "literal", value: normalizeLiteral(quoted.value) });
+                index = quoted.nextIndex;
+                continue;
+            }
+            const end = input.slice(index).search(/\s/u);
+            const nextIndex = end === -1 ? input.length : index + end;
+            const value = input.slice(index, nextIndex);
+            if (value.length === 0) {
+                return { ok: false, detail: "Explicit literals cannot be empty." };
+            }
+            clauses.push({ kind: "literal", value: normalizeLiteral(value) });
+            index = nextIndex;
+            continue;
+        }
+        if (input[index] === '"') {
+            const quoted = parseQuotedValue(input, index);
+            if (!quoted.ok) {
+                return { ok: false, detail: "Quoted phrases must end with a closing quote." };
+            }
+            if (quoted.value.length === 0) {
+                return { ok: false, detail: "Quoted phrases cannot be empty." };
+            }
+            const tokens = tokenizeKnowledgeSearchText(quoted.value);
+            if (tokens.length === 0) {
+                return {
+                    ok: false,
+                    detail: "Quoted phrases must contain at least one searchable token.",
+                };
+            }
+            clauses.push({ kind: "phrase", tokens });
+            index = quoted.nextIndex;
+            continue;
+        }
+        let end = index;
+        while (end < input.length && !/\s/u.test(input[end] ?? "") && input[end] !== '"') {
+            end += 1;
+        }
+        addOrdinaryTerms(clauses, input.slice(index, end));
+        index = end;
+    }
+    return clauses.length === 0
+        ? { ok: false, detail: "Search query must contain at least one term, phrase, or literal." }
+        : { ok: true, query: { clauses } };
+};
+const containsPhrase = (fieldTokens, phraseTokens) => {
+    if (phraseTokens.length > fieldTokens.length)
+        return false;
+    const finalStart = fieldTokens.length - phraseTokens.length;
+    for (let start = 0; start <= finalStart; start += 1) {
+        if (phraseTokens.every((token, offset) => fieldTokens[start + offset] === token))
+            return true;
+    }
+    return false;
+};
+const searchableFields = (concept) => [
+    concept.id,
+    concept.title,
+    ...(concept.description === undefined ? [] : [concept.description]),
+    ...(concept.tags ?? []),
+    ...(concept.type === undefined ? [] : [concept.type]),
+    concept.body,
+];
+export const matchesKnowledgeSearchQuery = (concept, query) => {
+    const fields = searchableFields(concept);
+    const tokenFields = fields.map(tokenizeKnowledgeSearchText);
+    const literalFields = fields.map(normalizeLiteral);
+    return query.clauses.every((clause) => {
+        switch (clause.kind) {
+            case "term":
+                return tokenFields.some((tokens) => tokens.includes(clause.token));
+            case "phrase":
+                return tokenFields.some((tokens) => containsPhrase(tokens, clause.tokens));
+            case "literal":
+                return literalFields.some((field) => field.includes(clause.value));
+            default:
+                return clause;
+        }
+    });
+};
+//# sourceMappingURL=knowledge-search.js.map

package/dist/src/unstable/knowledge/okf.d.ts

@@ -0,0 +1,86 @@
+/** Open Knowledge Format discovery and AgentXM-profile validation (v0.2). */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import { FrontmatterParseFailure } from "../content/frontmatter.js";
+import { type KnowledgeSearchQuery } from "./knowledge-search.js";
+/** OKF dialect versions this inspector understands. */
+export type OkfVersion = "0.2";
+/** Actor that produced or confirmed a concept, per the OKF actor convention. */
+export interface KnowledgeActorRecord {
+    readonly by: string;
+    readonly at?: string;
+}
+/**
+ * Trust tier derived from `verified`, per OKF 0.2. A concept is
+ * `human-reviewed` when any verifier is a `human:<id>` actor,
+ * `machine-confirmed` when verified only by non-human actors, and
+ * `unverified` when `verified` is absent.
+ */
+export type KnowledgeTrustTier = "unverified" | "machine-confirmed" | "human-reviewed";
+export type KnowledgeDocumentKind = "concept" | "index" | "log";
+/** An authored Markdown link and the bundle-local concept it resolves to, when any. */
+export interface KnowledgeAuthoredLink {
+    readonly target: string;
+    readonly line: number;
+    readonly resolvedConceptId?: string;
+}
+export interface KnowledgeConcept {
+    readonly id: string;
+    readonly kind: KnowledgeDocumentKind;
+    readonly title: string;
+    /** The authored level-one heading, absent when `title` fell back to the concept ID. */
+    readonly authoredTitle?: string;
+    readonly frontmatter?: Readonly<Record<string, unknown>>;
+    readonly type?: string;
+    readonly description?: string;
+    readonly tags?: ReadonlyArray<string>;
+    readonly resource?: string;
+    readonly status?: string;
+    readonly staleAfter?: string;
+    readonly generated?: KnowledgeActorRecord;
+    readonly verified?: ReadonlyArray<KnowledgeActorRecord>;
+    readonly trust?: KnowledgeTrustTier;
+    readonly authoredLinks: ReadonlyArray<KnowledgeAuthoredLink>;
+    readonly relativePath: string;
+    readonly body: string;
+}
+export declare const KNOWLEDGE_DIAGNOSTIC_CODES: readonly ["bundle-too-large", "file-too-large", "invalid-tags", "missing-root-index", "missing-okf-version", "missing-title", "missing-description", "missing-manifest-description", "empty-bundle", "missing-tags", "symbolic-link", "too-many-files", "unsupported-okf-version", "missing-type", "invalid-frontmatter", "case-collision", "dangerous-uri", "detected-secret", "unsafe-path", "invalid-index", "invalid-log", "invalid-resource", "escaping-resource", "unresolved-resource", "broken-internal-link", "escaping-link", "unreachable-concept", "missing-index-entry", "stale-index-entry", "embedded-html", "duplicate-resource", "inconsistent-type", "large-concept", "large-index", "unreferenced-asset", "invalid-sources", "invalid-generated", "invalid-verified", "invalid-status", "invalid-stale-after", "invalid-attestation"];
+export type KnowledgeDiagnosticCode = (typeof KNOWLEDGE_DIAGNOSTIC_CODES)[number];
+export interface KnowledgeFrontmatterParseDetails {
+    readonly kind: "frontmatter-parse";
+    readonly reason: string;
+}
+export interface KnowledgeDiagnostic {
+    readonly code: KnowledgeDiagnosticCode;
+    readonly severity: "error" | "warning";
+    readonly relativePath: string;
+    readonly line?: number;
+    readonly column?: number;
+    readonly message: string;
+    readonly details?: KnowledgeFrontmatterParseDetails;
+}
+/** Convert a typed frontmatter failure into the stable Knowledge diagnostic contract. */
+export declare const frontmatterParseDiagnostic: (relativePath: string, failure: FrontmatterParseFailure) => KnowledgeDiagnostic;
+export interface KnowledgeInspection {
+    readonly concepts: ReadonlyArray<KnowledgeConcept>;
+    readonly diagnostics: ReadonlyArray<KnowledgeDiagnostic>;
+    /** Canonical dialect required at the bundle root. */
+    readonly okfVersion: OkfVersion;
+}
+export interface KnowledgeBundleEntry {
+    readonly relativePath: string;
+    readonly type: FileSystem.File.Type;
+    readonly size: bigint;
+}
+/** Collect a bundle's normalized entry inventory without following symbolic links. */
+export declare const collectKnowledgeBundleEntries: (sourceRoot: string) => Effect.Effect<ReadonlyArray<KnowledgeBundleEntry>, unknown, FileSystem.FileSystem | Path.Path>;
+/**
+ * Inspect a canonical OKF 0.2 bundle. The root index requirement is an explicit
+ * AgentXM profile constraint; upstream OKF permits a root without it.
+ */
+export declare const inspectKnowledgeEntries: <E>(entries: ReadonlyArray<KnowledgeBundleEntry>, readMarkdown: (relativePath: string) => Effect.Effect<string, E>) => Effect.Effect<KnowledgeInspection, E>;
+export declare const inspectKnowledgeBundle: (sourceRoot: string) => Effect.Effect<KnowledgeInspection, unknown, FileSystem.FileSystem | Path.Path>;
+export declare const searchKnowledgeConcepts: (concepts: ReadonlyArray<KnowledgeConcept>, query: KnowledgeSearchQuery) => ReadonlyArray<KnowledgeConcept>;
+export declare const openKnowledgeConcept: (concepts: ReadonlyArray<KnowledgeConcept>, id: string) => KnowledgeConcept | undefined;
+//# sourceMappingURL=okf.d.ts.map