dsh-realtimeavatar

dsh plugin --profile web add dsh-realtimeavatar

dsh-realtimeavatar


**Realtime Avatar for the DeepSeek Harness: the developer's API key held by the harness, the public docs as on-demand skills, rta_* tools over the public REST API, and a /rta command that walks a developer from no key to a live call.**

Realtime Avatar puts a live AI character on a voice or video call. The developer surface is the realtime-avatar npm SDK (source) and a REST API at https://realtimeavatar.ai/api/v1. Driving that from a coding agent usually means pasting an API key into chat, re-explaining the documentation every session, and letting the agent call endpoints that spend credits without anyone noticing. This plugin gives the harness the avatar as a primitive instead: the key is a credential reference the harness resolves per call and the model never sees; the documentation is five skills the model loads when they are relevant; the API is eighteen typed tools behind a write-approval gate; and /rta does onboarding without the model in the loop.

Writes are enabled by default but approval-gated, and anything that spends credits always asks. readOnly:true turns every write off.

What you get

Tools

Read tools run without approval and are marked concurrency-safe, so the harness may run them in parallel. rta_docs and rta_quickstart need no key at all.

Tool · Scope · What it does

rta_status · credits:read, realtime:write · Self-check: whether a key is configured (source and live/test tag, never the value), the credit balance, live capacity, the write posture, and what to do next. Run it first when something is off.

rta_balance · credits:read · Credit balance: available, reserved and lifetime credits, with an approximate number of minutes on air (1 credit = 1 second).

rta_capacity · realtime:write · Live-call capacity snapshot: free and active slots, queue depth, whether admission is open, recommended retry delay. Informational only — it does not predict whether a mint will be granted, so never gate a mint on it; mint, and treat a queued answer as the signal.

rta_avatars · avatars:read · List the workspace's avatars with status and idleVideoStatus (most recently updated first, capped at 100).

rta_avatar · avatars:read · Fetch one avatar. The tool to poll every few seconds after rta_avatar_create until status is ready.

rta_clips · avatars:read · An avatar's motion-clip library (clipId, role, status, whenHint) plus the revision that rta_clips_set can compare against.

rta_assets · avatars:read · List uploaded assets; an image asset id is what rta_avatar_create takes as sourceAssetId.

rta_usage · usage:read · Billed sessions: trailing 30 days by default, clamped to 90, paged by cursor, narrowable to one end user. Each row carries activeSeconds (the spec field), avatarName and endUserId (taken from metadata.user_id). Only released and failed rows are settled, and the totals sum those rows only.

rta_session_release · realtime:write · Free a minted call's slot early. Free of charge and idempotent, which is why it sits in the read tier.

rta_docs · none · The current markdown of one public documentation page: the 14 doc pages plus index (llms.txt) and openapi (an operation table). Optional heading returns one section.

rta_quickstart · none · The integration page for one framework (nextjs, tanstack-start, express, hono, react) with the server-half and client-half code skeletons extracted; falls back to the shipped snapshot when offline.

Write-free tools change state but spend no credits. They ask for approval by default and run without a prompt only when writeApproval:false.

Tool · Scope · What it does

rta_asset_remote · avatars:write · Register a file the platform fetches by absolute http(s) URL as an asset (image, video or audio).

rta_avatar_update · avatars:write · Partially update an avatar: display name, default voice, llmProvider and model, persona, art direction, stylePreset, settings, metadata, anchorTimeMs. llmProvider and stylePreset are closed enums: local, gemini, openai and cinematic-founder, editorial-companion, warm-anime, luxury-realism, soft-3d, noir-avatar. A portrait swap is its own lane: pass sourceAssetId (an image asset) alone, optionally with anchorTimeMs — it is exclusive of every other field.

rta_avatar_delete · avatars:write · Soft-delete an avatar; it disappears from every read afterwards.

Write-costly tools spend credits and always ask for approval, whatever writeApproval says.

Tool · Scope · What it does

rta_avatar_create · avatars:write · Create an avatar from a portrait image asset (one generation). Returns preprocessing; poll rta_avatar until ready.

rta_loop_set · avatars:write · Re-render an avatar's resting loop from a new motion prompt (one generation). Needs a portrait on the avatar (422 loop_not_generatable otherwise); do not gate on sourceKind — a ready avatar reads video once its generated loop attaches. Sends an Idempotency-Key so a retry never renders twice.

rta_clips_set · avatars:write · Declare the full clip library: new clips render, matching ones are kept, dropped ones retire, and an empty array retires every clip. At most 12 entries; each clipId matches ^[a-z0-9][a-z0-9_-]*$ (≤64 chars), whenHint is ≤280 chars, durationSeconds is an integer 4–8, and source is { motionPrompt } or { assetId }. Idempotency-Key plus an optional compare-and-swap on `expe

…(truncated)