@codemation/agent-skills 0.4.0 → 0.5.1

package/skills/codemation-custom-node-development/SKILL.md

@@ -1,61 +0,0 @@
----
-name: codemation-custom-node-development
-description: Guides Codemation custom node development with `defineNode(...)` (`execute` per item), `defineBatchNode(...)` (batch `run`), reusable node modules, credential-aware nodes, and the class-based node fallback for advanced cases. Use when creating or updating custom nodes for apps or plugin packages.
-compatibility: Designed for Codemation apps and plugin packages that define reusable nodes.
-tags: node, custom, plugin
-uses: "@codemation/core"
----
-
-# Codemation Custom Node Development
-
-## Mental model
-
-Custom nodes are the extension point for reusable business logic that doesn't belong inline in a workflow callback. `defineNode(...)` wraps a per-item `execute` function with a typed contract (input schema, credential slots, output shape); the engine calls it once per item. `defineBatchNode(...)` is the batch variant for logic that must see all items at once. Nodes compose into workflows via config class instances — the node definition is separate from the config class used to wire it into a workflow.
-
-## Use this skill when
-
-Use this skill for reusable custom node work, whether the node lives inside an app or a published plugin package.
-
-Do not use this skill for pure workflow chaining questions unless the node implementation itself is changing.
-
-## Per-item vs batch
-
-**`defineNode(...)` (per-item)** — the engine calls `execute(args, context)` once per item. This is the right default for the vast majority of nodes: straightforward logic, credential slots, input schema, optional fan-out.
-
-**`defineBatchNode(...)` (batch)** — the engine calls `run(items, context)` with the full activation batch. Use only when the node genuinely needs to see all items at once (aggregation, bulk API calls, cross-item correlation).
-
-When in doubt, start with `defineNode`.
-
-## Node rules
-
-1. Keep nodes deterministic and focused.
-2. Request credentials through named slots — never hard-code secrets.
-3. Put **static** options (credentials, retry policy, labels) on **config**; put **per-item** behavior in **inputs** / wire JSON and optional `itemExpr` on config fields.
-4. **Emit files with `ctx.binary`, not base64 in `json`** — base64 in `item.json` bloats persisted run data. See `references/node-patterns.md`.
-5. Drop to class-based node APIs only when you need constructor-injected collaborators, decorators, or deeper runtime metadata.
-
-## Minimal `defineNode` example
-
-```ts
-import { defineNode } from "@codemation/core";
-import { z } from "zod";
-
-export const uppercaseNode = defineNode({
-  key: "example.uppercase",
-  title: "Uppercase field",
-  icon: "lucide:languages",
-  inputSchema: z.object({ field: z.string() }),
-  async execute({ input }) {
-    return { ...input, field: input.field.toUpperCase() };
-  },
-});
-```
-
-For full patterns — credential-slotted nodes, batch nodes, fan-out, binary payloads, and test kit usage — use your harness's example-discovery tool: `find_examples({ query: "defineNode" })` or `find_examples({ query: "defineBatchNode" })`.
-
-## Read next
-
-- `references/define-node-per-item.md` — full `defineNode(...)` contract, `inputSchema`, `itemExpr`, fan-out, assertion nodes, and `WorkflowTestKit` usage. Load this when writing or debugging a per-item node.
-- `references/define-batch-node.md` — `defineBatchNode(...)` contract and when to choose batch over per-item. Load this when the node must see the entire batch at once.
-- `references/credential-aware-nodes.md` — credential slots, typed sessions, and how to test credential-aware nodes. Load this when your node needs a credential.
-- `references/node-patterns.md` — binary payloads (`ctx.binary`, `attach`, `withAttachment`), fan-out return shapes, polling-trigger binary patterns, MS Graph attachment download, and HTTP binary round-trips. Load this when working with file data or HTTP binaries.

package/skills/codemation-custom-node-development/references/credential-aware-nodes.md

