@heyamiko/amiko-cli 0.14.0-beta.18 → 0.14.0-beta.19

package/README.md

@@ -260,6 +260,9 @@ amiko chat send "Trip planning" "standup in 5" --all --yes    # same, via the ex
 amiko chat send @sophie "look 👀" --image ./cat.png --yes         # attach a local image
 amiko chat send @sophie "made this 🎵" --audio <generated-url> --yes  # attach audio (e.g. from `amiko create`)
 amiko chat receipts <messageId>                  # who read your message + when (id from `chat read`)
+amiko chat pin <messageId> --yes                 # pin for everyone (id from `chat read`; groups: admins only)
+amiko chat unpin <messageId> --yes               # remove a pin for everyone
+amiko chat pinned "Trip planning"                # list a conversation's pinned messages, oldest first
 ```
 
 - **`<target>`** for `read`/`send` is a **conversation id** (from `chat list` — use this for groups), a **user id**, an **`@handle`**, or a **name**. Names resolve against your **friends first**, then people search; if ambiguous, the CLI lists candidates instead of guessing. A cuid that isn't one of your conversations is retried as a user id, so pasting a user id "just works".
@@ -268,6 +271,7 @@ amiko chat receipts <messageId>                  # who read your message + when
 - **@all in groups**: `--all` prepends an @all mention, and a standalone `@all` word typed in the message converts too — either way **every member** is notified. Group **admins/owners** can always use it; everyone else only after an admin runs `amiko chat group mention-all <group> on`. Without permission, `--all` fails with the fix named, while a typed `@all` is delivered as plain text (with a note). Incoming mention markup renders as plain `@name`/`@all` in `chat read` and `chat list`.
 - `chat send` messages a real person, so it's **gated on `--yes`** in non-interactive shells. Delivery is real-time. `--raw` prints raw JSON on any subcommand.
 - **`chat receipts <messageId>`** shows read receipts for **your own** messages (server-enforced; 403 otherwise): sent time, who read it with each person's first-read time, and who it was delivered to but hasn't read. Reads from before receipts tracking show as "exact time unknown". Read-only, ungated.
+- **Pinned messages**: `chat pin <messageId>` pins for the **whole conversation** (the chat sees an "X pinned a message" announcement) and `chat unpin <messageId>` removes it for everyone — both gated on `--yes`. In **groups** only admins can pin/unpin (403 otherwise); in DMs either side can. Max 20 pins per conversation. `chat pinned <target>` (same targets as `read`; never creates a DM) lists them oldest-first with each message's id and pinner — read-only, ungated.
 
 ### Group chats
 
@@ -590,6 +594,10 @@ npm publish
 
 ## Changelog
 
+### 0.14.0-beta.19
+
+- **Pinned messages: `amiko chat pin <messageId>`, `amiko chat unpin <messageId>`, `amiko chat pinned <target>`.** Pins are conversation-wide: `pin` posts an "X pinned a message" announcement to the whole chat (POST `/api/messages/{id}/pin`), so it sits behind the outward-action `--yes` gate with a content preview; `unpin` (DELETE, silent but removes shared state for everyone) sits behind the destructive gate. Groups are admin-gated server-side — a 403 names the rule and the `chat group info` check; DMs let either side pin. 409 at the 20-pin cap and 400 for unpinnable (system/in-flight) messages get status-specific copy. `pinned <target>` is an ungated read using the same target resolution as `chat read` (conversation id, user id, `@handle`, or name; never creates a DM), listing pins oldest-first with sender, message id, and pinner name; `--raw` on all three. Requires the companion amiko-web `feat/chat-pinned-messages` deploy.
+
 ### 0.14.0-beta.18
 
 - **Read receipts: `amiko chat receipts <messageId>`.** Shows when the message was sent, who has read it (per-person first-read time), and who it was delivered to but hasn't read yet. Sender-only, enforced server-side — works for messages sent as the owner (`chat send`); anything else 403s with a clear message. Reader names resolve from the conversation's participant list (short-id fallback). Read-only and ungated, like `chat reactions`; `--raw` prints the API payload. Rows read before receipts tracking existed render as "exact time unknown". Requires the companion amiko-web `feat/chat-read-receipts` deploy (`GET /api/messages/{id}/receipts`).

package/dist/index.js

@@ -27672,6 +27672,20 @@ function registerChatGroupCommand(group) {
 }
 
 // src/commands/chat.ts
+var PIN_LIMIT = 20;
+function pinErrorMessage(e5, fallback2) {
+  const status = e5.status;
+  if (status === 403) {
+    return "Only group admins can pin or unpin messages in a group — check roles with `amiko chat group info`. In a DM either side can pin.";
+  }
+  if (status === 409) {
+    return `Pin limit reached (${PIN_LIMIT}) — unpin one first (see them with \`amiko chat pinned\`).`;
+  }
+  if (status === 400) {
+    return "This message can't be pinned (system and in-flight messages aren't pinnable).";
+  }
+  return e5 instanceof Error ? e5.message : fallback2;
+}
 async function findOrCreateDm(auth, userId) {
   const data = await amikoWebFetch(auth, "/api/conversations", {
     method: "POST",
@@ -28171,6 +28185,117 @@ function registerChatCommand(chat) {
       }
     }
   });
