Inbox Shared Test Conventions

Purpose

This document captures shared assumptions used by multiple inbox test-plan documents so command and workflow files can stay focused on behavior rather than repeating setup boilerplate.

Recommended Fixture Shape

Use an isolated temp workspace per case:

database path: TMPDIR/coord.db
optional body file: TMPDIR/body.md
optional artifact file: TMPDIR/artifact.txt

Recommended bootstrap command:

inbox --db TMPDIR/coord.db --json init

Global Flags

Root-level flags apply to every subcommand:

--db: SQLite database path, default .agents/coord.db
--json: emit machine-readable JSON
--agent: acting agent identity shortcut used by commands that accept agent context

When a command-specific --agent or --from flag is omitted, the root --agent value may be used instead. Cases that verify fallback behavior should state that explicitly.

Success JSON Contract

Successful JSON output uses this shape:

{
  "ok": true,
  "command": "send",
  "data": {}
}

Shared assertion points:

ok is true
command matches the invoked subcommand
data contains the command-specific payload

Error JSON Contract

Failure JSON output uses this shape:

{
  "ok": false,
  "error": {
    "code": "invalid_input",
    "message": "..."
  }
}

Shared assertion points:

ok is false
error.code matches the stable contract
error.message is present and human-readable

Exit Code Contract

The current CLI contract uses these exit codes:

Exit Code	Meaning	Typical Error Code
`0`	success	none
`10`	no matching work / timeout without match	`no_matching_work`
`20`	lease conflict	`lease_conflict`
`30`	invalid input, invalid state, usage-style error	`invalid_input` or `invalid_state`
`40`	referenced thread or message missing	`not_found`
`50`	unexpected internal failure	`internal_error`

When a case expects no result, assert both the exit code and the JSON error code.

Body Input Rules

Commands that support --body and --body-file follow these rules:

--body and --body-file are mutually exclusive
--body-file content is read verbatim into the message body
unreadable --body-file should be treated as invalid_input

Relevant commands:

send
update
reply
done
fail

Artifact Rules

Commands with artifact support use these shared rules:

--artifact may be repeated
--artifact-kind may be specified once for all artifacts, or once per artifact
--artifact-metadata-json may be specified once for all artifacts, or once per artifact
--artifact-kind and --artifact-metadata-json are invalid without at least one --artifact
an empty artifact path is invalid input

When artifact behavior is under test, assert at least:

artifact count
artifact path
artifact kind
metadata presence when supplied

Read And Unread Assertions

Unread-related cases should verify behavior from the agent's point of view, not only raw message existence.

Recommended checks:

fetch --unread returns a thread before read acknowledgement
show --mark-read clears unread state for that agent
a new message to the same thread makes the thread unread again
wait-reply may clear blocked unread state for the waiting agent when the reply is consumed

Workflow Authoring Rule

If a case spans multiple commands, place the end-to-end narrative in workflows/README.md first, then add narrower command-level cases only when they introduce behavior that is easier to reason about in isolation.