Audit, Usage, and Privacy #

The audit and usage systems answer different questions:

• Audit explains what happened in Discord and through the bot.
• Usage explains which Discord user caused metered agent work.

Audit Storage #

Audit is enabled by default and stores SQLite data at DATA_DIR/audit/discord.sqlite unless AUDIT_LOG_DB overrides it.

The recorder stores Discord gateway activity and bot-side events, including message creates, updates, deletes, reactions, channel and thread events, interactions, command replies, WebShare share lifecycle and delegated actions, agent lifecycle events, final responses, and delivery success or failure metadata.

Typing events are recorded only when AUDIT_LOG_RECORD_TYPING=true.

Message Deletion Attribution #

Discord gateway message_delete events confirm that a message disappeared, but they do not identify the deletion actor. When the bot previously recorded the original message, audit queries can show the original author and, when content retention is enabled and explicitly requested, a short content snippet. That original author is not proof of who deleted the message.

Moderator or bot deletions may appear in Discord Guild Audit Log as MESSAGE_DELETE or MESSAGE_BULK_DELETE, but that is a separate Discord audit-log data source with limited fields and a finite retention window. User self-deletes generally cannot be proven from Discord gateway events alone.

Content Recording #

AUDIT_LOG_RECORD_CONTENT=true records message content in audit projections and raw payloads. Set it to false when content retention is not acceptable for the deployment.

Use AUDIT_LOG_RETENTION_DAYS to prune old rows. The default 0 keeps all audit data.

WebShare Audit and Privacy #

WebShare audit events identify the share ID, opener Discord user, remote browser display name when available, target channel/thread, action type, allow/deny result, and revoke reason. They must not store full control/view links, fragment secrets, write tokens, relay host tokens, CDN signed URLs, or raw local filesystem paths.

Browser-originated Discord messages are intentionally visible as delegated output, for example Alice via WebShare. The relay remains content-blind, but operators should still treat relay access logs as sensitive metadata because room IDs, IP addresses, user agents, frame sizes, and timing can reveal usage patterns.

Audit Command Behavior #

/audit is slash-only:

• /audit <limit> privately returns recent audit rows for the current channel or thread.
• /audit <prompt> starts a private audit investigation agent and asks it to use bot_query_audit.
• Text !audit intentionally does not return audit rows because Discord text commands cannot guarantee private responses.

Audit management requires the same channel/admin authorization used by sensitive channel controls.

Usage Attribution #

Usage records are append-only ledgers written after completed agent work. They are attributed to the invoking Discord user when the job came from a user command, prompt, mention, WebShare delegated action, audit prompt, compact, clear, or scheduled command context.

Runtime usage data is stored in the dedicated SQLite database DATA_DIR/usage/usage.sqlite. On the first startup after upgrading, legacy monthly DATA_DIR/usage/*.jsonl ledgers are imported transactionally and moved to DATA_DIR/usage/archive/. The archived files are retained as migration backups and are no longer queried or written at runtime. A malformed legacy file aborts startup without partially importing that file.

For cron jobs, the record uses the job owner or configured user context. Kiro usage sums credit or credits metering metadata when present. OMP usage sums USD cost metadata from usage_update.

If an engine does not return metering metadata for a turn, /usage still counts the turn but reports the missing metadata. This means the turn happened, but the bot cannot infer credits or cost from absent ACP metadata.

Aggregation #

/usage privately lists the requester's guild-wide current-month usage by default. Members with Manage Guild or Administrator permission may list every user with a current-month record or select another member; long reports automatically send additional ephemeral response parts when they exceed Discord's message limit. The report groups records by resolved Discord user ID when possible. If older records only have a username, the report merges that username into a user row only when it can do so unambiguously. Ambiguous names remain separate so the bot does not misattribute usage.

/usage-history privately returns guild-wide detailed records for the selected period and supports user, status, and source filters. Members may inspect their own history. Inspecting another member's detailed history requires Manage Guild or Administrator permission.

When filtering /usage-history, WebShare-originated agent work appears under the webshare source while still attributing usage to the opener whose Discord authority was delegated.

The report windows are:

• Today from local midnight in USAGE_TIMEZONE.
• This week from Monday local midnight.
• This month from the first day local midnight.

Use USAGE_RETENTION_MONTHS to prune old rows from the online SQLite database. The default 0 retains all online usage rows. This setting does not delete archived legacy JSONL migration backups.

Usage limits are optional per-user effective USD gates. The bot checks the current day, week, and month totals before starting new agent work; if a configured ceiling is already reached, the job is rejected without adding usage. OMP USD cost counts directly, and Kiro credits count as credits * USAGE_CREDIT_USD_RATE. IDs in BOT_GM_USER_IDS bypass these gates.