common-qa-mcp 0.10.0 → 0.11.0

package/dist/adapters/simplifyqa/adapter.js

@@ -1,4 +1,6 @@
 import os from 'node:os';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
 import { makeClient } from '../http.js';
 import { RemoteMcpAdapter } from '../remoteMcp/adapter.js';
 import { applyCollectionSteps, buildTestcasePayload, deriveTcType, extractApiParamNames, extractParamNames, fromSqaStep, looksSensitive, normalizeSuiteEntry, numericId, paramDefault, pickArray, str, SUITE_UPDATE_ALLOWED_KEYS, TECH_BY_STEPTYPE, toDefectSummary, toEpic, toEpicSummary, toFeature, toFeatureSummary, toFunction, toFunctionSummary, toModuleSaved, toModuleSummary, toObject, toImageUrl, toReleaseSummary, toSavedRef, toSprintSummary, toStory, toStorySummary, toSuite, toSuiteSummary, toTaskSummary, toTcSummary, toTestCase, toVersionEntries, withTotal, } from './mapper.js';
@@ -196,8 +198,6 @@ function versionDepIsEmpty(dep) {
 const NEEDS_PROJECT = 'No project selected. Call list_projects to see the available projects, then ' +
     'qa_switch_project({ projectId }) to choose one — test cases, runs and objects ' +
     'are all scoped to a project.';
-const HOP_NEEDED_WRITE = 'This SimplifyQA operation is not yet ported to direct REST — set QA_MCP_URL to the SimplifyQA ' +
-    'agent /mcp so common-mcp can hop for it, or open the SimplifyQA UI to perform it there.';
 /**
  * SimplifyQaAdapter — DIRECT-to-backend REST driver for SimplifyQA, mirroring WalnutAdapter's
  * design. Reads (list/get for projects/testcases/suites/stories/modules/releases/sprints/objects)
@@ -295,6 +295,11 @@ export class SimplifyQaAdapter {
         };
         if (opts.selectFields)
             body['selectFields'] = opts.selectFields;
+        // test-management's search treats `startIndex` as a PAGE number (skip = limit × startIndex) unless
+        // `skipStartIndex` is set, which makes it a raw row offset. Opt-in per call so other endpoints keep
+        // their existing behaviour.
+        if (opts.rawOffset)
+            body['skipStartIndex'] = 1;
         return body;
     }
     // ---------------------------------------------------------------------- Info + projects
@@ -446,6 +451,7 @@ export class SimplifyQaAdapter {
         const body = this.searchBody(fields, {
             startIndex: q.offset ?? 0,
             limit: q.limit ?? 100,
+            rawOffset: true,
             selectFields: ['id', 'code', 'name', 'priority', 'status', 'stepCount', 'tcType', 'executionType', 'obsolete'],
         });
         const raw = await this.http.postJson('/tm/testcase/search', body);
@@ -1208,6 +1214,146 @@ export class SimplifyQaAdapter {
         }
         await this.http.putJson(`/pm/module/bulkupdate/${id}`, { parentId: Number.parseInt(targetId, 10), isRoot: false });
     }
+    /** PDF reports for one execution — the same `/reports/pdfV2/*` endpoints the SimplifyQA UI downloads
+     *  from, so content and format match the UI. The path values (`type`/`executionType`/`executionStyle`)
+     *  come from the execution doc, exactly as the UI takes them from its `displayDataExecution`.
+     *  Protected-parameter masking is done by the report service itself — nothing is re-rendered here. */
+    async downloadReports(input) {
+        const projectId = this.requireProjectId();
+        const execNum = Number.parseInt(numericId(input.runId), 10);
+        if (!Number.isFinite(execNum))
+            throw new Error(`"${input.runId}" is not a valid execution id.`);
+        if (!this.http.getBinary)
+            throw new Error('This connection cannot download binary reports.');
+        const execDoc = await this.fetchExecDoc(execNum, projectId);
+        if (!execDoc)
+            throw new Error(`Execution ${input.runId} was not found in this project.`);
+        const state = mapRunState(str(execDoc, 'status') ?? '');
+        if (state === 'queued' || state === 'running') {
+            throw new Error(`Execution ${input.runId} is still ${state} — reports can only be generated once it has completed.`);
+        }
+        const isSuite = String(execDoc.type ?? '').toUpperCase() === 'SUITE';
+        const type = str(execDoc, 'type') ?? '';
+        const executionType = str(execDoc, 'executionType') ?? '';
+        const executionStyle = str(execDoc, 'executionStyle') ?? '';
+        const code = str(execDoc, 'executionTypeCode') ?? (isSuite ? 'SUITE' : 'TC');
+        const tz = encodeURIComponent(Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC');
+        const enc = encodeURIComponent;
+        const safe = (v) => v.replace(/[^\w.\-()\s]+/g, '_').trim() || 'report';
+        await mkdir(input.outDir, { recursive: true });
+        const files = [];
+        const notes = [];
+        const fetchPdf = async (path, what) => {
+            let res;
+            try {
+                res = await this.http.getBinary(path);
+            }
+            catch (e) {
+                throw new Error(`${what}: report generation failed — ${e instanceof Error ? e.message : String(e)}`);
+            }
+            const head = Buffer.from(res.data.subarray(0, 5)).toString('latin1');
+            if (!head.startsWith('%PDF')) {
+                throw new Error(`${what}: the report service did not return a PDF (${res.contentType || 'unknown type'}): ${Buffer.from(res.data.subarray(0, 200)).toString('utf8')}`);
+            }
+            return res.data;
+        };
+        const save = async (kind, label, fileName, data) => {
+            const path = join(input.outDir, safe(fileName));
+            await writeFile(path, data);
+            files.push({ kind, label, path, bytes: data.byteLength });
+        };
+        const needTcValues = () => {
+            if (!type || !executionType || !executionStyle) {
+                throw new Error(`Execution ${input.runId} is missing type/executionType/executionStyle (got "${type}"/"${executionType}"/"${executionStyle}") — cannot build the report request.`);
+            }
+        };
+        const tcUrl = (kind, runUuid) => `/reports/pdfV2/tc-${kind === 'detailed' ? 'detail' : 'summary'}/${projectId}/${execNum}/${enc(type)}/${enc(executionType)}/${enc(executionStyle)}/${enc(runUuid)}?tz=${tz}`;
+        const pickRun = (runs) => runs.find((r) => String(r?.status ?? '').toUpperCase() === 'FAILED') ?? runs[0];
+        const kindWord = (k) => (k === 'detailed' ? 'Detailed' : 'Summary');
+        if (!isSuite) {
+            if (input.kinds.includes('suite'))
+                throw new Error('The suite report is only available for a suite execution; this is a test case execution.');
+            const runs = await this.http.getJson(`/exec/report/${execNum}/${projectId}`);
+            if (!Array.isArray(runs) || runs.length === 0)
+                throw new Error(`Execution ${input.runId} has no run results to report on.`);
+            const chosen = pickRun(runs);
+            const runUuid = str(chosen, 'id', '_id') ?? '';
+            if (!runUuid)
+                throw new Error(`Execution ${input.runId}: could not find the run id for its results.`);
+            if (runs.length > 1)
+                notes.push(`Execution ${execNum} has ${runs.length} runs; used ${String(chosen?.status ?? '').toUpperCase() === 'FAILED' ? 'the first FAILED one' : 'the first one'} (${runUuid}).`);
+            needTcValues();
+            for (const kind of input.kinds) {
+                const data = await fetchPdf(tcUrl(kind, runUuid), `${kind} report`);
+                await save(kind, `${kindWord(kind)} report for ${code}`, `${code}_EX-${execNum}(${kindWord(kind)}).pdf`, data);
+            }
+            return { scope: 'testcase', runLabel: `EX-${execNum}`, files, notes };
+        }
+        // SUITE
+        const suiteNum = Number(execDoc.executionTypeId ?? 0);
+        for (const kind of input.kinds) {
+            if (kind === 'suite') {
+                const data = await fetchPdf(`/reports/pdfV2/su/${enc(type)}/${projectId}/${execNum}?tz=${tz}`, 'suite overall report');
+                await save('suite', `Suite overall report for ${code}`, `${code}_EX-${execNum}.pdf`, data);
+                continue;
+            }
+            needTcValues();
+            const items = Array.isArray(execDoc.executionItems) ? execDoc.executionItems : [];
+            if (!items.length)
+                throw new Error(`Suite execution ${input.runId} has no test cases to report on.`);
+            for (const it of items) {
+                const name = str(it, 'name') ?? `TC_${str(it, 'testcaseId') ?? '?'}`;
+                const raw = await this.http.postJson('/reports/execution/getExecutionRuns', {
+                    type: 'SU', projectId, parentId: suiteNum, executionId: execNum,
+                    tcId: Number.parseInt(numericId(str(it, 'testcaseId') ?? ''), 10),
+                    ...(str(it, 'versionId') ? { tcVersionId: str(it, 'versionId') } : {}),
+                    ...(str(it, 'stepId') ? { stepId: str(it, 'stepId') } : {}),
+                });
+                const runs = Array.isArray(raw?.data) ? raw.data : [];
+                const runUuid = runs.length ? (str(pickRun(runs), 'id', '_id') ?? '') : '';
+                if (!runUuid) {
+                    notes.push(`${name}: no run results (not executed) — skipped.`);
+                    continue;
+                }
+                const data = await fetchPdf(tcUrl(kind, runUuid), `${kind} report for ${name}`);
+                await save(kind, `${kindWord(kind)} report for ${name}`, `${name}_EX-${execNum}(${kindWord(kind)}).pdf`, data);
+            }
+        }
+        return { scope: 'suite', runLabel: `EX-${execNum}`, files, notes };
+    }
+    /** PATCH /pm/{epic|feature|userstory|defect|task} with `{ids, projectId, isDelete}`. Epic / feature /
+     *  story / defect are two-phase (`isDelete:false` returns the per-id dependency rows, and `isDelete:true`
+     *  silently skips ids that still have dependents, returning those rows again). Task has no dry-run and
+     *  no dependency check. `deleted` is therefore decided by the response shape: dependency rows come
+     *  back as an ARRAY, a real delete does not. */
+    async deleteBacklogItem(input) {
+        const path = { epic: '/pm/epic', feature: '/pm/feature', story: '/pm/userstory', defect: '/pm/defect', task: '/pm/task' }[input.kind];
+        const id = Number.parseInt(numericId(input.id), 10);
+        if (!Number.isFinite(id))
+            throw new Error(`deleteBacklogItem: "${input.id}" is not a numeric id.`);
+        const projectId = this.requireProjectId();
+        const confirm = input.confirm === true;
+        if (input.kind === 'task') {
+            if (!confirm)
+                return { dryRun: true, deleted: false, dependencies: [] };
+            await this.http.patchJson(path, { ids: [id], projectId });
+            return { dryRun: false, deleted: true, dependencies: [] };
+        }
+        const raw = await this.http.patchJson(path, { ids: [id], projectId, isDelete: confirm });
+        const data = raw?.data ?? raw;
+        const rows = Array.isArray(data) ? data : [];
+        const dependencies = rows
+            .filter((r) => r && typeof r === 'object')
+            .map((r) => {
+            const counts = {};
+            for (const [k, v] of Object.entries(r))
+                if (k.endsWith('Arr') && Array.isArray(v) && v.length)
+                    counts[k] = v;
+            return { id: Number(r.id), counts };
+        });
+        const blocked = dependencies.some((d) => Object.keys(d.counts).length > 0);
+        return { dryRun: !confirm, deleted: confirm && !Array.isArray(data) && !blocked, dependencies };
+    }
     /** PATCH /pm/module — two-phase per module.controller.js:94. `confirm:false` returns the per-id
      *  dependency footprint (test cases, functions, params, objects, defects, user stories). `confirm:true`
      *  triggers the actual delete: server drops only ids with EMPTY dependencies; ids with references are
@@ -1443,12 +1589,6 @@ export class SimplifyQaAdapter {
             this.agentHop = new RemoteMcpAdapter(this.cfg);
         return this.agentHop;
     }
-    requireHop(op) {
-        const h = this.hop();
-        if (!h)
-            throw new Error(`${op}: ${HOP_NEEDED_WRITE}`);
-        return h;
-    }
     /** Recording tool schemas from the SQA agent — mirrored so the recording passthrough can register
      *  them. No agent configured → `[]`, so no recording tools get registered. */
     async listAgentTools() {
@@ -1502,10 +1642,41 @@ export class SimplifyQaAdapter {
             paramIdByName,
             ...(stepResolutions ? { stepResolutions } : {}),
         });
+        await this.appendRemovedSteps(id, tc, payload);
         // `!` — putMultipart is optional on QaHttp (walnut's wrapper opts out); makeClient always provides it.
         const raw = await this.http.putMultipart('/tm/testcase', 'testcaseObj', payload);
         return toSavedRef(raw, false);
     }
+    /** The backend deletes a step only when it receives it with `deleted:true`; a step that is simply
+     *  absent from the payload is left untouched. So a step removed from the draft (remove_step) has to be
+     *  sent back explicitly as deleted, otherwise the save "succeeds" and the step is still there.
+     *  Only applies when the draft was hydrated from this test case (its steps carry `sourceId`), so a
+     *  hand-built draft with no source ids can never wipe the stored steps. Best-effort: a failed lookup
+     *  leaves the payload as it was. */
+    async appendRemovedSteps(id, tc, payload) {
+        const kept = new Set((tc.steps ?? []).map((s) => s.sourceId).filter((v) => !!v));
+        if (kept.size === 0)
+            return;
+        try {
+            const rawTc = await this.fetchRawTestcase(id);
+            const current = await this.fetchStepsCollection(id, rawTc, tc.currentVersionId);
+            const tcNum = Number.parseInt(numericId(id), 10);
+            for (const r of current) {
+                const sid = str(r, 'id', '_id');
+                if (!sid || kept.has(sid) || r?.deleted === true)
+                    continue;
+                const step = { ...pick(r, STEP_ALLOWED_KEYS), id: sid, deleted: true, parentId: tcNum };
+                const vid = str(r, 'versionId');
+                if (vid)
+                    step['versionId'] = vid;
+                const bucket = String(r?.executionType ?? '').toUpperCase() === 'MANUAL' ? 'manualSteps' : 'automationSteps';
+                payload.steps[bucket].push(step);
+            }
+        }
+        catch {
+            // lookup failed — save proceeds without delete markers
+        }
+    }
     /** Snapshot the CURRENT server state of a testcase under a NEW version name — same TC id,
      *  new `tcfn_version` row with cloned steps. Backed by `PUT /tm/testcase` with
      *  `operation:"SAVENEWVERSION"` (see tcfn.service.js:115/242/355 for the branches). The steps
@@ -1538,7 +1709,8 @@ export class SimplifyQaAdapter {
                 sourceVersionId = str(rawTc.versions[0], 'id', '_id');
             }
         }
-        const rawSteps = await this.fetchStepsCollection(id, rawTc);
+        // Steps must come from the SELECTED source version, not whichever version the TC has open.
+        const rawSteps = await this.fetchStepsCollection(id, rawTc, sourceVersionId);
         const automationSteps = [];
         const manualSteps = [];
         for (const s of rawSteps) {
@@ -2029,7 +2201,8 @@ export class SimplifyQaAdapter {
                 : undefined;
             return match ? str(match, 'name') : str(rawTc?.versionsDetails, 'name');
         })() ?? 'v1.0';
-        const rawSteps = await this.fetchStepsCollection(id, rawTc);
+        // Steps must come from the SELECTED source version, not whichever version the TC has open.
+        const rawSteps = await this.fetchStepsCollection(id, rawTc, sourceVersionId);
         const automationSteps = [];
         const manualSteps = [];
         for (const s of rawSteps) {
@@ -2412,10 +2585,13 @@ export class SimplifyQaAdapter {
                 paramIdByName.set(name, id);
             }
             if (s.recordedParam) {
+                const runtimeNames = new Set(s.runtimeParameters ?? []);
                 for (const [name, value] of Object.entries(s.recordedParam)) {
                     if (paramIdByName.has(name))
                         continue;
-                    const id = await this.getOrCreateParameter(projectId, moduleId, name, String(value ?? ''));
+                    // A store slot ("Runtime Parameter") must be a Runtime param so the agent hands the plugin a
+                    // writable argument; everything else stays Local.
+                    const id = await this.getOrCreateParameter(projectId, moduleId, name, String(value ?? ''), runtimeNames.has(name) ? 'Runtime' : 'Local');
                     paramIdByName.set(name, id);
                 }
             }
@@ -2456,7 +2632,16 @@ export class SimplifyQaAdapter {
                 limit: 100000,
                 selectFields: ['id', 'name', 'technology', 'objectTemplate', 'objectRequired'],
             };
-            const raw = await this.http.postJson('/tm/action/search', body);
+            // Also ask for the plugin's `@Sync` uniqueId ("db-2"): action NAMES collide (executeQuery = db-2 AND
+            // db-3), so a save must resolve by uniqueId when the backend exposes it. Not every backend build
+            // accepts the column, so fall back to the plain field set — resolution then degrades to by-name.
+            let raw;
+            try {
+                raw = await this.http.postJson('/tm/action/search', { ...body, selectFields: [...body.selectFields, 'uniqueId'] });
+            }
+            catch {
+                raw = await this.http.postJson('/tm/action/search', body);
+            }
             const rows = pickArray(raw, 'data', 'content', 'actions');
             // Capture diagnostic snapshot so downstream errors can surface WHY the fetch returned 0 rows.
             try {
@@ -2497,6 +2682,10 @@ export class SimplifyQaAdapter {
                 }
                 // Id-keyed entry so numeric-actionType round-trip lookups are O(1) instead of a scan.
                 map.set(`id::${id}`, entry);
+                // Plugin-uniqueId-keyed entry: the only collision-free way to pick db-2 vs db-3 etc.
+                const uniq = str(row, 'uniqueId', 'actionUniqueId');
+                if (uniq)
+                    map.set(`uniq::${uniq}`, entry);
             }
             return map;
         })().catch((e) => { this.actionCatalogCache = null; throw e; });
@@ -2518,7 +2707,7 @@ export class SimplifyQaAdapter {
                     if (!sameLocators && incomingLocators.length) {
                         await this.updateObject(existing.id, { locators: incomingLocators });
                     }
-                    return Number.parseInt(existing.id, 10);
+                    return { id: Number.parseInt(existing.id, 10) };
                 }
             }
             catch {
@@ -2553,7 +2742,20 @@ export class SimplifyQaAdapter {
         const id = str(flat, 'id', '_id', 'objectId');
         if (!id)
             throw new Error(`createObjectSeq returned no id for object "${name}": ${JSON.stringify(raw)}`);
-        return Number.parseInt(id, 10);
+        // The backend dedups a clashing name by suffixing it ("Sign In button" → "Sign In button_1") and
+        // returns the stored `disname`. Surface it so the step can show the name actually in use.
+        const storedName = (str(flat, 'disname') ?? '').trim();
+        return { id: Number.parseInt(id, 10), ...(storedName && storedName !== name ? { storedName } : {}) };
+    }
+    /** Rewrite `from` → `to` in a step's description + objectRef.name after the backend renamed its
+     *  object. Skips matches already followed by a `_N` suffix so a re-run never double-suffixes. */
+    applyObjectRename(step, from, to) {
+        if (step.objectRef)
+            step.objectRef.name = to;
+        if (!step.description || !from)
+            return;
+        const escaped = from.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        step.description = step.description.replace(new RegExp(`${escaped}(?!_\\d)`, 'i'), to);
     }
     /** For every automation step, resolve `actionId` (from action name + technology) and
      *  `objectId` (via createObjectSeq get-or-create) so the mapper can emit a valid step. Runs
@@ -2590,9 +2792,14 @@ export class SimplifyQaAdapter {
             // `<lowercase name>` for model-authored by-name lookups. Tech is not in the key because
             // action rows have no top-level `technology` field (SQA UI resolves via objectTemplate lookup).
             const isNumericId = /^\d+$/.test(name);
-            let meta = isNumericId
-                ? catalog.get(`id::${Number.parseInt(name, 10)}`)
-                : catalog.get(name.toLowerCase());
+            // A recorder step carries the plugin's uniqueId; prefer it — names are not unique ("executeQuery"
+            // is db-2 AND db-3) so by-name can silently save the wrong overload.
+            // Scoped to database steps: other technologies keep the existing by-name/by-id resolution untouched.
+            let meta = s.stepType === 'database' && s.actionUniqueId ? catalog.get(`uniq::${s.actionUniqueId}`) : undefined;
+            if (!meta)
+                meta = isNumericId
+                    ? catalog.get(`id::${Number.parseInt(name, 10)}`)
+                    : catalog.get(name.toLowerCase());
             // Fallback: if the by-id scan misses (action created in a different project and thus not in
             // the UI's projectId-filtered catalog), fetch it directly via GET /tm/action/:id. Only tries
             // for numeric-id lookups — model-authored name lookups have no id to fetch.
@@ -2660,7 +2867,10 @@ export class SimplifyQaAdapter {
                     if (meta.objectTemplate == null) {
                         throw new Error(`Automation step ${i + 1} ("${name}"): action ${meta.id} has no objectTemplate — cannot create/reuse an object without knowing which template it belongs to.`);
                     }
-                    objectId = await this.resolveObjectId(s.objectRef, projectId, moduleId, tech, meta.objectTemplate);
+                    const resolved = await this.resolveObjectId(s.objectRef, projectId, moduleId, tech, meta.objectTemplate);
+                    objectId = resolved.id;
+                    if (resolved.storedName)
+                        this.applyObjectRename(s, s.objectRef.name.trim(), resolved.storedName);
                 }
                 else {
                     throw new Error(`Automation step ${i + 1} ("${name}"): action requires an object but Step.objectRef is missing. Provide objectRef:{id} to reuse a known one, objectRef:{name} to look one up by name in the project, or objectRef:{name, locators:[{name, value}]} to create a new one.`);
@@ -2685,7 +2895,10 @@ export class SimplifyQaAdapter {
         const rows = pickArray(raw, 'data', 'content');
         for (const row of rows) {
             const rowName = str(row, 'name');
-            if (rowName === name) {
+            // Case-insensitive: the search above sets ignorecase, and the backend's duplicate-name
+            // collation is case-insensitive too — an exact-case compare here misses an existing "host"
+            // (vs "Host") and the next POST trips "Duplicate Name Error".
+            if (rowName != null && rowName.toLowerCase() === name.toLowerCase()) {
                 const id = str(row, 'id', '_id', 'parameterId');
                 if (id)
                     return Number.parseInt(id, 10);
@@ -2715,7 +2928,7 @@ export class SimplifyQaAdapter {
         }
         return null;
     }
-    async getOrCreateParameter(projectId, moduleId, name, defaultValue) {
+    async getOrCreateParameter(projectId, moduleId, name, defaultValue, accessType = 'Local') {
         const existing = await this.findParameterId(projectId, name);
         if (existing != null)
             return existing;
@@ -2727,7 +2940,7 @@ export class SimplifyQaAdapter {
             defaultValue,
             // Match the SQA UI's Add-Parameter defaults so API-created params render identically. Without
             // these the UI shows "Parameter Type*" empty and refuses to save edits.
-            type: 'Local',
+            type: accessType,
             parameterType: 'Alphanumeric',
             description: '',
             unique: false,
@@ -3700,11 +3913,14 @@ export class SimplifyQaAdapter {
         // LOCAL fast-fail: the desktop agent is what actually executes the TC (it polls the Redis queue
         // the backend RPUSHes to). If :4040 isn't up, no roster / customer-search / dispatch will help —
         // fail here with a clear message instead of enqueuing a job nothing will drain.
-        if (mode === 'LOCAL' && !(await this.probeLocalAgent())) {
-            throw new Error(`startRun (LOCAL): SimplifyQA desktop agent is not reachable at ` +
-                `${this.cfg.url ?? '(no agent URL configured — set QA_MCP_URL)'}. Start the desktop ` +
-                `agent, then try again. Use mode:'cloud' to run on a cloud runner instead — it does not ` +
-                `need the desktop agent.`);
+        if (mode === 'LOCAL') {
+            const probe = await this.probeLocalAgentDetailed();
+            if (!probe.up) {
+                throw new Error(`startRun (LOCAL): could not reach the SimplifyQA desktop agent at ${probe.url ?? '(no URL)'} ` +
+                    `just now (${probe.reason ?? 'unknown'}) — checked live at dispatch, not from earlier in this chat. ` +
+                    `If the agent shows Online in the SimplifyQA UI, retry once; otherwise start the desktop agent. ` +
+                    `Use mode:'cloud' to run on a cloud runner instead — it does not need the desktop agent.`);
+            }
         }
         const rawTc = await this.fetchRawTestcase(tcId);
         if (!rawTc || Object.keys(rawTc).length === 0) {
@@ -3886,11 +4102,14 @@ export class SimplifyQaAdapter {
         // Effective mode: caller pick wins (matches our tool's cascade UX); fall back to the suite doc's
         // stored `executionType`, which the UI reads unconditionally (execution-popup-modal.ts:668).
         const mode = (opts.mode ?? String(rawSuite.executionType ?? 'LOCAL')).toUpperCase();
-        if (mode === 'LOCAL' && !(await this.probeLocalAgent())) {
-            throw new Error(`startRun (LOCAL): SimplifyQA desktop agent is not reachable at ` +
-                `${this.cfg.url ?? '(no agent URL configured — set QA_MCP_URL)'}. Start the desktop ` +
-                `agent, then try again. Use mode:'cloud' to run on a cloud runner instead — it does not ` +
-                `need the desktop agent.`);
+        if (mode === 'LOCAL') {
+            const probe = await this.probeLocalAgentDetailed();
+            if (!probe.up) {
+                throw new Error(`startRun (LOCAL): could not reach the SimplifyQA desktop agent at ${probe.url ?? '(no URL)'} ` +
+                    `just now (${probe.reason ?? 'unknown'}) — checked live at dispatch, not from earlier in this chat. ` +
+                    `If the agent shows Online in the SimplifyQA UI, retry once; otherwise start the desktop agent. ` +
+                    `Use mode:'cloud' to run on a cloud runner instead — it does not need the desktop agent.`);
+            }
         }
         const projectName = await this.lookupProjectName(projectId);
         if (!projectName) {
@@ -4057,20 +4276,31 @@ export class SimplifyQaAdapter {
      *  a naked GET) proves the process is up; connect/DNS/timeout errors mean it is down. Replaces
      *  the customer-wide `machineRegistration` round trip when all we needed was "is LOCAL possible?". */
     async probeLocalAgent() {
-        if (!this.cfg.url)
-            return false;
-        const ac = new AbortController();
-        const timer = setTimeout(() => ac.abort(), 1000);
-        try {
-            await fetch(this.cfg.url, { method: 'GET', signal: ac.signal });
-            return true;
-        }
-        catch {
-            return false;
-        }
-        finally {
-            clearTimeout(timer);
+        return (await this.probeLocalAgentDetailed()).up;
+    }
+    /** Live probe, never cached — every dispatch re-checks. A single 1s attempt misreported a busy-but-up
+     *  agent as offline (the "agent offline mid-chain" report), so: 3s per attempt, one retry, and the
+     *  failure reason is returned so callers can say WHY instead of a bare "not reachable". */
+    async probeLocalAgentDetailed() {
+        const url = this.cfg.url;
+        if (!url)
+            return { up: false, reason: 'no agent URL configured (set QA_MCP_URL)' };
+        let reason = '';
+        for (let attempt = 0; attempt < 2; attempt++) {
+            const ac = new AbortController();
+            const timer = setTimeout(() => ac.abort(), 3000);
+            try {
+                await fetch(url, { method: 'GET', signal: ac.signal });
+                return { up: true, url };
+            }
+            catch (e) {
+                reason = ac.signal.aborted ? 'no response within 3s' : (e instanceof Error ? (e.cause?.message ?? e.message) : String(e));
+            }
+            finally {
+                clearTimeout(timer);
+            }
         }
+        return { up: false, url, reason };
     }
     async listCloudRunners() {
         const projectId = this.requireProjectId();
@@ -4454,11 +4684,104 @@ export class SimplifyQaAdapter {
         return h?.listDatasets ? h.listDatasets(tcId) : [];
     }
     // --- Journal (recording seed lives on the agent's FS) ------------------
+    // The agent keeps the recording journal. When it is NOT reachable (not running / no URL) the steps are
+    // still readable and editable straight from the backend, the same way the SQA UI does it — so these two
+    // fall back to REST instead of failing. When the agent IS up its behaviour is unchanged.
+    agentUnreachable(e) {
+        const m = e instanceof Error ? e.message : String(e);
+        return /Could not reach the product MCP|fetch failed|ECONNREFUSED/i.test(m);
+    }
     async readJournal(tcId) {
-        return this.requireHop('read_journal').readJournal(tcId);
+        const h = this.hop();
+        if (h) {
+            try {
+                return await h.readJournal(tcId);
+            }
+            catch (e) {
+                if (!this.agentUnreachable(e))
+                    throw e;
+            }
+        }
+        return this.stepsView(tcId);
     }
     async editJournal(tcId, ops) {
-        return this.requireHop('edit_journal').editJournal(tcId, ops);
+        const h = this.hop();
+        if (h) {
+            try {
+                return await h.editJournal(tcId, ops);
+            }
+            catch (e) {
+                if (!this.agentUnreachable(e))
+                    throw e;
+            }
+        }
+        return this.editStepsDirect(tcId, ops);
+    }
+    async stepsView(tcId) {
+        const tc = await this.getTestCase(tcId);
+        return { tcId, source: 'steps', steps: tc.steps ?? [] };
+    }
+    /** Agent-free step edit: read the test case, apply remove / update / move by step number, renumber, and
+     *  save through updateTestCase (which sends removed steps back with `deleted:true`, as the UI does). */
+    async editStepsDirect(tcId, ops) {
+        const tc = await this.getTestCase(tcId);
+        let steps = [...(tc.steps ?? [])];
+        for (const op of ops) {
+            if (op.op === 'remove_step') {
+                if (!steps.some((x) => x.n === op.n))
+                    throw new Error(`remove_step: no step ${op.n} on ${tcId} (it has ${steps.length}).`);
+                steps = steps.filter((x) => x.n !== op.n);
+            }
+            else if (op.op === 'update_step') {
+                const i = steps.findIndex((x) => x.n === op.n);
+                if (i < 0)
+                    throw new Error(`update_step: no step ${op.n} on ${tcId} (it has ${steps.length}).`);
+                const cur = steps[i];
+                const patch = op.patch;
+                steps[i] = {
+                    ...cur, ...patch,
+                    ...(patch.flags ? { flags: { ...cur.flags, ...patch.flags } } : {}),
+                    ...(patch.objectRef ? { objectRef: { ...cur.objectRef, ...patch.objectRef } } : {}),
+                };
+            }
+            else if (op.op === 'move_step') {
+                const i = steps.findIndex((x) => x.n === op.n);
+                if (i < 0)
+                    throw new Error(`move_step: no step ${op.n} on ${tcId} (it has ${steps.length}).`);
+                const [moved] = steps.splice(i, 1);
+                steps.splice(Math.max(0, Math.min(steps.length, op.to - 1)), 0, moved);
+            }
+            else if (op.op === 'insert_nested') {
+                // Same shape the UI inserts (steps.component.ts addStep 'FUNCTION'): a FUNCTION step directly
+                // followed by its FUNCTION_END, with the function's newest version pinned (function-step-card
+                // onSelectFunction). The automation payload builder turns the neutral pair into wire steps.
+                if (tc.category !== 'automated') {
+                    throw new Error(`insert_nested: ${tcId} is a manual test case — nested function calls can only be added to automated test cases.`);
+                }
+                const fn = await this.getFunction(op.tcId);
+                const fnVersionId = fn.versions?.[0]?.id;
+                if (!fnVersionId)
+                    throw new Error(`insert_nested: function ${op.tcId} has no version to pin.`);
+                const idx = op.at != null ? Math.max(0, Math.min(steps.length, op.at - 1)) : steps.length;
+                if (steps[idx - 1]?.stepType === 'function') {
+                    throw new Error(`insert_nested: position ${idx + 1} is inside the function call at step ${idx}.`);
+                }
+                const fnStep = {
+                    n: 0, stepType: 'function', actionType: 'function',
+                    description: op.name ?? fn.description ?? '',
+                    functionCall: { testCaseId: numericId(op.tcId), versionId: fnVersionId },
+                };
+                const endStep = { n: 0, stepType: 'function_end', actionType: 'function_end', description: '' };
+                steps.splice(idx, 0, fnStep, endStep);
+            }
+            else {
+                throw new Error(`The SimplifyQA desktop agent is not reachable, and '${op.op}' needs it. Without the agent only ` +
+                    'update_step, remove_step, move_step and insert_nested can be applied. Start the agent, or use those ops.');
+            }
+            steps = steps.map((x, k) => ({ ...x, n: k + 1 }));
+        }
+        await this.updateTestCase(tcId, { ...tc, steps });
+        return this.stepsView(tcId);
     }
 }
 //# sourceMappingURL=adapter.js.map