tide-commander 1.32.2 → 1.35.0

package/dist/src/packages/server/data/builtin-skills/workflow-builder.js

@@ -0,0 +1,253 @@
+/**
+ * Workflow Builder - Built-in Skill Definition
+ * Provides agents with runtime context when executing workflow states.
+ * The generateWorkflowExecutorPrompt() function creates a prompt that tells
+ * an agent what workflow it's in, what state it's executing, what variables
+ * are available, and how to update variables / signal completion.
+ */
+/**
+ * Generate a prompt for an agent executing a workflow state.
+ * This gives the agent full context about the workflow instance,
+ * current state, available variables, and API endpoints.
+ */
+export function generateWorkflowExecutorPrompt(params) {
+    const { authToken, port, instanceId, workflowName, currentStateId, currentStateName, currentStateType, promptTemplate, variables, skills, agentId, allStates, transitions, } = params;
+    const variablesList = Object.entries(variables)
+        .map(([k, v]) => `- **${k}**: ${v !== undefined && v !== null ? JSON.stringify(v) : '(not set)'}`)
+        .join('\n');
+    const statesList = allStates
+        .map((s) => `- ${s.name} (${s.id}) [${s.type}]${s.id === currentStateId ? ' ← YOU ARE HERE' : ''}`)
+        .join('\n');
+    const transitionsList = transitions
+        .map((t) => `- "${t.name}" → ${t.targetStateId} (on ${t.conditionType})`)
+        .join('\n');
+    const skillsList = skills.length > 0
+        ? skills.map((s) => `- ${s}`).join('\n')
+        : '- (none assigned)';
+    return `# Workflow Executor Context
+
+You are executing a step in an active workflow instance.
+
+## Workflow: ${workflowName}
+**Instance ID:** ${instanceId}
+**Current State:** ${currentStateName} (${currentStateId}) [${currentStateType}]
+**Agent:** ${agentId}
+
+## Your Task
+
+${promptTemplate}
+
+## Available Variables
+
+${variablesList}
+
+## Workflow States
+
+${statesList}
+
+## Transitions from Current State
+
+${transitionsList}
+
+## Assigned Skills
+
+${skillsList}
+
+## How to Update Workflow Variables
+
+When your task produces results, update the workflow variables so downstream states can use them:
+
+\`\`\`bash
+curl -s -X PATCH "http://localhost:${port}/api/workflows/instances/${instanceId}/variables" \\
+  -H "Content-Type: application/json" \\
+  -H "X-Auth-Token: ${authToken}" \\
+  -d '{ "variables": { "variable_name": "value" }, "changedBy": "agent:${agentId}" }'
+\`\`\`
+
+## How to Check Available Transitions
+
+Before transitioning, check which transitions are available from the current state:
+
+\`\`\`bash
+curl -s -H "X-Auth-Token: ${authToken}" "http://localhost:${port}/api/workflows/instances/${instanceId}/available-transitions"
+\`\`\`
+
+Returns: \`{ "transitions": [{ "id": "...", "name": "...", "targetStateId": "...", "targetStateName": "...", "conditionType": "..." }] }\`
+
+## How to Transition to the Next State
+
+When your task is done, explicitly transition the workflow to the next state. Choose the appropriate target state from the available transitions above:
+
+\`\`\`bash
+curl -s -X PUT "http://localhost:${port}/api/workflows/instances/${instanceId}/transition" \\
+  -H "Content-Type: application/json" \\
+  -H "X-Auth-Token: ${authToken}" \\
+  -d '{ "targetStateId": "TARGET_STATE_ID", "reason": "Brief explanation of why this transition" }'
+\`\`\`
+
+## How to Signal Task Completion (Legacy)
+
+Alternatively, signal completion via an event (the workflow engine matches the event to a transition):
+
+\`\`\`bash
+curl -s -X POST "http://localhost:${port}/api/workflows/instances/${instanceId}/event" \\
+  -H "Content-Type: application/json" \\
+  -H "X-Auth-Token: ${authToken}" \\
+  -d '{ "eventType": "agent_complete", "data": { "agentResponse": "Brief summary of what you did" } }'
+\`\`\`
+
+## Important Rules
+
+1. **Always update variables BEFORE transitioning** — downstream states need your results
+2. **Always transition or signal completion** — the workflow waits for you to move it forward
+3. **Check available transitions** to know which target states are valid
+4. **Use the skills assigned** to accomplish your task (listed above)
+5. **Reference variables** using their current values shown above
+6. **Do not modify states or transitions** — only update variables and drive transitions
+`;
+}
+export const workflowBuilder = {
+    slug: 'workflow-builder',
+    name: 'Workflow Builder',
+    description: 'Runtime context and API reference for agents executing workflow states',
+    allowedTools: ['Bash(curl:*)'],
+    content: `# Workflow Builder — Agent Execution Guide
+
+When you are assigned a workflow state task, you receive context about the workflow instance,
+your current state, available variables, and the API endpoints to interact with the workflow engine.
+
+## Workflow Execution Lifecycle
+
+1. The workflow engine enters your state and sends you a prompt
+2. You execute your task using the assigned skills
+3. You update workflow variables with your results
+4. You signal completion so the workflow transitions to the next state
+
+## Update Variables
+
+Store your results in workflow variables so downstream states can use them:
+
+\`\`\`bash
+curl -s -X PATCH "http://localhost:{{PORT}}/api/workflows/instances/INSTANCE_ID/variables" \\
+  -H "Content-Type: application/json" \\
+  -H "X-Auth-Token: {{AUTH_TOKEN}}" \\
+  -d '{ "variables": { "result_key": "result_value" }, "changedBy": "agent:YOUR_AGENT_ID" }'
+\`\`\`
+
+## Check Available Transitions
+
+Before transitioning, see which next states are valid:
+
+\`\`\`bash
+curl -s -H "X-Auth-Token: {{AUTH_TOKEN}}" "http://localhost:{{PORT}}/api/workflows/instances/INSTANCE_ID/available-transitions"
+\`\`\`
+
+Returns a list of transitions with id, name, targetStateId, targetStateName, and conditionType.
+
+## Transition to Next State
+
+After finishing your task, explicitly move the workflow to the next state:
+
+\`\`\`bash
+curl -s -X PUT "http://localhost:{{PORT}}/api/workflows/instances/INSTANCE_ID/transition" \\
+  -H "Content-Type: application/json" \\
+  -H "X-Auth-Token: {{AUTH_TOKEN}}" \\
+  -d '{ "targetStateId": "TARGET_STATE_ID", "reason": "Why this transition was chosen" }'
+\`\`\`
+
+## Signal Completion (Legacy)
+
+Alternatively, signal the workflow engine with an event:
+
+\`\`\`bash
+curl -s -X POST "http://localhost:{{PORT}}/api/workflows/instances/INSTANCE_ID/event" \\
+  -H "Content-Type: application/json" \\
+  -H "X-Auth-Token: {{AUTH_TOKEN}}" \\
+  -d '{ "eventType": "agent_complete", "data": { "agentResponse": "Summary of what was done" } }'
+\`\`\`
+
+## Read Current Variables
+
+Check the current state of all workflow variables:
+
+\`\`\`bash
+curl -s -H "X-Auth-Token: {{AUTH_TOKEN}}" "http://localhost:{{PORT}}/api/workflows/instances/INSTANCE_ID"
+\`\`\`
+
+## Read Instance Timeline
+
+See execution history and previous state transitions:
+
+\`\`\`bash
+curl -s -H "X-Auth-Token: {{AUTH_TOKEN}}" "http://localhost:{{PORT}}/api/workflows/instances/INSTANCE_ID/timeline"
+\`\`\`
+
+## Read Step Logs
+
+See what previous agents did in earlier states:
+
+\`\`\`bash
+curl -s -H "X-Auth-Token: {{AUTH_TOKEN}}" "http://localhost:{{PORT}}/api/workflows/instances/INSTANCE_ID/steps"
+\`\`\`
+
+## Variable Interpolation
+
+In prompt templates, variables are referenced with double braces: \`{{variable_name}}\`.
+The workflow engine substitutes these before sending you the prompt.
+
+## Common Patterns
+
+### Pattern: Collect and Store
+1. Use a skill (e.g. slack-messaging) to gather information
+2. Update variables with the collected data
+3. Check available transitions, then transition to the next state
+
+### Pattern: Generate and Forward
+1. Use a skill (e.g. document-generator) to create output
+2. Store the output reference (filename, URL) in variables
+3. Transition to the next state so it can use the output
+
+### Pattern: Notify and Complete
+1. Use a skill (e.g. email-gmail, slack-messaging) to send a notification
+2. Store confirmation details in variables
+3. Transition to the next state
+
+### Pattern: Decision Point
+1. Evaluate current variables or task results
+2. Check available transitions for the different paths
+3. Choose the appropriate transition based on your decision
+
+## Execution Rules
+
+1. **Always update variables BEFORE transitioning** — downstream states depend on your output
+2. **Always transition explicitly** — check available transitions, then PUT the target state
+3. **Use only assigned skills** — the workflow definition specifies which skills you should use
+4. **Do not skip steps** — execute the full task described in your prompt
+5. **Handle errors gracefully** — if a skill fails, transition to an error state or include error details
+6. **Be concise** — the reason in your transition should summarize what you did and why
+
+## Error Handling
+
+If your task fails, check available transitions for an error/failure path and transition there:
+
+\`\`\`bash
+# Check for error transitions
+curl -s -H "X-Auth-Token: {{AUTH_TOKEN}}" "http://localhost:{{PORT}}/api/workflows/instances/INSTANCE_ID/available-transitions"
+
+# Transition to the error state
+curl -s -X PUT "http://localhost:{{PORT}}/api/workflows/instances/INSTANCE_ID/transition" \\
+  -H "Content-Type: application/json" \\
+  -H "X-Auth-Token: {{AUTH_TOKEN}}" \\
+  -d '{ "targetStateId": "ERROR_STATE_ID", "reason": "FAILED: reason for failure" }'
+\`\`\`
+
+If no error transition exists, use the event-based completion as fallback:
+
+\`\`\`bash
+curl -s -X POST "http://localhost:{{PORT}}/api/workflows/instances/INSTANCE_ID/event" \\
+  -H "Content-Type: application/json" \\
+  -H "X-Auth-Token: {{AUTH_TOKEN}}" \\
+  -d '{ "eventType": "agent_complete", "data": { "agentResponse": "FAILED: reason for failure", "error": true } }'
+\`\`\`
+`,
+};

