Dudu-0223
ff563d07e0
Models coordinate subagents through send_message, interrupt_agent, list_agents,
and Team task owners, but every one of those addressed a member by a
36-character Session id. Each new child now has a name, unique among its
creator's children, recorded as a field of the subagent/catalog entry the
creator already appends (payload version 3).
The Session id stays the only execution identity for routing, authorization,
persistence, task ownership, and navigation. A name is a model-facing
reference: 1-32 lower-case letters, digits, or hyphens starting with a letter,
never `lead`, so a UUID never parses as one. Omission selects the first free
`agent-N`; an explicit duplicate or invalid name fails before startup. The
creator reserves the name synchronously at admission and releases it when the
catalog entry commits or startup fails, so no second write, rollback protocol,
or optional naming service exists.
The root is `lead`, and a descendant's full name is its path from the root
without a `lead/` prefix, such as `reviewer/checker`. Sibling-unique segments
make full names tree-unique without a root registry, and cold resume rebuilds
a member's path from the catalogs along its creation chain. A member below an
unnamed historical creator keeps its Session id as its name. resolveName()
reads only the catalogs along the path and grants no authority.
Tools, runtime-authored text, and the Web client consume names: delegation
takes an optional name and returns { kind, subagentId, name }; send_message and
interrupt_agent take `agent`; list_agents rows carry name, status, and
description; Team task results report the owner's name while storage keeps
ownerId; identity runtime context, message framing, and settlement notices use
full names. Recorded sessions, CLI and Web expectations, the Python runtime
snapshots, bilingual docs, an upgrade guide, and an Agent Note follow.
description
| description |
|---|
| Find the complete declared persistence types for every Session format from V0 through the checkout writer. |
Session persistence formats
English | 中文
Summary
Use this reference to inspect a stored Session generation’s headers, event envelopes, and payload types. Every format below the checkout writer has a bilingual document and a complete schema snapshot. The current format uses the generated persistence catalog. The version authority owns the writer constant and release status.
Table of Contents
Format references
The index is generated from validated snapshots and the current writer constant. Each historical reference identifies its source checkpoint; a Session format number does not identify every event payload revision within that format.
| Format | Source | Reference | Machine schema | Roots / types |
|---|---|---|---|---|
| 0 | dsh-v0.1.2-rc.1 |
V0 | JSON | 54 / 415 |
| 1 | PR #3349 | V1 | JSON | 54 / 415 |
| 2 | dsh-v0.1.3-alpha.2 |
V2 | JSON | 56 / 435 |
| 3 | PR #4320 | V3 | JSON | 60 / 467 |
| 4 | Current checkout | Current catalog | JSON | 66 / 634 |
Scope and evidence
Each vN.md / vN.zh.md pair has kind: persistence-format, an identical yaml persistence-format declaration binding every root key to its captured digest, a pairing sidecar, and a complete vN.schema.json. The template defines these records. Roots cover the logical Session header, physical JSONL header, event envelope, and all first-party events at the selected checkpoint; each root includes every reachable declared type. Packed physical body records have separate codec owners linked from each page.
V0 and V2 use the latest matching tags in the captured prerelease archive. V1 uses an intermediate source tree identified in its reference because the captured tags contain no V1 writer. V3 captures the verified inventory before the V4 writer change in PR #4320. Historical sources retain file paths without line numbers. Snapshots preserve historical optional fields and opaque values; they do not substitute current types into older formats. Historical identifiers remain intact only in schema JSON and the verified generated schema regions; authored prose follows current terminology rules.
These references describe selected schemas, not historical application replay or migration safety. Same-version event additions and optional payload changes can produce other valid inventories. The prerelease archive retains tag-by-tag differences; change records retain current compatibility acknowledgements. Neither history is replaced by these format snapshots.
Maintain coverage
verify-persistence-formats derives the required integer range from SESSION_FORMAT_VERSION. Every older integer needs its own complete record. The current catalog and schema must exist and match the writer version. The check rejects missing, extra, misnumbered, incomplete, or inconsistent records and stale generated regions without fetching Git history or querying a service.
Before advancing the writer, verify the current catalog and archive the outgoing format. For a V3-to-V4 change, run these commands while the writer and current schema still describe V3:
pnpm run verify-persistence-catalog
pnpm run verify-persistence-formats --archive 3
Replace 3 with the outgoing writer version for other transitions. --archive N creates vN.schema.json from the current inventory, retains exactly the types reachable from its roots, and removes source line numbers. It refuses an existing destination, a version other than the current writer, invalid or incomplete schemas, and combination with --write. Add the snapshot’s bilingual record and source evidence using the template. Retain all earlier records. The successor uses the current catalog; copying a new current catalog cannot satisfy the archived predecessor requirement. Follow the format-version cookbook for runtime changes.
The schema definitions and index inside comment markers are generated. After advancing the writer and completing the machine data and authored evidence, refresh their tables and pairing records, then verify:
pnpm run verify-persistence-formats --write
pnpm run verify-persistence-formats
pnpm run doc-sync
--write validates the machine data before updating generated Markdown and pairing records. It preserves authored explanations, machine declarations, and schemas. Default verification also rejects stale pairing records; the standard documentation checks validate translations and local links. Current catalog freshness remains owned by verify-persistence-catalog.
Dev Note
None.