Avatar Manual

Avatar Manual

Avatar creates a persistent, independent peer as a detached process. Use daemon for disposable work and shell for a one-off command. After launch, communicate by mail/email; there is no ongoing Avatar handle.

Routine spawn: direct path

The schema is enough for a routine call; do not load this manual as a ritual. Use all five strict spawn-input keys and put the mission in root reasoning:

avatar(action="spawn",
       input={"name": "researcher", "type": null, "comment": null,
              "dry_run": false, "confirm": false},
       reasoning="Inspect the heartbeat regression; report evidence by mail and change no code.")

State objective, resources, reporting route, done condition, and constraints. name is the canonical sibling basename, not a separate display name. Spawn creates an independent life: obtain authorization, and do not batch it with unrelated calls. dry_run=true previews without writes or a process, not launch admissibility; confirm=true acknowledges only mission review.

avatar(action="manual", input={}, reasoning="load Avatar guidance") returns this package-local body and manual_path; resolve its links from that path, not from an Agent's installed skill copy. Avatar has no rules action or fan-out: use psyche(action="manual", input={}, reasoning="locate rules guidance") for the kernel/Psyche .rules protocol.

Read-only settings

avatar(action="settings", input={}, reasoning="inspect Avatar policy") returns 16 fresh five-field rows: key, current, default, configurable, comment. Every row is fixed, current=default, configurable:false. The source is tools/avatar/settings.py; there is no Avatar settings file, LINGTAI_AVATAR_* override, or set/reset action. Per-call inputs do not change SHOW. Changing fixed policy requires an authorized source change, tests and owner relaunch, then SHOW again. Values are public policy, not identity, credentials, environment contents, or live session state. An unavailable row fails the whole action as bounded SETTINGS_UNAVAILABLE, without partial rows.

Spawn call defaults

type is shallow, comment is empty, dry_run and confirm are false when nullable inputs are omitted/null. These four rows describe call defaults only. Shallow copies rewritten init plus narrow Psyche inputs; deep adds durable identity/knowledge state. See the payload reference before assuming isolation.

Spawn validation policy

Five rows: allowed types shallow/deep; name minimum 1 and maximum 64 characters; mission minimum 20 trimmed characters; placeholder tokens bar, check, debug, foo, temp, test, tmp. Names use Unicode-aware ^[\w-]+$ plus explicit length/dot checks: supply letters/digits/underscore/ hyphen only. Exact mission token/space behavior is in the spawn reference.

Spawn lifecycle policy

Seven rows: boot wait 5.0 seconds, poll 0.1 seconds, stderr tail 2,000 bytes; preset policy parent-default, environment inherit-launcher-process, lifecycle detached-independent, and admin inheritance none. Heartbeat presence is not a freshness or human-delivery proof; raw stderr may be sensitive. The lifecycle reference owns result/error and authority details. Preset rewriting is conditional on a configured default; see spawn reference.

Cleanup / Footprint

Targets are sibling <network-root>/<name>/ and the parent's append-only delegates/ledger.jsonl, not cache. For read-only counts/bytes, the packaged shared footprint recipe accepts explicit target paths and writes/deletes nothing. Consider a report after an avatar-heavy session or before retirement; logging it to logs/cleanup.jsonl is optional and requires consent.

Never delete directories, ledger, active processes, or recovery/audit state blindly. Capture a handoff, check current liveness, report footprint, then seek exact authorization for the specific lifecycle or destructive action. If the user is unavailable, stop after the report.