@agentled/cli 0.1.6 → 0.5.0

package/patterns/v1/07-error-handling.md

@@ -0,0 +1,157 @@
+# 07 — Error handling: skip vs stop vs wait
+
+**Problem**: Developers use the same error behavior (`stop` or `skip`) everywhere, causing workflows to either halt on recoverable errors or continue silently with missing data.
+
+**Why it fails silently**: `skip` silently passes empty/null data to downstream steps, which then produce wrong outputs with no error. `stop` halts workflows on optional steps that should have been bypassed. Neither produces a visible failure at the wrong step — the failure surfaces later, in a confusing place.
+
+---
+
+## The three behaviors
+
+Every entry condition has an `onCriteriaFail` setting that determines what happens when the condition isn't met:
+
+| Value | What it does | When to use |
+|---|---|---|
+| `skip` | Skip this step, pass `null`/empty to downstream steps, continue execution | Optional step — workflow is valid without it |
+| `stop` | Halt the entire execution immediately | Hard prerequisite — nothing downstream is meaningful without this step |
+| `wait` | Block this step until criteria become true | Async dependency — waiting for a loop or parallel group to finish |
+
+---
+
+## Anti-pattern: stop everywhere
+
+```yaml
+# Wrong: using stop for an optional enrichment step
+- id: enrich-linkedin
+  type: app-action
+  entryConditions:
+    onCriteriaFail: "stop"       # ← wrong: this is optional
+    criteria:
+      - variable: "{{input.linkedinUrl}}"
+        operator: "isNotNull"
+# If linkedinUrl is missing: entire workflow halts.
+# But the workflow could run fine without LinkedIn data.
+```
+
+```yaml
+# Correct: optional enrichment step uses skip
+- id: enrich-linkedin
+  type: app-action
+  entryConditions:
+    onCriteriaFail: "skip"       # ← correct: skip if no URL
+    conditionText: "Skip LinkedIn enrichment if no URL provided"
+    criteria:
+      - variable: "{{input.linkedinUrl}}"
+        operator: "isNotNull"
+```
+
+---
+
+## Anti-pattern: skip for hard prerequisites
+
+```yaml
+# Wrong: using skip for required input validation
+- id: validate-required-fields
+  type: code
+  entryConditions:
+    onCriteriaFail: "skip"       # ← wrong: nothing downstream works without this
+    criteria:
+      - variable: "{{input.companyDomain}}"
+        operator: "isNotNull"
+# If domain is missing: validation is skipped.
+# Next step tries to enrich with null domain.
+# Enrichment fails with a confusing error 3 steps later.
+```
+
+```yaml
+# Correct: hard prerequisite uses stop
+- id: validate-required-fields
+  type: code
+  entryConditions:
+    onCriteriaFail: "stop"       # ← correct: stop early with a clear failure
+    conditionText: "Company domain is required"
+    criteria:
+      - variable: "{{input.companyDomain}}"
+        operator: "isNotNull"
+```
+
+Fail fast. A clear stop at the prerequisite is better than a confusing error 5 steps later.
+
+---
+
+## `wait`: blocking on async completion
+
+`wait` is for a specific use case: blocking a step until an async process finishes. The two common cases are loop completion and parallel group completion.
+
+```yaml
+# Wait for a loop to finish before consuming its output
+- id: aggregate-results
+  type: ai-action
+  entryConditions:
+    onCriteriaFail: "wait"
+    conditionText: "Wait for all enrichment loop iterations to complete"
+    criteria:
+      - type: loop_completion
+        stepId: enrich-loop
+        operator: "=="
+        value: true
+  prompt: "Summarize these enriched companies: {{steps.enrich-loop.outputs}}"
+```
+
+`wait` is not a general-purpose retry mechanism. It's specifically for dependency ordering in async workflows.
+
+---
+
+## Decision guide
+
+Ask these questions in order:
+
+**1. Is this step required for the workflow to produce a valid output?**
+- Yes → `stop`
+- No → continue to question 2
+
+**2. Is this step waiting for another step/loop/group to finish?**
+- Yes → `wait`
+- No → `skip`
+
+Examples:
+
+| Step | Required? | Async wait? | Use |
+|---|---|---|---|
+| "Validate required domain field" | Yes | No | `stop` |
+| "Enrich LinkedIn (optional)" | No | No | `skip` |
+| "Send Slack alert (if webhook configured)" | No | No | `skip` |
+| "Aggregate loop results" | Yes | Yes (loop) | `wait` |
+| "Score company (ICP match required)" | Yes | No | `stop` |
+| "Add CRM note (nice to have)" | No | No | `skip` |
+
+---
+
+## Handling downstream null data after skip
+
+When a step is skipped, its outputs are `null` or empty. Downstream steps that reference those outputs must handle nulls gracefully:
+
+```yaml
+# Pattern: null-safe reference in AI prompt
+prompt: |
+  Company: {{steps.enrich.company.name | default: "Unknown"}}
+  LinkedIn headline: {{steps.enrich-linkedin.headline | default: "Not available"}}
+  Score this company based on what's available.
+```
+
+Or use a code step to normalize before passing to downstream AI steps:
+
+```javascript
+// Code step: normalize potentially-null enrichment data
+return {
+  name: input.enrichData?.name ?? input.rawInput.companyName,
+  industry: input.enrichData?.industry ?? "Unknown",
+  employees: input.enrichData?.employees ?? null,
+};
+```
+
+---
+
+## One-line rule
+
+> Use `skip` for optional steps, `stop` for hard prerequisites, and `wait` for async dependencies — and always handle `null` outputs from skipped steps in downstream steps.