@@ -1,38 +0,0 @@
-# Credential-Aware Nodes
-
-Load this when your node needs a typed credential (OAuth token, API key, or any `defineCredential(...)` type) injected at runtime.
-
-## Core rule
-
-Request credentials through **named slots** on the node config instead of hard-coding secrets. The framework resolves the slot to a live typed session at execution time.
-
-## Adding a credential slot to `defineNode`
-
-```ts
-import { defineNode } from "@codemation/core";
-import { myApiCredentialType } from "./myApiCredential.js";
-
-export const callApiNode = defineNode({
-  key: "example.call-api",
-  title: "Call My API",
-  credentials: {
-    api: myApiCredentialType, // slot name → credential type
-  },
-  async execute({ input }, { credentials }) {
-    const session = await credentials.api.getSession();
-    // session is typed by myApiCredentialType.sessionSchema
-    const response = await fetch("https://api.example.com/data", {
-      headers: { Authorization: `Bearer ${session.accessToken}` },
-    });
-    return response.json();
-  },
-});
-```
-
-## Typed sessions
-
-`credentials.<slot>.getSession()` returns the shape declared in the credential type's `sessionSchema`. The framework handles refresh, storage, and error propagation — your node only consumes the session.
-
-## Testing credential-aware nodes
-
-Supply a mock credential in `WorkflowTestKit` rather than live credentials. See `codemation-credential-development` for the full `defineCredential(...)` story, typed sessions, and credential testing patterns.

package/skills/codemation-custom-node-development/references/define-batch-node.md

@@ -1,38 +0,0 @@
-# Define Batch Node
-
-Load this when you need to author a `defineBatchNode(...)` node that processes all items in one call.
-
-## When to use `defineBatchNode` instead of `defineNode`
-
-- The node must see the **entire activation batch** at once (e.g. an aggregation, a bulk API call, or a node that correlates items against each other).
-- Legacy batch semantics are required by the calling workflow.
-- You need the same contract as built-in batch-shaped nodes such as `Aggregate`.
-
-For the common case (one-item-at-a-time logic), prefer `defineNode` — the engine handles iteration for you.
-
-## Minimal skeleton
-
-```ts
-import { defineBatchNode } from "@codemation/core";
-import { z } from "zod";
-
-export const sumNode = defineBatchNode({
-  key: "example.sum",
-  title: "Sum numeric field",
-  inputSchema: z.object({ value: z.number() }),
-  async run(items, { config }) {
-    const total = items.reduce((acc, item) => acc + (item.json as { value: number }).value, 0);
-    return [{ json: { total } }];
-  },
-});
-```
-
-## Contract
-
-- `run(items, context)` receives the **full array** of activation items.
-- Return an array of output items (same length as input is not required — you can fan-in to one, or fan-out to many).
-- The context object exposes `config`, `credentials`, and `execution` (same as `defineNode`).
-
-## Advanced fallback
-
-Reach for class-based node APIs when constructor-injected collaborators are required, plugin packaging needs the lower-level runtime contract, or decorators/persisted metadata need tighter control.

package/skills/codemation-document-scanner/SKILL.md

