@agentxm/extension-model 0.28.4-bootstrap.0

package/dist/src/unstable/hooks/manifest-schema.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Hook manifest schema definition.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Schema from "effect/Schema";
+export declare const HOOK_MANIFEST_FILENAME = "hook.json";
+export declare const HOOK_EXTENSION_DIR = "hooks";
+export declare const HOOK_MANIFEST_SCHEMA_URL = "https://axm.sh/schemas/hook.schema.json";
+export declare const HookRuntimeSchema: Schema.Literals<readonly ["bash", "node", "python"]>;
+/** @experimental */
+export type HookRuntime = Schema.Schema.Type<typeof HookRuntimeSchema>;
+export declare const HookEventSchema: Schema.Literals<readonly ["session.start", "prompt.submit", "turn.end", "tool.pre", "tool.post", "subagent.stop", "compaction.pre"]>;
+/** @experimental */
+export type HookEvent = Schema.Schema.Type<typeof HookEventSchema>;
+export declare const HookMatchSchema: Schema.Struct<{
+    readonly tools: Schema.optional<Schema.NonEmptyArray<Schema.Literals<readonly ["file.read", "file.write", "file.edit", "shell.exec", "web.fetch", "mcp.call"]>>>;
+}>;
+/** @experimental */
+export type HookMatch = Schema.Schema.Type<typeof HookMatchSchema>;
+export declare const HookDecisionRequirementSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly kind: Schema.Literal<"observe">;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"block">;
+    readonly outcomes: Schema.optional<Schema.NonEmptyArray<Schema.Literals<readonly ["allow", "deny", "ask"]>>>;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"modify">;
+    readonly operations: Schema.optional<Schema.NonEmptyArray<Schema.Literals<readonly ["modify-input", "inject-context", "modify-output", "synthesize", "redact"]>>>;
+}>]>;
+/** @experimental */
+export type HookDecisionRequirement = Schema.Schema.Type<typeof HookDecisionRequirementSchema>;
+export declare const HookBindingTargetSchema: Schema.Struct<{
+    readonly matcherRaw: Schema.optional<Schema.NonEmptyString>;
+}>;
+export declare const CanonicalHookBindingSchema: Schema.Struct<{
+    readonly on: Schema.Literals<readonly ["session.start", "prompt.submit", "turn.end", "tool.pre", "tool.post", "subagent.stop", "compaction.pre"]>;
+    readonly match: Schema.optional<Schema.Struct<{
+        readonly tools: Schema.optional<Schema.NonEmptyArray<Schema.Literals<readonly ["file.read", "file.write", "file.edit", "shell.exec", "web.fetch", "mcp.call"]>>>;
+    }>>;
+    readonly matcherRaw: Schema.optional<Schema.NonEmptyString>;
+    readonly targets: Schema.optional<Schema.$Record<Schema.String, Schema.Struct<{
+        readonly matcherRaw: Schema.optional<Schema.NonEmptyString>;
+    }>>>;
+    readonly requires: Schema.optional<Schema.Struct<{
+        readonly decision: Schema.Union<readonly [Schema.Struct<{
+            readonly kind: Schema.Literal<"observe">;
+        }>, Schema.Struct<{
+            readonly kind: Schema.Literal<"block">;
+            readonly outcomes: Schema.optional<Schema.NonEmptyArray<Schema.Literals<readonly ["allow", "deny", "ask"]>>>;
+        }>, Schema.Struct<{
+            readonly kind: Schema.Literal<"modify">;
+            readonly operations: Schema.optional<Schema.NonEmptyArray<Schema.Literals<readonly ["modify-input", "inject-context", "modify-output", "synthesize", "redact"]>>>;
+        }>]>;
+    }>>;
+}>;
+export declare const HookBindingSchema: Schema.Struct<{
+    readonly on: Schema.Literals<readonly ["session.start", "prompt.submit", "turn.end", "tool.pre", "tool.post", "subagent.stop", "compaction.pre"]>;
+    readonly match: Schema.optional<Schema.Struct<{
+        readonly tools: Schema.optional<Schema.NonEmptyArray<Schema.Literals<readonly ["file.read", "file.write", "file.edit", "shell.exec", "web.fetch", "mcp.call"]>>>;
+    }>>;
+    readonly matcherRaw: Schema.optional<Schema.NonEmptyString>;
+    readonly targets: Schema.optional<Schema.$Record<Schema.String, Schema.Struct<{
+        readonly matcherRaw: Schema.optional<Schema.NonEmptyString>;
+    }>>>;
+    readonly requires: Schema.optional<Schema.Struct<{
+        readonly decision: Schema.Union<readonly [Schema.Struct<{
+            readonly kind: Schema.Literal<"observe">;
+        }>, Schema.Struct<{
+            readonly kind: Schema.Literal<"block">;
+            readonly outcomes: Schema.optional<Schema.NonEmptyArray<Schema.Literals<readonly ["allow", "deny", "ask"]>>>;
+        }>, Schema.Struct<{
+            readonly kind: Schema.Literal<"modify">;
+            readonly operations: Schema.optional<Schema.NonEmptyArray<Schema.Literals<readonly ["modify-input", "inject-context", "modify-output", "synthesize", "redact"]>>>;
+        }>]>;
+    }>>;
+}>;
+/** @experimental */
+export type HookBinding = Schema.Schema.Type<typeof HookBindingSchema>;
+export declare const HookCapabilitiesSchema: Schema.Struct<{
+    readonly network: Schema.optional<Schema.Boolean>;
+    readonly filesystemWrite: Schema.optional<Schema.Boolean>;
+    readonly exec: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+    readonly env: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+}>;
+/** @experimental */
+export type HookCapabilities = Schema.Schema.Type<typeof HookCapabilitiesSchema>;
+/**
+ * Schema for hook manifest files (hook.json).
+ *
+ * Hooks distribute an executable body plus agent event bindings. Install
+ * materializes the body under agent_extensions and registers native agent hook
+ * settings that invoke the materialized entrypoint.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const HookManifestSchema: Schema.Struct<{
+    readonly type: Schema.Literal<"hook">;
+    readonly name: Schema.brand<Schema.NonEmptyString, "ExtensionName">;
+    readonly title: Schema.optional<Schema.NonEmptyString>;
+    readonly runtime: Schema.Literals<readonly ["bash", "node", "python"]>;
+    readonly entrypoint: Schema.NonEmptyString;
+    readonly bindings: Schema.$Array<Schema.Struct<{
+        readonly on: Schema.Literals<readonly ["session.start", "prompt.submit", "turn.end", "tool.pre", "tool.post", "subagent.stop", "compaction.pre"]>;
+        readonly match: Schema.optional<Schema.Struct<{
+            readonly tools: Schema.optional<Schema.NonEmptyArray<Schema.Literals<readonly ["file.read", "file.write", "file.edit", "shell.exec", "web.fetch", "mcp.call"]>>>;
+        }>>;
+        readonly matcherRaw: Schema.optional<Schema.NonEmptyString>;
+        readonly targets: Schema.optional<Schema.$Record<Schema.String, Schema.Struct<{
+            readonly matcherRaw: Schema.optional<Schema.NonEmptyString>;
+        }>>>;
+        readonly requires: Schema.optional<Schema.Struct<{
+            readonly decision: Schema.Union<readonly [Schema.Struct<{
+                readonly kind: Schema.Literal<"observe">;
+            }>, Schema.Struct<{
+                readonly kind: Schema.Literal<"block">;
+                readonly outcomes: Schema.optional<Schema.NonEmptyArray<Schema.Literals<readonly ["allow", "deny", "ask"]>>>;
+            }>, Schema.Struct<{
+                readonly kind: Schema.Literal<"modify">;
+                readonly operations: Schema.optional<Schema.NonEmptyArray<Schema.Literals<readonly ["modify-input", "inject-context", "modify-output", "synthesize", "redact"]>>>;
+            }>]>;
+        }>>;
+    }>>;
+    readonly timeoutMs: Schema.optional<Schema.Int>;
+    readonly capabilities: Schema.optional<Schema.Struct<{
+        readonly network: Schema.optional<Schema.Boolean>;
+        readonly filesystemWrite: Schema.optional<Schema.Boolean>;
+        readonly exec: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+        readonly env: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+    }>>;
+    readonly enhances: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+    readonly requires: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+    readonly fallback: Schema.optional<Schema.Literals<readonly ["auto", "none"]>>;
+    readonly recommendedPacks: Schema.optional<Schema.$Array<Schema.brand<Schema.NonEmptyString, "PackSpec">>>;
+    readonly standalone: Schema.optional<Schema.Boolean>;
+    readonly publish: Schema.optional<Schema.Struct<{
+        readonly visibility: Schema.optional<Schema.Literals<readonly ["public", "private"]>>;
+        readonly ignore: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+    }>>;
+    readonly metadata: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly owner: Schema.brand<Schema.String, "Handle">;
+    readonly version: Schema.brand<Schema.String, "Version">;
+    readonly description: Schema.optional<Schema.String>;
+    readonly keywords: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+    readonly repository: Schema.optional<Schema.Union<readonly [Schema.String, Schema.Struct<{
+        readonly type: Schema.optional<Schema.NonEmptyString>;
+        readonly url: Schema.NonEmptyString;
+        readonly directory: Schema.optional<Schema.NonEmptyString>;
+    }>]>>;
+    readonly homepage: Schema.optional<Schema.String>;
+    readonly license: Schema.optional<Schema.String>;
+    readonly bugs: Schema.optional<Schema.Union<readonly [Schema.String, Schema.Struct<{
+        readonly url: Schema.optional<Schema.NonEmptyString>;
+        readonly email: Schema.optional<Schema.NonEmptyString>;
+    }>]>>;
+    readonly authors: Schema.optional<Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly email: Schema.optional<Schema.String>;
+        readonly url: Schema.optional<Schema.String>;
+    }>>>;
+    readonly packages: Schema.optional<Schema.$Array<Schema.Struct<{
+        readonly purl: Schema.brand<Schema.NonEmptyString, "PackageIdentityPurl">;
+        readonly versionRange: Schema.optional<Schema.brand<Schema.decodeTo<Schema.toType<Schema.Struct<{
+            readonly raw: Schema.NonEmptyString;
+            readonly scheme: Schema.NonEmptyString;
+            readonly constraints: Schema.$Array<Schema.Struct<{
+                readonly comparator: Schema.Literals<readonly ["=", "!=", "<", "<=", ">", ">="]>;
+                readonly version: Schema.NonEmptyString;
+            }>>;
+        }>>, Schema.NonEmptyString, never, never>, "VersRange">>;
+    }>>>;
+    readonly $schema: Schema.optional<Schema.String>;
+}>;
+/** @experimental */
+export type HookManifest = Schema.Schema.Type<typeof HookManifestSchema>;
+//# sourceMappingURL=manifest-schema.d.ts.map

