@heyamiko/amiko-cli 0.12.0-beta.3 → 0.12.0-beta.5

package/README.md

@@ -1,4 +1,4 @@
-# @heyamiko/amiko-cli (v0.11.0-beta.3)
+# @heyamiko/amiko-cli (v0.12.0-beta.5)
 
 Manage wallets, credits, swaps, MPP marketplace services, and your Amiko twin (identity, documents, voice, avatar, friends, feed) from the terminal. Works for both human users and AI agents running on OpenClaw.
 
@@ -210,6 +210,26 @@ amiko create media --service video --limit 5
 
 > `amiko markets image` still exists and is unchanged — it's the direct MPP pay-per-call path (pre-pay in AMIKO). Use `amiko create` for the Create Studio experience (async, charge-on-success); use `amiko markets` for raw MPP endpoints.
 
+## Chat
+
+Your conversations — **DMs and group chats** — acting **as you (the owner)**. (This is distinct from the openhermit gateway's `session_*` tools, which act as the *agent* on the agent's own sessions.)
+
+```bash
+amiko chat list                                  # all conversations (DM + group): id, peer/title, last msg, unread
+amiko chat list --limit 50 --archived            # include archived
+amiko chat read @sophie                          # recent messages with a user (by @handle)
+amiko chat read <conversationId> --limit 40      # by conversation id (from `chat list`) — works for groups too
+amiko chat send @sophie "on my way!" --yes       # send as the owner
+amiko chat send <groupConversationId> "hi all" --yes   # send to a group chat
+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`)
+```
+
+- **`<target>`** for `read`/`send` is a **conversation id** (from `chat list` — use this for groups), an **`@handle`**, or a **name** (resolved via user search; if ambiguous, the CLI lists candidates instead of guessing).
+- A DM target that doesn't exist yet is **created automatically** (find-or-create).
+- **Inline media**: `--image <pathOrUrl>` (jpg/png/webp/gif, local ≤10MB or an Amiko URL) and `--audio <pathOrUrl>` (local ≤25MB or an Amiko URL → sent as a voice note). One media block per message (image *or* audio). **Video isn't supported in chat yet.** A local file is uploaded; an Amiko URL (e.g. a generated asset from `amiko create`) attaches directly with no re-upload. (A local *audio* file is sent as a voice note, with your text as a separate message.)
+- `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.
+
 ## Amazon
 
 ```bash

package/dist/index.js

@@ -28924,6 +28924,337 @@ More available — raise --limit to see more.`));
   });
 }
 
