makaron-cli 0.8.0 → 0.8.1

package/README.md

@@ -141,15 +141,16 @@ 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. A non-checkpoint response returns `status: "ready"` or `status: "has_artifacts"`. Use `--no-fail` to inspect the JSON without failing. For pure Q&A runs, use:
+`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 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
 
@@ -338,9 +339,20 @@ if ! NEXT=$(npx makaron-cli responses next "$RUN_ID" --json); then
     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

@@ -133,15 +133,16 @@ 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. A non-checkpoint response returns `status: "ready"` or `status: "has_artifacts"`. Use `--no-fail` to inspect the JSON without failing. For pure Q&A runs, use:
+`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 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
 
@@ -327,9 +328,20 @@ if ! NEXT=$(npx makaron-cli responses next "$RUN_ID" --json); then
     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;
@@ -632,21 +652,84 @@ 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 `npx makaron-cli responses handle ${messageId} --run ${runId} --choice ${choice}`;
+  return `${buildCliCommand()} responses handle ${messageId} --run ${runId} --choice ${choice}`;
 }
 
 function buildNextCommand(runId) {
-  return `npx makaron-cli responses next ${runId} --json`;
+  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) {
+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: {
@@ -659,11 +742,30 @@ function buildNextAction(runId, events) {
       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 ? 'has_artifacts' : 'ready',
+    status: artifacts.length ? 'delivered' : 'ready',
+    blocking: false,
     runId,
     artifacts,
     approvals,
+    deliveries: loadDeliveries().filter(item => item.runId === runId),
     next_commands: {
       inspect: buildNextCommand(runId),
     },
@@ -713,9 +815,12 @@ 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);
+  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);
@@ -725,14 +830,23 @@ async function printAgentNext(baseUrl, headers, runId, opts = {}) {
     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.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) {
@@ -752,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 = {}) {
@@ -1419,6 +1551,22 @@ if (command === '--version' || command === '-v' || command === 'version') {
     }
     await printDialogueEvents(baseUrl, headers, runId, { interval, jsonl, follow, failOnUnapproved, compact, checkpointMode });
 
+  } 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) {
@@ -1474,6 +1622,7 @@ if (command === '--version' || command === '-v' || command === 'version') {
   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
@@ -1920,6 +2069,7 @@ Commands:
   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.8.0",
+  "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

@@ -133,15 +133,16 @@ 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. A non-checkpoint response returns `status: "ready"` or `status: "has_artifacts"`. Use `--no-fail` to inspect the JSON without failing. For pure Q&A runs, use:
+`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 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
 
@@ -327,9 +328,20 @@ if ! NEXT=$(npx makaron-cli responses next "$RUN_ID" --json); then
     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)
 ```