@agentproto/extension 0.1.0

package/LICENSE

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

@@ -0,0 +1,23 @@
+# @agentproto/extension
+
+AIP-40 `EXTENSION.md` reference implementation. A meta-doctype that lets a workspace declare its own custom doctype as an extension of an existing AIP — adding fields, tightening constraints, overriding defaults, and choosing a path convention — without going through the public AIP process. The runtime (@agentproto/manifest verbs, MCP server, scaffolder) treats local extensions identically to public AIPs.
+
+> **Status: 0.1.0-alpha.** Generated by `scripts/scaffold-aip.mjs` — `build()` and `validate()` bodies are TODOs.
+
+Spec: <https://agentproto.sh/docs/aip-40>
+
+## Usage
+
+```ts
+import { defineExtension } from "@agentproto/extension"
+
+const x = defineExtension({
+  id: "my-extension",
+  description: "Short purpose.",
+  // ...
+})
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/chunk-XIW4DKUM.mjs

@@ -0,0 +1,51 @@
+import matter from 'gray-matter';
+import { z } from 'zod';
+import { createDoctype } from '@agentproto/define-doctype';
+
+/**
+ * @agentproto/extension v0.1.0-alpha
+ * AIP-40 EXTENSION.md `defineExtension` reference implementation.
+ */
+
+var extensionFrontmatterSchema = z.object({ "schema": z.literal("agentproto/extension/v1").describe("Pins the spec version this manifest conforms to."), "slug": z.string().regex(new RegExp("^[a-z][a-z0-9-]*:[a-z][a-z0-9-]*[a-z0-9]$")).describe("Namespaced identifier \u2014 `<namespace>:<name>`. Lowercase, digits, dashes; single colon separator. Example: `acme:deal`."), "title": z.string().min(1).max(80).describe("Human-readable display name."), "description": z.string().min(1).max(2e3).describe("One-paragraph statement of the extension's purpose."), "version": z.string().regex(new RegExp("^\\d+\\.\\d+\\.\\d+(?:[-+][a-zA-Z0-9.-]+)?$")).describe("Extension's own semver. Bump on breaking change."), "status": z.literal("Local").describe("Extensions are perpetually Local \u2014 they never enter the public registry's Draft/Review/Final lifecycle."), "extends": z.union([z.string().regex(new RegExp("^aip-\\d+$")).describe("Inherit a public AIP's schema (e.g. `aip-14`)."), z.literal("none").describe("Brand-new doctype, no inheritance.")]).describe("Parent AIP this extension inherits from, or `none` for a root doctype."), "add_fields": z.object({ "properties": z.record(z.string(), z.any()).describe("JSON Schema property definitions to merge into the parent's properties. Collisions are an error \u2014 use `tighten` to narrow an existing field.").optional(), "required": z.array(z.string()).refine((arr) => arr.every((item, i) => arr.indexOf(item) == i), { message: "All items must be unique!" }).describe("Field names that become required in addition to parent's required[]. Unioned with parent's required, never replaces.").default([]) }).strict().describe("Schema-level additions: new properties + new required entries.").optional(), "tighten": z.record(z.string(), z.object({ "pattern": z.string().optional(), "enum": z.array(z.any()).optional(), "minLength": z.number().int().gte(0).optional(), "maxLength": z.number().int().gte(0).optional(), "minimum": z.number().optional(), "maximum": z.number().optional() }).strict()).describe("Per-field constraint overrides. Each entry MUST tighten (not loosen) the parent's constraints; runtimes verify monotonicity at registration.").optional(), "defaults": z.record(z.string(), z.any()).describe("Default values applied when a field is omitted. Layered on top of parent's defaults; extension's value wins on the same key.").optional(), "path_convention": z.string().min(1).describe("Filesystem convention template, e.g. `\"deals/<slug>/DEAL.md\"`. Tokens: `<slug>` (doctype identity), `<DOCTYPE>` (extension's slug name part). Falls back to parent's convention when omitted.").optional(), "requires": z.array(z.number().int().gte(1)).refine((arr) => arr.every((item, i) => arr.indexOf(item) == i), { message: "All items must be unique!" }).describe("Public AIPs the extension depends on, in addition to its parent.").default([]), "metadata": z.record(z.string(), z.any()).describe("Free-form vendor extensions under namespaced keys (`metadata.<vendor>.<field>`).").default({}) }).strict().describe("Validates the YAML frontmatter portion of an AIP-40 EXTENSION.md manifest. An extension declares a workspace-local doctype that inherits a public AIP's schema and may add fields, tighten constraints, set defaults, and override the path convention.");
+var defineExtension = createDoctype({
+  aip: 40,
+  name: "extension",
+  // Extension slugs are namespaced: `<namespace>:<name>` (e.g.
+  // `acme:deal`). Override the default kebab-only pattern.
+  idPattern: /^[a-z][a-z0-9-]*:[a-z][a-z0-9-]*[a-z0-9]$/,
+  readIdentity: (def) => def.slug,
+  validate(def) {
+    const result = extensionFrontmatterSchema.safeParse(def);
+    if (!result.success) {
+      throw new Error(
+        `defineExtension (AIP-40): ${result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
+      );
+    }
+  },
+  build(def) {
+    return { ...def };
+  }
+});
+
+// src/manifest/index.ts
+function parseExtensionManifest(source) {
+  const parsed = matter(source);
+  if (Object.keys(parsed.data).length === 0) {
+    throw new Error("parseExtensionManifest: missing or empty frontmatter");
+  }
+  const result = extensionFrontmatterSchema.safeParse(parsed.data);
+  if (!result.success) {
+    throw new Error(
+      `parseExtensionManifest: invalid frontmatter \u2014 ${result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
+    );
+  }
+  return { frontmatter: result.data, body: parsed.content };
+}
+function extensionFromManifest(manifest) {
+  return defineExtension(manifest.frontmatter);
+}
+
+export { defineExtension, extensionFromManifest, extensionFrontmatterSchema, parseExtensionManifest };
+//# sourceMappingURL=chunk-XIW4DKUM.mjs.map
+//# sourceMappingURL=chunk-XIW4DKUM.mjs.map

package/dist/chunk-XIW4DKUM.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema.ts","../src/define-extension.ts","../src/manifest/index.ts"],"names":[],"mappings":"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","file":"chunk-XIW4DKUM.mjs","sourcesContent":["/**\n * AIP-40 EXTENSION.md frontmatter zod schema.\n *\n * Generated from `resources/aip-40/draft/EXTENSION.schema.json` via\n * json-schema-to-zod. Imported by both `define-extension.ts` (TS path\n * validation) and `manifest/index.ts` (.md path validation) so every\n * field-level constraint runs in both authoring paths from a single\n * source of truth — re-run scaffold-aip to refresh after spec changes.\n *\n * Cross-field rules (if/then/allOf in JSON Schema) don't translate\n * cleanly and live in `define-extension.ts`'s `validate(def)` instead.\n */\n\nimport { z } from \"zod\"\n\nexport const extensionFrontmatterSchema = z.object({ \"schema\": z.literal(\"agentproto/extension/v1\").describe(\"Pins the spec version this manifest conforms to.\"), \"slug\": z.string().regex(new RegExp(\"^[a-z][a-z0-9-]*:[a-z][a-z0-9-]*[a-z0-9]$\")).describe(\"Namespaced identifier — `<namespace>:<name>`. Lowercase, digits, dashes; single colon separator. Example: `acme:deal`.\"), \"title\": z.string().min(1).max(80).describe(\"Human-readable display name.\"), \"description\": z.string().min(1).max(2000).describe(\"One-paragraph statement of the extension's purpose.\"), \"version\": z.string().regex(new RegExp(\"^\\\\d+\\\\.\\\\d+\\\\.\\\\d+(?:[-+][a-zA-Z0-9.-]+)?$\")).describe(\"Extension's own semver. Bump on breaking change.\"), \"status\": z.literal(\"Local\").describe(\"Extensions are perpetually Local — they never enter the public registry's Draft/Review/Final lifecycle.\"), \"extends\": z.union([z.string().regex(new RegExp(\"^aip-\\\\d+$\")).describe(\"Inherit a public AIP's schema (e.g. `aip-14`).\"), z.literal(\"none\").describe(\"Brand-new doctype, no inheritance.\")]).describe(\"Parent AIP this extension inherits from, or `none` for a root doctype.\"), \"add_fields\": z.object({ \"properties\": z.record(z.string(), z.any()).describe(\"JSON Schema property definitions to merge into the parent's properties. Collisions are an error — use `tighten` to narrow an existing field.\").optional(), \"required\": z.array(z.string()).refine((arr) => arr.every((item, i) => arr.indexOf(item) == i), { message: \"All items must be unique!\" }).describe(\"Field names that become required in addition to parent's required[]. Unioned with parent's required, never replaces.\").default([] as never) }).strict().describe(\"Schema-level additions: new properties + new required entries.\").optional(), \"tighten\": z.record(z.string(), z.object({ \"pattern\": z.string().optional(), \"enum\": z.array(z.any()).optional(), \"minLength\": z.number().int().gte(0).optional(), \"maxLength\": z.number().int().gte(0).optional(), \"minimum\": z.number().optional(), \"maximum\": z.number().optional() }).strict()).describe(\"Per-field constraint overrides. Each entry MUST tighten (not loosen) the parent's constraints; runtimes verify monotonicity at registration.\").optional(), \"defaults\": z.record(z.string(), z.any()).describe(\"Default values applied when a field is omitted. Layered on top of parent's defaults; extension's value wins on the same key.\").optional(), \"path_convention\": z.string().min(1).describe(\"Filesystem convention template, e.g. `\\\"deals/<slug>/DEAL.md\\\"`. Tokens: `<slug>` (doctype identity), `<DOCTYPE>` (extension's slug name part). Falls back to parent's convention when omitted.\").optional(), \"requires\": z.array(z.number().int().gte(1)).refine((arr) => arr.every((item, i) => arr.indexOf(item) == i), { message: \"All items must be unique!\" }).describe(\"Public AIPs the extension depends on, in addition to its parent.\").default([] as never), \"metadata\": z.record(z.string(), z.any()).describe(\"Free-form vendor extensions under namespaced keys (`metadata.<vendor>.<field>`).\").default({} as never) }).strict().describe(\"Validates the YAML frontmatter portion of an AIP-40 EXTENSION.md manifest. An extension declares a workspace-local doctype that inherits a public AIP's schema and may add fields, tighten constraints, set defaults, and override the path convention.\")\n\nexport type ExtensionFrontmatter = z.infer<typeof extensionFrontmatterSchema>\n","import { createDoctype } from \"@agentproto/define-doctype\"\nimport { extensionFrontmatterSchema } from \"./schema.js\"\nimport type { ExtensionDefinition, ExtensionHandle } from \"./types.js\"\n\n/**\n * AIP-40 reference implementation of `defineExtension`.\n *\n * Built on `createDoctype` so the cross-AIP invariants (id pattern,\n * description length, top-level freeze, \"defineExtension (AIP-40): …\"\n * error prefix) run uniformly with every other AIP defineX.\n *\n * Field-level validation runs the schema-derived zod from\n * `./schema.ts` against the input. Same source of truth as the .md\n * path uses (`parseExtensionManifest`), so a malformed TS-authored\n * definition fails with the same diagnostic as a malformed manifest.\n * Cross-field rules go in `validate(def)` after the zod check.\n *\n * Identity / description extractors detected from the JSON Schema:\n *   readIdentity: def.slug\n *   readDescription: def.description.\n */\nexport const defineExtension = createDoctype<ExtensionDefinition, ExtensionHandle>({\n  aip: 40,\n  name: \"extension\",\n  // Extension slugs are namespaced: `<namespace>:<name>` (e.g.\n  // `acme:deal`). Override the default kebab-only pattern.\n  idPattern: /^[a-z][a-z0-9-]*:[a-z][a-z0-9-]*[a-z0-9]$/,\n  readIdentity: (def) => def.slug,\n  validate(def) {\n    const result = extensionFrontmatterSchema.safeParse(def)\n    if (!result.success) {\n      throw new Error(\n        `defineExtension (AIP-40): ${result.error.issues\n          .map((i) => `${i.path.join(\".\")}: ${i.message}`)\n          .join(\"; \")}`,\n      )\n    }\n    // TODO: spec-40-specific cross-field rules (if/then/allOf in\n    // the JSON Schema) — those don't translate to zod cleanly and\n    // belong here. See @agentproto/operator's autonomy=gated rule.\n  },\n  build(def) {\n    // Default build: spread the validated definition into a fresh object.\n    // Hand-tune for nested freezing (Object.freeze on arrays/objects) and\n    // for fields that need defaults applied — see @agentproto/operator\n    // for a reference shape.\n    return { ...def } as ExtensionHandle\n  },\n})\n","/**\n * AIP-40 EXTENSION.md sidecar parser + manifest-to-handle constructor.\n *\n * Mirror of `@agentproto/tool/manifest` and `@agentproto/driver/manifest`:\n * the .md provides metadata; the TS module supplies any spec-specific\n * runtime bits (schemas, execute bodies, …) that can't live in\n * frontmatter. Both inputs end up in `defineExtension` so the cross-AIP\n * invariants run uniformly.\n *\n *\n * The frontmatter zod schema below was generated from\n * `resources/aip-40/draft/EXTENSION.schema.json` via json-schema-to-zod.\n * Re-run scaffold-aip to refresh after spec changes (or hand-tune\n * any constraint the converter doesn't capture cleanly).\n */\n\nimport matter from \"gray-matter\"\nimport { extensionFrontmatterSchema, type ExtensionFrontmatter } from \"../schema.js\"\nimport { defineExtension } from \"../define-extension.js\"\nimport type { ExtensionDefinition, ExtensionHandle } from \"../types.js\"\n\n// Re-export so consumers can import the schema + inferred type either\n// from \"@@agentproto/extension/manifest\" or directly from \"@@agentproto/extension/schema\".\nexport { extensionFrontmatterSchema, type ExtensionFrontmatter }\n\nexport interface ExtensionManifest {\n  frontmatter: ExtensionFrontmatter\n  body: string\n}\n\nexport function parseExtensionManifest(source: string): ExtensionManifest {\n  const parsed = matter(source)\n  if (Object.keys(parsed.data).length === 0) {\n    throw new Error(\"parseExtensionManifest: missing or empty frontmatter\")\n  }\n  const result = extensionFrontmatterSchema.safeParse(parsed.data)\n  if (!result.success) {\n    throw new Error(\n      `parseExtensionManifest: invalid frontmatter — ${result.error.issues\n        .map((i) => `${i.path.join(\".\")}: ${i.message}`)\n        .join(\"; \")}`,\n    )\n  }\n  return { frontmatter: result.data, body: parsed.content }\n}\n\nexport function extensionFromManifest(manifest: ExtensionManifest): ExtensionHandle {\n  // The zod-validated frontmatter is structurally compatible with\n  // ExtensionDefinition; the cast pins the typing once the manifest\n  // schema and the TS interface diverge (e.g. handle has frozen fields\n  // a literal config doesn't carry yet).\n  return defineExtension(manifest.frontmatter as unknown as ExtensionDefinition)\n}\n"]}

package/dist/index-C2uTNMnb.d.ts

@@ -0,0 +1,157 @@
+import { z } from 'zod';
+
+/**
+ * AIP-40 ExtensionDefinition + ExtensionHandle.
+ *
+ * `ExtensionDefinition` was generated from
+ * `resources/aip-40/draft/EXTENSION.schema.json` via json-schema-to-typescript.
+ * `ExtensionHandle` is the readonly view of the same shape; tighten it
+ * by hand for fields that get defaults applied in build().
+ */
+/**
+ * Validates the YAML frontmatter portion of an AIP-40 EXTENSION.md manifest. An extension declares a workspace-local doctype that inherits a public AIP's schema and may add fields, tighten constraints, set defaults, and override the path convention.
+ */
+interface ExtensionDefinition {
+    /**
+     * Pins the spec version this manifest conforms to.
+     */
+    schema: "agentproto/extension/v1";
+    /**
+     * Namespaced identifier — `<namespace>:<name>`. Lowercase, digits, dashes; single colon separator. Example: `acme:deal`.
+     */
+    slug: string;
+    /**
+     * Human-readable display name.
+     */
+    title: string;
+    /**
+     * One-paragraph statement of the extension's purpose.
+     */
+    description: string;
+    /**
+     * Extension's own semver. Bump on breaking change.
+     */
+    version: string;
+    /**
+     * Extensions are perpetually Local — they never enter the public registry's Draft/Review/Final lifecycle.
+     */
+    status: "Local";
+    /**
+     * Parent AIP this extension inherits from, or `none` for a root doctype.
+     */
+    extends: string | "none";
+    /**
+     * Schema-level additions: new properties + new required entries.
+     */
+    add_fields?: {
+        /**
+         * JSON Schema property definitions to merge into the parent's properties. Collisions are an error — use `tighten` to narrow an existing field.
+         */
+        properties?: {
+            [k: string]: unknown;
+        };
+        /**
+         * Field names that become required in addition to parent's required[]. Unioned with parent's required, never replaces.
+         */
+        required?: string[];
+    };
+    /**
+     * Per-field constraint overrides. Each entry MUST tighten (not loosen) the parent's constraints; runtimes verify monotonicity at registration.
+     */
+    tighten?: {
+        [k: string]: {
+            pattern?: string;
+            enum?: unknown[];
+            minLength?: number;
+            maxLength?: number;
+            minimum?: number;
+            maximum?: number;
+        };
+    };
+    /**
+     * Default values applied when a field is omitted. Layered on top of parent's defaults; extension's value wins on the same key.
+     */
+    defaults?: {
+        [k: string]: unknown;
+    };
+    /**
+     * Filesystem convention template, e.g. `"deals/<slug>/DEAL.md"`. Tokens: `<slug>` (doctype identity), `<DOCTYPE>` (extension's slug name part). Falls back to parent's convention when omitted.
+     */
+    path_convention?: string;
+    /**
+     * Public AIPs the extension depends on, in addition to its parent.
+     */
+    requires?: number[];
+    /**
+     * Free-form vendor extensions under namespaced keys (`metadata.<vendor>.<field>`).
+     */
+    metadata?: {
+        [k: string]: unknown;
+    };
+}
+type ExtensionHandle = Readonly<ExtensionDefinition>;
+
+/**
+ * AIP-40 EXTENSION.md frontmatter zod schema.
+ *
+ * Generated from `resources/aip-40/draft/EXTENSION.schema.json` via
+ * json-schema-to-zod. Imported by both `define-extension.ts` (TS path
+ * validation) and `manifest/index.ts` (.md path validation) so every
+ * field-level constraint runs in both authoring paths from a single
+ * source of truth — re-run scaffold-aip to refresh after spec changes.
+ *
+ * Cross-field rules (if/then/allOf in JSON Schema) don't translate
+ * cleanly and live in `define-extension.ts`'s `validate(def)` instead.
+ */
+
+declare const extensionFrontmatterSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"agentproto/extension/v1">;
+    slug: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodString;
+    version: z.ZodString;
+    status: z.ZodLiteral<"Local">;
+    extends: z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<"none">]>;
+    add_fields: z.ZodOptional<z.ZodObject<{
+        properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+        required: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    tighten: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        pattern: z.ZodOptional<z.ZodString>;
+        enum: z.ZodOptional<z.ZodArray<z.ZodAny>>;
+        minLength: z.ZodOptional<z.ZodNumber>;
+        maxLength: z.ZodOptional<z.ZodNumber>;
+        minimum: z.ZodOptional<z.ZodNumber>;
+        maximum: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>>;
+    defaults: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    path_convention: z.ZodOptional<z.ZodString>;
+    requires: z.ZodDefault<z.ZodArray<z.ZodNumber>>;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, z.core.$strict>;
+type ExtensionFrontmatter = z.infer<typeof extensionFrontmatterSchema>;
+
+/**
+ * AIP-40 EXTENSION.md sidecar parser + manifest-to-handle constructor.
+ *
+ * Mirror of `@agentproto/tool/manifest` and `@agentproto/driver/manifest`:
+ * the .md provides metadata; the TS module supplies any spec-specific
+ * runtime bits (schemas, execute bodies, …) that can't live in
+ * frontmatter. Both inputs end up in `defineExtension` so the cross-AIP
+ * invariants run uniformly.
+ *
+ *
+ * The frontmatter zod schema below was generated from
+ * `resources/aip-40/draft/EXTENSION.schema.json` via json-schema-to-zod.
+ * Re-run scaffold-aip to refresh after spec changes (or hand-tune
+ * any constraint the converter doesn't capture cleanly).
+ */
+
+interface ExtensionManifest {
+    frontmatter: ExtensionFrontmatter;
+    body: string;
+}
+declare function parseExtensionManifest(source: string): ExtensionManifest;
+declare function extensionFromManifest(manifest: ExtensionManifest): ExtensionHandle;
+
+export { type ExtensionDefinition as E, type ExtensionFrontmatter as a, type ExtensionHandle as b, type ExtensionManifest as c, extensionFrontmatterSchema as d, extensionFromManifest as e, parseExtensionManifest as p };

package/dist/index.d.ts

@@ -0,0 +1,79 @@
+import { E as ExtensionDefinition } from './index-C2uTNMnb.js';
+export { a as ExtensionFrontmatter, b as ExtensionHandle, c as ExtensionManifest, e as extensionFromManifest, d as extensionFrontmatterSchema, p as parseExtensionManifest } from './index-C2uTNMnb.js';
+import { DoctypeSpec } from '@agentproto/manifest';
+import 'zod';
+
+/**
+ * AIP-40 reference implementation of `defineExtension`.
+ *
+ * Built on `createDoctype` so the cross-AIP invariants (id pattern,
+ * description length, top-level freeze, "defineExtension (AIP-40): …"
+ * error prefix) run uniformly with every other AIP defineX.
+ *
+ * Field-level validation runs the schema-derived zod from
+ * `./schema.ts` against the input. Same source of truth as the .md
+ * path uses (`parseExtensionManifest`), so a malformed TS-authored
+ * definition fails with the same diagnostic as a malformed manifest.
+ * Cross-field rules go in `validate(def)` after the zod check.
+ *
+ * Identity / description extractors detected from the JSON Schema:
+ *   readIdentity: def.slug
+ *   readDescription: def.description.
+ */
+declare const defineExtension: (def: ExtensionDefinition) => Readonly<ExtensionDefinition>;
+
+/**
+ * `specFromExtension(handle, parent)` — turn a parsed EXTENSION.md
+ * into a runtime `DoctypeSpec` consumable by
+ * `@agentproto/manifest.createVerbs`.
+ *
+ * The parent argument is the public AIP's spec (e.g. `toolSpec` from
+ * `@agentproto/tool`). The function composes:
+ *
+ *   schema       parent.schema ∪ ext.add_fields, then ext.tighten
+ *   path         ext.path_convention ?? parent.pathOf
+ *   defaults     parent defaults ⨁ ext.defaults
+ *   define       wraps parent.define with default-application
+ *   parse        parent.parse (frontmatter shape stays compatible)
+ *
+ * Tightening monotonicity is verified by-field: pattern subset
+ * (cheap heuristic — full regex-language inclusion is undecidable),
+ * enum subset (set membership), minLength/minimum ≥, maxLength/maximum ≤.
+ *
+ * For `extends: none`, `parent` is null/undefined and the extension
+ * acts as a root doctype: the `add_fields` becomes its full schema,
+ * `path_convention` is required (no parent fallback).
+ */
+
+interface SpecFromExtensionOptions<TParams extends {
+    id?: string;
+    slug?: string;
+    name?: string;
+}, THandle> {
+    /**
+     * Parent doctype spec. Required when `extension.extends !== "none"`.
+     * Pass e.g. `toolSpec` from `@agentproto/tool`.
+     */
+    parent?: DoctypeSpec<TParams, THandle>;
+}
+declare function specFromExtension<TParams extends {
+    id?: string;
+    slug?: string;
+    name?: string;
+}, THandle>(extension: ExtensionDefinition, opts?: SpecFromExtensionOptions<TParams, THandle>): DoctypeSpec<TParams, THandle>;
+
+/**
+ * @agentproto/extension — AIP-40 EXTENSION.md `defineExtension` reference impl.
+ *
+ * A meta-doctype that lets a workspace declare its own custom doctype as an extension of an existing AIP — adding fields, tightening constraints, overriding defaults, and choosing a path convention — without going through the public AIP process. The runtime (@agentproto/manifest verbs, MCP server, scaffolder) treats local extensions identically to public AIPs.
+ *
+ * Spec: https://agentproto.sh/docs/aip-40
+ *
+ * Authoring paths:
+ *   - TS:  `defineExtension({...})` → `ExtensionHandle`
+ *   - MD:  `parseExtensionManifest(src) → extensionFromManifest({...})` → `ExtensionHandle`
+ */
+declare const SPEC_NAME: "agentextension/v1";
+declare const SPEC_VERSION: "1.0.0-alpha";
+
+export { ExtensionDefinition, SPEC_NAME, SPEC_VERSION, type SpecFromExtensionOptions, defineExtension, specFromExtension };

package/dist/index.mjs

@@ -0,0 +1,112 @@
+export { defineExtension, extensionFromManifest, extensionFrontmatterSchema, parseExtensionManifest } from './chunk-XIW4DKUM.mjs';
+
+/**
+ * @agentproto/extension v0.1.0-alpha
+ * AIP-40 EXTENSION.md `defineExtension` reference implementation.
+ */
+
+// src/spec-from-extension.ts
+function specFromExtension(extension, opts = {}) {
+  const { parent } = opts;
+  const isRoot = extension.extends === "none";
+  if (!isRoot && !parent) {
+    throw new Error(
+      `specFromExtension (AIP-40): extension '${extension.slug}' extends '${extension.extends}' but no parent spec was provided in opts.parent`
+    );
+  }
+  if (isRoot && !extension.path_convention) {
+    throw new Error(
+      `specFromExtension (AIP-40): extension '${extension.slug}' is a root doctype (extends: none) and MUST declare path_convention`
+    );
+  }
+  if (parent && extension.tighten) {
+    verifyTightening(extension);
+  }
+  const slugName = extension.slug.split(":")[1] ?? extension.slug;
+  const pathTemplate = extension.path_convention ?? null;
+  const extensionKeys = new Set(
+    Object.keys(extension.add_fields?.properties ?? {})
+  );
+  const define = (params) => {
+    const withDefaults = { ...params };
+    if (extension.defaults) {
+      for (const [key, value] of Object.entries(extension.defaults)) {
+        if (withDefaults[key] === void 0 && value !== void 0) {
+          withDefaults[key] = value;
+        }
+      }
+    }
+    if (isRoot) {
+      return Object.freeze(withDefaults);
+    }
+    const parentOnly = {};
+    const extensionOnly = {};
+    for (const [key, value] of Object.entries(withDefaults)) {
+      if (extensionKeys.has(key)) extensionOnly[key] = value;
+      else parentOnly[key] = value;
+    }
+    const parentHandle = parent.define(parentOnly);
+    return Object.freeze({
+      ...parentHandle,
+      ...extensionOnly
+    });
+  };
+  const parse = isRoot ? rootParse(extension) : parent.parse;
+  const pathOf = (handle) => {
+    if (pathTemplate) {
+      return resolvePathTemplate(
+        pathTemplate,
+        handle,
+        slugName
+      );
+    }
+    return parent.pathOf(handle);
+  };
+  return {
+    name: extension.slug,
+    aip: 40,
+    schemaLiteral: parent?.schemaLiteral ?? `agentproto/extension/v1`,
+    pathOf,
+    define,
+    parse
+  };
+}
+function verifyTightening(extension, parent) {
+  const t = extension.tighten ?? {};
+  for (const [field, override] of Object.entries(t)) {
+    if (typeof override.minLength === "number" && typeof override.maxLength === "number" && override.minLength > override.maxLength) {
+      throw new Error(
+        `specFromExtension (AIP-40): extension '${extension.slug}' tighten.${field}: minLength (${override.minLength}) > maxLength (${override.maxLength})`
+      );
+    }
+    if (typeof override.minimum === "number" && typeof override.maximum === "number" && override.minimum > override.maximum) {
+      throw new Error(
+        `specFromExtension (AIP-40): extension '${extension.slug}' tighten.${field}: minimum (${override.minimum}) > maximum (${override.maximum})`
+      );
+    }
+    if (override.enum !== void 0 && !Array.isArray(override.enum)) {
+      throw new Error(
+        `specFromExtension (AIP-40): extension '${extension.slug}' tighten.${field}: enum must be an array`
+      );
+    }
+  }
+}
+function rootParse(extension) {
+  return (source) => {
+    throw new Error(
+      `specFromExtension (AIP-40): extension '${extension.slug}' is a root doctype \u2014 supply your own parser or extend a public AIP for parser inheritance`
+    );
+  };
+}
+function resolvePathTemplate(template, handle, doctypeSlug) {
+  const identity = typeof handle.id === "string" && handle.id || typeof handle.slug === "string" && handle.slug || typeof handle.name === "string" && handle.name || "unknown";
+  return template.replace(/<slug>/g, identity).replace(/<DOCTYPE>/g, doctypeSlug.toUpperCase());
+}
+
+// src/index.ts
+var SPEC_NAME = "agentextension/v1";
+var SPEC_VERSION = "1.0.0-alpha";
+
+export { SPEC_NAME, SPEC_VERSION, specFromExtension };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/spec-from-extension.ts","../src/index.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["/**\n * `specFromExtension(handle, parent)` — turn a parsed EXTENSION.md\n * into a runtime `DoctypeSpec` consumable by\n * `@agentproto/manifest.createVerbs`.\n *\n * The parent argument is the public AIP's spec (e.g. `toolSpec` from\n * `@agentproto/tool`). The function composes:\n *\n *   schema       parent.schema ∪ ext.add_fields, then ext.tighten\n *   path         ext.path_convention ?? parent.pathOf\n *   defaults     parent defaults ⨁ ext.defaults\n *   define       wraps parent.define with default-application\n *   parse        parent.parse (frontmatter shape stays compatible)\n *\n * Tightening monotonicity is verified by-field: pattern subset\n * (cheap heuristic — full regex-language inclusion is undecidable),\n * enum subset (set membership), minLength/minimum ≥, maxLength/maximum ≤.\n *\n * For `extends: none`, `parent` is null/undefined and the extension\n * acts as a root doctype: the `add_fields` becomes its full schema,\n * `path_convention` is required (no parent fallback).\n */\n\nimport type { DoctypeSpec } from \"@agentproto/manifest\"\nimport type { ExtensionDefinition } from \"./types.js\"\n\nexport interface SpecFromExtensionOptions<\n  TParams extends { id?: string; slug?: string; name?: string },\n  THandle,\n> {\n  /**\n   * Parent doctype spec. Required when `extension.extends !== \"none\"`.\n   * Pass e.g. `toolSpec` from `@agentproto/tool`.\n   */\n  parent?: DoctypeSpec<TParams, THandle>\n}\n\nexport function specFromExtension<\n  TParams extends { id?: string; slug?: string; name?: string },\n  THandle,\n>(\n  extension: ExtensionDefinition,\n  opts: SpecFromExtensionOptions<TParams, THandle> = {},\n): DoctypeSpec<TParams, THandle> {\n  const { parent } = opts\n  const isRoot = extension.extends === \"none\"\n\n  if (!isRoot && !parent) {\n    throw new Error(\n      `specFromExtension (AIP-40): extension '${extension.slug}' extends '${extension.extends}' but no parent spec was provided in opts.parent`,\n    )\n  }\n  if (isRoot && !extension.path_convention) {\n    throw new Error(\n      `specFromExtension (AIP-40): extension '${extension.slug}' is a root doctype (extends: none) and MUST declare path_convention`,\n    )\n  }\n\n  // Tightening monotonicity check — see Specification §\"Composition rules\" #3.\n  if (parent && extension.tighten) {\n    verifyTightening(extension, parent)\n  }\n\n  const slugName = extension.slug.split(\":\")[1] ?? extension.slug\n  const pathTemplate = extension.path_convention ?? null\n\n  // Keys the extension is authoritative over — anything declared in\n  // `add_fields.properties`. Computed once at spec-composition time so\n  // the per-call `define` is a hot-path lookup, not a re-derivation.\n  const extensionKeys = new Set(\n    Object.keys(extension.add_fields?.properties ?? {}),\n  )\n\n  const define = (params: TParams) => {\n    // Layered defaults: parent defaults are baked into parent.define;\n    // extension defaults apply on top, only for keys the user omitted.\n    const withDefaults = { ...params } as Record<string, unknown>\n    if (extension.defaults) {\n      for (const [key, value] of Object.entries(extension.defaults)) {\n        if (withDefaults[key] === undefined && value !== undefined) {\n          withDefaults[key] = value\n        }\n      }\n    }\n    if (isRoot) {\n      // Root doctype — no parent.define to delegate to. Return the\n      // params verbatim, frozen. (A more disciplined runtime would\n      // compile the add_fields schema to zod and validate; deferred\n      // because root doctypes are rare and the manifest layer's\n      // schema-level zod catches malformed input.)\n      return Object.freeze(withDefaults) as unknown as THandle\n    }\n    // Split params before delegating: parent specs typically validate\n    // through `zod.strict()` (e.g. AIP-42 `agentFrontmatterSchema`),\n    // which rejects extension-owned keys as \"Unrecognized\". Hand the\n    // parent only what it owns, then re-attach extension fields onto\n    // the resulting handle. Extension-side validation of these fields\n    // is the manifest layer's responsibility (compiled from\n    // `add_fields` JSON Schema at parse time); the runtime trusts\n    // input it received via that path.\n    const parentOnly: Record<string, unknown> = {}\n    const extensionOnly: Record<string, unknown> = {}\n    for (const [key, value] of Object.entries(withDefaults)) {\n      if (extensionKeys.has(key)) extensionOnly[key] = value\n      else parentOnly[key] = value\n    }\n    const parentHandle = parent!.define(parentOnly as unknown as TParams)\n    return Object.freeze({\n      ...(parentHandle as object),\n      ...extensionOnly,\n    }) as unknown as THandle\n  }\n\n  const parse = isRoot ? rootParse(extension) : parent!.parse\n\n  const pathOf = (handle: THandle) => {\n    if (pathTemplate) {\n      return resolvePathTemplate(\n        pathTemplate,\n        handle as unknown as Record<string, unknown>,\n        slugName,\n      )\n    }\n    return parent!.pathOf(handle)\n  }\n\n  return {\n    name: extension.slug,\n    aip: 40,\n    schemaLiteral: parent?.schemaLiteral ?? `agentproto/extension/v1`,\n    pathOf,\n    define,\n    parse,\n  }\n}\n\nfunction verifyTightening<\n  TParams extends { id?: string; slug?: string; name?: string },\n  THandle,\n>(\n  extension: ExtensionDefinition,\n  parent: DoctypeSpec<TParams, THandle>,\n): void {\n  // Best-effort: the manifest layer doesn't expose the parent's raw\n  // JSON Schema, so we can only verify what the spec ships in\n  // `extension.tighten` against itself for self-consistency. Full\n  // parent-vs-extension monotonicity verification belongs to a future\n  // version once parent specs expose `schema:` introspection.\n  const t = extension.tighten ?? {}\n  for (const [field, override] of Object.entries(t)) {\n    if (\n      typeof override.minLength === \"number\" &&\n      typeof override.maxLength === \"number\" &&\n      override.minLength > override.maxLength\n    ) {\n      throw new Error(\n        `specFromExtension (AIP-40): extension '${extension.slug}' tighten.${field}: minLength (${override.minLength}) > maxLength (${override.maxLength})`,\n      )\n    }\n    if (\n      typeof override.minimum === \"number\" &&\n      typeof override.maximum === \"number\" &&\n      override.minimum > override.maximum\n    ) {\n      throw new Error(\n        `specFromExtension (AIP-40): extension '${extension.slug}' tighten.${field}: minimum (${override.minimum}) > maximum (${override.maximum})`,\n      )\n    }\n    if (override.enum !== undefined && !Array.isArray(override.enum)) {\n      throw new Error(\n        `specFromExtension (AIP-40): extension '${extension.slug}' tighten.${field}: enum must be an array`,\n      )\n    }\n  }\n}\n\nfunction rootParse(extension: ExtensionDefinition) {\n  return (source: string) => {\n    // Root doctypes don't have a parent parser — fall back to bare\n    // gray-matter. The manifest layer applies `define` afterwards.\n    // We don't import gray-matter here to keep this module dependency-\n    // light; the caller wires their own parse if they really want a\n    // root doctype, or uses the standard parse from a sibling package.\n    void source\n    void extension\n    throw new Error(\n      `specFromExtension (AIP-40): extension '${extension.slug}' is a root doctype — supply your own parser or extend a public AIP for parser inheritance`,\n    )\n  }\n}\n\nfunction resolvePathTemplate(\n  template: string,\n  handle: Record<string, unknown>,\n  doctypeSlug: string,\n): string {\n  // Tokens supported in v1: <slug> (the doctype's identity field —\n  // tries id, slug, name in that order) and <DOCTYPE> (uppercase\n  // version of the extension's slug name part, e.g. \"DEAL\").\n  const identity =\n    (typeof handle.id === \"string\" && handle.id) ||\n    (typeof handle.slug === \"string\" && handle.slug) ||\n    (typeof handle.name === \"string\" && handle.name) ||\n    \"unknown\"\n  return template\n    .replace(/<slug>/g, identity)\n    .replace(/<DOCTYPE>/g, doctypeSlug.toUpperCase())\n}\n","/**\n * @agentproto/extension — AIP-40 EXTENSION.md `defineExtension` reference impl.\n *\n * A meta-doctype that lets a workspace declare its own custom doctype as an extension of an existing AIP — adding fields, tightening constraints, overriding defaults, and choosing a path convention — without going through the public AIP process. The runtime (@agentproto/manifest verbs, MCP server, scaffolder) treats local extensions identically to public AIPs.\n *\n * Spec: https://agentproto.sh/docs/aip-40\n *\n * Authoring paths:\n *   - TS:  `defineExtension({...})` → `ExtensionHandle`\n *   - MD:  `parseExtensionManifest(src) → extensionFromManifest({...})` → `ExtensionHandle`\n */\n\nexport const SPEC_NAME = \"agentextension/v1\" as const\nexport const SPEC_VERSION = \"1.0.0-alpha\" as const\n\nexport { defineExtension } from \"./define-extension.js\"\nexport type { ExtensionDefinition, ExtensionHandle } from \"./types.js\"\nexport {\n  specFromExtension,\n  type SpecFromExtensionOptions,\n} from \"./spec-from-extension.js\"\nexport {\n  parseExtensionManifest,\n  extensionFromManifest,\n  extensionFrontmatterSchema,\n  type ExtensionFrontmatter,\n  type ExtensionManifest,\n} from \"./manifest/index.js\"\n"]}