package/dist/src/unstable/hooks/manifest-schema.js

@@ -0,0 +1,112 @@
+/**
+ * Hook manifest schema definition.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Schema from "effect/Schema";
+import { CanonicalHookEventIdSchema, CanonicalHookToolIdSchema, HookBlockOutcomeSchema, HookModifyOperationSchema, } from "../agent-capabilities/index.js";
+import { CommonManifestBaseFields, ExtensionNameSchema, NonPackManifestFields, } from "../extensions/common.js";
+export const HOOK_MANIFEST_FILENAME = "hook.json";
+export const HOOK_EXTENSION_DIR = "hooks";
+export const HOOK_MANIFEST_SCHEMA_URL = "https://axm.sh/schemas/hook.schema.json";
+export const HookRuntimeSchema = Schema.Literals(["bash", "node", "python"]).annotate({
+    identifier: "HookRuntime",
+    title: "Hook Runtime",
+    description: "Interpreter family used to execute the materialized hook entrypoint.",
+});
+export const HookEventSchema = CanonicalHookEventIdSchema.annotate({
+    identifier: "HookEvent",
+    title: "Hook Event",
+    description: "Canonical AXM hook event this extension binds to.",
+});
+export const HookMatchSchema = Schema.Struct({
+    tools: Schema.optional(Schema.NonEmptyArray(CanonicalHookToolIdSchema).pipe(Schema.check(Schema.isUnique()))),
+}).annotate({
+    identifier: "HookMatch",
+    title: "Hook Match",
+    description: "Portable hook matcher expressed over AXM canonical tool IDs.",
+});
+export const HookDecisionRequirementSchema = Schema.Union([
+    Schema.Struct({ kind: Schema.Literal("observe") }),
+    Schema.Struct({
+        kind: Schema.Literal("block"),
+        outcomes: Schema.optional(Schema.NonEmptyArray(HookBlockOutcomeSchema).pipe(Schema.check(Schema.isUnique()))),
+    }),
+    Schema.Struct({
+        kind: Schema.Literal("modify"),
+        operations: Schema.optional(Schema.NonEmptyArray(HookModifyOperationSchema).pipe(Schema.check(Schema.isUnique()))),
+    }),
+]).annotate({
+    identifier: "HookDecisionRequirement",
+    title: "Hook Decision Requirement",
+    description: "Decision capability a hook binding requires from the target agent event.",
+});
+export const HookBindingTargetSchema = Schema.Struct({
+    matcherRaw: Schema.optional(Schema.NonEmptyString),
+}).annotate({
+    identifier: "HookBindingTarget",
+    title: "Hook Binding Target",
+    description: "Target-agent-specific hook binding escape hatches.",
+});
+export const CanonicalHookBindingSchema = Schema.Struct({
+    on: HookEventSchema,
+    match: Schema.optional(HookMatchSchema),
+    matcherRaw: Schema.optional(Schema.NonEmptyString),
+    targets: Schema.optional(Schema.Record(Schema.String, HookBindingTargetSchema)),
+    requires: Schema.optional(Schema.Struct({
+        decision: HookDecisionRequirementSchema,
+    })),
+}).annotate({
+    identifier: "CanonicalHookBinding",
+    title: "Canonical Hook Binding",
+    description: "Universal hook event binding expressed in AXM canonical vocabulary.",
+});
+export const HookBindingSchema = CanonicalHookBindingSchema.annotate({
+    identifier: "HookBinding",
+    title: "Hook Binding",
+    description: "Universal hook event binding with portable canonical matching and raw native escape hatches.",
+});
+export const HookCapabilitiesSchema = Schema.Struct({
+    network: Schema.optional(Schema.Boolean),
+    filesystemWrite: Schema.optional(Schema.Boolean),
+    exec: Schema.optional(Schema.Array(Schema.NonEmptyString)),
+    env: Schema.optional(Schema.Array(Schema.NonEmptyString)),
+}).annotate({
+    identifier: "HookCapabilities",
+    title: "Hook Capabilities",
+    description: "Advisory author-declared hook capability surface. v1 does not enforce it.",
+});
+/**
+ * Schema for hook manifest files (hook.json).
+ *
+ * Hooks distribute an executable body plus agent event bindings. Install
+ * materializes the body under agent_extensions and registers native agent hook
+ * settings that invoke the materialized entrypoint.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const HookManifestSchema = Schema.Struct({
+    $schema: Schema.optional(Schema.String),
+    ...CommonManifestBaseFields,
+    ...NonPackManifestFields,
+    type: Schema.Literal("hook"),
+    name: ExtensionNameSchema.pipe(Schema.annotateKey({ messageMissingKey: "hook name is required" }), Schema.annotate({
+        description: "Short name for this hook within its owner namespace. Combined with owner, forms the FQN @owner/hooks/<name>.",
+    })),
+    title: Schema.optional(Schema.NonEmptyString.annotate({
+        description: "Optional display title for this hook.",
+    })),
+    runtime: HookRuntimeSchema.pipe(Schema.annotateKey({ messageMissingKey: "runtime is required" })),
+    entrypoint: Schema.NonEmptyString.pipe(Schema.annotateKey({ messageMissingKey: "entrypoint is required" }), Schema.annotate({
+        description: "Hook body entrypoint path, relative to the hook manifest directory.",
+        examples: ["src/hook.sh", "src/hook.js", "src/hook.py"],
+    })),
+    bindings: Schema.Array(HookBindingSchema).pipe(Schema.annotateKey({ messageMissingKey: "bindings are required" })),
+    timeoutMs: Schema.optional(Schema.Int.pipe(Schema.check(Schema.isGreaterThan(0)))),
+    capabilities: Schema.optional(HookCapabilitiesSchema),
+}).annotate({
+    identifier: "HookManifest",
+    title: "Hook Manifest",
+    description: "Hook manifest for managed agent hooks. The executable body lives under src/ and is invoked from native agent settings.",
+});
+//# sourceMappingURL=manifest-schema.js.map

package/dist/src/unstable/knowledge/concept-ref.d.ts

@@ -0,0 +1,34 @@
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+export declare const KnowledgeBundleFqnSchema: Schema.String;
+export type KnowledgeBundleFqn = typeof KnowledgeBundleFqnSchema.Type;
+export declare const KnowledgeConceptIdSchema: Schema.String;
+export type KnowledgeConceptId = typeof KnowledgeConceptIdSchema.Type;
+export declare const KnowledgeRevisionSchema: Schema.String;
+export type KnowledgeRevision = typeof KnowledgeRevisionSchema.Type;
+export declare const ConceptRefSchema: Schema.Struct<{
+    readonly bundle: Schema.String;
+    readonly conceptId: Schema.String;
+}>;
+export type ConceptRef = typeof ConceptRefSchema.Type;
+export declare const ResolvedConceptRefSchema: Schema.Struct<{
+    readonly bundle: Schema.String;
+    readonly conceptId: Schema.String;
+    readonly bundleVersion: Schema.String;
+    readonly bundleFingerprint: Schema.String;
+    readonly contentRevision: Schema.String;
+}>;
+export type ResolvedConceptRef = typeof ResolvedConceptRefSchema.Type;
+declare const ConceptRefInvalidError_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: "ConceptRefInvalidError";
+} & Readonly<A>;
+export declare class ConceptRefInvalidError extends ConceptRefInvalidError_base<{
+    readonly input: string;
+}> {
+}
+/** Parse a compact `FQN#concept` or canonical AgentXM HTTPS concept reference. */
+export declare const parseConceptRef: (input: string) => Result.Result<ConceptRef, ConceptRefInvalidError>;
+export type ConceptRefFormat = "compact" | "url";
+export declare const formatConceptRef: (ref: ConceptRef, format?: ConceptRefFormat) => string;
+export {};
+//# sourceMappingURL=concept-ref.d.ts.map

