nyatipaw

nyatipaw is the Nyatif social-agent product. It uses the verified nyaticode/nyatibara direction as its contract and treats OpenClaw as a reference, not a compatibility target.

Current surfaces:

• nyatipaw doctor local readiness report for config, memory, channel/provider setup, runtime, and teams
• nyatipaw doctor --strict live-readiness gate that exits nonzero when Mattermost, provider, memory, or channel isolation requirements are not ready
• nyatipaw live-smoke --include-disabled --require-all integrated credentialed verifier for configured Mattermost, Telegram, Discord, provider, and optional outbound send checks
• nyatipaw tui/nyatipaw configure ratatui settings UI for workspace, model providers, channel credentials, pending pairing approvals, and private/channel isolation policies
• Non-interactive provider/model subcommands for setup automation
• nyatipaw configure provider add-codex --model gpt-5.5
• nyatipaw configure provider add-ollama --base-url http://127.0.0.1:11434/v1 --model llama3.2
• nyatipaw configure provider add-open-ai-compatible <name> --base-url <url> --model <id>
• nyatipaw configure model set-default <provider/model> and nyatipaw models
• nyatipaw gateway install/status/start/stop/restart for user-level systemd gateway service management
• nyatipaw automation schedule/heartbeat/tasks/runs/wakes for OpenClaw-style resident automation
• nyatipaw web local web control UI
• nyatipaw pairing list/request/approve for DM pairing approval, with optional requester notification
• nyatipaw memory write/search
• nyatipaw mattermost send
• nyatipaw mattermost monitor for Mattermost WebSocket event ingress
• nyatipaw mattermost verify for read-only live Mattermost bot verification
• nyatipaw telegram send --chat <id> "text" for Telegram outbound messages
• nyatipaw telegram verify for read-only live Telegram bot verification
• nyatipaw telegram discover to summarize recent Telegram updates and find chat/thread ids after sending a message to the bot
• nyatipaw discord send --channel <id> "text" for Discord outbound messages
• nyatipaw discord verify for read-only live Discord bot verification
• nyatipaw misskey send/react/verify for Misskey note send, reaction, and token verification
• POST /channels/mattermost/inbound for Mattermost webhook ingress
• POST /channels/telegram/inbound for Telegram update webhook ingress
• POST /channels/discord/inbound for Discord message webhook ingress
• POST /hooks/wake and POST /hooks/agent for authenticated automation hooks
• nyatipaw channel ingest --kind telegram|discord|mattermost|web for adapter-path smoke testing
• nyatipaw team create/status/mate-spawn/mate-message/task-create/task-update/dispatch/reconcile/list and nyatipaw subagent
• nyatipaw runtime list/pending/events/transcript/checkpoint/drain-once to inspect and process queued runtime commands
• nyatipaw runtime send/resume/cancel/close --session <key> for explicit session control
• nyatipaw runtime delivery list|get|clear to inspect stuck outbound channel delivery records and intentionally clear retry/dead-letter state
• GET /api/doctor, GET /api/runtime/snapshot, GET /api/runtime/session?session=<key>, and GET /runtime/events/stream for web timeline/session refresh
• Web runtime session cards with transcript previews and an in-page transcript/command/event detail pane
• Runtime session policy ledger persisted at workspace/runtime/session_policies.json, surfaced through Web session snapshots
• Web team forms for create, mate spawn/message, task create, and task status updates
• Web subagent form for creating isolated child sessions from a parent session
• Web settings form for editing first-agent private/channel isolation policies
• Web pairing approval controls for pending DM access requests

The default config is created at .nyatipaw/config.toml; agent workspace files are created under .nyatipaw/workspace.

See docs/AUTOMATION.md for scheduler, heartbeat, background task, hook, and standing-order conventions.

Misskey channel

Misskey is a channel gateway for SNS-style notes rather than editable chat messages. Configure it through nyatipaw tui or .nyatipaw/config.toml:

[misskey]
enabled = true
base_url = "https://example.invalid"
account = "danabot"
token = "..."
default_visibility = "home"
local_only = true
reaction_ack = ""
reaction_processing = "⏳"

default_visibility = "home" is the Misskey API value for unlisted-style timeline delivery. Keep local_only = true unless federation is intentional. The gateway connects to Misskey streaming and can use reactions as status indicators. reaction_ack marks that nyatipaw accepted the note into its runtime queue, but defaults to off because Misskey reaction deletion is commonly rate-limited. When the actual model turn starts, nyatipaw removes that reaction if configured and applies reaction_processing. After the final reply note is sent, all configured status reactions are removed. Configure these through nyatipaw configure misskey set --reaction-ack 👀 --reaction-processing ⏳ or disable them with --no-reaction-ack / --no-reaction-processing. Misskey replies are posted as new notes; nyatipaw does not edit progress/status notes on Misskey because note edits are a poor fit for federation.

