kuzymail 1.4.1__tar.gz

kuzymail-1.4.1/AGENT_USAGE.md

@@ -0,0 +1,700 @@
+# Agent Usage
+
+This document is for agent participants using `kuzymail` as a client tool.
+Profiles and accounts are configured locally on the machine where `kuzymail`
+runs. A shared registry may provide optional metadata, but it is not required
+for local setup.
+
+It assumes a working mail service already exists.
+
+Examples below assume `kuzymail` is installed or that the local `.venv` is
+activated.
+
+## 1. Mental Model
+
+Use:
+
+- `kuzymail` as the canonical agent-facing facade for:
+  - account selection
+  - current-profile selection
+  - profile/runtime setup
+  - `sync`
+  - `list`
+  - `show`
+  - `attachments`
+  - `send`
+  - `reply`
+  - `archive`
+  - `delete`
+- raw `notmuch` for deep search/debugging when needed
+
+Output contract:
+
+- `secret` stays plaintext because `mbsync` and `msmtp` consume it directly
+- the agent-facing operational commands are JSON-first by default
+
+You do not need to manage IMAP sessions or SMTP sessions manually.
+
+Normal workflow:
+
+1. select your account once
+2. select your profile once
+3. sync your mailbox
+4. inspect/search local mail with `kuzymail list/show`
+5. send new mail with `kuzymail send` or answer with `kuzymail reply`
+6. archive or delete with explicit dry-run first
+
+## 2. Profiles
+
+Create your local profile after Reception grants your service identity and you
+have claimed your password:
+
+```bash
+kuzymail profile create --profile zorbax --address zorbax@mail.example.invalid --display-name "Zorbax"
+```
+
+Use `profile modify` for corrections to an existing profile:
+
+```bash
+kuzymail profile modify --profile zorbax --display-name "Zorbax"
+```
+
+Use this command to inspect the currently known mailbox inventory:
+
+```bash
+kuzymail mailboxes
+```
+
+Your profile determines:
+
+- your email address
+- where your local runtime is stored
+
+### Select your current profile
+
+```bash
+kuzymail profile use --profile zorbax
+```
+
+After that, most commands can omit `--profile`.
+
+## 2.1 Accounts
+
+An account is one concrete mailbox account for a profile.
+
+It carries:
+
+- mailbox address
+- login username
+- secret key name
+- IMAP host/port/security
+- SMTP host/port/security
+
+Account names are scoped by profile.
+`zorbax/primary` and `quindle/primary` are different accounts even though the account id is the same.
+
+Typical service setup:
+
+```bash
+kuzymail account set \
+  --account primary \
+  --profile zorbax \
+  --address zorbax@mail.example.invalid \
+  --imap-host mail.example.invalid \
+  --imap-security ssl \
+  --smtp-host mail.example.invalid \
+  --smtp-security starttls \
+  --set-current
+```
+
+Example second account for the same profile:
+
+```bash
+kuzymail account set \
+  --account external \
+  --profile zorbax \
+  --address zorbax@example.net \
+  --login-user zorbax@example.net \
+  --secret-key ZORBAX_EXTERNAL_PASSWORD \
+  --imap-host imap.example.net \
+  --imap-security ssl \
+  --smtp-host smtp.example.net \
+  --smtp-security ssl
+```
+
+Inspect configured accounts:
+
+```bash
+kuzymail account list
+kuzymail account show
+```
+
+By default, account secrets are kept under:
+
+```text
+secrets/profiles/<profile>/accounts/<account>.env
+```
+
+Use `--secrets-file` only when you intentionally want an explicit shared or external env file.
+
+## 2.2 Profile Tokens
+
+If a profile token is enabled, sensitive commands require one of:
+
+- `--token-file <path>`
+- `KUZYMAIL_TOKEN`
+
+Example:
+
+```bash
+kuzymail profile issue-token --profile zorbax
+printf '%s' '...token...' > ~/.config/kuzymail/zorbax.token
+kuzymail sync --token-file ~/.config/kuzymail/zorbax.token
+```
+
+This is a local capability guard.
+It is not strong host-level isolation.
+
+## 2.3 Strict Current Profile
+
+In an agent-local environment, enable strict mode after selecting your profile:
+
+```bash
+kuzymail profile use --profile zorbax
+kuzymail profile strict --on
+```
+
+After this, `kuzymail` refuses mailbox operations for another profile in the same environment.
+This reduces accidental or casual cross-profile use; it does not replace host-level isolation.
+
+### Initialize a newly granted profile
+
+After Reception grants mail access and you claim the one-time password, initialize the local runtime and secret like this:
+
+```bash
+kuzymail account set --account primary --profile blorvax --address blorvax@mail.example.invalid --imap-host mail.example.invalid --imap-security ssl --smtp-host mail.example.invalid --smtp-security starttls --set-current
+kuzymail init-profile --profile blorvax --password-prompt --set-current
+```
+
+## 3. Core Commands
+
+### Show runtime paths
+
+```bash
+kuzymail paths
+```
+
+Returns JSON.
+
+### Sync mailbox
+
+```bash
+kuzymail sync
+```
+
+Returns JSON, including captured `mbsync` / `notmuch` command output.
+
+This pulls:
+
+- `INBOX`
+- `Sent`
+- `Archive`
+
+Then refreshes the local notmuch database.
+It also runs `notmuch reindex '*'` every time. That is deliberate: on the current build, structured header queries become reliable only after reindex, so the wrapper pays the extra cost to keep search semantics correct.
+
+### Lightweight check
+
+```bash
+kuzymail check
+```
+
+Returns a single JSON object from an IMAP `STATUS` probe. It is read-only: no
+message bodies or headers are fetched, no MIME is parsed, no local Maildir is
+updated, and no IMAP flags are changed. Use `should_sync` and `sync_reason` to
+decide whether to run a full `kuzymail sync`.
+
+The check reads the local profile/account cursor from `imap-status.json` when it
+exists. A successful `sync` refreshes that cursor with the latest `UIDNEXT` and
+`UIDVALIDITY`; `check` never writes it. If no cursor exists yet, unseen mail can
+still trigger `should_sync=true`, but UID advancement cannot be inferred.
+
+### Managed-mode inject prompt templates
+
+`kuzymaild` wakes an agent with the `mail.digest` prompt template when managed
+mail attention decides that new mail should be injected.
+
+The upstream default is generic and policy-free:
+
+```text
+Open one directly with `{show_command}`, or sync the mailbox with `{sync_command}`.
+```
+
+Inspect and validate the effective template:
+
+```bash
+kuzymail prompt template list
+kuzymail prompt template show mail.digest
+kuzymail prompt template render mail.digest
+kuzymail prompt template validate
+```
+
+Set an override from a text file:
+
+```bash
+kuzymail prompt template set mail.digest --file template.txt
+```
+
+Add local policy text without replacing the whole template:
+
+```bash
+kuzymail prompt policy set --file policy.txt
+```
+
+Precedence is package default, `/etc/kuzymail/prompt-templates.json`, user
+override, profile override, then account override. Use `--profile` and
+`--account` on the prompt commands to inspect or set profile/account scoped
+overrides. Use `--system` only for host-wide policy.
+
+Managed-mode inject adapters are also registry-backed. The package ships default
+kuzywrap adapters under `kuzymail/data/inject-adapters/default.json`; host-wide
+overrides can be placed in `/etc/kuzymail/inject-adapters.json`, and user
+overrides in `$XDG_CONFIG_HOME/kuzymail/inject-adapters.json`. The attention
+field `inject_wrapper` names one configured adapter. Adapter definitions use
+argv lists, not shell strings. The packaged adapters are `kuzywrap-claude`,
+`kuzywrap-codex`, `kuzywrap-codewhale`, and `kuzywrap-antigravity`;
+Antigravity-hosted agents should use `kuzywrap-antigravity`, and
+CodeWhale-hosted agents should use `kuzywrap-codewhale`.
+
+### List inbox threads
+
+```bash
+kuzymail list
+```
+
+### Search / list with JSON
+
+```bash
+kuzymail list --query "tag:inbox subject:BLOCKER"
+```
+
+### Show message or thread
+
+```bash
+kuzymail show --message-id '<message-id>'
+kuzymail show --thread 0000000000000001 --entire-thread
+```
+
+### Attachments
+
+```bash
+kuzymail attachments list --message-id '<message-id>'
+kuzymail attachments extract --message-id '<message-id>' --part 3 --output /tmp/file.bin
+```
+
+### Raw notmuch remains available
+
+```bash
+notmuch --config runtime/profiles/zorbax/accounts/primary/notmuch-config search --sort=newest-first tag:inbox
+notmuch --config runtime/profiles/zorbax/accounts/primary/notmuch-config search --sort=newest-first subject:extid-1
+notmuch --config runtime/profiles/zorbax/accounts/primary/notmuch-config show --entire-thread=false id:<message-id>
+```
+
+### Threaded reply
+
+```bash
+kuzymail reply \
+  --profile zorbax \
+  --message-id '<message-id>' \
+  --body "Reviewed. I agree with the proposed direction."
+```
+
+`reply` is the safer default for agents: it replies only to `Reply-To` when
+present, otherwise `From`, and removes the current account address. It does not
+copy the original `To` or `Cc` recipients.
+
+Use `reply --include-cc` when you intentionally want a sender-only reply that
+also keeps the original `Cc` recipients. It still does not copy the original
+`To` list.
+
+Use `reply-all` only when you intentionally want to include the sender plus the
+original thread recipients:
+
+```bash
+kuzymail reply-all \
+  --profile zorbax \
+  --message-id '<message-id>' \
+  --x project thecost-accounting \
+  --x task-id extid-2026-03 \
+  --body "Reviewed. Including the thread."
+```
+
+Use `reply-all --exclude-cc` when you want the sender plus original `To`
+recipients, but do not want to copy the original `Cc` recipients.
+
+Both reply commands report `to`, `cc`, and `external_recipients` in JSON.
+`external_recipients` is visibility by default; account policy can require
+`--allow-external` or block external delivery.
+
+To add recipients deliberately, use additive flags:
+
+```bash
+kuzymail reply \
+  --profile zorbax \
+  --message-id '<message-id>' \
+  --add-to reviewer@example.invalid \
+  --add-cc zorbax@example.invalid \
+  --add-bcc audit@example.net \
+  --x project thecost-accounting \
+  --x task-id extid-2026-03 \
+  --body "Reviewed. Explicit recipients included."
+```
+
+`--add-to`, `--add-cc`, and `--add-bcc` are explicit additions to the computed
+reply recipients. kuzymail removes the current account only from implicit
+computed recipients; configured sender aliases are also treated as self
+addresses for implicit reply/reply-all filtering. If an agent explicitly adds
+its own address, it is kept.
+Bcc recipients are included in the SMTP envelope and local JSON output, but are
+not written into the outgoing message headers or the sent-copy serialization.
+`send` also accepts repeatable `--bcc` for envelope-only Bcc recipients.
+
+For multiline replies, prefer `--body-stdin` or `--body-file -`. Inline
+`--body` text interprets shell-safe escaped newlines by default: `\n`, `\r`,
+`\t`, and `\\`. Pass `--no-body-escape` only when you need literal backslashes.
+`send`, `reply`, and `reply-all` reject empty bodies by default; pass
+`--empty-body` only when an empty message body is intentional. `send` also
+rejects an empty `--subject` unless `--empty-subject` is passed.
+
+### HTML mail
+
+Plain text remains the default. To send HTML, provide both an explicit
+plain-text body and an HTML body; kuzymail emits `multipart/alternative` with
+the plain part first.
+
+```bash
+kuzymail send \
+  --profile zorbax \
+  --to quindle@mail.example.invalid \
+  --subject "Readable report" \
+  --x project kuzymail \
+  --x task-id html-report-1 \
+  --body-file plain.txt \
+  --html-body-file report.html
+```
+
+Markdown mail is explicit and symmetric with HTML input. Use `--markdown-body`,
+`--markdown-body-file`, or `--markdown-stdin`; kuzymail renders the Markdown to
+the HTML part and uses the original Markdown as the plain-text part unless an
+explicit `--body`, `--body-file`, or `--body-stdin` fallback is provided.
+Markdown options cannot be combined with `--html-body`, `--html-body-file`, or
+`--html-stdin`. Markdown images with `http://` or `https://` sources remain
+remote HTML images. Non-remote Markdown image targets are local files, resolved
+relative to the Markdown file directory for `--markdown-body-file`; they must
+exist as regular files and are attached inline with `cid:` references.
+
+```bash
+kuzymail send \
+  --profile zorbax \
+  --to quindle@mail.example.invalid \
+  --subject "Readable report" \
+  --x project kuzymail \
+  --x task-id markdown-report-1 \
+  --markdown-body-file report.md
+```
+
+### Sending attachments
+
+`send` and `reply` accept repeatable `--attach` / `--attachment` flags:
+
+```bash
+kuzymail send \
+  --profile zorbax \
+  --to quindle@mail.example.invalid \
+  --subject "Review request" \
+  --x project kuzymail \
+  --x task-id contract-review-1 \
+  --body "Attached for review." \
+  --attach ./contract.tex
+```
+
+### Archive
+
+Dry-run first:
+
+```bash
+kuzymail archive --profile zorbax --thread 0000000000000001
+```
+
+Apply:
+
+```bash
+kuzymail archive --profile zorbax --thread 0000000000000001 --yes
+```
+
+This also removes the affected messages from the local `notmuch` inbox/unread view so the operator-visible state stays coherent after the IMAP move.
+
+### Delete
+
+Dry-run first:
+
+```bash
+kuzymail delete --profile zorbax --message-id '<message-id>'
+```
+
+Apply:
+
+```bash
+kuzymail delete --profile zorbax --message-id '<message-id>' --yes
+```
+
+This also tags the affected local messages as `deleted` and removes them from the `notmuch` inbox/unread view.
+
+## 4. Sending Mail
+
+Example:
+
+```bash
+kuzymail send \
+  --profile zorbax \
+  --to quindle@mail.example.invalid \
+  --subject "Proposal: namespace cleanup" \
+  --body "Intent: tighten noisy IDs. Action requested: review proposed cleanup."
+```
+
+Use `--from` only for the account address or an explicitly configured sender
+alias. This keeps the same SMTP login, kuzymail secret, runtime account, Sent
+copy, and notmuch index while changing the RFC822 `From:` header:
+
+```bash
+kuzymail account modify \
+  --profile ada \
+  --account proton-bridge \
+  --sender-alias "Ada Example <ada@example.org>"
+
+kuzymail send \
+  --profile ada \
+  --account proton-bridge \
+  --from "Ada Example <ada@example.org>" \
+  --to customer@example.org \
+  --subject "Order update" \
+  --body "Your order has been updated."
+```
+
+Unauthorized `--from` addresses fail before SMTP with `send_from_not_allowed`.
+Header injection and multi-address values are rejected. The SMTP provider must
+also know the alias; otherwise it may reject the message even after kuzymail
+accepts the local configuration. Use `--dry-run` to inspect `from`,
+`from_address`, `account_address`, and `login_user` before sending. `reply` and
+`reply-all` accept the same `--from` option.
+
+Outbound attributes are optional by default. Add them when they help audit,
+routing, or operational context:
+
+```bash
+kuzymail send \
+  --profile zorbax \
+  --to quindle@mail.example.invalid \
+  --subject "Proposal: namespace cleanup" \
+  --x project thecost-accounting \
+  --x task-id extid-2026-03 \
+  --body "Intent: tighten noisy IDs. Action requested: review proposed cleanup."
+```
+
+`--x NAME VALUE` is a short alias for `--attribute NAME VALUE`. Attribute names
+map directly to custom mail headers: `--x project email2` emits
+`X-Project: email2`; `--x x-task-id abc` emits `X-Task-ID: abc`. Attribute names
+are case-insensitive for validation and duplicate detection.
+
+For multiline mail, prefer stdin:
+
+```bash
+cat <<'EOF' | kuzymail send \
+  --profile zorbax \
+  --to quindle@mail.example.invalid \
+  --subject "Proposal: namespace cleanup" \
+  --x project thecost-accounting \
+  --x task-id extid-2026-03 \
+  --body-stdin
+Intent: tighten noisy IDs.
+Action requested: review proposed cleanup.
+Why now: the current state is too noisy to trust.
+EOF
+```
+
+Multiple recipients:
+
+```bash
+kuzymail send \
+  --profile zorbax \
+  --to quindle@mail.example.invalid \
+  --to vornix@mail.example.invalid \
+  --subject "Handoff: matcher analysis" \
+  --x project thecost-core \
+  --x task-id matcher-7 \
+  --body "Passing the current state and next recommended step."
+```
+
+With CC:
+
+```bash
+kuzymail send \
+  --profile zorbax \
+  --to quindle@mail.example.invalid \
+  --cc umbrik@mail.example.invalid \
+  --subject "Escalation: external ID policy" \
+  --x project thecost-accounting \
+  --x task-id extid-escalation-2 \
+  --escalation HUMAN_REQUIRED \
+  --body "Need a human decision on long-term policy."
+```
+
+## 5. Structured Header Contract
+
+Attribute semantics:
+
+- `--x project email2` -> `X-Project: email2`
+- `--x task-id extid-1` -> `X-Task-ID: extid-1`
+- `--x x-project email2` -> `X-Project: email2`
+- `--x my_important_field yes` -> `X-My-Important-Field: yes`
+
+Optional:
+
+- `--escalation` -> `X-Escalation`
+- `--header NAME VALUE` -> sets a standard outbound header from a fixed allow-list
+  (`Auto-Submitted`, `List-Unsubscribe`, `List-Unsubscribe-Post`). Repeat for
+  multiple headers. Kept separate from `--attribute`/`--x` so arbitrary custom
+  headers can't be smuggled in through this path. Names are case-insensitive
+  and emitted in canonical casing. Duplicate names (including case variants)
+  and values containing CR or LF are rejected.
+
+If an operator wants `X-Agent-Type`, pass `--x agent-type VALUE` explicitly.
+
+To make attributes mandatory or restrict their names for a specific account:
+
+```bash
+kuzymail account modify \
+  --profile zorbax \
+  --account primary \
+  --attributes-allowed project \
+  --attributes-allowed task-id \
+  --attributes-allowed context \
+  --attributes-mandatory project
+```
+
+To return to free-form optional attributes:
+
+```bash
+kuzymail account modify --profile zorbax --account primary --attributes-allow-any --attributes-clear-mandatory
+```
+
+Attributes are included in JSON output. They are not for secrets.
+Standard outbound headers are reported separately as `standard_headers` in
+`send` and dry-run JSON, using canonical names and their final values.
+
+Use `--dry-run` on `send`, `reply`, and `reply-all` before risky outbound mail.
+It builds the message plan and validates recipients, attributes, attachments,
+and policy without SMTP or sent-copy side effects.
+
+External recipients are visible in JSON by default. Accounts can tighten this:
+
+```bash
+kuzymail account modify \
+  --profile zorbax \
+  --account primary \
+  --external-recipients-policy require-confirm
+```
+
+With `require-confirm`, pass `--allow-external` for an intentional external
+send. With `block`, external recipients are rejected even if
+`--allow-external` is present.
+
+Recommended escalation values:
+
+- `NONE`
+- `HUMAN_REQUIRED`
+
+## 6. Query Prefixes in Notmuch
+
+Configured custom query prefixes:
+
+- `Escalation:`
+
+Examples:
+
+```bash
+notmuch --config runtime/profiles/zorbax/accounts/primary/notmuch-config search --sort=newest-first Escalation:HUMAN_REQUIRED
+```
+
+## 7. What Send Actually Does
+
+When you call `send` or `reply`, the facade:
+
+1. builds an RFC822 message
+2. sends it through `msmtp` to local authenticated SMTP submission
+3. archives the same message into local `Sent`
+4. syncs `Sent`
+5. refreshes the notmuch database
+
+So your `Sent` view should remain coherent without manual steps.
+It also pays the `notmuch reindex '*'` cost so local index state remains truthful
+after generated sent-copy changes.
+
+If `--from` uses a configured sender alias, the login and envelope config still
+come from the account. kuzymail does not create a second profile/runtime just to
+send as an alias.
+
+Known addresses are formatted as `Display Name <email>` using local profiles first, then the optional shared registry.
+
+`archive` and `delete` are intentionally dry-run by default and only mutate the real mailbox with `--yes`.
+
+## 8. Expectations and Boundaries
+
+This is a message system and lightweight agent facade, not an execution channel.
+
+Do not treat mail as:
+
+- shell command transport
+- arbitrary code transport
+- secret exfiltration path
+
+Use it for:
+
+- handoffs
+- dissent
+- blockers
+- context updates
+- escalation
+
+## 9. Debugging
+
+If sync fails:
+
+```bash
+mbsync -c runtime/profiles/zorbax/accounts/primary/mbsyncrc zorbax-inbox zorbax-sent
+```
+
+If the wrapper output feels surprising:
+
+```bash
+kuzymail list --profile zorbax --query "tag:inbox" --limit 5
+kuzymail show --profile zorbax --message-id '<message-id>'
+```
+
+If search feels wrong:
+
+```bash
+notmuch --config runtime/profiles/zorbax/accounts/primary/notmuch-config search '*'
+```
+
+If send fails:
+
+```bash
+msmtp -C runtime/profiles/zorbax/accounts/primary/msmtprc --serverinfo
+```
+
+Use raw mail tools only when needed:
+
+- `mbsync`
+- `notmuch`
+- `msmtp`