@probelabs/visor 0.1.107 → 0.1.112

package/dist/docs/engine-pause-resume-rfc.md

@@ -0,0 +1,192 @@
+# RFC: Proper Pause/Resume for State-Machine Engine (Event‑Bus + Snapshots)
+
+Status: draft
+
+Owner: visor engine
+
+Last updated: 2025-11-20
+
+## Summary
+
+We will add first‑class pause/resume to the state‑machine engine so long‑running or interactive workflows (e.g., human‑input in Slack) can suspend execution and later continue exactly where they left off, without re‑running completed work. The design builds on our event‑bus architecture and the existing ExecutionJournal. It introduces JSON snapshots of the engine’s RunState and journal, and a resume entrypoint that hydrates a new runner from a snapshot. Slack and other frontends trigger resume when the awaited user event arrives.
+
+## Goals
+
+- Pause a workflow at deterministic points (e.g., when HumanInputRequested is emitted) and resume later.
+- Persist minimal, safe state; do not leak secrets.
+- Avoid re‑executing completed checks; preserve outputs/history/routing.
+- Keep the event‑driven integration pattern (no long‑lived in‑memory runs).
+- Be robust to process restarts (snapshots on disk); work in CI and serverless.
+
+## Non‑Goals (initial)
+
+- Arbitrary mid‑provider checkpointing (we pause at well‑defined integration points).
+- Time‑travel debugging; only last consistent snapshot is kept by default.
+
+## Current State (as of this RFC)
+
+- We already end the run on human‑input and rely on PromptState + a new event to re‑enter the workflow. This re‑entry currently performs a cold start and plans from scratch, which is acceptable but can be inefficient and can re‑visit guards.
+- Engine has ExecutionJournal and experimental `saveSnapshotToFile()` that serializes RunState and journal; there is no hydrate/resume path.
+
+## High‑Level Design
+
+1) Snapshots (JSON)
+- When the engine encounters a pause point (e.g., HumanInputRequested), it writes a snapshot JSON file containing:
+  - `version`: number
+  - `sessionId`, `event` (trigger), `wave`
+  - `state`: serialized RunState (via a new `serializeRunState()` + `deserializeRunState()` pair)
+  - `journal`: visible `JournalEntry[]` up to the snapshot
+  - `requestedChecks`: string[]
+  - `meta`: optional { checkId, channel, threadTs, threadKey, promptTs }
+
+2) Pause Points
+- Initial scope: provider‑level pause during HumanInputRequested (event‑bus). Other future pause points can hook the same API.
+
+3) Resume Entry Point
+- New `engine.resumeFromSnapshot(snapshot, overrides)` that:
+  - Rebuilds `EngineContext` (config, requestedChecks, sessionId, event, journal)
+  - Creates a new `StateMachineRunner`, calls `runner.setState(deserializedRunState)` (new API), and continues the main loop.
+  - Applies overrides such as `webhookContext` to allow providers to consume the awaited input.
+
+4) Frontends & PromptState
+- Frontends (Slack) maintain the human prompt UI and store a pointer to the snapshot path in PromptState. On the awaited reply, frontends look up the snapshot and call `resumeFromSnapshot()` (via the socket/webhook path).
+
+5) Storage & Retention
+- Default snapshot directory: `${VISOR_SNAPSHOT_DIR || '.visor/snapshots'}`.
+- File naming: `${threadKey}-${checkId}.json` where `threadKey = "${channel}:${threadTs}"`.
+- Retention: delete on successful resume; background TTL cleanup (e.g., 24h) to reap orphans.
+
+## Detailed Design
+
+### A. RunState serialization/hydration
+
+- Today we have `serializeRunState(state)` for JSON. We will:
+  - Add `deserializeRunState(obj): RunState` (recreates Sets/Maps and ensures invariants).
+  - Add `StateMachineRunner.setState(state: RunState)`; only valid before `run()`; asserts state consistency.
+  - Ensure we never serialize provider internals or secrets; RunState contains only orchestration fields.
+
+### B. Engine APIs
+
+- `StateMachineExecutionEngine.saveSnapshotToFile(filePath)` already exists.
+- Add `resumeFromSnapshot(snapshot: SnapshotJson, opts?: { webhookContext?: ..., debug?: boolean }): Promise<ExecutionResult>`
+  - Recreate `EngineContext` using config and `snapshot.sessionId`.
+  - Rehydrate journal into a fresh `ExecutionJournal` (push `snapshot.journal`).
+  - Hydrate runner with `deserializeRunState(snapshot.state)` then continue.
+  - Wire `eventBus` and frontends like a normal run so integrations keep working.
+
+### C. Snapshot triggers & lifecycle
+
+- Human‑input path:
+  - Provider emits `HumanInputRequested(checkId, prompt, channel, threadTs, threadKey)` and returns.
+  - Engine listens for `HumanInputRequested` during the run and immediately calls `saveSnapshotToFile()` to `${SNAP_DIR}/${threadKey}-${checkId}.json`.
+  - Slack Frontend posts the prompt, also sets PromptState for `${threadKey}` with `snapshotPath`.
+  - The run completes (no blocking).
+  - On Slack reply in the same thread, the socket path looks up `${snapshotPath}` and calls `resumeFromSnapshot()` with the current `webhookContext`.
+- After a successful resume (terminal StateTransition), engine deletes the snapshot file and clears PromptState.
+
+### D. Idempotency & Safety
+
+- Completed checks are recorded in RunState + journal; resuming does not re‑run them.
+- We treat new inbound input as a new event; routing/guards continue from the hydrated state.
+- If snapshot is missing or corrupted, we gracefully fall back to a cold run (today’s behavior).
+
+### E. Security/Privacy
+
+- Snapshots omit secrets and environment variables. Only engine orchestration and committed results are stored.
+- Snapshot directory is local by default; users can relocate via `VISOR_SNAPSHOT_DIR`.
+
+## File Layout
+
+```
+.visor/
+  snapshots/
+    C123:1700.55-ask.json   # example: threadKey+checkId
+```
+
+## Snapshot JSON (v1) — Example
+
+```json
+{
+  "version": 1,
+  "sessionId": "a1b2c3",
+  "event": "issue_comment",
+  "wave": 2,
+  "state": { "currentState": "Routing", "wave": 2, "activeDispatches": [], "completedChecks": ["lint"], "stats": [], "historyLog": [], "forwardRunGuards": [], "currentLevelChecks": [], "pendingRunScopes": [] },
+  "journal": [
+    { "commitId": 1, "sessionId": "a1b2c3", "scope": [], "checkId": "lint", "event": "issue_comment", "result": { "issues": [] } }
+  ],
+  "requestedChecks": ["ask", "refine", "run-commands"],
+  "meta": { "checkId": "ask", "channel": "C123", "threadTs": "1700.55", "threadKey": "C123:1700.55", "promptTs": "1700.66" }
+}
+```
+
+## Slack Integration Flow (pause/resume)
+
+1) Run emits `HumanInputRequested` → engine writes snapshot to `${threadKey}-${checkId}.json`.
+2) Slack Frontend posts prompt and sets PromptState with `snapshotPath`.
+3) User replies in same thread; socket receives the envelope, finds PromptState/snapshot.
+4) Engine `resumeFromSnapshot(snapshot, { webhookContext })` continues the workflow.
+5) On terminal state, snapshot is deleted and PromptState cleared.
+
+## CLI/Config
+
+- Env:
+  - `VISOR_SNAPSHOT_DIR` — optional base directory for snapshots.
+- Config (optional):
+  - `limits.max_workflow_depth` continues to apply; pause/resume doesn’t alter nesting rules.
+  - Future: `snapshots.enabled` (default true in Slack/webhook contexts), `snapshots.retentionHours`.
+
+## Failure Modes & Recovery
+
+- Missing snapshot: fall back to cold run.
+- Corrupt snapshot: log, fall back to cold run.
+- Multiple prompts in the same thread: last snapshot wins; older ones are overwritten.
+- Process restart: snapshots survive; PromptState TTL means we rely on snapshot presence to resume.
+
+## Testing Plan
+
+1) Unit
+- `deserializeRunState(serializeRunState(state))` round‑trip equals for non‑object identity fields.
+- `resumeFromSnapshot` continues and does not re‑execute completed checks (assert via journal size).
+
+2) Integration (Slack)
+- First run → emits HumanInputRequested, snapshot written, prompt posted, run completes.
+- Second run (reply) → loads snapshot, resumes, consumes reply, deletes snapshot.
+
+3) Crash/Restart Simulation
+- Save snapshot, reset in‑memory state, then `resumeFromSnapshot` from file.
+
+## Rollout
+
+- Phase 1 (behind feature switch in code): add hydrate APIs and write snapshots on HumanInputRequested; continue to cold‑run on reply but verify snapshot creation.
+- Phase 2: wire socket path to call `resumeFromSnapshot`; delete snapshot on success.
+- Phase 3: expand pause points if needed; add retention cleanup task.
+
+## Work Items
+
+- Runner
+  - [ ] Add `deserializeRunState()`
+  - [ ] Add `runner.setState()`
+- Engine
+  - [ ] Add `resumeFromSnapshot()`
+  - [ ] On HumanInputRequested → `saveSnapshotToFile()` (path via threadKey+checkId)
+- Slack
+  - [ ] PromptState stores `snapshotPath` alongside prompt metadata
+  - [ ] Socket runner loads snapshot and calls `resumeFromSnapshot()` on reply
+- Tests
+  - [ ] Unit: serialize/deserialize round‑trip
+  - [ ] Integration: pause/resume end‑to‑end (Slack fixture), snapshot deletion
+- Docs
+  - [ ] Update Slack integration docs and human‑input provider docs
+
+## Alternatives Considered
+
+- Keeping the runner alive across Slack replies → fragile in CI/serverless and ties up resources.
+- Persisting only high‑level outputs and re‑planning on resume → simpler but can re‑emit side‑effects and re‑evaluate guards unexpectedly.
+
+## Open Questions
+
+- Should we also emit a `RunPaused` event for analytics/observability?
+- Do we want a structured `output.awaiting = true` signal at pause for downstream guards?
+- Snapshot encryption at rest (out of scope for now; directory is local/trusted).
+

