@cspeach/cli 0.9.0 → 1.0.0

package/dist/tools/project/_merge-shared.js

@@ -0,0 +1,68 @@
+/**
+ * Shared input-resolution for the two merge tools (cca_merge,
+ * upgrade_merge_progress).
+ *
+ * Inputs arrive as the same `@<token>` forms the rest of the CLI uses
+ * (workspace.ts:resolveAtToken): absolute path, relative path, or a bare
+ * workspace-filename fragment. A leading '@' is stripped — skills pass
+ * the user's `--inputs @file` tokens through verbatim.
+ *
+ * Absolute / relative paths are resolved WITHOUT touching the workspace
+ * (no ensureWorkspace side effects from a tool call); only bare tokens
+ * trigger the workspace lookup.
+ */
+import { basename, isAbsolute, join } from 'node:path';
+import { readProjectFile } from '../../projects/status.js';
+import { resolveAtTokenAsync, formatProjectFileList } from '../../projects/workspace.js';
+export function labelFor(path) {
+    return basename(path).replace(/\.cspeach\.json$/i, '');
+}
+/**
+ * Resolve one `@<token>` to an absolute path. Throws with a
+ * user-presentable message on ambiguity / not-found.
+ */
+export async function resolveEnvelopeToken(rawToken, cwd) {
+    const token = rawToken.startsWith('@') ? rawToken.slice(1) : rawToken;
+    if (token.length === 0)
+        throw new Error('empty input token');
+    if (isAbsolute(token))
+        return token;
+    if (token.includes('/') || token.includes('\\'))
+        return join(cwd, token);
+    const resolved = await resolveAtTokenAsync(token, cwd);
+    if (resolved.kind === 'path')
+        return resolved.path;
+    if (resolved.kind === 'ambiguous') {
+        throw new Error(`'@${token}' matches multiple workspace files — be more specific:\n`
+            + formatProjectFileList(resolved.matches, '(workspace)'));
+    }
+    throw new Error(`'@${token}' matches no file in the workspace (${resolved.workspace})`);
+}
+/**
+ * Resolve + read + type-check one envelope input. readProjectFile
+ * already validates the envelope schema and throws readable errors.
+ */
+export async function loadEnvelope(rawToken, cwd, expectedType) {
+    const path = await resolveEnvelopeToken(rawToken, cwd);
+    let envelope;
+    try {
+        envelope = readProjectFile(path);
+    }
+    catch (e) {
+        throw new Error(`cannot read '${rawToken}': ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (envelope.artefactType !== expectedType) {
+        throw new Error(`'${rawToken}' is a '${envelope.artefactType}' envelope — this merge needs '${expectedType}' inputs.`);
+    }
+    return { path, label: labelFor(path), envelope };
+}
+/**
+ * The presentation contract returned to the model alongside the merged
+ * numbers. Keeping the model away from arithmetic is the whole point
+ * (battery S4 defects D6/D7) — it presents, it does not recompute.
+ */
+export const MANIFEST_PASTE_INSTRUCTIONS = 'Present merged_summary, per_input and warnings to the user with your own judgment commentary '
+    + '(conflict arbitration advice, next steps). Then paste manifest_block VERBATIM — unchanged, '
+    + 'byte for byte — as the LAST block of your reply so the CLI save hook can persist the merged '
+    + 'envelope. Do NOT recompute, reformat, re-sort, or edit any number or row in the block: the '
+    + 'extractor re-validates counts against rows on save and a hand-edited block fails loudly.';

package/dist/tools/project/cca_merge.js

@@ -0,0 +1,164 @@
+/**
+ * cca_merge — deterministic reconciliation of N parallel /abap-cca
+ * assessment envelopes (the /abap-cca-merge skill's execution seam).
+ *
+ * DESIGN (2026-06-12, team-chain): the skill used to ask the MODEL to
+ * reconcile envelopes by hand; battery S4 (D6/D7) proved models can't
+ * keep counts consistent with rows. This tool runs
+ * src/projects/merge-cca.ts and returns the merged content, warnings,
+ * AND a pre-rendered manifest block the model pastes VERBATIM. The
+ * normal save hook then persists the envelope — persistence
+ * deliberately stays on the one existing save path (confirm prompt,
+ * workspace resolution, validation, version semantics) instead of the
+ * tool minting envelopes through a second door. A merge is a NEW
+ * artefact superseding its inputs (new identity is correct — there is
+ * no prior chain to extend, unlike the plan-revision case in
+ * save-command.ts), and the extractor's counts-vs-rows validation acts
+ * as a tamper backstop if the model edits the pasted block.
+ *
+ * NOT flag-gated: the abap-cca-merge skill depends on this tool; gating
+ * it off would silently break the multi-consultant chain.
+ *
+ * Stays isMutating: false despite writing the merged detail file: the
+ * write is the merge's own local artifact under .cspeach/ (derived
+ * purely from envelopes the user supplied), the same trust level as the
+ * save hook persisting the envelope — no SAP or user-file mutation.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join } from 'node:path';
+import { registerTool } from '../index.js';
+import { mergeCcaAssessments, renderCcaMergeManifest, } from '../../projects/merge-cca.js';
+import { loadEnvelope, MANIFEST_PASTE_INSTRUCTIONS } from './_merge-shared.js';
+export async function ccaMergeHandler(args, ctx) {
+    if (!Array.isArray(args.inputs) || args.inputs.some((i) => typeof i !== 'string')) {
+        return { content: 'error: inputs must be an array of envelope paths / @-tokens.', is_error: true };
+    }
+    const tokens = args.inputs;
+    if (tokens.length === 1) {
+        return {
+            content: 'error: only one input supplied — a single assessment needs no merge. Use the file directly.',
+            is_error: true,
+        };
+    }
+    if (tokens.length < 2) {
+        return { content: 'error: at least 2 input envelopes are required.', is_error: true };
+    }
+    if (args.allow_cross_project !== undefined && typeof args.allow_cross_project !== 'boolean') {
+        return { content: 'error: allow_cross_project must be a boolean.', is_error: true };
+    }
+    // load + type-check every input before merging — fail with the precise file
+    const inputs = [];
+    const perInput = [];
+    for (const token of tokens) {
+        let resolved;
+        try {
+            resolved = await loadEnvelope(token, ctx.cwd, 'cca-assessment');
+        }
+        catch (e) {
+            return { content: `error: ${e instanceof Error ? e.message : String(e)}`, is_error: true };
+        }
+        const content = resolved.envelope.content;
+        inputs.push({ label: resolved.label, content });
+        perInput.push({
+            file: resolved.path,
+            label: resolved.label,
+            project_id: content.projectId,
+            scope: content.scope,
+            total_objects: content.summary.totalObjects,
+            keep: content.summary.keep,
+            fix: content.summary.fix,
+            retire: content.summary.retire,
+            redesign: content.summary.redesign,
+            uncategorized: content.summary.uncategorized,
+            truncated: content.classificationsTruncated === true,
+        });
+    }
+    let merged;
+    let warnings;
+    try {
+        ({ merged, warnings } = mergeCcaAssessments(inputs, {
+            allowCrossProject: args.allow_cross_project === true,
+        }));
+    }
+    catch (e) {
+        return { content: `error: ${e instanceof Error ? e.message : String(e)}`, is_error: true };
+    }
+    const title = `${inputs[0].content.projectId} — Merged (${inputs.length} slices)`;
+    // ── write the merged detail file BEFORE emitting the manifest ──────────
+    // The manifest's detail_path must point at a REAL file (the rule this
+    // branch added for /abap-cca emitters applies to the merge too). The
+    // manifest table caps at 50 rows; this file always carries every merged
+    // row. Minimal documented shape (a merge supersedes its inputs, so this
+    // is a fresh consolidated detail, not a phase-state project.json):
+    //   {
+    //     generatedAt:  ISO timestamp of the merge
+    //     projectId / scope / atcVariant / summary: as in the manifest
+    //     objects:      ALL merged classification rows (uncapped)
+    //     mergedFrom:   the input envelopes [{ file, label }]
+    //   }
+    let detailWritten = true;
+    const detailAbs = isAbsolute(merged.detailPath) ? merged.detailPath : join(ctx.cwd, merged.detailPath);
+    try {
+        mkdirSync(dirname(detailAbs), { recursive: true });
+        writeFileSync(detailAbs, JSON.stringify({
+            generatedAt: new Date().toISOString(),
+            projectId: merged.projectId,
+            scope: merged.scope,
+            atcVariant: merged.atcVariant,
+            summary: merged.summary,
+            objects: merged.classifications,
+            mergedFrom: perInput.map((p) => ({ file: p.file, label: p.label })),
+        }, null, 2), 'utf8');
+    }
+    catch (e) {
+        detailWritten = false;
+        warnings.push(`DETAIL WRITE FAILED: could not write the merged detail file '${merged.detailPath}' `
+            + `(${e instanceof Error ? e.message : String(e)}). The manifest block omits detail_path — `
+            + `a manifest must never point at a file that does not exist — so the save will refuse it. `
+            + `Fix the path/permissions and re-run the merge.`);
+    }
+    const manifestBlock = renderCcaMergeManifest(merged, title, { omitDetailPath: !detailWritten });
+    return {
+        content: JSON.stringify({
+            merged_summary: merged.summary,
+            merged_project_id: merged.projectId,
+            merged_scope: merged.scope,
+            atc_variant: merged.atcVariant,
+            ...(detailWritten ? { detail_path: merged.detailPath } : {}),
+            per_input: perInput,
+            warnings,
+            // full merged rows — the manifest block caps at 50; nothing is lost
+            // from the transcript even for large estates.
+            merged_classifications: merged.classifications,
+            manifest_block: manifestBlock,
+            instructions: MANIFEST_PASTE_INSTRUCTIONS,
+        }, null, 2),
+    };
+}
+registerTool({
+    name: 'cca_merge',
+    description: 'Deterministically merge 2+ parallel /abap-cca assessment envelopes (.cspeach.json) into one consolidated '
+        + 'cca-assessment. Validates project identity and ATC variant, detects scope overlaps and classification '
+        + 'conflicts (most-restrictive wins: retire > redesign > fix > keep), recomputes all counts from the merged '
+        + 'rows, writes the full merged rows to a new detail file under .cspeach/cca/projects/, and returns warnings '
+        + 'plus a ready-made csforge:cca-manifest block to paste verbatim. '
+        + 'Inputs accept absolute/relative paths or bare workspace @-tokens.',
+    isMutating: false,
+    category: 'project',
+    input_schema: {
+        type: 'object',
+        properties: {
+            inputs: {
+                type: 'array',
+                items: { type: 'string' },
+                description: '2+ cca-assessment envelope references (path or @-token), one per consultant slice.',
+            },
+            allow_cross_project: {
+                type: 'boolean',
+                description: 'Accept inputs with different projectId (disjoint --scope slices of the same system). Default false.',
+            },
+        },
+        required: ['inputs'],
+    },
+    handler: (args, ctx) => ccaMergeHandler(args, ctx),
+});

package/dist/tools/project/playbook_get.js

@@ -4,7 +4,7 @@
  * Fetches a SKILL.md body via ctx.skillSource (the managed / manifest /
  * bundled SkillSource abstraction the agent loop already uses). Lets the
  * agent inspect another skill's playbook for orchestration patterns
- * (e.g. /abap-incident calling /abap-dump-analyze inline) without
+ * (e.g. /abap-incident calling /abap-dump inline) without
  * triggering a full skill dispatch.
  *
  * Caching: in-process Map-based LRU. Keyed by validated skill name.

package/dist/tools/project/upgrade_merge_progress.js

@@ -0,0 +1,206 @@
+/**
+ * upgrade_merge_progress — deterministic reconciliation of N parallel
+ * /abap-upgrade-fix progress envelopes (the /abap-upgrade-merge skill's
+ * execution seam). See cca_merge.ts for the design rationale: the tool
+ * does the arithmetic (battery S4 D6/D7), the model presents; the
+ * pre-rendered manifest block is pasted verbatim and persisted by the
+ * normal save hook.
+ *
+ * Baseline discipline:
+ *   - every input's baselineRef.sha256 must match the merge baseline —
+ *     HARD ERROR otherwise.
+ *   - `baseline` arg (recommended): the originating upgrade-scan
+ *     envelope. The tool hashes the scan's detail file (that is what
+ *     baseline_sha256 refers to, per the upgrade-fix manifest contract)
+ *     and uses the scan's findings to fill never-touched findings as
+ *     'pending', so the merged view covers the whole baseline.
+ *   - without `baseline`, the first input's baselineRef is taken as
+ *     truth and the others are checked against it; untouched baseline
+ *     findings cannot be filled in (warned).
+ *
+ * NOT flag-gated: the abap-upgrade-merge skill depends on this tool.
+ *
+ * Stays isMutating: false despite writing the merged detail file: the
+ * write is the merge's own local artifact under .cspeach/ (derived
+ * purely from envelopes the user supplied), the same trust level as the
+ * save hook persisting the envelope — no SAP or user-file mutation.
+ */
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join } from 'node:path';
+import { registerTool } from '../index.js';
+import { mergeUpgradeProgress, renderUpgradeMergeManifest, } from '../../projects/merge-upgrade.js';
+import { loadEnvelope, MANIFEST_PASTE_INSTRUCTIONS } from './_merge-shared.js';
+function sha256OfFile(path) {
+    return createHash('sha256').update(readFileSync(path)).digest('hex');
+}
+export async function upgradeMergeProgressHandler(args, ctx) {
+    if (!Array.isArray(args.inputs) || args.inputs.some((i) => typeof i !== 'string')) {
+        return { content: 'error: inputs must be an array of envelope paths / @-tokens.', is_error: true };
+    }
+    const tokens = args.inputs;
+    if (tokens.length === 1) {
+        return {
+            content: 'error: only one input supplied — a single progress file needs no merge. Use the file directly.',
+            is_error: true,
+        };
+    }
+    if (tokens.length < 2) {
+        return { content: 'error: at least 2 input envelopes are required.', is_error: true };
+    }
+    if (args.baseline !== undefined && typeof args.baseline !== 'string') {
+        return { content: 'error: baseline must be a string (upgrade-scan envelope path / @-token).', is_error: true };
+    }
+    const inputs = [];
+    const perInput = [];
+    for (const token of tokens) {
+        let resolved;
+        try {
+            resolved = await loadEnvelope(token, ctx.cwd, 'upgrade-progress');
+        }
+        catch (e) {
+            return { content: `error: ${e instanceof Error ? e.message : String(e)}`, is_error: true };
+        }
+        const content = resolved.envelope.content;
+        inputs.push({ label: resolved.label, content });
+        perInput.push({
+            file: resolved.path,
+            label: resolved.label,
+            baseline_sha256: content.baselineRef.sha256,
+            transport: content.transport,
+            fixed: content.summary.fixed,
+            skipped: content.summary.skipped,
+            failed: content.summary.failed,
+            pending: content.summary.pending,
+        });
+    }
+    const extraWarnings = [];
+    let baseline;
+    let title;
+    if (typeof args.baseline === 'string') {
+        let scan;
+        try {
+            scan = await loadEnvelope(args.baseline, ctx.cwd, 'upgrade-scan');
+        }
+        catch (e) {
+            return { content: `error: ${e instanceof Error ? e.message : String(e)}`, is_error: true };
+        }
+        const scanContent = scan.envelope.content;
+        // baseline_sha256 is the sha256 of the baseline DETAIL JSON body (the
+        // upgrade-fix manifest contract), not of the envelope.
+        const detailAbs = isAbsolute(scanContent.detailPath)
+            ? scanContent.detailPath
+            : join(ctx.cwd, scanContent.detailPath);
+        let sha256;
+        try {
+            sha256 = sha256OfFile(detailAbs);
+        }
+        catch (e) {
+            return {
+                content: `error: cannot hash baseline detail file '${scanContent.detailPath}' (resolved: ${detailAbs}): `
+                    + `${e instanceof Error ? e.message : String(e)}. The merge needs the scan's detail JSON on this machine.`,
+                is_error: true,
+            };
+        }
+        baseline = {
+            sha256,
+            path: scanContent.detailPath,
+            title: scan.envelope.title,
+            findings: scanContent.findings.map((f) => ({ id: f.id, objectName: f.objectName, finding: f.rule })),
+        };
+        title = `${scan.envelope.title} — Merged (${inputs.length} slices)`;
+        if (scanContent.findingsTruncated) {
+            extraWarnings.push(`TRUNCATED BASELINE: the scan manifest carries only ${scanContent.findingsShown ?? scanContent.findings.length} `
+                + `of ${scanContent.summary.total} findings — pending-fill covers the manifest rows only.`);
+        }
+    }
+    else {
+        const ref = inputs[0].content.baselineRef;
+        baseline = { sha256: ref.sha256, path: ref.path };
+        title = `${ref.path.split(/[\\\/]/).pop() ?? 'baseline'} — Merged (${inputs.length} slices)`;
+        extraWarnings.push('NO EXPLICIT BASELINE: consistency was checked against the first input\'s baselineRef. '
+            + 'Findings untouched by every slice are NOT filled as pending — pass the upgrade-scan envelope '
+            + 'as `baseline` for full-baseline coverage.');
+    }
+    let merged;
+    let warnings;
+    try {
+        ({ merged, warnings } = mergeUpgradeProgress(inputs, baseline));
+    }
+    catch (e) {
+        return { content: `error: ${e instanceof Error ? e.message : String(e)}`, is_error: true };
+    }
+    warnings = [...extraWarnings, ...warnings];
+    // ── write the merged detail file BEFORE emitting the manifest ──────────
+    // The manifest's detail_path must point at a REAL file. Minimal
+    // documented shape (full merged rows, never capped):
+    //   {
+    //     generatedAt: ISO timestamp of the merge
+    //     baseline / transport / summary: as in the manifest
+    //     fixes:      ALL merged per-finding rows
+    //     mergedFrom: the input envelopes [{ file, label }]
+    //   }
+    let detailWritten = true;
+    const mergedDetailAbs = isAbsolute(merged.detailPath) ? merged.detailPath : join(ctx.cwd, merged.detailPath);
+    try {
+        mkdirSync(dirname(mergedDetailAbs), { recursive: true });
+        writeFileSync(mergedDetailAbs, JSON.stringify({
+            generatedAt: new Date().toISOString(),
+            baseline: { path: merged.baselineRef.path, sha256: merged.baselineRef.sha256 },
+            transport: merged.transport,
+            summary: merged.summary,
+            fixes: merged.fixes,
+            mergedFrom: perInput.map((p) => ({ file: p.file, label: p.label })),
+        }, null, 2), 'utf8');
+    }
+    catch (e) {
+        detailWritten = false;
+        warnings.push(`DETAIL WRITE FAILED: could not write the merged detail file '${merged.detailPath}' `
+            + `(${e instanceof Error ? e.message : String(e)}). The manifest block omits detail_path — `
+            + `a manifest must never point at a file that does not exist — so the save will refuse it. `
+            + `Fix the path/permissions and re-run the merge.`);
+    }
+    const manifestBlock = renderUpgradeMergeManifest(merged, title, { omitDetailPath: !detailWritten });
+    return {
+        content: JSON.stringify({
+            merged_summary: merged.summary,
+            baseline: { path: merged.baselineRef.path, sha256: merged.baselineRef.sha256 },
+            transport: merged.transport,
+            ...(detailWritten ? { detail_path: merged.detailPath } : {}),
+            per_input: perInput,
+            warnings,
+            merged_fixes: merged.fixes,
+            manifest_block: manifestBlock,
+            instructions: MANIFEST_PASTE_INSTRUCTIONS,
+        }, null, 2),
+    };
+}
+registerTool({
+    name: 'upgrade_merge_progress',
+    description: 'Deterministically merge 2+ parallel /abap-upgrade-fix progress envelopes (.cspeach.json) into one consolidated '
+        + 'upgrade-progress. Hard-errors on baseline_sha256 mismatch, reconciles per-finding status '
+        + '(failed > fixed > skipped > pending), warns on double-fixes, recomputes all counts from the merged rows, '
+        + 'writes the full merged rows to a new detail file under .cspeach/upgrades/, '
+        + 'and returns warnings plus a ready-made csforge:upgrade-manifest block to paste verbatim. '
+        + 'Pass the originating upgrade-scan envelope as `baseline` (recommended) to fill never-touched findings as pending. '
+        + 'Inputs accept absolute/relative paths or bare workspace @-tokens.',
+    isMutating: false,
+    category: 'project',
+    input_schema: {
+        type: 'object',
+        properties: {
+            inputs: {
+                type: 'array',
+                items: { type: 'string' },
+                description: '2+ upgrade-progress envelope references (path or @-token), one per developer slice.',
+            },
+            baseline: {
+                type: 'string',
+                description: 'Optional but recommended: the originating upgrade-scan envelope (path or @-token). '
+                    + 'Used to verify baseline integrity from source and to fill untouched findings as pending.',
+            },
+        },
+        required: ['inputs'],
+    },
+    handler: (args, ctx) => upgradeMergeProgressHandler(args, ctx),
+});

