engine

Overview ¶

Agent memory: per-thread conversation transcripts for the ai-agent block, persisted in the runtime KV store. An ai-agent with a memoryThreadId loads the prior transcript before its run and saves the accumulated transcript after, compacting it when it grows past its token budget. The clear-agent-memory leaf block wipes a thread. All memory objects live in the user namespace under a dedicated prefix so they never collide with object-read/write keys.

Caching built on the runtime KV store: the cache-scope composite memoizes the body its wrapped flow produces, and the invalidate-cache leaf evicts an entry. Both key the user namespace (core.NamespaceUser) by the SHA-256 of an evaluated CEL key, so an invalidate-cache with the same key expression targets the same entry a cache-scope wrote.

The KV store has no native TTL, so cache-scope encodes the expiry inside the stored value (cacheEnvelope) and checks it on read; an expired entry is treated as a miss and overwritten on the next run. Only the message body is cached: variables the wrapped flow sets are not restored on a hit.

Package engine assembles and runs message-processing flows. It is the runtime's pipeline implementation: the Flow type, the builder that turns a FlowConfig into a tree of leaf and composite blocks, the composite kinds (scope, fork, if, switch, foreach), and the built-in setter blocks. It is internal — callers wire flows through the public core package and the runtime service.

Built-in flow-ref block: invokes another flow by name. It registers on the process-wide block registry like the other built-ins. A flow-ref calls a flow that has no external source (an implicit-source flow), reached through the flow caller wired into BlockDeps.

Built-in leaf blocks that read and write objects in the runtime KV store: object-read and object-write. They register on the process-wide block registry so they are always available once the engine is linked, and reach the store through the runtime services carried on the context (core.RuntimeServicesFromContext), so no connector is required.

Both confine themselves to the user namespace (core.NamespaceUser): the store isolates keys per namespace, so a user flow's objects never collide with or expose internal runtime state. Each block compiles its CEL expressions once at build time, so a malformed expression fails at startup rather than per message.

Schema-only metadata for composite (control-flow) blocks. Composites are not leaf blocks: they are dispatched by the flow builder (flow.go) and read their typed sub-flow slots off types.BlockConfig, so they have no settings struct to reflect. Instead each declares a schema-only meta struct here — never decoded, only reflected for the editor schema — whose fields carry octo slot tags. A pure sub-flow slot uses a *struct{} placeholder since type=flow overrides inference and no value is read from it.

Built-in leaf blocks that mutate the message: set-payload, set-variable, and delete-variable. They register on the process-wide block registry so they are always available once the engine is linked, without importing the optional processors module. Each compiles its CEL expression once at build time, so a malformed expression fails at startup rather than per message.

The multi-transform leaf block applies an ordered sequence of CEL edits to the message in one pass. Each step either sets the body (setBody) or a variable (setVar/value); the edits are additive, so a later step's expression sees the results of the earlier ones (the activation is rebuilt before every step). It lets a flow compress a chain of set-payload / set-variable blocks into a single block while keeping every expression's surface identical to those blocks.