package/patterns/v1/08-composed-email-approval.md

@@ -0,0 +1,130 @@
+# 08 — Composed email with approval gate: outreach that ships safely
+
+**Problem**: Agents build outreach by chaining a "draft email" AI step with a separate "gmail send" app action. This skips the user-review step, sends unreviewed drafts, and can't display the email in the pending-approval UI.
+
+**Why it fails silently**: A raw draft-then-send pipeline has no concept of "email" as a first-class artifact. The orchestrator's approval UI won't render a preview, the `schedule-email` action can't fire, and there's no audit trail of what was sent to whom. The workflow looks correct at authoring time and may even work in testing — until a real recipient gets an unreviewed draft.
+
+---
+
+## The composed-email shape
+
+An email step is a specialized `aiAction` with four coupled pieces:
+
+1. **Prompt type**: `pipelineStepPrompt.type: "email"` — tells the orchestrator this is an email step (not a generic AI step).
+2. **Renderer**: `renderer: { type: "Email", config: { fromContextKey: "outreachProfile" } }` — tells the UI to render the result as an email preview, pulling sender info from a context input page.
+3. **Integrations declaration**: declares that the workflow needs a connected email account (Gmail or Outlook).
+4. **Approval + send action**: `onApproval: { action: "schedule-email" }` + `next.conditions.approvalRequired: true` — the step waits for user approval, then the `schedule-email` action actually sends the email.
+
+All four must be present. Omit any one and the step silently degrades: no preview, no approval gate, or no send.
+
+## Required input page: outreachProfile
+
+Sender identity lives on a workflow-level `inputPages` entry with `contextKey: "outreachProfile"`. Without this page, the `{{context.outreachProfile.fromEmail}}` template resolves to empty and the email has no sender.
+
+```json
+{
+  "title": "Outreach Profile",
+  "pathname": "outreach-profile",
+  "configuration": {
+    "contextKey": "outreachProfile",
+    "shortDescriptionFields": ["name", "fromEmail"],
+    "fields": [
+      { "name": "name", "label": "Sender name", "type": "text", "required": true },
+      { "name": "fromEmailLabel", "label": "From name", "type": "text", "required": true },
+      { "name": "fromEmail", "label": "From email", "type": "connected_emails_selector_multiple", "required": true },
+      { "name": "replyToEmail", "label": "Reply-to (optional)", "type": "text" }
+    ]
+  }
+}
+```
+
+## Full composed-email step (copy-paste)
+
+```json
+{
+  "id": "send-outreach-email",
+  "type": "aiAction",
+  "name": "Send Outreach Email",
+  "pipelineStepPrompt": {
+    "type": "email",
+    "template": "Draft a personalized email to {{steps.enrich.contact.fullName}} at {{steps.enrich.company.name}} introducing our offering. Keep it warm, concise, and specific to their role.",
+    "responseStructure": {
+      "email": {
+        "from": "{{context.outreachProfile.fromEmail}}",
+        "to": "{{steps.enrich.contact.email}}",
+        "subject": "",
+        "body": "",
+        "bodyType": "html"
+      }
+    }
+  },
+  "renderer": {
+    "type": "Email",
+    "config": { "fromContextKey": "outreachProfile" }
+  },
+  "integrations": [
+    {
+      "type": "oneOf",
+      "label": "Email",
+      "connectorType": "email",
+      "options": [
+        { "name": "Gmail", "url": "https://gmail.com", "isUserAccountConnectionRequired": true },
+        { "name": "Outlook", "url": "https://outlook.com", "isUserAccountConnectionRequired": true }
+      ],
+      "selectionHint": "preferConnected"
+    }
+  ],
+  "onApproval": {
+    "executedText": "Email sent by {{name}} at {{date}}",
+    "failedText": "Email failed to send.",
+    "action": "schedule-email"
+  },
+  "creditCost": 5,
+  "next": { "stepId": "done", "conditions": { "approvalRequired": true } }
+}
+```
+
+## Anti-patterns
+
+**Draft + Gmail send (no approval):**
+
+```
+❌ draft-email (aiAction) → gmail.send-email (appAction) → done
+```
+
+No preview, no user approval, and the drafted body is written as a plain string instead of the structured `email` object — Gmail's send-email action expects specific fields (`to`, `subject`, `html`) that the draft prompt has no way to produce reliably.
+
+**Missing `pipelineStepPrompt.type: "email"`:**
+
+```yaml
+pipelineStepPrompt:
+  template: "..."
+  responseStructure:
+    email: { from, to, subject, body, bodyType }
+# ❌ No `type: "email"` — the renderer falls back to a generic JSON view,
+# and the orchestrator treats this as a regular aiAction (no schedule-email).
+```
+
+**Email body as plain text when `bodyType: "html"`:**
+
+Email clients render HTML bodies literally if the wrapping element is missing. Always generate email-safe HTML (`<p>`, `<br>`, `<a>`, `<strong>` — no CSS blocks, no `<script>`). Don't use markdown — the approval UI won't convert it.
+
+**No `outreachProfile` input page:**
+
+`{{context.outreachProfile.fromEmail}}` resolves to an empty string. The email has no sender. It may still send (from the default connected account) but you lose per-workflow sender control.
+
+## Checklist
+
+Before wiring a composed-email step into a workflow:
+
+- [ ] `context.inputPages[]` contains the `outreachProfile` page (pattern above)
+- [ ] `pipelineStepPrompt.type: "email"` is set
+- [ ] `renderer: { type: "Email", config: { fromContextKey: "outreachProfile" } }` is present
+- [ ] `integrations[]` declares the email connector (Gmail / Outlook)
+- [ ] `onApproval.action: "schedule-email"` is set
+- [ ] `next.conditions.approvalRequired: true` on the outgoing edge
+- [ ] Recipient and subject are derived from prior step output, not hardcoded
+
+## When to use a generic approval gate instead
+
+For non-email approvals (sending a Slack post, firing a webhook), use a plain `aiAction` + `next.conditions.approvalRequired: true` without the email renderer. The approval gate is a general-purpose feature; the email shape is only required when the approved artifact is an email that needs to be sent through the user's connected mailbox.