package/dist/docs/lifecycle-hooks.md

@@ -0,0 +1,253 @@
+# Lifecycle Hooks
+
+Lifecycle hooks allow you to execute preprocessing or setup tasks automatically before a step runs. This is particularly useful for enriching context, fetching external data, or preparing the environment.
+
+## `on_init` Hook
+
+The `on_init` hook runs **before** a step executes, allowing you to:
+- Fetch external data (JIRA issues, metrics, configuration)
+- Enrich AI prompts with additional context
+- Execute setup tasks or validation
+- Invoke custom tools, steps, or workflows
+
+### Basic Usage
+
+```yaml
+steps:
+  my-check:
+    type: ai
+    on_init:
+      run:
+        - tool: fetch-jira-issue
+          with:
+            issue_key: "PROJ-123"
+          as: jira-data
+    prompt: |
+      Review this PR considering JIRA issue: {{ outputs['jira-data'] | json }}
+```
+
+### Features
+
+#### 1. Multiple Invocations
+
+Execute multiple tools, steps, or workflows in sequence:
+
+```yaml
+on_init:
+  run:
+    - tool: fetch-user-data
+      as: users
+    - tool: fetch-config
+      as: config
+    - workflow: validate-environment
+      as: validation
+```
+
+#### 2. Custom Arguments
+
+Pass arguments to tools and workflows using `with`:
+
+```yaml
+on_init:
+  run:
+    - tool: fetch-external-data
+      with:
+        source: metrics-api
+        format: json
+      as: metrics
+```
+
+#### 3. Custom Output Names
+
+Store outputs with custom names using `as`:
+
+```yaml
+on_init:
+  run:
+    - tool: fetch-jira-issue
+      with:
+        issue_key: "PROJ-456"
+      as: jira-context  # Access via {{ outputs['jira-context'] }}
+```
+
+#### 4. Dynamic Preprocessing
+
+Use `run_js` for conditional preprocessing based on PR context:
+
+```yaml
+on_init:
+  run_js: |
+    const items = [];
+
+    // Fetch JIRA only if PR title contains issue key
+    const jiraMatch = pr.title.match(/PROJ-\d+/);
+    if (jiraMatch) {
+      items.push({
+        tool: 'fetch-jira-issue',
+        with: { issue_key: jiraMatch[0] },
+        as: 'jira-data'
+      });
+    }
+
+    // Fetch metrics if backend files changed
+    if (files.some(f => f.filename.includes('backend/'))) {
+      items.push({
+        tool: 'fetch-metrics',
+        as: 'backend-metrics'
+      });
+    }
+
+    return items;
+```
+
+### Invocation Types
+
+#### Tool Invocation
+
+Execute a custom MCP tool:
+
+```yaml
+on_init:
+  run:
+    - tool: my-custom-tool
+      with:
+        param1: value1
+      as: tool-output
+```
+
+#### Step Invocation
+
+Execute another step:
+
+```yaml
+on_init:
+  run:
+    - step: preprocessing-step
+      with:
+        input: "{{ pr.title }}"
+      as: preprocessed
+```
+
+#### Workflow Invocation
+
+Execute a workflow:
+
+```yaml
+on_init:
+  run:
+    - workflow: data-enrichment
+      with:
+        source: production
+      as: enriched-data
+```
+
+### Accessing Outputs
+
+Outputs from `on_init` items are available in the step's execution context:
+
+```yaml
+steps:
+  my-check:
+    type: command
+    on_init:
+      run:
+        - tool: fetch-data
+          as: external-data
+    exec: |
+      echo "Fetched data: {{ outputs['external-data'] | json }}"
+```
+
+### Reusable Tools and Workflows
+
+Define tools and workflows in separate files and import them:
+
+**reusable-tools.yaml:**
+```yaml
+version: "1.0"
+tools:
+  fetch-jira-issue:
+    name: fetch-jira-issue
+    exec: |
+      # Fetch JIRA issue...
+    parseJson: true
+steps: {}
+```
+
+**Main configuration:**
+```yaml
+version: "1.0"
+extends:
+  - ./reusable-tools.yaml
+
+steps:
+  ai-review:
+    type: ai
+    on_init:
+      run:
+        - tool: fetch-jira-issue
+          with:
+            issue_key: "{{ pr.title | regex_search: '[A-Z]+-[0-9]+' }}"
+          as: jira
+    prompt: "Review considering: {{ outputs.jira | json }}"
+```
+
+### Loop Protection
+
+To prevent infinite loops and excessive preprocessing:
+
+- **Maximum 50 items**: `on_init` can execute at most 50 items (configurable via `MAX_ON_INIT_ITEMS`)
+- **No nested execution**: `on_init` hooks within `on_init` items are skipped
+- **Separate from routing loops**: `on_init` loop protection is independent of `on_success`/`on_fail` routing
+
+### forEach Integration
+
+**How on_init works with forEach**: When a check uses `forEach`, the `on_init` hook runs **once before the forEach loop starts**, not once per item:
+
+```yaml
+steps:
+  analyze-files:
+    type: ai
+    forEach: file-list
+    on_init:  # Runs ONCE before processing all files
+      run:
+        - tool: fetch-project-config
+          as: config
+    prompt: |
+      Analyze {{ item }} using config: {{ outputs.config }}
+      # outputs.config is available to ALL forEach iterations
+```
+
+This design allows you to:
+- Fetch shared data once that all iterations can use
+- Avoid redundant preprocessing for each item
+- Keep forEach loops efficient
+
+If you need per-item preprocessing, add `on_init` to child steps that depend on the forEach check.
+
+### Examples
+
+See the `examples/` directory for comprehensive examples:
+
+- **examples/reusable-tools.yaml** - Reusable tool library with 3 custom tools (fetch-jira-issue, fetch-external-data, validate-data)
+- **examples/reusable-workflows.yaml** - Reusable workflow library with 3 workflows (data-enrichment, issue-triage, multi-step-validation)
+- **examples/on-init-import-demo.yaml** - Complete demonstration showing:
+  - Using multiple imported tools in on_init
+  - Invoking imported workflows
+  - Chaining tools and workflows together
+  - Reusing the same tool multiple times with different parameters
+  - Includes 4 passing test cases
+
+### Best Practices
+
+1. **Keep preprocessing lightweight**: `on_init` runs before every step execution
+2. **Use custom output names**: Make outputs easy to identify with descriptive `as` names
+3. **Leverage reusability**: Define common tools/workflows once and import them
+4. **Use `run_js` for conditionals**: Avoid fetching unnecessary data
+5. **Handle failures gracefully**: Consider what happens if preprocessing fails
+
+### See Also
+
+- [Custom Tools](./custom-tools.md) - Define reusable MCP tools
+- [Workflows](./workflows.md) - Create reusable workflows
+- [Liquid Templates](./liquid-templates.md) - Template syntax for dynamic values
+- [RFC: on_init Hook](./rfc/on_init-hook.md) - Design proposal and rationale

