makaron-cli 0.7.10 → 0.8.1

package/README.md

@@ -134,6 +134,24 @@ Outputs one JSON per line as artifacts appear:
 {"event":"done","status":"completed"}
 ```
 
+### New Agent quickstart
+
+For a new Agent, keep the default service flow to two response commands:
+
+```bash
+npx makaron-cli responses next <runId> --json
+npx makaron-cli responses handle <messageId> --run <runId> --choice approve
+npx makaron-cli responses deliver <artifactId> --run <runId> --channel feishu --message-id <messageId>
+```
+
+`responses next` emits a compact timeline, detects text-only checkpoints for creative/service work, and returns `next_commands` when the Agent must handle a Makaron message before waiting for artifacts. It exits with code `3` on an unhandled checkpoint so wrappers stop instead of silently waiting. After handling a checkpoint, run the returned `next_commands.inspect` command to continue. While the run is still generating, it returns `status: "running"` and `blocking: false`. If completed image/video artifacts exist and have not been delivered, it returns `status: "has_artifacts"` and `blocking: true` with compact `undelivered_artifacts` entries containing `kind`, `status`, `url`, `fileName`, and `contentType` when available, plus `next_commands.deliver`; the Agent must send the artifact URL to the user, then record delivery with `responses deliver`. A non-checkpoint response returns `status: "ready"` or `status: "delivered"`. If a run failed, `responses next --json` prints `status: "failed"` and `blocking: true` plus `error.type`, `error.message`, `error.recoverable`, `error.detail`, and `next_command` to stdout before exiting `1`, so wrappers can parse the failure without scraping stderr. Use `--no-fail` to inspect checkpoint JSON without failing. For pure Q&A runs, use:
+
+```bash
+npx makaron-cli responses next <runId> --json --checkpoint-mode off
+```
+
+`responses handle` is the single checkpoint action command. Valid choices are `approve`, `revise`, `ask_user`, and `continue`. `responses deliver` records that a completed artifact was actually delivered to the user, preventing repeated delivery prompts.
+
 ### Dialogue events for external Agents
 
 Use this when another Agent needs to read what Makaron said, handle text checkpoints, and relay artifacts without inventing customer-service wording.
@@ -145,6 +163,8 @@ npx makaron-cli responses events <runId> --jsonl
 # pure Q&A view: npx makaron-cli responses timeline <runId> --jsonl --checkpoint-mode off
 ```
 
+`events` and `timeline` are lower-level commands. New Agents should start with `responses next` and use these only when they need raw event streams.
+
 Events use only three factual types:
 
 ```json
@@ -160,6 +180,7 @@ 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>
+npx makaron-cli responses handle msg_1 --run <runId> --choice approve
 ```
 
 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:
@@ -310,18 +331,26 @@ 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
+if ! NEXT=$(npx makaron-cli responses next "$RUN_ID" --json); then
+  STATUS=$(echo "$NEXT" | jq -r .status)
+  if [ "$STATUS" = "needs_approval" ]; then
+    MSG_ID=$(echo "$NEXT" | jq -r .checkpoint.id)
+    TEXT=$(echo "$NEXT" | jq -r .checkpoint.text)
+    send_message "$TEXT"
+    npx makaron-cli responses handle "$MSG_ID" --run "$RUN_ID" --choice ask_user
+    exit 3
+  elif [ "$STATUS" = "failed" ]; then
+    send_message "$(echo "$NEXT" | jq -r .error.message)"
+    exit 1
+  fi
+fi
+
+NEXT=$(npx makaron-cli responses next "$RUN_ID" --json --no-fail)
+if [ "$(echo "$NEXT" | jq -r .status)" = "has_artifacts" ]; then
+  ARTIFACT_ID=$(echo "$NEXT" | jq -r ".undelivered_artifacts[0].id")
+  ARTIFACT_URL=$(echo "$NEXT" | jq -r ".undelivered_artifacts[0].url")
+  DELIVERY_MESSAGE_ID=$(send_message "$ARTIFACT_URL")
+  npx makaron-cli responses deliver "$ARTIFACT_ID" --run "$RUN_ID" --channel feishu --message-id "$DELIVERY_MESSAGE_ID"
 fi
 
 RESULT=$(npx makaron-cli responses get "$RUN_ID" --wait --json)

