@hailer/mcp 1.3.14 → 1.3.23

package/.claude/skills/sdk-activity-patterns/SKILL.md

@@ -1,19 +1,34 @@
 ---
 name: sdk-activity-patterns
-description: Activity CRUD patterns - field value formats, dates, users, links, dropdowns
-version: 1.5.0
-triggers: Create activity, update activity, field values, date format, activitylink value
+description: Correct field value formats for creating and updating Hailer activities via MCP tools (mcp__hailer__create_activity, mcp__hailer__update_activity). Load whenever creating activities, updating activity fields, bulk-creating activities, or debugging field write failures. Covers dates (Unix timestamps), dropdowns (plain strings), user fields, activitylink fields, daterange/timerange objects, clearing fields, bulk teamId placement, phase-gated field writes, and all-or-nothing batch behavior.
 ---
 
+<!-- augmentation-guard: shrink-ok -->
+
 # Activity CRUD Patterns
 
+## MCP Tools
+
+| Tool | Purpose |
+|------|---------|
+| `mcp__hailer__create_activity` | Create new activity |
+| `mcp__hailer__update_activity` | Update existing activity |
+
+---
+
 ## Create Activity
 
+**`name` must be a non-empty string when provided.** Hailer rejects `name: ""` with `name: Activity name cannot be empty`.
+
+**`create_activity` REQUIRES `name` even when `nameFunctionEnabled: true`.** The MCP runtime enforces this — pass a meaningful placeholder (e.g. `'Luonnos'`). The `nameFunction` will overwrite it immediately.
+
+**`nameFunction` overrides any `name` you pass on create.** Place the human-readable identity in the field that `nameFunction` reads.
+
 ```javascript
 mcp__hailer__create_activity({
   workflowId: "682ac815fba468d857d498f7",
   phaseId: "682ac815fba468d857d49904",
-  name: "New Task",  // Optional
+  name: "New Task",  // non-empty string; omit entirely not allowed in single mode
   fields: {
     "fieldId1": "value1",
     "fieldId2": "value2"
@@ -31,78 +46,132 @@ mcp__hailer__update_activity({
 })
 ```
 
+**Update error reporting is lossy.** `update_activity` rejections surface as `[object Object]` — the underlying server error is swallowed. When an MCP write errors opaquely, re-run the same operation via REST, or confirm via read-back (`show_activity_by_id`). `create_activity` errors ARE rich (full `{code, msg, details}` envelope).
+
+**@hailer/mcp 1.3.x behavior change — unknown field keys now ERROR.** Passing an unknown field key in `create_activity` or `update_activity` now returns an error. On 1.2.1 the key was silently ignored.
+
 ---
 
-## Critical Field Value Rules
+## Field Value Formats
 
-**All single-value fields use STRING, not array.** No multi-select types exist in Hailer.
+**No multi-select types exist in Hailer.**
 
-```javascript
-// ✅ Correct
-fields: { priority: "High", assignee: "userId", customer: "actId" }
+### Text Fields
 
-// ❌ Wrong — arrays rejected
-fields: { priority: ["High"], assignee: ["userId"], customer: ["actId"] }
-```
+| Type | Format | Example |
+|------|--------|---------|
+| `text` | String | `"Hello world"` |
+| `textarea` | String | `"Multi\nline\ntext"` |
+| `textunit` | String | `"100"` |
 
-**Dates are Unix timestamps in milliseconds** (not ISO strings):
-```javascript
-fields: { due_date: new Date('2024-11-07').getTime() }  // 1730937600000
-```
+### Number Fields
+
+| Type | Format | Example |
+|------|--------|---------|
+| `numeric` | Number | `42` or `42.5` |
+| `numericunit` | Number | `99.99` (plain number — unit is display-only) |
+
+### Date/Time Fields
+
+| Type | Format | Example |
+|------|--------|---------|
+| `date` | Unix timestamp (ms) OR ISO `YYYY-MM-DD` string via MCP (auto-converted) | `1730937600000` or `"2024-11-07"` |
+| `datetime` | Unix timestamp (ms) OR ISO `YYYY-MM-DD` string via MCP | `1730937600000` |
+| `daterange` | Object | `{ start: 1730937600000, end: 1731024000000 }` |
+| `datetimerange` | Object | `{ start: 1730937600000, end: 1731024000000 }` |
+| `time` | Unix ms since epoch (includes date) — `HH:MM` string is rejected, NOT coerced | `46800000` |
+| `timerange` | Object | `{ start: 1765863000000, end: 1765915200000 }` |
 