@@ -1,136 +0,0 @@
----
-name: codemation-document-scanner
-description: CodemationDocumentScanner node — managed document/invoice/image extraction via the Codemation doc-scanner service. No Azure credentials required. Read before writing any workflow that scans documents, invoices, or images.
-compatibility: Codemation core-nodes. Requires @codemation/core-nodes import.
-tags: ocr, document, invoice, image, scan, extract, managed, confidence
-uses: "@codemation/core-nodes"
----
-
-# Codemation Document Scanner Node
-
-> **Start here: call `find_examples` before reading further.**
->
-> - `find_examples({ query: "CodemationDocumentScanner" })` — node-level usage and all analyzerType variants
-> - `find_examples({ query: "invoice scan post accounting" })` — end-to-end invoice extraction scenario
-> - `find_examples({ query: "document scanner confidence fields" })` — how to enable per-field confidence scores
-
-## Use this skill when
-
-Writing a workflow that extracts text and/or structured fields from documents, invoices, or images
-using the Codemation managed scanning service. No Azure credentials are required — the service is
-pre-wired to the platform.
-
-Use `codemation-workflow-dsl` for surrounding workflow structure.
-Use `codemation-ai-agent-node` if you need to pass the extracted markdown to an LLM for further processing.
-
-## When to use CodemationDocumentScanner vs the standalone OCR nodes
-
-| Situation                                        | Use                                                                                                 |
-| ------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
-| Managed platform deployment, no Azure credential | `codemationDocumentScannerNode` (this skill)                                                        |
-| Self-hosted / BYOK Azure Content Understanding   | `analyzeDocumentNode` / `analyzeInvoiceNode` / `analyzeImageNode` from `@codemation/core-nodes-ocr` |
-
-`codemationDocumentScannerNode` calls the internal `doc-scanner` service via HMAC — the workspace holds
-no Azure key. The standalone OCR nodes call Azure directly using a per-workspace credential.
-
-## Choosing `analyzerType`
-
-| `analyzerType` | When to use                                     | Azure analyzer                                                          | Field extraction       | Confidence opt-in supported             |
-| -------------- | ----------------------------------------------- | ----------------------------------------------------------------------- | ---------------------- | --------------------------------------- |
-| `"document"`   | General PDFs, Word docs, HTML, text-heavy files | `prebuilt-document`                                                     | Yes                    | Yes                                     |
-| `"invoice"`    | Invoices, receipts — always prebuilt-invoice    | `prebuilt-invoice`                                                      | Yes                    | Yes                                     |
-| `"image"`      | Photos, screenshots, diagrams                   | `prebuilt-imageAnalyzer`                                                | No (markdown only)     | No — image carries no extraction charge |
-| `"auto"`       | Unknown mime type at author time                | Routes on `Content-Type`: `image/*` → image, everything else → document | Depends on routed type | Depends on routed type                  |
-
-**Default is `"auto"`.** Set an explicit type whenever you know the content class — it avoids
-unnecessary re-routing and makes the workflow self-documenting.
-
-## Output shape
-
-```ts
-{
-  markdown: string; // full text content
-  fields: Record<
-    string,
-    {
-      value: unknown; // extracted scalar, date ISO string, nested object, or array
-      confidence: number | null; // 0–1 when includeConfidence:true; null otherwise
-    }
-  >;
-}
-```
-
-`item.json.markdown` is the Markdown rendering of the document.
-`item.json.fields` is a flat-or-nested map of structured fields found by the analyzer.
-For `analyzerType: "image"`, `fields` is always `{}`.
-Fields may be sparse or absent for generic documents — extraction is best-effort.
-
-## WARNING: How to enable per-field confidence scores (LD6)
-
-**By default, `confidence` is `null` on every field.** This keeps token cost low for the majority
-of workflows that only need `value`.
-
-To get a populated `confidence` (0–1 float) on each field, set `includeConfidence: true`:
-
-```ts
-codemationDocumentScannerNode.create(
-  {
-    binaryField: "data",
-    analyzerType: "invoice",
-    includeConfidence: true, // ← opt-in: fields carry confidence 0–1
-  },
-  "Scan invoice",
-  "scan-invoice",
-);
-```
-
-**Cost implication:** enabling confidence routes the request to a confidence-enabled analyzer variant,
-which roughly doubles the contextualization token count for document/invoice analyzers.
-Only enable it when your downstream logic actually reads `field.confidence`.
-
-Images (`analyzerType: "image"`) and auto-routed-to-image requests carry no field-extraction charge
-regardless of this flag — they silently ignore `includeConfidence` (confidence stays `null`, never a 400).
-
-## API usage
-
-```ts
-import { codemationDocumentScannerNode } from "@codemation/core-nodes";
-
-codemationDocumentScannerNode.create(
-  {
-    binaryField?: string;         // key on item.binary — default "data"
-    analyzerType?: "document" | "invoice" | "image" | "auto";  // default "auto"
-    contentType?: string;         // MIME type override — falls back to attachment.mimeType
-    includeConfidence?: boolean;  // default false — see cost note above
-    maxBytes?: number;            // size cap before reading; default 50 MiB (LD10)
-  },
-  label?: string,   // node label on the canvas
-  nodeId?: string,  // explicit stable id — set when output is used downstream
-)
-```
-
-Set an explicit `nodeId` whenever downstream nodes reference this node's output by id, or when
-the node may be renamed later (avoids credential-binding orphaning).
-
-## Consuming fields downstream
-
-```ts
-import type { DocScannerOutput, DocScannerField } from "@codemation/core-nodes";
-
-// item.json after codemationDocumentScannerNode:
-// DocScannerOutput = { markdown: string; fields: Record<string, DocScannerField> }
-// DocScannerField  = { value: unknown; confidence: number | null }
-
-new Callback<DocScannerOutput>("Use fields", (items, _ctx) =>
-  items.map((item) => {
-    const vendorName = item.json.fields["VendorName"]?.value as string | undefined;
-    const vendorConf = item.json.fields["VendorName"]?.confidence; // null unless includeConfidence:true
-    return { ...item, json: { ...item.json, vendorName, vendorConf } };
-  }),
-);
-```
-
-## Read next when needed
-
-- `codemation-workflow-dsl` — workflow builder, trigger types, fluent vs low-level API.
-- `codemation-ai-agent-node` — pass `item.json.markdown` to an LLM for summarisation or extraction.