package/dist/src/packages/server/data/builtin-skills/workflow-designer.js

@@ -168,6 +168,161 @@ curl -s -X POST "http://localhost:{{PORT}}/api/workflows/instances/INSTANCE_ID/e
 | \`helix\` | DNA-like double spiral |
 | \`clockwork\` | Mechanical gears and cogs |
 
+## Get Instance Details
+
+\`\`\`bash
+curl -s -H "X-Auth-Token: {{AUTH_TOKEN}}" "http://localhost:{{PORT}}/api/workflows/instances/INSTANCE_ID"
+\`\`\`
+
+Response includes current state, variables, status, and execution progress.
+
+## List All Instances (with filtering)
+
+\`\`\`bash
+curl -s -H "X-Auth-Token: {{AUTH_TOKEN}}" "http://localhost:{{PORT}}/api/workflows/instances?workflowDefId=WORKFLOW_ID&status=running&limit=50"
+\`\`\`
+
+Filters available: \`workflowDefId\`, \`status\` (running, paused, completed, failed, cancelled), \`limit\`, \`offset\`
+
+## Pause a Running Instance
+
+Stop a workflow instance temporarily. All timers are suspended, state is preserved.
+
+\`\`\`bash
+curl -s -X PATCH "http://localhost:{{PORT}}/api/workflows/instances/INSTANCE_ID/pause" \\
+  -H "X-Auth-Token: {{AUTH_TOKEN}}"
+\`\`\`
+
+## Resume a Paused Instance
+
+Continue a paused workflow from where it left off.
+
+\`\`\`bash
+curl -s -X PATCH "http://localhost:{{PORT}}/api/workflows/instances/INSTANCE_ID/resume" \\
+  -H "X-Auth-Token: {{AUTH_TOKEN}}"
+\`\`\`
+
+## Cancel a Running Instance
+
+Terminate a workflow instance and mark it as cancelled.
+
+\`\`\`bash
+curl -s -X PATCH "http://localhost:{{PORT}}/api/workflows/instances/INSTANCE_ID/cancel" \\
+  -H "X-Auth-Token: {{AUTH_TOKEN}}"
+\`\`\`
+
+## Get Instance Execution Timeline
+
+View a chronological trace of state transitions, including timestamps and conditions that triggered each transition.
+
+\`\`\`bash
+curl -s -H "X-Auth-Token: {{AUTH_TOKEN}}" "http://localhost:{{PORT}}/api/workflows/instances/INSTANCE_ID/timeline"
+\`\`\`
+
+## Get Instance Steps
+
+View detailed information about each state execution: agent assignments, outcomes, variable changes.
+
+\`\`\`bash
+curl -s -H "X-Auth-Token: {{AUTH_TOKEN}}" "http://localhost:{{PORT}}/api/workflows/instances/INSTANCE_ID/steps"
+\`\`\`
+
+## Get Variable Change History
+
+Track all changes to a specific workflow variable (or all variables).
+
+\`\`\`bash
+curl -s -H "X-Auth-Token: {{AUTH_TOKEN}}" "http://localhost:{{PORT}}/api/workflows/instances/INSTANCE_ID/variables?variableName=release_name"
+\`\`\`
+
+Omit \`variableName\` to see history of all variables.
+
+## Get Instance Reasoning Trace
+
+View the decision-making logic and Claude reasoning for each workflow step (if available).
+
+\`\`\`bash
+curl -s -H "X-Auth-Token: {{AUTH_TOKEN}}" "http://localhost:{{PORT}}/api/workflows/instances/INSTANCE_ID/reasoning"
+\`\`\`
+
+## Trigger Manual Transition
+
+Force a workflow to transition via a specific transition ID. Useful for manual approvals or overrides.
+
+\`\`\`bash
+curl -s -X POST "http://localhost:{{PORT}}/api/workflows/instances/INSTANCE_ID/transition" \\
+  -H "Content-Type: application/json" \\
+  -H "X-Auth-Token: {{AUTH_TOKEN}}" \\
+  -d '{ "transitionId": "t1" }'
+\`\`\`
+
+## Get Conversational Explanation of Workflow
+
+Ask Claude AI questions about a workflow definition, execution trace, or design.
+
+\`\`\`bash
+curl -s -X POST "http://localhost:{{PORT}}/api/workflows/WORKFLOW_ID/chat" \\
+  -H "Content-Type: application/json" \\
+  -H "X-Auth-Token: {{AUTH_TOKEN}}" \\
+  -d '{
+    "message": "Why did the workflow transition to the error state?",
+    "scope": {
+      "type": "instance",
+      "instanceId": "INSTANCE_ID"
+    },
+    "conversationHistory": []
+  }'
+\`\`\`
+
+Scope types: \`definition\`, \`instance\`
+
+## Troubleshooting Common Issues
+
+### Workflow Stuck in a State
+
+1. Get timeline to see last state: \`GET /instances/INSTANCE_ID/timeline\`
+2. Check variable history: \`GET /instances/INSTANCE_ID/variables\`
+3. Pause the instance: \`PATCH /instances/INSTANCE_ID/pause\`
+4. Fix any issues manually or via variable update
+5. Resume: \`PATCH /instances/INSTANCE_ID/resume\`
+6. Or manually transition: \`POST /instances/INSTANCE_ID/transition\` with correct transitionId
+
+### Agent Task Not Completing
+
+1. Get steps to see agent's task: \`GET /instances/INSTANCE_ID/steps\`
+2. Check reasoning trace: \`GET /instances/INSTANCE_ID/reasoning\`
+3. Pause the instance while debugging
+4. Contact the assigned agent or check agent logs
+5. Manually transition once resolved
+
+### Variable Not Updating
+
+1. Check variable history: \`GET /instances/INSTANCE_ID/variables?variableName=YOUR_VAR\`
+2. Use PATCH /variables endpoint to set correct value if needed
+3. Verify agents in action states are using correct variable names in prompts
+4. Use {{variable_name}} syntax (double braces) in promptTemplate
+
+### Timeout Issues
+
+- If a wait state is timing out incorrectly, check the \`afterMs\` value in the wait action config
+- Get timeline to confirm timeout fired: \`GET /instances/INSTANCE_ID/timeline\`
+- Pause and manually transition if needed
+
+## Instance Lifecycle State Diagram
+
+A workflow instance flows through these states:
+
+\`\`\`
+idle → running ──→ completed
+       ↓    ↑
+     paused─┘
+       ↓
+    cancelled
+
+       ↓
+     failed ← (if agent/trigger error)
+\`\`\`
+
 ## Design Guidelines
 
 1. **State naming**: Use descriptive, action-oriented names ("Collect Requirements", "Generate Report")
@@ -176,5 +331,7 @@ curl -s -X POST "http://localhost:{{PORT}}/api/workflows/instances/INSTANCE_ID/e
 4. **Skills**: Assign only the skills each state needs (slack-messaging, email-gmail, jira-service-desk, document-generator, google-calendar)
 5. **Error handling**: Add timeout transitions on wait states. Consider error/escalation states
 6. **Position**: Place workflow models near related buildings/agents in the work area
+7. **Monitoring**: Use the chat API and timeline queries during development to understand execution flow
+8. **Debugging**: When instances get stuck, use pause/resume and manual transitions as escape hatches
 `,
 };

