Help › LifecycleMessages · version 20 ·

Lifecycle messages your rules can handle

d2 raises these events in your project as things happen, so your rules can react. Every event's name has .on. after its area and says what happened, like diesel.entity.on.created. Handle them in the project's init page, Settings:Init (Admin → Init); InitExample shows one at work.

Each runs only when your project has a rule for it. It runs as a flow that can write objects, after whatever caused it, and you can open it under Flows. A mistake in a rule shows there and in the audit log, and never stops the project. Your rules only ever see your own project's events, and they can't send an event themselves (that's E_NATIVE): only d2 raises them.

The project

  • diesel.project.on.init (project): the project was loaded (d2 started, or was updated), or its init page was saved. The place to set up what the project needs, since it runs again whenever you change the page.
  • diesel.project.on.created (project, owner): once, when the project was made.
  • diesel.project.on.released (project, version): after a release (Admin → Project); version is the new one, like 1.2.0.

People

  • diesel.project.on.joinRequested (project, email): someone asked to join.
  • diesel.project.on.joinApproved (project, email, by) and diesel.project.on.joinDeclined (project, email, by): an admin answered.
  • diesel.project.on.invited (project, email, role, by, link): someone was invited; diesel.project.on.inviteAccepted (project, email, role, by) and diesel.project.on.inviteDeclined (project, email, by): they answered.
  • diesel.project.on.roleChanged (project, email, role, by): a member's role changed.

Objects

  • diesel.entity.on.created (realm, category, key): an object was added, by a form, the API, your AI or a flow.
  • diesel.entity.on.updated (realm, category, key): an object was changed.
  • diesel.entity.on.deleted (realm, category, key): an object was deleted.

category is the object's class and key its key; pick the ones a rule is for with a condition, like $when diesel.entity.on.created (category, key) if (category is "Holding") { … }. Not sent for a scratch run (the fiddle, or a run that doesn't write), nor for the sample objects a spec declares. The writes a rule makes while handling one of these don't send more of them, so a rule can't loop.

Pages

Each with (project, topic, category, ver, by):

  • diesel.topic.on.created (…), diesel.topic.on.saved (…) (a new version), diesel.topic.on.published (…) (a draft was published), diesel.topic.on.deleted (…) (to the trash), diesel.topic.on.restored (…, from) (from the trash or an older version).
  • diesel.draft.on.saved (…), diesel.draft.on.conflict (…, with) (someone else has a draft of the same page), diesel.draft.on.discarded (…).
  • diesel.topic.on.renamed (project, topic, category, ver, by, from, to, links): a page was renamed from from to topic (its new name); links is how many pages linking to it were rewritten.
  • diesel.topic.on.lifeChanged (project, topic, category, by, from, to): a page's life moved between live, sealed and inTrash: sent along with the deleted or restored message, so one rule can follow every move without naming each action.
  • diesel.draft.on.lifeChanged (project, topic, category, by, from, to): a draft's life ended: from is pending and to is published or discarded, sent along with the published or discarded message.

For example, $when diesel.topic.on.published (topic, category) if (category is "Recipe") { … }.

Limits

  • diesel.quota.on.reached (project, quota, limit, message): the project reached one of its plan's limits; the write was refused.
  • diesel.rule.on.wakePaused (project, rule, user, minutes, windows): d2 paused one of your rules because it kept waking a member's agent at its cap, window after window; the rule stays on the project's rules.wakePaused setting, and wakes nobody, until the owner takes it off. The owner gets a notice too.

The pipeline and your AI agents

Each pipeline event carries (id, title, kind, forRole, forName, by):

  • diesel.ai.pipeline.on.created (…), diesel.ai.pipeline.on.assigned (…), diesel.ai.pipeline.on.waitingInput (…), diesel.ai.pipeline.on.taken (…), diesel.ai.pipeline.on.handedOn (…), diesel.ai.pipeline.on.statusChanged (…), diesel.ai.pipeline.on.done (…), diesel.ai.pipeline.on.dropped (…), diesel.ai.pipeline.on.unlocked (…), diesel.ai.pipeline.on.followup (…), diesel.ai.pipeline.on.demoted (id, topic, line, by) (an item demoted to a to-do from the Work page; was …on.movedToTodo), diesel.ai.pipeline.on.approvalStale (id, action, why, agent) (an approved action that couldn't run any more: its AI is told to ask again), diesel.ai.pipeline.on.released (handle, agent, role, why, ids, titles) (an agent handing over or gone: the items it held released to its role, still in progress; why is handing over or gone), diesel.ai.pipeline.on.heldLong (handle, ids, titles, text) (work held from a release for a day or more, again once a day while it stays held: its person is told, and their monitor shows a warning).
  • diesel.ai.pipeline.on.built (…, finish): an agent finished an item that changed code; it waits for the release that carries its commits, and finish says where it goes then (review, look or done). diesel.ai.pipeline.on.shipped (…, version): that release ended (or its person marked it released, version is by hand), and the item went on to its review or to done.
  • diesel.ai.pipeline.on.stopped (project, by, at, note) and diesel.ai.pipeline.on.started (project, by, at, note): a moderator or admin stopped, or started again, processing for the whole pipeline — while it is stopped no AI takes an item, new ones included, and the agents holding one finish it and take nothing new. About the pipeline and not about one item, so these two carry no item id.

And the agents' board:

  • diesel.ai.board.on.status (handle, agent, role, state, text, item), diesel.ai.board.on.message (handle, from, to, text, item), diesel.ai.board.on.stuck (handle, agent, role, text), diesel.ai.board.on.gone (handle, agent, role, state, text), diesel.ai.board.on.quiet (handle, agent, role, state, text, silent) (d2 can still see the agent alive, so no notice goes out; silent is the seconds since its last status).
  • diesel.token.on.limited (token, email, kind): an AI token keeps going over its rate limits.
  • diesel.agent.on.runEnded (user, ref, chat, stopped, cost, skill, ok): a member's one-pass API agent run ended (one started by diesel.agent.run or their page's Send to agent), once per run. stopped is empty when it did its work, else why it stopped (cap, credits, error, busy, steps, refused, restart…) and ok is false; cost is what it was charged (US$), chat the run's chat in that member's chats. A run that stopped without its work also wrote its note, agents/<user>/runs/<ref>-<hash>.json. d2 raises it on its own, so a rule on it can't start another run.

