docs(prds): draft SOUL, the per-identity chat personality
This commit is contained in:
1 parent
f4ed542b00
commit
fcc6a7974e
1 file changed
+142
@@ -0,0 +1,142 @@
|
||||
# SOUL: an agent's user-authored personality
|
||||
|
||||
**Status:** Draft
|
||||
**Authority:** `docs/architecture/identity.md`, “Three-layer identity model”;
|
||||
`docs/prds/orgs-and-access.md` for identity and org ownership.
|
||||
|
||||
## Decision
|
||||
|
||||
SOUL supplies an agent's name, register and warmth. It belongs to the agent's
|
||||
immutable `IdentityID`, not its session, model, installation or container
|
||||
profile. Rename preserves it; changing a profile does not change who acts.
|
||||
SOUL never changes attribution, credentials, grants or identity lifecycle.
|
||||
`config.AgentProfile` remains an execution environment, not another identity.
|
||||
|
||||
Use the existing three layers: invariants, user-authored SOUL, and curator-derived
|
||||
representation. Curators may propose SOUL changes but never apply them.
|
||||
|
||||
## Files and ownership
|
||||
|
||||
The config directory is `${XDG_CONFIG_HOME:-~/.config}/archie`, or the directory
|
||||
of an explicitly selected config file. The default/root agent uses `SOUL.md`
|
||||
directly there; additional agents use `agents/<identity-id>/SOUL.md`. The root is
|
||||
the identity selected by application composition, never the initiating user or
|
||||
a session's personality selection. No file creates or selects an identity.
|
||||
|
||||
The common case keeps a human-friendly filename; additional agents get separate
|
||||
asset directories, following `.agents/skills/<name>/SKILL.md` without confusing
|
||||
these directories with `[containers.profiles.<name>]`. Reject display-name or
|
||||
slug directories: rename and same-name agents across orgs would require another
|
||||
name-resolution rule. Immutable IDs avoid both problems without an org directory.
|
||||
|
||||
When a file-owned agent's file is absent, create the shipped default with
|
||||
exclusive creation. Never overwrite an existing file, including an empty one.
|
||||
A creation failure still permits the turn using the embedded shipped default.
|
||||
Ship that document independently of `agent.ShippedPersonas`, so deleting personas
|
||||
cannot delete the fallback.
|
||||
|
||||
Resolve once at the start of every new generation:
|
||||
|
||||
1. A stored SOUL entry for the acting identity is authoritative.
|
||||
2. Without an entry, read that identity's file again.
|
||||
3. An absent, empty, unreadable or invalid selected source uses the shipped default.
|
||||
|
||||
The first explicit dashboard/API save takes ownership permanently. Thereafter
|
||||
file edits are ignored: emit one ownership notice and show the owning stored
|
||||
version in the dashboard. Restoring the shipped default writes a stored value;
|
||||
it does not remove ownership. Refuse writes that remove an owned entry.
|
||||
|
||||
This ownership boundary is the design's one stateful rule. Files seed the
|
||||
editable value, not an automatic durable import. Reject seed-once import because
|
||||
it breaks next-message file editing; reject file-always-wins because it makes
|
||||
dashboard saves ineffective. Neither a restart nor an upgrade overwrites an
|
||||
owned value, following the precedence of `controlplane.AgentProfileKind` without
|
||||
copying its startup import timing.
|
||||
|
||||
## Prompt and failure contract
|
||||
|
||||
Keep `archie.md.tpl`'s XML-escaped
|
||||
`<soul purpose="identity_and_style" trust="data">` block before
|
||||
`<instruction_precedence>`. SOUL is style reference data; the invariant sections,
|
||||
tool inventory and runtime metadata remain authoritative and uneditable.
|
||||
Preserve `TestBuildSystemPromptSoulCannotOverrideInvariants`.
|
||||
|
||||
Accept UTF-8 plain Markdown with at most 8 KiB in its XML-escaped body. This bounds
|
||||
personality to a small prompt contribution; count the complete rendered prompt
|
||||
in the turn's context budget and never truncate invariant sections. Bound file
|
||||
reads before decoding; reject oversize input rather than truncating instructions.
|
||||
File and stored writes use the same validator; an invalid save leaves the stored
|
||||
version unchanged. The shipped default must pass that validator.
|
||||
|
||||
Read and creation errors never fail a turn. Log once per identity/source failure
|
||||
episode, retry on the next turn, and allow a new warning after recovery. If the
|
||||
store cannot establish whether an owned entry exists, use the shipped default,
|
||||
not a potentially shadowed file. Do not log SOUL text. Each turn keeps its resolved
|
||||
snapshot; edits affect the next generation without restart or SIGHUP.
|
||||
|
||||
## Cross-layer delivery
|
||||
|
||||
- `internal/domain/agent` owns SOUL content validation and the identity-keyed read
|
||||
contract; `internal/domain/identity` remains the actor/lifecycle authority.
|
||||
- The configuration infrastructure resolves the config directory and handles
|
||||
file discovery, exclusive default creation and bounded per-turn reads.
|
||||
Application composition resolves the acting `IdentityID` through the existing
|
||||
identity repository/bindings and supplies it to the gateway.
|
||||
- Register `SoulKind` (`agent-souls`) in the control plane with a live descriptor
|
||||
and an org-scoped document mapping identity IDs to `{text}`. Persist it through
|
||||
the State Store's existing resource/history contracts, not a new table,
|
||||
process or SOUL RPC. An empty map owns no identity; saves preserve other entries
|
||||
and use expected-version checks. Validate that each key is an agent identity
|
||||
in the resource's org; begin with the default org without inventing org setup.
|
||||
Every save records the authenticated editor's identity, source, request ID and
|
||||
timestamp; file installation records the system identity, not a fictitious user.
|
||||
- Replace `TurnRunnerConfig.Personas` / `PersonaPromptSource` with the per-identity
|
||||
source in `prepareTurn`; name the `SystemPromptConfig` input SOUL. Both normal
|
||||
and streaming turns use this assembly path. Do not add personality to the
|
||||
worker environment, `AgentProfile` or workflow-stage prompts.
|
||||
- On an agent identity's dashboard page, expose its effective SOUL, file/default
|
||||
or stored source, shadowed file path, owning version, and Markdown editing.
|
||||
Save to the control plane, never the host file; show validation/version
|
||||
conflicts and offer restoring shipped content or a history revision as a save.
|
||||
Read effective file/default content and ownership metadata through a gateway
|
||||
query using the turn resolver; the separate UI process never reads the
|
||||
gateway host's files. Apply identity-management access rules and the existing
|
||||
shared live-update hub.
|
||||
- Update `docs/development/agent.md` and `control-plane.md` with this reach and
|
||||
precedence, `frontend-ui.md` with the gateway query, and the config wiring
|
||||
guidance with a copyable file example.
|
||||
|
||||
## Persona removal gate
|
||||
|
||||
SOUL supersedes `PersonaRegistry` and the persona-reconciliation proposal;
|
||||
identity-per-action supersedes personas as an identity mechanism.
|
||||
`PersonaRegistry.GetActive` composes the baseline with one of five styles from
|
||||
`agent.ShippedPersonas`; SOUL replaces the baseline, not that style catalogue.
|
||||
Per-session switching disappears: remove `/personality`, Telegram personality
|
||||
callbacks, the dashboard persona page, and chat wire fields `personas`,
|
||||
`active_personas` and `personas_available` without reusing their field numbers.
|
||||
Do not merge session selections into SOUL or retain a separate style axis.
|
||||
Custom persona text must remain available to copy before deleting its stored
|
||||
resource; no migration guesses one agent's SOUL from several sessions.
|
||||
|
||||
Remove persona loading, selectors and commands only after every chat composition
|
||||
supplies the identity-aware SOUL source, the fallback renders without personas,
|
||||
and the dashboard can edit it. SOUL delivery does not wait for org creation or a
|
||||
new container-profile model.
|
||||
|
||||
## Acceptance
|
||||
|
||||
- Two agents use distinct files and stored entries; renaming one or sharing a
|
||||
container profile does not change or mix their SOULs.
|
||||
- Before ownership, a file edit changes the next normal or streaming prompt;
|
||||
creating defaults never clobbers an existing file.
|
||||
- After a save, conflicting file edits and restarts cannot override the stored
|
||||
value; the ignored file and owning version are visible. Updating one agent
|
||||
preserves the other; stale saves fail and history restores are audited saves.
|
||||
- Missing, empty, unreadable, malformed and oversize selected inputs render the
|
||||
shipped default. Repeated read failures log once, recover on a later turn,
|
||||
and never abort generation.
|
||||
- Hostile markup stays escaped before singular, unchanged invariant blocks;
|
||||
prompt budgeting includes SOUL and cannot drop the rules.
|
||||
- Dashboard edits reach the next generation without restart; persona removal
|
||||
leaves every channel with a nonempty identity slot and preserved custom text.
|
||||
Reference in new issue
Block a user