makaron-cli 0.7.6 → 0.7.8

package/README.md

@@ -61,14 +61,14 @@ Share the `claim_url` with a human. They log in and the API key gets linked to t
 # One-shot: create project + upload image + submit prompt — all in one command
 RUN_ID=$(npx makaron-cli chat --project auto --image photo.jpg -b "make it cinematic and create a 5s video")
 
-# Watch until all artifacts are ready
-npx makaron-cli responses watch $RUN_ID --jsonl
+# Wait for the final customer-ready result
+npx makaron-cli responses get $RUN_ID --wait --json
 ```
 
 Or with an existing project:
 ```bash
 RUN_ID=$(npx makaron-cli chat --project $PROJECT_ID -b "make a 5s video")
-npx makaron-cli responses watch $RUN_ID --jsonl
+npx makaron-cli responses get $RUN_ID --wait --json
 ```
 
 ## Primary: `chat` (Agent-driven creative work)
@@ -120,7 +120,7 @@ Use `chat --project <id|auto> --video ...` for any project/timeline video work.
 npx makaron-cli responses get <runId> --json
 ```
 
-### Watch until done (streaming events)
+### Advanced: stream incremental events
 
 ```bash
 npx makaron-cli responses watch <runId> --jsonl
@@ -134,6 +134,37 @@ Outputs one JSON per line as artifacts appear:
 {"event":"done","status":"completed"}
 ```
 
+### Dialogue events for external Agents
+
+Use this when another Agent needs to read what Makaron said, detect approval requirements, and relay artifacts without inventing customer-service wording.
+
+```bash
+npx makaron-cli responses events <runId> --jsonl
+```
+
+Events use only three factual types:
+
+```json
+{"type":"message","id":"msg_1","runId":"run_xxx","seq":1,"text":"Makaron original message","requires_approval":true,"approval_options":["approve","revise","ask_user","continue"]}
+{"type":"approval","messageId":"msg_1","choice":"approve","status":"recorded"}
+{"type":"artifact","kind":"image","status":"completed","url":"https://..."}
+```
+
+If a message has `requires_approval: true`, the external Agent must record an approval before continuing to wait for artifacts or claiming completion:
+
+```bash
+npx makaron-cli responses approve msg_1 --run <runId> --note "Proceed."
+npx makaron-cli responses revise msg_1 --run <runId> "make it softer"
+npx makaron-cli responses ask-user msg_1 --run <runId>
+npx makaron-cli responses continue msg_1 --run <runId>
+```
+
+Wrappers can enforce this with:
+
+```bash
+npx makaron-cli responses events <runId> --jsonl --fail-on-unapproved
+```
+
 ### Extract specific results
 
 ```bash
@@ -278,38 +309,33 @@ RUN_ID=$(npx makaron-cli chat --project auto --image photo.jpg -b "make it cinem
 PROJECT_URL=$(npx makaron-cli responses get $RUN_ID --pick project_url)
 send_message "Project created: $PROJECT_URL"
 
-# 4. Watch and send each artifact as it appears
-npx makaron-cli responses watch $RUN_ID --jsonl | while read -r line; do
-  EVENT=$(echo "$line" | jq -r '.event')
-  TYPE=$(echo "$line" | jq -r '.item.type // empty')
-  URL=$(echo "$line" | jq -r '.item.url // empty')
-  STATUS=$(echo "$line" | jq -r '.item.status // empty')
-
-  if [ "$EVENT" = "output.added" ] && [ "$TYPE" = "image" ]; then
-    # Send image immediately as media (not just link)
-    send_image "$URL"
-  elif [ "$EVENT" = "output.updated" ] && [ "$TYPE" = "video" ] && [ "$STATUS" = "completed" ]; then
-    # Video ready — send as media
-    send_video "$URL"
-  elif [ "$EVENT" = "done" ]; then
-    send_message "All done!"
-  fi
+# 4. Wait for the final customer-ready result
+RESULT=$(npx makaron-cli responses get $RUN_ID --wait --json)
+IMAGE_URLS=$(echo "$RESULT" | jq -r '[.result.images[]?.imageUrl, .output[]? | select(.type == "image") | .url] | map(select(. != null)) | unique | .[]')
+VIDEO_URLS=$(echo "$RESULT" | jq -r '[.result.videos[]?.videoUrl, .output[]? | select(.type == "video") | .url] | map(select(. != null)) | unique | .[]')
+
+for URL in $IMAGE_URLS; do
+  send_image "$URL"
+done
+for URL in $VIDEO_URLS; do
+  send_video "$URL"
 done
+send_message "All done!"
 ```
 
 **Key principles for service agents:**
