common-qa-mcp 0.2.0 → 0.3.0

package/dist/adapters/simplifyqa/adapter.js

@@ -0,0 +1,1150 @@
+import os from 'node:os';
+import { makeClient } from '../http.js';
+import { RemoteMcpAdapter } from '../remoteMcp/adapter.js';
+import { applyCollectionSteps, buildTestcasePayload, extractParamNames, looksSensitive, normalizeSuiteEntry, numericId, paramDefault, pickArray, str, SUITE_UPDATE_ALLOWED_KEYS, toModuleSummary, toObject, toReleaseSummary, toSavedRef, toSprintSummary, toStory, toStorySummary, toSuite, toSuiteSummary, toTcSummary, toTestCase, } from './mapper.js';
+const PROJECT_URL_SEGMENT = {
+    testcase: 'testcase',
+    suite: 'suite',
+    run: 'reports/execution',
+};
+/** SQA run-row status → neutral RunStatus.state. */
+function mapRunState(s) {
+    switch (s.toUpperCase()) {
+        case 'PASSED': return 'passed';
+        case 'FAILED': return 'failed';
+        case 'STOPPED': return 'stopped';
+        case 'RUNNING': return 'running';
+        case 'QUEUED': return 'queued';
+        default: return 'queued';
+    }
+}
+/** Formula names round-trip with parens on ("FIRST_NAME()") from the backend and sometimes with a full
+ *  signature ("FIRST_NAME(country,sex)") from a caller. Reduce both to the bare identifier. */
+function bareFormulaName(s) {
+    return s.replace(/\s*\(.*\)\s*$/, '').trim();
+}
+/** Query keys /tm/customFormula expects per formula, positionally — they are NOT the formula's declared
+ *  keyNames. Mirrors the SQA UI (wfTestdataView.ts). Anything absent takes at most one arg as `value`.
+ *  ponytail: table, not per-formula handlers — extend a row when a new multi-arg formula shows up. */
+const FORMULA_ARG_KEYS = {
+    FIRST_NAME: ['country', 'sex', 'min_len', 'max_len'],
+    LAST_NAME: ['country', 'sex', 'min_len', 'max_len'],
+    FULL_NAME: ['country', 'sex', 'min_len', 'max_len'],
+    MIDDLE_NAME: ['country', 'sex', 'min_len', 'max_len'],
+    PREFIX: ['sex'],
+    DATE_OF_BIRTH: ['pattern', 'min_age', 'max_age'],
+};
+/** Normalise a formula document from `/tm/syncFormulas/fetch` into the neutral Formula shape. Returns
+ *  null when the doc is missing a name — a nameless formula cannot be called. `scope` is inferred:
+ *  DEFAULT → 'default'; CUSTOM with a matching projectId → 'project'; CUSTOM otherwise → 'customer'. */
+function normalizeFormula(doc, projectId) {
+    if (!doc || typeof doc !== 'object')
+        return null;
+    const name = str(doc, 'name');
+    if (!name)
+        return null;
+    const type = str(doc, 'type') === 'CUSTOM' ? 'CUSTOM' : 'DEFAULT';
+    const docPid = Number(doc.projectId ?? 0);
+    const scope = type === 'DEFAULT' ? 'default' : docPid && docPid === projectId ? 'project' : 'customer';
+    const desc = (doc.description && typeof doc.description === 'object') ? doc.description : {};
+    const params = Array.isArray(desc.parameters)
+        ? desc.parameters
+            .map((p) => (p && typeof p === 'object' && typeof p.keyName === 'string')
+            ? { keyName: p.keyName, description: str(p, 'value', 'description') ?? undefined, dataType: str(p, 'dataType') ?? undefined }
+            : null)
+            .filter((p) => p !== null)
+        : [];
+    return {
+        name,
+        uniqueId: str(doc, 'uniqueId') ?? name,
+        type,
+        scope,
+        signature: str(desc, 'name') ?? `${name}()`,
+        details: str(desc, 'details') ?? undefined,
+        example: str(desc, 'example') ?? undefined,
+        parameters: params,
+    };
+}
+/** SQA per-step status → neutral step status. */
+function mapStepStatus(s) {
+    switch (s.toUpperCase()) {
+        case 'PASSED': return 'pass';
+        case 'FAILED': return 'fail';
+        case 'SKIPPED': return 'skip';
+        case 'STOPPED': return 'stop';
+        default: return s.toLowerCase();
+    }
+}
+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)
+ * hit the SQA TM backend REST directly via a `QaHttp` bound to `cfg.baseUrl`. Anything not yet
+ * ported (writes, testdata, run dispatch, marketplace, and the recording surface) delegates to
+ * the LOCAL AGENT's `/mcp` (`cfg.url`) via a lazily-built RemoteMcpAdapter — same "graceful hop"
+ * pattern walnut uses for recording. When the hop is not configured, unported ops surface a clear
+ * error instead of failing silently.
+ *
+ * This class deliberately does not `implements ProviderAdapter` (walnut trick): the factory casts
+ * it, and tools that call ported methods get direct REST; tools that call unported methods get
+ * the hop (or a clear error). Each porting step replaces one more delegation with a direct call.
+ */
+export class SimplifyQaAdapter {
+    constructor(cfg, transport) {
+        this.cfg = cfg;
+        this.agentHop = null;
+        // Formula list rarely changes during a session; cache the fetch response so the model can call
+        // tc_list_formulas without paying a round trip each time. Instance-scoped: switchProject rebuilds
+        // the adapter (see connection.ts), which drops this cache with it — no manual invalidation needed.
+        // We store the in-flight PROMISE, not the resolved array: several concurrent evaluateFormula calls
+        // (from the Promise.all in saveGeneratedIterations) all await the same fetch instead of each firing
+        // their own /tm/syncFormulas/fetch before the cache is populated.
+        this.formulaCache = null;
+        if (!cfg.baseUrl) {
+            throw new Error('SimplifyQaAdapter requires a baseUrl — set QA_BASE_URL or use a JWT with a `url` claim.');
+        }
+        this.http = makeClient({
+            baseUrl: cfg.baseUrl,
+            headers: () => this.headers(),
+            ...transport,
+        });
+    }
+    // Auth headers mirror the Java RequestContext: bearer + x-project-id. `x-project-id` is only
+    // spread in when a project is selected — a session can be connected before one is chosen.
+    headers() {
+        return {
+            Authorization: `Bearer ${this.cfg.token}`,
+            ...(this.cfg.projectId ? { 'x-project-id': this.cfg.projectId } : {}),
+            'Content-Type': 'application/json',
+        };
+    }
+    requireProjectId() {
+        if (!this.cfg.projectId)
+            throw new Error(NEEDS_PROJECT);
+        const n = Number.parseInt(String(this.cfg.projectId).trim(), 10);
+        if (!Number.isFinite(n))
+            throw new Error(`Invalid projectId ${this.cfg.projectId} — expected a numeric id.`);
+        return n;
+    }
+    // Standard SQA `searchFields` payload builder — the SAME shape every /search endpoint expects.
+    // Every list op below uses this instead of hand-writing the same 6-line boilerplate.
+    searchBody(fields, opts = {}) {
+        const body = {
+            searchFields: fields.map((f) => ({
+                column: f.column,
+                value: f.value,
+                ...(f.regEx ? { regEx: true } : {}),
+            })),
+            startIndex: opts.startIndex ?? 0,
+            limit: opts.limit ?? 1000,
+        };
+        if (opts.selectFields)
+            body['selectFields'] = opts.selectFields;
+        return body;
+    }
+    // ---------------------------------------------------------------------- Info + projects
+    /** Validates baseUrl + token + (optional) project by running the same list_projects search the
+     *  Java `infoResult` uses to resolve the project name — no separate /info endpoint on SQA. */
+    async info() {
+        const projects = await this.listProjects();
+        const projectId = this.cfg.projectId ?? '';
+        const found = projects.find((p) => p.id === projectId);
+        return {
+            provider: 'simplifyqa',
+            projectId,
+            projectName: found?.name ?? '',
+        };
+    }
+    /** `POST /pm/project/search` — projects the token can see. NOT project-scoped. */
+    async listProjects() {
+        const body = this.searchBody([{ column: 'deleted', value: false }], { selectFields: ['id', 'code', 'name'] });
+        const raw = await this.http.postJson('/pm/project/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'projects');
+        return rows.map((n) => ({
+            id: str(n, 'id', '_id', 'projectId') ?? '',
+            name: str(n, 'name', 'projectName') ?? '',
+        }));
+    }
+    // ---------------------------------------------------------------------- Test cases (read)
+    async listTestCases(q) {
+        const projectId = this.requireProjectId();
+        const fields = [
+            { column: 'deleted', value: false },
+            { column: 'projectId', value: projectId },
+        ];
+        if (q.search)
+            fields.push({ column: 'name', value: q.search, regEx: true });
+        if (q.status)
+            fields.push({ column: 'status', value: q.status });
+        const body = this.searchBody(fields, {
+            startIndex: q.offset ?? 0,
+            limit: q.limit ?? 100,
+            selectFields: ['id', 'code', 'name', 'priority', 'status', 'stepCount', 'tcType', 'executionType'],
+        });
+        const raw = await this.http.postJson('/tm/testcase/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'testCases');
+        return rows.map(toTcSummary);
+    }
+    /** Neutral test case, steps included. Accepts numeric id or business code (`TC_123`). */
+    async getTestCase(id) {
+        const raw = await this.fetchRawTestcase(id);
+        if (!raw || Object.keys(raw).length === 0) {
+            throw new Error(`test case ${id} not found`);
+        }
+        const tc = toTestCase(raw);
+        // Prefer the steps COLLECTION — that's the source of truth the SQA UI, executor, and save
+        // paths use today. Inline steps.manualSteps / steps.automationSteps on the TC doc drift
+        // against it. Fall back to inline (already on `tc` from toTestCase) if the collection
+        // fetch is empty or throws — legacy TCs that never migrated still surface something.
+        try {
+            const rows = await this.fetchStepsCollection(id, raw);
+            if (rows.length > 0)
+                return applyCollectionSteps(tc, rows);
+        }
+        catch {
+            // ignore — inline steps stay
+        }
+        return tc;
+    }
+    async fetchRawTestcase(id) {
+        const raw = await this.http.getJson(`/tm/testcase/getById/${numericId(id)}`);
+        let doc = raw?.data ?? raw;
+        if (Array.isArray(doc))
+            doc = doc.length > 0 ? doc[0] : {};
+        return doc && typeof doc === 'object' ? doc : {};
+    }
+    async fetchStepsCollection(tcId, rawTc) {
+        const projectId = this.requireProjectId();
+        const tcNum = numericId(tcId);
+        // versionId lives under a few different keys depending on the read model — Java tries all four.
+        let versionId = str(rawTc, 'versionId', 'selectedVersionId') ??
+            (rawTc?.versionsDetails && typeof rawTc.versionsDetails === 'object'
+                ? str(rawTc.versionsDetails, 'id', '_id', 'versionId')
+                : undefined);
+        if (!versionId && Array.isArray(rawTc?.versions) && rawTc.versions.length > 0) {
+            versionId = str(rawTc.versions[0], 'id', '_id');
+        }
+        if (!versionId)
+            return [];
+        const path = '/tm/testcase/steps' +
+            `?projectId=${projectId}` +
+            `&tcfnId=${tcNum}` +
+            `&versionId=${encodeURIComponent(versionId)}` +
+            '&type=TC';
+        const body = await this.http.getJson(path);
+        const rows = Array.isArray(body) ? body : Array.isArray(body?.data) ? body.data : [];
+        return rows;
+    }
+    // ---------------------------------------------------------------------- Suites (read)
+    async listSuites() {
+        const projectId = this.requireProjectId();
+        const body = this.searchBody([
+            { column: 'deleted', value: false },
+            { column: 'projectId', value: projectId },
+        ]);
+        const raw = await this.http.postJson('/tm/suites/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'suites');
+        return rows.map(toSuiteSummary);
+    }
+    async getSuite(id) {
+        const raw = await this.http.getJson(`/tm/suites/${numericId(id)}`);
+        let doc = raw?.data ?? raw;
+        if (Array.isArray(doc))
+            doc = doc.length > 0 ? doc[0] : {};
+        return toSuite(doc && typeof doc === 'object' ? doc : {});
+    }
+    // ---------------------------------------------------------------------- Stories (read)
+    async listStories(q) {
+        const projectId = this.requireProjectId();
+        const fields = [
+            { column: 'deleted', value: false },
+            { column: 'projectId', value: projectId },
+        ];
+        if (q.search)
+            fields.push({ column: 'name', value: q.search, regEx: true });
+        // SQA's userstory FK for sprint is `iterationId` — spec uses the neutral name `sprintId`.
+        if (q.sprintId)
+            fields.push({ column: 'iterationId', value: Number.parseInt(q.sprintId, 10) });
+        if (q.releaseId)
+            fields.push({ column: 'releaseId', value: Number.parseInt(q.releaseId, 10) });
+        const body = this.searchBody(fields, { limit: q.limit ?? 50 });
+        const raw = await this.http.postJson('/pm/userstory/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'userStories', 'stories');
+        return rows.map(toStorySummary);
+    }
+    async getStory(id) {
+        const resolvedId = await this.resolveStoryNumericId(id);
+        const raw = await this.http.getJson(`/pm/userstory/${resolvedId}`);
+        const doc = Array.isArray(raw)
+            ? (raw.length > 0 ? raw[0] : {})
+            : (raw?.data && typeof raw.data === 'object' ? raw.data : raw);
+        return toStory(doc && typeof doc === 'object' ? doc : {});
+    }
+    /** A US_XXX business key → the numeric userstoryId via `/pm/userstory/search`. Numeric passes
+     *  through. SQA's GET-by-id parseInts the path, so a raw key would 404. */
+    async resolveStoryNumericId(ref) {
+        if (!ref)
+            return ref;
+        if (/^\d+$/.test(ref))
+            return ref;
+        const body = this.searchBody([{ column: 'code', value: ref }], { startIndex: 0, limit: 1 });
+        const raw = await this.http.postJson('/pm/userstory/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'userStories', 'stories');
+        if (rows.length === 0)
+            throw new Error(`Story not found for business key: ${ref}`);
+        return str(rows[0], 'id', '_id', 'userstoryId') ?? ref;
+    }
+    // ---------------------------------------------------------------------- Modules, releases, sprints
+    async listModules() {
+        const projectId = this.requireProjectId();
+        const body = this.searchBody([
+            { column: 'projectId', value: projectId },
+            { column: 'deleted', value: false },
+        ], { selectFields: ['id', 'code', 'name', 'parentId'], limit: 10000 });
+        const raw = await this.http.postJson('/pm/module/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'modules');
+        return rows.map(toModuleSummary);
+    }
+    async listReleases(q) {
+        const fields = [{ column: 'deleted', value: false }];
+        if (q.scope === 'project')
+            fields.push({ column: 'projectIds', value: this.requireProjectId() });
+        const body = this.searchBody(fields);
+        const raw = await this.http.postJson('/pm/release/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'releases');
+        return rows.map(toReleaseSummary);
+    }
+    async listSprints(q) {
+        const fields = [{ column: 'deleted', value: false }];
+        if (q.releaseId)
+            fields.push({ column: 'releaseId', value: Number.parseInt(q.releaseId, 10) });
+        const body = this.searchBody(fields);
+        const raw = await this.http.postJson('/pm/sprint/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'sprints');
+        return rows.map(toSprintSummary);
+    }
+    // ---------------------------------------------------------------------- Objects (read)
+    async getObject(id) {
+        const raw = await this.http.getJson(`/tm/object/${numericId(id)}`);
+        let doc = raw?.data ?? raw;
+        if (Array.isArray(doc))
+            doc = doc.length > 0 ? doc[0] : {};
+        return toObject(doc && typeof doc === 'object' ? doc : {});
+    }
+    // ---------------------------------------------------------------------- Deep links
+    productUrlFor(entity) {
+        const base = (this.cfg.baseUrl ?? '').replace(/\/+$/, '');
+        return `${base}/${PROJECT_URL_SEGMENT[entity.kind]}/${entity.id}`;
+    }
+    // ---------------------------------------------------------------------- Agent hop (recording + not-yet-ported ops)
+    // Everything below either delegates to the local agent /mcp (recording surface, and writes/testdata/
+    // run dispatch we haven't ported to REST yet) or fails with a clear message when the hop is unset.
+    // As each step of the port lands, the corresponding delegate is replaced with a direct REST impl.
+    hop() {
+        if (!this.cfg.url)
+            return null;
+        if (!this.agentHop)
+            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() {
+        const h = this.hop();
+        return h ? h.listAgentTools() : [];
+    }
+    /** Forward a recording-tool call to the agent /mcp. Same behavior as walnut. */
+    async callRaw(name, args) {
+        const h = this.hop();
+        if (!h) {
+            throw new Error("Recording needs a local SimplifyQA agent — set QA_MCP_URL to the agent's /mcp endpoint.");
+        }
+        return h.callRaw(name, args);
+    }
+    // ---------------------------------------------------------------------- Test cases (write)  [Step 4]
+    /** Two-step create: (1) resolve every `${name}` token in the steps to a project-scoped parameter id
+     *  (get-or-create), (2) POST /tm/testcase multipart with the assembled `testcaseObj`. */
+    async createTestCase(tc) {
+        const projectId = this.requireProjectId();
+        const moduleId = Number.parseInt(String(tc.folderOrModule ?? '0'), 10) || 0;
+        const userstoryId = tc.storyRef ? await this.resolveStoryNumericIdOrNull(tc.storyRef) : undefined;
+        const paramIdByName = await this.resolveParamIds(projectId, moduleId, tc);
+        const payload = buildTestcasePayload({
+            projectId, moduleId,
+            ...(userstoryId != null ? { userstoryId } : {}),
+            tc,
+            paramIdByName,
+            operation: 'CREATE',
+        });
+        const raw = await this.http.postMultipart('/tm/testcase', 'testcaseObj', payload);
+        return toSavedRef(raw, true);
+    }
+    /** Same shape as create, but with `tcfnObj.id` set and operation:'UPDATE'. */
+    async updateTestCase(id, tc) {
+        const projectId = this.requireProjectId();
+        const moduleId = Number.parseInt(String(tc.folderOrModule ?? '0'), 10) || 0;
+        const userstoryId = tc.storyRef ? await this.resolveStoryNumericIdOrNull(tc.storyRef) : undefined;
+        const paramIdByName = await this.resolveParamIds(projectId, moduleId, tc);
+        const payload = buildTestcasePayload({
+            projectId, moduleId,
+            ...(userstoryId != null ? { userstoryId } : {}),
+            existingId: numericId(id),
+            tc,
+            paramIdByName,
+            operation: 'UPDATE',
+        });
+        // `!` — 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);
+    }
+    /** Soft-delete (recoverable via recycle bin). `isDelete:true` = delete; `false` = restore. */
+    async deleteTestCase(id) {
+        const projectId = this.requireProjectId();
+        await this.http.postJson('/tm/testcase/delete', {
+            ids: [Number.parseInt(numericId(id), 10)],
+            projectId,
+            isDelete: true,
+        });
+    }
+    /** Never throw on unresolvable storyRef — the Java code logs and moves on so the save still lands. */
+    async resolveStoryNumericIdOrNull(storyRef) {
+        try {
+            const s = await this.resolveStoryNumericId(storyRef);
+            const n = Number.parseInt(s, 10);
+            return Number.isFinite(n) ? n : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Resolve every `${name}` token across every step to a SQA parameter id via get-or-create.
+     *  Name-uniqueness is project-wide on the backend; get-or-create means every TC using
+     *  `${appUrl}` links to the same parameter row. */
+    async resolveParamIds(projectId, moduleId, tc) {
+        const paramIdByName = new Map();
+        const steps = Array.isArray(tc.steps) ? tc.steps : [];
+        for (const s of steps) {
+            const names = extractParamNames(s.description);
+            for (const name of names) {
+                if (paramIdByName.has(name))
+                    continue;
+                const defaultValue = paramDefault(name, tc.data, s.value);
+                const id = await this.getOrCreateParameter(projectId, moduleId, name, defaultValue);
+                paramIdByName.set(name, id);
+            }
+        }
+        return paramIdByName;
+    }
+    /** Case-insensitive project-scoped exact-name lookup. Backend duplicate-name check uses Mongo
+     *  collation strength:2, so a case-sensitive search here misses params stored under different
+     *  casing — the next POST then trips "Duplicate Name Error". Returns null when not found. */
+    async findParameterId(projectId, name) {
+        const body = this.searchBody([
+            { column: 'name', value: name },
+            { column: 'projectId', value: projectId },
+        ], { startIndex: 0, limit: 10 });
+        // The `searchFields` shape supports `ignorecase:true` per-field; searchBody doesn't emit it,
+        // so add it inline for the name column.
+        body['searchFields'][0]['ignorecase'] = true;
+        const raw = await this.http.postJson('/tm/parameter/search', body);
+        const rows = pickArray(raw, 'data', 'content');
+        for (const row of rows) {
+            const rowName = str(row, 'name');
+            if (rowName === name) {
+                const id = str(row, 'id', '_id', 'parameterId');
+                if (id)
+                    return Number.parseInt(id, 10);
+            }
+        }
+        return null;
+    }
+    async getOrCreateParameter(projectId, moduleId, name, defaultValue) {
+        const existing = await this.findParameterId(projectId, name);
+        if (existing != null)
+            return existing;
+        const body = {
+            name,
+            projectId,
+            protected: looksSensitive(name),
+            ...(moduleId > 0 ? { moduleId } : {}),
+            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',
+            parameterType: 'Alphanumeric',
+            description: '',
+            unique: false,
+            concat: '',
+            paramAttributes: { minLength: 0, maxLength: 0, prefix: '', suffix: '' },
+        };
+        let raw;
+        try {
+            raw = await this.http.postJson('/tm/parameter', body);
+        }
+        catch (e) {
+            // Backend rejects a race-lost duplicate with 500 "Duplicate Name" when the concurrent search
+            // missed the just-created row. Recover by re-querying — same name, project-scoped.
+            const msg = e instanceof Error ? e.message : String(e);
+            if (/Duplicate Name|BADREQUEST/i.test(msg)) {
+                const after = await this.findParameterId(projectId, name);
+                if (after != null)
+                    return after;
+            }
+            throw e;
+        }
+        // The id lives at various nesting levels depending on which path the backend took (bare doc,
+        // `data`, or `message[0]` for a race-lost duplicate). Try all three.
+        let id = str(raw, 'id', '_id', 'parameterId') ?? str(raw?.data, 'id', '_id', 'parameterId');
+        if (!id) {
+            const m = raw?.message;
+            if (Array.isArray(m) && m.length > 0)
+                id = str(m[0], 'id', '_id', 'parameterId');
+            else if (m && typeof m === 'object')
+                id = str(m, 'id', '_id', 'parameterId');
+        }
+        if (!id)
+            throw new Error(`getOrCreateParameter: no id in response: ${JSON.stringify(raw)}`);
+        return Number.parseInt(id, 10);
+    }
+    // ---------------------------------------------------------------------- Suites (write)  [Step 4]
+    async createSuite(s) {
+        // Java stubs this out ("create_suite is not supported yet on SimplifyQA"). Mirror that.
+        if (this.hop())
+            return this.requireHop('create_suite').createSuite(s);
+        throw new Error('create_suite is not supported yet on SimplifyQA — create the suite in the SimplifyQA UI, ' +
+            'then add test cases via suite_add_testcases.');
+    }
+    /** Fetch raw suite, apply add/remove/reorder ops in memory, then PUT the whole doc back with a
+     *  STRICT allow-listed payload (the SQA update validator rejects unknown keys on both suite-level
+     *  and testCases[] entries). */
+    async updateSuiteMembers(id, ops) {
+        if (!Array.isArray(ops))
+            throw new Error('ops must be an array');
+        const raw = await this.fetchRawSuite(id);
+        if (Object.keys(raw).length === 0)
+            throw new Error(`suite ${id} not found`);
+        const currentRows = Array.isArray(raw['testCases']) ? raw['testCases'] : [];
+        const members = currentRows.map(normalizeSuiteEntry);
+        for (const op of ops) {
+            const tcNum = numericId(String(op.tcId));
+            switch (op.op) {
+                case 'add': {
+                    const already = members.some((m) => String(m['testcaseId']) === tcNum);
+                    if (!already)
+                        members.push(await this.buildSuiteEntryFromTestcase(tcNum));
+                    break;
+                }
+                case 'remove': {
+                    for (let i = members.length - 1; i >= 0; i--) {
+                        if (String(members[i]['testcaseId']) === tcNum)
+                            members.splice(i, 1);
+                    }
+                    break;
+                }
+                case 'reorder': {
+                    const newOrder = op.order ?? -1;
+                    const idx = members.findIndex((m) => String(m['testcaseId']) === tcNum);
+                    if (idx < 0 || newOrder < 1 || newOrder > members.length)
+                        break;
+                    const [moved] = members.splice(idx, 1);
+                    if (moved)
+                        members.splice(newOrder - 1, 0, moved);
+                    break;
+                }
+                default: throw new Error(`suite op '${op.op}' not supported (add|remove|reorder)`);
+            }
+        }
+        // Renumber `seq` contiguously from 1 after any mutation.
+        members.forEach((m, i) => { m['seq'] = i + 1; });
+        const payload = {};
+        for (const k of SUITE_UPDATE_ALLOWED_KEYS) {
+            if (raw[k] !== undefined)
+                payload[k] = raw[k];
+        }
+        payload['tcChanged'] = true;
+        payload['testCases'] = members;
+        await this.http.putMultipart(`/tm/suites/${numericId(id)}`, 'suiteObj', payload);
+        return this.getSuite(id);
+    }
+    /** Soft-delete via `isDelete:true`. `isDelete:false` restores. */
+    async deleteSuite(id) {
+        const projectId = this.requireProjectId();
+        await this.http.patchJson('/tm/suites', {
+            ids: [Number.parseInt(numericId(id), 10)],
+            projectId,
+            isDelete: true,
+        });
+    }
+    async fetchRawSuite(id) {
+        const raw = await this.http.getJson(`/tm/suites/${numericId(id)}`);
+        let doc = raw?.data ?? raw;
+        if (Array.isArray(doc))
+            doc = doc.length > 0 ? doc[0] : {};
+        return doc && typeof doc === 'object' ? doc : {};
+    }
+    /** Assemble the strict allow-listed suite entry for an ADD op. Required fields per the SQA
+     *  validator: testcaseId, code, seq (set by the caller), version, versionId, tcType. */
+    async buildSuiteEntryFromTestcase(tcNum) {
+        const raw = await this.fetchRawTestcase(tcNum);
+        if (Object.keys(raw).length === 0)
+            throw new Error(`test case ${tcNum} not found (cannot add to suite)`);
+        const code = str(raw, 'code', 'tcCode') ?? `TC_${tcNum}`;
+        const tcType = str(raw, 'tcType') ?? 'WEB';
+        let versionName = str(raw, 'versionName', 'selectedVersionName');
+        let versionId = str(raw, 'versionId', 'selectedVersionId');
+        if ((!versionName || !versionId) && Array.isArray(raw?.versions) && raw.versions.length > 0) {
+            const v = raw.versions[0];
+            versionName ?? (versionName = str(v, 'name'));
+            versionId ?? (versionId = str(v, 'id', '_id'));
+        }
+        return {
+            testcaseId: Number.parseInt(tcNum, 10),
+            code,
+            tcType,
+            ...(raw?.projectId !== undefined ? { projectId: raw.projectId } : {}),
+            version: versionName ?? 'v1.0',
+            versionId: versionId ?? '',
+            executionPlatform: { LOCAL: {}, REMOTE: {}, CLOUD: {} },
+        };
+    }
+    // ---------------------------------------------------------------------- Object search + write  [Step 4]
+    // No exposed common-mcp tool calls these on ProviderAdapter today for SQA — leave on hop.
+    async searchObjects(q) { return this.requireHop('search_objects').searchObjects(q); }
+    async createObject(o) { return this.requireHop('create_object').createObject(o); }
+    // ---------------------------------------------------------------------- Actions catalog
+    async actionsCatalog(platform) {
+        return this.requireHop('actions_catalog').actionsCatalog(platform);
+    }
+    // ---------------------------------------------------------------------- Testdata generation  [Step 3]
+    /** Fetch the default (template) iteration row for a TC. Fills gaps from the raw TC:
+     *   - versionId: falls back through versionId → selectedVersionId → versionsDetails.id → versions[0].id
+     *   - executionType (required by the backend Mongo filter): read from raw TC, default AUTOMATION
+     *   - environmentType: caller value wins; else /pm/fields/8 first configured env; else 'general' */
+    async getDefaultIteration(q) {
+        const projectId = this.requireProjectId();
+        const tcNum = numericId(q.tcId);
+        let versionId = q.versionId;
+        let execType;
+        if (!versionId || !execType) {
+            const raw = await this.fetchRawTestcase(q.tcId);
+            if (!versionId) {
+                versionId = str(raw, 'versionId', 'selectedVersionId', 'selVersion');
+                if (!versionId && raw?.versionsDetails && typeof raw.versionsDetails === 'object') {
+                    versionId = str(raw.versionsDetails, 'id', '_id', 'versionId');
+                }
+                if (!versionId && Array.isArray(raw?.versions) && raw.versions.length > 0) {
+                    versionId = str(raw.versions[0], 'id', '_id');
+                }
+            }
+            execType = str(raw, 'executionType');
+            if (!versionId)
+                throw new Error(`test case ${q.tcId} has no versionId — pass one explicitly`);
+        }
+        if (!execType)
+            execType = 'AUTOMATION';
+        const env = await this.resolveEnvironment(projectId, q.environmentType);
+        const path = '/tm/testdata/getDefaultItr' +
+            `?projectId=${projectId}` +
+            `&testcaseId=${tcNum}` +
+            `&versionId=${encodeURIComponent(versionId)}` +
+            `&environmentType=${encodeURIComponent(env)}` +
+            '&collection=TC' +
+            `&executionType=${encodeURIComponent(execType)}`;
+        const raw = await this.http.getJson(path);
+        const paramsMap = raw?.data?.parametersData;
+        const parameters = [];
+        if (paramsMap && typeof paramsMap === 'object' && !Array.isArray(paramsMap)) {
+            for (const [key, value] of Object.entries(paramsMap)) {
+                const pid = Number.parseInt(key, 10);
+                if (!Number.isFinite(pid))
+                    continue;
+                const seed = String(value?.value ?? '');
+                const name = await this.fetchParameterName(pid);
+                if (!name)
+                    continue; // parameter deleted — skip
+                parameters.push({ paramId: pid, name, seed });
+            }
+        }
+        return { tcId: q.tcId, versionId: versionId, environmentType: env, parameters };
+    }
+    /** Persist N generated iteration rows. Rebuilds the name → paramId map from a fresh template
+     *  fetch — no cache, because a stale id would silently write to the wrong parameter. */
+    async saveGeneratedIterations(payload) {
+        if (!payload.rows || payload.rows.length === 0)
+            throw new Error('rows[] required and non-empty');
+        if (!payload.versionId)
+            throw new Error('versionId required — call get_default_iteration first');
+        const projectId = this.requireProjectId();
+        const tcNum = numericId(payload.tcId);
+        const env = payload.environmentType || 'general';
+        // Reuse the caller's already-fetched template when supplied — the tc_generate_testdata tool
+        // fetches it just before calling us. Skipping the re-fetch avoids a duplicate /getDefaultItr +
+        // N /tm/parameter/{id} round trips per save.
+        const tplParams = payload.parameters ?? (await this.getDefaultIteration({
+            tcId: payload.tcId,
+            versionId: payload.versionId,
+            environmentType: env,
+        })).parameters;
+        const nameToId = new Map();
+        for (const p of tplParams)
+            nameToId.set(p.name, p.paramId);
+        const formulas = payload.formulas ?? {};
+        const formulaNames = Object.keys(formulas);
+        // Per-row: evaluate the row's formula columns concurrently. The compute endpoint mints RANDOM
+        // values so each call must still happen (no dedup across rows), but within a row the calls are
+        // independent — Promise.all cuts wall time roughly by the formula count.
+        // ponytail: per-row concurrency only. Firing all rows × formulas at once would work but might
+        // stress the external DATA_GENERATION_URL proxy; scale wider only if the row-level speedup is not enough.
+        const iterations = [];
+        for (const row of payload.rows) {
+            const data = [];
+            for (const [k, v] of Object.entries(row)) {
+                if (formulaNames.includes(k))
+                    continue; // a formula covers this column — its value wins
+                const pid = nameToId.get(k);
+                if (pid == null)
+                    continue; // unknown param name — silently skip
+                data.push({ paramId: pid, value: String(v ?? '') });
+            }
+            const evaluated = await Promise.all(formulaNames.map(async (name) => {
+                const pid = nameToId.get(name);
+                if (pid == null)
+                    return null;
+                const { value, expression } = await this.evaluateFormula(formulas[name]);
+                return { paramId: pid, value, formulaValue: expression };
+            }));
+            for (const cell of evaluated)
+                if (cell)
+                    data.push(cell);
+            iterations.push({ isChecked: true, data });
+        }
+        const body = {
+            projectId,
+            data: [
+                {
+                    type: 'TC',
+                    id: Number.parseInt(tcNum, 10),
+                    versionId: payload.versionId,
+                    environmentType: env,
+                    projectId,
+                    iterations,
+                },
+            ],
+        };
+        await this.http.postJson('/tm/testdata/saveItrForDataGen', body);
+        return { tcId: payload.tcId, inserted: iterations.length };
+    }
+    /** Environment key: caller wins; else fetch the project's configured envs and pick the first;
+     *  else 'general' (matches the SQA UI fallback). */
+    async resolveEnvironment(projectId, requested) {
+        if (requested && requested.length > 0)
+            return requested;
+        try {
+            const envs = await this.http.getJson(`/pm/fields/8?projectId=${projectId}&fieldType=environment`);
+            if (Array.isArray(envs) && envs.length > 0) {
+                const key = str(envs[0], 'key', 'value', 'name');
+                if (key)
+                    return key;
+            }
+        }
+        catch { /* fall through */ }
+        return 'general';
+    }
+    /** Parameter name lookup for paramId → name enrichment. Null when the parameter is deleted or
+     *  belongs to a different project. */
+    async fetchParameterName(paramId) {
+        let raw;
+        try {
+            raw = await this.http.getJson(`/tm/parameter/${paramId}`);
+        }
+        catch {
+            return null;
+        }
+        let n = raw?.data ?? raw;
+        if (Array.isArray(n))
+            n = n.length > 0 ? n[0] : null;
+        if (!n || typeof n !== 'object')
+            return null;
+        return str(n, 'name') ?? null;
+    }
+    // ---------------------------------------------------------------------- Formulas  [Step 3b]
+    /** List every formula the current project can use — DEFAULT (customer-wide prefabs) unioned with
+     *  CUSTOM entries scoped to the customer or this project. The backend endpoint already returns the
+     *  union when called with `projectId`; we just normalise the doc shape and derive `scope` from
+     *  (type + projectId). Cached per adapter instance. */
+    async listFormulas() {
+        if (this.formulaCache)
+            return this.formulaCache;
+        const projectId = this.requireProjectId();
+        const pending = (async () => {
+            const raw = await this.http.getJson(`/tm/syncFormulas/fetch?projectId=${projectId}`);
+            const list = Array.isArray(raw?.data) ? raw.data : Array.isArray(raw) ? raw : [];
+            const out = [];
+            for (const doc of list) {
+                const f = normalizeFormula(doc, projectId);
+                if (f)
+                    out.push(f);
+            }
+            return out;
+        })().catch((e) => {
+            // On failure, drop the memoised promise so a retry actually retries.
+            this.formulaCache = null;
+            throw e;
+        });
+        this.formulaCache = pending;
+        return pending;
+    }
+    /** Evaluate one formula call and return { value, expression }. Order args by the formula's declared
+     *  parameter list so the stored `formulaValue` string is positional (`=NAME("a","b")`) — that's
+     *  what the SQA UI writes, and the backend just reads it verbatim on save. */
+    async evaluateFormula(call) {
+        const all = await this.listFormulas();
+        // Both sides carry parens: the backend stores DEFAULT names as "FIRST_NAME()", and models copy the
+        // SIGNATURE format ("FIRST_NAME(country name,sex,min,max)"). Strip on both, compare case-insensitively.
+        const needle = bareFormulaName(call.name).toUpperCase();
+        const meta = all.find((f) => bareFormulaName(f.name).toUpperCase() === needle);
+        if (!meta) {
+            throw new Error(`Unknown formula "${call.name}" — call tc_list_formulas to see what is available.`);
+        }
+        const fname = bareFormulaName(meta.name);
+        // Arg keys arrive with trailing colons/whitespace ("country name:", " sex ") from both the model AND
+        // the formula's own declared keyName. Normalise both sides before binding.
+        const argKey = (k) => k.replace(/:$/, '').trim();
+        const args = {};
+        for (const [k, v] of Object.entries(call.args ?? {}))
+            args[argKey(k)] = v;
+        const ordered = meta.parameters.map((p) => args[argKey(p.keyName)] ?? '');
+        // /tm/customFormula takes its OWN positional query keys, not the formula's display keyNames.
+        const qs = new URLSearchParams({ formulaName: fname });
+        const apiKeys = FORMULA_ARG_KEYS[fname.toUpperCase()] ?? ['value'];
+        ordered.forEach((v, i) => { if (v !== '' && apiKeys[i])
+            qs.append(apiKeys[i], v); });
+        // ponytail: the compute endpoint's response envelope varies between formula types
+        // (`{data:{value}}` for person-info, plain string for a few); coerce defensively.
+        const resp = await this.http.getJson(`/tm/customFormula?${qs.toString()}`);
+        const value = String(resp?.data?.value ?? resp?.value ?? resp?.data ?? resp ?? '');
+        const quoted = ordered.map((a) => `"${String(a).replace(/"/g, '\\"')}"`).join(',');
+        const expression = `=${fname}(${quoted})`;
+        return { value, expression };
+    }
+    // ---------------------------------------------------------------------- Run status  [Step 6]
+    /** Real status of a run — reads step-level results direct from SQA REST because the desktop agent's
+     *  get_run only returns queue state (often stale). start/stop still hop for v1. */
+    async getRun(runId) {
+        const projectId = this.requireProjectId();
+        const base = (this.cfg.baseUrl ?? '').replace(/\/+$/, '');
+        // GET /exec/report/{runId}/{projectId} — the run rows the /reports page reads.
+        const runs = await this.http.getJson(`/exec/report/${runId}/${projectId}`);
+        if (!Array.isArray(runs) || runs.length === 0) {
+            return { runId, state: 'queued' };
+        }
+        // Multi-TC runs return several rows; pick the first FAILED so tc_heal has a failing step to diagnose.
+        let chosen = runs[0];
+        for (const r of runs) {
+            if (typeof r?.status === 'string' && r.status.toUpperCase() === 'FAILED') {
+                chosen = r;
+                break;
+            }
+        }
+        const executionRunId = str(chosen, 'id', '_id') ?? '';
+        const parentId = Number(chosen?.executionItemId ?? 0);
+        const stepsResp = await this.http.postJson('/reports/execution/getstepResult', {
+            executionId: Number.parseInt(numericId(runId), 10),
+            executionRunId,
+            parentId,
+            projectId,
+        });
+        const rawSteps = Array.isArray(stepsResp?.data) ? stepsResp.data : [];
+        const stepResults = rawSteps.map((s) => {
+            const step = {
+                n: typeof s?.seq === 'number' ? s.seq : 0,
+                description: String(s?.description ?? ''),
+                status: mapStepStatus(str(s, 'status') ?? ''),
+            };
+            const exc = str(s, 'exception');
+            if (exc && exc.length > 0) {
+                step.error = exc;
+            }
+            else {
+                // SQA leaves `exception` null even on FAILED. The real cause sits in ERROR log lines
+                // (e.g. "No Such Element Exception: ..."). Send ALL ERROR lines joined — a trailing
+                // "JS disabled" line would otherwise mask the real NoSuchElement above it.
+                const logs = s?.executionLogData?.executionLogs;
+                if (Array.isArray(logs) && logs.length > 0) {
+                    const errorLines = [];
+                    for (const l of logs) {
+                        const t = String(l ?? '');
+                        if (t.includes('ERROR'))
+                            errorLines.push(t);
+                    }
+                    if (errorLines.length > 0)
+                        step.error = errorLines.join('\n');
+                    else
+                        step.error = String(logs[logs.length - 1] ?? '');
+                }
+            }
+            return step;
+        });
+        return {
+            runId,
+            state: mapRunState(str(chosen, 'status') ?? ''),
+            stepResults,
+            reportUrl: `${base}/reports/execution/${runId}`,
+        };
+    }
+    // --- Run dispatch (direct REST) --------------------------------------------
+    // Trigger, stop, and local-agent roster all speak the SQA gateway directly.
+    // The desktop agent still runs the actual TC — backend RPUSHes to Redis and the
+    // agent's poll loop picks it up — but the KICKOFF event no longer hops through
+    // /mcp:4040. Spec: common-mcp/plan/sqa-execution-trigger.md. Cloud runners and
+    // SUITE runs are not yet ported and still hop (or error clearly).
+    async startRun(target, opts) {
+        const projectId = this.requireProjectId();
+        if (!target.tcId) {
+            if (target.suiteId) {
+                throw new Error('startRun: SUITE runs are not yet ported to direct REST — set QA_MCP_URL so common-mcp ' +
+                    'can hop to the SimplifyQA agent for suite dispatch, or run a single TC.');
+            }
+            throw new Error('startRun: target.tcId (or target.suiteId) is required.');
+        }
+        const tcId = target.tcId;
+        const tcNum = Number.parseInt(numericId(tcId), 10);
+        if (!Number.isFinite(tcNum))
+            throw new Error(`startRun: could not resolve numeric id for ${tcId}.`);
+        const mode = (opts.mode ?? 'local').toUpperCase();
+        const rawTc = await this.fetchRawTestcase(tcId);
+        if (!rawTc || Object.keys(rawTc).length === 0) {
+            throw new Error(`startRun: test case ${tcId} not found.`);
+        }
+        // Version resolution — same fallback chain buildTestcasePayload/getDefaultIteration use.
+        let versionName = str(rawTc, 'versionName', 'selectedVersionName');
+        let versionId = str(rawTc, 'versionId', 'selectedVersionId');
+        if ((!versionName || !versionId) && rawTc?.versionsDetails && typeof rawTc.versionsDetails === 'object') {
+            versionName ?? (versionName = str(rawTc.versionsDetails, 'name'));
+            versionId ?? (versionId = str(rawTc.versionsDetails, 'id', '_id', 'versionId'));
+        }
+        if ((!versionName || !versionId) && Array.isArray(rawTc?.versions) && rawTc.versions.length > 0) {
+            const v = rawTc.versions[0];
+            versionName ?? (versionName = str(v, 'name'));
+            versionId ?? (versionId = str(v, 'id', '_id'));
+        }
+        versionName ?? (versionName = 'v1.0');
+        versionId ?? (versionId = '');
+        const info = await this.info();
+        const env = await this.resolveEnvironment(projectId, opts.environment);
+        const tcType = String(str(rawTc, 'tcType') ?? 'WEB').toUpperCase();
+        const executionType = String(str(rawTc, 'executionType') ?? 'AUTOMATION').toUpperCase();
+        const code = str(rawTc, 'code') ?? '';
+        const name = str(rawTc, 'name', 'title') ?? '';
+        const description = str(rawTc, 'description') ?? '';
+        const prerequisite = str(rawTc, 'prerequisite', 'preconditions') ?? '';
+        const moduleIdNum = typeof rawTc?.moduleId === 'number' ? rawTc.moduleId : 0;
+        const userstoryIdNum = typeof rawTc?.userstoryId === 'number' ? rawTc.userstoryId : 0;
+        const tags = Array.isArray(rawTc?.tags) ? rawTc.tags : [];
+        // Best-effort module name — backend doesn't validate it functionally; one /pm/module/search
+        // covers every id, so the extra call is cheap. Story name deliberately left empty; adds a
+        // per-run round-trip for a cosmetic field. ponytail: enrich if a caller ever complains.
+        let moduleName = '';
+        if (moduleIdNum > 0) {
+            try {
+                const modules = await this.listModules();
+                moduleName = modules.find((m) => m.id === String(moduleIdNum))?.name ?? '';
+            }
+            catch { /* leave empty */ }
+        }
+        const agentId = mode === 'LOCAL' ? await this.resolveLocalAgentId(opts.agentId) : null;
+        const platform = this.buildRunPlatform(tcType, mode, opts.browser, opts.deviceId);
+        // UI uses `Math.random().toString(26).substr(5,6)` — plan doc confirms any string works.
+        const stepId = Math.random().toString(36).slice(2, 8).padEnd(6, '0');
+        const body = {
+            projectId,
+            agentId,
+            environmentType: env,
+            executionStyle: (opts.strategy ?? 'serial').toUpperCase(),
+            executionOS: this.detectExecutionOS(),
+            executionTypeId: tcNum,
+            executionTypeName: name,
+            executionTypeCode: code,
+            mailersList: {},
+            cloudType: mode === 'CLOUD' ? 'VM' : 'NONE',
+            mode,
+            executionCategory: 'EXECUTION',
+            releaseId: 0,
+            iterationId: 0,
+            executionTime: '',
+            status: 'INPROGRESS',
+            iterationsSelected: [],
+            result: '',
+            globalConfiguration: {},
+            isRecordingEnabled: false,
+            offset: -(new Date().getTimezoneOffset()),
+            type: 'TESTCASE',
+            executionType,
+            executionItems: [{
+                    id: tcNum,
+                    name,
+                    description,
+                    versionId,
+                    versionName,
+                    seq: 1,
+                    stepId,
+                    stepCount: 0,
+                    technologyType: tcType,
+                    type: 'TC',
+                    platform,
+                    projectId,
+                    projectName: info.projectName,
+                    configuration: {},
+                    iterationsSelected: [],
+                    moduleId: moduleIdNum,
+                    userstoryId: userstoryIdNum,
+                    tags,
+                    code,
+                    prerequisite,
+                    moduleName,
+                    userstoryName: '',
+                }],
+        };
+        const resp = await this.http.postJson('/exec/execution', body);
+        const d = resp?.data ?? resp;
+        const runId = str(d, 'id', 'executionId', '_id') ??
+            (typeof d?.id === 'number' ? String(d.id) : undefined) ??
+            (typeof d?.executionId === 'number' ? String(d.executionId) : undefined);
+        if (!runId)
+            throw new Error('startRun: backend accepted trigger but returned no run id.');
+        return { runId };
+    }
+    async stopRun(runId) {
+        const projectId = this.requireProjectId();
+        const executionId = Number.parseInt(numericId(runId), 10);
+        if (!Number.isFinite(executionId))
+            throw new Error(`stopRun: invalid runId ${runId}.`);
+        await this.http.postJson('/exec/execution/stopExecution', {
+            projectId,
+            executionId,
+            killType: 'STOP_EXECUTION',
+        });
+    }
+    // Cloud runner roster is not yet ported — plan doc only covers LOCAL trigger + stop + agents.
+    async listCloudRunners() { return this.requireHop('list_cloud_runners').listCloudRunners(); }
+    async listLocalAgents() {
+        const body = this.searchBody([{ column: 'deleted', value: false }], { limit: 1000 });
+        const raw = await this.http.postJson('/tm/machineRegistration/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'agents', 'machines');
+        return rows.map((n) => {
+            const id = str(n, 'id', '_id', 'agentId') ?? '';
+            const agentName = str(n, 'machineName', 'name', 'host');
+            const owner = str(n, 'owner', 'userName', 'createdBy');
+            const host = str(n, 'macAddress', 'hostAddress');
+            // `active` is the real Redis-heartbeat flag on machineRegistration — the executor only picks
+            // up runs whose agent is currently polling. A stale registration with `active: false` will
+            // sit in Redis until TTL and never execute, so surface the real state to the caller.
+            const active = typeof n?.active === 'boolean' ? n.active : false;
+            return {
+                id,
+                ...(agentName ? { name: agentName } : {}),
+                online: active,
+                ...(owner ? { owner } : {}),
+                ...(host ? { host } : {}),
+            };
+        });
+    }
+    /**
+     * Pick THE ACTING USER'S OWN active agent — never row [0] of a shared-tenant roster (which
+     * would silently dispatch a local run to a teammate's box, and the run would sit queued until
+     * TTL because it lands in a Redis key that no local agent on the caller's machine polls).
+     *
+     * SQA's `machineRegistration` row carries no owner_user_id column (unlike walnut, which matches
+     * the JWT `id` claim to `owner_user_id`), so we identify "your" agent by hostname: common-mcp
+     * runs on the caller's own box in the typical MCP setup, and SQA `machineName` is either the
+     * bare OS hostname or a bracketed display form (`USER.NAME [ Hostname.local ]`) — both contain
+     * `os.hostname()`. Filter → active only → hostname substring match → return the single hit.
+     * Zero/many matches refuse honestly; a silent guess would just repeat the exact bug we're fixing.
+     *
+     * ponytail: hostname heuristic. Upgrade to owner-user-id match if the backend adds that column
+     * to machineRegistration (mirror walnut's `resolveLocalAgentCredential` at that point).
+     */
+    async resolveLocalAgentId(preferred) {
+        if (preferred && preferred.length > 0)
+            return preferred;
+        const agents = await this.listLocalAgents();
+        if (agents.length === 0) {
+            throw new Error('startRun (LOCAL): no local agent registered. Register a machine in the SimplifyQA UI ' +
+                'first, or pass mode: "cloud" if a cloud runner is provisioned.');
+        }
+        const active = agents.filter((a) => a.online);
+        if (active.length === 0) {
+            throw new Error('startRun (LOCAL): no local agent is currently active (polling). Launch your SimplifyQA ' +
+                'desktop agent and retry — or pass `agentId` explicitly if you know the credential id.');
+        }
+        const host = os.hostname().toLowerCase();
+        const mine = active.filter((a) => (a.name ?? '').toLowerCase().includes(host));
+        if (mine.length === 1)
+            return mine[0].id;
+        const listing = (arr) => arr.map((a) => `  - ${a.name ?? a.id} \`${a.id}\``).join('\n');
+        if (mine.length > 1) {
+            throw new Error(`startRun (LOCAL): multiple active agents match this machine (${host}). Pass \`agentId\` ` +
+                `to pick one:\n${listing(mine)}`);
+        }
+        throw new Error(`startRun (LOCAL): could not auto-pick your local agent — no active agent's name matches ` +
+            `this hostname (${host}). Pass \`agentId\` explicitly. Active agents:\n${listing(active)}`);
+    }
+    detectExecutionOS() {
+        if (process.platform === 'win32')
+            return 'WINDOWS';
+        if (process.platform === 'darwin')
+            return 'MAC';
+        return 'LINUX';
+    }
+    buildRunPlatform(tcType, mode, browser, deviceId) {
+        const t = tcType.toUpperCase();
+        if (t === 'WEB') {
+            const b = (browser ?? 'CHROME').toUpperCase();
+            return [{ name: b, id: b, technologyType: 'WEB', type: 'NONE' }];
+        }
+        if (t === 'ANDROID' || t === 'IOS') {
+            // Executor's AndroidSessionFactory.buildLocal calls requireDeviceId — no default. Fail
+            // loud so the caller sees the fix (list devices, pick one) instead of a queued/error hang.
+            if (!deviceId) {
+                throw new Error(`${t} test cases need \`deviceId\`. Call android_list_devices to see the available ` +
+                    `devices, then re-run with \`deviceId\` set to the adb serial (LOCAL) or marketplace ` +
+                    `device name (CLOUD).`);
+            }
+            // ponytail: CLOUD path still ships `cloudDeviceType: undefined` — the executor needs it
+            // (BROWSER_STACK / SAUCE_LABS / LAMBDA_INTEGRATION / SQA_DEVICE_FARM) to know which farm
+            // to route to. Deferred with the marketplace port; LOCAL runs unaffected.
+            return [{
+                    name: deviceId, id: deviceId, technologyType: t,
+                    type: mode === 'CLOUD' ? 'CLOUD_DEVICE' : 'NONE',
+                }];
+        }
+        return [{ name: t, id: t, technologyType: t, type: 'NONE' }];
+    }
+    // --- Environments + datasets ------------------------------------------- (fine to hop for now)
+    async listEnvironments() {
+        const h = this.hop();
+        return h ? h.listEnvironments() : [];
+    }
+    async listDatasets(tcId) {
+        const h = this.hop();
+        return h?.listDatasets ? h.listDatasets(tcId) : [];
+    }
+    // --- Journal (recording seed lives on the agent's FS) ------------------
+    async readJournal(tcId) {
+        return this.requireHop('read_journal').readJournal(tcId);
+    }
+    async editJournal(tcId, ops) {
+        return this.requireHop('edit_journal').editJournal(tcId, ops);
+    }
+}
+//# sourceMappingURL=adapter.js.map