A2A task fields on run records (R0(a1))
This release prepares the stores for the A2A task model (design 2026-11-13-remote-agents-a2a-design.md §3.2, §4.1). It is a minor release of @helix-agents/core, @helix-agents/store-postgres, @helix-agents/store-cloudflare, @helix-agents/store-redis and @helix-agents/runtime-cloudflare, and a patch of @helix-agents/store-memory. No runtime plans a task yet, so no run behaves differently: a run-start commit with no StartRun.task writes no task field. A custom SessionStateStore has new obligations (below).
What changed
RunMetadatagains optional task fields:taskId,referenceTaskIds,statusChangedAt,taskVersion,endMessageCount,endReason(TaskEndReason),endedByTaskId,outcomeCheckpointId,unlisted.StartRun.task?: { open: { referenceTaskIds?, closeExpected? } } | { join: { taskId } }, validated and recorded by every store inside the run-start commit (coreplanRunStartTask). Not part ofstartDigest.- A new
RunStartRejectedErrorcause,task_join_mismatch: a join the live expected run cannot serve. Nothing is written; it is classedfataland never retried. SessionState.clientContextId/CreateSessionOptions.clientContextId: written once bycreateSession, never changed by a later write.- Core
runMetadataSchema(),taskEndReasonSchema(),startRunTaskSchema().
Migrations (roll-forward only, nullable, no backfill)
| Backend | Migration | Adds |
|---|---|---|
| Postgres | V37 | runs task columns + (session_id, task_id) and (session_id, status_changed_at) indexes; states client_context_id; checkpoints task_outcome + (session_id, kind, stream_sequence) index; usage run_id + index |
| D1 | V39 | the same (a fresh database gets them from the collapsed schema) |
| DO-SQLite | 34 | the runs, state and checkpoint columns and indexes (the DO usage table has no chain) |
| Redis | none | new run hash fields and a per-session session:tasks:{sessionId} ZSET |
Run your migrations as usual (PostgresMigrations.run(), runMigration(db); the DO store migrates itself on first use). There is no rollback step.
A custom SessionStateStore
- Pass the session's live message count (read inside your atomic run-start step, before the commit's rows and any rewind) to core
applyRunStartRulesasmessageCount; it is now required. - On a
createdecision, writedecision.task:task.runon the new run, and eachtask.closeentry onto its run, in the same atomic step. - Keep
clientContextIdwrite-once: store it increateSessionand never from a later write. - Your contract suite now runs core
taskRunStartCases(TASK-1 … TASK-10, CCI-1) throughrunStartOperationTests.
The task bump (R0(a2))
Breaking (shipped in core 15.7.0 as a minor). A fenced
saveStatecall ({ fenceRunId }) must now also passbumpTask(TypeScript reports TS2345 at every call site that does not), and a customSessionStateStoremust implement the newbumpTaskop. PassbumpTask: falseon your own fenced saves unless they store a client-tool answer. Core 16.0.0 corrects the version signal.
Core 15.7.0 makes every write that changes a task's derived state advance the task (design §4.1 "The bump"): taskVersion + 1 and statusChangedAt = the store clock (never earlier than stored), on the session's current run, only while that run carries a live, unended task. No runtime plans a task yet, so no task is bumped at run time; the breaking part is the type and the store interface above.
- Fenced
saveStatetakes a requiredbumpTask: boolean.SaveStateOptionsis now a union: withfenceRunIdyou must say whether the save bumps. The framework bumps only for a stored client-tool answer and a lapsed client-tool call. PassbumpTask: falseon your own fenced saves unless they store a client's answer; TypeScript lists every call site that needs it. - A custom
SessionStateStorebumps inside each producing write's own atomic step (coreplanTaskBump, decided on the current run as it was BEFORE the write): a status change of the current run (updateRunStatus),updateClientToolCallOwnership(whenownershipChangeBumps(result)),updateRemotePendingCalls(when it writes),replacePendingAnswer(when it replaces),requestStop(whenstopChangeBumps(prior, next)and the run is current) and a fencedsaveStatewithbumpTask: true. A write that changes nothing bumps nothing. - Implement the new op
bumpTask(sessionId, { seen }), mode{ seen }ofplanTaskBump:max(stored, seen + 1)when the current task is the one the caller saw, elsestored + 1, answeringBumpTaskResult. Runtime-js and CF Workflows call it on a child's ROOT after the child's run-status write. - Your contract suite now runs core
taskBumpCases(BUMP-1 … BUMP-8) throughstateStoreContractTests.
No migration: the columns (and Redis's task ZSET) came with R0(a1).
The task reads and the K5 outcome (R0(a3), R0(a4))
The store halves of R0(a3) and R0(a4).
A later minor release adds the reads behind A2A's task listing and the storage of a task's outcome (design §3.2, §4.1, §4.4). No runtime writes an outcome or serves a task read yet, so no run behaves differently, except the CF DO's default run page (below). Breaking for a custom SessionStateStore (core 16.0.0): it must implement the two new reads.
listRuns(sessionId, { taskId })reads only that task's runs, in turn order;totalcounts them, and an unknown task reads an empty page.listTasks(sessionId, { limit?, after? })(new, required): each task's latest run (its highest turn),(statusChangedAt desc, taskId desc), keysetafter(a previous page'snext), default limit 50,totalSizecounting the tasks. A run with no task is never listed; a task whose latest run isunlistedis left out. A session that does not exist reads{ tasks: [], totalSize: 0 }and is not created. Not one snapshot: while tasks change, a task may appear on two pages or on none.getRewoundKeepCount(sessionId, afterSequence)(new, required): the smallestkeepCountof the session'struncatecheckpoints afterafterSequence, ornull.commitState(…, { taskOutcome })stores aTaskOutcome({ output?, artifacts: TaskArtifactDescriptor[] }, descriptors only, never bytes) on the K5 checkpoint, read back asCheckpoint.taskOutcome. A store with a finitelimits.maxStateBytes(D1, the DO) measures it like the state and refuses an oversized one withstate_size_exceeded(operationstate), nothing written.UpdateRunMetadata.outcomeCheckpointIdpoints the run at that K5. CorefinishCommittedRunpasses it when the K5 it finishes carries an outcome.- The CF DO's
listRunsdefault page is 50 runs (it was 10), as on every other store. Passlimitif you relied on 10.DOStateStoreClient.listRuns(overGET /runs) refusestaskIdwithframework_not_supported: that route serves no task filter. - Redis adds two key families, written by the commit script in the same
EVALas the commit that produces them:session:task-runs:{sessionId}:{taskId}(a ZSET of the task's runs by turn, written by the run-start commit that opens or joins the task) andsession:truncates:{sessionId}(a ZSET of truncate checkpoint ids by stream sequence). No backfill: runs and truncates written before this release are not indexed (fresh start). - A custom
SessionStateStoreimplementslistTasksandgetRewoundKeepCount, honoursListRunsOptions.taskId, storestaskOutcomeandoutcomeCheckpointId, and passes coretaskReadCases(TRD-1 … TRD-5, K5O-1, K5O-2), run bystateStoreContractTests.
No SQL migration: the columns and indexes came with R0(a1) (Postgres V37, D1 V39, DO-SQLite 34).