Reusable scheduled lifecycle helpers for AI agents.

These functions keep scheduling mechanics and error handling generic while concrete agents provide memory construction, authorization, and compaction policy.

Functions

compact-stale-sessions

fn (rt: ::ai::agent::runtime/AgentRuntime, handler: Fn): Vec<LifecycleJob>

Run an app-provided compaction handler for all registered sessions.

Example

::lifecycle ::ai::agent::lifecycle
::runtime ::ai::agent::runtime

rt ::runtime/create-runtime("team-agent")
jobs ::lifecycle/compact-stale-sessions(rt, (session) {
    {compacted: session.id}
})
length(jobs)

job-error

fn (rt: ::ai::agent::runtime/AgentRuntime, session: ::ai::session/Session, action: Str, error: Any): LifecycleJob

Build a failed LifecycleJob result and record it in the runtime error log.

Example

::lifecycle ::ai::agent::lifecycle
::runtime ::ai::agent::runtime

rt ::runtime/create-runtime("team-agent")
job ::lifecycle/job-error(rt, ::ai::session/Session({id: "s1"}), "compact", "store unavailable")
job.error

job-ok

fn (session: ::ai::session/Session, action: Str, result: Any?): LifecycleJob

Build a successful LifecycleJob result.

Example

::lifecycle ::ai::agent::lifecycle

job ::lifecycle/job-ok(::ai::session/Session({id: "s1"}), "compact", {kept: 3})
job.ok  // true
job.session-id  // "s1"

prune-raw-memory

fn (mem: ::ai::memory/AgentMemory, policy: ::ai::agent::memory/RetentionPolicy): Int

Prune raw session memory older than policy.raw-retention-secs; returns deleted count.

Example

::lifecycle ::ai::agent::lifecycle
::session ::ai::session

mem ::ai::memory/create-memory(
    "team-agent",
    ::session/Session({id: "slack:C123"}),
    ::session/Identity({id: "u1", name: "Ada", meta: {}})
)
policy ::ai::agent::memory/RetentionPolicy({name: "30-days", raw-retention-secs: 2592000})
deleted ::lifecycle/prune-raw-memory(mem, policy)
`pruned ${deleted} records`

prune-sessions

fn (rt: ::ai::agent::runtime/AgentRuntime, policy: ::ai::agent::memory/RetentionPolicy, memory-for-session: Fn): Vec<LifecycleJob>

Run an app-provided memory factory and prune handler for all registered sessions.

Example

::lifecycle ::ai::agent::lifecycle
::runtime ::ai::agent::runtime

rt ::runtime/create-runtime("team-agent")
policy ::ai::agent::memory/RetentionPolicy({name: "30-days", raw-retention-secs: 2592000})
owner ::ai::session/Identity({id: "team-agent", name: "Team Agent", meta: {}})
jobs ::lifecycle/prune-sessions(rt, policy, (session) {
    ::ai::memory/create-memory("team-agent", session, owner)
})
map(jobs, %.result)

run-session-job

fn (rt: ::ai::agent::runtime/AgentRuntime, action: Str, handler: Fn): Vec<LifecycleJob>

Run handler(session) for every registered session and collect a LifecycleJob per session.

Per-session recovery: whether a handler halts via fail() / cancel() or returns a Result.Err value, the error is captured and recorded on rt.errors-store, and the slot becomes LifecycleJob.ok = false. The loop always processes every session and always returns a uniform Vec<LifecycleJob> — halts never escape run-session-job.

Example

::lifecycle ::ai::agent::lifecycle
::runtime ::ai::agent::runtime

rt ::runtime/create-runtime("team-agent")
jobs ::lifecycle/run-session-job(rt, "daily-recap", (session) {
    `recap for ${session.id}`
})
// A handler failure becomes ok: false on that session's job.
filter(jobs, (job) { not(job.ok) })

schedule-descriptor

fn (name: Str, cron: Str, action: Str): Map

Return a neutral descriptor agents can attach to scheduled lifecycle functions.

Example

descriptor ::ai::agent::lifecycle/schedule-descriptor("nightly-prune", "0 3 * * *", "prune-raw-memory")
descriptor.cron  // "0 3 * * *"
descriptor.action  // "prune-raw-memory"

Types

LifecycleJob

LifecycleJob type {
    session-id: Str,
    action: Str,
    ok: Bool,
    result: Any?,
    error: Str?
}

Result record from a lifecycle job applied to one session.