+  chat.command("pin <messageId>").description("Pin a message for everyone in the conversation. Get the message id from `amiko chat read`. Groups require the admin role; the chat sees a pinned-message announcement.").option("--yes", "Skip the confirmation (required in non-interactive shells)").option("--raw", "Output raw JSON").action(async (messageId, opts) => {
+    const auth = authOrExit();
+    let msg;
+    try {
+      msg = await fetchMessage(auth, messageId);
+    } catch (e5) {
+      console.error(error(e5 instanceof Error ? e5.message : "Could not load that message"));
+      process.exit(1);
+    }
+    await requireApproval({
+      free: "pins the message for everyone — the chat sees a pinned-message announcement",
+      summary: `Pin "${previewText(msg)}"`,
+      yes: opts.yes,
+      commandExample: `amiko chat pin ${JSON.stringify(messageId)}`
+    });
+    let data;
+    try {
+      data = await amikoWebFetch(auth, `/api/messages/${encodeURIComponent(messageId)}/pin`, { method: "POST", timeoutMs: 20000 });
+    } catch (e5) {
+      console.error(error(pinErrorMessage(e5, "Failed to pin the message")));
+      process.exit(1);
+    }
+    if (opts.raw) {
+      console.log(JSON.stringify(data, null, 2));
+      return;
+    }
+    console.log(success(`Pinned "${previewText(msg)}"`));
+    const total = data.pins?.length;
+    if (typeof total === "number") {
+      console.log(dim(`  ${total}/${PIN_LIMIT} pinned in this conversation — see them with \`amiko chat pinned\`.`));
+    }
+  });
+  chat.command("unpin <messageId>").description("Unpin a message — removes it from the conversation's pinned list for everyone. Get the message id from `amiko chat read` or `amiko chat pinned`.").option("--yes", "Skip the confirmation (required in non-interactive shells)").option("--raw", "Output raw JSON").action(async (messageId, opts) => {
+    const auth = authOrExit();
+    let msg;
+    try {
+      msg = await fetchMessage(auth, messageId);
+    } catch (e5) {
+      console.error(error(e5 instanceof Error ? e5.message : "Could not load that message"));
+      process.exit(1);
+    }
+    await confirmDestructive({
+      action: `Unpin "${previewText(msg)}" for everyone in the conversation`,
+      yes: opts.yes,
+      commandExample: `amiko chat unpin ${JSON.stringify(messageId)}`
+    });
+    let data;
+    try {
+      data = await amikoWebFetch(auth, `/api/messages/${encodeURIComponent(messageId)}/pin`, { method: "DELETE", timeoutMs: 20000 });
+    } catch (e5) {
+      console.error(error(pinErrorMessage(e5, "Failed to unpin the message")));
+      process.exit(1);
+    }
+    if (opts.raw) {
+      console.log(JSON.stringify(data, null, 2));
+      return;
+    }
+    console.log(success(`Unpinned "${previewText(msg)}"`));
+    const remaining = data.pins?.length;
+    if (typeof remaining === "number" && remaining > 0) {
+      console.log(dim(`  ${remaining} still pinned in this conversation.`));
+    }
+  });
+  chat.command("pinned <target>").description("List a conversation's pinned messages, oldest first (conversation id, user id, @handle, or name)").option("--raw", "Output raw JSON").action(async (target, opts) => {
+    const auth = authOrExit();
+    let convId;
+    try {
+      const resolved = await resolveConversation(auth, target);
+      if (resolved.kind === "user") {
+        const existing = await findDmByUserId(auth, resolved.userId);
+        if (!existing) {
+          throw new Error(`No ${resolved.label} yet — start one with \`amiko chat send\`.`);
+        }
+        convId = existing;
+      } else {
+        convId = resolved.id;
+      }
+    } catch (e5) {
+      console.error(error(e5 instanceof Error ? e5.message : "Could not resolve target"));
+      process.exit(1);
+    }
+    let data;
+    try {
+      data = await amikoWebFetch(auth, `/api/conversations/${encodeURIComponent(convId)}/pinned-messages`, { timeoutMs: 20000 });
+    } catch (e5) {
+      console.error(error(e5 instanceof Error ? e5.message : "Failed to load pinned messages"));
+      process.exit(1);
+    }
+    if (opts.raw) {
+      console.log(JSON.stringify(data, null, 2));
+      return;
+    }
+    const pins = data.pins ?? [];
+    if (pins.length === 0) {
+      console.log(dim("No pinned messages."));
+      return;
+    }
+    console.log(heading(`Pinned messages (${pins.length})
+`));
+    for (const pin of pins) {
+      const m = pin.message;
+      const who = m.name ?? (m.sender_id ? m.sender_id.slice(0, 8) : "?");
+      const when = m.created_at ? m.created_at.slice(0, 19).replace("T", " ") : "";
+      console.log(label(who, mentionMarkupToPlainText(m.content ?? "")));
+      const meta3 = [when, `id ${m.id}`].filter(Boolean).join("  ");
+      console.log(dim(`  ${meta3}`));
+      if (pin.pinned_by_name) {
+        console.log(dim(`  pinned by ${pin.pinned_by_name}`));
+      }
+    }
+  });
   const group = chat.command("group").description("Group chats — create, list, info, rename, add/remove members, @all permission, leave");
   registerChatGroupCommand(group);
 }