-**Time fields** also use full millisecond timestamps including date:
 ```javascript
+// JavaScript Date to Hailer timestamp
+const timestamp = new Date('2024-11-07').getTime();  // 1730937600000
+
+// Time field: also Unix timestamp (includes date)
 const today = new Date();
 today.setUTCHours(9, 30, 0, 0);
-fields: { start_time: today.getTime() }
+const timeValue = today.getTime();
 ```
 
-**daterange / datetimerange** use object with `start` + `end`:
-```javascript
-fields: { period: { start: 1730937600000, end: 1731024000000 } }
-```
+### Selection Fields
 
-**activitylink** is plain string ID — READ format (object with `_id`, `name`) differs from WRITE format:
-```javascript
-// ✅ Write: plain string ID
-fields: { customer: "692abc123def456" }
+| Type | Format | Example |
+|------|--------|---------|
+| `textpredefinedoptions` | **STRING** (exact option string from field's `data[]`) | `"High"` |
 
-// ❌ Wrong: object (this is what you get when reading)
-fields: { customer: { _id: "692abc123def456", name: "Acme" } }
-```
+**CRITICAL #1:** Value is STRING, not array!
+**CRITICAL #2:** The string is the **exact option string** from the field's `data[]` — there is no separate generated key.
+**CRITICAL #3 — No server-side membership check.** A non-option value or wrong-case value is stored verbatim without error, renders blank, and silently breaks downstream filters.
 
-**textpredefinedoptions** is the exact option string, not an array:
 ```javascript
-fields: { status: "In Progress" }
-```
+// ✅ Correct
+fields: { industry: "Retail" }
 
-**text fields must always be strings**, even for numeric-looking values:
-```javascript
-fields: { code: "300" }  // not 300
+// ❌ Wrong — array rejected with code 191
+fields: { industry: ["Retail"] }
+
+// ⚠️ Silently stores invalid value — renders blank
+fields: { industry: "retail" }      // wrong case
 ```
 
----
+### User & Team Fields
+
+| Type | Format | Example |
+|------|--------|---------|
+| `users` | **STRING** (user ID) | `"5f8a1b2c3d4e5f6a7b8c9d0e"` |
+| `teams` | **STRING** (team ID) | `"teamId123"` |
+
+**CRITICAL:** Value is STRING, not array! No multi-select types exist.
+
+### Link Fields
 
-## Modified Fields (Checkbox & File)
+| Type | Format | Example |
+|------|--------|---------|
+| `activitylink` | **STRING** (activity ID) | `"692abc123def456"` |
+
+**CRITICAL:** Canonical write format is a plain STRING ID, not array or object!
+
+**CREATE vs UPDATE asymmetry:**
+- On **CREATE**: object format is REJECTED with code 191. Use plain string only.
+- On **UPDATE** (single mode): `{_id, name}` or `{value: "<24hex>"}` objects are silently coerced to string ID.
+- Arrays are NOT coerced in either mode.
+
+**READ vs WRITE formats differ:**
+- **READ via app-sdk / `returnFlat: true`**: `{ _id: string, name: string }` object
+- **READ via MCP `show_activity_by_id`**: `{ type: "activitylink", value: { _id, name } }` — unwrap `.value`
+- **WRITE**: plain string ID only
+
+**ActivityLink Multi-Value Inconsistency:** The same ActivityLink field on different activities can return different shapes (`{_id, name}` object vs array). Use a defensive helper:
+
+```js
+function matchesActivityLink(value, targetId) {
+  if (Array.isArray(value)) return value.some(x => x?._id === targetId);
+  return value?._id === targetId;
+}
+```
 
-These use base types with a `modifier` in the field config:
+### Modified Fields (Checkbox & File)
 
