@agentproto/action 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/action
+
+AIP-39 `ACTION.md` reference implementation. A markdown + frontmatter format for declaring an abstract verb / operation that can be performed on a resource — its identity, semantics, side-effect profile, approval class, and lifecycle events. The pivot primitive that TOOL implements (with LLM schema), POLICY references (for grants), INTENT routes to (from user verbs), and WORKFLOW steps invoke. Bottom-up — implementations declare which actions they implement.
+
+> **Status: 0.1.0-alpha.** Generated by `scripts/scaffold-aip.mjs` — `build()` and `validate()` bodies are TODOs.
+
+Spec: <https://agentproto.sh/docs/aip-39>
+
+## Usage
+
+```ts
+import { defineAction } from "@agentproto/action"
+
+const x = defineAction({
+  id: "my-action",
+  description: "Short purpose.",
+  // ...
+})
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/chunk-VJCWGENG.mjs

@@ -0,0 +1,51 @@
+import matter from 'gray-matter';
+import { z } from 'zod';
+import { createDoctype } from '@agentproto/define-doctype';
+
+/**
+ * @agentproto/action v0.1.0-alpha
+ * AIP-39 ACTION.md `defineAction` reference implementation.
+ */
+
+var actionFrontmatterSchema = z.object({ "schema": z.literal("action/v1"), "id": z.string().regex(new RegExp("^[a-z0-9][a-z0-9.-]*(:[a-z0-9][a-z0-9.-]*)?$")).min(2).max(80).describe("Machine identifier. Standard format `<target-kind>:<verb>` (e.g. `storage:commit`). Single colon only; multiple colons reserved for future namespacing."), "description": z.string().min(1).max(2e3).describe("One-paragraph purpose, written for the LLM caller."), "version": z.string().regex(new RegExp("^\\d+\\.\\d+\\.\\d+(?:[-+][\\w.\\-]+)?$")).describe("Spec version of THIS file. Bump on breaking change to mutates / risk_level.").default("1.0.0"), "category": z.string().describe("Discovery category for catalog UIs. Common: filesystem, compute, messaging, vcs, payment, auth, lifecycle.").default(""), "verb": z.string().describe("The bare verb (e.g. `commit`, `execute`). Derived from `id` after the `:` if absent.").optional(), "target_kind": z.string().describe("The resource kind this action operates on (e.g. `storage`, `sandbox`, `secrets`). Derived from `id` before the `:` if absent.").optional(), "mutates": z.array(z.string().regex(new RegExp("^[a-z]+:[^\\s]+$")).describe("Format: <class>:<scope>. Examples: storage:*, network:api.foo.com, database:invoices. Implementors MUST honour every entry; widening rejected at parse time.")).describe("Resources the action may modify. Inherited by implementors (TOOL, DRIVER); they MAY add more, never drop.").default([]), "requires": z.object({ "network": z.array(z.string()).optional(), "secrets": z.array(z.string()).optional(), "tools": z.array(z.string()).optional() }).strict().describe("Capability requirements gated by AIP-7 governance. Implementors MAY add to this set; MUST NOT remove.").optional(), "approval": z.union([z.enum(["auto", "always", "on-mutate"]), z.string().regex(new RegExp("^policy:[A-Za-z0-9_./-]+$"))]).describe("Approval class. Implementors MAY narrow (`auto` \u2192 `always` \u2192 `on-mutate`); MUST NOT widen.").default("auto"), "risk_level": z.number().int().gte(0).lte(3).describe("0=read-only, 1=scoped writes, 2=external side effects, 3=irreversible. Implementors MAY raise; MUST NOT lower.").default(0), "fires_events": z.array(z.string().min(1)).describe("AIP-37 LIFECYCLE event names this action fires when invoked. Subscribers (sync layers, audit) attach to these. Implementors MAY fire more events; MUST NOT drop any declared here.").default([]), "implementations": z.array(z.object({ "kind": z.enum(["tool", "driver", "ui", "lifecycle"]).describe("Kind of implementation."), "ref": z.string().min(1).describe("Reference to the implementor (TOOL.md id, DRIVER.md id, UI surface name, etc.).") }).strict()).describe("OPTIONAL discovery hint \u2014 known implementations of this action. NOT authoritative \u2014 source of truth lives on implementors via their `implements:` field. Hosts populate from scanning.").default([]), "tags": z.array(z.string()).describe("Free-form discovery tags.").default([]), "examples": z.array(z.object({ "name": z.string().min(1), "scenario": z.string().min(1), "note": z.string().optional() }).strict()).describe("Semantic examples (NOT input/output, since action has no schema). Each `{ name, scenario, note? }`.").default([]), "metadata": z.record(z.string(), z.any()).describe("Free-form, namespaced. Authors MAY stash adapter-specific hints under namespaced keys.").optional() }).strict().describe("Validates the YAML frontmatter portion of an AIP-39 ACTION.md manifest. The pivot primitive: TOOL implements it, POLICY grants on it, INTENT routes to it, WORKFLOW steps invoke it.");
+var defineAction = createDoctype({
+  aip: 39,
+  name: "action",
+  // Action ids are namespaced `<target_kind>:<verb>` (`secrets:reveal`,
+  // `storage:commit`). Override createDoctype's default kebab-only
+  // pattern; the schema's own id regex (stricter) runs inside zod.
+  idPattern: /^[a-z0-9][a-z0-9.-]*(?::[a-z0-9][a-z0-9.-]*)?$/,
+  validate(def) {
+    const result = actionFrontmatterSchema.safeParse(def);
+    if (!result.success) {
+      throw new Error(
+        `defineAction (AIP-39): ${result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
+      );
+    }
+  },
+  build(def) {
+    return { ...def };
+  }
+});
+
+// src/manifest/index.ts
+function parseActionManifest(source) {
+  const parsed = matter(source);
+  if (Object.keys(parsed.data).length === 0) {
+    throw new Error("parseActionManifest: missing or empty frontmatter");
+  }
+  const result = actionFrontmatterSchema.safeParse(parsed.data);
+  if (!result.success) {
+    throw new Error(
+      `parseActionManifest: invalid frontmatter \u2014 ${result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
+    );
+  }
+  return { frontmatter: result.data, body: parsed.content };
+}
+function actionFromManifest(manifest) {
+  return defineAction(manifest.frontmatter);
+}
+
+export { actionFromManifest, actionFrontmatterSchema, defineAction, parseActionManifest };
+//# sourceMappingURL=chunk-VJCWGENG.mjs.map
+//# sourceMappingURL=chunk-VJCWGENG.mjs.map

package/dist/chunk-VJCWGENG.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema.ts","../src/define-action.ts","../src/manifest/index.ts"],"names":[],"mappings":"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","file":"chunk-VJCWGENG.mjs","sourcesContent":["/**\n * AIP-39 ACTION.md frontmatter zod schema.\n *\n * Generated from `resources/aip-39/draft/ACTION.schema.json` via\n * json-schema-to-zod. Imported by both `define-action.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-action.ts`'s `validate(def)` instead.\n */\n\nimport { z } from \"zod\"\n\nexport const actionFrontmatterSchema = z.object({ \"schema\": z.literal(\"action/v1\"), \"id\": z.string().regex(new RegExp(\"^[a-z0-9][a-z0-9.-]*(:[a-z0-9][a-z0-9.-]*)?$\")).min(2).max(80).describe(\"Machine identifier. Standard format `<target-kind>:<verb>` (e.g. `storage:commit`). Single colon only; multiple colons reserved for future namespacing.\"), \"description\": z.string().min(1).max(2000).describe(\"One-paragraph purpose, written for the LLM caller.\"), \"version\": z.string().regex(new RegExp(\"^\\\\d+\\\\.\\\\d+\\\\.\\\\d+(?:[-+][\\\\w.\\\\-]+)?$\")).describe(\"Spec version of THIS file. Bump on breaking change to mutates / risk_level.\").default(\"1.0.0\"), \"category\": z.string().describe(\"Discovery category for catalog UIs. Common: filesystem, compute, messaging, vcs, payment, auth, lifecycle.\").default(\"\"), \"verb\": z.string().describe(\"The bare verb (e.g. `commit`, `execute`). Derived from `id` after the `:` if absent.\").optional(), \"target_kind\": z.string().describe(\"The resource kind this action operates on (e.g. `storage`, `sandbox`, `secrets`). Derived from `id` before the `:` if absent.\").optional(), \"mutates\": z.array(z.string().regex(new RegExp(\"^[a-z]+:[^\\\\s]+$\")).describe(\"Format: <class>:<scope>. Examples: storage:*, network:api.foo.com, database:invoices. Implementors MUST honour every entry; widening rejected at parse time.\")).describe(\"Resources the action may modify. Inherited by implementors (TOOL, DRIVER); they MAY add more, never drop.\").default([] as never), \"requires\": z.object({ \"network\": z.array(z.string()).optional(), \"secrets\": z.array(z.string()).optional(), \"tools\": z.array(z.string()).optional() }).strict().describe(\"Capability requirements gated by AIP-7 governance. Implementors MAY add to this set; MUST NOT remove.\").optional(), \"approval\": z.union([z.enum([\"auto\",\"always\",\"on-mutate\"]), z.string().regex(new RegExp(\"^policy:[A-Za-z0-9_./-]+$\"))]).describe(\"Approval class. Implementors MAY narrow (`auto` → `always` → `on-mutate`); MUST NOT widen.\").default(\"auto\"), \"risk_level\": z.number().int().gte(0).lte(3).describe(\"0=read-only, 1=scoped writes, 2=external side effects, 3=irreversible. Implementors MAY raise; MUST NOT lower.\").default(0), \"fires_events\": z.array(z.string().min(1)).describe(\"AIP-37 LIFECYCLE event names this action fires when invoked. Subscribers (sync layers, audit) attach to these. Implementors MAY fire more events; MUST NOT drop any declared here.\").default([] as never), \"implementations\": z.array(z.object({ \"kind\": z.enum([\"tool\",\"driver\",\"ui\",\"lifecycle\"]).describe(\"Kind of implementation.\"), \"ref\": z.string().min(1).describe(\"Reference to the implementor (TOOL.md id, DRIVER.md id, UI surface name, etc.).\") }).strict()).describe(\"OPTIONAL discovery hint — known implementations of this action. NOT authoritative — source of truth lives on implementors via their `implements:` field. Hosts populate from scanning.\").default([] as never), \"tags\": z.array(z.string()).describe(\"Free-form discovery tags.\").default([] as never), \"examples\": z.array(z.object({ \"name\": z.string().min(1), \"scenario\": z.string().min(1), \"note\": z.string().optional() }).strict()).describe(\"Semantic examples (NOT input/output, since action has no schema). Each `{ name, scenario, note? }`.\").default([] as never), \"metadata\": z.record(z.string(), z.any()).describe(\"Free-form, namespaced. Authors MAY stash adapter-specific hints under namespaced keys.\").optional() }).strict().describe(\"Validates the YAML frontmatter portion of an AIP-39 ACTION.md manifest. The pivot primitive: TOOL implements it, POLICY grants on it, INTENT routes to it, WORKFLOW steps invoke it.\")\n\nexport type ActionFrontmatter = z.infer<typeof actionFrontmatterSchema>\n","import { createDoctype } from \"@agentproto/define-doctype\"\nimport { actionFrontmatterSchema } from \"./schema.js\"\nimport type { ActionDefinition, ActionHandle } from \"./types.js\"\n\n/**\n * AIP-39 reference implementation of `defineAction`.\n *\n * Built on `createDoctype` so the cross-AIP invariants (id pattern,\n * description length, top-level freeze, \"defineAction (AIP-39): …\"\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 (`parseActionManifest`), 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 */\nexport const defineAction = createDoctype<ActionDefinition, ActionHandle>({\n  aip: 39,\n  name: \"action\",\n  // Action ids are namespaced `<target_kind>:<verb>` (`secrets:reveal`,\n  // `storage:commit`). Override createDoctype's default kebab-only\n  // pattern; the schema's own id regex (stricter) runs inside zod.\n  idPattern: /^[a-z0-9][a-z0-9.-]*(?::[a-z0-9][a-z0-9.-]*)?$/,\n  validate(def) {\n    const result = actionFrontmatterSchema.safeParse(def)\n    if (!result.success) {\n      throw new Error(\n        `defineAction (AIP-39): ${result.error.issues\n          .map((i) => `${i.path.join(\".\")}: ${i.message}`)\n          .join(\"; \")}`,\n      )\n    }\n    // TODO: spec-39-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 ActionHandle\n  },\n})\n","/**\n * AIP-39 ACTION.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 `defineAction` so the cross-AIP\n * invariants run uniformly.\n *\n *\n * The frontmatter zod schema below was generated from\n * `resources/aip-39/draft/ACTION.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 { actionFrontmatterSchema, type ActionFrontmatter } from \"../schema.js\"\nimport { defineAction } from \"../define-action.js\"\nimport type { ActionDefinition, ActionHandle } from \"../types.js\"\n\n// Re-export so consumers can import the schema + inferred type either\n// from \"@@agentproto/action/manifest\" or directly from \"@@agentproto/action/schema\".\nexport { actionFrontmatterSchema, type ActionFrontmatter }\n\nexport interface ActionManifest {\n  frontmatter: ActionFrontmatter\n  body: string\n}\n\nexport function parseActionManifest(source: string): ActionManifest {\n  const parsed = matter(source)\n  if (Object.keys(parsed.data).length === 0) {\n    throw new Error(\"parseActionManifest: missing or empty frontmatter\")\n  }\n  const result = actionFrontmatterSchema.safeParse(parsed.data)\n  if (!result.success) {\n    throw new Error(\n      `parseActionManifest: 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 actionFromManifest(manifest: ActionManifest): ActionHandle {\n  // The zod-validated frontmatter is structurally compatible with\n  // ActionDefinition; 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 defineAction(manifest.frontmatter as unknown as ActionDefinition)\n}\n"]}

package/dist/index-CETj5oaU.d.ts

@@ -0,0 +1,174 @@
+import { z } from 'zod';
+
+/**
+ * AIP-39 ActionDefinition + ActionHandle.
+ *
+ * `ActionDefinition` was generated from
+ * `resources/aip-39/draft/ACTION.schema.json` via json-schema-to-typescript.
+ * `ActionHandle` 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-39 ACTION.md manifest. The pivot primitive: TOOL implements it, POLICY grants on it, INTENT routes to it, WORKFLOW steps invoke it.
+ */
+interface ActionDefinition {
+    schema: "action/v1";
+    /**
+     * Machine identifier. Standard format `<target-kind>:<verb>` (e.g. `storage:commit`). Single colon only; multiple colons reserved for future namespacing.
+     */
+    id: string;
+    /**
+     * One-paragraph purpose, written for the LLM caller.
+     */
+    description: string;
+    /**
+     * Spec version of THIS file. Bump on breaking change to mutates / risk_level.
+     */
+    version?: string;
+    /**
+     * Discovery category for catalog UIs. Common: filesystem, compute, messaging, vcs, payment, auth, lifecycle.
+     */
+    category?: string;
+    /**
+     * The bare verb (e.g. `commit`, `execute`). Derived from `id` after the `:` if absent.
+     */
+    verb?: string;
+    /**
+     * The resource kind this action operates on (e.g. `storage`, `sandbox`, `secrets`). Derived from `id` before the `:` if absent.
+     */
+    target_kind?: string;
+    /**
+     * Resources the action may modify. Inherited by implementors (TOOL, DRIVER); they MAY add more, never drop.
+     */
+    mutates?: string[];
+    /**
+     * Capability requirements gated by AIP-7 governance. Implementors MAY add to this set; MUST NOT remove.
+     */
+    requires?: {
+        network?: string[];
+        secrets?: string[];
+        tools?: string[];
+    };
+    /**
+     * Approval class. Implementors MAY narrow (`auto` → `always` → `on-mutate`); MUST NOT widen.
+     */
+    approval?: ("auto" | "always" | "on-mutate") | string;
+    /**
+     * 0=read-only, 1=scoped writes, 2=external side effects, 3=irreversible. Implementors MAY raise; MUST NOT lower.
+     */
+    risk_level?: number;
+    /**
+     * AIP-37 LIFECYCLE event names this action fires when invoked. Subscribers (sync layers, audit) attach to these. Implementors MAY fire more events; MUST NOT drop any declared here.
+     */
+    fires_events?: string[];
+    /**
+     * OPTIONAL discovery hint — known implementations of this action. NOT authoritative — source of truth lives on implementors via their `implements:` field. Hosts populate from scanning.
+     */
+    implementations?: {
+        /**
+         * Kind of implementation.
+         */
+        kind: "tool" | "driver" | "ui" | "lifecycle";
+        /**
+         * Reference to the implementor (TOOL.md id, DRIVER.md id, UI surface name, etc.).
+         */
+        ref: string;
+    }[];
+    /**
+     * Free-form discovery tags.
+     */
+    tags?: string[];
+    /**
+     * Semantic examples (NOT input/output, since action has no schema). Each `{ name, scenario, note? }`.
+     */
+    examples?: {
+        name: string;
+        scenario: string;
+        note?: string;
+    }[];
+    /**
+     * Free-form, namespaced. Authors MAY stash adapter-specific hints under namespaced keys.
+     */
+    metadata?: {
+        [k: string]: unknown;
+    };
+}
+type ActionHandle = Readonly<ActionDefinition>;
+
+/**
+ * AIP-39 ACTION.md frontmatter zod schema.
+ *
+ * Generated from `resources/aip-39/draft/ACTION.schema.json` via
+ * json-schema-to-zod. Imported by both `define-action.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-action.ts`'s `validate(def)` instead.
+ */
+
+declare const actionFrontmatterSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"action/v1">;
+    id: z.ZodString;
+    description: z.ZodString;
+    version: z.ZodDefault<z.ZodString>;
+    category: z.ZodDefault<z.ZodString>;
+    verb: z.ZodOptional<z.ZodString>;
+    target_kind: z.ZodOptional<z.ZodString>;
+    mutates: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    requires: z.ZodOptional<z.ZodObject<{
+        network: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        secrets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    approval: z.ZodDefault<z.ZodUnion<readonly [z.ZodEnum<{
+        auto: "auto";
+        always: "always";
+        "on-mutate": "on-mutate";
+    }>, z.ZodString]>>;
+    risk_level: z.ZodDefault<z.ZodNumber>;
+    fires_events: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    implementations: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            tool: "tool";
+            driver: "driver";
+            ui: "ui";
+            lifecycle: "lifecycle";
+        }>;
+        ref: z.ZodString;
+    }, z.core.$strict>>>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    examples: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        scenario: z.ZodString;
+        note: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, z.core.$strict>;
+type ActionFrontmatter = z.infer<typeof actionFrontmatterSchema>;
+
+/**
+ * AIP-39 ACTION.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 `defineAction` so the cross-AIP
+ * invariants run uniformly.
+ *
+ *
+ * The frontmatter zod schema below was generated from
+ * `resources/aip-39/draft/ACTION.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 ActionManifest {
+    frontmatter: ActionFrontmatter;
+    body: string;
+}
+declare function parseActionManifest(source: string): ActionManifest;
+declare function actionFromManifest(manifest: ActionManifest): ActionHandle;
+
+export { type ActionDefinition as A, type ActionHandle as a, type ActionManifest as b, actionFromManifest as c, actionFrontmatterSchema as d, type ActionFrontmatter as e, parseActionManifest as p };

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+import { A as ActionDefinition, a as ActionHandle } from './index-CETj5oaU.js';
+export { b as ActionManifest, c as actionFromManifest, d as actionFrontmatterSchema, p as parseActionManifest } from './index-CETj5oaU.js';
+import * as _agentproto_manifest from '@agentproto/manifest';
+import { DoctypeSpec } from '@agentproto/manifest';
+import 'zod';
+
+/**
+ * AIP-39 reference implementation of `defineAction`.
+ *
+ * Built on `createDoctype` so the cross-AIP invariants (id pattern,
+ * description length, top-level freeze, "defineAction (AIP-39): …"
+ * 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 (`parseActionManifest`), 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.
+ */
+declare const defineAction: (def: ActionDefinition) => Readonly<ActionDefinition>;
+
+declare const actionSpec: DoctypeSpec<ActionDefinition, ActionHandle>;
+declare const actionVerbs: _agentproto_manifest.Verbs<ActionDefinition, Readonly<ActionDefinition>>;
+
+/**
+ * @agentproto/action — AIP-39 ACTION.md `defineAction` reference impl.
+ *
+ * A markdown + frontmatter format for declaring an abstract verb / operation that can be performed on a resource — its identity, semantics, side-effect profile, approval class, and lifecycle events. The pivot primitive that TOOL implements (with LLM schema), POLICY references (for grants), INTENT routes to (from user verbs), and WORKFLOW steps invoke. Bottom-up — implementations declare which actions they implement.
+ *
+ * Spec: https://agentproto.sh/docs/aip-39
+ *
+ * Authoring paths:
+ *   - TS:  `defineAction({...})` → `ActionHandle`
+ *   - MD:  `parseActionManifest(src) → actionFromManifest({...})` → `ActionHandle`
+ */
+declare const SPEC_NAME: "agentaction/v1";
+declare const SPEC_VERSION: "1.0.0-alpha";
+
+export { ActionDefinition, ActionHandle, SPEC_NAME, SPEC_VERSION, actionSpec, actionVerbs, defineAction };

package/dist/index.mjs

@@ -0,0 +1,37 @@
+import { defineAction, parseActionManifest } from './chunk-VJCWGENG.mjs';
+export { actionFromManifest, actionFrontmatterSchema, defineAction, parseActionManifest } from './chunk-VJCWGENG.mjs';
+import { createVerbs } from '@agentproto/manifest';
+
+/**
+ * @agentproto/action v0.1.0-alpha
+ * AIP-39 ACTION.md `defineAction` reference implementation.
+ */
+var actionSpec = {
+  name: "action",
+  aip: 39,
+  schemaLiteral: "action/v1",
+  // Path convention: actions live under a `.actions/` dir keyed by
+  // their kebab-cased id. AIP-39's standard library follows the same
+  // shape (`.actions/secrets-reveal/ACTION.md` for id `secrets:reveal`).
+  pathOf: (h) => {
+    const slug = h.id.replace(/:/g, "-");
+    return `.actions/${slug}/ACTION.md`;
+  },
+  define: defineAction,
+  parse: (source) => {
+    const m = parseActionManifest(source);
+    return {
+      frontmatter: m.frontmatter,
+      body: m.body
+    };
+  }
+};
+var actionVerbs = createVerbs(actionSpec);
+
+// src/index.ts
+var SPEC_NAME = "agentaction/v1";
+var SPEC_VERSION = "1.0.0-alpha";
+
+export { SPEC_NAME, SPEC_VERSION, actionSpec, actionVerbs };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/spec.ts","../src/index.ts"],"names":[],"mappings":";;;;;;;;AAaO,IAAM,UAAA,GAA0D;AAAA,EACrE,IAAA,EAAM,QAAA;AAAA,EACN,GAAA,EAAK,EAAA;AAAA,EACL,aAAA,EAAe,WAAA;AAAA;AAAA;AAAA;AAAA,EAIf,MAAA,EAAQ,CAAC,CAAA,KAAM;AACb,IAAA,MAAM,IAAA,GAAO,CAAA,CAAE,EAAA,CAAG,OAAA,CAAQ,MAAM,GAAG,CAAA;AACnC,IAAA,OAAO,YAAY,IAAI,CAAA,UAAA,CAAA;AAAA,EACzB,CAAA;AAAA,EACA,MAAA,EAAQ,YAAA;AAAA,EACR,KAAA,EAAO,CAAC,MAAA,KAAW;AACjB,IAAA,MAAM,CAAA,GAAI,oBAAoB,MAAM,CAAA;AACpC,IAAA,OAAO;AAAA,MACL,aAAa,CAAA,CAAE,WAAA;AAAA,MACf,MAAM,CAAA,CAAE;AAAA,KACV;AAAA,EACF;AACF;AAEO,IAAM,WAAA,GAAc,YAAY,UAAU;;;ACtB1C,IAAM,SAAA,GAAY;AAClB,IAAM,YAAA,GAAe","file":"index.mjs","sourcesContent":["/**\n * AIP-39 doctype spec — fed to `@agentproto/manifest.createVerbs`\n * to derive create / load / list / update / resolve / delete in one\n * place. Plugs into `@agentproto/mcp-server` so an action library\n * lives at `<workspace>/.actions/<id>/ACTION.md` (the convention\n * AIP-39's standard library uses) and is callable over MCP.\n */\n\nimport { createVerbs, type DoctypeSpec } from \"@agentproto/manifest\"\nimport { defineAction } from \"./define-action.js\"\nimport { parseActionManifest } from \"./manifest/index.js\"\nimport type { ActionDefinition, ActionHandle } from \"./types.js\"\n\nexport const actionSpec: DoctypeSpec<ActionDefinition, ActionHandle> = {\n  name: \"action\",\n  aip: 39,\n  schemaLiteral: \"action/v1\",\n  // Path convention: actions live under a `.actions/` dir keyed by\n  // their kebab-cased id. AIP-39's standard library follows the same\n  // shape (`.actions/secrets-reveal/ACTION.md` for id `secrets:reveal`).\n  pathOf: (h) => {\n    const slug = h.id.replace(/:/g, \"-\")\n    return `.actions/${slug}/ACTION.md`\n  },\n  define: defineAction,\n  parse: (source) => {\n    const m = parseActionManifest(source)\n    return {\n      frontmatter: m.frontmatter as unknown as Record<string, unknown>,\n      body: m.body,\n    }\n  },\n}\n\nexport const actionVerbs = createVerbs(actionSpec)\n","/**\n * @agentproto/action — AIP-39 ACTION.md `defineAction` reference impl.\n *\n * A markdown + frontmatter format for declaring an abstract verb / operation that can be performed on a resource — its identity, semantics, side-effect profile, approval class, and lifecycle events. The pivot primitive that TOOL implements (with LLM schema), POLICY references (for grants), INTENT routes to (from user verbs), and WORKFLOW steps invoke. Bottom-up — implementations declare which actions they implement.\n *\n * Spec: https://agentproto.sh/docs/aip-39\n *\n * Authoring paths:\n *   - TS:  `defineAction({...})` → `ActionHandle`\n *   - MD:  `parseActionManifest(src) → actionFromManifest({...})` → `ActionHandle`\n */\n\nexport const SPEC_NAME = \"agentaction/v1\" as const\nexport const SPEC_VERSION = \"1.0.0-alpha\" as const\n\nexport { defineAction } from \"./define-action.js\"\nexport type { ActionDefinition, ActionHandle } from \"./types.js\"\nexport { actionSpec, actionVerbs } from \"./spec.js\"\nexport {\n  parseActionManifest,\n  actionFromManifest,\n  actionFrontmatterSchema,\n  type ActionManifest,\n} from \"./manifest/index.js\"\n"]}

package/dist/manifest/index.d.ts

@@ -0,0 +1,2 @@
+export { e as ActionFrontmatter, b as ActionManifest, c as actionFromManifest, d as actionFrontmatterSchema, p as parseActionManifest } from '../index-CETj5oaU.js';
+import 'zod';

package/dist/manifest/index.mjs

@@ -0,0 +1,3 @@
+export { actionFromManifest, actionFrontmatterSchema, parseActionManifest } from '../chunk-VJCWGENG.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/action",
+  "version": "0.1.0",
+  "description": "@agentproto/action — AIP-39 ACTION.md reference implementation. A markdown + frontmatter format for declaring an abstract verb / operation that can be performed on a resource — its identity, semantics, side-effect profile, approval class, and lifecycle events. The pivot primitive that TOOL implements (with LLM schema), POLICY references (for grants), INTENT routes to (from user verbs), and WORKFLOW steps invoke. Bottom-up — implementations declare which actions they implement.",
+  "keywords": [
+    "agentproto",
+    "aip-39",
+    "action",
+    "defineAction",
+    "open-standard",
+    "agentic"
+  ],
+  "homepage": "https://agentproto.sh/docs/aip-39",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentproto/ts",
+    "directory": "packages/action"
+  },
+  "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"
+  }
+}