makaron-cli 0.7.8 → 0.7.10

package/README.md

@@ -136,10 +136,13 @@ Outputs one JSON per line as artifacts appear:
 
 ### 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.
+Use this when another Agent needs to read what Makaron said, handle text checkpoints, and relay artifacts without inventing customer-service wording.
 
 ```bash
 npx makaron-cli responses events <runId> --jsonl
+# alias: npx makaron-cli responses timeline <runId> --jsonl
+# compact view: npx makaron-cli responses timeline <runId> --jsonl --compact
+# pure Q&A view: npx makaron-cli responses timeline <runId> --jsonl --checkpoint-mode off
 ```
 
 Events use only three factual types:
@@ -150,7 +153,7 @@ Events use only three factual types:
 {"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:
+Makaron uses a conservative checkpoint rule for creative/service Agents: if a run stops with substantive text, has no image/video/music/design artifact, and has no continuing execution action such as a tool call, the message is marked `requires_approval: true`. Pure status text such as queued, rendering, uploading, or completed is not treated as a checkpoint. Pure Q&A flows should pass `--checkpoint-mode off`. 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."
@@ -159,12 +162,15 @@ npx makaron-cli responses ask-user msg_1 --run <runId>
 npx makaron-cli responses continue msg_1 --run <runId>
 ```
 
-Wrappers can enforce this with:
+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 --fail-on-unapproved
+npx makaron-cli responses events <runId> --jsonl --checkpoint-mode service --fail-on-unapproved
+# alias: npx makaron-cli responses timeline <runId> --jsonl --compact --fail-on-unapproved
 ```
 
+Use `--compact` when relaying to another Agent or chat system; it merges consecutive Makaron content chunks into a single readable message.
+
 ### Extract specific results
 
 ```bash
@@ -294,6 +300,33 @@ type MakaronOutput =
 | Motion design | "create an Instagram story with animated text" |
 | Multi-step | "edit the photo then make a video from it" |
 
+## Minimal Agent Wrapper
+
+A new Agent can use this minimal flow:
+
+```bash
+RUN_JSON=$(npx makaron-cli chat --project auto --json -b "$USER_PROMPT")
+RUN_ID=$(echo "$RUN_JSON" | jq -r .runId)
+PROJECT_URL=$(echo "$RUN_JSON" | jq -r .projectUrl)
+send_message "Project created: $PROJECT_URL"
+
+if ! npx makaron-cli responses timeline "$RUN_ID" --jsonl --compact --checkpoint-mode service --fail-on-unapproved > /tmp/makaron-events.jsonl; then
+  npx makaron-cli responses timeline "$RUN_ID" --jsonl --compact | while read -r event; do
+    TYPE=$(echo "$event" | jq -r .type)
+    REQUIRES=$(echo "$event" | jq -r ".requires_approval // false")
+    TEXT=$(echo "$event" | jq -r ".text // empty")
+    MSG_ID=$(echo "$event" | jq -r ".id // empty")
+    if [ "$TYPE" = "message" ] && [ "$REQUIRES" = "true" ]; then
+      send_message "$TEXT"
+      npx makaron-cli responses ask-user "$MSG_ID" --run "$RUN_ID"
+      exit 3
+    fi
+  done
+fi
+
+RESULT=$(npx makaron-cli responses get "$RUN_ID" --wait --json)
+```
+
 ## Recommended Pattern: Service Flow (Feishu/OpenClaw/Group Chat)
 
 When serving end-users in a chat environment (Feishu, Slack, Discord), use this proactive message pattern:

package/SKILL.md

@@ -128,10 +128,13 @@ Outputs one JSON per line as artifacts appear:
 
 ### 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.
+Use this when another Agent needs to read what Makaron said, handle text checkpoints, and relay artifacts without inventing customer-service wording.
 
 ```bash
 npx makaron-cli responses events <runId> --jsonl
+# alias: npx makaron-cli responses timeline <runId> --jsonl
+# compact view: npx makaron-cli responses timeline <runId> --jsonl --compact
+# pure Q&A view: npx makaron-cli responses timeline <runId> --jsonl --checkpoint-mode off
 ```
 
 Events use only three factual types:
@@ -142,7 +145,7 @@ Events use only three factual types:
 {"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:
+Makaron uses a conservative checkpoint rule for creative/service Agents: if a run stops with substantive text, has no image/video/music/design artifact, and has no continuing execution action such as a tool call, the message is marked `requires_approval: true`. Pure status text such as queued, rendering, uploading, or completed is not treated as a checkpoint. Pure Q&A flows should pass `--checkpoint-mode off`. 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."
@@ -151,12 +154,15 @@ npx makaron-cli responses ask-user msg_1 --run <runId>
 npx makaron-cli responses continue msg_1 --run <runId>
 ```
 
-Wrappers can enforce this with:
+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 --fail-on-unapproved
+npx makaron-cli responses events <runId> --jsonl --checkpoint-mode service --fail-on-unapproved
+# alias: npx makaron-cli responses timeline <runId> --jsonl --compact --fail-on-unapproved
 ```
 
+Use `--compact` when relaying to another Agent or chat system; it merges consecutive Makaron content chunks into a single readable message.
+
 ### Extract specific results
 
 ```bash
@@ -283,6 +289,33 @@ type MakaronOutput =
 | Motion design | "create an Instagram story with animated text" |
 | Multi-step | "edit the photo then make a video from it" |
 
+## Minimal Agent Wrapper
+
+A new Agent can use this minimal flow:
+
+```bash
+RUN_JSON=$(npx makaron-cli chat --project auto --json -b "$USER_PROMPT")
+RUN_ID=$(echo "$RUN_JSON" | jq -r .runId)
+PROJECT_URL=$(echo "$RUN_JSON" | jq -r .projectUrl)
+send_message "Project created: $PROJECT_URL"
+
+if ! npx makaron-cli responses timeline "$RUN_ID" --jsonl --compact --checkpoint-mode service --fail-on-unapproved > /tmp/makaron-events.jsonl; then
+  npx makaron-cli responses timeline "$RUN_ID" --jsonl --compact | while read -r event; do
+    TYPE=$(echo "$event" | jq -r .type)
+    REQUIRES=$(echo "$event" | jq -r ".requires_approval // false")
+    TEXT=$(echo "$event" | jq -r ".text // empty")
+    MSG_ID=$(echo "$event" | jq -r ".id // empty")
+    if [ "$TYPE" = "message" ] && [ "$REQUIRES" = "true" ]; then
+      send_message "$TEXT"
+      npx makaron-cli responses ask-user "$MSG_ID" --run "$RUN_ID"
+      exit 3
+    fi
+  done
+fi
+
+RESULT=$(npx makaron-cli responses get "$RUN_ID" --wait --json)
+```
+
 ## Recommended Pattern: Service Flow (Feishu/OpenClaw/Group Chat)
 
 When serving end-users in a chat environment (Feishu, Slack, Discord), use this proactive message pattern:

package/bin/makaron.mjs

@@ -447,11 +447,61 @@ function stableEventId(prefix, runId, seq, fallback) {
   return fallback || `${prefix}_${runId}_${seq ?? Date.now()}`;
 }
 
-function normalizeDialogueMessage(runId, projectId, ev) {
+function inferApprovalIntent(text) {
+  if (!text) return false;
+  const normalized = text.toLowerCase().replace(/\s+/g, ' ').trim();
+  const hasEnglishApprovalIntent = /\b(shall i|should i|do you want me to|confirm|approve|approval|permission)\b/.test(normalized);
+  const hasEnglishAction = /\b(go ahead|proceed|continue|generate|create|submit|start|run|render)\b/.test(normalized);
+  const hasChineseApprovalIntent = /(是否|要不要|是否要|需要我|请确认|确认|同意|批准|可以吗|是否可以)/.test(normalized);
+  const hasChineseAction = /(继续|开始|生成|创建|提交|执行|渲染|出图|出视频|制作)/.test(normalized);
+  return (hasEnglishApprovalIntent && hasEnglishAction) || (hasChineseApprovalIntent && hasChineseAction);
+}
+
+function isPureStatusMessage(text, sourceType, status) {
+  const normalized = String(text || '').toLowerCase().replace(/\s+/g, ' ').trim();
+  if (sourceType === 'status') return true;
+  if (status && !normalized) return true;
+  if (!normalized) return false;
+  return /^(queued|running|rendering|uploading|processing|generating|completed|complete|done|failed|aborted|started|submitted|waiting|polling)(\.|…|\.\.\.)?$/.test(normalized)
+    || /^(排队中|队列中|运行中|渲染中|上传中|处理中|生成中|已完成|完成|失败|已失败|已提交|等待中)$/.test(normalized);
+}
+
+function hasExplicitApprovalRequirement(data, text) {
+  return Boolean(
+    data.requires_approval
+      || data.requiresApproval
+      || data.action_required
+      || data.actionRequired
+      || data.proposal
+      || inferApprovalIntent(text)
+  );
+}
+
+function isPureQaRun(data) {
+  const raw = [
+    data.intent,
+    data.mode,
+    data.workflow,
+    data.workflow_type,
+    data.workflowType,
+    data.run_type,
+    data.runType,
+    data.kind,
+  ].filter(Boolean).join(' ').toLowerCase();
+  return /\b(qa|q&a|question_answer|question-answer|answer|pure_qa|pure-qa)\b/.test(raw);
+}
+
+function normalizeDialogueMessage(runId, projectId, ev, context = {}) {
   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 explicitApproval = hasExplicitApprovalRequirement(data, text);
+  const textOnlyCheckpoint = Boolean(
+    context.stoppedWithoutArtifacts
+      && !explicitApproval
+      && !isPureStatusMessage(text, ev.type, data.status)
+  );
+  const requiresApproval = explicitApproval || textOnlyCheckpoint;
   const message = {
     type: 'message',
     id: stableEventId('msg', runId, ev.seq, data.id || ev.id),
@@ -465,6 +515,7 @@ function normalizeDialogueMessage(runId, projectId, ev) {
   if (requiresApproval) {
     message.requires_approval = true;
     message.approval_options = data.approval_options || data.approvalOptions || ['approve', 'revise', 'ask_user', 'continue'];
+    if (textOnlyCheckpoint) message.approval_reason = 'text_only_checkpoint';
   }
   if (data.proposal) message.proposal = data.proposal;
   return message;
@@ -474,6 +525,7 @@ 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;
+  if (!['image', 'video', 'design', 'music', 'audio', 'file'].includes(kind)) return null;
   const artifact = {
     type: 'artifact',
     id: stableEventId('artifact', runId, seq, item.id || item.snapshotId || item.taskId),
@@ -491,7 +543,7 @@ function normalizeDialogueArtifact(runId, projectId, item, seq) {
   return artifact;
 }
 
-function normalizeDialogueEvent(runId, projectId, ev) {
+function normalizeDialogueEvent(runId, projectId, ev, context = {}) {
   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 };
@@ -501,7 +553,7 @@ function normalizeDialogueEvent(runId, projectId, ev) {
     case 'status':
     case 'tool_call':
     case 'error':
-      return normalizeDialogueMessage(runId, projectId, ev);
+      return normalizeDialogueMessage(runId, projectId, ev, context);
     case 'image':
       return normalizeDialogueArtifact(runId, projectId, { type: 'image', status: data.imageUrl ? 'completed' : 'running', imageUrl: data.imageUrl, snapshotId: data.snapshotId }, ev.seq);
     case 'render':
@@ -519,8 +571,22 @@ function normalizeDialogueEvent(runId, projectId, ev) {
 function buildDialogueEvents(runId, data) {
   const projectId = data.projectId || data.project_id;
   const events = [];
+  const hasArtifacts = Boolean(
+    (data.output || []).some(item => normalizeDialogueArtifact(runId, projectId, item, item.seq))
+      || (data.events || []).some(ev => normalizeDialogueEvent(runId, projectId, ev, { stoppedWithoutArtifacts: false })?.type === 'artifact')
+  );
+  const hasContinuationAction = (data.events || []).some(ev => ['tool_call', 'image', 'render', 'animation_task', 'video_snapshot', 'music_task'].includes(ev.type));
+  const checkpointMode = data.checkpointMode || 'service';
+  const context = {
+    stoppedWithoutArtifacts: checkpointMode !== 'off'
+      && !isPureQaRun(data)
+      && !hasArtifacts
+      && !hasContinuationAction
+      && !data.incomplete
+      && ['completed', 'failed', 'aborted', 'waiting', 'needs_input'].includes(data.status),
+  };
   for (const ev of data.events || []) {
-    const normalized = normalizeDialogueEvent(runId, projectId, ev);
+    const normalized = normalizeDialogueEvent(runId, projectId, ev, context);
     if (normalized) events.push(normalized);
   }
   for (const item of data.output || []) {
@@ -533,6 +599,30 @@ function buildDialogueEvents(runId, data) {
   return events;
 }
 
+function compactDialogueEvents(events) {
+  const compacted = [];
+  for (const ev of events) {
+    const prev = compacted[compacted.length - 1];
+    const canMerge = prev
+      && ev.type === 'message'
+      && prev.type === 'message'
+      && ev.source_type === 'content'
+      && prev.source_type === 'content'
+      && !ev.requires_approval
+      && !prev.requires_approval
+      && !ev.proposal
+      && !prev.proposal;
+    if (canMerge) {
+      prev.text = `${prev.text}${ev.text}`;
+      prev.id = `${prev.id}+${ev.id}`;
+      prev.seq_end = ev.seq;
+    } else {
+      compacted.push({ ...ev });
+    }
+  }
+  return compacted;
+}
+
 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));
@@ -548,12 +638,13 @@ async function fetchRun(baseUrl, headers, runId, opts = {}) {
 }
 
 async function printDialogueEvents(baseUrl, headers, runId, opts = {}) {
-  const { jsonl = false, failOnUnapproved = false, follow = false, interval = 5000 } = opts;
+  const { jsonl = false, failOnUnapproved = false, follow = false, interval = 5000, compact = false, checkpointMode = 'service' } = opts;
   const printed = new Set();
 
   while (true) {
     const data = await fetchRun(baseUrl, headers, runId, { events: true });
-    const events = buildDialogueEvents(runId, data);
+    const dialogueEvents = buildDialogueEvents(runId, { ...data, checkpointMode });
+    const events = compact ? compactDialogueEvents(dialogueEvents) : dialogueEvents;
     const unhandled = findUnhandledApprovalMessages(events);
     if (failOnUnapproved && unhandled.length) {
       process.stderr.write(`Unhandled Makaron message requires approval: ${unhandled.map(ev => ev.id).join(', ')}\n`);
@@ -1226,17 +1317,23 @@ if (command === '--version' || command === '-v' || command === 'version') {
     }
     await watchRun(baseUrl, headers, runId, { interval, jsonl });
 
-  } else if (sub === 'events') {
+  } else if (sub === 'events' || sub === 'timeline') {
     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;
+    if (!runId) { console.error(`Usage: makaron responses ${sub} <runId> [--jsonl] [--compact] [--checkpoint-mode service|off] [--follow] [--interval <ms>] [--fail-on-unapproved]`); process.exit(1); }
+    let interval = 5000, jsonl = false, follow = false, failOnUnapproved = false, compact = false, checkpointMode = 'service';
     for (let i = 3; i < args.length; i++) {
       if (args[i] === '--jsonl') jsonl = true;
+      else if (args[i] === '--compact') compact = true;
+      else if (args[i] === '--checkpoint-mode' && args[i + 1]) checkpointMode = args[++i];
       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 });
+    if (!['service', 'off'].includes(checkpointMode)) {
+      console.error('--checkpoint-mode must be service or off');
+      process.exit(1);
+    }
+    await printDialogueEvents(baseUrl, headers, runId, { interval, jsonl, follow, failOnUnapproved, compact, checkpointMode });
 
   } else if (['approve', 'revise', 'ask-user', 'continue'].includes(sub)) {
     const messageId = args[2];
@@ -1276,6 +1373,8 @@ if (command === '--version' || command === '-v' || command === 'version') {
   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 timeline <runId> --checkpoint-mode off   Disable text-only checkpoints for pure Q&A
   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
@@ -1718,6 +1817,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 timeline <runId> --checkpoint-mode off   Disable text-only checkpoints for pure Q&A
   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.8",
+  "version": "0.7.10",
   "description": "Talk to Makaron Agent from the terminal — create projects, edit images, generate videos",
   "type": "module",
   "scripts": {

package/skills/makaron/SKILL.md

@@ -128,10 +128,13 @@ Outputs one JSON per line as artifacts appear:
 
 ### 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.
+Use this when another Agent needs to read what Makaron said, handle text checkpoints, and relay artifacts without inventing customer-service wording.
 
 ```bash
 npx makaron-cli responses events <runId> --jsonl
+# alias: npx makaron-cli responses timeline <runId> --jsonl
+# compact view: npx makaron-cli responses timeline <runId> --jsonl --compact
+# pure Q&A view: npx makaron-cli responses timeline <runId> --jsonl --checkpoint-mode off
 ```
 
 Events use only three factual types:
@@ -142,7 +145,7 @@ Events use only three factual types:
 {"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:
+Makaron uses a conservative checkpoint rule for creative/service Agents: if a run stops with substantive text, has no image/video/music/design artifact, and has no continuing execution action such as a tool call, the message is marked `requires_approval: true`. Pure status text such as queued, rendering, uploading, or completed is not treated as a checkpoint. Pure Q&A flows should pass `--checkpoint-mode off`. 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."
@@ -151,12 +154,15 @@ npx makaron-cli responses ask-user msg_1 --run <runId>
 npx makaron-cli responses continue msg_1 --run <runId>
 ```
 
-Wrappers can enforce this with:
+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 --fail-on-unapproved
+npx makaron-cli responses events <runId> --jsonl --checkpoint-mode service --fail-on-unapproved
+# alias: npx makaron-cli responses timeline <runId> --jsonl --compact --fail-on-unapproved
 ```
 
+Use `--compact` when relaying to another Agent or chat system; it merges consecutive Makaron content chunks into a single readable message.
+
 ### Extract specific results
 
 ```bash
@@ -283,6 +289,33 @@ type MakaronOutput =
 | Motion design | "create an Instagram story with animated text" |
 | Multi-step | "edit the photo then make a video from it" |
 
+## Minimal Agent Wrapper
+
+A new Agent can use this minimal flow:
+
+```bash
+RUN_JSON=$(npx makaron-cli chat --project auto --json -b "$USER_PROMPT")
+RUN_ID=$(echo "$RUN_JSON" | jq -r .runId)
+PROJECT_URL=$(echo "$RUN_JSON" | jq -r .projectUrl)
+send_message "Project created: $PROJECT_URL"
+
+if ! npx makaron-cli responses timeline "$RUN_ID" --jsonl --compact --checkpoint-mode service --fail-on-unapproved > /tmp/makaron-events.jsonl; then
+  npx makaron-cli responses timeline "$RUN_ID" --jsonl --compact | while read -r event; do
+    TYPE=$(echo "$event" | jq -r .type)
+    REQUIRES=$(echo "$event" | jq -r ".requires_approval // false")
+    TEXT=$(echo "$event" | jq -r ".text // empty")
+    MSG_ID=$(echo "$event" | jq -r ".id // empty")
+    if [ "$TYPE" = "message" ] && [ "$REQUIRES" = "true" ]; then
+      send_message "$TEXT"
+      npx makaron-cli responses ask-user "$MSG_ID" --run "$RUN_ID"
+      exit 3
+    fi
+  done
+fi
+
+RESULT=$(npx makaron-cli responses get "$RUN_ID" --wait --json)
+```
+
 ## Recommended Pattern: Service Flow (Feishu/OpenClaw/Group Chat)
 
 When serving end-users in a chat environment (Feishu, Slack, Discord), use this proactive message pattern: