@heyamiko/amiko-cli 0.17.2 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heyamiko/amiko-cli",
-  "version": "0.17.2",
+  "version": "0.19.0",
   "description": "Amiko CLI — swap tokens, manage credits, bridge cross-chain, and call marketplace agents",
   "type": "module",
   "bin": {

package/skills/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: amiko-cli
-description: The Amiko CLI lets an agent act on the Amiko platform end-to-end — read platform notifications (friend requests, mentions, system alerts), search and write **cross-agent memories** about the owner (what other agents already know — preferences, decisions, facts), manage Solana/Base wallets (create, swap via Jupiter, bridge USDC via Across, transfer tokens to external addresses), top up and spend credits, generate media — images, video, speech, music, and SFX — via Create Studio (`amiko create`, async and charged on success), call paid MPP marketplace services (X/Twitter search, Amazon product search, TTS/STT, AI chat), manage the twin's identity and drive (files, folders, RAG), voice and avatar, and social graph (friends, follows, private friend nicknames, posts/notes with titles, images and document attachments, comments, who liked a post, feed). Auth is automatic when run from the agent's workspace folder; payments are platform-custodied (no keys on disk). The owner's DMs and group chats are `amiko chat` (list / read / send / mark everything read / see which chats have unread @mentions or replies to the owner (`chat list --mentions`) / organize chats into private folders (`chat lists`) / create + manage group chats AS the owner, including sending GIFs (`chat gifs` search + `chat send --gif`), sharing a group's invite/join link + QR and @all group announcements, 人对人); the agent's OWN sessions are the openhermit gateway's session_list / session_send (AS the agent) — different identities, different surfaces. Use this skill whenever the user asks about their Amiko notifications, chats/DMs, drive, memory, social graph, wallets, credits, or marketplace services — anything that would show up in their Amiko account or cost AMIKO/credits.
+description: The Amiko CLI lets an agent act on the Amiko platform end-to-end — read platform notifications (friend requests, mentions, system alerts), search and write **cross-agent memories** about the owner (what other agents already know — preferences, decisions, facts), manage Solana/Base wallets (create, swap via Jupiter, bridge USDC via Across, transfer tokens to external addresses), top up and spend credits, generate media — images, video, speech, music, and SFX — via Create Studio (`amiko create`, async and charged on success), call paid MPP marketplace services (X/Twitter search, Amazon product search, TTS/STT, AI chat), manage the twin's identity and drive (files, folders, RAG), voice and avatar, and social graph (friends, follows, private friend nicknames, posts/notes with titles, images and document attachments, comments, who liked a post, feed). Auth is automatic when run from the agent's workspace folder; payments are platform-custodied (no keys on disk). The owner's DMs and group chats are `amiko chat` (list / read / send / mark everything read / see which chats have unread @mentions or replies to the owner (`chat list --mentions`) / organize chats into private folders (`chat lists`) / create + manage group chats AS the owner, run chat polls (`chat poll` create / vote / close, quizzes included), including sending GIFs (`chat gifs` search + `chat send --gif`), sharing a group's invite/join link + QR and @all group announcements, 人对人); the agent's OWN sessions are the openhermit gateway's session_list / session_send (AS the agent) — different identities, different surfaces. Use this skill whenever the user asks about their Amiko notifications, chats/DMs, drive, memory, social graph, wallets, credits, or marketplace services — anything that would show up in their Amiko account or cost AMIKO/credits.
 homepage: https://platform.heyamiko.com
 metadata: {"openclaw":{"emoji":"🤖","requires":{"bins":["node"]}}}
 ---