-- **Proactive, not reactive**: Don't wait for the full run to finish. Send progress messages and artifacts as they appear.
+- **Proactive, not silent**: Acknowledge immediately, send the project link early, then send the final customer-ready media when the run completes.
 - **Media over links**: When possible, send images/videos as native media in the chat (download URL and upload as attachment), not just paste the URL.
 - **Immediate acknowledgment**: Reply within 1 second of receiving user request. Don't make users wait for project creation.
 - **Project link early**: Send the project URL right after creation so users can check anytime.
-- **Stream artifacts**: Use `watch --jsonl` to push each artifact the moment it's ready. An image at 15s should reach the user at 15s, not after the video finishes at 5 minutes.
+- **Use `get --wait --json` as the default service path**: reserve `watch --jsonl` for advanced streaming or debugging integrations that explicitly need incremental events.
 
 ## Important Notes
 
 - One project = one conversation thread. All history is preserved.
 - One run at a time per project. New message interrupts previous run.
 - Multi-image: `create --image a.jpg --image b.jpg` or `chat --image ref.jpg`.
-- Videos take 2-5 minutes to render. Use `watch` to get URL when ready.
+- Videos take 2-5 minutes to render. Use `responses get <runId> --wait --json` for the default customer-service path.
 - Music takes ~60 seconds. Appears in output when done.
 - Images are typically ready in 15-30 seconds.
 - stdout is always machine-readable JSON/text. Human-friendly logs go to stderr.

package/SKILL.md

@@ -50,14 +50,14 @@ Verify: `npx makaron-cli list` should show projects.
 # One-shot: create project + upload image + submit prompt — all in one command
 RUN_ID=$(npx makaron-cli chat --project auto --image photo.jpg -b "make it cinematic and create a 5s video")
 
-# Watch until all artifacts are ready
-npx makaron-cli responses watch $RUN_ID --jsonl
+# Wait for the final customer-ready result
+npx makaron-cli responses get $RUN_ID --wait --json
 ```
 
 Or with an existing project:
 ```bash
 RUN_ID=$(npx makaron-cli chat --project $PROJECT_ID -b "make a 5s video")
-npx makaron-cli responses watch $RUN_ID --jsonl
+npx makaron-cli responses get $RUN_ID --wait --json
 ```
 
 ## Primary: `chat` (Agent-driven creative work)
@@ -112,7 +112,7 @@ Use `chat --project <id|auto> --video ...` for any project/timeline video work.
 npx makaron-cli responses get <runId> --json
 ```
 
-### Watch until done (streaming events)
+### Advanced: stream incremental events
 
 ```bash
 npx makaron-cli responses watch <runId> --jsonl
@@ -126,6 +126,37 @@ Outputs one JSON per line as artifacts appear:
 {"event":"done","status":"completed"}
 ```
 
+### Dialogue events for external Agents
+
+Use this when another Agent needs to read what Makaron said, detect approval requirements, and relay artifacts without inventing customer-service wording.
+
+```bash
+npx makaron-cli responses events <runId> --jsonl
+```
+
+Events use only three factual types:
+
+```json
+{"type":"message","id":"msg_1","runId":"run_xxx","seq":1,"text":"Makaron original message","requires_approval":true,"approval_options":["approve","revise","ask_user","continue"]}
+{"type":"approval","messageId":"msg_1","choice":"approve","status":"recorded"}
+{"type":"artifact","kind":"image","status":"completed","url":"https://..."}
+```
+
+If a message has `requires_approval: true`, the external Agent must record an approval before continuing to wait for artifacts or claiming completion:
+
+```bash
+npx makaron-cli responses approve msg_1 --run <runId> --note "Proceed."
+npx makaron-cli responses revise msg_1 --run <runId> "make it softer"
+npx makaron-cli responses ask-user msg_1 --run <runId>
+npx makaron-cli responses continue msg_1 --run <runId>
+```
+
+Wrappers can enforce this with:
+
+```bash
+npx makaron-cli responses events <runId> --jsonl --fail-on-unapproved
+```
+
 ### Extract specific results
 
 ```bash
@@ -267,38 +298,33 @@ RUN_ID=$(npx makaron-cli chat --project auto --image photo.jpg -b "make it cinem
 PROJECT_URL=$(npx makaron-cli responses get $RUN_ID --pick project_url)
 send_message "Project created: $PROJECT_URL"
 
-# 4. Watch and send each artifact as it appears
-npx makaron-cli responses watch $RUN_ID --jsonl | while read -r line; do
-  EVENT=$(echo "$line" | jq -r '.event')
-  TYPE=$(echo "$line" | jq -r '.item.type // empty')
-  URL=$(echo "$line" | jq -r '.item.url // empty')
-  STATUS=$(echo "$line" | jq -r '.item.status // empty')
-
-  if [ "$EVENT" = "output.added" ] && [ "$TYPE" = "image" ]; then
-    # Send image immediately as media (not just link)
-    send_image "$URL"
-  elif [ "$EVENT" = "output.updated" ] && [ "$TYPE" = "video" ] && [ "$STATUS" = "completed" ]; then
-    # Video ready — send as media
-    send_video "$URL"
-  elif [ "$EVENT" = "done" ]; then
-    send_message "All done!"
-  fi
+# 4. Wait for the final customer-ready result
+RESULT=$(npx makaron-cli responses get $RUN_ID --wait --json)
+IMAGE_URLS=$(echo "$RESULT" | jq -r '[.result.images[]?.imageUrl, .output[]? | select(.type == "image") | .url] | map(select(. != null)) | unique | .[]')
+VIDEO_URLS=$(echo "$RESULT" | jq -r '[.result.videos[]?.videoUrl, .output[]? | select(.type == "video") | .url] | map(select(. != null)) | unique | .[]')
+
+for URL in $IMAGE_URLS; do
+  send_image "$URL"
+done
+for URL in $VIDEO_URLS; do
+  send_video "$URL"
 done
+send_message "All done!"
 ```
 
 **Key principles for service agents:**
-- **Proactive, not reactive**: Don't wait for the full run to finish. Send progress messages and artifacts as they appear.
+- **Proactive, not silent**: Acknowledge immediately, send the project link early, then send the final customer-ready media when the run completes.
 - **Media over links**: When possible, send images/videos as native media in the chat (download URL and upload as attachment), not just paste the URL.
 - **Immediate acknowledgment**: Reply within 1 second of receiving user request. Don't make users wait for project creation.
 - **Project link early**: Send the project URL right after creation so users can check anytime.
-- **Stream artifacts**: Use `watch --jsonl` to push each artifact the moment it's ready. An image at 15s should reach the user at 15s, not after the video finishes at 5 minutes.
+- **Use `get --wait --json` as the default service path**: reserve `watch --jsonl` for advanced streaming or debugging integrations that explicitly need incremental events.
 
 ## Important Notes
 
 - One project = one conversation thread. All history is preserved.
 - One run at a time per project. New message interrupts previous run.
 - Multi-image: `create --image a.jpg --image b.jpg` or `chat --image ref.jpg`.
-- Videos take 2-5 minutes to render. Use `watch` to get URL when ready.
+- Videos take 2-5 minutes to render. Use `responses get <runId> --wait --json` for the default customer-service path.
 - Music takes ~60 seconds. Appears in output when done.
 - Images are typically ready in 15-30 seconds.
 - stdout is always machine-readable JSON/text. Human-friendly logs go to stderr.