package/dist/src/packages/server/data/event-queries.js

@@ -388,6 +388,9 @@ function workflowRowToInstance(row) {
         activeTriggerIds: fromJson(row.active_trigger_ids) ?? [],
         activeTimers: fromJson(row.active_timers) ?? [],
         error: row.error ?? undefined,
+        agentId: row.agent_id ?? undefined,
+        triggerId: row.trigger_id ?? undefined,
+        triggerData: fromJson(row.trigger_data_json) ?? undefined,
         createdAt: row.created_at,
         updatedAt: row.updated_at,
         completedAt: row.completed_at ?? undefined,
@@ -404,6 +407,9 @@ export function insertWorkflowInstance(instance) {
         active_trigger_ids: JSON.stringify(instance.activeTriggerIds),
         active_timers: JSON.stringify(instance.activeTimers),
         error: instance.error ?? null,
+        agent_id: instance.agentId ?? null,
+        trigger_id: instance.triggerId ?? null,
+        trigger_data_json: instance.triggerData ? JSON.stringify(instance.triggerData) : null,
         created_at: instance.createdAt,
         updated_at: instance.updatedAt,
         completed_at: instance.completedAt ?? null,
@@ -436,6 +442,18 @@ export function updateWorkflowInstance(id, updates) {
         setClauses.push('error = ?');
         params.push(updates.error);
     }
+    if (updates.agentId !== undefined) {
+        setClauses.push('agent_id = ?');
+        params.push(updates.agentId);
+    }
+    if (updates.triggerId !== undefined) {
+        setClauses.push('trigger_id = ?');
+        params.push(updates.triggerId);
+    }
+    if (updates.triggerData !== undefined) {
+        setClauses.push('trigger_data_json = ?');
+        params.push(JSON.stringify(updates.triggerData));
+    }
     if (updates.updatedAt !== undefined) {
         setClauses.push('updated_at = ?');
         params.push(updates.updatedAt);
@@ -504,6 +522,7 @@ function stepLogRowToModel(row) {
         promptSent: row.prompt_sent ?? undefined,
         agentResponse: row.agent_response ?? undefined,
         agentReasoning: row.agent_reasoning ?? undefined,
+        agentSummary: row.agent_summary ?? undefined,
         triggerId: row.trigger_id ?? undefined,
         triggerPayload: fromJson(row.trigger_payload),
         variablesBefore: fromJson(row.variables_before),
@@ -528,6 +547,7 @@ export function insertStepLog(step) {
         prompt_sent: step.promptSent ?? null,
         agent_response: step.agentResponse ?? null,
         agent_reasoning: step.agentReasoning ?? null,
+        agent_summary: step.agentSummary ?? null,
         trigger_id: step.triggerId ?? null,
         trigger_payload: toJson(step.triggerPayload),
         variables_before: toJson(step.variablesBefore),
@@ -550,6 +570,10 @@ export function updateStepLog(id, updates) {
         setClauses.push('agent_reasoning = ?');
         params.push(updates.agentReasoning);
     }
+    if (updates.agentSummary !== undefined) {
+        setClauses.push('agent_summary = ?');
+        params.push(updates.agentSummary);
+    }
     if (updates.variablesAfter !== undefined) {
         setClauses.push('variables_after = ?');
         params.push(toJson(updates.variablesAfter));

package/dist/src/packages/server/data/migrations/002_workflow_agent_binding.sql

@@ -0,0 +1,14 @@
+-- Migration 002: Workflow-as-Agent Architecture
+-- Adds agent binding, trigger correlation, and agent summary fields
+
+-- ─── workflow_instances: add agent_id and trigger correlation ───
+
+ALTER TABLE workflow_instances ADD COLUMN agent_id TEXT;
+ALTER TABLE workflow_instances ADD COLUMN trigger_id TEXT;
+ALTER TABLE workflow_instances ADD COLUMN trigger_data_json TEXT;
+
+CREATE INDEX idx_workflow_instances_agent ON workflow_instances(agent_id);
+
+-- ─── workflow_step_log: add agent_summary ───
+
+ALTER TABLE workflow_step_log ADD COLUMN agent_summary TEXT;

package/dist/src/packages/server/data/migrations/003_matcher_executions.sql

@@ -0,0 +1,19 @@
+-- Migration 003: Matcher Executions
+-- Debugging layer for trigger matcher pipeline visibility
+
+CREATE TABLE matcher_executions (
+  id                INTEGER PRIMARY KEY AUTOINCREMENT,
+  trigger_event_id  INTEGER,
+  trigger_id        TEXT NOT NULL,
+  matcher_type      TEXT NOT NULL,
+  matcher_name      TEXT NOT NULL,
+  executed_at       INTEGER NOT NULL,
+  matched           INTEGER NOT NULL DEFAULT 0,
+  confidence        REAL,
+  reason            TEXT,
+  result_json       TEXT,
+  FOREIGN KEY (trigger_event_id) REFERENCES trigger_events(id)
+);
+
+CREATE INDEX idx_matcher_executions_event ON matcher_executions(trigger_event_id);
+CREATE INDEX idx_matcher_executions_trigger ON matcher_executions(trigger_id);

package/dist/src/packages/server/data/migrations/004_matcher_message_source.sql

@@ -0,0 +1,8 @@
+-- Migration 004: Matcher Message Source
+-- Adds source tracking to matcher_executions for per-message visibility
+
+ALTER TABLE matcher_executions ADD COLUMN source_type TEXT;
+ALTER TABLE matcher_executions ADD COLUMN source_id TEXT;
+ALTER TABLE matcher_executions ADD COLUMN source_timestamp INTEGER;
+
+CREATE INDEX idx_matcher_executions_source ON matcher_executions(source_type, source_id);