@@ -48,6 +48,9 @@ Call your shell tool (your runtime calls it `bash`, `shell`, `run`, or similar)
 | "did Sophie read my message about the demo?" | shell → `amiko chat read "Sophie"` (find the owner's message, copy its `id`) → `amiko chat receipts <messageId>` |
 | "pin that hackathon message in the builders group" | shell → `amiko chat read "<group>"` (find the message, copy its `id`) → `amiko chat pin <messageId> --yes` |
 | "what's pinned in the team chat?" | shell → `amiko chat pinned "<group>"` |
+| "start a poll in the team chat: pizza or sushi?" | confirm the question + options with the owner → `amiko chat poll create "<group>" "Pizza or sushi?" --option Pizza --option Sushi --yes` |
+| "vote Sushi on Mars's lunch poll" | shell → `amiko chat read "<group>"` (find the 📊 poll, copy its `id`) → `amiko chat poll vote <messageId> Sushi --yes` |
+| "how's my poll doing? / end the poll" | shell → `amiko chat poll show <messageId>` · to end it (permanent) → `amiko chat poll close <messageId> --yes` |
 | "mark all my chats as read" | shell → `amiko chat mark-read --all --yes` (after the owner confirms — it clears every badge and senders see read ticks) |
 | "any unread mentions or replies to me?" | shell → `amiko chat list --mentions` (chats whose unread messages @mention the owner or reply to them) |
 | "what chat lists do I have? what's in my Work list?" | shell → `amiko chat lists` |
@@ -73,7 +76,7 @@ Discover everything via `amiko --help` (or `amiko <group> --help` / `amiko <grou
 
 ## Critical Rules
 
-1. **Every paid / value-moving command is hard-gated on `--yes` in a non-interactive shell.** The CLI refuses to run `search *`, `markets *`, `create *`, `card mint`, `credits topup`, `wallets swap send`, `wallets bridge send`, `wallets transfer` unless `--yes` is passed. The refusal prints the cost and the re-run command. **Quote the cost, get explicit approval, THEN append `--yes`.** For `create *` there is a step before that — propose the model and settings and get the owner's sign-off on the *plan* first; see **Proposing, then quoting, before you generate**. The same `--yes` gate also covers **free outward social actions** — `chat send`, `chat pin` (the whole chat sees a pinned-message announcement), `chat group create`, `chat group add`, `friends add` / `friends accept` (real people see them — a friended user is notified — so get the owner's explicit approval for the action itself) — and **destructive ops** like `chat unpin` (removes the pin for everyone), `chat mark-read --all` (irreversibly marks every conversation read — senders see read ticks), `chat group remove/leave/rename/promote/mention-all`, `chat lists create/rename/add/remove/delete` (private to the owner, but they reshape the owner's chat UI), `friends nickname set/remove` (private to the owner, but it changes how that friend is displayed everywhere in the owner's apps), `twin update --public`, `drive delete`, `drive share` / `drive folder share` (exposes the file — or the folder's ENTIRE subtree — to anyone with the link), `friends remove`, `friends reports request`, `avatar update`, `voice reset`, `review reject`. **For these free actions never mention cost, never say "the cost is 0", and never call it a paid operation** — ask for plain confirmation of the action itself (e.g. "Send "hi" to Mars — go ahead?").
+1. **Every paid / value-moving command is hard-gated on `--yes` in a non-interactive shell.** The CLI refuses to run `search *`, `markets *`, `create *`, `card mint`, `credits topup`, `wallets swap send`, `wallets bridge send`, `wallets transfer` unless `--yes` is passed. The refusal prints the cost and the re-run command. **Quote the cost, get explicit approval, THEN append `--yes`.** For `create *` there is a step before that — propose the model and settings and get the owner's sign-off on the *plan* first; see **Proposing, then quoting, before you generate**. The same `--yes` gate also covers **free outward social actions** — `chat send`, `chat pin` (the whole chat sees a pinned-message announcement), `chat poll create` / `chat poll vote` / `chat poll retract` (the chat sees the poll and the updated results), `chat group create`, `chat group add`, `friends add` / `friends accept` (real people see them — a friended user is notified — so get the owner's explicit approval for the action itself) — and **destructive ops** like `chat unpin` (removes the pin for everyone), `chat poll close` (ends the poll for everyone — it can't be reopened), `chat mark-read --all` (irreversibly marks every conversation read — senders see read ticks), `chat group remove/leave/rename/promote/mention-all`, `chat lists create/rename/add/remove/delete` (private to the owner, but they reshape the owner's chat UI), `friends nickname set/remove` (private to the owner, but it changes how that friend is displayed everywhere in the owner's apps), `twin update --public`, `drive delete`, `drive share` / `drive folder share` (exposes the file — or the folder's ENTIRE subtree — to anyone with the link), `friends remove`, `friends reports request`, `avatar update`, `voice reset`, `review reject`. **For these free actions never mention cost, never say "the cost is 0", and never call it a paid operation** — ask for plain confirmation of the action itself (e.g. "Send "hi" to Mars — go ahead?").
 2. **After every paid command, report the remaining balance.** The CLI prints a `Balance: N credits` line — include that figure in your reply.
 3. **Never retry a failed command.** Report and stop. Every paid call costs tokens even on failure.
 4. **Auth is automatic.** Never suggest `amiko login` / `amiko connect`. Run from the agent's workspace folder; if anything looks off, `amiko accounts` shows the resolved `userId` / `twinId`.
@@ -263,7 +266,12 @@ MiniMax Hailuo (02/2.3) is silent — there is no CLI mux step to attach a separ
 - `amiko chat list` — all conversations, **DMs and group chats** (id, type, peer/title, last message, unread). Rows with unread messages that concern the owner directly show an **`@you` marker**, and `--mentions` filters to just those. `@you` / `--mentions` means the unread messages include a **direct @mention of the owner, a permitted @all in a group, or a reply to one of the owner's messages** — so "did anyone reply to me?" is also answered here, not just literal mentions. No `@you` rows under `--mentions` = nothing unread needs the owner's attention specifically. (On servers that predate the flag it reads as false for every conversation: unread counts still show, `@you` never does, and `--mentions` matches nothing — an empty result there is NOT proof nobody mentioned or replied.)
 - `amiko chat read <target>` — recent messages. `<target>` = a conversation id (from `list`), a **user id**, an `@handle`, or a name. Reading never creates a conversation — if there's no DM with that person yet, it says so.
 - `amiko chat send <target> "message"` — send **as the owner**. Delivered in real time. `--yes` required in non-interactive shells (it's an outward message to a real person). `<target>` = a conversation id, a **user id**, an `@handle`, or a name. A user id / @handle / unambiguous name opens (or reuses) the DM for you — but only **after** the owner approves the send (via the confirmation, or `--yes` in your shell); nothing is created if approval is refused. **The owner never needs to start the conversation first, and there is no platform authorization step for starting a DM.** For **group chats**, use the conversation id from `list`. **@all in groups:** add `--all` (or write a standalone `@all` word in the message) to notify **every member** — allowed for group admins/owners, or for everyone once an admin enables it (`amiko chat group mention-all <group> on`). The CLI pre-checks permission: `--all` without it fails and names the fix; a plain `@all` word still sends, as ordinary text, with a note. It pings the whole group — use it only when the owner clearly wants everyone notified.
-- **Inline media**: `--image <pathOrUrl>` (jpg/png/webp/gif, local ≤10MB or an Amiko URL — e.g. a generated image), `--audio <pathOrUrl>` (local ≤25MB or an Amiko URL → sent as a voice note), and `--gif <queryOrUrl>` (see GIFs below). One media block per message (image XOR audio XOR gif). **General video files are not supported** on chat yet. To share a generated asset, pass its URL from `amiko create status` (no re-upload). A local audio file is sent as a voice note with the text as a separate message.
+- **Inline media**: `--image <pathOrUrl>` (jpg/png/webp/gif, local ≤10MB or an Amiko URL — e.g. a generated image), `--audio <pathOrUrl>` (local ≤25MB or an Amiko URL → sent as a voice note), and `--gif <queryOrUrl>` (see GIFs below). One of those per message (image XOR audio XOR gif); `--image` may be combined with `--attach`. **Local video files are not supported** on chat yet — a Library/Explore video goes through `--attach`. To share a generated asset, pass its URL from `amiko create status` (no re-upload) or its `library:<id>` ref. A local audio file is sent as a voice note with the text as a separate message.
+- **Attach from Drive / Library / Explore** — `amiko chat send <target> "text" --attach <ref> [--attach <ref>…]`, up to **6 attachments per message** (a `--image` counts). Use this whenever the owner asks to send something that already lives on Amiko — "send Sophie the report from my drive", "share my latest creation", "send that sunset post from Explore". Refs:
+  - `drive:<docId>` — **images and documents only** (pdf, docx, …, ≤25MB); get the `id` from `amiko drive list --json` or `amiko drive search "<words>" --json`, matching by filename/title. Drive audio/video is refused (say so; offer the Library version if it's a creation).
+  - `library:<id>` — the owner's Create Studio creations; list with `amiko chat library` (`--kind image|video|audio`, `--search "<prompt words>"`, `--raw` for JSON). The owner's creations are *their* Library — don't use Explore for them.
+  - `explore:post:<postId>:<n>` — public media other people published; list with `amiko chat explore` (`--kind`, `--search "<title words>"`, `--cursor` to page). Copy the `REF` column as-is.
+  - Drive and Library read the current twin; `--twin <id>` targets another twin's. Text is optional with `--attach`. `--attach` can't be combined with `--audio`/`--gif`. Errors like "wasn't found", "can't be attached to a chat" or "over the 25MB chat attachment limit" are final for that ref — report them, don't retry blindly. `chat library`/`chat explore` are free, ungated reads; the send stays `--yes`-gated.
 - **GIFs** — `amiko chat send <target> --gif "<search words>"` sends the **top Klipy result** for those words (the message text is optional with `--gif`; when present it becomes the GIF's caption). To send a *specific* GIF, browse first with `amiko chat gifs "<search words>"` (trending when no query; `--page`/`--limit`/`--raw`; read-only and ungated) and pass the chosen result's URL to `--gif`. Only Klipy URLs are accepted there — any other image must go through `--image` as a local file or an Amiko URL (arbitrary external URLs aren't supported). Recipients on web/desktop/mobile see a looping GIF (with the KLIPY watermark), so this is the right tool when the owner asks to "send a GIF" — don't generate media with `amiko create` for that. The send itself stays `--yes`-gated like every `chat send`.
 - Plain names resolve against the owner's **friends first**, then people search; if ambiguous the CLI errors listing the candidates — ask the owner which one, don't blind-send. A plain name that exactly matches one of the owner's group titles targets that **group**. If a send fails, surface the CLI's error verbatim — don't invent permission explanations or ask the owner to open the chat from the app.
 - **Reactions** — `amiko chat react <messageId> <emoji>`, `amiko chat unreact <messageId>`, `amiko chat reactions <messageId>`. The owner **won't give you a message id** — they'll say something like *"react to the latest Ava message about the team with a heart"*. Get ids from `amiko chat read <target>`: it prints each message's `id` and any existing reactions — match the message by its **content**, then act on that id. `react` adds (or replaces) your reaction — **one per message**, a new emoji replaces the previous one, and re-reacting the same emoji is a no-op (use `unreact` to remove). Pass the **actual emoji character** (`❤️`, `👍`, `😂`). `react`/`unreact` are outward (other people see them), so `--yes` is required in non-interactive shells and the confirmation shows a preview of the target message; `reactions` (read) is ungated. These act **as the owner** (人对人), just like `chat send` — not the twin's own `session_*`.
@@ -271,6 +279,17 @@ MiniMax Hailuo (02/2.3) is silent — there is no CLI mux step to attach a separ
 - **Pinned messages** — `amiko chat pin <messageId>`, `amiko chat unpin <messageId>`, `amiko chat pinned <target>`. Pins are **conversation-wide**: everyone sees them, and `pin` posts an "X pinned a message" announcement to the whole chat, so both `pin` and `unpin` are `--yes`-gated with a preview of the target message. The owner won't give you a message id — get it from `amiko chat read <target>` (or `amiko chat pinned <target>` when unpinning), matching by **content**. In **groups** only admins can pin/unpin (a 403 names that rule; check roles with `amiko chat group info`, report it, don't retry); in DMs either side can. Max 20 pins per conversation — a "Pin limit reached" error means unpin one first, ask the owner which. Re-pinning an already-pinned message is a harmless no-op. `pinned <target>` is an ungated read (same targets as `chat read`: conversation id, user id, `@handle`, or name; it never creates a DM) listing pins oldest-first with each message's `id` and who pinned it.
 - **Mark all read** — `amiko chat mark-read --all` marks EVERY conversation read as the owner in one shot: unread badges clear on all the owner's devices, the owner's chat/mention notifications clear, and senders see read ticks on their messages (the ~50 most recent conversations flip live; the rest on their next refresh). Irreversible — there is no "mark unread" — so it's `--yes`-gated: only run it when the owner explicitly asks to clear everything, never as routine tidying. The success line won't say how many conversations were affected (the server doesn't report a full count); don't invent a number.
 
+### Polls — `amiko chat poll`
+
+Chat polls in the owner's DMs and groups, **as the owner**: `create <target> <question> --option <text>…`, `show <messageId>`, `vote <messageId> <choice…>`, `retract <messageId>`, `close <messageId>`.
+
+- **Create:** 2–12 unique `--option`s (≤100 chars each; question ≤300). `--multiple` allows several answers, `--anonymous` hides who voted for what, `--quiz --correct <n>` (1-based) makes a quiz with one right answer, optional `--explanation` (≤200). Same targets as `chat send` (a DM with a person is opened after approval). Polls only work in **DMs and groups with at least two people** — never in channels, support chats, or the owner's own chat with you (their twin); the CLI and server both refuse those. Confirm the question and options with the owner before running with `--yes`.
+- **Find the poll:** the owner won't give you an id. `amiko chat read <target>` shows each poll as `📊 <question>` with its options, tallies and `●` on the owner's own choices — copy that message's `id`. `amiko chat poll show <id>` gives the full picture: voter names (non-anonymous polls), the owner's current vote, and which actions are still open.
+- **Vote:** `vote <id> <choice…>` **sets the owner's answer to exactly these choices** (replacing any earlier vote). A choice is the option's number from `show`, its text, or its id. Single-answer polls take one choice; for multi-answer polls pass them all. `retract <id>` removes the vote. You vote **as the owner** — never pick on your own; ask which option the owner wants.
+- **Quizzes:** results and the answer stay hidden until the owner answers; the answer is **final** (no changing or retracting); the owner can't answer their own quiz. Don't reveal a quiz's answer from a poll the owner created to other people.
+- **Close:** only the poll's creator can `close` it, and it's **permanent** — votes stop and a quiz's answer is revealed to everyone. Only close when the owner asks.
+- Errors like "This poll has ended", "quiz answers are final", or "Polls are only available in…" are final — report them, don't retry. `create`/`vote`/`retract`/`close` need `--yes` in your shell (see Critical Rules); `show` is a free, ungated read.
+
 ### Group chats — `amiko chat group`
 
 Create and manage the owner's group chats: `create <name> --member <who>…`, `list`, `info <group>`, `invite <group>`, `rename <group> <newTitle>`, `add <group> --member <who>…`, `remove <group> --member <who>…`, `promote <group> --member <who>`, `mention-all <group> <on|off>`, `leave <group>` (alias `delete`).