Misskey image attachments are parsed from note files. The gateway downloads a small bounded set of non-sensitive image/* files and passes them as ModelContentBlock::Image to the shared runtime, so vision-capable OpenAI-compatible/Ollama routes can inspect them directly. Sensitive, unsupported, oversized, or failed downloads are preserved as text omissions in the model-visible turn context rather than silently disappearing.

Outbound delivery is tracked separately from the runtime transcript. Successful events are marked sent, rate-limited events are retried after the channel reset hint or a bounded backoff, and permanent 4xx channel failures are dead-lettered instead of being resent every gateway tick. Reaction failures are logged and cleared independently so they do not block final reply delivery. Operators can inspect the state with:

nyatipaw runtime delivery list
nyatipaw runtime delivery get EVENT_ID
nyatipaw runtime delivery clear EVENT_ID

Misskey thread sessions are rooted by the root note id, not by each individual mention note. Each inbound turn carries a Misskey context block with the sender id, username/name, bot flag, role, visibility, note id, reply id, and root id so the model can distinguish a public/home/unlisted thread from a direct exchange. Owner/admin identity grants authority, but public/home/unlisted thread turns still use the restricted channel policy; private workspace memory and host tools are only available by default in direct/specified owner/admin sessions.

By default, the final assistant message is posted as a Misskey thread reply. Misskey exception tools are only for replacing that default behavior: misskey_no_reply ignores low-value or bot-like interactions, misskey_private_reply sends privately to paired owner/admin users, misskey_react_only acknowledges with a reaction and no text, and misskey_escalate routes the turn to owner/admin handling. If an exception is recorded for the turn, later plain final assistant messages for that turn are not posted publicly to Misskey. If a turn reads or executes against sensitive paths such as .nyatipaw/config.toml, auth files, tokens, or secret-looking config output, the tool result marks the turn as private. Misskey then sends the final reply as a specified note visible only to paired owner/admin user ids for that account, and refuses to send if no paired private recipient is available. Replies are never sent with broader visibility than the note being replied to. For example, a home/unlisted default is clamped down when replying into a followers-only or specified note. If nyatipaw cannot determine a safe specified audience, the delivery is dead-lettered rather than retried forever.

Owner/admin Misskey sessions expose guarded Misskey API tools for note creation and reaction management. General channel sessions do not see those tools. Public or otherwise restricted users can use web_search and web_fetch for general research. web_fetch refuses private, loopback, link-local, and otherwise internal IP hosts unless a stricter deployment-level egress policy overrides the container. Restricted users may also write durable notes through memory_write, but those writes are scoped to the current channel/session under memory/scoped/ and do not modify USER.md or MEMORY.md. Restricted channel users may create bounded one-shot reminders with wake_after and reminder_create. These timers are limited to the current session/channel, must deliver back to the current channel, cannot create cron or repeating schedules, and are capped to short-term reminders. Owner/admin sessions keep the full scheduler surface. Scheduled jobs support delivery_mode = auto | thread | new-message. The default keeps one-shot thread reminders best-effort but sends recurring reports as new channel messages, so daily automation does not keep replying under the note or post that originally created it.

The first Misskey channel admin must be paired before the channel performs any general action. Before a misskey:<account>:<user-id> owner/admin exists, public timeline notes are ignored even if public activation is configured as Always. A direct note, reply, or mention can create a pairing request:

nyatipaw pairing list
nyatipaw pairing approve CODE --role admin

TUI pairing approval also shows the recommended role and allows an explicit role override. After admin pairing, that admin can decide whether later users should be ignored, handled as public/limited users, or added to another access role through the normal access-policy commands.

Credentialed completion gates are documented in docs/LIVE_VERIFICATION.md and runnable with scripts/live-gates.sh. Use docs/examples/live-gates.env.example as the non-secret env template. Local repeatable gates are runnable with scripts/local-gates.sh.

nyatiagents also exposes the optional nyatibara-agent-compat feature for type-checked conversion into nyatibara-agent command/event payloads.

Build nyatipaw with --features nyatibara-agent-runtime to expose nyatipaw runtime drain-agent-once, which mirrors pending commands into a nyatibara-agent supervisor and wakes the actor with a deterministic local turn runner. This proves the actor/checkpoint path can persist both inbound user messages and assistant turns before a real provider runner is wired in. Agent and provider drain paths emit runtime turn-started/turn-completed status events, which the Web UI surfaces as the session's latest status.

Build with --features nyatibara-provider-runtime to expose nyatipaw runtime drain-provider-once and nyatipaw runtime verify-provider. The drain command uses nyatibara-core::ToolLoop and nyatibara-providers::ProviderRegistry for real model turns; the verify command performs a read-only provider/model-list check. Configure with nyatipaw configure provider ...; env-only fallback still accepts NYATIPAW_MODEL, such as openai/gpt-5.4 or openai-compatible/local-model, plus matching provider env vars.