package/package.json

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

package/skills/SKILL.md

@@ -35,6 +35,8 @@ Call your shell tool (your runtime calls it `bash`, `shell`, `run`, or similar)
 | "share the group's invite link" (asked by an admin) | shell → `amiko chat group info "<group>"` (confirm they're admin) → `amiko chat group invite "<group>"` |
 | "react to the latest message from Ava about the team with a heart" | shell → `amiko chat read "Ava"` (find that message, copy its `id`) → `amiko chat react <messageId> ❤️ --yes` |
 | "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>"` |
 | "what can amiko do?" | shell → `amiko --help` |
 | "what's my MiniMax / ElevenLabs voice id?" | shell → `amiko info` |
 | "speak with my cloned MiniMax voice" | shell → `amiko info`, quote the cost, obtain explicit approval, then run `amiko create tts "…" --provider minimax --voice <minimax_voice_id> --yes` |
@@ -54,7 +56,7 @@ Discover everything via `amiko --help`. Groups: `markets` (paid MPP services), `
 
 ## Critical Rules
 
-1. **Every paid / value-moving command is hard-gated on `--yes` in a non-interactive shell.** The CLI refuses to run `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`.** The same `--yes` gate also covers **free outward social actions** — `chat send`, `chat group create`, `chat group add` (real people see them, so get the owner's explicit approval for the action itself) — and **destructive ops** like `chat group remove/leave/rename/promote/mention-all`, `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 `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`.** 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` (real people see them, so get the owner's explicit approval for the action itself) — and **destructive ops** like `chat unpin` (removes the pin for everyone), `chat group remove/leave/rename/promote/mention-all`, `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`.
@@ -150,6 +152,7 @@ MiniMax Hailuo is silent — there is no CLI mux step to attach a separate music
 - 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_*`.
 - **Read receipts** — `amiko chat receipts <messageId>` shows when the message was sent, who has read it (with each person's first-read time), and who it was delivered to but hasn't read yet. **Only works for messages the owner sent** (server-enforced) — a 403 means it wasn't the owner's message; report that, don't retry. Get the id from `amiko chat read <target>`, matching the message by its **content**. Read-only and ungated, like `reactions`. Rows marked "exact time unknown" were read before receipts tracking existed — never invent a time for them.
+- **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.
 
 ### Group chats — `amiko chat group`