package/dist/src/unstable/knowledge/concept-ref.js

@@ -0,0 +1,114 @@
+import * as Data from "effect/Data";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import { ExtensionFqnSchema, parseExtensionFqnParts } from "../extensions/common.js";
+const KNOWLEDGE_BUNDLE_FQN_MESSAGE = "Expected a Knowledge bundle FQN in @owner/knowledge/name form";
+const CONCEPT_ID_MESSAGE = "Expected a non-empty safe bundle-relative concept ID without .md";
+const REVISION_MESSAGE = "Expected an opaque SHA-256 revision";
+export const KnowledgeBundleFqnSchema = ExtensionFqnSchema.check(Schema.makeFilter((value) => parseExtensionFqnParts(value)?.type === "knowledge" ? undefined : KNOWLEDGE_BUNDLE_FQN_MESSAGE)).annotate({
+    identifier: "KnowledgeBundleFqn",
+    title: "Knowledge Bundle FQN",
+    description: "A fully qualified Knowledge bundle identity.",
+    message: KNOWLEDGE_BUNDLE_FQN_MESSAGE,
+});
+export const KnowledgeConceptIdSchema = Schema.String.check(Schema.makeFilter((value) => {
+    if (value.length === 0 ||
+        value.startsWith("/") ||
+        value.endsWith("/") ||
+        value.includes("\\") ||
+        value.toLowerCase().endsWith(".md") ||
+        value
+            .split("/")
+            .some((segment) => segment.length === 0 || segment === "." || segment === "..")) {
+        return CONCEPT_ID_MESSAGE;
+    }
+    return undefined;
+})).annotate({
+    identifier: "KnowledgeConceptId",
+    title: "Knowledge Concept ID",
+    description: "A bundle-relative Markdown path without the .md suffix.",
+    message: CONCEPT_ID_MESSAGE,
+});
+export const KnowledgeRevisionSchema = Schema.String.check(Schema.isPattern(/^sha256:[0-9a-f]{64}$/u, { message: REVISION_MESSAGE })).annotate({
+    identifier: "KnowledgeRevision",
+    title: "Knowledge Content Revision",
+    description: "An opaque deterministic content revision.",
+    message: REVISION_MESSAGE,
+});
+export const ConceptRefSchema = Schema.Struct({
+    bundle: KnowledgeBundleFqnSchema,
+    conceptId: KnowledgeConceptIdSchema,
+}).annotate({
+    identifier: "ConceptRef",
+    title: "Knowledge Concept Reference",
+    description: "Logical Knowledge concept identity: bundle FQN plus concept ID.",
+});
+export const ResolvedConceptRefSchema = Schema.Struct({
+    bundle: KnowledgeBundleFqnSchema,
+    conceptId: KnowledgeConceptIdSchema,
+    bundleVersion: Schema.String.check(Schema.isNonEmpty()),
+    bundleFingerprint: KnowledgeRevisionSchema,
+    contentRevision: KnowledgeRevisionSchema,
+}).annotate({
+    identifier: "ResolvedConceptRef",
+    title: "Resolved Knowledge Concept Reference",
+    description: "Logical concept identity resolved to one bundle and content revision.",
+});
+export class ConceptRefInvalidError extends Data.TaggedError("ConceptRefInvalidError") {
+}
+const decodeConceptRef = Schema.decodeUnknownResult(ConceptRefSchema);
+const decodeComponent = (value) => {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return undefined;
+    }
+};
+const validatedRef = (input, bundle, conceptId) => {
+    const decoded = decodeConceptRef({ bundle, conceptId });
+    return Result.isSuccess(decoded)
+        ? Result.succeed(decoded.success)
+        : Result.fail(new ConceptRefInvalidError({ input }));
+};
+/** Parse a compact `FQN#concept` or canonical AgentXM HTTPS concept reference. */
+export const parseConceptRef = (input) => {
+    if (input.startsWith("https://")) {
+        try {
+            const url = new URL(input);
+            const marker = "/concepts/";
+            const markerIndex = url.pathname.indexOf(marker);
+            if (url.origin !== "https://agentxm.ai" ||
+                url.username.length > 0 ||
+                url.password.length > 0 ||
+                url.search.length > 0 ||
+                url.hash.length > 0 ||
+                markerIndex <= 0) {
+                return Result.fail(new ConceptRefInvalidError({ input }));
+            }
+            const bundle = decodeComponent(url.pathname.slice(1, markerIndex));
+            const conceptId = decodeComponent(url.pathname.slice(markerIndex + marker.length));
+            return bundle === undefined || conceptId === undefined
+                ? Result.fail(new ConceptRefInvalidError({ input }))
+                : validatedRef(input, bundle, conceptId);
+        }
+        catch {
+            return Result.fail(new ConceptRefInvalidError({ input }));
+        }
+    }
+    const separator = input.indexOf("#");
+    if (separator <= 0)
+        return Result.fail(new ConceptRefInvalidError({ input }));
+    const bundle = input.slice(0, separator);
+    const conceptId = decodeComponent(input.slice(separator + 1));
+    return conceptId === undefined
+        ? Result.fail(new ConceptRefInvalidError({ input }))
+        : validatedRef(input, bundle, conceptId);
+};
+export const formatConceptRef = (ref, format = "compact") => format === "compact"
+    ? `${ref.bundle}#${encodeURIComponent(ref.conceptId)}`
+    : `https://agentxm.ai/${ref.bundle}/concepts/${ref.conceptId
+        .split("/")
+        .map(encodeURIComponent)
+        .join("/")}`;
+//# sourceMappingURL=concept-ref.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 { type ConceptRef, type ConceptRefFormat, ConceptRefInvalidError, ConceptRefSchema, type KnowledgeBundleFqn, KnowledgeBundleFqnSchema, type KnowledgeConceptId, KnowledgeConceptIdSchema, type KnowledgeRevision, KnowledgeRevisionSchema, type ResolvedConceptRef, ResolvedConceptRefSchema, formatConceptRef, parseConceptRef, } from "./concept-ref.js";
+export { KNOWLEDGE_EXTENSION_DIR, KNOWLEDGE_MANIFEST_FILENAME, KNOWLEDGE_MANIFEST_SCHEMA_URL, KNOWLEDGE_SOURCE_DIR, type KnowledgeManifest, KnowledgeManifestSchema, } from "./manifest-schema.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 { ConceptRefInvalidError, ConceptRefSchema, KnowledgeBundleFqnSchema, KnowledgeConceptIdSchema, KnowledgeRevisionSchema, ResolvedConceptRefSchema, formatConceptRef, parseConceptRef, } from "./concept-ref.js";
+export { KNOWLEDGE_EXTENSION_DIR, KNOWLEDGE_MANIFEST_FILENAME, KNOWLEDGE_MANIFEST_SCHEMA_URL, KNOWLEDGE_SOURCE_DIR, KnowledgeManifestSchema, } from "./manifest-schema.js";
+//# sourceMappingURL=index.js.map