-| Config | Write Format |
-|--------|-------------|
-| `numeric` + `modifier.checkbox: true` | `1` (true) or `0` (false) |
-| `text` + `modifier.file: true` | File reference (UI handles upload) |
+| Config | Value Format | Example |
+|--------|--------------|---------|
+| `numeric` + `modifier.checkbox: true` | Number | `1` (true) or `0` (false) |
+| `text` + `modifier.file: true` | Object | File reference (UI handles) |
 
 ---
 
-## Clearing Field Values
+## Complete Create Example
 
 ```javascript
-mcp__hailer__update_activity({
-  activityId: "692abc123def456",
+mcp__hailer__create_activity({
+  workflowId: "682ac815fba468d857d498f7",
+  phaseId: "682ac815fba468d857d49904",
+  name: "Fix login bug",
   fields: {
-    "assignee_abc": "",     // Clear user
-    "due_date_def": null,   // Clear date
-    "notes_ghi": ""         // Clear text
+    "description_abc": "Users cannot log in after password reset",
+    "priority_def": "High",               // Dropdown — exact string from data[]
+    "assignee_jkl": "5f8a1b2c3d4e5f6a7b8c9d0e",  // User — string ID
+    "project_mno": "692abc123def456",     // Activity link — string ID
+    "due_date_pqr": 1730937600000,        // Date — ms timestamp
+    "estimated_hours_stu": 4              // Number
   }
 })
 ```
