@codemation/agent-skills 0.4.0 → 0.5.2

package/skills/builder/msgraph/SKILL.md

@@ -0,0 +1,338 @@
+---
+name: msgraph
+description: Builds a Codemation workflow against Microsoft 365 via Microsoft Graph — trigger on new Outlook mail, reply, patch (read-state/categories/move), and reach OneDrive/Excel. Use whenever a workflow reads from or writes to a Microsoft 365 mailbox, OneDrive, or Excel workbook.
+compatibility: Requires @codemation/core-nodes-msgraph. A Microsoft Graph OAuth credential binds on slot "auth".
+tags: msgraph, microsoft, outlook, email, onedrive, excel, integration
+uses: "@codemation/core-nodes-msgraph, @codemation/core-nodes, @codemation/core"
+---
+
+# Codemation Microsoft Graph
+
+`@codemation/core-nodes-msgraph` covers three Microsoft 365 surfaces, each binding a Graph OAuth
+credential on slot **`"auth"`**:
+
+- **Outlook mail** — trigger on new mail, plus reply / send / patch / get / attachment-download / folder-resolve.
+- **OneDrive** — resolve, list, get, download, upload, copy, list-drives.
+- **Excel** — open/close workbook, list/add sheets, read/write/style ranges.
+
+Mail and Excel-on-mailbox bind the **`msgraph-mail-oauth`** credential type; OneDrive/Excel-on-drive
+bind **`msgraph-drive-oauth`**. The two differ only in granted scopes — pick by surface.
+
+These nodes are `defineNode` / `definePollingTrigger` definitions: instantiate with
+**`node.create(config, label?, id?)`**, not `new`. Config fields accept per-item expressions via
+`itemExpr` (type the expression with the item shape, e.g. `itemExpr<string, MsGraphMailItem>`).
+
+**Discipline:** author straight from this file, then run `verify_workflow` and fix only what it flags.
+Use `workflow-dsl` for the surrounding builder, trigger, and flow-control surface.
+
+## The default flow: trigger on new mail → reply
+
+`onNewMsGraphMailTrigger` polls a folder and emits one `MsGraphMailItem` per new message.
+`outlookMessageReplyNode` replies by `messageId`. Type the `.create<MsGraphMailItem>` call so the
+`itemExpr` callbacks see the trigger payload.
+
+```typescript
+import { createWorkflowBuilder } from "@codemation/core-nodes";
+import { itemExpr } from "@codemation/core";
+import { onNewMsGraphMailTrigger, outlookMessageReplyNode, type MsGraphMailItem } from "@codemation/core-nodes-msgraph";
+
+export default createWorkflowBuilder({ id: "wf.msgraph.acknowledge", name: "Acknowledge inbound mail" })
+  .trigger(
+    // Polls the mailbox folder; default filter is "isRead eq false". Slot "auth" must be bound.
+    onNewMsGraphMailTrigger.create(
+      { mailbox: "me", folderId: "inbox", filter: "isRead eq false" },
+      "On new mail",
+      "mail-trigger",
+    ),
+  )
+  .then(
+    outlookMessageReplyNode.create<MsGraphMailItem>(
+      {
+        mailbox: "me",
+        messageId: itemExpr<string, MsGraphMailItem>(({ item }) => item.json.messageId),
+        body: itemExpr<string, MsGraphMailItem>(
+          ({ item }) => `Thanks — we received "${item.json.subject ?? "your email"}" and are processing it.`,
+        ),
+        bodyType: "text", // or "html"
+        // replyAll: true / forward: true (forward requires `to`) / draftOnly: true to save without sending
+      },
+      "Reply",
+      "reply",
+    ),
+  )
+  .build();
+```
+
+## Mail item shape
+
+`onNewMsGraphMailTrigger` emits `MsGraphMailItem` — import the type, do not redefine it:
+
+```text
+MsGraphMailItem = {
+  messageId: string;                 // target for reply / patch / get
+  conversationId?: string;
+  receivedDateTime: string;
+  internetMessageId?: string;
+  replyToMessageId?: string;
+  from?: { name?: string; address?: string };
+  to: { name?: string; address?: string }[];
+  cc?, bcc?: same shape;
+  subject?: string;
+  bodyText?: string;                 // prefer this for an LLM step
+  bodyHtml?: string;
+  attachments?: MsGraphMailAttachment[];   // metadata only — see below
+  headers?: Record<string, string>;
+  skippedAttachments?: { name; size; reason: "size-cap" }[];
+}
+```
+
+Trigger options: `{ mailbox; folderId?="inbox"; filter?; downloadAttachments?; attachmentSizeCapBytes?; pollIntervalMs? }`.
+`mailbox: "me"` watches the credential owner's inbox; a UPN watches a shared mailbox (needs
+`Mail.Read.Shared`). `filter` is a raw Graph OData `$filter` (e.g. `"hasAttachments eq true"`).
+
+## Patch a message (mark read, categorize, move)
+
+`outlookMessagePatchNode` is the common "tidy up after handling" step. Chain it directly off the
+trigger.
+
+```typescript
+import { createWorkflowBuilder } from "@codemation/core-nodes";
+import { itemExpr } from "@codemation/core";
+import { onNewMsGraphMailTrigger, outlookMessagePatchNode, type MsGraphMailItem } from "@codemation/core-nodes-msgraph";
+
+export default createWorkflowBuilder({ id: "wf.msgraph.triage", name: "Triage inbound mail" })
+  .trigger(onNewMsGraphMailTrigger.create({ mailbox: "me" }, "On new mail", "trigger"))
+  .then(
+    outlookMessagePatchNode.create<MsGraphMailItem>(
+      {
+        mailbox: "me",
+        messageId: itemExpr<string, MsGraphMailItem>(({ item }) => item.json.messageId),
+        isRead: true,
+        categories: ["Processed"],
+        move: { folderId: "Archive" }, // a well-known name or a folder id from outlookFolderResolveNode
+      },
+      "Mark processed",
+      "mark-processed",
+    ),
+  )
+  .build();
+```
+
+## Attachments → binary
+
+Set the trigger's `downloadAttachments: true` and the trigger's `execute` step stores each attachment's
+bytes via `ctx.binary` under a slot named after the attachment (`name`, or `inline:{contentId}` for
+embedded images). `item.json.attachments` carries metadata only
+(`{ id, name, contentType, size, isInline?, contentId? }`) — never the payload. To pull one attachment
+on demand later, use `outlookAttachmentDownloadNode` (`{ mailbox?, messageId, attachmentId, binarySlot?="attachment" }`).
+Read the stored bytes off `item.binary[slot]`; feed them to `document-ai` for OCR.
+
+## Node catalog
+
+Instantiate each with `node.create(config, label?, id?)`. Bind `"auth"` to the matching credential type.
+
+```text
+Outlook mail  (msgraph-mail-oauth)
+  onNewMsGraphMailTrigger      { mailbox; folderId?; filter?; downloadAttachments?; pollIntervalMs? }
+  outlookMessageReplyNode      { mailbox; messageId; body; bodyType; replyAll?; forward?; to?; cc?; bcc?; draftOnly?; attachments? }
+  outlookMessageSendNode       { mailbox; to; subject; body; bodyType; cc?; bcc?; attachments?; draftOnly? }
+  outlookMessagePatchNode      { mailbox; messageId; isRead?; categories?; move?: { folderId } }
+  outlookMessageGetNode        { mailbox; messageId; expandAttachments? }
+  outlookAttachmentDownloadNode{ mailbox?; messageId; attachmentId; binarySlot?; sizeCapBytes? }
+  outlookFolderResolveNode     { mailbox; folderPath } → { folderId, path, mailbox }
+
+OneDrive  (msgraph-drive-oauth)
+  driveResolveNode · driveListChildrenNode · driveItemGetNode · driveDownloadNode
+  driveUploadNode · driveCopyNode · driveListMyDrivesNode · driveListSharedWithMeNode
+
+Excel  (msgraph-drive-oauth; open a workbook first, pass the handle downstream)
+  excelOpenWorkbookNode · excelCloseWorkbookNode · excelListWorksheetsNode · excelAddSheetNode
+  excelReadRangeNode · excelWriteRangeNode · excelStyleRangeNode
+```
+
+For a OneDrive/Excel case not covered, resolve `ctx.getCredential<MsGraphSession>("auth")` in a
+`Callback` and call `createGraphClient(session)` (exported from `@codemation/core-nodes-msgraph`) to
+reach the raw Graph SDK.
+
+## Gotchas
+
+- **`.create(...)`, never `new`.** These are `defineNode` definitions — `new outlookMessageReplyNode(...)`
+  does not exist.
+- **Type the `itemExpr`.** `.create<MsGraphMailItem>` alone leaves a bare `itemExpr` callback's
+  `item.json` as `unknown`. Write `itemExpr<string, MsGraphMailItem>(({ item }) => item.json.messageId)`.
+- **Pick the right credential type on `"auth"`.** Mail nodes → `msgraph-mail-oauth`; OneDrive/Excel →
+  `msgraph-drive-oauth`. Bind every node's slot before activation.
+- **`filter` is server-side OData.** It is a raw `$filter` string — malformed expressions fail the poll.
+  The trigger establishes a baseline on its first cycle (emits nothing) so existing mail doesn't replay.
+- **Attachment bytes need `downloadAttachments: true`** (or a later `outlookAttachmentDownloadNode`);
+  the item JSON only ever carries attachment metadata.
+
+## Testing an Outlook workflow on real mail (not fabricated fixtures)
+
+Use `OutlookFolderTestSource` (a `TestTriggerNodeConfig`) to run the persistent Tests-tab suite on
+real emails from a **designated test folder** in the same mailbox. Each message becomes one test
+case and yields items in the **identical `MsGraphMailItem` shape** the live trigger emits — so OCR,
+extraction, and matching all run downstream in tests too.
+
+**The designated test folder is communicated to the builder by the concierge as part of the build
+task.** If the folder id/name is absent from the task, call `report_flag({ kind: "gap" })` and note
+that the test folder must be provided. Prefer declaring the folder id as a named constant the owner
+fills (e.g. `const TEST_FOLDER = "TODO(setup): paste the test folder id here"`) rather than leaving
+an unexplained placeholder string buried inside the node config. NEVER fabricate a folder id or fall
+back to hard-coded fixture data.
+
+The topology that matters:
+
+```text
+trigger → [shared processing: OCR / extraction / matching] → IsTestRun → {
+  true  (test):  Assertion   — checks the EXTRACTION OUTCOME, not the raw email
+  false (live):  ALL side-effects — reply + patch (mark read/categorize) + ERP write, all gated together
+}
+```
+
+`IsTestRun` must go **after** the shared processing and **just before** the side-effects. If it
+forks before the extraction, the test path asserts raw trigger bytes and proves nothing.
+
+```typescript
+import { z } from "zod";
+import {
+  createWorkflowBuilder,
+  AIAgent,
+  IsTestRun,
+  Assertion,
+  CodemationChatModelConfig,
+} from "@codemation/core-nodes";
+import { itemExpr } from "@codemation/core";
+import {
+  onNewMsGraphMailTrigger,
+  OutlookFolderTestSource,
+  outlookMessageReplyNode,
+  outlookMessagePatchNode,
+  type MsGraphMailItem,
+} from "@codemation/core-nodes-msgraph";
+
+// ── output schema for the extraction step ─────────────────────────────────
+// messageId is passed through so the side-effect nodes can address the message after extraction.
+const ExtractionSchema = z.object({
+  messageId: z.string(), // pass-through from trigger — needed by reply/patch nodes
+  customer: z.string(), // recognised company/customer name; empty string when unrecognised
+  lineItems: z.array(z.object({ description: z.string(), amount: z.number() })),
+});
+type ExtractionOutput = z.infer<typeof ExtractionSchema>;
+
+// ── test folder ───────────────────────────────────────────────────────────
+// Declare the folder id as a named constant the owner fills.
+// If the concierge did not provide it → call report_flag({ kind: "gap" }) instead.
+const TEST_FOLDER = "TODO(setup): paste the test folder id here";
+
+// SEPARATE top-level export — the Tests tab discovers it. NOT a second .trigger().
+// `new`, not `.create(...)`: the test source is a class (like GmailLabelTestSource), not a defineNode.
+export const testSource = new OutlookFolderTestSource(
+  "Outlook test cases",
+  { mailbox: "me", folderId: TEST_FOLDER, maxResults: 20 },
+  "outlook-test-source",
+);
+
+export default createWorkflowBuilder({ id: "wf.msgraph.procurement", name: "Procurement intake" })
+  .trigger(onNewMsGraphMailTrigger.create({ mailbox: "me", folderId: "inbox" }, "New email", "mail-trigger"))
+  // ── shared processing (runs in BOTH test and live paths) ────────────────
+  // Extract structured fields from the email body. Include messageId so
+  // downstream side-effect nodes (reply, patch, ERP) can address the message.
+  .then(
+    new AIAgent<MsGraphMailItem, ExtractionOutput>({
+      name: "Extract procurement data",
+      id: "extract-procurement-data",
+      messages: [
+        {
+          role: "system",
+          content:
+            "Extract the supplier/customer name and line items from the email. " +
+            "Include the messageId field verbatim from the input. " +
+            'Reply with strict JSON matching {"messageId","customer","lineItems":[{"description","amount"}]}.',
+        },
+        {
+          role: "user",
+          content: ({ item }) => `messageId: ${item.json.messageId}\n\n${item.json.bodyText ?? ""}`,
+        },
+      ],
+      chatModel: new CodemationChatModelConfig("Managed AI", "low"),
+      outputSchema: ExtractionSchema,
+      guardrails: { maxTurns: 1 },
+    }),
+  )
+  // ── IsTestRun: AFTER all shared processing, JUST BEFORE side-effects ───
+  .then(new IsTestRun<ExtractionOutput>("Is this a test run?", "is-test-run"))
+  .when({
+    // true = test path: assert the EXTRACTION OUTCOME, not the raw email fields
+    true: [
+      new Assertion<ExtractionOutput>({
+        name: "Extraction outcome",
+        id: "assert-extraction-outcome",
+        assertions: (item) => [
+          {
+            // Did the model recognise a company/customer?
+            name: "customer recognised",
+            score: item.json.customer.trim().length > 0 ? 1 : 0,
+            actual: item.json.customer,
+          },
+          {
+            // Did the model extract at least one line item?
+            name: "line items extracted",
+            score: item.json.lineItems.length > 0 ? 1 : 0,
+            actual: item.json.lineItems.length,
+          },
+        ],
+      }),
+    ],
+    // false = live path: EVERY side-effect is gated here together
+    // (ERP write / create-order call belongs here too — never outside this branch)
+    false: [
+      outlookMessageReplyNode.create<ExtractionOutput>(
+        {
+          mailbox: "me",
+          messageId: itemExpr<string, ExtractionOutput>(({ item }) => item.json.messageId),
+          body: itemExpr<string, ExtractionOutput>(
+            ({ item }) =>
+              `Thank you — we received your procurement request and are processing it.` +
+              (item.json.customer ? ` Customer: ${item.json.customer}.` : ""),
+          ),
+          bodyType: "text",
+          // draftOnly is NOT a test switch — see the note below. Sending is gated by IsTestRun.
+        },
+        "Acknowledge receipt",
+        "reply",
+      ),
+      outlookMessagePatchNode.create<ExtractionOutput>(
+        {
+          mailbox: "me",
+          messageId: itemExpr<string, ExtractionOutput>(({ item }) => item.json.messageId),
+          isRead: true,
+          categories: ["Processed"],
+          // move: { folderId: "Archive" } — a well-known name or an id from outlookFolderResolveNode
+        },
+        "Mark processed",
+        "mark-processed",
+      ),
+      // → Add the ERP write node here (e.g. odooCreateSaleOrderNode) before marking processed.
+    ],
+  })
+  .build();
+```
+
+**Key rules:**
+
+- `OutlookFolderTestSource` is a **separate `export const`**, never a second `.trigger(...)` on the chain. It is a class (mirroring `GmailLabelTestSource`) — instantiate with `new`, not `.create(...)`.
+- **Place `IsTestRun` after all shared processing and just before the side-effects.** Processing steps (OCR, extraction, matching) must be upstream of `IsTestRun` so both the test path and the live path exercise the same logic. An `IsTestRun` placed right after the trigger asserts nothing useful.
+- **Assert the processing outcome, not the raw email.** The `Assertion` on the `true` branch must check the extractor's structured output (recognised customer, extracted line items) — not `subject`, `from`, or other raw trigger fields. Asserting `subject.length > 0` proves only that an email arrived; asserting `lineItems.length > 0` proves the extraction worked.
+- **Gate EVERY side-effect on the `false` branch.** Reply, patch (mark read / categorize / move), and ERP writes all belong on the `false` branch — together. A single gated patch while the reply or ERP write runs unconditionally defeats the purpose. If you add a node that writes to an external system, it must live on the `false` branch.
+- **`draftOnly` is NOT the test mechanism.** Gate the reply behind `IsTestRun` (it lives on the `false`/live branch, so a test run never reaches it and no mail is sent). Do not reach for `outlookMessageReplyNode`'s `draftOnly: true` to make a run "safe": `draftOnly` saves a draft on the live account, it is not a test-mode switch.
+- **Absent test folder → `report_flag` + declare a required input, never a silent placeholder.** If the concierge did not provide the test folder, call `report_flag({ kind: "gap" })`. When a placeholder is unavoidable, declare it as a named constant at the top of the file (as `TEST_FOLDER` above) so the owner knows exactly what to fill in — never bury an opaque string inside a node config.
+- `OutlookFolderTestSource` yields items in the same raw `MsGraphMailItem` shape as the live `onNewMsGraphMailTrigger` — no pre-processing, no canonicalization. That's what makes the test meaningful.
+- The `caseLabel` on `OutlookFolderTestSource` defaults to the email subject so each test-case row in the Tests tab is human-readable.
+
+## Read next when needed
+
+- `workflow-dsl` — builder, triggers, flow control, the per-item contract.
+- `document-ai` — OCR an attachment's bytes once they're in `ctx.binary`.
+- `ai-agent` — summarize or triage `item.json.bodyText` with an LLM before replying.
+- `testing` — the full `IsTestRun` + `Assertion` + `TestTrigger` pattern (trigger-agnostic).