package/dist/tools/sap-read.js

@@ -7,7 +7,7 @@
  *   searchObject(query, objType?, maxResults?)
  *   changeLog(type, name)
  *   sqlQuery(query, maxRows?, extraBlocked?)
- *   shortDump(dumpId?, user?)
+ *   shortDump(dumpId?, user?, fromDate?, toDate?)
  *   atcRun(type, name, variant?)
  *   usageReferences(objectType, objectName)
  *   apiState(objects)
@@ -167,7 +167,9 @@ registerTool({
 // -----------------------------------------------------------------------
 registerTool({
     name: 'sap_sql_query',
-    description: 'Execute a read-only SQL SELECT against the SAP database via ADT Data Preview. Security-sensitive tables are blocked automatically.',
+    description: 'Execute a read-only SQL SELECT against the SAP database via ADT Data Preview. Security-sensitive tables are blocked automatically. '
+        + 'Dialect limits (violations return an opaque "SAP HTTP 400: sqlQuery"): no IN-lists and at most one LIKE per WHERE clause '
+        + '(multi-OR LIKE chains are rejected) — use a single LIKE or split into separate queries.',
     isMutating: false,
     input_schema: {
         type: 'object',
@@ -187,7 +189,10 @@ registerTool({
 // -----------------------------------------------------------------------
 registerTool({
     name: 'sap_short_dump',
-    description: 'Read ABAP runtime errors (short dumps / ST22). Without dumpId returns a list of recent dumps; with dumpId returns the full diagnostic detail.',
+    description: 'Read ABAP runtime errors (short dumps / ST22). Without dumpId returns dumps from a '
+        + 'time window (default: the last 24h of SAP SYSTEM time), paginated server-side; the '
+        + 'result includes a `coverage` line stating exactly which window was fetched — trust it '
+        + 'over assumptions. With dumpId returns the full diagnostic detail.',
     isMutating: false,
     input_schema: {
         type: 'object',
@@ -198,13 +203,43 @@ registerTool({
             },
             user: {
                 type: 'string',
-                description: 'Filter dumps by SAP username (list mode only)',
+                description: 'Filter dumps by SAP username (list mode only, applied after the windowed fetch)',
+            },
+            fromDate: {
+                type: 'string',
+                description: 'Window start (list mode). Zone-less values are SAP SYSTEM time: "YYYYMMDDHHMMSS", '
+                    + '"YYYY-MM-DD" (day start) or "2026-06-11T06:00:00". ISO-8601 with timezone '
+                    + '("2026-06-11T06:00:00Z") is an absolute instant, auto-translated to system time. '
+                    + 'Default: now − 24h (or 24h before an explicit toDate).',
+            },
+            toDate: {
+                type: 'string',
+                description: 'Window end (list mode). Same formats as fromDate ("YYYY-MM-DD" = day end). '
+                    + 'Default: now (SAP system time).',
             },
         },
         required: [],
     },
     handler: async (args, ctx) => {
-        const result = await ctx.adt.shortDump(args.dumpId, args.user);
+        const result = await ctx.adt.shortDump(args.dumpId, args.user, args.fromDate, args.toDate);
+        // List mode: lead with a coverage line so the model KNOWS what slice of
+        // time it is looking at (battery D18 — the old list was the feed's
+        // arbitrary first page and the newest dumps were routinely missing).
+        if (result.operation === 'list' && result.window) {
+            const w = result.window;
+            let coverage = `showing ${result.count} dump(s) from window ${w.windowFromSap}–${w.windowToSap} `
+                + `(SAP system time${w.windowFromUtc ? `; UTC ${w.windowFromUtc}–${w.windowToUtc}` : ''}); `
+                + `${w.totalFetched} in window before filters; ${w.pagesFetched} page(s) fetched`;
+            if (w.clockProbe === 'failed') {
+                coverage +=
+                    '; WARNING: system clock probe failed — window widened by ±1 day, timestamps are approximate';
+            }
+            if (w.capped) {
+                coverage +=
+                    '; WARNING: page cap hit — window NOT fully covered, narrow fromDate/toDate to see the rest';
+            }
+            return { content: JSON.stringify({ coverage, ...result }, null, 2) };
+        }
         return { content: JSON.stringify(result, null, 2) };
     },
 });
@@ -448,18 +483,27 @@ registerTool({
 // -----------------------------------------------------------------------
 registerTool({
     name: 'sap_odata_test',
-    description: 'Test an OData service endpoint by issuing a GET or HEAD request and returning the HTTP status and response body.',
+    description: 'Test an OData service endpoint (V2 or V4). Fetches $metadata or reads an entity set and returns the real HTTP status, the request URL/Accept actually used, and the response body. Works on draft-enabled OData V4 RAP services: V4 is auto-detected from /odata4/ paths, $metadata gets an XML Accept, and data reads use a JSON Accept without the V2-only $format option. System query options ($metadata, $top, $filter, $select, $expand, $count) are preserved literally.',
     isMutating: false,
     input_schema: {
         type: 'object',
         properties: {
             servicePath: {
                 type: 'string',
-                description: 'Full service path, e.g. /sap/opu/odata/sap/ZSALESORDER_SD_SRV',
+                description: 'Full service path. V2 e.g. /sap/opu/odata/sap/ZSALESORDER_SD_SRV; V4 e.g. /sap/opu/odata4/sap/zui_x_o4/srvd/sap/zui_x/0001',
             },
             entity: {
                 type: 'string',
-                description: 'Optional entity set name to append, e.g. SalesOrder',
+                description: 'Optional entity set name to append and read, e.g. SalesOrder',
+            },
+            query: {
+                type: 'string',
+                description: 'Optional raw OData query/resource. Pass "$metadata" to fetch the metadata document, or query options like "$top=5&$filter=Status eq \'OPEN\'". $ signs are preserved as-is. Overrides the default $top=5 when an entity is given.',
+            },
+            version: {
+                type: 'string',
+                enum: ['v2', 'v4'],
+                description: 'OData version override. Normally auto-detected (/odata4/ ⇒ v4, else v2). Set this only when the path does not reveal the version.',
             },
             method: {
                 type: 'string',
@@ -470,7 +514,7 @@ registerTool({
         required: ['servicePath'],
     },
     handler: async (args, ctx) => {
-        const result = await ctx.adt.odataTest(args.servicePath, args.entity, args.method ?? 'GET');
+        const result = await ctx.adt.odataTest(args.servicePath, args.entity, args.method ?? 'GET', { query: args.query, version: args.version });
         return { content: JSON.stringify(result, null, 2) };
     },
 });