package/dist/manifest/index.d.ts

@@ -0,0 +1,2 @@
+export { a as ExtensionFrontmatter, c as ExtensionManifest, e as extensionFromManifest, d as extensionFrontmatterSchema, p as parseExtensionManifest } from '../index-C2uTNMnb.js';
+import 'zod';

package/dist/manifest/index.mjs

@@ -0,0 +1,3 @@
+export { extensionFromManifest, extensionFrontmatterSchema, parseExtensionManifest } from '../chunk-XIW4DKUM.mjs';
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/manifest/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.mjs"}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@agentproto/extension",
+  "version": "0.1.0",
+  "description": "@agentproto/extension — AIP-40 EXTENSION.md reference implementation. A meta-doctype that lets a workspace declare its own custom doctype as an extension of an existing AIP — adding fields, tightening constraints, overriding defaults, and choosing a path convention — without going through the public AIP process. The runtime (@agentproto/manifest verbs, MCP server, scaffolder) treats local extensions identically to public AIPs.",
+  "keywords": [
+    "agentproto",
+    "aip-40",
+    "extension",
+    "defineExtension",
+    "open-standard",
+    "agentic"
+  ],
+  "homepage": "https://agentproto.sh/docs/aip-40",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentproto/ts",
+    "directory": "packages/extension"
+  },
+  "bugs": {
+    "url": "https://github.com/agentproto/ts/issues"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.mjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./manifest": {
+      "types": "./dist/manifest/index.d.ts",
+      "import": "./dist/manifest/index.mjs",
+      "default": "./dist/manifest/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "gray-matter": "^4.0.3",
+    "zod": "^4.4.3",
+    "@agentproto/define-doctype": "0.1.0",
+    "@agentproto/manifest": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4",
+    "@agentproto/tooling": "0.1.0-alpha.0"
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest"
+  }
+}