package/skills/codemation-workflow-dsl/SKILL.md

@@ -1,78 +0,0 @@
----
-name: codemation-workflow-dsl
-description: Guides Codemation workflow authoring. Use when creating or updating workflow definitions in `src/workflows` — manual-trigger flows via `workflow("...").manualTrigger(...)`, or cron/webhook/other triggers via `createWorkflowBuilder({id, name}).trigger(...)`.
-compatibility: Designed for Codemation apps and plugins that author workflows.
-tags: workflow, dsl, authoring
-uses: "@codemation/core-nodes, @codemation/host"
----
-
-# Codemation Workflow DSL
-
-## Mental model
-
-A workflow definition describes how items move from a trigger through downstream node steps. Items carry data in `item.json`; earlier outputs are available through `ctx.data`. Activations are batch-shaped but most node steps execute per-item. Every workflow definition finishes with `.build()`, which validates node ids and emits a `WorkflowDefinitionError` on collision or empty id.
-
-## When to use / when NOT
-
-Use this skill when authoring or reviewing workflow definitions under `src/workflows/`.
-Do not use for CLI-only troubleshooting or deep host architecture questions unless they directly affect workflow authoring.
-
-## Quickstart — pick API by trigger type
-
-```ts
-// Manual trigger — full fluent sugar (.map, .if, .switch, .agent, .node, .then)
-import { workflow } from "@codemation/host";
-export default workflow("wf.example")
-  .manualTrigger("Start", {
-    /* seed items */
-  })
-  .map(/* ... */)
-  .build();
-
-// Cron / webhook / any other trigger — low-level .then(new NodeConfig(...)) only
-import { createWorkflowBuilder, CronTrigger } from "@codemation/core-nodes";
-export default createWorkflowBuilder({ id: "wf.example", name: "Example" })
-  .trigger(new CronTrigger("Daily", { schedule: "0 9 * * *", timezone: "UTC" }))
-  .then(/* new SomeNodeConfig(...) */)
-  .build();
-```
-
-For full patterns — multi-step pipelines, branching, SubWorkflow, binary, agent tools, TestTrigger, and complete working examples — use your harness's example-discovery tool: `find_examples({ query: "..." })`. Useful queries: `"CronTrigger"`, `"if branch"`, `"AIAgent multi-step"`, `"SubWorkflow binary"`, `"TestTrigger assertion"`.
-
-## Decision branches & gotchas
-
-**Two authoring APIs — pick by trigger type.** `workflow("id").manualTrigger(...)` returns a `WorkflowChain` with full fluent helpers (`.map`, `.if`, `.switch`, `.split`, `.agent`, `.node`). `createWorkflowBuilder({id, name}).trigger(new XxxTrigger(...))` returns a `ChainCursor` whose only chain method is `.then(new NodeConfig(...))`. Do NOT call `.trigger(...)` on the `workflow(...)` builder — it doesn't exist there.
-
-**Node ids and stability.** When no explicit `id:` is given, the engine slugifies the node's `name` label (lowercase, non-alphanumeric → `-`). `"Send Email"` → `"send-email"`. Nodes sharing credential bindings use `(workflowId, nodeId, slotKey)` as the binding key — renaming a label orphans the binding. **Set explicit `id:` on every credential-using node.** `.build()` throws `WorkflowDefinitionError` on empty or duplicate ids.
-
-**Id collision pitfall.** A manual-trigger label and a downstream agent label that share the same string both slugify to the same id — `.build()` throws. Fix: add `id: "...-agent"` to disambiguate.
-
-**Collection nodes** use `.then(node.create(...))` instead of `.node(label, node, opts)` — TypeScript can't infer the `ParamDeep` constraint via the fluent helper. See `find_examples({ query: "collection crud" })`.
-
-**Install state in example results.** Every `find_examples` result includes `installed: boolean` and `requiresInstall: string[]`. If `installed` is `false` or `requiresInstall` is non-empty, call `install_package` for each missing package before writing any workflow code that imports them.
-
-**When no example matches — self-solving fallback chain.**
-
-1. Retry with intent variations (different verb, more generic term).
-2. For HTTP APIs: `find_examples({ query: "defineRestNode" })` — covers basic and credential-slotted REST.
-3. For one-shot inline HTTP: `find_examples({ query: "HttpRequest" })`.
-4. For non-HTTP custom logic: `find_examples({ query: "defineNode template" })`.
-   Do NOT ask the user to pick between primitives — they can't help; use the chain. Do NOT grep `node_modules/@codemation/*` for node implementations — examples are authoritative. Surface the technique used in your reply.
-
-**Workflow testing.** Three built-in nodes from `@codemation/core-nodes`: `TestTrigger` (yields one item per test case), `IsTestRun` (routes `true`/`false` by `ctx.testContext`), `Assertion` (emits `AssertionResult[]`, sets `emitsAssertions: true`). See `references/workflow-testing.md` for authoring details.
-
-**SubWorkflow binary.** `item.binary` slots pass transparently through SubWorkflow boundaries in both directions — no special config needed. Both runs share the same `BinaryStorage` singleton.
-
-**Verify your workflow.** Call `verify_workflow({ path: "src/workflows/my-workflow.ts" })` instead of running `pnpm typecheck` yourself. Returns `{ ok, data: { typecheck, lint, build, structure }, hint? }`.
-
-## Anti-patterns
-
-- Do not call `.trigger(...)` on the `workflow(...)` manual builder — use `createWorkflowBuilder(...)` for non-manual triggers.
-- Do not rely on slug-derived node ids for production workflows with credential bindings — always set an explicit `id:`.
-- Do not improvise from memory when `find_examples` returns zero hits — use the fallback chain above.
-
-## Read next when needed
-
-- `references/builder-patterns.md` — item-flow rules and fluent authoring patterns.
-- `references/workflow-testing.md` — TestTrigger / IsTestRun / Assertion with full examples.
-- `references/complete-example.md` — dense end-to-end example covering most authoring features.

package/skills/codemation-workflow-dsl/references/builder-patterns.md

@@ -1,120 +0,0 @@
-Load this when you need item-flow rules, the two-API decision, and fluent authoring patterns.
-
-# Builder Patterns
-
-## Manual-trigger workflow (fluent — full sugar available)
-
-```ts
-import { workflow } from "@codemation/host";
-
-export default workflow("wf.example.id")
-  .name("Example")
-  .manualTrigger("Start", { step: "start" })
-  .map("Transform", (item, _ctx) => ({
-    ...item.json,
-    transformed: true,
-  }))
-  .build();
-```
-
-The `.map`, `.if`, `.switch`, `.split`, `.agent`, `.node`, `.then` helpers are available because `manualTrigger(...)` returns a `WorkflowChain`.
-
-## Cron-triggered workflow (low-level — `.then(new NodeConfig(...))` only)
-
-```ts
-import { Callback, CronTrigger, createWorkflowBuilder } from "@codemation/core-nodes";
-
-export default createWorkflowBuilder({
-  id: "wf.nightly.id",
-  name: "Nightly job",
-})
-  .trigger(new CronTrigger("Nightly", { schedule: "0 3 * * *", timezone: "Europe/Amsterdam" }))
-  .then(
-    new Callback("Process tick", (items, _ctx) => {
-      // Callback receives the whole batch (Items), not a single item.
-      // For a cron trigger the batch is always one item: { firedAt, scheduledFor }.
-      return items.map((item) => ({ firedAt: (item.json as { firedAt: string }).firedAt }));
-    }),
-  )
-  .build();
-```
-
-The cron expression is validated at workflow build time. Each tick emits one item with `{ firedAt, scheduledFor }` ISO-8601 strings. Always supply `timezone` for DST-sensitive schedules — defaults to UTC.
-
-**Note:** non-manual triggers do NOT give you `.map(...)` / `.if(...)` / `.agent(...)` sugar. Compose with `.then(new Callback(...))`, `.then(new If(...))`, `.then(new AIAgent({...}))`, etc.
-
-## Webhook-triggered workflow
-
-```ts
-import { WebhookTrigger, createWorkflowBuilder, Callback } from "@codemation/core-nodes";
-
-export default createWorkflowBuilder({
-  id: "wf.webhook.example",
-  name: "Webhook example",
-})
-  .trigger(new WebhookTrigger("Incoming", { endpointKey: "inbound", methods: ["POST"] }))
-  .then(new Callback("Handle payload", (items) => items.map((it) => ({ received: it.json }))))
-  .build();
-```
-
-## Decision rule
-
-- **Manual one-shot trigger?** Use `workflow("id").manualTrigger(...)` — short, fluent, full sugar.
-- **Anything else?** Use `createWorkflowBuilder({ id, name }).trigger(new Trigger(...))` — verbose, node-config style.
-
-## Imports cheat sheet
-
-- `workflow` → `@codemation/host` (re-exports from `@codemation/core-nodes`)
-- `createWorkflowBuilder`, `CronTrigger`, `WebhookTrigger`, `Callback`, `HttpRequest`, `AIAgent`, `If`, `Split`, `Merge`, `SubWorkflow` → `@codemation/core-nodes`
-- `callableTool`, `itemExpr` → `@codemation/core`
-- Workflow file location: `src/workflows/`. Export the built definition as the default export.
-
-## Item rules
-
-- workflow data flows as items
-- items usually carry `json` data and optional `binary` data (**storage-backed attachments** via node **`ctx.binary.attach`**, not huge base64 strings in **`json`** — base64 in **`json`** inflates the persisted run payload in the DB; binaries stay as **references**)
-- runtime nodes receive batches of items, not just one record
-- author workflow steps with batching in mind
-- fluent `.map(...)`, `.if(...)`, and `.switch({ resolveCaseKey })` callbacks receive `(item, ctx)`
-- read row fields from `item.json` and earlier completed outputs from `ctx.data`
-
-## Node id assignment
-
-When no `id:` is provided, the builder slugifies the node's `name` label: lowercase, non-alphanumeric runs replaced with `-`, leading/trailing `-` stripped. Two nodes with the same effective label produce the same slug and `.build()` throws `WorkflowDefinitionError`. Fix: provide a unique `id:` on the colliding node configs.
-
-Credential bindings are stored as `(workflowId, nodeId, slotKey)`. Changing a node's label changes its slug-derived id and the binding appears unbound. For credential-using nodes, either keep the label stable or set an explicit `id:`:
-
-```ts
-.node("Send email", SendEmailNodeConfig, {
-  id: "send-email", // stable even after a label rename
-  credentials: { smtp: mySmtpCredential },
-})
-```
-
-## When to move beyond callbacks
-
-Promote inline callbacks into custom nodes when:
-
-- the logic is reused across workflows
-- the workflow graph needs clearer names
-- credentials or collaborators need explicit boundaries
-- the callback has become hard to test in isolation
-
-## Relationship to the engine
-
-- the fluent DSL is the friendly authoring surface
-- `@codemation/core` still owns planning, execution, continuation, and runtime contracts
-- host and node packages add the surrounding product capabilities
-
-## Inline callable agent tools
-
-- import `callableTool` from `@codemation/core`
-- build tools with `callableTool({ name, inputSchema, outputSchema, execute, credentialRequirements? })` (equivalent to `CallableToolFactory.callableTool(...)`)
-- pass the result in `AIAgent` `tools: [...]` alongside other tool configs
-
-## Fluent agent steps
-
-- use `.agent(...)` for agent steps in fluent workflow definitions
-- define agent prompts with `messages`
-- use `itemExpr(...)` when message content depends on `item.json`
-- use `outputSchema` when the workflow should expose typed structured agent output