package/SKILL.md

@@ -126,6 +126,24 @@ Outputs one JSON per line as artifacts appear:
 {"event":"done","status":"completed"}
 ```
 
+### New Agent quickstart
+
+For a new Agent, keep the default service flow to two response commands:
+
+```bash
+npx makaron-cli responses next <runId> --json
+npx makaron-cli responses handle <messageId> --run <runId> --choice approve
+npx makaron-cli responses deliver <artifactId> --run <runId> --channel feishu --message-id <messageId>
+```
+
+`responses next` emits a compact timeline, detects text-only checkpoints for creative/service work, and returns `next_commands` when the Agent must handle a Makaron message before waiting for artifacts. It exits with code `3` on an unhandled checkpoint so wrappers stop instead of silently waiting. After handling a checkpoint, run the returned `next_commands.inspect` command to continue. While the run is still generating, it returns `status: "running"` and `blocking: false`. If completed image/video artifacts exist and have not been delivered, it returns `status: "has_artifacts"` and `blocking: true` with compact `undelivered_artifacts` entries containing `kind`, `status`, `url`, `fileName`, and `contentType` when available, plus `next_commands.deliver`; the Agent must send the artifact URL to the user, then record delivery with `responses deliver`. A non-checkpoint response returns `status: "ready"` or `status: "delivered"`. If a run failed, `responses next --json` prints `status: "failed"` and `blocking: true` plus `error.type`, `error.message`, `error.recoverable`, `error.detail`, and `next_command` to stdout before exiting `1`, so wrappers can parse the failure without scraping stderr. Use `--no-fail` to inspect checkpoint JSON without failing. For pure Q&A runs, use:
+
+```bash
+npx makaron-cli responses next <runId> --json --checkpoint-mode off
+```
+
+`responses handle` is the single checkpoint action command. Valid choices are `approve`, `revise`, `ask_user`, and `continue`. `responses deliver` records that a completed artifact was actually delivered to the user, preventing repeated delivery prompts.
+
 ### Dialogue events for external Agents
 
 Use this when another Agent needs to read what Makaron said, handle text checkpoints, and relay artifacts without inventing customer-service wording.
@@ -137,6 +155,8 @@ npx makaron-cli responses events <runId> --jsonl
 # pure Q&A view: npx makaron-cli responses timeline <runId> --jsonl --checkpoint-mode off
 ```
 
+`events` and `timeline` are lower-level commands. New Agents should start with `responses next` and use these only when they need raw event streams.
+
 Events use only three factual types:
 
 ```json
@@ -152,6 +172,7 @@ 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>
+npx makaron-cli responses handle msg_1 --run <runId> --choice approve
 ```
 
 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:
@@ -299,18 +320,26 @@ 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
+if ! NEXT=$(npx makaron-cli responses next "$RUN_ID" --json); then
+  STATUS=$(echo "$NEXT" | jq -r .status)
+  if [ "$STATUS" = "needs_approval" ]; then
+    MSG_ID=$(echo "$NEXT" | jq -r .checkpoint.id)
+    TEXT=$(echo "$NEXT" | jq -r .checkpoint.text)
+    send_message "$TEXT"
+    npx makaron-cli responses handle "$MSG_ID" --run "$RUN_ID" --choice ask_user
+    exit 3
+  elif [ "$STATUS" = "failed" ]; then
+    send_message "$(echo "$NEXT" | jq -r .error.message)"
+    exit 1
+  fi
+fi
+
+NEXT=$(npx makaron-cli responses next "$RUN_ID" --json --no-fail)
+if [ "$(echo "$NEXT" | jq -r .status)" = "has_artifacts" ]; then
+  ARTIFACT_ID=$(echo "$NEXT" | jq -r ".undelivered_artifacts[0].id")
+  ARTIFACT_URL=$(echo "$NEXT" | jq -r ".undelivered_artifacts[0].url")
+  DELIVERY_MESSAGE_ID=$(send_message "$ARTIFACT_URL")
+  npx makaron-cli responses deliver "$ARTIFACT_ID" --run "$RUN_ID" --channel feishu --message-id "$DELIVERY_MESSAGE_ID"
 fi
 
 RESULT=$(npx makaron-cli responses get "$RUN_ID" --wait --json)