package/bin/makaron.mjs

@@ -19,6 +19,7 @@ import { execFileSync } from 'child_process';
 // ─── Config ──────────────────────────────────────────────────────────────────
 
 const AUTH_FILE = path.join(process.env.HOME || '~', '.makaron', 'auth.json');
+const APPROVALS_FILE = path.join(path.dirname(AUTH_FILE), 'approvals.json');
 const DEFAULT_URL = 'https://www.makaron.app';
 const BASE_URL = process.env.MAKARON_URL || DEFAULT_URL;
 const APP_URL = process.env.MAKARON_APP_URL || DEFAULT_URL;
@@ -32,6 +33,15 @@ const MAX_VIDEO_DURATION = 15;
 const MAX_VIDEO_DURATION_TOLERANCE = 0.5;
 const MAX_VIDEO_FRAME_PIXELS = 2_086_876;
 
+function getCliVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf-8'));
+    return pkg.version || '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
 function formatSeconds(seconds) {
   if (!Number.isFinite(seconds)) return String(seconds);
   return Number.isInteger(seconds) ? String(seconds) : seconds.toFixed(1).replace(/\.0$/, '');
@@ -53,6 +63,20 @@ function saveAuth(data) {
   fs.writeFileSync(AUTH_FILE, JSON.stringify(data, null, 2));
 }
 
+function loadApprovals() {
+  try {
+    return JSON.parse(fs.readFileSync(APPROVALS_FILE, 'utf-8'));
+  } catch {
+    return [];
+  }
+}
+
+function saveApprovals(approvals) {
+  const dir = path.dirname(APPROVALS_FILE);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(APPROVALS_FILE, JSON.stringify(approvals, null, 2));
+}
+
 function buildCookie(tokenJson) {
   const url = tokenJson._supabaseUrl || SUPABASE_URL;
   const ref = url.match(/\/\/([^.]+)\./)?.[1] || '';
@@ -409,7 +433,7 @@ function applyPick(data, field) {
     case 'design_urls': return (data.output || []).filter(o => o.type === 'design' && o.url).map(o => o.url);
     case 'first_music_url': return data.output?.find(o => o.type === 'music' && o.url)?.url || null;
     case 'music_urls': return (data.output || []).filter(o => o.type === 'music' && o.url).map(o => o.url);
-    case 'project_url': return data.project_url || null;
+    case 'project_url': return data.project_url || data.projectUrl || null;
     case 'output': return data.output || [];
     case 'text': return data.output?.find(o => o.type === 'text')?.content || null;
     case 'status': return data.status;
@@ -417,6 +441,157 @@ function applyPick(data, field) {
   }
 }
 
+// ─── Dialogue Events (message / approval / artifact) ─────────────────────────
+
+function stableEventId(prefix, runId, seq, fallback) {
+  return fallback || `${prefix}_${runId}_${seq ?? Date.now()}`;
+}
+
+function normalizeDialogueMessage(runId, projectId, ev) {
+  const data = ev.data || ev;
+  const text = data.text || data.message || data.content || data.statusText || '';
+  if (!text && ev.type !== 'tool_call') return null;
+  const requiresApproval = Boolean(data.requires_approval || data.requiresApproval || data.action_required || data.actionRequired);
+  const message = {
+    type: 'message',
+    id: stableEventId('msg', runId, ev.seq, data.id || ev.id),
+    runId,
+    projectId,
+    seq: ev.seq,
+    status: data.status || undefined,
+    text: text || `${data.tool || 'tool_call'}${data.input?.description ? `: ${data.input.description}` : ''}`,
+  };
+  if (ev.type) message.source_type = ev.type;
+  if (requiresApproval) {
+    message.requires_approval = true;
+    message.approval_options = data.approval_options || data.approvalOptions || ['approve', 'revise', 'ask_user', 'continue'];
+  }
+  if (data.proposal) message.proposal = data.proposal;
+  return message;
+}
+
+function normalizeDialogueArtifact(runId, projectId, item, seq) {
+  if (!item) return null;
+  const kind = item.type || item.kind || (item.imageUrl ? 'image' : item.videoUrl ? 'video' : undefined);
+  if (!kind) return null;
+  const artifact = {
+    type: 'artifact',
+    id: stableEventId('artifact', runId, seq, item.id || item.snapshotId || item.taskId),
+    runId,
+    projectId,
+    seq,
+    kind,
+    status: item.status || (item.url || item.imageUrl || item.videoUrl || item.audioUrl ? 'completed' : 'running'),
+  };
+  const url = item.url || item.imageUrl || item.videoUrl || item.audioUrl;
+  if (url) artifact.url = url;
+  if (item.error) artifact.error = item.error;
+  if (item.taskId) artifact.taskId = item.taskId;
+  if (item.snapshotId) artifact.snapshotId = item.snapshotId;
+  return artifact;
+}
+
+function normalizeDialogueEvent(runId, projectId, ev) {
+  const data = ev.data || {};
+  if (ev.type === 'message' || ev.type === 'approval' || ev.type === 'artifact') {
+    return { ...data, ...ev, runId: ev.runId || runId, projectId: ev.projectId || projectId };
+  }
+  switch (ev.type) {
+    case 'content':
+    case 'status':
+    case 'tool_call':
+    case 'error':
+      return normalizeDialogueMessage(runId, projectId, ev);
+    case 'image':
+      return normalizeDialogueArtifact(runId, projectId, { type: 'image', status: data.imageUrl ? 'completed' : 'running', imageUrl: data.imageUrl, snapshotId: data.snapshotId }, ev.seq);
+    case 'render':
+      return normalizeDialogueArtifact(runId, projectId, { type: data.animation ? 'video' : 'design', status: data.published ? 'completed' : 'running', url: data.url, snapshotId: data.snapshotId }, ev.seq);
+    case 'animation_task':
+    case 'video_snapshot':
+      return normalizeDialogueArtifact(runId, projectId, { type: 'video', status: 'running', taskId: data.taskId, snapshotId: data.snapshotId }, ev.seq);
+    case 'music_task':
+      return normalizeDialogueArtifact(runId, projectId, { type: 'music', status: 'running', taskId: data.taskId }, ev.seq);
+    default:
+      return null;
+  }
+}
+
+function buildDialogueEvents(runId, data) {
+  const projectId = data.projectId || data.project_id;
+  const events = [];
+  for (const ev of data.events || []) {
+    const normalized = normalizeDialogueEvent(runId, projectId, ev);
+    if (normalized) events.push(normalized);
+  }
+  for (const item of data.output || []) {
+    const normalized = normalizeDialogueArtifact(runId, projectId, item, item.seq);
+    if (normalized && !events.some(ev => ev.type === 'artifact' && ev.id === normalized.id)) events.push(normalized);
+  }
+  for (const approval of loadApprovals().filter(item => item.runId === runId)) {
+    events.push(approval);
+  }
+  return events;
+}
+
+function findUnhandledApprovalMessages(events) {
+  const approved = new Set(events.filter(ev => ev.type === 'approval').map(ev => ev.messageId || ev.message_id));
+  return events.filter(ev => ev.type === 'message' && ev.requires_approval && !approved.has(ev.id));
+}
+
+async function fetchRun(baseUrl, headers, runId, opts = {}) {
+  const params = new URLSearchParams();
+  if (opts.events) params.set('events', 'true');
+  const suffix = params.toString() ? `?${params}` : '';
+  const res = await fetch(`${baseUrl}/api/agent/run/${runId}${suffix}`, { headers });
+  if (!res.ok) { process.stderr.write(`Error ${res.status}: ${await res.text()}\n`); process.exit(1); }
+  return normalizeRunResponse(await res.json());
+}
+
+async function printDialogueEvents(baseUrl, headers, runId, opts = {}) {
+  const { jsonl = false, failOnUnapproved = false, follow = false, interval = 5000 } = opts;
+  const printed = new Set();
+
+  while (true) {
+    const data = await fetchRun(baseUrl, headers, runId, { events: true });
+    const events = buildDialogueEvents(runId, data);
+    const unhandled = findUnhandledApprovalMessages(events);
+    if (failOnUnapproved && unhandled.length) {
+      process.stderr.write(`Unhandled Makaron message requires approval: ${unhandled.map(ev => ev.id).join(', ')}\n`);
+      process.exit(3);
+    }
+
+    const nextEvents = follow ? events.filter(ev => !printed.has(`${ev.type}:${ev.id || ev.seq}`)) : events;
+    for (const ev of nextEvents) {
+      printed.add(`${ev.type}:${ev.id || ev.seq}`);
+      if (jsonl) console.log(JSON.stringify(ev));
+    }
+    if (!jsonl) console.log(JSON.stringify(nextEvents, null, 2));
+
+    if (!follow || (!data.incomplete && ['completed', 'failed', 'aborted'].includes(data.status))) {
+      if (data.status === 'failed' || data.status === 'aborted') process.exit(1);
+      return;
+    }
+    await new Promise(r => setTimeout(r, data.next_poll_after_ms || interval));
+  }
+}
+
+function recordApproval(runId, messageId, choice, note) {
+  const approvals = loadApprovals();
+  const approval = {
+    type: 'approval',
+    id: `approval_${Date.now()}`,
+    runId,
+    messageId,
+    choice,
+    status: 'recorded',
+    createdAt: new Date().toISOString(),
+  };
+  if (note) approval.note = note;
+  approvals.push(approval);
+  saveApprovals(approvals);
+  console.log(JSON.stringify(approval));
+}
+
 // ─── Watch (incremental event stream) ───────────────────────────────────────
 
 async function watchRun(baseUrl, headers, runId, opts = {}) {
@@ -813,7 +988,9 @@ async function analyzeVideoCli(baseUrl, headers, rawVideo, questionParts) {
 const args = process.argv.slice(2);
 const command = args[0];
 
-if (command === 'login') {
+if (command === '--version' || command === '-v' || command === 'version') {
+  console.log(getCliVersion());
+} else if (command === 'login') {
   await login();
 } else if (command === 'create') {
   const { headers, baseUrl } = getAuth();
@@ -1049,6 +1226,32 @@ if (command === 'login') {
     }
     await watchRun(baseUrl, headers, runId, { interval, jsonl });
 
+  } else if (sub === 'events') {
+    const runId = args[2];
+    if (!runId) { console.error('Usage: makaron responses events <runId> [--jsonl] [--follow] [--interval <ms>] [--fail-on-unapproved]'); process.exit(1); }
+    let interval = 5000, jsonl = false, follow = false, failOnUnapproved = false;
+    for (let i = 3; i < args.length; i++) {
+      if (args[i] === '--jsonl') jsonl = true;
+      else if (args[i] === '--follow') follow = true;
+      else if (args[i] === '--fail-on-unapproved') failOnUnapproved = true;
+      else if (args[i] === '--interval' && args[i + 1]) interval = parseInt(args[++i]);
+    }
+    await printDialogueEvents(baseUrl, headers, runId, { interval, jsonl, follow, failOnUnapproved });
+
+  } else if (['approve', 'revise', 'ask-user', 'continue'].includes(sub)) {
+    const messageId = args[2];
+    if (!messageId) { console.error(`Usage: makaron responses ${sub} <messageId> --run <runId> [--note <text>]`); process.exit(1); }
+    let runId = null, note = null;
+    const noteParts = [];
+    for (let i = 3; i < args.length; i++) {
+      if (args[i] === '--run' && args[i + 1]) runId = args[++i];
+      else if (args[i] === '--note' && args[i + 1]) note = args[++i];
+      else noteParts.push(args[i]);
+    }
+    if (!runId) { console.error(`Usage: makaron responses ${sub} <messageId> --run <runId> [--note <text>]`); process.exit(1); }
+    if (!note && noteParts.length) note = noteParts.join(' ');
+    recordApproval(runId, messageId, sub === 'ask-user' ? 'ask_user' : sub, note);
+
   } else if (sub === 'list') {
     let projectId = null;
     for (let i = 2; i < args.length; i++) {
@@ -1072,6 +1275,11 @@ if (command === 'login') {
   responses get <runId>                  Get status and output (JSON)
   responses get <runId> --wait           Poll until completed
   responses get <runId> --pick <field>   Extract: first_image_url, first_video_url, project_url, output
+  responses events <runId> --jsonl       Emit message/approval/artifact events for external Agents
+  responses approve <messageId> --run <runId>    Record approval for a Makaron message
+  responses revise <messageId> --run <runId>     Record revision request for a Makaron message
+  responses ask-user <messageId> --run <runId>   Record that the user must decide
+  responses continue <messageId> --run <runId>   Record continue decision
   responses watch <runId> --jsonl        Watch until done (incremental events)
   responses list --project <id>          List runs for a project
 `);
@@ -1509,6 +1717,7 @@ Commands:
 
   responses get <runId>              Get run status and results
   responses get <runId> --wait       Poll until completed
+  responses events <runId> --jsonl   Emit message/approval/artifact events
   responses list --project <id>      List runs for a project
   abort <runId>                      Abort a running Agent
 

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "makaron-cli",
-  "version": "0.7.6",
+  "version": "0.7.8",
   "description": "Talk to Makaron Agent from the terminal — create projects, edit images, generate videos",
   "type": "module",
+  "scripts": {
+    "test": "node test/smoke.mjs",
+    "test:smoke": "node test/smoke.mjs",
+    "test:live": "MAKARON_LIVE=1 node test/live-smoke.mjs"
+  },
   "bin": {
     "makaron": "./bin/makaron.mjs"
   },

package/skills/makaron/SKILL.md

@@ -50,14 +50,14 @@ Verify: `npx makaron-cli list` should show projects.
 # One-shot: create project + upload image + submit prompt — all in one command
 RUN_ID=$(npx makaron-cli chat --project auto --image photo.jpg -b "make it cinematic and create a 5s video")
 
-# Watch until all artifacts are ready
-npx makaron-cli responses watch $RUN_ID --jsonl
+# Wait for the final customer-ready result
+npx makaron-cli responses get $RUN_ID --wait --json
 ```
 
 Or with an existing project:
 ```bash
 RUN_ID=$(npx makaron-cli chat --project $PROJECT_ID -b "make a 5s video")
-npx makaron-cli responses watch $RUN_ID --jsonl
+npx makaron-cli responses get $RUN_ID --wait --json
 ```
 
 ## Primary: `chat` (Agent-driven creative work)
@@ -112,7 +112,7 @@ Use `chat --project <id|auto> --video ...` for any project/timeline video work.
 npx makaron-cli responses get <runId> --json
 ```
 
-### Watch until done (streaming events)
+### Advanced: stream incremental events
 
 ```bash
 npx makaron-cli responses watch <runId> --jsonl
@@ -126,6 +126,37 @@ Outputs one JSON per line as artifacts appear:
 {"event":"done","status":"completed"}
 ```
 
+### Dialogue events for external Agents
+
+Use this when another Agent needs to read what Makaron said, detect approval requirements, and relay artifacts without inventing customer-service wording.
+
+```bash
+npx makaron-cli responses events <runId> --jsonl
+```
+
+Events use only three factual types:
+
+```json
+{"type":"message","id":"msg_1","runId":"run_xxx","seq":1,"text":"Makaron original message","requires_approval":true,"approval_options":["approve","revise","ask_user","continue"]}
+{"type":"approval","messageId":"msg_1","choice":"approve","status":"recorded"}
+{"type":"artifact","kind":"image","status":"completed","url":"https://..."}
+```
+
+If a message has `requires_approval: true`, the external Agent must record an approval before continuing to wait for artifacts or claiming completion:
+
+```bash
+npx makaron-cli responses approve msg_1 --run <runId> --note "Proceed."
+npx makaron-cli responses revise msg_1 --run <runId> "make it softer"
+npx makaron-cli responses ask-user msg_1 --run <runId>
+npx makaron-cli responses continue msg_1 --run <runId>
+```
+
+Wrappers can enforce this with:
+
+```bash
+npx makaron-cli responses events <runId> --jsonl --fail-on-unapproved
+```
+
 ### Extract specific results
 
 ```bash
@@ -267,38 +298,33 @@ RUN_ID=$(npx makaron-cli chat --project auto --image photo.jpg -b "make it cinem
 PROJECT_URL=$(npx makaron-cli responses get $RUN_ID --pick project_url)
 send_message "Project created: $PROJECT_URL"
 
-# 4. Watch and send each artifact as it appears
-npx makaron-cli responses watch $RUN_ID --jsonl | while read -r line; do
-  EVENT=$(echo "$line" | jq -r '.event')
-  TYPE=$(echo "$line" | jq -r '.item.type // empty')
-  URL=$(echo "$line" | jq -r '.item.url // empty')
-  STATUS=$(echo "$line" | jq -r '.item.status // empty')
-
-  if [ "$EVENT" = "output.added" ] && [ "$TYPE" = "image" ]; then
-    # Send image immediately as media (not just link)
-    send_image "$URL"
-  elif [ "$EVENT" = "output.updated" ] && [ "$TYPE" = "video" ] && [ "$STATUS" = "completed" ]; then
-    # Video ready — send as media
-    send_video "$URL"
-  elif [ "$EVENT" = "done" ]; then
-    send_message "All done!"
-  fi
+# 4. Wait for the final customer-ready result
+RESULT=$(npx makaron-cli responses get $RUN_ID --wait --json)
+IMAGE_URLS=$(echo "$RESULT" | jq -r '[.result.images[]?.imageUrl, .output[]? | select(.type == "image") | .url] | map(select(. != null)) | unique | .[]')
+VIDEO_URLS=$(echo "$RESULT" | jq -r '[.result.videos[]?.videoUrl, .output[]? | select(.type == "video") | .url] | map(select(. != null)) | unique | .[]')
+
+for URL in $IMAGE_URLS; do
+  send_image "$URL"
+done
+for URL in $VIDEO_URLS; do
+  send_video "$URL"
 done
+send_message "All done!"
 ```
 
 **Key principles for service agents:**
-- **Proactive, not reactive**: Don't wait for the full run to finish. Send progress messages and artifacts as they appear.
+- **Proactive, not silent**: Acknowledge immediately, send the project link early, then send the final customer-ready media when the run completes.
 - **Media over links**: When possible, send images/videos as native media in the chat (download URL and upload as attachment), not just paste the URL.
 - **Immediate acknowledgment**: Reply within 1 second of receiving user request. Don't make users wait for project creation.
 - **Project link early**: Send the project URL right after creation so users can check anytime.
-- **Stream artifacts**: Use `watch --jsonl` to push each artifact the moment it's ready. An image at 15s should reach the user at 15s, not after the video finishes at 5 minutes.
+- **Use `get --wait --json` as the default service path**: reserve `watch --jsonl` for advanced streaming or debugging integrations that explicitly need incremental events.
 
 ## Important Notes
 
 - One project = one conversation thread. All history is preserved.
 - One run at a time per project. New message interrupts previous run.
 - Multi-image: `create --image a.jpg --image b.jpg` or `chat --image ref.jpg`.
-- Videos take 2-5 minutes to render. Use `watch` to get URL when ready.
+- Videos take 2-5 minutes to render. Use `responses get <runId> --wait --json` for the default customer-service path.
 - Music takes ~60 seconds. Appears in output when done.
 - Images are typically ready in 15-30 seconds.
 - stdout is always machine-readable JSON/text. Human-friendly logs go to stderr.