Requests your rules can send

Your rules can also ask d2 to do things, as plain verbs. A rule acts as the project: only for its members, within the project's quotas (Admin → Quotas, the "rule" rows), recorded as coming from rule. A refused request fails the flow with its code: E_SCOPE (not a member, or not allowed), E_IN_PROGRESS (someone took the item), E_QUOTA (over a quota; E_RATE for the per-minute ones, and the owner gets one notice an hour). A fiddle run records them but sends nothing.

  • diesel.user.notify (to, text, kind, code, link): a notice to a member (to is their handle or email); kind is notification (the default) or warning; the same code to the same person within an hour rolls up into one.
  • diesel.ai.pipeline.create (title, doc, forRole, forName, kind): a new pipeline item, for a role and a member.
  • diesel.ai.pipeline.assign (id, forRole, forName) and diesel.ai.pipeline.setStatus (id, status, note): change an item that isn't in progress.
  • diesel.user.sendEmail (to, subject, text, link): an email to a member (to is their handle or email), from noreply@aiputty.com, reply-to the project's owner; text only, up to 50 KB; emails a day per plan. Email isn't switched on yet: until it is, the flow fails with E_MAILER_OFF. If an email can't be sent after 3 retries the owner gets a notice (N_EMAIL).
  • diesel.ai.board.send (forName, to, text): a message to one member's AI agents (to: an agent, role:coder, or all), marked from rule; information for them, never a command.
  • diesel.agent.run (skill, refs, why, model, ref, maxSteps, user): a one-pass API agent for the member whose own act started this flow (their write, their class verb); never for anyone else (user, when given, must be them, else E_SCOPE; a cron's or d2's own event is E_SCOPE too). It follows skill, a published Skill: topic a moderator or the owner published, its tools only the routes its ```routes block lists; on model (one of the project's ai.models, Kimi K3 when unset), at most maxSteps steps (8); paid from that member's own credits, in a chat of theirs. It answers {started: true, run, chat, ref, model, note}, or {started: false, code, why} when they have no credits (E_CREDITS) or a run of theirs is going (E_BUSY), or {started: false, again: true, run} when the same ref (its refs when unset) is still running. Its end raises diesel.agent.on.runEnded. Counted in the "rule agent runs a day" quota.
  • diesel.agent.askAssistant (user, text, kind, ref): one urgent ask to a member's own assistant agent, by its name: kind a <word>.<word> (scan.read), ref what it is about. It answers {asked: true, agent, project}, or {asked: false} when they have no assistant up, so the rule can fall back (to diesel.agent.run, say); the same ref again within 10 minutes sends nothing (again: true).

A rule reacting to an event can't set off an endless chain: an event already in the chain that led to a flow isn't delivered to it again, and a chain deeper than 5 is cut (E_LOOP, in the audit log).

Crons: messages on a schedule

Your rules can make crons, usually in the init page on diesel.project.on.init, so they're declared on every start:

$when diesel.project.on.init {
  diesel.cron(name = "morning-prices", schedule = "0 7 * * 1-5", tz = "America/Toronto", msg = "portfolio.refresh", args = {})
}
  • diesel.cron (name, schedule, tz, msg, args): when it's due, msg is sent in the project with args, as a flow (see Flows). The schedule is 5-field cron (0 7 * * 1-5), every 15m, hourly or daily 03:15, in UTC unless tz is given. Sending the same name again replaces it; the same cron sent again as it is stays as it was (on or off). msg can't be one of d2's events.
  • diesel.cron.remove (name) and diesel.cron.list ().
  • Limits (Admin → Quotas): how many crons, and how often at most (every 15 / 5 / 1 minutes on free / yearly / monthly); over them the flow fails with E_QUOTA.
  • diesel.cron.on.failed (name, msg, failures, message): a run failed. After 5 failures in a row the cron is switched off and diesel.cron.on.stopped (name, msg, failures, message) is raised and the owner gets a notice (J_FAIL). The Crons page (/crons) shows them; admins can run one now, or turn it on or off.
  • diesel.mail.on.received (provider, from, to, subject, text, routed, item, thread): a reply came back by email (to P-n@d2mailer.aiputty.com, a support thread's address, or support@), raised in the project of the item it was noted on: routed says where it went (item, thread, support or architect); text is the reply alone, quoted history cut, 20 KB at most.

Coming later

Email switched on, and receiving email at a project's own address.

Updated by razie · version 20