package/patterns/v1/09-reports-and-knowledge-storage.md

@@ -0,0 +1,166 @@
+# 09 — Reports, sharing, and knowledge-graph storage: closing the loop
+
+**Problem**: Agents produce analysis as free-form prose in AI step output, then either never display it or drop it into a raw JSON view. Results aren't shareable with stakeholders, aren't comparable across runs, and don't feed back into the Knowledge Graph for trend analysis or future scoring calibration.
+
+**Why it fails silently**: Without a `renderer`, an AI step's structured output is unreadable in the workspace UI. Without a `share` step, the output has no URL that can be sent to a stakeholder. Without a `knowledgeSync` step, each run's data is discarded — the second run can't learn from the first, and KPIs have no history to trend against.
+
+---
+
+## The three-part closing loop
+
+```
+... upstream steps → AI report step (with Config renderer)
+                   → [optional] share step (public URL)
+                   → [optional] composed email step (delivery)
+                   → knowledgeSync (persist to KG for trending)
+                   → milestone
+```
+
+The three pieces are independent and optional, but they compound. A report with a renderer is readable. A report with a renderer + share step is forwardable. A report with all three + knowledgeSync is how KPI dashboards actually get built.
+
+## 1. Report AI step with Config renderer
+
+The Config renderer turns structured AI output into a KPI dashboard view. Key blocks: `kpiRow`, `markdown`, `table`, `signalList`.
+
+```json
+{
+  "id": "generate-report",
+  "type": "aiAction",
+  "name": "Generate Report",
+  "pipelineStepPrompt": {
+    "template": "Analyze the data and produce a structured report.\n\nData: {{steps.evaluate.items}}",
+    "responseStructure": {
+      "summary": "string — executive summary",
+      "kpis": "object { total: number, qualified: number, avgScore: number }",
+      "items": "array of { name, score, decision }",
+      "insights": "array of strings"
+    }
+  },
+  "renderer": {
+    "type": "Config",
+    "config": {
+      "layout": {
+        "title": "Run Report",
+        "blocks": [
+          { "blockType": "kpiRow", "kpis": [
+            { "label": "Total", "valuePath": "kpis.total", "icon": "Hash" },
+            { "label": "Qualified", "valuePath": "kpis.qualified", "icon": "CheckCircle" },
+            { "label": "Avg Score", "valuePath": "kpis.avgScore", "format": "score" }
+          ]},
+          { "blockType": "markdown", "contentPath": "summary" },
+          { "blockType": "table", "arrayPath": "items", "searchable": true, "columns": [
+            { "header": "Name", "field": "name" },
+            { "header": "Score", "field": "score", "display": "score", "sortable": true },
+            { "header": "Decision", "field": "decision", "display": "badge" }
+          ]},
+          { "blockType": "signalList", "title": "Insights", "arrayPath": "insights", "variant": "signal" }
+        ]
+      }
+    }
+  },
+  "creditCost": 10,
+  "next": { "stepId": "share-report" }
+}
+```
+
+**Rule**: the `responseStructure` keys must match the renderer's `valuePath`/`arrayPath`/`contentPath` references. Drift between the two silently produces empty KPI tiles and blank tables.
+
+## 2. Share step for a public URL
+
+```json
+{
+  "id": "share-report",
+  "type": "share",
+  "name": "Create Public Report Link",
+  "shareConfig": {
+    "outputSteps": ["generate-report"],
+    "expiresInDays": 30,
+    "visibility": "public"
+  },
+  "next": { "stepId": "send-report-email" }
+}
+```
+
+Outputs `{ shareId, shareUrl, expiresAt }`. Downstream steps use `{{steps.share-report.shareUrl}}` to reference the public URL (e.g., in an email body).
+
+**When to add a share step**:
+
+- Anyone outside the workspace needs to see the report.
+- The report should remain accessible after the execution's detail page expires.
+- The workflow delivers the report via email and the body should link to the full report.
+
+**When to skip it**: internal-only dashboards where viewers already have workspace access.
+
+## 3. Knowledge-graph storage for trending
+
+Without this, each run's data vanishes. With it, you can:
+
+- Compare "today's MRR" against last month's.
+- Calibrate future AI scoring on past outcomes (see `kg.retrieve-scoring-memory`).
+- Build a timeline view of any metric.
+
+```json
+{
+  "id": "store-history",
+  "type": "knowledgeSync",
+  "name": "Store to KPI History",
+  "knowledgeSync": {
+    "source": { "stepId": "generate-report" },
+    "listKey": "kpi_history",
+    "fieldMapping": {
+      "mrr": "mrr",
+      "burn": "burn",
+      "runway_months": "runway_months",
+      "executedAt": "executedAt"
+    }
+  },
+  "next": { "stepId": "done" }
+}
+```
+
+If you're inside a loop (scoring many items per run), set `source.resultsPath: "items"` so each loop iteration produces one KG row.
+
+## Anti-patterns
+
+**AI step with no renderer:**
+
+```yaml
+type: aiAction
+responseStructure:
+  summary: string
+  kpis: { total, avgScore }
+# ❌ No renderer — the workspace UI shows raw JSON. Nobody reads it.
+```
+
+**Share step without `outputSteps`:**
+
+```yaml
+type: share
+shareConfig:
+  visibility: public
+  # ❌ Missing outputSteps — share URL renders nothing
+```
+
+**`knowledgeSync` without a clear schema:**
+
+If `listKey` doesn't already exist, the KG creates an implicit schema from the first write. Subsequent writes with different field shapes fail to index. For trending, pre-create the list with a typed schema.
+
+**Reusing `fieldMapping` values with source-side renames:**
+
+`fieldMapping` keys are source field names (from the prior step's output), values are target field names (in the KG). Flipping them silently stores the wrong data.
+
+```yaml
+# ✅ Correct: source → target
+fieldMapping:
+  mrr: monthly_revenue          # steps.extract.mrr → row.monthly_revenue
+  burn: monthly_expenses
+```
+
+## Checklist for any "report" workflow
+
+- [ ] `responseStructure` keys match every renderer `valuePath` / `arrayPath` / `contentPath`
+- [ ] Renderer `blocks` cover at least one KPI + one tabular view
+- [ ] Share step exists if report is forwardable to non-workspace users
+- [ ] If delivered via email, the email template embeds `{{steps.share.shareUrl}}`
+- [ ] `knowledgeSync` persists to a list with a typed schema (not implicit)
+- [ ] `executedAt` (or a similar timestamp) is stored so rows can be trended

package/scaffolds/README.md

@@ -0,0 +1,62 @@
+# CLI scaffolds
+
+Each `*.json` file in this directory is a **preflight-clean pipeline skeleton**
+keyed to one of the patterns in `agentic-ops/patterns/v1/` (canonical) or
+`packages/cli/patterns/v1/` (byte-identical mirror).
+
+Scaffolds are **pattern shapes, not domain templates.** The goal is to give
+an agent (or human) a known-good starting point for a structural shape —
+loop over a KG list, composed email with approval, conditional alert on
+threshold, etc. — not to ship templates for every possible business use case.
+
+## Contract
+
+Every bundled scaffold:
+
+1. Passes `agentled workflows validate --file <scaffold>` with zero errors
+   and zero warnings.
+2. Has a clear `name` and `goal` field that describes the pattern shape.
+3. References the matching agentic-ops pattern number(s) in its `description`.
+4. Uses domain-agnostic placeholder names (`candidate`, `metric_a`,
+   `entity_id`) — not specific verticals.
+
+## Catalog
+
+| Slug | Pattern(s) | Shape |
+|------|-----------|-------|
+| `minimal` | — | trigger → milestone (smallest valid pipeline) |
+| `email-polling-dedup` | 02 + 13 | schedule → fetch emails (label dedup) → loop process → add label |
+| `lead-scoring-kg` | 04 + 09 | trigger → kg.read-list → AI scoring loop → knowledgeSync → report |
+| `list-match-email` | 08 | trigger → kg.read-list → AI match top candidates → composed email (approval gate) → knowledgeSync |
+| `extract-threshold-alert` | 06 + 09 | trigger → AI extract → threshold check (code) → external update → conditional Slack alert → knowledgeSync |
+| `ai-with-tools` | — | trigger → `aiActionWithTools` (web_search + workspace_memory) → milestone |
+
+## Bring your own scaffolds
+
+The bundled set is deliberately small. Workspaces, teams, or customers who
+have recurring workflow shapes should maintain their own scaffold library
+outside this CLI release cycle:
+
+1. Drop JSON files in `~/.agentled/scaffolds/` or set
+   `AGENTLED_SCAFFOLDS_DIR=/path/to/your/scaffolds`.
+2. Run `agentled workflows scaffold --list` — local scaffolds appear with
+   a `[local]` tag next to their name.
+3. Local slugs **shadow bundled ones** with the same name, so a team can
+   override `list-match-email.json` with a locally-tuned version without
+   forking the CLI.
+
+Any JSON in those directories must also pass `workflows validate --file`.
+The CLI doesn't gate this at load time — but a scaffold that fails preflight
+will waste an operator's time, which is exactly what the scaffold set is
+meant to prevent.
+
+## Editing the bundled set
+
+The bundled scaffolds are meant to stay small and pattern-focused. If you
+want to propose a new one:
+
+- It must map to an existing agentic-ops pattern (or come with a new pattern).
+- It must be domain-agnostic — name fields `candidate` / `metric_a` /
+  `entity_id`, not `mentor` / `mrr` / `companyId`.
+- The `description` must state the pattern number it demonstrates.
+- Commit both the scaffold and a preflight test verifying it passes.

package/scaffolds/ai-with-tools.json

@@ -0,0 +1,49 @@
+{
+  "name": "AI with Runtime Tools",
+  "goal": "AI step that can call web_search + workspace_memory at runtime (aiActionWithTools shape).",
+  "description": "Starting shape for an AI step that needs to pull fresh web context and recall/store workspace memory. Replace the prompt and response structure for your task.",
+  "status": "draft",
+  "context": {
+    "executionInputConfig": {
+      "title": "Research + Recall",
+      "description": "Provide a topic or entity to research.",
+      "runCTALabel": "Run",
+      "fields": [
+        { "name": "topic", "label": "Topic or entity", "type": "text", "required": true }
+      ]
+    }
+  },
+  "steps": [
+    {
+      "id": "start",
+      "type": "trigger",
+      "name": "Manual Start",
+      "pipelineStepStartConditions": { "trigger": { "type": "manual" } },
+      "next": { "stepId": "analyze" }
+    },
+    {
+      "id": "analyze",
+      "type": "aiActionWithTools",
+      "name": "Analyze with Tools",
+      "tools": [
+        { "type": "builtin", "name": "web_search", "builtinType": "web_search" },
+        { "type": "builtin", "name": "workspace_memory", "builtinType": "workspace_memory" }
+      ],
+      "pipelineStepPrompt": {
+        "template": "Research the topic: {{input.topic}}.\n\nUse `web_search` for fresh external context. Use `workspace_memory` to recall what we already know about {{input.topic}} (call action \"search\" with a relevant query) and to `store` any durable fact you learn (category=fact, confidence 70-100).\n\nReturn a concise structured summary.",
+        "responseStructure": {
+          "summary": "string — 3-5 sentences synthesising research + prior memory",
+          "sources": "array of strings — URLs cited from web_search",
+          "stored_memories": "array of strings — keys of new memories written (if any)"
+        }
+      },
+      "creditCost": 10,
+      "next": { "stepId": "done" }
+    },
+    {
+      "id": "done",
+      "type": "milestone",
+      "name": "Done"
+    }
+  ]
+}

package/scaffolds/email-polling-dedup.json

@@ -0,0 +1,71 @@
+{
+  "name": "Email Polling + Dedup",
+  "goal": "Poll Gmail for new emails, process each, and mark them with a label so they're never reprocessed.",
+  "description": "Pattern 02 (dedup-gates). Default intake pattern — prefer this over event triggers unless you need sub-minute latency.",
+  "status": "draft",
+  "steps": [
+    {
+      "id": "schedule",
+      "type": "trigger",
+      "name": "Daily poll",
+      "pipelineStepStartConditions": {
+        "trigger": {
+          "type": "schedule",
+          "config": { "frequency": "daily", "time": "07:00" }
+        }
+      },
+      "next": { "stepId": "ensure-label" }
+    },
+    {
+      "id": "ensure-label",
+      "type": "appAction",
+      "name": "Ensure Processed Label",
+      "app": { "id": "gmail", "actionId": "GMAIL_CREATE_LABEL", "source": "composio" },
+      "stepInputData": { "name": "processed" },
+      "next": { "stepId": "fetch-emails" }
+    },
+    {
+      "id": "fetch-emails",
+      "type": "appAction",
+      "name": "Fetch New Emails",
+      "app": { "id": "gmail", "actionId": "GMAIL_FETCH_EMAILS", "source": "composio" },
+      "stepInputData": {
+        "query": "-label:processed newer_than:1d",
+        "max_results": "50"
+      },
+      "next": { "stepId": "process" }
+    },
+    {
+      "id": "process",
+      "type": "aiAction",
+      "name": "Process Email",
+      "loopConfig": {
+        "source": "executionContent",
+        "config": { "stepId": "fetch-emails", "field": "messages" },
+        "ItemAlias": "emailItem"
+      },
+      "pipelineStepPrompt": {
+        "template": "Process this email:\n\nFrom: {{emailItem.from}}\nSubject: {{emailItem.subject}}\n\n{{emailItem.body}}",
+        "responseStructure": { "summary": "string", "action": "string" }
+      },
+      "creditCost": 8,
+      "next": { "stepId": "mark-processed" }
+    },
+    {
+      "id": "mark-processed",
+      "type": "appAction",
+      "name": "Mark as Processed",
+      "app": { "id": "gmail", "actionId": "GMAIL_ADD_LABEL", "source": "composio" },
+      "stepInputData": {
+        "message_id": "{{emailItem.id}}",
+        "label_id": "{{steps.ensure-label.id}}"
+      },
+      "next": { "stepId": "done" }
+    },
+    {
+      "id": "done",
+      "type": "milestone",
+      "name": "Done"
+    }
+  ]
+}