package/dist/src/unstable/knowledge/manifest-schema.d.ts

@@ -0,0 +1,60 @@
+/** Manifest schema for Open Knowledge Format bundles. */
+import * as Schema from "effect/Schema";
+export declare const KNOWLEDGE_MANIFEST_FILENAME = "knowledge.json";
+export declare const KNOWLEDGE_EXTENSION_DIR = "knowledge";
+export declare const KNOWLEDGE_SOURCE_DIR = "src";
+export declare const KNOWLEDGE_MANIFEST_SCHEMA_URL = "https://axm.sh/schemas/knowledge.schema.json";
+export declare const KnowledgeManifestSchema: Schema.Struct<{
+    readonly type: Schema.Literal<"knowledge">;
+    readonly format: Schema.Struct<{
+        readonly name: Schema.Literal<"okf">;
+        readonly version: Schema.Literal<"0.2">;
+    }>;
+    readonly bundleRoot: Schema.Literal<"src">;
+    readonly instructionEntry: Schema.optionalKey<Schema.Boolean>;
+    readonly name: Schema.brand<Schema.NonEmptyString, "ExtensionName">;
+    readonly enhances: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+    readonly requires: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+    readonly fallback: Schema.optional<Schema.Literals<readonly ["auto", "none"]>>;
+    readonly recommendedPacks: Schema.optional<Schema.$Array<Schema.brand<Schema.NonEmptyString, "PackSpec">>>;
+    readonly standalone: Schema.optional<Schema.Boolean>;
+    readonly publish: Schema.optional<Schema.Struct<{
+        readonly visibility: Schema.optional<Schema.Literals<readonly ["public", "private"]>>;
+        readonly ignore: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+    }>>;
+    readonly metadata: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly owner: Schema.brand<Schema.String, "Handle">;
+    readonly version: Schema.brand<Schema.String, "Version">;
+    readonly description: Schema.optional<Schema.String>;
+    readonly keywords: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+    readonly repository: Schema.optional<Schema.Union<readonly [Schema.String, Schema.Struct<{
+        readonly type: Schema.optional<Schema.NonEmptyString>;
+        readonly url: Schema.NonEmptyString;
+        readonly directory: Schema.optional<Schema.NonEmptyString>;
+    }>]>>;
+    readonly homepage: Schema.optional<Schema.String>;
+    readonly license: Schema.optional<Schema.String>;
+    readonly bugs: Schema.optional<Schema.Union<readonly [Schema.String, Schema.Struct<{
+        readonly url: Schema.optional<Schema.NonEmptyString>;
+        readonly email: Schema.optional<Schema.NonEmptyString>;
+    }>]>>;
+    readonly authors: Schema.optional<Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly email: Schema.optional<Schema.String>;
+        readonly url: Schema.optional<Schema.String>;
+    }>>>;
+    readonly packages: Schema.optional<Schema.$Array<Schema.Struct<{
+        readonly purl: Schema.brand<Schema.NonEmptyString, "PackageIdentityPurl">;
+        readonly versionRange: Schema.optional<Schema.brand<Schema.decodeTo<Schema.toType<Schema.Struct<{
+            readonly raw: Schema.NonEmptyString;
+            readonly scheme: Schema.NonEmptyString;
+            readonly constraints: Schema.$Array<Schema.Struct<{
+                readonly comparator: Schema.Literals<readonly ["=", "!=", "<", "<=", ">", ">="]>;
+                readonly version: Schema.NonEmptyString;
+            }>>;
+        }>>, Schema.NonEmptyString, never, never>, "VersRange">>;
+    }>>>;
+    readonly $schema: Schema.optional<Schema.String>;
+}>;
+export type KnowledgeManifest = Schema.Schema.Type<typeof KnowledgeManifestSchema>;
+//# sourceMappingURL=manifest-schema.d.ts.map

