makaron-cli 0.7.7 → 0.7.9

package/README.md

@@ -134,6 +134,39 @@ 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
+# alias: npx makaron-cli responses timeline <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>
+```
+
+Important: approvals are a local Agent gate in v0. They are recorded by the CLI so wrappers and Skills can fail fast, but they do not pause or resume the remote Makaron runtime yet. Wrappers can enforce the local gate with:
+
+```bash
+npx makaron-cli responses events <runId> --jsonl
+# alias: npx makaron-cli responses timeline <runId> --jsonl --fail-on-unapproved
+```
+
 ### Extract specific results
 
 ```bash

package/SKILL.md

@@ -126,6 +126,39 @@ 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
+# alias: npx makaron-cli responses timeline <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>
+```
+
+Important: approvals are a local Agent gate in v0. They are recorded by the CLI so wrappers and Skills can fail fast, but they do not pause or resume the remote Makaron runtime yet. Wrappers can enforce the local gate with:
+
+```bash
+npx makaron-cli responses events <runId> --jsonl
+# alias: npx makaron-cli responses timeline <runId> --jsonl --fail-on-unapproved
+```
+
 ### Extract specific results
 
 ```bash

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;
@@ -62,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] || '';
@@ -426,6 +441,171 @@ function applyPick(data, field) {
   }
 }
 
+// ─── Dialogue Events (message / approval / artifact) ─────────────────────────
+
+function stableEventId(prefix, runId, seq, fallback) {
+  return fallback || `${prefix}_${runId}_${seq ?? Date.now()}`;
+}
+
+function inferRequiresApproval(text) {
+  if (!text) return false;
+  const normalized = text.toLowerCase().replace(/\s+/g, ' ').trim();
+  const approvalPhrases = [
+    /\bshall i\b.*\b(go ahead|proceed|continue|generate|create|submit|start)\b/,
+    /\bshould i\b.*\b(go ahead|proceed|continue|generate|create|submit|start)\b/,
+    /\bdo you want me to\b.*\b(go ahead|proceed|continue|generate|create|submit|start)\b/,
+    /\bconfirm\b.*\b(before|to)\b.*\b(generate|create|submit|proceed|continue)\b/,
+    /\bapprove\b.*\b(before|to)\b.*\b(generate|create|submit|proceed|continue)\b/,
+    /\bplease\b.*\b(confirm|approve)\b.*\b(generate|create|submit|proceed|continue)\b/,
+  ];
+  return approvalPhrases.some(pattern => pattern.test(normalized));
+}
+
+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 || inferRequiresApproval(text));
+  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 = {}) {
@@ -1060,6 +1240,32 @@ if (command === '--version' || command === '-v' || command === 'version') {
     }
     await watchRun(baseUrl, headers, runId, { interval, jsonl });
 
+  } else if (sub === 'events' || sub === 'timeline') {
+    const runId = args[2];
+    if (!runId) { console.error(`Usage: makaron responses ${sub} <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++) {
@@ -1083,6 +1289,12 @@ if (command === '--version' || command === '-v' || command === 'version') {
   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 timeline <runId> --jsonl     Alias for responses events
+  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
 `);
@@ -1520,6 +1732,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,6 +1,6 @@
 {
   "name": "makaron-cli",
-  "version": "0.7.7",
+  "version": "0.7.9",
   "description": "Talk to Makaron Agent from the terminal — create projects, edit images, generate videos",
   "type": "module",
   "scripts": {

package/skills/makaron/SKILL.md

@@ -126,6 +126,39 @@ 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
+# alias: npx makaron-cli responses timeline <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>
+```
+
+Important: approvals are a local Agent gate in v0. They are recorded by the CLI so wrappers and Skills can fail fast, but they do not pause or resume the remote Makaron runtime yet. Wrappers can enforce the local gate with:
+
+```bash
+npx makaron-cli responses events <runId> --jsonl
+# alias: npx makaron-cli responses timeline <runId> --jsonl --fail-on-unapproved
+```
+
 ### Extract specific results
 
 ```bash