AIP-37: LIFECYCLE.md — agentlifecycle/v1 (event vocabulary)

AbstractCopy Anchor Link

This AIP defines a vocabulary of lifecycle event names that hosts fire and that policy blocks across the AIP series reference. It is not a runtime contract — hosts choose which events they fire and how. The AIP just standardizes the event names so configs that reference them (e.g. STORAGE.md.sync.commit.on: turn-end) mean the same thing on any conformant host.

There is no LIFECYCLE.md file format. This AIP is purely a lookup table for event identifiers.

MotivationCopy Anchor Link

Several AIPs in the series want to express "do X when Y happens":

• STORAGE.md.sync.commit.on: per-turn — commit when an agent turn ends
• SANDBOX.md.lifecycle.destroy_on: workspace-close — destroy when workspace closes
• CODE.md.identity.refresh_on: conversation-start — re-resolve identity when a conversation starts

If each AIP coins its own event names, configs become incompatible. The same intent ("after each agent turn") gets spelled three different ways. Reviewing a manifest requires knowing the local vocabulary of each block.

This AIP gives a shared vocabulary. Any AIP that needs lifecycle triggers MAY reference an event from this list, knowing every conformant host fires the events under the same names.

Design principlesCopy Anchor Link

1. Vocabulary, not behaviour. The AIP defines names + semantic meaning. It does NOT define when events MUST fire — that is host policy.

2. Open enumeration. Hosts MAY fire additional events beyond this list (e.g. agentik:custom-trigger). Names without a colon prefix are reserved for this spec; namespaced names (<host>:<event>) are host-specific.

3. No event payload spec. The AIP defines event names only. Payloads (which workspace, which conversation, etc.) are host-specific bindings that consumers extract from the host's request context.

4. Best-effort firing. A host that doesn't fire an event listed here is non-conformant for that event but otherwise compliant. Configs MUST tolerate missing events (treat as "never trigger") rather than crash.

SpecificationCopy Anchor Link

Standard event namesCopy Anchor Link

Event names are kebab-case, lowercase, no colons (colons reserved for host namespaces).

Workspace lifecycleCopy Anchor Link

Conversation lifecycleCopy Anchor Link

Agent turn lifecycleCopy Anchor Link

Tool / command lifecycleCopy Anchor Link

File / write lifecycleCopy Anchor Link

Run / step lifecycle (added 2026-09-25, per AIP-58)Copy Anchor Link

AIP-58 RUN's event log is host-written and per-run — it does not itself broadcast to this vocabulary's cross-cutting listeners the way turn-end or write do. The names below are registered here so that a sync.commit.on:-style consumer (STORAGE.md, SANDBOX.md, …) MAY reference a run/step transition using the same shared vocabulary this AIP already provides for every other lifecycle phase, exactly as design principle 1 intends. AIP-58 §5 is the normative source for when each of these actually fires and what data it carries; this table only registers the names.

Idle hooksCopy Anchor Link

ManualCopy Anchor Link

AliasesCopy Anchor Link

These shorthand names alias to standard events for ergonomics:

Reference syntaxCopy Anchor Link

Consumers (other AIPs) reference events as bare strings:

# In STORAGE.md
sync:
  commit:
    on: per-turn          # alias for turn-end

# In SANDBOX.md
lifecycle:
  destroy_on: workspace-close

# Custom (namespaced) — host-specific, not in this AIP
sync:
  pull:
    on: agentik:scheduled-pull

Conformance rulesCopy Anchor Link

1. Hosts SHOULD fire the events listed here when their semantic conditions are met. A host that supports a subset of events MUST document which.

2. Configs MUST tolerate missing events. If a config references turn-end but the host doesn't fire it, the trigger MUST be silently skipped (logged, but not erroring).

3. Aliases MUST resolve transparently. A host that supports turn-end MUST also accept per-turn as the same trigger.

4. Namespaced events (<host>:<event>) are non-portable. Configs using namespaced events declare an explicit host dependency.

Backward compatibilityCopy Anchor Link

This AIP is purely additive. Existing AIPs (STORAGE.md, SANDBOX.md, CODE.md, etc.) MAY reference these event names without changing their own schemas — the references are bare strings interpreted at runtime.

2026-09-25 — added the run.* / step.* names (Run / step lifecycle) registered by AIP-58 RUN. Purely additive, same as every prior addition to this table.

Security considerationsCopy Anchor Link

Event names are not security-sensitive. Hosts MUST NOT include sensitive data (credentials, PII) in event names — those go in payloads, which this AIP does not specify.

See alsoCopy Anchor Link

• AIP-35 STORAGE.md — sync.{pull,commit,push}.on consumes events
• AIP-36 SANDBOX.md — lifecycle.{destroy_on,pause_on} consumes events
• AIP-26 CODE.md — identity.refresh_on consumes events
• AIP-58 RUN — registers the run.* / step.* names