package/dist/src/unstable/knowledge/manifest-schema.js

@@ -0,0 +1,34 @@
+/** Manifest schema for Open Knowledge Format bundles. */
+import * as Schema from "effect/Schema";
+import { CommonManifestBaseFields, ExtensionNameSchema, NonPackManifestFields, } from "../extensions/common.js";
+export const KNOWLEDGE_MANIFEST_FILENAME = "knowledge.json";
+export const KNOWLEDGE_EXTENSION_DIR = "knowledge";
+export const KNOWLEDGE_SOURCE_DIR = "src";
+export const KNOWLEDGE_MANIFEST_SCHEMA_URL = "https://axm.sh/schemas/knowledge.schema.json";
+export const KnowledgeManifestSchema = Schema.Struct({
+    $schema: Schema.optional(Schema.String),
+    ...CommonManifestBaseFields,
+    ...NonPackManifestFields,
+    type: Schema.Literal("knowledge"),
+    format: Schema.Struct({
+        name: Schema.Literal("okf"),
+        version: Schema.Literal("0.2"),
+    }).annotate({
+        description: "Open Knowledge Format dialect and version used by this bundle.",
+    }),
+    bundleRoot: Schema.Literal(KNOWLEDGE_SOURCE_DIR).annotate({
+        description: "Package-relative directory containing the authoritative OKF bundle.",
+    }),
+    instructionEntry: Schema.optionalKey(Schema.Boolean.annotate({
+        description: "Whether this bundle appears by default in the managed Knowledge Bundles instruction table. Defaults effectively to true.",
+        default: true,
+    })),
+    name: ExtensionNameSchema.pipe(Schema.annotateKey({ messageMissingKey: "knowledge bundle name is required" }), Schema.annotate({
+        description: "Short bundle name. Combined with owner, forms the FQN @owner/knowledge/<name>.",
+    })),
+}).annotate({
+    identifier: "KnowledgeManifest",
+    title: "Knowledge Manifest",
+    description: "Manifest for an isolated Open Knowledge Format bundle rooted at src/.",
+});
+//# sourceMappingURL=manifest-schema.js.map