@agentproto/lifecycle 0.1.0-alpha.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/lifecycle
+
+AIP-37 `LIFECYCLE.md` reference implementation. A vocabulary AIP defining the standard lifecycle event names that hosts fire and that policy blocks (storage sync, sandbox lifecycle, etc.) reference. Not a runtime — just a shared language so configs across hosts mean the same thing.
+
+> **Status: 0.1.0-alpha.** Generated by `scripts/scaffold-aip.mjs` — `build()` and `validate()` bodies are TODOs.
+
+Spec: <https://agentproto.sh/docs/aip-37>
+
+## Usage
+
+```ts
+import { defineLifecycle } from "@agentproto/lifecycle"
+
+const x = defineLifecycle({
+  id: "my-lifecycle",
+  description: "Short purpose.",
+  // ...
+})
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @agentproto/lifecycle — AIP-37 event-name vocabulary.
+ *
+ * Type: Meta. There is no `defineLifecycle` doctype — AIP-37 specifies a
+ * shared vocabulary of event names that other AIPs reference (e.g.
+ * `STORAGE.md.sync.commit.on: turn-end`). This package exports the
+ * constants + alias resolution so consumers get type-safe event names.
+ *
+ * Spec: https://agentproto.sh/docs/aip-37
+ */
+declare const SPEC_NAME: "agentlifecycle/v1";
+declare const SPEC_VERSION: "1.0.0-alpha";
+/**
+ * Standard lifecycle event names. Kebab-case, no colons (colons reserved
+ * for host namespaces like `agentik:custom-trigger`).
+ *
+ * Hosts MAY fire additional events beyond this list; configs reference
+ * any event name as a bare string. This array is the union of "events
+ * that conformant hosts SHOULD fire when their semantic conditions hold."
+ */
+declare const LIFECYCLE_EVENTS: readonly ["workspace-open", "workspace-close", "conversation-start", "conversation-end", "turn-start", "turn-end", "turn-error", "tool-call", "tool-result", "tool-error", "write", "delete", "manual"];
+type LifecycleEvent = (typeof LIFECYCLE_EVENTS)[number];
+/**
+ * Templated event names — hosts substitute the placeholder before firing.
+ * `idle-<N>` and `conversation-idle-<N>` accept a positive integer
+ * `N` (seconds since the relevant scope went idle).
+ */
+declare const LIFECYCLE_TEMPLATED_EVENTS: readonly ["idle", "conversation-idle"];
+type LifecycleTemplatedEvent = (typeof LIFECYCLE_TEMPLATED_EVENTS)[number];
+/**
+ * Aliases — shorthand names that resolve to standard event names.
+ * Hosts MUST accept aliases transparently (a config saying
+ * `commit.on: per-turn` is equivalent to `commit.on: turn-end`).
+ */
+declare const LIFECYCLE_ALIASES: {
+    readonly "each-write": "write";
+    readonly "per-turn": "turn-end";
+    readonly "per-conversation": "conversation-end";
+};
+type LifecycleAlias = keyof typeof LIFECYCLE_ALIASES;
+/**
+ * Resolve any event reference (alias, standard, templated, or
+ * host-namespaced) to its canonical form. Aliases are rewritten;
+ * everything else passes through. Returns the input unchanged when
+ * no alias matches — consumers handle templated and namespaced
+ * events themselves.
+ */
+declare function resolveLifecycleEvent(name: string): string;
+/**
+ * True if `name` is one of the standard event names listed in this
+ * spec. Useful for host implementations to decide whether they
+ * support firing the event.
+ */
+declare function isStandardLifecycleEvent(name: string): name is LifecycleEvent;
+/**
+ * Parse a templated event name (`idle-300`, `conversation-idle-600`)
+ * into its base + the integer threshold. Returns null when the name
+ * isn't a templated event.
+ */
+declare function parseTemplatedLifecycleEvent(name: string): {
+    base: LifecycleTemplatedEvent;
+    thresholdSeconds: number;
+} | null;
+/**
+ * True if `name` is a host-namespaced (non-portable) event like
+ * `agentik:scheduled-pull`. Configs using these declare an explicit
+ * host dependency.
+ */
+declare function isNamespacedLifecycleEvent(name: string): boolean;
+
+export { LIFECYCLE_ALIASES, LIFECYCLE_EVENTS, LIFECYCLE_TEMPLATED_EVENTS, type LifecycleAlias, type LifecycleEvent, type LifecycleTemplatedEvent, SPEC_NAME, SPEC_VERSION, isNamespacedLifecycleEvent, isStandardLifecycleEvent, parseTemplatedLifecycleEvent, resolveLifecycleEvent };

package/dist/index.mjs

@@ -0,0 +1,60 @@
+/**
+ * @agentproto/lifecycle v0.1.0-alpha
+ * AIP-37 LIFECYCLE event-name vocabulary (Meta type — no doctype).
+ */
+
+// src/index.ts
+var SPEC_NAME = "agentlifecycle/v1";
+var SPEC_VERSION = "1.0.0-alpha";
+var LIFECYCLE_EVENTS = [
+  // Workspace lifecycle
+  "workspace-open",
+  "workspace-close",
+  // Conversation lifecycle
+  "conversation-start",
+  "conversation-end",
+  // Agent turn lifecycle
+  "turn-start",
+  "turn-end",
+  "turn-error",
+  // Tool / command lifecycle
+  "tool-call",
+  "tool-result",
+  "tool-error",
+  // File / write lifecycle
+  "write",
+  "delete",
+  // Manual
+  "manual"
+];
+var LIFECYCLE_TEMPLATED_EVENTS = ["idle", "conversation-idle"];
+var LIFECYCLE_ALIASES = {
+  "each-write": "write",
+  "per-turn": "turn-end",
+  "per-conversation": "conversation-end"
+};
+function resolveLifecycleEvent(name) {
+  return name in LIFECYCLE_ALIASES ? LIFECYCLE_ALIASES[name] : name;
+}
+function isStandardLifecycleEvent(name) {
+  return LIFECYCLE_EVENTS.includes(name);
+}
+function parseTemplatedLifecycleEvent(name) {
+  for (const base of LIFECYCLE_TEMPLATED_EVENTS) {
+    if (name.startsWith(`${base}-`)) {
+      const tail = name.slice(base.length + 1);
+      const n = Number(tail);
+      if (Number.isInteger(n) && n > 0) {
+        return { base, thresholdSeconds: n };
+      }
+    }
+  }
+  return null;
+}
+function isNamespacedLifecycleEvent(name) {
+  return name.includes(":");
+}
+
+export { LIFECYCLE_ALIASES, LIFECYCLE_EVENTS, LIFECYCLE_TEMPLATED_EVENTS, SPEC_NAME, SPEC_VERSION, isNamespacedLifecycleEvent, isStandardLifecycleEvent, parseTemplatedLifecycleEvent, resolveLifecycleEvent };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";;;;;;AAWO,IAAM,SAAA,GAAY;AAClB,IAAM,YAAA,GAAe;AAUrB,IAAM,gBAAA,GAAmB;AAAA;AAAA,EAE9B,gBAAA;AAAA,EACA,iBAAA;AAAA;AAAA,EAEA,oBAAA;AAAA,EACA,kBAAA;AAAA;AAAA,EAEA,YAAA;AAAA,EACA,UAAA;AAAA,EACA,YAAA;AAAA;AAAA,EAEA,WAAA;AAAA,EACA,aAAA;AAAA,EACA,YAAA;AAAA;AAAA,EAEA,OAAA;AAAA,EACA,QAAA;AAAA;AAAA,EAEA;AACF;AASO,IAAM,0BAAA,GAA6B,CAAC,MAAA,EAAQ,mBAAmB;AAU/D,IAAM,iBAAA,GAAoB;AAAA,EAC/B,YAAA,EAAc,OAAA;AAAA,EACd,UAAA,EAAY,UAAA;AAAA,EACZ,kBAAA,EAAoB;AACtB;AAWO,SAAS,sBAAsB,IAAA,EAAsB;AAC1D,EAAA,OAAO,IAAA,IAAQ,iBAAA,GACX,iBAAA,CAAkB,IAAsB,CAAA,GACxC,IAAA;AACN;AAOO,SAAS,yBACd,IAAA,EACwB;AACxB,EAAA,OAAQ,gBAAA,CAAuC,SAAS,IAAI,CAAA;AAC9D;AAOO,SAAS,6BACd,IAAA,EACoE;AACpE,EAAA,KAAA,MAAW,QAAQ,0BAAA,EAA4B;AAC7C,IAAA,IAAI,IAAA,CAAK,UAAA,CAAW,CAAA,EAAG,IAAI,GAAG,CAAA,EAAG;AAC/B,MAAA,MAAM,IAAA,GAAO,IAAA,CAAK,KAAA,CAAM,IAAA,CAAK,SAAS,CAAC,CAAA;AACvC,MAAA,MAAM,CAAA,GAAI,OAAO,IAAI,CAAA;AACrB,MAAA,IAAI,MAAA,CAAO,SAAA,CAAU,CAAC,CAAA,IAAK,IAAI,CAAA,EAAG;AAChC,QAAA,OAAO,EAAE,IAAA,EAAM,gBAAA,EAAkB,CAAA,EAAE;AAAA,MACrC;AAAA,IACF;AAAA,EACF;AACA,EAAA,OAAO,IAAA;AACT;AAOO,SAAS,2BAA2B,IAAA,EAAuB;AAChE,EAAA,OAAO,IAAA,CAAK,SAAS,GAAG,CAAA;AAC1B","file":"index.mjs","sourcesContent":["/**\n * @agentproto/lifecycle — AIP-37 event-name vocabulary.\n *\n * Type: Meta. There is no `defineLifecycle` doctype — AIP-37 specifies a\n * shared vocabulary of event names that other AIPs reference (e.g.\n * `STORAGE.md.sync.commit.on: turn-end`). This package exports the\n * constants + alias resolution so consumers get type-safe event names.\n *\n * Spec: https://agentproto.sh/docs/aip-37\n */\n\nexport const SPEC_NAME = \"agentlifecycle/v1\" as const\nexport const SPEC_VERSION = \"1.0.0-alpha\" as const\n\n/**\n * Standard lifecycle event names. Kebab-case, no colons (colons reserved\n * for host namespaces like `agentik:custom-trigger`).\n *\n * Hosts MAY fire additional events beyond this list; configs reference\n * any event name as a bare string. This array is the union of \"events\n * that conformant hosts SHOULD fire when their semantic conditions hold.\"\n */\nexport const LIFECYCLE_EVENTS = [\n  // Workspace lifecycle\n  \"workspace-open\",\n  \"workspace-close\",\n  // Conversation lifecycle\n  \"conversation-start\",\n  \"conversation-end\",\n  // Agent turn lifecycle\n  \"turn-start\",\n  \"turn-end\",\n  \"turn-error\",\n  // Tool / command lifecycle\n  \"tool-call\",\n  \"tool-result\",\n  \"tool-error\",\n  // File / write lifecycle\n  \"write\",\n  \"delete\",\n  // Manual\n  \"manual\",\n] as const\n\nexport type LifecycleEvent = (typeof LIFECYCLE_EVENTS)[number]\n\n/**\n * Templated event names — hosts substitute the placeholder before firing.\n * `idle-<N>` and `conversation-idle-<N>` accept a positive integer\n * `N` (seconds since the relevant scope went idle).\n */\nexport const LIFECYCLE_TEMPLATED_EVENTS = [\"idle\", \"conversation-idle\"] as const\n\nexport type LifecycleTemplatedEvent =\n  (typeof LIFECYCLE_TEMPLATED_EVENTS)[number]\n\n/**\n * Aliases — shorthand names that resolve to standard event names.\n * Hosts MUST accept aliases transparently (a config saying\n * `commit.on: per-turn` is equivalent to `commit.on: turn-end`).\n */\nexport const LIFECYCLE_ALIASES = {\n  \"each-write\": \"write\",\n  \"per-turn\": \"turn-end\",\n  \"per-conversation\": \"conversation-end\",\n} as const\n\nexport type LifecycleAlias = keyof typeof LIFECYCLE_ALIASES\n\n/**\n * Resolve any event reference (alias, standard, templated, or\n * host-namespaced) to its canonical form. Aliases are rewritten;\n * everything else passes through. Returns the input unchanged when\n * no alias matches — consumers handle templated and namespaced\n * events themselves.\n */\nexport function resolveLifecycleEvent(name: string): string {\n  return name in LIFECYCLE_ALIASES\n    ? LIFECYCLE_ALIASES[name as LifecycleAlias]\n    : name\n}\n\n/**\n * True if `name` is one of the standard event names listed in this\n * spec. Useful for host implementations to decide whether they\n * support firing the event.\n */\nexport function isStandardLifecycleEvent(\n  name: string\n): name is LifecycleEvent {\n  return (LIFECYCLE_EVENTS as readonly string[]).includes(name)\n}\n\n/**\n * Parse a templated event name (`idle-300`, `conversation-idle-600`)\n * into its base + the integer threshold. Returns null when the name\n * isn't a templated event.\n */\nexport function parseTemplatedLifecycleEvent(\n  name: string\n): { base: LifecycleTemplatedEvent; thresholdSeconds: number } | null {\n  for (const base of LIFECYCLE_TEMPLATED_EVENTS) {\n    if (name.startsWith(`${base}-`)) {\n      const tail = name.slice(base.length + 1)\n      const n = Number(tail)\n      if (Number.isInteger(n) && n > 0) {\n        return { base, thresholdSeconds: n }\n      }\n    }\n  }\n  return null\n}\n\n/**\n * True if `name` is a host-namespaced (non-portable) event like\n * `agentik:scheduled-pull`. Configs using these declare an explicit\n * host dependency.\n */\nexport function isNamespacedLifecycleEvent(name: string): boolean {\n  return name.includes(\":\")\n}\n"]}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@agentproto/lifecycle",
+  "version": "0.1.0-alpha.0",
+  "description": "@agentproto/lifecycle — AIP-37 LIFECYCLE.md reference implementation. A vocabulary AIP defining the standard lifecycle event names that hosts fire and that policy blocks (storage sync, sandbox lifecycle, etc.) reference. Not a runtime — just a shared language so configs across hosts mean the same thing.",
+  "keywords": [
+    "agentproto",
+    "aip-37",
+    "lifecycle",
+    "events",
+    "vocabulary",
+    "open-standard",
+    "agentic"
+  ],
+  "homepage": "https://agentproto.sh/docs/aip-37",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentproto/ts",
+    "directory": "packages/lifecycle"
+  },
+  "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"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "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"
+  }
+}