+// src/lib/file-input.ts
+import { readFile } from "node:fs/promises";
+import { basename, extname } from "node:path";
+var MAX_BYTES = 100 * 1024 * 1024;
+var FETCH_TIMEOUT_MS = 30000;
+async function resolveFileInput(src, opts = {}) {
+  if (src === "-" || opts.stdin) {
+    const buffer2 = await readStdin();
+    const name2 = opts.hintName ?? "stdin";
+    const mime2 = opts.hintMime ?? detectMime(buffer2, name2);
+    return { buffer: buffer2, name: name2, mime: mime2, size: buffer2.length };
+  }
+  if (/^https?:\/\//i.test(src)) {
+    const buffer2 = await fetchRemote(src);
+    const urlPath = new URL(src).pathname;
+    const name2 = opts.hintName ?? (basename(urlPath) || "download");
+    const mime2 = opts.hintMime ?? detectMime(buffer2, name2);
+    return { buffer: buffer2, name: name2, mime: mime2, size: buffer2.length };
+  }
+  const buffer = await readFile(src);
+  if (buffer.length > MAX_BYTES) {
+    throw new Error(`File too large: ${buffer.length} bytes exceeds ${MAX_BYTES} byte cap.`);
+  }
+  const name = opts.hintName ?? basename(src);
+  const mime = opts.hintMime ?? detectMime(buffer, name);
+  return { buffer, name, mime, size: buffer.length };
+}
+async function readStdin() {
+  const chunks = [];
+  let total = 0;
+  for await (const chunk of process.stdin) {
+    const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    total += buf.length;
+    if (total > MAX_BYTES) {
+      throw new Error(`stdin exceeded ${MAX_BYTES} byte cap.`);
+    }
+    chunks.push(buf);
+  }
+  return Buffer.concat(chunks);
+}
+async function fetchRemote(url2) {
+  const controller = new AbortController;
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const res = await fetch(url2, { signal: controller.signal });
+    if (!res.ok) {
+      throw new Error(`Fetch ${url2} failed: ${res.status} ${res.statusText}`);
+    }
+    const len = Number(res.headers.get("content-length") || 0);
+    if (len > MAX_BYTES) {
+      throw new Error(`Remote file too large: ${len} bytes exceeds ${MAX_BYTES} byte cap.`);
+    }
+    const buf = Buffer.from(await res.arrayBuffer());
+    if (buf.length > MAX_BYTES) {
+      throw new Error(`Remote file too large: ${buf.length} bytes exceeds ${MAX_BYTES} byte cap.`);
+    }
+    return buf;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+var MAGIC = [
+  [Buffer.from([37, 80, 68, 70]), "application/pdf"],
+  [Buffer.from([137, 80, 78, 71]), "image/png"],
+  [Buffer.from([255, 216, 255]), "image/jpeg"],
+  [Buffer.from([71, 73, 70, 56]), "image/gif"],
+  [Buffer.from([82, 73, 70, 70]), "audio/wav"],
+  [Buffer.from([73, 68, 51]), "audio/mpeg"],
+  [Buffer.from([255, 251]), "audio/mpeg"],
+  [Buffer.from([80, 75, 3, 4]), "application/zip"]
+];
+var EXT_MIME = {
+  ".pdf": "application/pdf",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".txt": "text/plain",
+  ".md": "text/markdown",
+  ".json": "application/json",
+  ".wav": "audio/wav",
+  ".mp3": "audio/mpeg",
+  ".m4a": "audio/mp4",
+  ".ogg": "audio/ogg",
+  ".zip": "application/zip"
+};
+function detectMime(buffer, name) {
+  for (const [sig, mime] of MAGIC) {
+    if (buffer.length >= sig.length && buffer.subarray(0, sig.length).equals(sig)) {
+      return mime;
+    }
+  }
+  const ext = extname(name).toLowerCase();
+  return EXT_MIME[ext] ?? "application/octet-stream";
+}
+
+// src/commands/chat.ts
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function authOrExit() {
+  try {
+    return requireAuth();
+  } catch (e5) {
+    console.error(error(e5 instanceof Error ? e5.message : "auth failed"));
+    process.exit(1);
+  }
+}
+function convLabel(conv, selfUserId) {
+  if (conv.title)
+    return conv.title;
+  const others = (conv.participants ?? []).filter((p) => !(p.participant_type === "user" && p.participant_id === selfUserId)).map((p) => p.user?.name ?? p.twin?.name ?? p.participant_id.slice(0, 8)).filter((n) => !!n);
+  return others.length ? others.join(", ") : "(conversation)";
+}
+async function findOrCreateDm(auth, userId) {
+  const data = await amikoWebFetch(auth, "/api/conversations", {
+    method: "POST",
+    body: {
+      participant_ids: [userId],
+      participant_types: ["user"],
+      conversation_type: "direct"
+    },
+    timeoutMs: 20000
+  });
+  const id = data.conversation?.id;
+  if (!id)
+    throw new Error("Could not open a conversation with that user.");
+  return id;
+}
+async function resolveConversation(auth, target) {
+  const t = target.trim();
+  if (UUID_RE.test(t))
+    return t;
+  if (t.startsWith("@")) {
+    const handle = t.slice(1);
+    const prof = await amikoWebFetch(auth, `/api/users/${encodeURIComponent(handle)}`, { timeoutMs: 15000 });
+    if (!prof.user?.id)
+      throw new Error(`No user @${handle}.`);
+    return findOrCreateDm(auth, prof.user.id);
+  }
+  const res = await amikoWebFetch(auth, "/api/search", {
+    query: { q: t, type: "people", limit: 8 },
+    timeoutMs: 15000
+  });
+  const users = res.users ?? [];
+  if (users.length === 0) {
+    throw new Error(`No user matching "${t}". Use an exact @handle, or a conversation id from \`amiko chat list\`.`);
+  }
+  if (users.length > 1) {
+    const names = users.map((u) => `${u.name ?? "?"} (@${u.handle ?? u.id.slice(0, 8)})`).join(", ");
+    throw new Error(`"${t}" is ambiguous — matches: ${names}. Use an exact @handle or a conversation id.`);
+  }
+  return findOrCreateDm(auth, users[0].id);
+}
+var HTTPS_RE = /^https:\/\//i;
+var CHAT_IMAGE_MIME = new Set([
+  "image/jpeg",
+  "image/jpg",
+  "image/png",
+  "image/webp",
+  "image/gif"
+]);
+var MAX_CHAT_IMAGE = 10 * 1024 * 1024;
+var MAX_CHAT_AUDIO = 25 * 1024 * 1024;
+function urlName(url2) {
+  try {
+    const p = new URL(url2).pathname.split("/").pop();
+    return p && p.length ? decodeURIComponent(p) : "attachment";
+  } catch {
+    return "attachment";
+  }
+}
+async function uploadChatImage(auth, convId, path2) {
+  const f = await resolveFileInput(path2);
+  if (!CHAT_IMAGE_MIME.has(f.mime)) {
+    throw new Error(`"${path2}" is not a supported image (detected ${f.mime}). Allowed: JPEG, PNG, WebP, GIF.`);
+  }
+  if (f.size > MAX_CHAT_IMAGE) {
+    throw new Error(`"${path2}" exceeds the 10MB chat image limit.`);
+  }
+  const form = new FormData;
+  form.set("file", new Blob([new Uint8Array(f.buffer)], { type: f.mime }), f.name);
+  const data = await amikoWebFetch(auth, `/api/conversations/${encodeURIComponent(convId)}/images/upload`, { method: "POST", multipart: form, timeoutMs: 60000 });
+  if (!data.image?.url)
+    throw new Error("Image upload returned no URL.");
+  return { url: data.image.url, name: data.image.name ?? f.name };
+}
+async function uploadChatVoice(auth, convId, path2) {
+  const f = await resolveFileInput(path2);
+  if (!f.mime.startsWith("audio/")) {
+    throw new Error(`"${path2}" is not an audio file (detected ${f.mime}).`);
+  }
+  if (f.size > MAX_CHAT_AUDIO) {
+    throw new Error(`"${path2}" exceeds the 25MB chat audio limit.`);
+  }
+  const form = new FormData;
+  form.set("audio", new Blob([new Uint8Array(f.buffer)], { type: f.mime }), f.name);
+  form.set("duration", "0");
+  await amikoWebFetch(auth, `/api/conversations/${encodeURIComponent(convId)}/audio/upload`, { method: "POST", multipart: form, timeoutMs: 120000 });
+}
+function registerChatCommand(chat) {
+  chat.command("list").description("List your conversations (DMs and group chats)").option("--limit <n>", "Max conversations", "30").option("--archived", "Include archived conversations").option("--raw", "Output raw JSON").action(async (opts) => {
+    const auth = authOrExit();
+    let data;
+    try {
+      data = await amikoWebFetch(auth, "/api/conversations", {
+        query: {
+          limit: opts.limit,
+          ...opts.archived ? { archived: "all" } : {}
+        },
+        timeoutMs: 20000
+      });
+    } catch (e5) {
+      console.error(error(e5 instanceof Error ? e5.message : "Failed to list conversations"));
+      process.exit(1);
+    }
+    if (opts.raw) {
+      console.log(JSON.stringify(data, null, 2));
+      return;
+    }
+    const convs = data.conversations ?? [];
+    if (convs.length === 0) {
+      console.log(dim("No conversations."));
+      return;
+    }
+    console.log(heading(`Conversations (${convs.length})
+`));
+    for (const c of convs) {
+      const kind = c.conversation_type === "direct" ? "DM" : c.conversation_type;
+      const unread = c.unread_count ? `  (${c.unread_count} unread)` : "";
+      console.log(label(`[${kind}] ${convLabel(c, auth.userId)}`, dim(c.id)));
+      if (c.last_message?.content) {
+        const who = c.last_message.name ? `${c.last_message.name}: ` : "";
+        console.log(dim(`  ${who}${c.last_message.content.slice(0, 80)}`));
+      }
+      if (unread)
+        console.log(dim(` ${unread.trim()}`));
+    }
+  });
+  chat.command("read <target>").description("Read recent messages in a conversation (conversation id, @handle, or name)").option("--limit <n>", "Max messages", "20").option("--raw", "Output raw JSON").action(async (target, opts) => {
+    const auth = authOrExit();
+    let convId;
+    try {
+      convId = await resolveConversation(auth, target);
+    } 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)}/messages`, { query: { limit: opts.limit }, timeoutMs: 20000 });
+    } catch (e5) {
+      console.error(error(e5 instanceof Error ? e5.message : "Failed to read messages"));
+      process.exit(1);
+    }
+    if (opts.raw) {
+      console.log(JSON.stringify(data, null, 2));
+      return;
+    }
+    const msgs = (data.messages ?? []).slice().reverse();
+    if (msgs.length === 0) {
+      console.log(dim("No messages."));
+      return;
+    }
+    console.log(heading(`Messages (${msgs.length})
+`));
+    for (const m of msgs) {
+      const who = m.sender?.name ?? 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, m.content));
+      if (when)
+        console.log(dim(`  ${when}`));
+    }
+  });
+  chat.command("send <target> <message>").description("Send a message as yourself (the owner) to a conversation (id, @handle, or name)").option("--image <pathOrUrl>", "Attach an image: local file (jpg/png/webp/gif, ≤10MB) or an Amiko URL (e.g. from `amiko create`)").option("--audio <pathOrUrl>", "Attach audio as a voice note: local file (≤25MB) or an Amiko URL").option("--yes", "Skip the confirmation (required in non-interactive shells)").option("--raw", "Output raw JSON").action(async (target, message, opts) => {
+    const auth = authOrExit();
+    if (opts.image && opts.audio) {
+      console.error(error("Attach either --image or --audio, not both (one media block per message)."));
+      process.exit(1);
+    }
+    let convId;
+    try {
+      convId = await resolveConversation(auth, target);
+    } catch (e5) {
+      console.error(error(e5 instanceof Error ? e5.message : "Could not resolve target"));
+      process.exit(1);
+    }
+    const media = opts.image ? `image ${opts.image}` : opts.audio ? `audio ${opts.audio}` : "";
+    await requireApproval({
+      cost: "no charge — sends a message as you (the owner)",
+      summary: `Send to ${target}${media ? ` [+${media}]` : ""}: ${message.slice(0, 80)}${message.length > 80 ? "…" : ""}`,
+      yes: opts.yes,
+      commandExample: `amiko chat send ${JSON.stringify(target)} ${JSON.stringify(message)}`
+    });
+    const messagesPath = `/api/conversations/${encodeURIComponent(convId)}/messages`;
+    const post = (body) => amikoWebFetch(auth, messagesPath, {
+      method: "POST",
+      body,
+      timeoutMs: 20000
+    });
+    let data;
+    try {
+      if (opts.image) {
+        const img = HTTPS_RE.test(opts.image) ? { url: opts.image, name: urlName(opts.image) } : await uploadChatImage(auth, convId, opts.image);
+        data = await post({ content: message, metadata: { images: [img] } });
+      } else if (opts.audio) {
+        if (HTTPS_RE.test(opts.audio)) {
+          data = await post({
+            content: message,
+            message_type: "voice",
+            metadata: { audioUrl: opts.audio }
+          });
+        } else {
+          data = await post({ content: message });
+          await uploadChatVoice(auth, convId, opts.audio);
+        }
+      } else {
+        data = await post({ content: message });
+      }
+    } catch (e5) {
+      console.error(error(e5 instanceof Error ? e5.message : "Send failed"));
+      process.exit(1);
+    }
+    if (opts.raw) {
+      console.log(JSON.stringify(data, null, 2));
+      return;
+    }
+    const what = opts.image ? "Message + image sent" : opts.audio ? "Message + voice note sent" : "Message sent";
+    console.log(success(what) + dim(` (conversation ${convId.slice(0, 8)}…)`));
+  });
+}
+
 // src/commands/amazon.ts
 var TREASURY3 = "FPiZAf3jEnNfCwfvbv46jdPfHbmSepD4Q6iHiLJDQXvb";
 async function payAmiko(auth, wallet, amount2) {
@@ -29474,105 +29805,6 @@ function registerTwinCommand(program2) {
 // src/commands/drive.ts
 import { writeFile } from "node:fs/promises";
 import { basename as basename2, resolve as resolvePath } from "node:path";
-
-// src/lib/file-input.ts
-import { readFile } from "node:fs/promises";
-import { basename, extname } from "node:path";
-var MAX_BYTES = 100 * 1024 * 1024;
-var FETCH_TIMEOUT_MS = 30000;
-async function resolveFileInput(src, opts = {}) {
-  if (src === "-" || opts.stdin) {
-    const buffer2 = await readStdin();
-    const name2 = opts.hintName ?? "stdin";
-    const mime2 = opts.hintMime ?? detectMime(buffer2, name2);
-    return { buffer: buffer2, name: name2, mime: mime2, size: buffer2.length };
-  }
-  if (/^https?:\/\//i.test(src)) {
-    const buffer2 = await fetchRemote(src);
-    const urlPath = new URL(src).pathname;
-    const name2 = opts.hintName ?? (basename(urlPath) || "download");
-    const mime2 = opts.hintMime ?? detectMime(buffer2, name2);
-    return { buffer: buffer2, name: name2, mime: mime2, size: buffer2.length };
-  }
-  const buffer = await readFile(src);
-  if (buffer.length > MAX_BYTES) {
-    throw new Error(`File too large: ${buffer.length} bytes exceeds ${MAX_BYTES} byte cap.`);
-  }
-  const name = opts.hintName ?? basename(src);
-  const mime = opts.hintMime ?? detectMime(buffer, name);
-  return { buffer, name, mime, size: buffer.length };
-}
-async function readStdin() {
-  const chunks = [];
-  let total = 0;
-  for await (const chunk of process.stdin) {
-    const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-    total += buf.length;
-    if (total > MAX_BYTES) {
-      throw new Error(`stdin exceeded ${MAX_BYTES} byte cap.`);
-    }
-    chunks.push(buf);
-  }
-  return Buffer.concat(chunks);
-}
-async function fetchRemote(url2) {
-  const controller = new AbortController;
-  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
-  try {
-    const res = await fetch(url2, { signal: controller.signal });
-    if (!res.ok) {
-      throw new Error(`Fetch ${url2} failed: ${res.status} ${res.statusText}`);
-    }
-    const len = Number(res.headers.get("content-length") || 0);
-    if (len > MAX_BYTES) {
-      throw new Error(`Remote file too large: ${len} bytes exceeds ${MAX_BYTES} byte cap.`);
-    }
-    const buf = Buffer.from(await res.arrayBuffer());
-    if (buf.length > MAX_BYTES) {
-      throw new Error(`Remote file too large: ${buf.length} bytes exceeds ${MAX_BYTES} byte cap.`);
-    }
-    return buf;
-  } finally {
-    clearTimeout(timer);
-  }
-}
-var MAGIC = [
-  [Buffer.from([37, 80, 68, 70]), "application/pdf"],
-  [Buffer.from([137, 80, 78, 71]), "image/png"],
-  [Buffer.from([255, 216, 255]), "image/jpeg"],
-  [Buffer.from([71, 73, 70, 56]), "image/gif"],
-  [Buffer.from([82, 73, 70, 70]), "audio/wav"],
-  [Buffer.from([73, 68, 51]), "audio/mpeg"],
-  [Buffer.from([255, 251]), "audio/mpeg"],
-  [Buffer.from([80, 75, 3, 4]), "application/zip"]
-];
-var EXT_MIME = {
-  ".pdf": "application/pdf",
-  ".png": "image/png",
-  ".jpg": "image/jpeg",
-  ".jpeg": "image/jpeg",
-  ".gif": "image/gif",
-  ".webp": "image/webp",
-  ".txt": "text/plain",
-  ".md": "text/markdown",
-  ".json": "application/json",
-  ".wav": "audio/wav",
-  ".mp3": "audio/mpeg",
-  ".m4a": "audio/mp4",
-  ".ogg": "audio/ogg",
-  ".zip": "application/zip"
-};
-function detectMime(buffer, name) {
-  for (const [sig, mime] of MAGIC) {
-    if (buffer.length >= sig.length && buffer.subarray(0, sig.length).equals(sig)) {
-      return mime;
-    }
-  }
-  const ext = extname(name).toLowerCase();
-  return EXT_MIME[ext] ?? "application/octet-stream";
-}
-
-// src/commands/drive.ts
 function fmtBytes(n) {
   if (!n || n <= 0)
     return "-";
@@ -31806,6 +32038,7 @@ var program2 = new Command;
 program2.name("amiko").description("Amiko CLI — swap tokens, manage credits, bridge cross-chain, and call marketplace services").version(PKG_VERSION);
 var markets = program2.command("markets").description("MPP marketplace — discover and call paid AMIKO services");
 var create2 = program2.command("create").description("Create Studio — generate images, video, speech, music, and SFX (charged on success)");
+var chat = program2.command("chat").description("Your conversations (DMs + group chats) as the owner — list, read, send");
 var wallets = program2.command("wallets").description("Manage twin wallets — list, swap, bridge");
 var twin = program2.command("twin").description("Update twin identity (name, description, visibility)");
 var drive = program2.command("drive").alias("docs").description("Manage twin drive — upload/download/search files, organise into folders");
@@ -31820,6 +32053,7 @@ registerCreditsCommand(program2);
 registerSearchCommand(markets);
 registerImageCommand(markets);
 registerCreateCommand(create2);
+registerChatCommand(chat);
 registerAmazonCommand(markets);
 registerWalletsCreateCommand(wallets);
 registerWalletsListCommand(wallets);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heyamiko/amiko-cli",
-  "version": "0.12.0-beta.3",
+  "version": "0.12.0-beta.5",
   "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, posts, comments, feed). Auth is automatic when run from the agent's workspace folder; payments are platform-custodied (no keys on disk). DMs / chat sessions are NOT in this CLI — use the openhermit gateway's built-in session_list / session_read tools for both local sessions and platform DMs. Use this skill whenever the user asks about their Amiko notifications, 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, posts, comments, 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 AS the owner, 人对人); 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"]}}}
 ---
@@ -41,13 +41,13 @@ The CLI is installed globally and is pre-authenticated when you're inside your w
 
 ## Command groups
 
-Discover everything via `amiko --help`. Groups: `markets` (paid MPP services), `create` (Create Studio — async media generation, charged on success), `wallets`, `credits`, `twin`, `drive` (files / folders / RAG; `docs` is an alias), `voice`, `avatar`, `friends`, `users`, `post`, `review`, `feed`, `notifications`, `memory`, plus the top-level `accounts`, `info`, `config`, `update`. All twin-scoped commands accept `--twin <id>`. Most commands support `--json`.
+Discover everything via `amiko --help`. Groups: `markets` (paid MPP services), `create` (Create Studio — async media generation, charged on success), `chat` (owner's DMs + group chats), `wallets`, `credits`, `twin`, `drive` (files / folders / RAG; `docs` is an alias), `voice`, `avatar`, `friends`, `users`, `post`, `review`, `feed`, `notifications`, `memory`, plus the top-level `accounts`, `info`, `config`, `update`. All twin-scoped commands accept `--twin <id>`. Most commands support `--json`.
 
-> **DMs / chat sessions are NOT in this CLI.** Use the openhermit gateway's built-in `session_list` / `session_read` tools for both the agent's local sessions and platform DMs with other users. The previous `amiko conversation` namespace was removed in 0.10.1-beta.4.
+> **Two chat surfaces — pick by identity.** `amiko chat` is the **owner's** DMs and group chats, acting **as the owner** (list / read / send). The openhermit gateway's `session_list` / `session_send` are the **agent's own** sessions, acting **as the agent**. "Send a message to Sophie for me" → `amiko chat send`; "have the twin reply as itself" → gateway. (The old `amiko conversation` namespace was removed in 0.10.1-beta.4; `amiko chat` is its owner-identity replacement.)
 
 ## 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 *`, `credits topup`, `wallets swap send`, `wallets bridge send`, `wallets transfer` (and destructive ops like `twin update --public`, `drive delete`, `friends remove`, `friends reports request`, `avatar update`, `voice reset`, `review reject`) unless `--yes` is passed. The refusal prints the cost and the re-run command. **Quote the cost, get explicit approval, THEN append `--yes`.**
+1. **Every paid / value-moving command is hard-gated on `--yes` in a non-interactive shell.** The CLI refuses to run `markets *`, `create *`, `chat send`, `credits topup`, `wallets swap send`, `wallets bridge send`, `wallets transfer` (and destructive ops like `twin update --public`, `drive delete`, `friends remove`, `friends reports request`, `avatar update`, `voice reset`, `review reject`) unless `--yes` is passed. The refusal prints the cost and the re-run command. **Quote the cost, get explicit approval, THEN append `--yes`.**
 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`.
@@ -96,6 +96,16 @@ All paid markets commands auto-select the twin's active Solana wallet (see `--wa
 
 `amiko create <image|video|tts|music|sfx>` is the CLI half of the platform Create Studio. It generates through Amiko's own authenticated endpoints (not raw MPP), runs **async**, and is **charged on success** from the twin's custodial wallet — a failed or timed-out generation is **never billed**, and there is no pre-pay. **The command returns immediately** with a `jobId` and `status: PENDING` — it does NOT block for the whole generation (so you're not held for 60s–9min). It prints how to check + a rough ETA. **Poll for the result** with `amiko create status <jobId>` (re-query that job, ~24h) — wait roughly: image ~15–60s, video ~2–9min, music ~30–120s, tts/sfx ~5–20s. Or `amiko create media` (list recent generations; `--service`/`--limit`/`--raw`). Result is a permanent Supabase Storage URL. (Pass `--wait` only if you deliberately want the command to block until done.) `--token <AMIKO|USDC|USDT|SOL>` selects the charge token (default auto, AMIKO-first). Prefer `create` over `markets image` for media generation — it doesn't lose money on timeouts. `markets image` remains the raw MPP pre-pay path.
 
+## Chat — behavior notes
+
+`amiko chat` is the **owner's** conversations, acting **as the owner** (人对人) — NOT the agent's own sessions (those are the gateway's `session_*`, as the agent).
+
+- `amiko chat list` — all conversations, **DMs and group chats** (id, type, peer/title, last message, unread).
+- `amiko chat read <target>` — recent messages. `<target>` = a conversation id (from `list`), an `@handle`, or a name.
+- `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). For **group chats**, use the conversation id from `list`; for a **DM**, an `@handle`/name resolves + finds-or-creates the DM.
+- **Inline media**: `--image <pathOrUrl>` (jpg/png/webp/gif, local ≤10MB or an Amiko URL — e.g. a generated image) and `--audio <pathOrUrl>` (local ≤25MB or an Amiko URL → sent as a voice note). One media block per message (image XOR audio). **Video is 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.
+- Name resolution goes through user search; if ambiguous it lists candidates — don't blind-send. Server enforces who you're allowed to message (friend/participant rules); surface its error, don't retry.
+
 ## Drive (files & folders)
 
 The drive is **shared between the user and the agent** — anything either side uploads is visible to both. Uploads kick off an async RAG-parsing job (~seconds to minutes); list/search/rename/move/delete all work regardless of parsing status. `drive search` and `drive list --search` hit filename, title, description, and the parsed content body (once parsing completes). Prefer reading parsed content via the agent workspace sync over polling `drive status` from long-running tasks. `amiko docs` is kept as an alias for backward compat.
@@ -133,7 +143,7 @@ Workflow: start with `friends matches --limit 20 --json`; narrow with `--dimensi
 
 > **Default platform = Amiko.** When the owner asks about notifications **without naming a platform**, assume Amiko and answer with `amiko notifications`. Only ask if they explicitly mention a non-Amiko channel.
 >
-> **DMs / chat history are handled by the openhermit gateway**, not the CLI. For "did X message me?" / "check my chat with Y", use the built-in `session_list` / `session_read` tools — they cover both the agent's local sessions and platform DMs in the unified gateway view.
+> **Owner DMs / group chats: `amiko chat`.** For "did X message me?" / "what did Sophie and I say?" / "message Y for me", use `amiko chat list` / `amiko chat read <who>` / `amiko chat send <who> "…"` — these act **as the owner** (人对人). The gateway's `session_*` tools are the **agent's own** sessions (as the agent), a separate surface (see Chat behavior notes).
 
 Platform notifications cover friend requests, mentions, system alerts, and post-related events.