snow-flow 10.0.143 → 10.0.145

package/package.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
-  "version": "10.0.143",
+  "version": "10.0.145",
   "name": "snow-flow",
   "description": "Snow-Flow - ServiceNow Multi-Agent Development Framework powered by AI",
   "license": "Elastic-2.0",

package/src/project/agents-template.txt

@@ -15,34 +15,6 @@ Transform user intent expressed in natural language into concrete ServiceNow art
 
 ---
 
-## 🌐 WEB TOOLS (Disabled by Default)
-
-The following tools are **disabled by default** to prevent accidental prompt injection from external web content:
-
-- **webfetch** – Fetches and reads content from arbitrary URLs
-- **websearch** – Searches the web via Exa API
-- **codesearch** – Searches code repositories via Exa API
-
-These tools make external HTTP calls that could expose the agent to untrusted content. They are opt-in only.
-
-### Enabling Web Tools
-
-Users can enable them in their `snow-code.jsonc` configuration:
-
-```jsonc
-{
-  "tools": {
-    "webfetch": true,
-    "websearch": true,
-    "codesearch": true
-  }
-}
-```
-
-Enable only the tools you need. Each can be toggled independently.
-
----
-
 ## 🔍 HOW MCP TOOLS WORK
 
 ### CRITICAL: Tools are NOT directly available!
@@ -464,32 +436,21 @@ function($scope) {
 
 ## 🛠️ DEVELOPMENT WORKFLOWS
 
-### Workflow 1: Standard Development
+### Workflow 1: Standard Development (widgets, business rules, scoped apps, etc.)
 
 Before creating ANY ServiceNow artifact, follow these steps IN ORDER:
 
-1. **Decide Application Scope** - Scoped app or global?
-2. **Create Update Set** - With descriptive name, ensure auto_switch=true. Get the sys_id from the response!
-3. **Start Activity Tracking** - Use activity_start with the ACTUAL Update Set sys_id (never use placeholders like "pending")
-4. **Do Your Development Work** - Create widgets, business rules, etc.
-5. **Log Each Artifact** - Use activity_add_artifact after each creation
-6. **Complete Activity and Update Set** - Use activity_complete and mark Update Set complete
+1. **Decide Application Scope** — Scoped app (x_vendor_appname format) or global? For scoped apps: use auto_create_update_set=true and auto_switch_scope=true
+2. **Create Update Set** — Descriptive name (e.g., "Feature: Incident Dashboard Widget"), ensure auto_switch=true. Get the sys_id from the response!
+3. **Start Activity Tracking** — Use activity_start with the ACTUAL Update Set sys_id (never use placeholders like "pending")
+4. **Develop** — Create your artifact(s). For widgets: ensure coherent HTML/Client/Server scripts (ES5 only!). For business rules: specify table, timing (before/after), ES5 script
+5. **Log Each Artifact** — Use activity_add_artifact after each creation (include artifactSysId!)
+6. **Test** — Verify behavior. For widgets: get instance URL for preview
+7. **Complete** — Use activity_complete and mark Update Set complete
 
-**⚠️ CRITICAL: Activity tracking requires REAL sys_ids!**
-- Always create the Update Set FIRST to get its sys_id
-- NEVER use placeholder values like "pending" for updateSetSysId
-- The activity_start call must include the actual 32-character sys_id from ServiceNow
+**⚠️ CRITICAL: Activity tracking requires REAL 32-character sys_ids from ServiceNow responses — NEVER placeholders!**
 
-### Workflow 2: Widget Development
-
-1. Create Update Set with descriptive name (e.g., "Feature: Incident Dashboard Widget") - get the sys_id!
-2. Start activity tracking with the ACTUAL Update Set sys_id (never use "pending")
-3. Create the widget with coherent HTML/Client/Server scripts (ES5 only!)
-4. Log the widget artifact with activity_add_artifact (include artifactSysId!)
-5. Get instance URL for preview
-6. Complete activity and Update Set
-
-### Workflow 3: Widget Debugging
+### Workflow 2: Widget Debugging
 
 1. Create Update Set for the fix
 2. Pull the widget to local filesystem for editing
@@ -497,35 +458,47 @@ Before creating ANY ServiceNow artifact, follow these steps IN ORDER:
 4. Push changes back to ServiceNow
 5. Complete Update Set
 
-### Workflow 4: Business Rule Creation
-
-1. Create Update Set
-2. Create business rule with:
-   - Descriptive name
-   - Target table
-   - When to run (before/after insert/update/delete)
-   - Script in ES5 ONLY!
-3. Test the business rule
-4. Complete Update Set
-
-### Workflow 5: Data Query (No Update Set Needed)
+### Workflow 3: Data Query (No Update Set Needed)
 
 For read-only operations, no Update Set is needed:
 - Query incidents, users, or any table
 - Analyze data patterns
 - Generate reports
 
-### Workflow 6: Scoped Application Development
-
-1. Create the application:
-   - Provide name, scope (x_vendor_appname format), version
-   - auto_create_update_set=true creates Update Set automatically
-   - auto_switch_scope=true switches to new scope automatically
-   - IMPORTANT: Get the sys_id of the created Update Set from the response!
-2. Start activity tracking with the ACTUAL Update Set sys_id (never use "pending")
-3. Log the application as an artifact with activity_add_artifact (include artifactSysId!)
-4. Create widgets, business rules, etc. (all tracked in application scope)
-5. Complete activity and Update Set
+### Workflow 4: Tool Debugging & Mutation Inspection
+
+When debugging MCP tool behavior or verifying what actually happened on the instance, use these debugging tools:
+
+**Available debugging tools:**
+- `snow_get_logs` — Syslog queries (errors/warnings/info) with time filter
+- `snow_trace_execution` — Script execution tracing
+- `snow_get_script_output` — Output of previously executed scripts
+- `snow_get_flow_execution_logs` — Flow Designer execution history
+- `snow_get_inbound_http_logs` / `snow_get_outbound_http_logs` — REST API call logs
+- `snow_audit_trail_analysis` — Audit trail analysis with anomaly detection
+- `snow_inspect_mutations` — **(NEW)** Mutation inspection after tool execution
+
+**Self-debugging workflow:**
+1. Note the current timestamp (or use relative like "30s")
+2. Execute the tool being tested (e.g. `snow_manage_flow action=create`)
+3. Call `snow_inspect_mutations` with `since=<timestamp>` or `since="30s"`
+4. Review: which records were INSERT/UPDATE/DELETE, which fields changed, old→new values
+5. Compare expected vs. actual mutations and adjust tool code accordingly
+
+**When to use which debugging tool:**
+- Script errors → `snow_get_logs` with `level="error"`
+- What changed? → `snow_inspect_mutations` with time window
+- What FAILED? → `snow_inspect_mutations` with `include_syslog=true` and `include_transactions=true`
+- Flow not started? → `snow_get_flow_execution_logs`
+- REST call failed? → `snow_get_outbound_http_logs`
+- Who did what when? → `snow_audit_trail_analysis`
+
+**Important notes on `snow_inspect_mutations`:**
+- `sys_audit` only captures SUCCESSFUL record changes. Failed operations leave no audit trail.
+- For failed operations, check syslog (errors) and sys_transaction_log (HTTP 4xx/5xx responses).
+- `sys_audit` field values are limited to 255 characters — the tool warns when values appear truncated.
+- Use `snapshot_record` to fetch the current state of a record alongside the audit trail.
+- Use `tables` filter to focus on specific tables and reduce noise.
 
 ---