@pmoses-s1/s1-secops-mcp 1.3.2 → 1.3.4

package/lib/sdl.js

@@ -26,6 +26,48 @@ export function sdlToken() {
   return token;
 }
 
+/**
+ * Resolve the S1-Scope header value for a request.
+ *
+ * SDL objects (dashboards, saved searches, config files) are filed against the
+ * scope the request carries, and reads are filtered by it. Verified live on
+ * usea1-purple 2026-08-17, same token: `configFiles` returned 113 files at
+ * account scope (20 of them dashboards) and 4 at a site scope (all 4
+ * dashboards). A dashboard created at site scope is invisible to an
+ * account-scoped listing, so a missing header is not a neutral default, it
+ * silently changes which objects exist as far as the caller can tell.
+ *
+ * Precedence: explicit per-call scope, then S1_SCOPE from credentials. Passing
+ * `null` is NOT the same as omitting: `null` deliberately suppresses the creds
+ * default and sends no header, which is what the account-wide listing needs.
+ *
+ * Format: "<accountId>" for account scope, "<accountId>:<siteId>" for site
+ * scope. Group scope does not exist in SDL; the console silently promotes a
+ * Group selection to the Site above it.
+ */
+function resolveScope(scope) {
+  if (scope === null) return null;
+  const raw = scope !== undefined ? scope : getCreds().S1_SCOPE;
+  if (raw === undefined || raw === null || raw === '') return null;
+  if (typeof raw !== 'string') {
+    throw new Error(`S1-Scope must be a string, got ${typeof raw}. Use "<accountId>" or "<accountId>:<siteId>".`);
+  }
+  const trimmed = raw.trim();
+  if (!/^\d+(:\d+)?$/.test(trimmed)) {
+    throw new Error(
+      `Invalid S1-Scope ${JSON.stringify(trimmed)}. Expected "<accountId>" or "<accountId>:<siteId>", ` +
+      'both numeric ids. Get them from GET /web/api/v2.1/accounts and /web/api/v2.1/sites.'
+    );
+  }
+  return trimmed;
+}
+
+/** Header object carrying S1-Scope, or empty when the request is unscoped. */
+function scopeHeaders(scope) {
+  const resolved = resolveScope(scope);
+  return resolved ? { 'S1-Scope': resolved } : {};
+}
+
 function sleep(ms) { return new Promise(r => setTimeout(r, ms)); }
 
 function retryAfterMs(res, fallback) {
@@ -133,6 +175,17 @@ async function sdlFetch(method, path, { body, extraHeaders = {}, rawBody = null,
 // dashboard by udoId. Skipping that rule is how one tenant accumulated 152
 // copies of `/dashboards/AI Usage`.
 
+/** Marks an error as originating from the GraphQL layer rather than the
+ *  transport. Absence detection keys off this: a 404 page whose body contains
+ *  "not found" must never be read as "the file does not exist". */
+class SdlGraphqlError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'SdlGraphqlError';
+    this.graphql = true;
+  }
+}
+
 /**
  * POST /sdl/v2/graphql. Returns `data`; throws on the GraphQL `errors` array.
  *
@@ -149,14 +202,15 @@ async function sdlFetch(method, path, { body, extraHeaders = {}, rawBody = null,
  *   3. Return a payload carrying neither `data` nor `errors`.
  *
  * `readOnly` opts into status-based retry; only pass it for queries.
+ * `scope` sets the S1-Scope header; see resolveScope for precedence.
  */
-async function sdlGraphql(opname, query, variables, { readOnly = false } = {}) {
+async function sdlGraphql(opname, query, variables, { readOnly = false, scope } = {}) {
   const body = { query };
   if (variables) body.variables = variables;
   const payload = await sdlFetch(
     'POST',
     `/v2/graphql?opname=${encodeURIComponent(opname)}`,
-    { body, allowRetry: readOnly }
+    { body, allowRetry: readOnly, extraHeaders: scopeHeaders(scope) }
   );
 
   if (typeof payload !== 'object' || payload === null) {
@@ -170,10 +224,10 @@ async function sdlGraphql(opname, query, variables, { readOnly = false } = {}) {
     const errs = Array.isArray(payload.errors) ? payload.errors : [payload.errors];
     const correlationId = payload.extensions?.correlationId ?? errs[0]?.extensions?.correlationId;
     const msg = errs[0]?.message || 'unknown GraphQL error';
-    throw new Error(`SDL GraphQL ${opname} → ${msg}${correlationId ? ` (correlationId=${correlationId})` : ''}`);
+    throw new SdlGraphqlError(`SDL GraphQL ${opname} → ${msg}${correlationId ? ` (correlationId=${correlationId})` : ''}`);
   }
   if (!('data' in payload)) {
-    throw new Error(`SDL GraphQL ${opname}: response carried neither data nor errors.`);
+    throw new SdlGraphqlError(`SDL GraphQL ${opname}: response carried neither data nor errors.`);
   }
   return payload.data;
 }
@@ -191,24 +245,84 @@ function assertSafeUdoId(udoId) {
 
 const CONFIG_FIELDS = 'udoId name readOnly version';
 
-/** Every config file on the tenant, including udoId-addressed dashboards. */
-export async function configFiles() {
+/** SDL config names are case-insensitive and tolerate stray whitespace, so the
+ *  absence check and the duplicate guard must normalise identically. */
+function normaliseName(n) {
+  return String(n ?? '').trim().toLowerCase();
+}
+function matchesName(file, name) {
+  return normaliseName(file?.name) === normaliseName(name);
+}
+
+/** Every config file visible at `scope`, including udoId-addressed dashboards.
+ *  This listing IS scope-filtered: a site-scoped dashboard does not appear in an
+ *  account-scoped listing and vice versa. */
+export async function configFiles({ scope } = {}) {
   const data = await sdlGraphql(
     'getConfigurationFiles',
     `query getConfigurationFiles { configFiles { ${CONFIG_FIELDS} } }`,
     undefined,
-    { readOnly: true }
+    { readOnly: true, scope }
   );
   return data?.configFiles ?? [];
 }
 
-/** Read one config file by name (plain files) or udoId (dashboards). */
-export async function configFile({ name, udoId }) {
+/**
+ * Read one config file by name (plain files) or udoId (dashboards).
+ * Returns null when the file does not exist.
+ *
+ * Absence is a normal outcome of a lookup, but the server reports it as a
+ * GraphQL error, and the message differs by address form (verified live):
+ *
+ *   by name : "Config file with name /x/y not found."   <- explicit
+ *   by udoId: "Something went wrong. Please try again..." <- generic, and the
+ *             SAME text a version conflict returns, so it cannot be trusted
+ *             on message alone.
+ *
+ * So the explicit form is normalised directly, and the ambiguous one is
+ * disambiguated against the file listing: absent from configFiles means the
+ * file is genuinely gone, otherwise the error was real and is rethrown. The
+ * extra listing only happens on the error path.
+ */
+export async function configFile({ name, udoId, scope }) {
   if (!name && !udoId) throw new Error('configFile requires either name or udoId');
-  const data = udoId
-    ? await sdlGraphql('configFile', `query f($udoId: ID!) { configFile(udoId: $udoId) { ${CONFIG_FIELDS} content } }`, { udoId: assertSafeUdoId(udoId) }, { readOnly: true })
-    : await sdlGraphql('configFile', `query f($id: ID!) { configFile(id: $id) { ${CONFIG_FIELDS} content } }`, { id: name }, { readOnly: true });
-  return data?.configFile ?? null;
+  // Validate before the try: an invalid udoId is a caller bug, not a signal
+  // that the file is absent, and must never be swallowed by the absence path.
+  const safeUdoId = udoId ? assertSafeUdoId(udoId) : null;
+  try {
+    const data = safeUdoId
+      ? await sdlGraphql('configFile', `query f($udoId: ID!) { configFile(udoId: $udoId) { ${CONFIG_FIELDS} content } }`, { udoId: safeUdoId }, { readOnly: true, scope })
+      : await sdlGraphql('configFile', `query f($id: ID!) { configFile(id: $id) { ${CONFIG_FIELDS} content } }`, { id: name }, { readOnly: true, scope });
+    return data?.configFile ?? null;
+  } catch (err) {
+    // Only a GraphQL-layer error can mean "absent". A transport failure whose
+    // body happens to contain the words "not found" (a 404 page, a WAF block)
+    // must never be read as absence: that is how a delete gets confirmed
+    // against a file that was never checked.
+    if (!err.graphql) throw err;
+    if (/config file with (name|id) .* not found/i.test(err.message)) return null;
+
+    // The udoId form returns a generic message that a version conflict also
+    // returns, so settle it against the listing. If the listing itself fails,
+    // surface the ORIGINAL error with the listing failure attached rather than
+    // replacing it.
+    // Same scope as the failed lookup. Disambiguating against a DIFFERENT
+    // scope's listing would report a site-scoped file as absent purely because
+    // the listing was taken at account scope, which is the exact false-negative
+    // class this branch exists to remove.
+    let all;
+    try {
+      all = await configFiles({ scope });
+    } catch (listErr) {
+      err.message += ` (absence check failed: ${listErr.message})`;
+      throw err;
+    }
+    const present = udoId
+      ? all.some(f => String(f.udoId) === String(udoId))
+      : all.some(f => matchesName(f, name));
+    if (!present) return null;
+    throw err;
+  }
 }
 
 /**
@@ -217,13 +331,16 @@ export async function configFile({ name, udoId }) {
  *   - name given   → updates in place for plain files, but CREATES A DUPLICATE
  *                    for /dashboards/. Never write a dashboard by name.
  */
-export async function putConfigFile({ name, udoId, content, expectedVersion }) {
+export async function putConfigFile({ name, udoId, content, expectedVersion, scope }) {
   if (!name && !udoId) throw new Error('putConfigFile requires either name or udoId');
   // Creating a dashboard must go by name (no udoId exists yet); only an
   // *existing* dashboard is at risk of being duplicated by a name-addressed
   // write. So refuse only when a file of that name already exists.
-  if (!udoId && String(name).startsWith('/dashboards/')) {
-    const all = await configFiles();
+  if (!udoId && normaliseName(name).startsWith('/dashboards/')) {
+    // Scoped to match the write. An account-scoped listing would not see a
+    // same-named site-scoped dashboard, so the guard has to look where the
+    // write is going, not where the token defaults.
+    const all = await configFiles({ scope });
     // An empty listing means the check could not run, not that the name is
     // free. Failing open here would silently disable the guard.
     if (!all.length) {
@@ -232,8 +349,7 @@ export async function putConfigFile({ name, udoId, content, expectedVersion }) {
         'duplicate check could not run. Retry, or pass an explicit udoId.'
       );
     }
-    const key = String(name).trim().toLowerCase();
-    const existing = all.filter(f => String(f.name || '').trim().toLowerCase() === key);
+    const existing = all.filter(f => matchesName(f, name));
     if (existing.length) {
       const ids = existing.map(f => f.udoId).filter(Boolean).join(', ');
       throw new Error(
@@ -251,10 +367,10 @@ export async function putConfigFile({ name, udoId, content, expectedVersion }) {
   const data = udoId
     ? await sdlGraphql('addConfigFile',
         `mutation f($udoId: ID, $content: String!, $expectedVersion: Long) { addConfigFile(udoId: $udoId, content: $content, expectedVersion: $expectedVersion) { ${CONFIG_FIELDS} } }`,
-        { udoId: assertSafeUdoId(udoId), content, expectedVersion })
+        { udoId: assertSafeUdoId(udoId), content, expectedVersion }, { scope })
     : await sdlGraphql('addConfigFile',
         `mutation f($name: String, $content: String!, $expectedVersion: Long) { addConfigFile(name: $name, content: $content, expectedVersion: $expectedVersion) { ${CONFIG_FIELDS} } }`,
-        { name, content, expectedVersion });
+        { name, content, expectedVersion }, { scope });
   return data?.addConfigFile ?? null;
 }
 
@@ -263,21 +379,21 @@ export async function putConfigFile({ name, udoId, content, expectedVersion }) {
  * A null return with no errors array is SUCCESS; the deleted object is not
  * echoed back. Treating that null as a failure is the classic mistake here.
  */
-export async function deleteConfigFile({ name, udoId, expectedVersion }) {
+export async function deleteConfigFile({ name, udoId, expectedVersion, scope }) {
   if (!name && !udoId) throw new Error('deleteConfigFile requires either name or udoId');
   const raw = udoId
     ? await sdlGraphql('deleteConfigFile',
         'mutation f($udoId: ID, $expectedVersion: Long) { deleteConfigFile(udoId: $udoId, expectedVersion: $expectedVersion) { udoId } }',
-        { udoId: assertSafeUdoId(udoId), expectedVersion })
+        { udoId: assertSafeUdoId(udoId), expectedVersion }, { scope })
     : await sdlGraphql('deleteConfigFile',
         'mutation f($id: ID, $expectedVersion: Long) { deleteConfigFile(id: $id, expectedVersion: $expectedVersion) { udoId } }',
-        { id: name, expectedVersion });
+        { id: name, expectedVersion }, { scope });
 
   // The mutation returns null on success and does not echo the deleted object,
   // so its response cannot distinguish "deleted" from "matched nothing". Confirm
   // by re-reading. This is the house rule established by uamSetStatus in
   // lib/s1.js: never treat a mutation response as proof, re-get and verify.
-  const still = await configFile({ name, udoId });
+  const still = await configFile({ name, udoId, scope });
   if (still) {
     throw new Error(
       `deleteConfigFile: ${udoId ? `udoId ${udoId}` : name} still exists after the delete mutation ` +
@@ -293,13 +409,275 @@ export async function deleteConfigFile({ name, udoId, expectedVersion }) {
 // exist" decision. The GraphQL operations above cover every namespace,
 // including parsers, lookups, datatables and /automaticLookups.
 
+// ─── Dashboard lifecycle (dashboardsV2, GraphQL) ──────────────────────────────
+//
+// A SECOND, HIGHER-LEVEL SURFACE on the same `POST /sdl/v2/graphql` endpoint.
+// This is what the console itself drives; captured from live console traffic on
+// usea1-purple 2026-08-17 (280 requests, 23 operations).
+//
+// Relationship to the config-file layer above:
+//
+//   dashboardsV2       dashboard-aware: name, description, tabs, access/sharing,
+//                      createdBy/updatedBy, isBuiltIn/isEditable. Create takes
+//                      the whole dashboard JSON as one `config` string.
+//   configFiles        the raw file underneath, addressed by udoId. Same object,
+//                      no sharing or authorship metadata, `content` is the JSON.
+//
+// The `id` in dashboardsV2 IS the `udoId` in configFiles. Verified: dashboard
+// "meta1" is id 6999000578736128 in getDashboardV2 and udoId 6999000578736128
+// / name "/dashboards/meta1" in configFile.
+//
+// WHY THIS EXISTS: creating a dashboard through addConfigFile(name:) files it at
+// the request's scope but gives no way to share it elsewhere, and the console's
+// own create path is createDashboardV2. Site-level lifecycle needs both this and
+// shareResource, which is the ONLY operation that takes an explicit scope target
+// rather than inferring one from the request header.
+//
+// VERSION FIELDS DIFFER, do not cross them. getDashboardV2 returns
+// `version: ""` (a display string, empty in practice); configFile returns
+// `version: 215771284` (the numeric CAS token). Only the configFile value is
+// valid as expectedVersion.
+
+const DASHBOARD_SUMMARY_FIELDS = 'id name description configType access { public users owner }';
+
+/** Every dashboard visible at `scope`, with sharing metadata. Prefer this over
+ *  configFiles({pathPrefix:'/dashboards/'}) when you need owner or access. */
+export async function listDashboards({ scope } = {}) {
+  const data = await sdlGraphql(
+    'GetDashboardNames',
+    `query GetDashboardNames { dashboardsV2 { ${DASHBOARD_SUMMARY_FIELDS} } }`,
+    undefined,
+    { readOnly: true, scope }
+  );
+  return data?.dashboardsV2 ?? [];
+}
+
+/**
+ * Read one dashboard by id (preferred) or name, including its tabs.
+ * Returns null when it does not exist at `scope`.
+ *
+ * `tabs[].graphs` / `.parameters` / `.filters` / `.options` come back as JSON
+ * STRINGS, not objects; the console parses them client-side. Callers that want
+ * structure must JSON.parse each one.
+ *
+ * ABSENCE HANDLING mirrors configFile deliberately. The live capture only shows
+ * a successful read, so it is not established whether a missing dashboard comes
+ * back as `data.getDashboardV2 = null` or as a GraphQL error. Both are treated
+ * as absence, disambiguated against the dashboard listing. Assuming only the
+ * null form is what broke every `sdl_delete_file` in 1.3.2: the confirming
+ * re-read threw on precisely the success path. A transport-layer error is still
+ * rethrown, so a proxy page containing "not found" can never be read as absence.
+ */
+export async function getDashboard({ id, name, scope }) {
+  if (!id && !name) throw new Error('getDashboard requires either id or name');
+  const safeId = id ? assertSafeUdoId(id) : undefined;
+  try {
+    const data = await sdlGraphql(
+      'GetDashboardConfigV2',
+      `query GetDashboardConfigV2($id: ID, $dashboardName: String) {
+         getDashboardV2(id: $id, dashboardName: $dashboardName, resolveParameters: true) {
+           id name description configType duration isBuiltIn isEditable version
+           access { public users owner }
+           tabs { tabName parameters graphs filters options }
+           createdAt createdBy updatedAt updatedBy
+         }
+       }`,
+      { id: safeId, dashboardName: name },
+      { readOnly: true, scope }
+    );
+    return data?.getDashboardV2 ?? null;
+  } catch (err) {
+    if (!err.graphql) throw err;
+    let all;
+    try {
+      all = await listDashboards({ scope });
+    } catch (listErr) {
+      err.message += ` (absence check failed: ${listErr.message})`;
+      throw err;
+    }
+    const present = safeId
+      ? all.some(d => String(d.id) === safeId)
+      : all.some(d => normaliseName(d.name) === normaliseName(name));
+    if (!present) return null;
+    throw err;
+  }
+}
+
+/**
+ * Create a dashboard from a full dashboard-JSON config, at `scope`.
+ *
+ * This is the console's own create path and it accepts the complete dashboard
+ * document (configType, duration, description, tabs[]) as ONE string. That is
+ * the important difference from the UI's "new dashboard then paste JSON" flow,
+ * which starts from a `{graphs: []}` stub: pasting after the stub instead of
+ * replacing it produces `{graphs: []}{...}` and the server rejects it with
+ * "Content is invalid json" / "Additional text after JSON object". Going
+ * through this function cannot hit that class of error.
+ *
+ * DUPLICATE NAMES ARE ALLOWED HERE, unlike putConfigFile. The console itself
+ * creates "<name> - Copy" siblings, and shareResource addresses dashboards by
+ * id, so duplicate names are not the footgun they are for name-addressed
+ * config-file writes. Set `failIfNameExists` to opt into the stricter
+ * behaviour; it costs one extra listing call.
+ */
+export async function createDashboard({ name, config, isPublic = false, scope, failIfNameExists = false }) {
+  if (!name || typeof name !== 'string') throw new Error('createDashboard requires a name');
+  if (typeof config !== 'string' || !config.trim()) {
+    throw new Error('createDashboard requires config as a JSON string (the full dashboard document).');
+  }
+  // Fail before the mutation rather than filing a broken dashboard the console
+  // then renders as an empty shell.
+  try {
+    JSON.parse(config);
+  } catch (e) {
+    throw new Error(
+      `createDashboard: config is not valid JSON (${e.message}). ` +
+      'If this came from the console\'s JSON editor, check for a leading "{graphs: []}" stub: ' +
+      'the new document must REPLACE it, not follow it.'
+    );
+  }
+
+  if (failIfNameExists) {
+    const existing = (await listDashboards({ scope })).filter(d => normaliseName(d.name) === normaliseName(name));
+    if (existing.length) {
+      throw new Error(
+        `createDashboard: ${existing.length} dashboard(s) named "${name}" already exist at this scope ` +
+        `(ids: ${existing.map(d => d.id).join(', ')}). Pass failIfNameExists:false to create a sibling anyway.`
+      );
+    }
+  }
+
+  const data = await sdlGraphql(
+    'CreateDashboard',
+    `mutation CreateDashboard($dashboardName: String!, $config: String, $public: Boolean) {
+       createDashboardV2(dashboardName: $dashboardName, config: $config, public: $public) { id name }
+     }`,
+    { dashboardName: name, config, public: isPublic },
+    { scope }
+  );
+  const created = data?.createDashboardV2 ?? null;
+  if (!created?.id) {
+    throw new SdlGraphqlError('createDashboard: mutation returned no id, so the dashboard was not created.');
+  }
+  return created;
+}
+
+/**
+ * Share a dashboard to scopes and/or users. THE ONLY OPERATION THAT TAKES AN
+ * EXPLICIT SCOPE TARGET; everything else infers scope from the S1-Scope header.
+ *
+ * `scopes` entries are {scopeType, scopeId, operation}:
+ *   scopeType  'site' | 'account' | 'global'
+ *   scopeId    the numeric id from /web/api/v2.1/sites or /accounts
+ *   operation  'ADD' | 'REMOVE'
+ *
+ * `scope` (the option, not the array) is still the header for the CALL, i.e.
+ * where you are standing when you share. It is independent of the targets.
+ */
+const VALID_SCOPE_TYPES = new Set(['site', 'account', 'global']);
+const VALID_SCOPE_OPS = new Set(['ADD', 'REMOVE']);
+
+export async function shareDashboard({ id, scopes = [], users = [], scope }) {
+  if (!id) throw new Error('shareDashboard requires the dashboard id');
+  if (!Array.isArray(scopes) || !Array.isArray(users)) {
+    throw new Error('shareDashboard: scopes and users must both be arrays.');
+  }
+  if (!scopes.length && !users.length) {
+    throw new Error('shareDashboard: pass at least one scope or user, otherwise the call is a no-op.');
+  }
+  // Validate up front: the server accepts a malformed entry and silently shares
+  // nothing, which reads as success.
+  const normalisedScopes = scopes.map((s, i) => {
+    const type = String(s?.scopeType ?? '').toLowerCase();
+    const op = String(s?.operation ?? 'ADD').toUpperCase();
+    if (!VALID_SCOPE_TYPES.has(type)) {
+      throw new Error(`shareDashboard: scopes[${i}].scopeType must be one of ${[...VALID_SCOPE_TYPES].join(', ')} (got ${JSON.stringify(s?.scopeType)}).`);
+    }
+    if (!VALID_SCOPE_OPS.has(op)) {
+      throw new Error(`shareDashboard: scopes[${i}].operation must be ADD or REMOVE (got ${JSON.stringify(s?.operation)}).`);
+    }
+    if (type !== 'global' && !/^\d+$/.test(String(s?.scopeId ?? ''))) {
+      throw new Error(`shareDashboard: scopes[${i}].scopeId must be a numeric id for scopeType "${type}" (got ${JSON.stringify(s?.scopeId)}).`);
+    }
+    return { scopeType: type, scopeId: String(s.scopeId), operation: op };
+  });
+
+  const data = await sdlGraphql(
+    'ShareDashboard',
+    `mutation ShareDashboard($id: ID!, $users: [UserSharingCommand], $scopes: [ScopeSharingCommand]) {
+       shareResource(id: $id, users: $users, scopes: $scopes) { id name }
+     }`,
+    { id: assertSafeUdoId(id), users, scopes: normalisedScopes },
+    { scope }
+  );
+  const shared = data?.shareResource ?? null;
+  if (!shared?.id) {
+    throw new SdlGraphqlError('shareDashboard: shareResource returned no id, so nothing was shared.');
+  }
+  return { status: 'success', dashboard: { id: String(shared.id), name: shared.name }, scopes: normalisedScopes, users };
+}
+
+/**
+ * Replace the panel layout of ONE tab. `graphs` is a JSON string shaped
+ * `{"graphs":[...]}` (note the wrapper key; the response echoes a bare array).
+ * Use this for incremental panel edits; use createDashboard for a whole document.
+ */
+export async function saveDashboardLayout({ id, name, tabName, graphs, options, scope }) {
+  if (!id && !name) throw new Error('saveDashboardLayout requires either id or name');
+  if (typeof graphs !== 'string' || !graphs.trim()) {
+    throw new Error('saveDashboardLayout requires graphs as a JSON string, shaped {"graphs":[...]}.');
+  }
+  try {
+    const parsed = JSON.parse(graphs);
+    if (!parsed || !Array.isArray(parsed.graphs)) {
+      throw new Error('missing the top-level "graphs" array');
+    }
+  } catch (e) {
+    throw new Error(`saveDashboardLayout: graphs is not a valid {"graphs":[...]} JSON string (${e.message}).`);
+  }
+  const data = await sdlGraphql(
+    'SaveDashboardLayout',
+    `mutation SaveDashboardLayout($id: ID, $dashboardName: String, $graphs: String, $options: String, $tabName: String) {
+       saveDashboardLayout(id: $id, dashboardName: $dashboardName, graphs: $graphs, options: $options, tabName: $tabName) { graphs options }
+     }`,
+    { id: id ? assertSafeUdoId(id) : undefined, dashboardName: name, graphs, options, tabName },
+    { scope }
+  );
+  return data?.saveDashboardLayout ?? null;
+}
+
+/**
+ * Delete a dashboard by id or name. `deleteDashboard` returns a bare boolean,
+ * so per the house rule the removal is confirmed by re-reading rather than
+ * trusted from the mutation response.
+ */
+export async function deleteDashboard({ id, name, scope }) {
+  if (!id && !name) throw new Error('deleteDashboard requires either id or name');
+  const data = await sdlGraphql(
+    'DeleteDashboard',
+    'mutation DeleteDashboard($id: ID, $dashboardName: String) { deleteDashboard(id: $id, dashboardName: $dashboardName) }',
+    { id: id ? assertSafeUdoId(id) : undefined, dashboardName: name },
+    { scope }
+  );
+  const reported = data?.deleteDashboard;
+
+  const still = await getDashboard({ id, name, scope });
+  if (still) {
+    throw new Error(
+      `deleteDashboard: ${id ? `id ${id}` : name} still exists after the delete mutation ` +
+      `(mutation returned ${JSON.stringify(reported)}). Nothing was removed.`
+    );
+  }
+  return { status: 'success', deleted: id ? { id: String(id) } : { name }, raw: reported ?? null };
+}
+
 // ─── V1 Query (schema discovery) ─────────────────────────────────────────────
 // Deprecated Feb 15 2027 but still the only way to get full event JSON per-event.
 // Use for schema discovery; use LRQ for hunting.
 
 /** POST /api/query: retrieve raw event JSON for schema discovery.
  *  Returns { matches: [{ timestamp, message, attributes }] }. */
-export async function v1Query(filter, { maxCount = 5, startTime = '24h', endTime } = {}) {
+export async function v1Query(filter, { maxCount = 5, startTime = '24h', endTime, scope } = {}) {
   const body = {
     queryType: 'log',
     filter,
@@ -307,5 +685,7 @@ export async function v1Query(filter, { maxCount = 5, startTime = '24h', endTime
     startTime,
   };
   if (endTime) body.endTime = endTime;
-  return sdlFetch('POST', '/api/query', { body });
+  // Read-only POST: opt back into status retry. Schema discovery iterates this
+  // once per data source, which is the workload that trips the SDL QPS cap.
+  return sdlFetch('POST', '/api/query', { body, allowRetry: true, extraHeaders: scopeHeaders(scope) });
 }

package/lib/server-core.js

@@ -94,7 +94,7 @@ const PROMPTS = [
 
 export const SERVER_INFO = {
   name: 's1-secops-mcp-server',
-  version: '1.3.2',
+  version: '1.3.4',
 };
 
 export const PROTOCOL_VERSION = '2024-11-05';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmoses-s1/s1-secops-mcp",
-  "version": "1.3.2",
+  "version": "1.3.4",
   "description": "MCP server orchestrating SentinelOne skills, APIs, and SOC analyst context. Stdio or Streamable HTTP transport with per-user bearer auth for team deployments.",
   "type": "module",
   "main": "index.js",

package/scripts/regen-readme-tools-table.mjs

@@ -44,6 +44,13 @@ const TOOL_SKILL = {
   sdl_get_file:                  'sdl-api / sdl-dashboard / sdl-log-parser',
   sdl_put_file:                  'sdl-api / sdl-dashboard / sdl-log-parser',
   sdl_delete_file:               'sdl-api',
+  // SDL dashboard lifecycle (dashboardsV2)
+  sdl_list_dashboards:           'sdl-api / sdl-dashboard',
+  sdl_get_dashboard:             'sdl-api / sdl-dashboard',
+  sdl_create_dashboard:          'sdl-api / sdl-dashboard',
+  sdl_share_dashboard:           'sdl-api / sdl-dashboard',
+  sdl_save_dashboard_layout:     'sdl-api / sdl-dashboard',
+  sdl_delete_dashboard:          'sdl-api / sdl-dashboard',
   hec_ingest:                    'sdl-api / sdl-log-parser',
   // Hyperautomation
   ha_list_workflows:             'hyperautomation',

package/scripts/smoke-test-http.sh

@@ -5,7 +5,7 @@
 # Exercises the public contract end-to-end:
 #   1. healthz returns 200 (no auth)
 #   2. initialize returns the expected protocol version and server info
-#   3. tools/list returns 26 tools
+#   3. tools/list returns 32 tools
 #   4. tools/call s1_api_get works (uses /agents/count as a cheap probe)
 #   5. bad bearer returns HTTP 401
 #   6. unknown method returns JSON-RPC error -32601 inside a 200 envelope
@@ -81,7 +81,7 @@ echo "=== 3. tools/list count ==="
 TOOLS_COUNT=$(curl -s -X POST "$URL" -H "$AUTH" -H "$JSON" \
   -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' |
   jq '.result.tools | length')
-[[ "$TOOLS_COUNT" == "26" ]] && pass "tools/list returned 26 tools" || fail "tools/list returned $TOOLS_COUNT"
+[[ "$TOOLS_COUNT" == "32" ]] && pass "tools/list returned 32 tools" || fail "tools/list returned $TOOLS_COUNT"
 
 echo
 echo "=== 4. tools/call s1_api_get on /agents/count ==="

package/scripts/test-mac.sh

@@ -128,8 +128,8 @@ STDIO_REPLY="$(printf '%s\n%s\n' \
   node index.js 2>/dev/null)"
 
 TOOL_COUNT="$(echo "$STDIO_REPLY" | tail -n 1 | node -e 'let s=""; process.stdin.on("data",d=>s+=d); process.stdin.on("end",()=>{try{console.log(JSON.parse(s).result.tools.length)}catch(e){console.log("ERR")}})')"
-if [[ "$TOOL_COUNT" == "26" ]]; then
-  pass "stdio tools/list returned 26 tools"
+if [[ "$TOOL_COUNT" == "32" ]]; then
+  pass "stdio tools/list returned 32 tools"
 else
   fail "stdio tools/list returned $TOOL_COUNT (expected 26)" "$STDIO_REPLY"
 fi
@@ -159,8 +159,8 @@ HTTP_REPLY="$(curl -sf -X POST "http://127.0.0.1:$PORT/mcp" \
   -H 'Content-Type: application/json' \
   -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}')"
 HTTP_COUNT="$(echo "$HTTP_REPLY" | node -e 'let s=""; process.stdin.on("data",d=>s+=d); process.stdin.on("end",()=>{try{console.log(JSON.parse(s).result.tools.length)}catch(e){console.log("ERR")}})')"
-if [[ "$HTTP_COUNT" == "26" ]]; then
-  pass "HTTP tools/list returned 26 tools"
+if [[ "$HTTP_COUNT" == "32" ]]; then
+  pass "HTTP tools/list returned 32 tools"
 else
   fail "HTTP tools/list returned $HTTP_COUNT" "$HTTP_REPLY"
 fi