common-qa-mcp 0.2.0 → 0.4.0

package/dist/domain/types.d.ts

@@ -19,7 +19,7 @@ export type Step = {
      *  steps by identity (update in place) and correctly deletes the ones dropped — not fragile
      *  slot-by-number matching. Absent on freshly-inserted steps (the backend then creates them). */
     sourceId?: string | undefined;
-    stepType: 'web' | 'api' | 'control_flow' | 'function' | 'database' | 'android' | 'mainframe';
+    stepType: 'manual' | 'web' | 'api' | 'control_flow' | 'function' | 'function_end' | 'database' | 'android' | 'mainframe' | 'switch' | 'compare';
     objectRef?: {
         id?: string | undefined;
         name?: string | undefined;
@@ -27,9 +27,15 @@ export type Step = {
     } | undefined;
     value?: string | undefined;
     expectedResult?: string | undefined;
+    /** Control-flow marker. `kind` mirrors SQA's raw `stepType` for control rows (IF/ELSE/ELSE_IF/IF_END,
+     *  WHILE_START/WHILE/WHILE_END, DO/DO_WHILE, FOR_START/FOR_END, LOOP, ITERATOR_START/END,
+     *  LOOP_ITERATION_START/END, SWITCH_TO_*). Kept as a wide string so a future backend adds don't need
+     *  a schema change here — the markdown renderer defaults unknown kinds to their raw uppercase name. */
     controlFlow?: {
-        kind: 'if' | 'else' | 'if_end' | 'while' | 'while_end';
+        kind: string;
         condition?: Condition | undefined;
+        /** Raw ifstring from SQA's `conditions.ifstring` — the human-readable expression as shown in the UI. */
+        conditionText?: string | undefined;
         blockId?: string | undefined;
         maxIterations?: number | undefined;
     } | undefined;
@@ -41,6 +47,13 @@ export type Step = {
     functionCall?: {
         testCaseId: string;
         testCaseName?: string | undefined;
+        /** SQA function code (e.g. FN_12). Populated by the adapter's FN-name lookup so the
+         *  markdown renderer can show a human ref instead of a bare numeric id. */
+        testCaseCode?: string | undefined;
+        /** SQA `fnVersionId` — the specific version of the referenced function pinned by this call. */
+        versionId?: string | undefined;
+        /** SQA `sharedFnProjectId` — non-null when the FN lives in a different project (shared functions). */
+        sharedProjectId?: string | undefined;
         inputParams?: Record<string, unknown> | undefined;
         continueOnFailure?: boolean | undefined;
     } | undefined;
@@ -50,6 +63,14 @@ export type Step = {
         continueOnFailure?: boolean | undefined;
         optional?: boolean | undefined;
     } | undefined;
+    /** WEB automation: browser to target for this step. Defaults to CHROME when absent. */
+    browserType?: string | undefined;
+    /** SQA automation: recorded values for this step, keyed by ACTION PARAMETER NAME (not id).
+     *  Example: for a launch action, `{ packageName: 'us.zoom.videomeetings', activity: '...' }`.
+     *  The mapper resolves each name → paramId via get-or-create, then emits SQA's
+     *  `parameterIds: [<id>...]` + `recordedParam: { <id>: value }` on the step. Populates the
+     *  default iteration on save. Manual TCs ignore this field. */
+    recordedParam?: Record<string, string> | undefined;
 };
 export type TestCase = {
     id?: string | undefined;
@@ -66,29 +87,82 @@ export type TestCase = {
     tags?: string[] | undefined;
     steps: Step[];
     version?: number | undefined;
+    /** All non-deleted versions of this TC — populated by adapters that support versioning (SQA).
+     *  `id` is the version's opaque id (SQA `tcfn_version.id`, a uuid); `name` is the human label
+     *  ("v1.0"). Walnut/manual-only adapters leave this undefined. */
+    versions?: TcVersion[] | undefined;
+    /** The version whose steps are surfaced on `steps[]`. Adapters resolve this: caller-provided
+     *  `versionId` argument > TC's currently-selected version > first entry in `versions[]`. */
+    currentVersionId?: string | undefined;
     /** Default-row test data: param name -> value. Forwarded to the product on save to populate the
      *  datarow of the dataset it auto-creates from the `${param}` tokens in step descriptions, so the
      *  saved test case is executable with data. Optional -- the product also derives it from each
      *  step's single `${param}` + its value. */
     data?: Record<string, string> | undefined;
+    /** SQA automation: execution target (device / browser) for the test case.
+     *  - WEB: OPTIONAL — omit to let the SQA backend default to Chrome.
+     *  - ANDROID / IOS: REQUIRED — the mapper refuses the save without one.
+     *  Wire shape mirrors the SQA `executionPlatform` field on the tcfnObj:
+     *  `{ id: <deviceSerial|'CHROME'>, name, technologyType: 'ANDROID'|'IOS'|'WEB', type:
+     *    'REAL_DEVICE'|'CLOUD_DEVICE'|'NONE', cloudDeviceType? }`. */
+    executionPlatform?: {
+        id: string;
+        name: string;
+        technologyType: string;
+        type: string;
+        cloudDeviceType?: string | undefined;
+    } | undefined;
+};
+/** One entry in `TestCase.versions[]`. Fields mirror what SQA's `/tm/testcase/getById` projects onto
+ *  `versions[]` (tcfn.service.js:1489). `updateVersion` is the optimistic-lock counter, useful when
+ *  the caller wants to display which version is newest. */
+export type TcVersion = {
+    id: string;
+    name: string;
+    updateVersion?: number | undefined;
+    reviewApproveStatus?: string | undefined;
+    executionType?: string | undefined;
+    /** True when this is the TC's currently-selected version (the one the UI opens by default). */
+    isCurrent?: boolean | undefined;
 };
 export type TcSummary = {
     id: string;
+    code?: string;
     title: string;
     priority: string;
     status?: string;
     stepCount?: number;
+    technologyType?: string;
+    executionType?: string;
+    obsolete?: boolean;
 };
 export type ProjectSummary = {
     id: string;
+    code?: string;
     name: string;
     counts?: Record<string, number> | undefined;
 };
+/** One raw backend column filter (searchFields protocol) — see `zRawFilter` in tools/schemas.ts. */
+export type RawSearchFilter = {
+    column: string;
+    value: string | number | boolean | string[] | number[];
+    regEx?: boolean | undefined;
+};
 export type TcQuery = {
     search?: string;
     status?: string;
     limit?: number;
     offset?: number;
+    /** Filter by numeric userId of the creator. Pass "me" and the adapter substitutes cfg.userId. */
+    createdBy?: string;
+    /** Filter by numeric userId of the last updater. Pass "me" and the adapter substitutes cfg.userId. */
+    updatedBy?: string;
+    storyId?: string;
+    /** Filter to test cases filed under this module (id or business key). SimplifyQA only; ignored on providers without a module tree. */
+    moduleId?: string;
+    /** True → only obsolete TCs; false → only non-obsolete. Omit to include both. SimplifyQA only. */
+    obsolete?: boolean;
+    filters?: RawSearchFilter[];
 };
 /** A USER STORY (Walnut `user_stories` doc, type 'story'). `key` = the human business key (walnut_key
  *  like US_001, or an external Jira/ADO key). `id` = the Mongo _id (what test cases link to via story_id). */
@@ -113,6 +187,420 @@ export type StoryQuery = {
     status?: string;
     limit?: number;
     offset?: number;
+    /** Filter stories that belong to this sprint. Neutral name; SimplifyQA maps it to `userstory.iterationId` server-side. */
+    sprintId?: string;
+    /** Filter stories that belong to this release (SimplifyQA `userstory.releaseId`). */
+    releaseId?: string;
+    /** Filter by numeric userId of the creator. Pass "me" and the adapter substitutes cfg.userId. */
+    createdBy?: string;
+    /** Filter by numeric userId of the last updater. Pass "me" and the adapter substitutes cfg.userId. */
+    updatedBy?: string;
+    /** Filter by numeric userId of the story owner (`userstory.ownerId`). Pass "me" and the adapter
+     *  substitutes cfg.userId. Testcases have no owner field — this is story-only. */
+    ownerId?: string;
+    filters?: RawSearchFilter[];
+};
+export type DefectSummary = {
+    id: string;
+    code?: string | undefined;
+    title: string;
+    state?: string | undefined;
+    severity?: string | undefined;
+    priority?: string | undefined;
+    assignedTo?: string[] | undefined;
+    tcIds?: string[] | undefined;
+};
+export type DefectQuery = {
+    search?: string;
+    limit?: number;
+    offset?: number;
+    tcId?: string;
+    storyId?: string;
+    /** Exact workflow-state key (e.g. "new"), not the capitalized UI label. */
+    state?: string;
+    /** Numeric userId of the assignee (array field on the defect). Pass "me" for the caller. */
+    assignedTo?: string;
+    createdBy?: string;
+    filters?: RawSearchFilter[];
+};
+/** A TASK (SimplifyQA `pm.task`) — project-management work item, distinct from a test case or defect. */
+export type TaskSummary = {
+    id: string;
+    code?: string | undefined;
+    title: string;
+    state?: string | undefined;
+    priority?: string | undefined;
+    assignedTo?: string[] | undefined;
+    /** Linked defect id, when raised against one. */
+    defectId?: string | undefined;
+};
+export type TaskQuery = {
+    search?: string;
+    limit?: number;
+    offset?: number;
+    /** Filter to tasks linked to this user story (`userstoryId`). */
+    storyId?: string;
+    state?: string;
+    assignedTo?: string;
+    createdBy?: string;
+    filters?: RawSearchFilter[];
+};
+/** Fields accepted when CREATING a user story (`POST /pm/userstory`). Neutral shape — the SQA adapter
+ *  maps `moduleId`/`iterationId`/etc to the SQA payload as-is. `projectId` is filled from the connected
+ *  project when omitted; `state` and `estimatedEffort` are backend-required. */
+export type StoryInput = {
+    name: string;
+    state: string;
+    estimatedEffort: number;
+    projectId?: number | undefined;
+    epicId?: number | undefined;
+    featureId?: number | undefined;
+    moduleId?: number | undefined;
+    releaseId?: number | undefined;
+    /** SQA `iterationId` — the sprint. */
+    iterationId?: number | undefined;
+    acceptanceCriteria?: string | undefined;
+    description?: string | undefined;
+    priority?: string | undefined;
+    /** SQA accepts an array of userIds. */
+    ownerId?: number[] | undefined;
+    tags?: number[] | undefined;
+    teamId?: number[] | undefined;
+    type?: string | undefined;
+    plannedStartDate?: string | undefined;
+    plannedEndDate?: string | undefined;
+    customFields?: Record<string, unknown> | undefined;
+};
+/** Partial update body for `PUT /pm/userstory/:id`. `updateVersion` is optimistic-concurrency: the
+ *  server bumps it on every write and rejects stale writes. Pass it back from the last `getStory`. */
+export type StoryUpdate = {
+    name?: string | undefined;
+    state?: string | undefined;
+    estimatedEffort?: number | undefined;
+    projectId?: number | undefined;
+    epicId?: number | undefined;
+    featureId?: number | undefined;
+    moduleId?: number | undefined;
+    releaseId?: number | undefined;
+    iterationId?: number | undefined;
+    acceptanceCriteria?: string | undefined;
+    description?: string | undefined;
+    priority?: string | undefined;
+    ownerId?: number[] | undefined;
+    tags?: number[] | undefined;
+    teamId?: number[] | undefined;
+    type?: string | undefined;
+    plannedStartDate?: string | undefined;
+    plannedEndDate?: string | undefined;
+    customFields?: Record<string, unknown> | undefined;
+    updateVersion?: number | undefined;
+};
+/** An EPIC (SimplifyQA `pm.epic`). Top of the backlog hierarchy: epic → feature → story. `key` is the
+ *  human business key (EP_XXX); `id` is the numeric doc id. */
+export type EpicSummary = {
+    id: string;
+    key?: string | undefined;
+    name: string;
+    state?: string | undefined;
+};
+export type Epic = EpicSummary & {
+    description?: string | undefined;
+    estimatedEffort?: number | undefined;
+    ownerId?: number | undefined;
+    plannedStartDate?: string | undefined;
+    plannedEndDate?: string | undefined;
+};
+export type EpicQuery = {
+    search?: string;
+    state?: string;
+    limit?: number;
+    offset?: number;
+    /** Numeric userId of the creator. Pass "me" and the adapter substitutes cfg.userId. */
+    createdBy?: string;
+    /** Numeric userId of the last updater. Pass "me" and the adapter substitutes cfg.userId. */
+    updatedBy?: string;
+    /** Numeric userId of the epic owner. Pass "me" and the adapter substitutes cfg.userId. */
+    ownerId?: string;
+};
+/** Fields accepted when CREATING an epic (`POST /pm/epic`). `projectIds` is filled to `[currentProject]`
+ *  when omitted; all six required fields (name/state/estimatedEffort/plannedStartDate/plannedEndDate/projectIds)
+ *  must be present before hitting the backend. */
+export type EpicInput = {
+    name: string;
+    state: string;
+    estimatedEffort: number;
+    plannedStartDate: string;
+    plannedEndDate: string;
+    projectIds?: number[] | undefined;
+    ownerId?: number | undefined;
+    description?: string | undefined;
+    tags?: string[] | undefined;
+    teamId?: number[] | undefined;
+    actualStartDate?: string | undefined;
+    actualEndDate?: string | undefined;
+    actualEffort?: number | undefined;
+    remainingEffort?: number | undefined;
+    plannedBudget?: number | undefined;
+    customFields?: Record<string, unknown> | undefined;
+};
+export type EpicUpdate = {
+    name?: string | undefined;
+    state?: string | undefined;
+    estimatedEffort?: number | undefined;
+    plannedStartDate?: string | undefined;
+    plannedEndDate?: string | undefined;
+    projectIds?: number[] | undefined;
+    ownerId?: number | undefined;
+    description?: string | undefined;
+    tags?: string[] | undefined;
+    teamId?: number[] | undefined;
+    actualStartDate?: string | undefined;
+    actualEndDate?: string | undefined;
+    actualEffort?: number | undefined;
+    remainingEffort?: number | undefined;
+    plannedBudget?: number | undefined;
+    customFields?: Record<string, unknown> | undefined;
+    updateVersion?: number | undefined;
+};
+/** A FEATURE (SimplifyQA `pm.feature`). Middle of the backlog hierarchy: epic → feature → story.
+ *  `key` = business key (FT_XXX). `epicId` links to the parent epic. */
+export type FeatureSummary = {
+    id: string;
+    key?: string | undefined;
+    name: string;
+    state?: string | undefined;
+    priority?: string | undefined;
+    epicId?: string | undefined;
+};
+export type Feature = FeatureSummary & {
+    description?: string | undefined;
+    estimatedEffort?: number | undefined;
+    ownerId?: number | undefined;
+    plannedStartDate?: string | undefined;
+    plannedEndDate?: string | undefined;
+};
+export type FeatureQuery = {
+    search?: string;
+    state?: string;
+    limit?: number;
+    offset?: number;
+    /** Filter features under a specific parent epic id. */
+    epicId?: string;
+    /** Numeric userId of the creator. Pass "me" and the adapter substitutes cfg.userId. */
+    createdBy?: string;
+    /** Numeric userId of the last updater. Pass "me" and the adapter substitutes cfg.userId. */
+    updatedBy?: string;
+    /** Numeric userId of the feature owner. Pass "me" and the adapter substitutes cfg.userId. */
+    ownerId?: string;
+};
+/** Fields accepted when CREATING a feature (`POST /pm/feature`). Same rules as EpicInput plus optional
+ *  `epicId` (parent). `state` is optional on the backend for features (unlike epic/story). */
+export type FeatureInput = {
+    name: string;
+    estimatedEffort: number;
+    plannedStartDate: string;
+    plannedEndDate: string;
+    projectIds?: number[] | undefined;
+    epicId?: number | undefined;
+    state?: string | undefined;
+    priority?: string | undefined;
+    ownerId?: number | undefined;
+    description?: string | undefined;
+    tags?: number[] | undefined;
+    teamId?: number[] | undefined;
+    actualStartDate?: string | undefined;
+    actualEndDate?: string | undefined;
+    actualEffort?: number | undefined;
+    remainingEffort?: number | undefined;
+    customFields?: Record<string, unknown> | undefined;
+};
+export type FeatureUpdate = {
+    name?: string | undefined;
+    estimatedEffort?: number | undefined;
+    plannedStartDate?: string | undefined;
+    plannedEndDate?: string | undefined;
+    projectIds?: number[] | undefined;
+    epicId?: number | undefined;
+    state?: string | undefined;
+    priority?: string | undefined;
+    ownerId?: number | undefined;
+    description?: string | undefined;
+    tags?: number[] | undefined;
+    teamId?: number[] | undefined;
+    actualStartDate?: string | undefined;
+    actualEndDate?: string | undefined;
+    actualEffort?: number | undefined;
+    remainingEffort?: number | undefined;
+    customFields?: Record<string, unknown> | undefined;
+    updateVersion?: number | undefined;
+};
+/** A RELEASE (SimplifyQA `pm.release`). `state` is the release state ("planned", "in-progress", ...). */
+export type ReleaseSummary = {
+    id: string;
+    name: string;
+    state?: string | undefined;
+    plannedStartDate?: string | undefined;
+    plannedEndDate?: string | undefined;
+};
+export type ReleaseQuery = {
+    scope: 'project' | 'all';
+};
+/** A SPRINT (SimplifyQA `pm.sprint`). `releaseId` links to the parent Release. */
+export type SprintSummary = {
+    id: string;
+    name: string;
+    releaseId?: string | undefined;
+    state?: string | undefined;
+    plannedStartDate?: string | undefined;
+    plannedEndDate?: string | undefined;
+};
+export type SprintQuery = {
+    releaseId?: string;
+};
+/** A MODULE / folder in the SimplifyQA test-case tree. `parentId` is absent on root nodes. */
+export type ModuleSummary = {
+    id: string;
+    name: string;
+    parentId?: string | undefined;
+};
+/** Full MODULE detail — `list_modules` returns only summary rows; `get_module` returns everything the
+ *  server persists (description, human-readable code, immediate children, project). */
+export type ModuleDetail = ModuleSummary & {
+    code?: string | undefined;
+    description?: string | undefined;
+    childIds?: number[] | undefined;
+    projectId?: string | undefined;
+    isRoot?: boolean | undefined;
+};
+/** Input to `createModule`. `isRoot:true` files under the project root (server strips `parentId`);
+ *  otherwise `parentId` must resolve to an existing module in the same project. */
+export type ModuleCreateInput = {
+    name: string;
+    projectId: string;
+    isRoot: boolean;
+    parentId?: string | undefined;
+    description?: string | undefined;
+};
+/** Per-id dependency footprint the PATCH /pm/module dry-run returns. Non-empty arrays block delete
+ *  until the referring rows are moved or removed. */
+export type ModuleDependency = {
+    id: number;
+    tcArr: number[];
+    fnArr: number[];
+    parameterArr: number[];
+    objArr: number[];
+    defectArr: number[];
+    usArr: number[];
+};
+/** Result of `deleteModule`. `dryRun:true` → nothing was deleted; `dependencies` names what still
+ *  references each id. `dryRun:false` → server actually deleted the ids with empty dependencies and
+ *  silently skipped the rest; `dependencies` still surfaces the skipped-with-refs list for the caller
+ *  to act on. */
+export type ModuleDeleteResult = {
+    dryRun: boolean;
+    dependencies: ModuleDependency[];
+};
+/** Input to `deleteVersion`. `kind` toggles the backend `parentType` ('TC'|'FN'); `versionId` is
+ *  the tcfn_version uuid (from `TestCase.versions[]` / `QaFunction.versions[]`); `versionName` is
+ *  required by the backend validator even though the delete match doesn't strictly need it. */
+export type VersionDeleteInput = {
+    kind: 'tc' | 'fn';
+    parentId: string;
+    versionId: string;
+    versionName: string;
+    confirm?: boolean;
+};
+/** TC-version dependency row — matches the payload SQA's dry-run returns for `parentType==='TC'`
+ *  (tcfnversion.service.js:219). Each `*Arr` maps projectId (as a string key) → array of referring
+ *  entity ids in that project. Empty maps mean "no refs of this kind". */
+export type TcVersionDep = {
+    id: number;
+    versionName?: string | undefined;
+    defectArr: Record<string, number[]>;
+    suiteArr: Record<string, number[]>;
+    epArr: Record<string, number[]>;
+    scenarioArr: Record<string, number[]>;
+    schedulerArr: Record<string, number[]>;
+    pipelineArr: Record<string, number[]>;
+    workflowArr: Record<string, number[]>;
+};
+/** FN-version dependency row — matches the payload SQA returns for `parentType==='FN'`
+ *  (tcfnversion.service.js:267). Same {projectId → ids} shape, narrower key set. */
+export type FnVersionDep = {
+    id: number;
+    tcArr: Record<string, number[]>;
+    fnArr: Record<string, number[]>;
+    wfArr: Record<string, number[]>;
+};
+/** Result of `deleteVersion`. Two-phase mirrors the backend contract (tcfnversion.service.js:30):
+ *  - `confirm:false` → `dryRun:true`, `dependencies` non-empty either way (each ref-array in the
+ *    dep row may be empty maps — a truly-safe delete is when EVERY *Arr is `{}`).
+ *  - `confirm:true` with empty deps → `dryRun:false`, `deleted:true`, `dependencies` empty.
+ *  - `confirm:true` with non-empty deps → SERVER REFUSED: `dryRun:false`, `deleted:false`,
+ *    `dependencies` populated. Caller must inspect the shape, not assume success from confirm:true. */
+export type VersionDeleteResult = {
+    dryRun: boolean;
+    deleted: boolean;
+    dependencies: Array<TcVersionDep | FnVersionDep>;
+    /** True when any dependency row still has a non-empty ref map. When `dryRun:true` this means
+     *  "delete would be refused"; when `dryRun:false` this means "server refused the delete". */
+    hasBlockers: boolean;
+};
+/** A reusable FUNCTION (SimplifyQA `tcfnObj` with type='FN'). Distinct from a TC: intended to be
+ *  called as a nested step from many test cases. `fnType` is the technology (WEB/API/ANDROID/IOS);
+ *  `executionType` is MANUAL/AUTOMATION; `status` is the review/approve status. */
+export type FunctionSummary = {
+    id: string;
+    code?: string;
+    name: string;
+    description?: string | undefined;
+    fnType?: string | undefined;
+    executionType?: string | undefined;
+    stepCount?: number | undefined;
+    status?: string | undefined;
+};
+export type QaFunction = {
+    id: string;
+    code?: string | undefined;
+    name: string;
+    description?: string | undefined;
+    fnType?: string | undefined;
+    executionType?: string | undefined;
+    status?: string | undefined;
+    stepCount?: number | undefined;
+    steps: Step[];
+    /** Present when the FN has versions (SQA always does). Newest first — same shape as `TestCase.versions`. */
+    versions?: TcVersion[] | undefined;
+};
+export type FunctionQuery = {
+    search?: string;
+    fnType?: string;
+    executionType?: string;
+    /** Filter to functions filed under this module (id or business key). */
+    moduleId?: string;
+    /** Numeric userId of the creator. Pass "me" and the adapter substitutes cfg.userId. */
+    createdBy?: string;
+    /** Numeric userId of the last updater. Pass "me" and the adapter substitutes cfg.userId. */
+    updatedBy?: string;
+    limit?: number;
+    offset?: number;
+};
+/** A USER row from `/pm/user/search` — the identity behind `createdBy` / `updatedBy` on stories &
+ *  testcases. Use `list_users` to resolve a name → id, then pass that id to `tc_list({createdBy})`. */
+export type UserSummary = {
+    id: string;
+    name?: string;
+    email?: string;
+    username?: string;
+    status?: string;
+};
+export type UserQuery = {
+    search?: string;
+    limit?: number;
+    offset?: number;
+    /** Restrict to users assigned to this project (via projectuserrole). Non-admin callers are
+     *  already scoped server-side to their accessible projects. */
+    projectId?: string;
 };
 export type QaObject = {
     id?: string;
@@ -122,8 +610,10 @@ export type QaObject = {
     locators: Locator[];
 };
 export type ObjectQuery = {
-    query: string;
+    query?: string;
     pageName?: string;
+    limit?: number;
+    offset?: number;
 };
 export type Suite = {
     id?: string;
@@ -134,10 +624,12 @@ export type Suite = {
         order: number;
     }[];
 };
+/** `suiteType` is SimplifyQA-only ("MANUAL" | "AUTOMATION"); absent on Walnut. */
 export type SuiteSummary = {
     id: string;
     name: string;
     memberCount?: number;
+    suiteType?: string | undefined;
 };
 export type MemberOp = {
     op: 'add' | 'remove' | 'reorder';
@@ -155,8 +647,15 @@ export type RunOptions = {
     /** Where to run: 'local' = the connected agent's own browser; 'cloud' = a cloud runner VM.
      *  The client MUST decide this (asking the user when unstated) — there is no safe default. */
     mode?: 'local' | 'cloud';
+    /** For mode:'local' — a specific local agent credential_id to dispatch to (resolved from
+     *  listLocalAgents). When omitted the adapter auto-picks the acting user's online agent. */
+    agentId?: string;
     /** For mode:'cloud' — the specific online cloud runner to dispatch to (resolved from listCloudRunners). */
     cloudRunnerId?: string;
+    /** REQUIRED for ANDROID/IOS test cases — the target device id (adb serial / emulator name for
+     *  LOCAL; cloud device name for CLOUD). Enumerate with `android_list_devices`. Ignored for
+     *  non-mobile tcTypes (WEB / API / MAINFRAME / etc.). */
+    deviceId?: string;
     /** SUITE runs only. Cloud dispatch order across the suite's test cases: 'serial' one-at-a-time,
      *  'batch'/'dynamic' concurrent (with maxConcurrent). Local is always serial. Default 'serial'. */
     strategy?: 'serial' | 'batch' | 'dynamic';
@@ -164,18 +663,121 @@ export type RunOptions = {
     maxConcurrent?: number;
     /** SUITE runs only — stop dispatching remaining test cases after the first failure. */
     terminateOnFailure?: boolean;
+    /** SimplifyQA project-management tag on the run. Optional — the UI's "Release" picker
+     *  (from `list_releases`). Sent as numeric `releaseId` on the exec payload; default 0. */
+    releaseId?: string;
+    /** SimplifyQA project-management tag on the run. Optional — the UI's "Sprint" picker
+     *  (from `list_sprints`). Sent as numeric `iterationId` on the exec payload; default 0. */
+    sprintId?: string;
+    /** Override the TC's currently-selected version for this run. Optional — the UI's
+     *  "Version" chip defaults to the TC's current; pass an id from the TC's `versions[]` to run
+     *  a different one. Omit to run the current version. */
+    versionId?: string;
 };
 export type RunRef = {
     runId: string;
 };
-/** A cloud runner VM registered to the project. `online` is the single flag the run flow gates on. */
+/** A cloud runner VM registered to the project. `online` is the single flag the run flow gates on.
+ *  `id` (compute_configs._id) drives an IMMEDIATE cloud reserve; `credentialId` (the linked
+ *  test_runner_vm agent credential) is what a SCHEDULE pins as assigned_agent_credential_id —
+ *  a different id-space from `id`. */
 export type CloudRunner = {
     id: string;
     name: string;
     online: boolean;
     status?: string;
     os?: string;
+    credentialId?: string;
+};
+/** A LOCAL Walnut agent registered to the project. `id` is the agent credential_id (what a LOCAL
+ *  run/schedule dispatches to). `online` gates whether it can take a run now. `owner` is the person
+ *  and `host` the machine hostname — shown together (like the product UI) so a user can tell apart
+ *  several agents owned by the same person (the credential_id alone means nothing to them). */
+export type LocalAgent = {
+    id: string;
+    name?: string;
+    online: boolean;
+    status?: string;
+    owner?: string;
+    host?: string;
 };
+/** Inputs to createSchedule (POST /api/schedules) — mirrors RunOptions' runner-pick fields plus the
+ *  schedule cadence. `mode` and `scheduledFor` are required (the backend rejects a schedule with no
+ *  start time). Manual test cases are not schedulable — the backend surfaces that error. */
+export type ScheduleOptions = {
+    /** Where the scheduled run executes: 'local' (a local agent) or 'cloud' (a cloud runner VM). */
+    mode: 'local' | 'cloud';
+    /** mode:'local' — REQUIRED: the specific local agent credential_id (from listLocalAgents) the
+     *  schedule fires on. A schedule runs detached from any live session (no "caller's own agent" at
+     *  fire time), so a local schedule must pin an agent — createSchedule sets execution_mode:'manual'
+     *  so the backend honors it. */
+    agentId?: string;
+    /** mode:'cloud' — the specific cloud runner id (compute_configs._id, from listCloudRunners), used
+     *  only to identify the runner. The actual SCHEDULE pin travels in cloudRunnerCredentialId. */
+    cloudRunnerId?: string;
+    /** mode:'cloud' — pin a SPECIFIC cloud runner by its agent CREDENTIAL id (CloudRunner.credentialId,
+     *  NOT cloudRunnerId). The backend validates it as an active test_runner_vm credential and rejects a
+     *  VM that is offline at create time; omit to let the backend auto-pick a live VM at fire time. */
+    cloudRunnerCredentialId?: string;
+    browser?: string;
+    /** Environment id (Mongo id); only forwarded when it is a 24-hex id, mirroring startRun. */
+    environmentId?: string;
+    /** Tag the scheduled run with a RELEASE (from list_releases). REQUIRED for suite schedules on
+     *  SimplifyQA — the UI marks Release with `*` when _parentComponent==='SU'. Sent as numeric
+     *  releaseId on the schedule payload. */
+    releaseId?: string;
+    /** Tag the scheduled run with a SPRINT (from list_sprints). REQUIRED for suite schedules on
+     *  SimplifyQA — mirrors the UI. SQA's underlying column is `iterationId`. */
+    sprintId?: string;
+    /** REQUIRED — ISO datetime of the first (or only) run. */
+    scheduledFor: string;
+    /** Recurrence cadence. Default 'once'. */
+    scheduleType?: 'once' | 'hourly' | 'daily' | 'weekdays' | 'weekly' | 'monthly';
+    /** ISO end date for recurring schedules. */
+    endDate?: string;
+    /** IANA timezone, default 'UTC'. */
+    timezone?: string;
+};
+/** Neutral reference to a created schedule (from POST /api/schedules `data`). */
+export type ScheduleRef = {
+    id: string;
+    status?: string;
+    nextRunAt?: string;
+    productUrl?: string;
+};
+/** A schedule as listed for management (GET /api/schedules). `target` names WHAT it runs (a test case
+ *  or a suite), `agent` is the pinned agent/runner's human name, and `updateVersion` is the optimistic-
+ *  concurrency token an edit must echo back. */
+export type ScheduleInfo = {
+    id: string;
+    target: string;
+    scheduleType: string;
+    status: string;
+    active?: boolean;
+    executionTarget?: 'local' | 'cloud_runner';
+    agent?: string;
+    browser?: string;
+    nextRunAt?: string;
+    scheduledFor?: string;
+    timezone?: string;
+    updateVersion?: number;
+};
+/** Fields an edit may change (schedule_update). Omitted = leave as-is. Mirrors updateScheduleSchema;
+ *  `mode:'local'` re-pins via agentId, `mode:'cloud'` via cloudRunnerCredentialId. */
+export type ScheduleUpdate = {
+    scheduledFor?: string;
+    scheduleType?: 'once' | 'hourly' | 'daily' | 'weekdays' | 'weekly' | 'monthly';
+    endDate?: string;
+    timezone?: string;
+    browser?: string;
+    environmentId?: string;
+    mode?: 'local' | 'cloud';
+    agentId?: string;
+    cloudRunnerCredentialId?: string;
+};
+/** State transitions for schedule_control. pause↔resume are reversible; cancel stops the pending/live
+ *  run; delete (a separate tool) removes the row entirely. */
+export type ScheduleAction = 'pause' | 'resume' | 'cancel';
 export type RunStatus = {
     runId: string;
     state: 'queued' | 'running' | 'passed' | 'failed' | 'stopped' | 'error';
@@ -213,14 +815,87 @@ export type ActionDef = {
 export type EnvInfo = {
     id: string;
     name: string;
+    key?: string;
+    isDefault?: boolean;
 };
 export type DatasetInfo = {
     id: string;
     name: string;
     rowCount?: number;
 };
+/** Template row for testdata generation. `parameters[i].paramId` is the backend id used when
+ *  posting new rows; `name` is the human-facing token (e.g. `${username}`); `seed` is the current
+ *  default value (empty string if unset) — used for regex-based type inference when no override is
+ *  supplied. `versionId`/`environmentType` are echoed back from the product so a follow-up
+ *  saveGeneratedIterations call targets the same TC context without a second lookup. */
+export type DefaultIteration = {
+    tcId: string;
+    versionId: string;
+    environmentType: string;
+    /** `seed` is already masked for a protected parameter ("*****" / "(empty)") — the real value
+     *  never leaves the adapter. */
+    parameters: Array<{
+        paramId: number;
+        name: string;
+        seed: string;
+        protected?: boolean | undefined;
+    }>;
+};
+/** Request body for `saveGeneratedIterations`. `rows[i]` is a flat `{paramName: value}` map; the
+ *  adapter re-keys it to `{paramId: value}` server-side using the template.
+ *  `formulas` — optional per-column formula assignments applied to EVERY row: the adapter evaluates
+ *  the formula fresh per row via the product's compute endpoint and stamps both `value` (evaluated)
+ *  and `formulaValue` (source `=NAME(...)` expression) on the payload cell. A formula wins over an
+ *  explicit `rows[i]` value for the same param name. */
+export type SaveGeneratedIterations = {
+    tcId: string;
+    versionId: string;
+    environmentType: string;
+    rows: Array<Record<string, string>>;
+    formulas?: Record<string, FormulaCall> | undefined;
+    /** Optional pre-fetched template parameters (from a getDefaultIteration the caller already made).
+     *  When present the adapter skips its own re-fetch — avoids paying the template + N parameter-name
+     *  lookups twice per save. Safe to omit; adapter falls back to fetching. */
+    parameters?: Array<{
+        paramId: number;
+        name: string;
+        seed: string;
+    }> | undefined;
+};
+/** A formula available in the project for testdata generation. `scope` is derived from the formula
+ *  document: 'default' = customer-wide prefab (FIRST_NAME, RANDOM_EMAIL, …); 'customer' = user-defined
+ *  formula visible across every project in the customer; 'project' = only in the current project.
+ *  `signature`/`example` come straight from the formula's stored description. `parameters` names the
+ *  argument keys (order matters: the adapter serialises calls positionally as `=NAME("a","b")`). */
+export type Formula = {
+    name: string;
+    uniqueId: string;
+    type: 'DEFAULT' | 'CUSTOM';
+    scope: 'default' | 'customer' | 'project';
+    signature: string;
+    details?: string | undefined;
+    example?: string | undefined;
+    parameters: Array<{
+        keyName: string;
+        description?: string | undefined;
+        dataType?: string | undefined;
+    }>;
+};
+/** A model-supplied call to a formula for one testdata column. `args` is name→value keyed by
+ *  `Formula.parameters[].keyName`; the adapter orders them positionally when building the stored
+ *  `formulaValue` expression, and passes them as query params to the compute endpoint. */
+export type FormulaCall = {
+    name: string;
+    args?: Record<string, string> | undefined;
+};
+export type SaveGeneratedIterationsResult = {
+    tcId: string;
+    inserted: number;
+    iterationIds?: string[];
+    datasetUrl?: string;
+};
 export type EntityRef = {
-    kind: 'testcase' | 'suite' | 'run';
+    kind: 'testcase' | 'suite' | 'run' | 'function';
     id: string;
 };
 /** The recording-JOURNAL view of a test case, for journal-first editing. `source:'journal'` = steps