package/dist/docs/liquid-templates.md

@@ -198,8 +198,151 @@ echo '{{ pr | json }}' | jq .
 {{ files | map: "filename" }}   # Array of filenames
 ```
 
+### Chat History Helper
+
+The `chat_history` filter turns one or more check histories into a linear, timestamp‑sorted chat transcript. This is especially useful for human‑input + AI chat flows (Slack, CLI, etc.).
+
+Basic usage:
+
+```liquid
+{% assign history = '' | chat_history: 'ask', 'reply' %}
+{% for m in history %}
+  {{ m.role | capitalize }}: {{ m.text }}
+{% endfor %}
+```
+
+Each `history` item has:
+
+- `m.step`  – originating check name (e.g. `"ask"`, `"reply"`)
+- `m.role`  – logical role (`"user"` or `"assistant"` by default)
+- `m.text`  – normalized text (from `.text` / `.content` / fallback field)
+- `m.ts`    – timestamp used for ordering
+- `m.raw`   – original `outputs_history[step][i]` object
+
+By default:
+
+- Human input checks (`type: human-input`) map to `role: "user"`.
+- AI checks (`type: ai`) map to `role: "assistant"`.
+- Messages are sorted by `ts` ascending across all steps.
+
+Advanced options (all optional, passed as keyword arguments):
+
+```liquid
+{% assign history = '' | chat_history:
+  'ask',
+  'reply',
+  direction: 'asc',          # or 'desc' (default: 'asc')
+  limit: 50,                 # keep at most N messages (after sorting)
+  text: {
+    default_field: 'text',   # which field to prefer when .text/.content missing
+    by_step: {
+      'summary': 'summary.text'  # use nested path for specific steps
+    }
+  },
+  roles: {
+    by_type: {
+      'human-input': 'user',
+      'ai': 'assistant'
+    },
+    by_step: {
+      'system-note': 'system'
+    },
+    default: 'assistant'
+  },
+  role_map: 'ask=user,reply=assistant'  # compact per-step override
+%}
+```
+
+Precedence for `role` resolution:
+
+1. `role_map` / `roles.by_step[step]` (explicit step override)
+2. `roles.by_type[checkType]` (e.g. `'human-input'`, `'ai'`)
+3. Built‑in defaults: `human-input → user`, `ai → assistant`
+4. `roles.default` if provided
+5. Fallback: `"assistant"`
+
+Examples:
+
+```liquid
+{%- assign history = '' | chat_history: 'ask', 'reply' -%}
+{%- for m in history -%}
+  {{ m.role }}: {{ m.text }}
+{%- endfor -%}
+```
+
+```liquid
+{%- assign history = '' | chat_history: 'ask', 'clarify', 'reply', direction: 'desc', limit: 5 -%}
+{%- for m in history -%}
+  [{{ m.step }}][{{ m.role }}] {{ m.text }}
+{%- endfor -%}
+```
+
 <!-- Removed merge_sort_by example: filter no longer provided -->
 
+### Conversation Context (Slack, GitHub, etc.)
+
+For transport‑aware prompts, Visor exposes a normalized `conversation` object in Liquid
+for AI checks:
+
+```liquid
+{% if conversation %}
+  Transport: {{ conversation.transport }}   {# 'slack', 'github', ... #}
+  Thread: {{ conversation.thread.id }}
+  {% if conversation.thread.url %}
+    Link: {{ conversation.thread.url }}
+  {% endif %}
+
+  {% for m in conversation.messages %}
+    {{ m.user }} ({{ m.role }} at {{ m.timestamp }}): {{ m.text }}
+  {% endfor %}
+
+  Latest:
+  {{ conversation.current.user }} ({{ conversation.current.role }}): {{ conversation.current.text }}
+{% endif %}
+```
+
+Contract:
+
+- `conversation.transport` – transport identifier (`'slack'`, `'github'`, etc.)
+- `conversation.thread.id` – stable thread key:
+  - Slack: `"channel:thread_ts"`
+  - GitHub: `"owner/repo#number"`
+- `conversation.thread.url` – optional deep link (Slack thread or GitHub PR/issue URL)
+- `conversation.messages[]` – full history as normalized messages:
+  - `role`: `'user' | 'bot'`
+  - `user`: Slack user id or GitHub login
+  - `text`: message body
+  - `timestamp`: message timestamp
+  - `origin`: e.g. `'visor'` for bot messages, `'github'` for GitHub messages
+- `conversation.current` – message that triggered the current run (same shape as above)
+- `conversation.attributes` – extra metadata (e.g. `channel`, `thread_ts`, `owner`, `repo`, `number`, `event_name`, `action`)
+
+Transport‑specific helpers:
+
+- Slack:
+  - `slack.event` – raw Slack event payload (channel, ts, text, etc.)
+  - `slack.conversation` – same structure as `conversation` for Slack runs
+- GitHub:
+  - `event` – GitHub event metadata and payload (unchanged)
+  - A normalized GitHub conversation is also attached so `conversation.transport == 'github'`
+    reflects the PR/issue body and comment history.
+
+You can combine `conversation` with `chat_history`:
+
+```liquid
+{% assign history = '' | chat_history: 'ask', 'reply' %}
+{% if conversation and conversation.transport == 'slack' %}
+  # Slack thread:
+  {% for m in conversation.messages %}
+    {{ m.user }}: {{ m.text }}
+  {% endfor %}
+{% endif %}
+
+{% for m in history %}
+  [{{ m.step }}][{{ m.role }}] {{ m.text }}
+{% endfor %}
+```
+
 ## Examples
 
 ### Debugging Outputs