@@ -111,7 +180,7 @@ mcp__hailer__update_activity({
 
 ## Bulk Creation
 
-Use the `activities[]` array for bulk creation. **Each activity must include its own `teamId` and `phaseId`.**
+Use the `activities[]` array for bulk creation. **In MCP `create_activity` bulk mode, each activity must include its own `teamId` and `phaseId`** in the `activities[]` array.
 
 ```javascript
 mcp__hailer__create_activity({
@@ -139,87 +208,168 @@ mcp__hailer__create_activity({
 |-----------|-------------|-----------|
 | `name` | Top-level | Inside each `activities[]` item |
 | `phaseId` | Top-level | Inside each `activities[]` item |
-| `teamId` | Top-level | **Inside each `activities[]` item** |
+| `teamId` | Top-level | Inside each `activities[]` item |
 | `fields` | Top-level | Inside each `activities[]` item |
 | `workflowId` | Top-level | Top-level (shared) |
 
-**CRITICAL:** In bulk mode, `teamId` at the top level is **IGNORED**. Each activity in the array must have its own `teamId`. Omitting it causes "Missing team(s)" (code 127) unless the workflow has a default team.
+**CRITICAL (MCP bulk mode):** `teamId` at the top level is **IGNORED**. MCP backfills the workflow default team when `teamId` is absent — code 127 "Missing team(s)" only fires if no default team exists at all. Supply `teamId` explicitly per activity to avoid relying on fallback.
 
-### Team ID Fallback Chain
+### Team ID Fallback Chain (MCP)
 
-The MCP tool auto-fills `teamId` if omitted:
-1. Per-activity `teamId` (if provided) — **always provide this**
+1. Per-activity `teamId` (if provided) — always provide this
 2. Workflow's default team (`workflow.team`)
-3. First workspace team (last resort, may be wrong team)
+3. First workspace team (last resort, may be wrong)
+
+---
 
-**Best practice:** Always pass `teamId` explicitly. Get IDs from `workspace/teams.ts`.
+## Getting IDs
 
-### Common Error: "Missing team(s)" (Code 127)
+- **Workflow ID** — from `describe_workflows` (real MongoDB ObjectId)
+- **Phase ID** — from `describe_workflows` with `workflowId` + `include:['phases']`
+- **Field IDs** — from `describe_workflows` with `workflowId` + `include:['schema']`
+- **User IDs** — from `search_workspace_users`
+- **Activity IDs** — from `list_activities` or previous create results
 
-**Fix options:**
-1. Pass `teamId` explicitly in every create call (best)
-2. Set default team on the workflow in Hailer UI
-3. Ask orchestrator for available team IDs before creating
+**`workflowId` and `phaseId` need real ObjectIds** (24-char hex strings), not enum key names.
+
+**Field keys vs field IDs vs enum keys:**
+- Field key: `firstName` — the `key` property set on the field in Hailer
+- Field ID: `68cbfec59b3869137fe2af84` — MongoDB ObjectId
+- Enum key: `etunimi_f84` — TypeScript constant (NOT accepted by API)
+
+Both field keys and field IDs work in `create_activity`/`update_activity`. Enum key names don't.
 
 ---
 
-## Enum Key vs ObjectId Gotcha
+## Clearing Field Values
 
-MCP tools require actual MongoDB ObjectIds (24-char hex strings), not enum key names.
+To clear a field, use `null`. **Do not use `""` for text or textarea fields** — empty string is rejected with code 191.
 
 ```javascript
-// ❌ WRONG - enum KEY NAME, not the ID
-mcp__hailer__create_activity({
-  workflowId: "Asiakkaat",            // enum key
-  fields: { "projekti_f84": "value" } // enum key
+mcp__hailer__update_activity({
+  activityId: "692abc123def456",
+  fields: {
+    "assignee_abc": null,   // Clear user
+    "due_date_def": null,   // Clear date
+    "notes_ghi": null       // Clear text — NOT ""
+  }
 })
+```
 
-// ✅ CORRECT - real ObjectIds
-mcp__hailer__create_activity({
-  workflowId: "682ac815fba468d857d498f7",
-  fields: { "68cbfec59b3869137fe2af84": "value" }
-})
+---
+
+## Phase-Gated Field Writes on Create
+
+`create_activity` gates field writes to the fields listed on the activity's **current phase** at creation time. If a field is defined on the workflow but not included in the initial phase's `fields[]` list, passing it in `create_activity` returns code 191 "not allowed" — even though the field exists and the value is valid.
+
+**Fix — split create from update:**
+
+```javascript
+// Step 1: create with ONLY fields present on the initial phase
+const activity = await mcp__hailer__create_activity({
+  workflowId: "...",
+  phaseId: initialPhaseId,
+  name: "Task name",
+  fields: { "field_on_initial_phase": value }
+});
+
+// Step 2: update the rest immediately after
+await mcp__hailer__update_activity({
+  activityId: activity.created_ids[0],
+  fields: { "due_date_field": dueDateTimestamp }
+});
 ```
 
-**TypeScript code vs MCP calls:**
-- **TypeScript:** Use enums for type safety → `WorkflowIds.Asiakkaat` resolves to the ObjectId
-- **MCP tools:** Pass the actual ObjectId string directly
+---
+
+## createMany / updateMany Cross-Cutting Patterns
+
+### All-or-Nothing Batch Behavior
+
+`v3.activity.createMany` and `v3.activity.updateMany` are **all-or-nothing per batch**. A single rejected row fails the entire batch.
+
+Mitigations:
+1. Isolate phase/status mixing into separate batches
+2. Pre-validate phase transitions against `possibleNextPhase` — terminal phases (`possibleNextPhase: []`) block reverse moves
+3. Bisect on failure to find the offender
+
+```javascript
+async function batchWithRetry(workflowId, rows, options) {
+  if (rows.length === 0) return;
+  try {
+    await v3.activity.createMany(workflowId, rows, options);
+  } catch (err) {
+    if (rows.length === 1) throw err;
+    const mid = Math.floor(rows.length / 2);
+    await batchWithRetry(workflowId, rows.slice(0, mid), options);
+    await batchWithRetry(workflowId, rows.slice(mid), options);
+  }
+}
+```
 
-**Where to get real IDs:**
-- `workspace/enums.ts` → enum values ARE the real ObjectIds
-- `list_workflows` → workflow `_id` field
-- `get_workflow_schema` → field `_id` property
+### Batch Size
+
+- createMany: 50 per batch
+- updateMany: 100 per batch
+
+### Empty String Rejected Even When `required: false` (Code 191)
+
+Passing `""` for a text or textarea field always triggers code 191, regardless of `required`. Omit keys with no value instead.
+
+```javascript
+function cleanFields(raw) {
+  return Object.fromEntries(
+    Object.entries(raw).filter(([, v]) => v !== null && v !== undefined && v !== "")
+  );
+}
+```
+
+### `updateMany` row shape
+
+Row shape is `{_id, fields?, phaseId?}` only — no `processId`. `processId` in the per-row object causes error 191.
 
 ---
 
-## Phase Transitions
+## Deleting Activities — Use `activities.remove`
 
 ```javascript
-// Move only
-mcp__hailer__update_activity({ activityId: "...", phaseId: "..." })
+// Hard delete
+await client.request('activities.remove', [activityId]);
 
-// Move + update fields
-mcp__hailer__update_activity({
-  activityId: "692abc123def456",
-  phaseId: "682ac815fba468d857d49906",
-  fields: { "completed_date_abc": Date.now() }
-})
+// Bulk delete
+await client.request('activities.remove', [[id1, id2, id3]]);
+```
+
+`v3.activity.delete` / `v3.activity.deleteMany` / `v3.activity.removeMany` → **code 7 "Method not found"**.
+
+**Soft-archive alternative:** Move to a terminal phase via `updateMany`.
+
+---
+
+## Create Response Shape (MCP vs REST)
+
+MCP `create_activity` returns `{ created_ids: [...] }` in BOTH single and bulk mode.
+
+```javascript
+// ✅ Correct success check
+const result = await mcp__hailer__create_activity({ workflowId, activities: [...] });
+const ids = result.created_ids ?? [];
+
+// ❌ Wrong — single _id check misses bulk responses
+if (!result._id) throw new Error('create failed');
 ```
 
 ---
 
-## Checklist
+## Filtering Reads: `text_search` Does NOT Match ActivityLink Fields
+
+`list_activities` `filters` with `operator: "text_search"` matches **text fields only**. On an `activitylink` field it returns 0 rows. Use `equals` + the linked activity's `_id` instead.
+
+---
 
-Before creating/updating activities:
+## Editable Function Fields
 
-- [ ] Have workflow ID (from enum or API)
-- [ ] Have phase ID (from enum or API)
-- [ ] Have field IDs (from enum or API)
-- [ ] Have **team ID** (from teams.ts or API) — don't rely on fallbacks
-- [ ] All values are **STRINGS** for select/user/link fields (no multi-select types exist)
-- [ ] Dates are **Unix timestamps in milliseconds**
-- [ ] Times are **Unix timestamps in milliseconds** (like dates)
-- [ ] **Bulk mode:** teamId, phaseId, fields are **inside each activity object**, not top-level
+A function field with `editable: true` is a valid write target — pass a value the same way as any other field. A stored value wins over the computed default; the function only back-fills while the field is empty.
 
 ---
 
@@ -227,12 +377,14 @@ Before creating/updating activities:
 
 | Wrong | Right |
 |-------|-------|
-| `{ priority: ["High"] }` | `{ priority: "High" }` (string) |
-| `{ assignee: ["userId"] }` | `{ assignee: "userId" }` (string) |
-| `{ customer: ["actId"] }` | `{ customer: "actId" }` (string) |
-| `{ date: "2024-11-07" }` | `{ date: 1730937600000 }` (timestamp ms) |
-| `{ time: "09:00" }` | `{ time: 1765863000000 }` (ms timestamp) |
+| `{ priority: ["High"] }` | `{ priority: "High" }` — string for single select |
+| `{ assignee: ["userId"] }` | `{ assignee: "userId" }` — string for single user |
+| `{ customer: ["actId"] }` | `{ customer: "actId" }` — string for activitylink |
+| `{ date: "2024-11-07" }` via raw REST/app-sdk | `{ date: 1730937600000 }` — ms timestamp |
+| `{ time: "09:00" }` | `{ time: 46800000 }` — `HH:MM` string is rejected |
 | `{ daterange: 1730937600000 }` | `{ daterange: { start: ..., end: ... } }` |
-| `{ textField: 300 }` | `{ textField: "300" }` (must be string) |
-| Passing enum key names as IDs | Use real 24-char hex ObjectIds |
+| `{ textField: 300 }` | `{ textField: "300" }` — text fields must be STRINGS |
+| Comparing activitylink by value | Compare `value._id` — READ format is `{_id, name}` object |
 | Bulk create with top-level teamId | Put teamId INSIDE each activity object |
+| `name: ""` | Non-empty string or omit; empty string rejected |
+| `data: [{value: "A", label: "A"}]` in field creation | `data: ["A", "B"]` — plain string array only |