package/bin/makaron.mjs

@@ -20,6 +20,7 @@ import { execFileSync } from 'child_process';
 
 const AUTH_FILE = path.join(process.env.HOME || '~', '.makaron', 'auth.json');
 const APPROVALS_FILE = path.join(path.dirname(AUTH_FILE), 'approvals.json');
+const DELIVERIES_FILE = path.join(path.dirname(AUTH_FILE), 'deliveries.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;
@@ -77,6 +78,20 @@ function saveApprovals(approvals) {
   fs.writeFileSync(APPROVALS_FILE, JSON.stringify(approvals, null, 2));
 }
 
+function loadDeliveries() {
+  try {
+    return JSON.parse(fs.readFileSync(DELIVERIES_FILE, 'utf-8'));
+  } catch {
+    return [];
+  }
+}
+
+function saveDeliveries(deliveries) {
+  const dir = path.dirname(DELIVERIES_FILE);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(DELIVERIES_FILE, JSON.stringify(deliveries, null, 2));
+}
+
 function buildCookie(tokenJson) {
   const url = tokenJson._supabaseUrl || SUPABASE_URL;
   const ref = url.match(/\/\/([^.]+)\./)?.[1] || '';
@@ -498,6 +513,7 @@ function normalizeDialogueMessage(runId, projectId, ev, context = {}) {
   const explicitApproval = hasExplicitApprovalRequirement(data, text);
   const textOnlyCheckpoint = Boolean(
     context.stoppedWithoutArtifacts
+      && ev.type !== 'error'
       && !explicitApproval
       && !isPureStatusMessage(text, ev.type, data.status)
   );
@@ -537,6 +553,10 @@ function normalizeDialogueArtifact(runId, projectId, item, seq) {
   };
   const url = item.url || item.imageUrl || item.videoUrl || item.audioUrl;
   if (url) artifact.url = url;
+  const fileName = item.fileName || item.filename || item.name || (url ? url.split('/').pop()?.split('?')[0] : null);
+  const contentType = item.contentType || item.content_type || item.mimeType || item.mime_type;
+  if (fileName) artifact.fileName = fileName;
+  if (contentType) artifact.contentType = contentType;
   if (item.error) artifact.error = item.error;
   if (item.taskId) artifact.taskId = item.taskId;
   if (item.snapshotId) artifact.snapshotId = item.snapshotId;
@@ -608,14 +628,18 @@ function compactDialogueEvents(events) {
       && prev.type === 'message'
       && ev.source_type === 'content'
       && prev.source_type === 'content'
-      && !ev.requires_approval
-      && !prev.requires_approval
       && !ev.proposal
-      && !prev.proposal;
+      && !prev.proposal
+      && Boolean(ev.requires_approval) === Boolean(prev.requires_approval)
+      && (ev.approval_reason || '') === (prev.approval_reason || '');
     if (canMerge) {
       prev.text = `${prev.text}${ev.text}`;
       prev.id = `${prev.id}+${ev.id}`;
       prev.seq_end = ev.seq;
+      if (ev.requires_approval) {
+        prev.requires_approval = true;
+        prev.approval_options = prev.approval_options || ev.approval_options;
+      }
     } else {
       compacted.push({ ...ev });
     }
@@ -628,6 +652,127 @@ function findUnhandledApprovalMessages(events) {
   return events.filter(ev => ev.type === 'message' && ev.requires_approval && !approved.has(ev.id));
 }
 
+function isCompletedDeliverableArtifact(artifact) {
+  return artifact?.type === 'artifact'
+    && ['image', 'video', 'design', 'music', 'audio', 'file'].includes(artifact.kind)
+    && artifact.status === 'completed'
+    && Boolean(artifact.url);
+}
+
+function findUndeliveredArtifacts(runId, events) {
+  const delivered = new Set(loadDeliveries().filter(item => item.runId === runId).map(item => item.artifactId || item.artifact_id));
+  return events.filter(isCompletedDeliverableArtifact).filter(artifact => !delivered.has(artifact.id));
+}
+
+function buildCliCommand() {
+  return 'npx makaron-cli@latest';
+}
+
+function buildHandleCommand(messageId, runId, choice) {
+  return `${buildCliCommand()} responses handle ${messageId} --run ${runId} --choice ${choice}`;
+}
+
+function buildNextCommand(runId) {
+  return `${buildCliCommand()} responses next ${runId} --json`;
+}
+
+function buildDeliverCommand(artifactId, runId) {
+  return `${buildCliCommand()} responses deliver ${artifactId} --run ${runId}`;
+}
+
+function buildRunError(data, events) {
+  const errorEvent = events.find(ev => ev.type === 'message' && ev.source_type === 'error') || null;
+  const resultError = data.result?.error || data.error || data.message || null;
+  if (!errorEvent && !resultError && !['failed', 'aborted'].includes(data.status)) return null;
+  const errorType = (typeof resultError === 'object' && (resultError.type || resultError.code)) || data.error_type || data.errorType || data.status || 'failed';
+  return {
+    type: errorType,
+    status: data.status || 'failed',
+    message: errorEvent?.text || (typeof resultError === 'string' ? resultError : resultError?.message) || `Makaron run ${data.status || 'failed'}`,
+    recoverable: Boolean((typeof resultError === 'object' && resultError.recoverable) || data.recoverable),
+    detail: typeof resultError === 'object' ? resultError : undefined,
+  };
+}
+
+function buildNextAction(runId, events, data = {}) {
+  const runError = buildRunError(data, events);
+  if (runError) {
+    return {
+      status: 'failed',
+      blocking: true,
+      runId,
+      error: runError,
+      next_command: buildNextCommand(runId),
+      next_commands: {
+        inspect: buildNextCommand(runId),
+      },
+      events,
+    };
+  }
+  const checkpoint = findUnhandledApprovalMessages(events)[0] || null;
+  const artifacts = events.filter(ev => ev.type === 'artifact');
+  const approvals = events.filter(ev => ev.type === 'approval');
+  if (data.incomplete || ['queued', 'running', 'rendering', 'processing', 'generating', 'submitted'].includes(data.status)) {
+    return {
+      status: 'running',
+      blocking: false,
+      runId,
+      artifacts,
+      approvals,
+      next_command: buildNextCommand(runId),
+      next_commands: {
+        inspect: buildNextCommand(runId),
+      },
+      events,
+    };
+  }
+  if (checkpoint) {
+    return {
+      status: 'needs_approval',
+      blocking: true,
+      runId,
+      checkpoint,
+      next_commands: {
+        approve: buildHandleCommand(checkpoint.id, runId, 'approve'),
+        revise: `${buildHandleCommand(checkpoint.id, runId, 'revise')} --note "what to change"`,
+        ask_user: buildHandleCommand(checkpoint.id, runId, 'ask_user'),
+        continue: buildHandleCommand(checkpoint.id, runId, 'continue'),
+        inspect: buildNextCommand(runId),
+      },
+      events,
+    };
+  }
+  const undeliveredArtifacts = findUndeliveredArtifacts(runId, events);
+  if (undeliveredArtifacts.length) {
+    const first = undeliveredArtifacts[0];
+    return {
+      status: 'has_artifacts',
+      blocking: true,
+      runId,
+      artifacts,
+      undelivered_artifacts: undeliveredArtifacts,
+      approvals,
+      next_commands: {
+        deliver: buildDeliverCommand(first.id, runId),
+        inspect: buildNextCommand(runId),
+      },
+      events,
+    };
+  }
+  return {
+    status: artifacts.length ? 'delivered' : 'ready',
+    blocking: false,
+    runId,
+    artifacts,
+    approvals,
+    deliveries: loadDeliveries().filter(item => item.runId === runId),
+    next_commands: {
+      inspect: buildNextCommand(runId),
+    },
+    events,
+  };
+}
+
 async function fetchRun(baseUrl, headers, runId, opts = {}) {
   const params = new URLSearchParams();
   if (opts.events) params.set('events', 'true');
@@ -666,6 +811,44 @@ async function printDialogueEvents(baseUrl, headers, runId, opts = {}) {
   }
 }
 
+async function printAgentNext(baseUrl, headers, runId, opts = {}) {
+  const { json = false, checkpointMode = 'service', failOnCheckpoint = true } = opts;
+  const data = await fetchRun(baseUrl, headers, runId, { events: true });
+  const events = compactDialogueEvents(buildDialogueEvents(runId, { ...data, checkpointMode }));
+  const action = buildNextAction(runId, events, data);
+  if (json) {
+    console.log(JSON.stringify(action, null, 2));
+  } else if (action.status === 'failed') {
+    console.log(`failed: ${action.error?.message || 'Makaron run failed'}`);
+    console.log(`inspect: ${action.next_commands.inspect}`);
+  } else if (action.status === 'needs_approval') {
+    console.log(`needs_approval: ${action.checkpoint.id}`);
+    if (action.checkpoint.text) console.log(action.checkpoint.text);
+    console.log(`approve: ${action.next_commands.approve}`);
+    console.log(`revise: ${action.next_commands.revise}`);
+    console.log(`ask_user: ${action.next_commands.ask_user}`);
+    console.log(`continue: ${action.next_commands.continue}`);
+    console.log(`inspect: ${action.next_commands.inspect}`);
+  } else if (action.status === 'has_artifacts') {
+    for (const artifact of action.undelivered_artifacts || action.artifacts) {
+      console.log(`${artifact.kind} ${artifact.status}${artifact.url ? ` ${artifact.url}` : ''}`);
+    }
+    if (action.next_commands.deliver) console.log(`deliver: ${action.next_commands.deliver}`);
+    console.log(`inspect: ${action.next_commands.inspect}`);
+  } else if (action.status === 'running') {
+    console.log('running');
+    console.log(`inspect: ${action.next_commands.inspect}`);
+  } else if (action.status === 'delivered') {
+    console.log('delivered');
+    console.log(`inspect: ${action.next_commands.inspect}`);
+  } else {
+    console.log('ready');
+    console.log(`inspect: ${action.next_commands.inspect}`);
+  }
+  if (action.status === 'needs_approval' && failOnCheckpoint) process.exit(3);
+  if (action.status === 'failed') process.exit(1);
+}
+
 function recordApproval(runId, messageId, choice, note) {
   const approvals = loadApprovals();
   const approval = {
@@ -683,6 +866,24 @@ function recordApproval(runId, messageId, choice, note) {
   console.log(JSON.stringify(approval));
 }
 
+function recordDelivery(runId, artifactId, opts = {}) {
+  const deliveries = loadDeliveries();
+  const delivery = {
+    type: 'delivery',
+    id: `delivery_${Date.now()}`,
+    runId,
+    artifactId,
+    status: 'recorded',
+    createdAt: new Date().toISOString(),
+  };
+  if (opts.channel) delivery.channel = opts.channel;
+  if (opts.messageId) delivery.messageId = opts.messageId;
+  if (opts.note) delivery.note = opts.note;
+  deliveries.push(delivery);
+  saveDeliveries(deliveries);
+  console.log(JSON.stringify(delivery));
+}
+
 // ─── Watch (incremental event stream) ───────────────────────────────────────
 
 async function watchRun(baseUrl, headers, runId, opts = {}) {
@@ -1317,6 +1518,21 @@ if (command === '--version' || command === '-v' || command === 'version') {
     }
     await watchRun(baseUrl, headers, runId, { interval, jsonl });
 
+  } else if (sub === 'next') {
+    const runId = args[2];
+    if (!runId) { console.error('Usage: makaron responses next <runId> [--json] [--checkpoint-mode service|off] [--no-fail]'); process.exit(1); }
+    let jsonOutput = false, checkpointMode = 'service', failOnCheckpoint = true;
+    for (let i = 3; i < args.length; i++) {
+      if (args[i] === '--json') jsonOutput = true;
+      else if (args[i] === '--checkpoint-mode' && args[i + 1]) checkpointMode = args[++i];
+      else if (args[i] === '--no-fail') failOnCheckpoint = false;
+    }
+    if (!['service', 'off'].includes(checkpointMode)) {
+      console.error('--checkpoint-mode must be service or off');
+      process.exit(1);
+    }
+    await printAgentNext(baseUrl, headers, runId, { json: jsonOutput, checkpointMode, failOnCheckpoint });
+
   } else if (sub === 'events' || sub === 'timeline') {
     const runId = args[2];
     if (!runId) { console.error(`Usage: makaron responses ${sub} <runId> [--jsonl] [--compact] [--checkpoint-mode service|off] [--follow] [--interval <ms>] [--fail-on-unapproved]`); process.exit(1); }
@@ -1335,19 +1551,51 @@ if (command === '--version' || command === '-v' || command === 'version') {
     }
     await printDialogueEvents(baseUrl, headers, runId, { interval, jsonl, follow, failOnUnapproved, compact, checkpointMode });
 
-  } else if (['approve', 'revise', 'ask-user', 'continue'].includes(sub)) {
+  } else if (sub === 'deliver') {
+    const artifactId = args[2];
+    if (!artifactId) { console.error('Usage: makaron responses deliver <artifactId> --run <runId> [--channel <name>] [--message-id <id>] [--note <text>]'); process.exit(1); }
+    let runId = null, note = null, channel = null, messageId = 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 if (args[i] === '--channel' && args[i + 1]) channel = args[++i];
+      else if (args[i] === '--message-id' && args[i + 1]) messageId = args[++i];
+      else noteParts.push(args[i]);
+    }
+    if (!runId) { console.error('Usage: makaron responses deliver <artifactId> --run <runId> [--channel <name>] [--message-id <id>] [--note <text>]'); process.exit(1); }
+    if (!note && noteParts.length) note = noteParts.join(' ');
+    recordDelivery(runId, artifactId, { note, channel, messageId });
+
+  } else if (sub === 'handle' || ['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;
+    if (!messageId) {
+      console.error(sub === 'handle'
+        ? 'Usage: makaron responses handle <messageId> --run <runId> --choice approve|revise|ask_user|continue [--note <text>]'
+        : `Usage: makaron responses ${sub} <messageId> --run <runId> [--note <text>]`);
+      process.exit(1);
+    }
+    let runId = null, note = null, choice = sub === 'handle' ? null : sub;
     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 if (args[i] === '--choice' && args[i + 1]) choice = args[++i];
       else noteParts.push(args[i]);
     }
-    if (!runId) { console.error(`Usage: makaron responses ${sub} <messageId> --run <runId> [--note <text>]`); process.exit(1); }
+    if (!runId || !choice) {
+      console.error(sub === 'handle'
+        ? 'Usage: makaron responses handle <messageId> --run <runId> --choice approve|revise|ask_user|continue [--note <text>]'
+        : `Usage: makaron responses ${sub} <messageId> --run <runId> [--note <text>]`);
+      process.exit(1);
+    }
+    choice = choice === 'ask-user' ? 'ask_user' : choice;
+    if (!['approve', 'revise', 'ask_user', 'continue'].includes(choice)) {
+      console.error('--choice must be approve, revise, ask_user, or continue');
+      process.exit(1);
+    }
     if (!note && noteParts.length) note = noteParts.join(' ');
-    recordApproval(runId, messageId, sub === 'ask-user' ? 'ask_user' : sub, note);
+    recordApproval(runId, messageId, choice, note);
 
   } else if (sub === 'list') {
     let projectId = null;
@@ -1372,6 +1620,9 @@ 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 next <runId> --json          New Agent entry: compact timeline + checkpoint guidance
+  responses handle <messageId> --run <runId> --choice approve|revise|ask_user|continue
+  responses deliver <artifactId> --run <runId>   Record artifact delivered to the user
   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
@@ -1816,6 +2067,9 @@ Commands:
 
   responses get <runId>              Get run status and results
   responses get <runId> --wait       Poll until completed
+  responses next <runId> --json      New Agent entry: compact timeline + checkpoint guidance
+  responses handle <messageId> --run <runId> --choice approve|revise|ask_user|continue
+  responses deliver <artifactId> --run <runId>   Record artifact delivered to the user
   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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "makaron-cli",
-  "version": "0.7.10",
+  "version": "0.8.1",
   "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,24 @@ Outputs one JSON per line as artifacts appear:
 {"event":"done","status":"completed"}
 ```
 
+### New Agent quickstart
+
+For a new Agent, keep the default service flow to two response commands:
+
+```bash
+npx makaron-cli responses next <runId> --json
+npx makaron-cli responses handle <messageId> --run <runId> --choice approve
+npx makaron-cli responses deliver <artifactId> --run <runId> --channel feishu --message-id <messageId>
+```
+
+`responses next` emits a compact timeline, detects text-only checkpoints for creative/service work, and returns `next_commands` when the Agent must handle a Makaron message before waiting for artifacts. It exits with code `3` on an unhandled checkpoint so wrappers stop instead of silently waiting. After handling a checkpoint, run the returned `next_commands.inspect` command to continue. While the run is still generating, it returns `status: "running"` and `blocking: false`. If completed image/video artifacts exist and have not been delivered, it returns `status: "has_artifacts"` and `blocking: true` with compact `undelivered_artifacts` entries containing `kind`, `status`, `url`, `fileName`, and `contentType` when available, plus `next_commands.deliver`; the Agent must send the artifact URL to the user, then record delivery with `responses deliver`. A non-checkpoint response returns `status: "ready"` or `status: "delivered"`. If a run failed, `responses next --json` prints `status: "failed"` and `blocking: true` plus `error.type`, `error.message`, `error.recoverable`, `error.detail`, and `next_command` to stdout before exiting `1`, so wrappers can parse the failure without scraping stderr. Use `--no-fail` to inspect checkpoint JSON without failing. For pure Q&A runs, use:
+
+```bash
+npx makaron-cli responses next <runId> --json --checkpoint-mode off
+```
+
+`responses handle` is the single checkpoint action command. Valid choices are `approve`, `revise`, `ask_user`, and `continue`. `responses deliver` records that a completed artifact was actually delivered to the user, preventing repeated delivery prompts.
+
 ### Dialogue events for external Agents
 
 Use this when another Agent needs to read what Makaron said, handle text checkpoints, and relay artifacts without inventing customer-service wording.
@@ -137,6 +155,8 @@ npx makaron-cli responses events <runId> --jsonl
 # pure Q&A view: npx makaron-cli responses timeline <runId> --jsonl --checkpoint-mode off
 ```
 
+`events` and `timeline` are lower-level commands. New Agents should start with `responses next` and use these only when they need raw event streams.
+
 Events use only three factual types:
 
 ```json
@@ -152,6 +172,7 @@ 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>
+npx makaron-cli responses handle msg_1 --run <runId> --choice approve
 ```
 
 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:
@@ -299,18 +320,26 @@ 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
+if ! NEXT=$(npx makaron-cli responses next "$RUN_ID" --json); then
+  STATUS=$(echo "$NEXT" | jq -r .status)
+  if [ "$STATUS" = "needs_approval" ]; then
+    MSG_ID=$(echo "$NEXT" | jq -r .checkpoint.id)
+    TEXT=$(echo "$NEXT" | jq -r .checkpoint.text)
+    send_message "$TEXT"
+    npx makaron-cli responses handle "$MSG_ID" --run "$RUN_ID" --choice ask_user
+    exit 3
+  elif [ "$STATUS" = "failed" ]; then
+    send_message "$(echo "$NEXT" | jq -r .error.message)"
+    exit 1
+  fi
+fi
+
+NEXT=$(npx makaron-cli responses next "$RUN_ID" --json --no-fail)
+if [ "$(echo "$NEXT" | jq -r .status)" = "has_artifacts" ]; then
+  ARTIFACT_ID=$(echo "$NEXT" | jq -r ".undelivered_artifacts[0].id")
+  ARTIFACT_URL=$(echo "$NEXT" | jq -r ".undelivered_artifacts[0].url")
+  DELIVERY_MESSAGE_ID=$(send_message "$ARTIFACT_URL")
+  npx makaron-cli responses deliver "$ARTIFACT_ID" --run "$RUN_ID" --channel feishu --message-id "$DELIVERY_MESSAGE_ID"
 fi
 
 RESULT=$(npx makaron-cli responses get "$RUN_ID" --wait --json)