Skip to content

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 ​

  • RunMetadata gains 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 (core planRunStartTask). Not part of startDigest.
  • A new RunStartRejectedError cause, task_join_mismatch: a join the live expected run cannot serve. Nothing is written; it is classed fatal and never retried.
  • SessionState.clientContextId / CreateSessionOptions.clientContextId: written once by createSession, never changed by a later write.
  • Core runMetadataSchema(), taskEndReasonSchema(), startRunTaskSchema().

Migrations (roll-forward only, nullable, no backfill) ​

BackendMigrationAdds
PostgresV37runs 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
D1V39the same (a fresh database gets them from the collapsed schema)
DO-SQLite34the runs, state and checkpoint columns and indexes (the DO usage table has no chain)
Redisnonenew 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 applyRunStartRules as messageCount; it is now required.
  • On a create decision, write decision.task: task.run on the new run, and each task.close entry onto its run, in the same atomic step.
  • Keep clientContextId write-once: store it in createSession and never from a later write.
  • Your contract suite now runs core taskRunStartCases (TASK-1 … TASK-10, CCI-1) through runStartOperationTests.

The task bump (R0(a2)) ​

Breaking (shipped in core 15.7.0 as a minor). A fenced saveState call ({ fenceRunId }) must now also pass bumpTask (TypeScript reports TS2345 at every call site that does not), and a custom SessionStateStore must implement the new bumpTask op. Pass bumpTask: false on 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 saveState takes a required bumpTask: boolean. SaveStateOptions is now a union: with fenceRunId you must say whether the save bumps. The framework bumps only for a stored client-tool answer and a lapsed client-tool call. Pass bumpTask: false on your own fenced saves unless they store a client's answer; TypeScript lists every call site that needs it.
  • A custom SessionStateStore bumps inside each producing write's own atomic step (core planTaskBump, decided on the current run as it was BEFORE the write): a status change of the current run (updateRunStatus), updateClientToolCallOwnership (when ownershipChangeBumps(result)), updateRemotePendingCalls (when it writes), replacePendingAnswer (when it replaces), requestStop (when stopChangeBumps(prior, next) and the run is current) and a fenced saveState with bumpTask: true. A write that changes nothing bumps nothing.
  • Implement the new op bumpTask(sessionId, { seen }), mode { seen } of planTaskBump: max(stored, seen + 1) when the current task is the one the caller saw, else stored + 1, answering BumpTaskResult. 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) through stateStoreContractTests.

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; total counts 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), keyset after (a previous page's next), default limit 50, totalSize counting the tasks. A run with no task is never listed; a task whose latest run is unlisted is 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 smallest keepCount of the session's truncate checkpoints after afterSequence, or null.
  • commitState(…, { taskOutcome }) stores a TaskOutcome ({ output?, artifacts: TaskArtifactDescriptor[] }, descriptors only, never bytes) on the K5 checkpoint, read back as Checkpoint.taskOutcome. A store with a finite limits.maxStateBytes (D1, the DO) measures it like the state and refuses an oversized one with state_size_exceeded (operation state), nothing written.
  • UpdateRunMetadata.outcomeCheckpointId points the run at that K5. Core finishCommittedRun passes it when the K5 it finishes carries an outcome.
  • The CF DO's listRuns default page is 50 runs (it was 10), as on every other store. Pass limit if you relied on 10. DOStateStoreClient.listRuns (over GET /runs) refuses taskId with framework_not_supported: that route serves no task filter.
  • Redis adds two key families, written by the commit script in the same EVAL as 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) and session: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 SessionStateStore implements listTasks and getRewoundKeepCount, honours ListRunsOptions.taskId, stores taskOutcome and outcomeCheckpointId, and passes core taskReadCases (TRD-1 … TRD-5, K5O-1, K5O-2), run by stateStoreContractTests.

No SQL migration: the columns and indexes came with R0(a1) (Postgres V37, D1 V39, DO-SQLite 34).

Released under the MIT License.