@joe-broadhead/opencode-gws 0.0.1 → 0.0.2

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.0.2] - 2026-11-03
+
+### Fixed
+
+- The default sign-in no longer requests the Keep scopes, which Google grants only through domain-wide delegation, so Google no longer refuses the whole consent with `invalid_scope`. No access level requests `keep` or `keep.readonly`, and the `default` account no longer enables Keep: Read and write now requests 45 scopes and Read-only 37. `gws_catalog` and `gws_schema` mark the 7 Keep methods `restriction: "domain-wide-delegation"` (app-only methods keep `appOnly` and gain `restriction: "app-only"`), and the scope check refuses them with that reason. For an interactive account that enables `keep` without adding a Keep scope in `accounts.<alias>.scopes`, status carries `delegationRequired`, the sign-in form says Keep needs delegation, and `/gws-doctor` reports Keep `SKIPPED` with the reason. (#8)
+- A non-admin's Admin SDK refusal of a valid sign-in, such as the Reports API's 401 `Access denied. You are not authorized to read activity records.`, is now `ADMIN_PRIVILEGE_REQUIRED`, not `AUTH_REQUIRED`. Its next step is to sign in with a Workspace admin account that has the privilege (Reports for `admin-reports`) or to remove the service from `enabledServices`. Reads, plans, commits and `/gws-doctor` classify it the same way; it never marks the account as needing sign-in in status or `/connect`, and the doctor reports it as its own status, counted as needing attention. Token failures (`invalid_grant`, an expired or revoked token, `UNAUTHENTICATED`) stay `AUTH_REQUIRED`. (#9)
+- The tools RPC reports `SESSION_UNKNOWN` only when OpenCode says the session does not exist (`Session.NotFoundError`, or a 404). Any other failure to look the session up now propagates unchanged instead of being reported as an unknown session.
+
 ## [0.0.1] - 2026-11-03
 
 ### Added

package/README.md

@@ -18,7 +18,7 @@ opencode plugin add @joe-broadhead/opencode-gws
 
 npm also installs the matching `@joe-broadhead/opencode-gws-bin-<target>` package, which holds the unmodified `gws` binary at the version the plugin pins ([details](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/docs/backend.md)). Nothing downloads at runtime and there is no install script.
 
-With no options, the plugin creates one account, `default`, with every Workspace service it covers at Read and write, so one consent grants every scope it can use. Every change still needs a plan and your approval. To narrow it, set `accounts` ([configuration](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/docs/configuration.md#accounts)).
+With no options, the plugin creates one account, `default`, with every Workspace service a Google sign-in can use at Read and write, so one consent grants every scope it can use. Keep is left out: Google grants its scopes only through domain-wide delegation, which a Workspace admin sets up ([Keep](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/docs/auth.md#keep-needs-domain-wide-delegation)). Every change still needs a plan and your approval. To narrow it, set `accounts` ([configuration](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/docs/configuration.md#accounts)).
 
 ## Sign in
 
@@ -28,7 +28,7 @@ Run `/connect` and choose **Google Workspace**. The TUI shows the sign-in link:
 opencode auth login gws-default
 ```
 
-No Google OAuth client ships with the plugin. The first time, the form asks for the client ID and secret of your own Desktop app OAuth client, unless your organisation set one (see [Organisation rollout](#organisation-rollout)). To make one, follow [Create your Desktop client](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/docs/auth.md#create-your-desktop-client). The form lists the exact scopes before Google's consent screen. Read and write is the default for the `default` account and needs an acknowledgment; Read-only is the other choice. The default consent lists about 46 scopes, and an External client in Testing shows unverified-app warnings and expires refresh tokens after 7 days: see [What the default consent asks for](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/docs/auth.md#what-the-default-consent-asks-for). With several accounts, each `/connect` entry is named **Google Workspace (`<alias>`)**.
+No Google OAuth client ships with the plugin. The first time, the form asks for the client ID and secret of your own Desktop app OAuth client, unless your organisation set one (see [Organisation rollout](#organisation-rollout)). To make one, follow [Create your Desktop client](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/docs/auth.md#create-your-desktop-client). The form lists the exact scopes before Google's consent screen. Read and write is the default for the `default` account and needs an acknowledgment; Read-only is the other choice. The default consent lists 45 scopes (37 for Read-only), and an External client in Testing shows unverified-app warnings and expires refresh tokens after 7 days: see [What the default consent asks for](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/docs/auth.md#what-the-default-consent-asks-for). With several accounts, each `/connect` entry is named **Google Workspace (`<alias>`)**.
 
 Details and the scope table: [docs/auth.md](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/docs/auth.md).
 
@@ -101,7 +101,8 @@ Members then only run `/connect`, choose Google Workspace, and pick an access le
 | Code | What to do |
 | --- | --- |
 | `AUTH_REQUIRED` | Run `/connect` and choose Google Workspace, or run `opencode auth login gws-<alias>`. |
-| `AUTH_SCOPE_MISSING` | Sign in again, approve every scope Google lists, and choose Read and write. A method marked `appOnly` needs a Chat app's or Classroom add-on's own credentials and cannot run with a Google sign-in. Nothing ran. |
+| `ADMIN_PRIVILEGE_REQUIRED` | The sign-in is valid, but the account is not a Workspace admin with the privilege the API needs, such as Reports for `admin-reports`. Signing in again as the same account does not help: sign in with an admin account that has it, or remove the service from `enabledServices`. |
+| `AUTH_SCOPE_MISSING` | Sign in again, approve every scope Google lists, and choose Read and write. A method marked `appOnly` (`restriction: "app-only"`) needs a Chat app's or Classroom add-on's own credentials and cannot run with a Google sign-in. A Keep method (`restriction: "domain-wide-delegation"`) needs domain-wide delegation that a Workspace admin sets up. Nothing ran. |
 | `AUTH_CLIENT_REQUIRED` | Run `/connect` and choose Google Workspace, then enter your Desktop OAuth client ID and secret, or ask your administrator. |
 | `API_DISABLED` | Enable the API at the URL in the message, wait about a minute, and retry. `/gws-doctor` checks every service. |
 | `HOST_UNTESTED` | Use OpenCode 2.2.3 or a later 2.2.x, or set `"allowUntestedHost": true`. |

package/dist/index.js

@@ -6618,6 +6618,10 @@ var ErrorCode = {
     meaning: "The sign-in has not granted a scope this operation needs. The plugin checks before gws runs, so nothing ran.",
     next: "Ask the user to sign in again with the access the message names, or to add the scope to the account's scopes, then retry. For a method only an app's credentials can run, use another method."
   },
+  ADMIN_PRIVILEGE_REQUIRED: {
+    meaning: "The sign-in is valid, but Google refused the call because the account lacks a Workspace admin privilege the API needs, such as Reports for admin-reports. Signing in again as the same account does not help, and the sign-in is not marked as needing renewal.",
+    next: "Ask the user to sign in with a Workspace admin account that has the needed privilege (Reports for admin-reports), or to remove the service from enabledServices."
+  },
   AUTH_CLIENT_REQUIRED: {
     meaning: "No OAuth client is configured for the sign-in, none was entered in the form, and no earlier sign-in has one.",
     next: "Run /connect and choose Google Workspace, then enter your Desktop OAuth client ID and secret, or ask your administrator."
@@ -6785,11 +6789,11 @@ import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-// src/domain/app-only.ts
-var APP_ONLY_SCOPES = ["chat.bot", "chat.import", "classroom.addons.student", "classroom.addons.teacher"].map(
-  (name) => `https://www.googleapis.com/auth/${name}`
-);
-var USER_UNUSABLE_METHODS = [
+// src/domain/restricted.ts
+var PREFIX = "https://www.googleapis.com/auth/";
+var APP_ONLY_SCOPES = ["chat.bot", "chat.import", "classroom.addons.student", "classroom.addons.teacher"].map((name) => `${PREFIX}${name}`);
+var DELEGATION_SCOPES = ["keep", "keep.readonly"].map((name) => `${PREFIX}${name}`);
+var APP_ONLY_METHODS = [
   // chat: a Chat app's own credentials
   "chat.spaces.completeImport",
   "chat.spaces.messages.attachments.get",
@@ -6822,9 +6826,33 @@ var USER_UNUSABLE_METHODS = [
   "classroom.courses.posts.addOnAttachments.studentSubmissions.patch",
   "classroom.courses.posts.getAddOnContext"
 ];
-var UNUSABLE = new Set(USER_UNUSABLE_METHODS);
-function appOnly(operation) {
-  return UNUSABLE.has(operation);
+var DELEGATION_METHODS = [
+  "keep.media.download",
+  "keep.notes.create",
+  "keep.notes.delete",
+  "keep.notes.get",
+  "keep.notes.list",
+  "keep.notes.permissions.batchCreate",
+  "keep.notes.permissions.batchDelete"
+];
+var DELEGATION_SERVICES = ["keep"];
+var RESTRICTIONS = new Map([
+  ...APP_ONLY_METHODS.map((id) => [id, "app-only"]),
+  ...DELEGATION_METHODS.map((id) => [id, "domain-wide-delegation"])
+]);
+function restriction(operation) {
+  return RESTRICTIONS.get(operation);
+}
+function addsDelegationScope(scopes) {
+  return scopes.some((scope) => DELEGATION_SCOPES.includes(scope));
+}
+function delegationRequired(services, scopes) {
+  return addsDelegationScope(scopes) ? [] : services.filter((service) => DELEGATION_SERVICES.includes(service));
+}
+function restrictionMarks(operation) {
+  const reason = restriction(operation);
+  if (!reason) return {};
+  return reason === "app-only" ? { appOnly: true, restriction: reason } : { restriction: reason };
 }
 
 // src/domain/helpers.ts
@@ -7350,7 +7378,7 @@ function catalog(input = {}, services) {
         ...method.pathTemplate ? { path: method.pathTemplate } : {},
         executable: methodExecutable(method),
         ...tool && methodExecutable(method) ? { commitTool: tool } : {},
-        ...appOnly(method.id) ? { appOnly: true } : {}
+        ...restrictionMarks(method.id)
       });
     }
   }
@@ -7513,7 +7541,8 @@ var DIRECT = {
   forms: { read: ["forms.body.readonly", "forms.responses.readonly"], write: ["forms.body", "forms.responses.readonly", "drive.file"] },
   // meetings.space.created reaches only spaces this client created; write keeps reading the others.
   meet: { read: ["meetings.space.readonly"], write: ["meetings.space.created", "meetings.space.readonly"] },
-  keep: { read: ["keep.readonly"], write: ["keep"] },
+  // Google grants Keep's scopes only through domain-wide delegation (restricted.ts), so neither level requests them.
+  keep: { read: [], write: [] },
   // Reports are read-only at both levels.
   "admin-reports": {
     read: ["admin.reports.audit.readonly", "admin.reports.usage.readonly"],
@@ -7601,7 +7630,8 @@ var ClientJsonSchema = union([
 var OAuthClientSchema = union([DesktopClientSchema, ClientJsonSchema]);
 var accessLevel = _enum(["read", "write"]);
 function defaultAccounts() {
-  return { default: { mode: "interactive", enabledServices: loadManifest().services.map((service) => service.alias), access: "write" } };
+  const services = loadManifest().services.map((service) => service.alias).filter((service) => !DELEGATION_SERVICES.includes(service));
+  return { default: { mode: "interactive", enabledServices: services, access: "write" } };
 }
 var enabledServices = array(string2().min(1)).min(1);
 var accountProfile = preprocess(
@@ -7812,7 +7842,7 @@ function loadConfig(raw) {
 }
 
 // src/domain/version.ts
-var PLUGIN_VERSION = "0.0.1";
+var PLUGIN_VERSION = "0.0.2";
 var PLUGIN_ID = "google-workspace.gws";
 var HOST_RANGE = ">=2.2.3 <2.3.0";
 var SEMVER = /^v?(\d+)\.(\d+)\.(\d+)(-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
@@ -7932,6 +7962,7 @@ var account = object2(
     clientSource: { enum: CLIENT_SOURCES },
     grantedScopes: texts,
     missingScopes: texts,
+    delegationRequired: texts,
     nextStep: text
   },
   ["alias", "mode", "services", "connected"]
@@ -7969,6 +8000,11 @@ function connectionLabel(account2) {
 function openCodeLabel(status2) {
   return status2.hostWarning ? `${status2.hostVersion} (host untested: ${status2.hostWarning})` : `${status2.hostVersion} (tested)`;
 }
+var DELEGATION_LABEL = "Needs domain-wide delegation";
+function delegationText(account2) {
+  const services = account2.delegationRequired ?? [];
+  return `${services.join(", ")} (a Workspace admin sets it up; then add the scopes to accounts.${account2.alias}.scopes)`;
+}
 var BLOCK_PLACEMENT = "Put this block first in that agent's own permissions, followed by your top-level rules for gws actions. Never put it in the top-level permissions: that would loosen Explore.";
 
 // src/auth/setup.ts
@@ -8163,6 +8199,199 @@ var PlanStore = class {
   }
 };
 
+// src/domain/result.ts
+function isApiError(value) {
+  if (Array.isArray(value)) return value.some(isApiError);
+  if (!value || typeof value !== "object") return false;
+  const record2 = value;
+  return "error" in record2 && record2.error !== null && typeof record2.error === "object";
+}
+function parseJson(text3) {
+  const lines = text3.split("\n");
+  const start2 = lines.findIndex((line) => /^[[{]/.test(line.trim()));
+  if (start2 < 0) return void 0;
+  const candidate = lines.slice(start2).join("\n").trim();
+  try {
+    return JSON.parse(candidate);
+  } catch {
+    const parsed = [];
+    for (const line of lines.slice(start2)) {
+      const value = line.trim();
+      if (!/^[[{]/.test(value)) continue;
+      try {
+        parsed.push(JSON.parse(value));
+      } catch {
+      }
+    }
+    return parsed.length > 0 ? parsed : void 0;
+  }
+}
+function inlineCap(maxInlineBytes, mode, requested) {
+  const base2 = mode === "full" ? Math.max(maxInlineBytes, 5 * 1024 * 1024) : maxInlineBytes;
+  return requested === void 0 ? base2 : Math.min(base2, requested);
+}
+function parseResult(result, options) {
+  const text3 = result.stdout.toString("utf8");
+  const parsed = parseJson(text3);
+  const serialized = parsed === void 0 ? text3 : JSON.stringify(parsed);
+  const bytes2 = Buffer.byteLength(serialized);
+  const cap = inlineCap(options.maxInlineBytes, options.mode, options.requestedInlineBytes);
+  const truncated = bytes2 > cap;
+  const empty = text3.trim().length === 0;
+  return {
+    // A successful DELETE commonly returns 204 with no body. Empty output
+    // with exit 0 is success; non-JSON text is not a JSON result.
+    ok: result.exitCode === 0 && (empty || parsed !== void 0 && !isApiError(parsed)),
+    data: parsed,
+    raw: parsed === void 0 ? text3.slice(0, cap) : void 0,
+    truncated,
+    diagnostics: { exitCode: result.exitCode, durationMs: result.durationMs, bytes: bytes2 }
+  };
+}
+function itemKey(page2) {
+  if (!page2 || typeof page2 !== "object" || Array.isArray(page2)) return void 0;
+  const record2 = page2;
+  if (Array.isArray(record2["items"])) return "items";
+  const arrays = Object.keys(record2).filter((key) => Array.isArray(record2[key]));
+  return arrays.length === 1 ? arrays[0] : void 0;
+}
+function capPageItems(data, maxItems) {
+  const pages = data === void 0 ? [] : Array.isArray(data) ? data : [data];
+  const keys = pages.map((page2) => itemKey(page2) ?? (isEmptyPage(page2) ? null : void 0));
+  if (keys.some((key) => key === void 0)) return { data: pages, pages: pages.length, capped: false };
+  const kept = [];
+  let items = 0;
+  let capped = false;
+  for (const [index2, page2] of pages.entries()) {
+    if (items >= maxItems) {
+      capped = true;
+      break;
+    }
+    const key = keys[index2];
+    if (!key) {
+      kept.push(page2);
+      continue;
+    }
+    const record2 = page2;
+    const list = record2[key];
+    const room = maxItems - items;
+    if (list.length > room) {
+      const { nextPageToken: _dropped, ...rest } = record2;
+      kept.push({ ...rest, [key]: list.slice(0, room) });
+      items += room;
+      capped = true;
+      break;
+    }
+    kept.push(page2);
+    items += list.length;
+  }
+  return { data: kept, pages: kept.length, items, capped };
+}
+function isEmptyPage(page2) {
+  if (!page2 || typeof page2 !== "object" || Array.isArray(page2)) return false;
+  return !Object.values(page2).some(Array.isArray);
+}
+function redactDryRun(value) {
+  if (Array.isArray(value)) return value.map(redactDryRun);
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [key, child] of Object.entries(value)) {
+      if (/^(body|raw|content)$/i.test(key)) out[key] = "[redacted]";
+      else out[key] = redactDryRun(child);
+    }
+    return out;
+  }
+  return value;
+}
+function apiErrorOf(result, parsed) {
+  const data = parsed ? parsed.data : parseJson(result.stdout.toString("utf8"));
+  const found = Array.isArray(data) ? data.find(isApiError) : data;
+  if (!isApiError(found)) return void 0;
+  return found.error;
+}
+function stderrText(result) {
+  return result.stderr.toString("utf8").split("\n").filter((line) => line.trim() && !/^Using keyring backend:/i.test(line)).join("\n").trim();
+}
+var EXIT = { auth: 2, validation: 3, discovery: 4, internal: 5 };
+var SCOPE_REASONS = /* @__PURE__ */ new Set(["ACCESS_TOKEN_SCOPE_INSUFFICIENT", "insufficientPermissions"]);
+var PRIVILEGE_REFUSALS = /\bnot authori[sz]ed to (?:read|access|view|list|use|manage|perform)\b|\bcaller does not have access to the customers? reporting data\b/i;
+function privilegeRefused(result, parsed) {
+  if (result.timedOut || result.outputCapped || result.exitCode === 0 || result.exitCode === EXIT.auth) return false;
+  const error2 = apiErrorOf(result, parsed);
+  if (error2?.code !== void 0 && error2.code !== 401 && error2.code !== 403) return false;
+  const text3 = [error2?.message, stderrText(result)].filter(Boolean).join("\n");
+  return !/invalid_grant/i.test(text3) && PRIVILEGE_REFUSALS.test(text3);
+}
+var ADMIN_PRIVILEGES = { "admin-reports": "Reports" };
+function privilegeName(service) {
+  const name = service ? ADMIN_PRIVILEGES[service] : void 0;
+  return name ? `the ${name} privilege` : "the admin privilege it needs";
+}
+function authProblem(result, parsed) {
+  if (result.timedOut || result.outputCapped) return void 0;
+  if (privilegeRefused(result, parsed)) return void 0;
+  const error2 = apiErrorOf(result, parsed);
+  if (result.exitCode === 0 && !error2) return void 0;
+  const reasons = [error2?.reason, ...(error2?.errors ?? []).map((item) => item?.reason), ...(error2?.details ?? []).map((item) => item?.reason)];
+  const text3 = [error2?.message, error2?.status, stderrText(result)].filter(Boolean).join("\n");
+  if (reasons.some((reason) => reason !== void 0 && SCOPE_REASONS.has(reason)) || /insufficient authentication scopes|ACCESS_TOKEN_SCOPE_INSUFFICIENT/i.test(text3)) {
+    return "AUTH_SCOPE_MISSING";
+  }
+  if (error2?.code === 401 || error2?.status === "UNAUTHENTICATED" || reasons.includes("authError") || /invalid_grant|\bUNAUTHENTICATED\b|^error\[auth\]/im.test(text3)) {
+    return "AUTH_REQUIRED";
+  }
+  return void 0;
+}
+var GENERIC_REMEDIATION = {
+  signIn: "sign in to the account again",
+  consent: "sign in again and grant the scope this operation needs",
+  privilege: "sign in with a Workspace admin account that has the admin privilege this operation needs, or remove the service from enabledServices"
+};
+var DISABLED_REASONS = /* @__PURE__ */ new Set(["accessNotConfigured", "SERVICE_DISABLED"]);
+var CONSOLE_URL = /https:\/\/console\.(?:developers|cloud)\.google\.com\/[^\s"'<>)]+/;
+function disabledApi(result, parsed) {
+  const error2 = apiErrorOf(result, parsed);
+  const reasons = [error2?.reason, ...(error2?.errors ?? []).map((item) => item?.reason), ...(error2?.details ?? []).map((item) => item?.reason)];
+  const text3 = [error2?.message, stderrText(result)].filter(Boolean).join("\n");
+  if (!reasons.some((reason) => reason !== void 0 && DISABLED_REASONS.has(reason)) && !/accessnotconfigured|has not been used|is disabled/i.test(text3)) {
+    return void 0;
+  }
+  const enableUrl = (typeof error2?.enable_url === "string" && CONSOLE_URL.test(error2.enable_url) ? error2.enable_url : CONSOLE_URL.exec(text3)?.[0])?.replace(/[.,;]+$/, "");
+  const project = (enableUrl ? /[?&]project=([\w.:-]+)/.exec(enableUrl)?.[1] : void 0) ?? /\bin project ([\w.:-]+)/.exec(text3)?.[1];
+  return { ...enableUrl ? { enableUrl } : {}, ...project ? { project } : {} };
+}
+function processError(result, parsed, remediation = GENERIC_REMEDIATION) {
+  if (result.timedOut) return new GwsError("TIMEOUT", `gws did not finish within the configured execution.timeoutMs (${result.durationMs}ms elapsed)`);
+  if (result.outputCapped) return new GwsError("OUTPUT_LIMIT", "gws output exceeded execution.maxStdoutBytes/maxStderrBytes; narrow fields or pagination");
+  const stderr = stderrText(result);
+  const payload = apiErrorOf(result, parsed);
+  const message = payload?.message || stderr || "gws command failed";
+  if (privilegeRefused(result, parsed)) {
+    return new GwsError(
+      "ADMIN_PRIVILEGE_REQUIRED",
+      `Google accepted the sign-in but refused the call, because the account lacks a Workspace admin privilege; signing in again as the same account cannot help (gws: ${message.slice(0, 300)})`,
+      { next: `${remediation.privilege.charAt(0).toUpperCase()}${remediation.privilege.slice(1)}.` }
+    );
+  }
+  const problem = authProblem(result, parsed) ?? (result.exitCode === EXIT.auth ? "AUTH_REQUIRED" : void 0);
+  if (problem === "AUTH_SCOPE_MISSING") {
+    return new GwsError("AUTH_SCOPE_MISSING", `the credential lacks a scope for this operation; ${remediation.consent} (gws: ${message.slice(0, 300)})`);
+  }
+  if (problem === "AUTH_REQUIRED") {
+    return new GwsError("AUTH_REQUIRED", `the Google Workspace sign-in is missing or no longer valid; ${remediation.signIn} (gws: ${message.slice(0, 300)})`);
+  }
+  const disabled = disabledApi(result, parsed);
+  if (disabled) {
+    const where = disabled.project ? ` for project ${disabled.project}` : "";
+    const next = disabled.enableUrl ? `Ask the user to open ${disabled.enableUrl} and enable the API${where}, then wait about a minute and retry.` : `Ask the user to enable the API${where} in the Google Cloud console, then wait about a minute and retry.`;
+    return new GwsError("API_DISABLED", message.slice(0, 500), { next, ...disabled.enableUrl ? { enableUrl: disabled.enableUrl } : {} });
+  }
+  if (result.exitCode === EXIT.validation) return new GwsError("GWS_VALIDATION_ERROR", `gws rejected the request: ${message.slice(0, 500)}`);
+  if (result.exitCode === EXIT.discovery) return new GwsError("GWS_DISCOVERY_ERROR", `gws could not load the API description: ${message.slice(0, 500)}`);
+  if (result.exitCode === EXIT.internal) return new GwsError("GWS_INTERNAL_ERROR", `gws failed: ${message.slice(0, 500)}`);
+  return new GwsError("GWS_API_ERROR", message.slice(0, 500));
+}
+
 // src/host/commands.ts
 var COMMANDS = {
   status: { name: "gws-status", description: "Google Workspace: sign-in, access, pending plans, setup steps, and unguarded agents" },
@@ -8219,6 +8448,7 @@ function accountLines(account2) {
   lines.push(`Services: ${account2.services.join(", ") || "none"}`);
   if (account2.grantedScopes) lines.push(`Granted scopes: ${scopeList(account2.grantedScopes)}`);
   if (account2.missingScopes?.length) lines.push(`Scopes not granted: ${scopeList(account2.missingScopes)}`);
+  if (account2.delegationRequired?.length) lines.push(`${DELEGATION_LABEL}: ${delegationText(account2)}`);
   return lines;
 }
 function formatStatus(status2, plans = [], now = Date.now()) {
@@ -8289,6 +8519,8 @@ function nextFor(outcome) {
       return `enable it at ${outcome.enableUrl}, wait about a minute, and run /gws-doctor again`;
     case "DENIED":
       return "allow gws.read for this account in your permissions, or skip the check";
+    case "ADMIN_PRIVILEGE_REQUIRED":
+      return `sign in with a Workspace admin account that has ${privilegeName(outcome.service)}, or remove ${outcome.service} from accounts.${outcome.account}.enabledServices`;
     default:
       return void 0;
   }
@@ -8424,6 +8656,11 @@ function accessOptions(profile) {
   if (!offersWrite(profile)) return [read];
   return [read, { value: "write", label: "Read and write", description: `Requests: ${signInScopes(profile, "write").join(" ")}` }];
 }
+function delegationNote(alias, profile) {
+  const services = delegationRequired(profile.enabledServices, profile.scopes);
+  if (services.length === 0) return "";
+  return ` ${services.join(", ")} needs domain-wide delegation, which a Workspace admin sets up, so this sign-in requests none of its scopes; with delegation, add them to accounts.${alias}.scopes.`;
+}
 function defaultAccess(profile) {
   const access = profile.access;
   return access === "write" || typeof access === "object" && Object.values(access).includes("write") ? "write" : "read";
@@ -8500,7 +8737,7 @@ function signInForm(alias, profile, configured, redirect = {}) {
       key: "access",
       type: "string",
       title: "Access",
-      description: `What ${alias} may do in Google Workspace. Read-only cannot change, send, share, or delete anything.`,
+      description: `What ${alias} may do in Google Workspace. Read-only cannot change, send, share, or delete anything.${delegationNote(alias, profile)}`,
       required: true,
       default: defaultAccess(profile),
       options: accessOptions(profile)
@@ -9304,6 +9541,9 @@ var Diagnostics = object({
   bytes: number2().describe("Serialized size of data")
 }).describe("gws process facts");
 var FileInfo = object({ path: string2(), bytes: number2(), sha256: string2() }).describe("A local file the plugin delivered");
+var Restriction = _enum(["app-only", "domain-wide-delegation"]).describe(
+  "Why an ordinary Google sign-in cannot run this method: app-only needs a Chat app's or Classroom add-on's own credentials; domain-wide-delegation needs scopes a Workspace admin grants only through domain-wide delegation"
+);
 var CatalogEntry = object({
   kind: _enum(["service", "method", "helper"]),
   id: string2().describe("Pass a method or helper id as operation"),
@@ -9315,7 +9555,8 @@ var CatalogEntry = object({
   executable: boolean2().describe("The plugin can run it (a service: at least one of its operations); false for denied, deploy, and watch entries"),
   commitTool: string2().optional().describe('The tool that commits its plan, e.g. "gws_send"; absent for reads'),
   alternative: string2().optional().describe("For a helper that cannot run: the method id that does the same job"),
-  appOnly: literal(true).optional().describe("Only an app's own credentials (a Chat app or a Classroom add-on) can run it; a Google sign-in cannot")
+  appOnly: literal(true).optional().describe("Only an app's own credentials (a Chat app or a Classroom add-on) can run it; a Google sign-in cannot"),
+  restriction: Restriction.optional()
 });
 var CatalogOutput = object({
   entries: array(CatalogEntry),
@@ -9343,6 +9584,7 @@ var SchemaOutput = object({
   account: string2(),
   schema: ResolvedSchema.optional().describe("Present for a method"),
   appOnly: literal(true).optional().describe("Only an app's own credentials (a Chat app or a Classroom add-on) can run this method; a Google sign-in cannot"),
+  restriction: Restriction.optional(),
   helper: HelperEntry.extend({
     input: unknown().optional().describe("JSON Schema of the helper's input flags; absent when the helper cannot run")
   }).optional().describe("Present for a helper")
@@ -9392,177 +9634,6 @@ var CommitOutput = object({
   cleanupDegraded: boolean2().optional().describe("The change succeeded, but private staging cleanup failed; do not retry the mutation")
 });
 
-// src/domain/result.ts
-function isApiError(value) {
-  if (Array.isArray(value)) return value.some(isApiError);
-  if (!value || typeof value !== "object") return false;
-  const record2 = value;
-  return "error" in record2 && record2.error !== null && typeof record2.error === "object";
-}
-function parseJson(text3) {
-  const lines = text3.split("\n");
-  const start2 = lines.findIndex((line) => /^[[{]/.test(line.trim()));
-  if (start2 < 0) return void 0;
-  const candidate = lines.slice(start2).join("\n").trim();
-  try {
-    return JSON.parse(candidate);
-  } catch {
-    const parsed = [];
-    for (const line of lines.slice(start2)) {
-      const value = line.trim();
-      if (!/^[[{]/.test(value)) continue;
-      try {
-        parsed.push(JSON.parse(value));
-      } catch {
-      }
-    }
-    return parsed.length > 0 ? parsed : void 0;
-  }
-}
-function inlineCap(maxInlineBytes, mode, requested) {
-  const base2 = mode === "full" ? Math.max(maxInlineBytes, 5 * 1024 * 1024) : maxInlineBytes;
-  return requested === void 0 ? base2 : Math.min(base2, requested);
-}
-function parseResult(result, options) {
-  const text3 = result.stdout.toString("utf8");
-  const parsed = parseJson(text3);
-  const serialized = parsed === void 0 ? text3 : JSON.stringify(parsed);
-  const bytes2 = Buffer.byteLength(serialized);
-  const cap = inlineCap(options.maxInlineBytes, options.mode, options.requestedInlineBytes);
-  const truncated = bytes2 > cap;
-  const empty = text3.trim().length === 0;
-  return {
-    // A successful DELETE commonly returns 204 with no body. Empty output
-    // with exit 0 is success; non-JSON text is not a JSON result.
-    ok: result.exitCode === 0 && (empty || parsed !== void 0 && !isApiError(parsed)),
-    data: parsed,
-    raw: parsed === void 0 ? text3.slice(0, cap) : void 0,
-    truncated,
-    diagnostics: { exitCode: result.exitCode, durationMs: result.durationMs, bytes: bytes2 }
-  };
-}
-function itemKey(page2) {
-  if (!page2 || typeof page2 !== "object" || Array.isArray(page2)) return void 0;
-  const record2 = page2;
-  if (Array.isArray(record2["items"])) return "items";
-  const arrays = Object.keys(record2).filter((key) => Array.isArray(record2[key]));
-  return arrays.length === 1 ? arrays[0] : void 0;
-}
-function capPageItems(data, maxItems) {
-  const pages = data === void 0 ? [] : Array.isArray(data) ? data : [data];
-  const keys = pages.map((page2) => itemKey(page2) ?? (isEmptyPage(page2) ? null : void 0));
-  if (keys.some((key) => key === void 0)) return { data: pages, pages: pages.length, capped: false };
-  const kept = [];
-  let items = 0;
-  let capped = false;
-  for (const [index2, page2] of pages.entries()) {
-    if (items >= maxItems) {
-      capped = true;
-      break;
-    }
-    const key = keys[index2];
-    if (!key) {
-      kept.push(page2);
-      continue;
-    }
-    const record2 = page2;
-    const list = record2[key];
-    const room = maxItems - items;
-    if (list.length > room) {
-      const { nextPageToken: _dropped, ...rest } = record2;
-      kept.push({ ...rest, [key]: list.slice(0, room) });
-      items += room;
-      capped = true;
-      break;
-    }
-    kept.push(page2);
-    items += list.length;
-  }
-  return { data: kept, pages: kept.length, items, capped };
-}
-function isEmptyPage(page2) {
-  if (!page2 || typeof page2 !== "object" || Array.isArray(page2)) return false;
-  return !Object.values(page2).some(Array.isArray);
-}
-function redactDryRun(value) {
-  if (Array.isArray(value)) return value.map(redactDryRun);
-  if (value && typeof value === "object") {
-    const out = {};
-    for (const [key, child] of Object.entries(value)) {
-      if (/^(body|raw|content)$/i.test(key)) out[key] = "[redacted]";
-      else out[key] = redactDryRun(child);
-    }
-    return out;
-  }
-  return value;
-}
-function apiErrorOf(result, parsed) {
-  const data = parsed ? parsed.data : parseJson(result.stdout.toString("utf8"));
-  const found = Array.isArray(data) ? data.find(isApiError) : data;
-  if (!isApiError(found)) return void 0;
-  return found.error;
-}
-function stderrText(result) {
-  return result.stderr.toString("utf8").split("\n").filter((line) => line.trim() && !/^Using keyring backend:/i.test(line)).join("\n").trim();
-}
-var SCOPE_REASONS = /* @__PURE__ */ new Set(["ACCESS_TOKEN_SCOPE_INSUFFICIENT", "insufficientPermissions"]);
-function authProblem(result, parsed) {
-  if (result.timedOut || result.outputCapped) return void 0;
-  const error2 = apiErrorOf(result, parsed);
-  if (result.exitCode === 0 && !error2) return void 0;
-  const reasons = [error2?.reason, ...(error2?.errors ?? []).map((item) => item?.reason), ...(error2?.details ?? []).map((item) => item?.reason)];
-  const text3 = [error2?.message, error2?.status, stderrText(result)].filter(Boolean).join("\n");
-  if (reasons.some((reason) => reason !== void 0 && SCOPE_REASONS.has(reason)) || /insufficient authentication scopes|ACCESS_TOKEN_SCOPE_INSUFFICIENT/i.test(text3)) {
-    return "AUTH_SCOPE_MISSING";
-  }
-  if (error2?.code === 401 || error2?.status === "UNAUTHENTICATED" || reasons.includes("authError") || /invalid_grant|\bUNAUTHENTICATED\b|^error\[auth\]/im.test(text3)) {
-    return "AUTH_REQUIRED";
-  }
-  return void 0;
-}
-var GENERIC_REMEDIATION = {
-  signIn: "sign in to the account again",
-  consent: "sign in again and grant the scope this operation needs"
-};
-var EXIT = { auth: 2, validation: 3, discovery: 4, internal: 5 };
-var DISABLED_REASONS = /* @__PURE__ */ new Set(["accessNotConfigured", "SERVICE_DISABLED"]);
-var CONSOLE_URL = /https:\/\/console\.(?:developers|cloud)\.google\.com\/[^\s"'<>)]+/;
-function disabledApi(result, parsed) {
-  const error2 = apiErrorOf(result, parsed);
-  const reasons = [error2?.reason, ...(error2?.errors ?? []).map((item) => item?.reason), ...(error2?.details ?? []).map((item) => item?.reason)];
-  const text3 = [error2?.message, stderrText(result)].filter(Boolean).join("\n");
-  if (!reasons.some((reason) => reason !== void 0 && DISABLED_REASONS.has(reason)) && !/accessnotconfigured|has not been used|is disabled/i.test(text3)) {
-    return void 0;
-  }
-  const enableUrl = (typeof error2?.enable_url === "string" && CONSOLE_URL.test(error2.enable_url) ? error2.enable_url : CONSOLE_URL.exec(text3)?.[0])?.replace(/[.,;]+$/, "");
-  const project = (enableUrl ? /[?&]project=([\w.:-]+)/.exec(enableUrl)?.[1] : void 0) ?? /\bin project ([\w.:-]+)/.exec(text3)?.[1];
-  return { ...enableUrl ? { enableUrl } : {}, ...project ? { project } : {} };
-}
-function processError(result, parsed, remediation = GENERIC_REMEDIATION) {
-  if (result.timedOut) return new GwsError("TIMEOUT", `gws did not finish within the configured execution.timeoutMs (${result.durationMs}ms elapsed)`);
-  if (result.outputCapped) return new GwsError("OUTPUT_LIMIT", "gws output exceeded execution.maxStdoutBytes/maxStderrBytes; narrow fields or pagination");
-  const stderr = stderrText(result);
-  const payload = apiErrorOf(result, parsed);
-  const message = payload?.message || stderr || "gws command failed";
-  const problem = authProblem(result, parsed) ?? (result.exitCode === EXIT.auth ? "AUTH_REQUIRED" : void 0);
-  if (problem === "AUTH_SCOPE_MISSING") {
-    return new GwsError("AUTH_SCOPE_MISSING", `the credential lacks a scope for this operation; ${remediation.consent} (gws: ${message.slice(0, 300)})`);
-  }
-  if (problem === "AUTH_REQUIRED") {
-    return new GwsError("AUTH_REQUIRED", `the Google Workspace sign-in is missing or no longer valid; ${remediation.signIn} (gws: ${message.slice(0, 300)})`);
-  }
-  const disabled = disabledApi(result, parsed);
-  if (disabled) {
-    const where = disabled.project ? ` for project ${disabled.project}` : "";
-    const next = disabled.enableUrl ? `Ask the user to open ${disabled.enableUrl} and enable the API${where}, then wait about a minute and retry.` : `Ask the user to enable the API${where} in the Google Cloud console, then wait about a minute and retry.`;
-    return new GwsError("API_DISABLED", message.slice(0, 500), { next, ...disabled.enableUrl ? { enableUrl: disabled.enableUrl } : {} });
-  }
-  if (result.exitCode === EXIT.validation) return new GwsError("GWS_VALIDATION_ERROR", `gws rejected the request: ${message.slice(0, 500)}`);
-  if (result.exitCode === EXIT.discovery) return new GwsError("GWS_DISCOVERY_ERROR", `gws could not load the API description: ${message.slice(0, 500)}`);
-  if (result.exitCode === EXIT.internal) return new GwsError("GWS_INTERNAL_ERROR", `gws failed: ${message.slice(0, 500)}`);
-  return new GwsError("GWS_API_ERROR", message.slice(0, 500));
-}
-
 // src/domain/status.ts
 var AccountStatus = object({
   alias: string2(),
@@ -9575,6 +9646,7 @@ var AccountStatus = object({
   clientSource: _enum(["account", "plugin", "pasted"]).optional().describe("Where the sign-in's OAuth client comes from"),
   grantedScopes: array(string2()).optional().describe("Scopes Google granted to the current sign-in"),
   missingScopes: array(string2()).optional().describe("Scopes the enabled services need at this access level that were not granted"),
+  delegationRequired: array(string2()).optional().describe("Enabled services that need domain-wide delegation, which a Workspace admin sets up; the sign-in requests none of their scopes unless accounts.<alias>.scopes adds them"),
   nextStep: string2().optional().describe("What to do next; absent when nothing is needed")
 });
 var StatusOutput = object({
@@ -9821,6 +9893,12 @@ var Description = strictObject({
     })
   )
 });
+function sessionNotFound(error2) {
+  if (error2 === null || typeof error2 !== "object") return false;
+  const record2 = error2;
+  const tag = record2["_tag"] ?? record2["name"];
+  return tag === "Session.NotFoundError" || tag === "SessionNotFoundError" || record2["status"] === 404 || record2["statusCode"] === 404;
+}
 async function registerScripting(ctx, runtime, status2) {
   const assert2 = async (request) => {
     try {
@@ -9836,8 +9914,8 @@ async function registerScripting(ctx, runtime, status2) {
     try {
       agent = (await runtime.wait(() => ctx.session.get({ sessionID }), signal)).agent;
     } catch (error2) {
-      if (GwsError.from(error2)?.code === "CANCELLED") throw error2;
-      throw new GwsError("SESSION_UNKNOWN", `there is no session '${sessionID}'`);
+      if (sessionNotFound(error2)) throw new GwsError("SESSION_UNKNOWN", `there is no session '${sessionID}'`);
+      throw error2;
     }
     if (!agent) throw new GwsError("SESSION_AGENT_REQUIRED", `session '${sessionID}' names no agent`);
     return { sessionID, agent, script: true };
@@ -10438,10 +10516,17 @@ var PROBES = {
   "admin-reports": { operation: "admin-reports.activities.list", params: { userKey: "all", applicationName: "login", maxResults: 1, fields: "items(id)" } },
   script: { operation: "script.processes.list", params: { pageSize: 1, fields: "processes(processType)" } }
 };
-function doctorTarget(account2, service) {
+function doctorTarget(account2, service, needsDelegation = false) {
+  if (needsDelegation) return { account: account2, service, needsDelegation: true };
   const probe = PROBES[service];
   return probe ? { account: account2, service, operation: probe.operation } : { account: account2, service };
 }
+function skipDetail(target) {
+  if (target.needsDelegation) {
+    return `${target.service} needs domain-wide delegation, which a Workspace admin sets up; with it, add ${target.service} or ${target.service}.readonly to accounts.${target.account}.scopes and sign in again`;
+  }
+  return "no read-only check exists for this service";
+}
 function probeArgv(target) {
   const probe = PROBES[target.service];
   const entry = probe ? commandIndex().methods.get(probe.operation) : void 0;
@@ -10452,6 +10537,9 @@ var DISABLED = /accessNotConfigured|SERVICE_DISABLED|has not been used in projec
 function probeOutcome(target, result) {
   const parsed = parseResult(result, { maxInlineBytes: 64 * 1024 });
   if (parsed.ok) return { ...target, status: "OK" };
+  if (privilegeRefused(result, parsed)) {
+    return { ...target, status: "ADMIN_PRIVILEGE_REQUIRED", detail: "Google accepted the sign-in, but the account lacks the Workspace admin privilege this service needs" };
+  }
   const problem = authProblem(result, parsed);
   if (problem === "AUTH_REQUIRED") return { ...target, status: problem, detail: "Google rejected the sign-in" };
   if (problem === "AUTH_SCOPE_MISSING") return { ...target, status: problem, detail: "Google says the sign-in lacks a scope for this service" };
@@ -10546,6 +10634,7 @@ var Accounts = class {
           mode: profile.mode,
           services: profile.enabledServices,
           ...profile.mode === "interactive" ? { integrationID } : {},
+          ...delegationField(profile),
           ...signIn
         };
       })
@@ -10612,9 +10701,14 @@ var Accounts = class {
     return credential;
   }
   scopeMissing(account2, profile, operation, accepted) {
-    if (appOnly(operation)) {
+    const reason = restriction(operation);
+    if (reason === "app-only") {
       return `AUTH_SCOPE_MISSING: ${operation} needs a scope Google grants only to an app's own credentials (a Chat app or a Classroom add-on), never to a person's sign-in, so '${account2}' cannot run it. Next step: Tell the user this method cannot run with a Google sign-in, and use another method.`;
     }
+    if (reason === "domain-wide-delegation") {
+      const named2 = accepted.map(shortScope).join(" or ");
+      return `AUTH_SCOPE_MISSING: ${operation} needs ${named2}, which Google grants only through domain-wide delegation that a Workspace admin sets up, and the sign-in for '${account2}' has not granted it. Next step: Tell the user this method needs domain-wide delegation; once their admin has set it up, they add ${named2} to accounts.${account2}.scopes and sign in again.`;
+    }
     const read = signInScopes(profile, "read");
     const named = accepted.slice(0, 5).map(shortScope).join(", ");
     const connect2 = this.connect(account2);
@@ -10631,24 +10725,27 @@ var Accounts = class {
   accountDir(account2) {
     return ownedDir(join6(this.runtime.paths.cacheDir, "accounts", this.integrationId(account2).replace(/^gws-/, "")));
   }
-  /** Remediation text for an account's sign-in and consent problems, by credential mode. */
-  remediation(account2, scopes) {
+  /** Remediation text for an account's sign-in, consent and admin privilege problems, by credential mode. */
+  remediation(account2, scopes, service) {
     const profile = this.runtime.config.accounts[account2];
     const named = scopes && scopes.length > 0 ? scopes.slice(0, 5).map(shortScope).join(", ") : void 0;
     const grant = named ? `include one of: ${named}` : "include the scope this operation needs";
+    const admin = `a Workspace admin account that has ${privilegeName(service)}`;
+    const remove = `remove ${service ?? "the service"} from accounts.${account2}.enabledServices`;
     if (profile?.mode === "credentials_file") {
       const source = profile.credentialsFileEnv ? `the credentials file named by ${profile.credentialsFileEnv}` : "the credentials file";
-      return { signIn: `replace ${source}`, consent: `replace ${source} with one whose grant can ${grant}` };
+      return { signIn: `replace ${source}`, consent: `replace ${source} with one whose grant can ${grant}`, privilege: `replace ${source} with one for ${admin}, or ${remove}` };
     }
     if (profile?.mode === "access_token") {
       const source = profile.tokenEnv ? `the access token in ${profile.tokenEnv}` : "the access token";
-      return { signIn: `refresh ${source}`, consent: `mint ${source} with scopes that ${grant}` };
+      return { signIn: `refresh ${source}`, consent: `mint ${source} with scopes that ${grant}`, privilege: `mint ${source} for ${admin}, or ${remove}` };
     }
     const connect2 = this.connect(account2);
     const extra = named ? `, or add one of ${named} to accounts.${account2}.scopes` : "";
     return {
       signIn: `to sign in again, ${connect2}`,
-      consent: `to grant the scope, ${connect2}, sign in again, and approve every scope, choosing Read and write for a change${extra}`
+      consent: `to grant the scope, ${connect2}, sign in again, and approve every scope, choosing Read and write for a change${extra}`,
+      privilege: `sign in with ${admin} (${connect2}), or ${remove}`
     };
   }
   authMessage(account2, code2, scopes) {
@@ -10667,11 +10764,13 @@ var Accounts = class {
   /** Every account and enabled service /gws-doctor checks, in config order. */
   doctorTargets() {
     this.runtime.assertActive();
-    return Object.entries(this.runtime.config.accounts).flatMap(([alias, profile]) => profile.enabledServices.map((service) => doctorTarget(alias, service)));
+    return Object.entries(this.runtime.config.accounts).flatMap(
+      ([alias, profile]) => profile.enabledServices.map((service) => doctorTarget(alias, service, profile.mode === "interactive" && delegationRequired([service], profile.scopes).length > 0))
+    );
   }
   /** Run one /gws-doctor probe as the account. A failure becomes an outcome, never a throw, except cancellation. */
   async probe(target, ctx) {
-    if (!target.operation) return { ...target, status: "SKIPPED", detail: "no read-only check exists for this service" };
+    if (!target.operation) return { ...target, status: "SKIPPED", detail: skipDetail(target) };
     const started = Date.now();
     try {
       const result = await this.run(probeArgv(target), target.account, target.operation, ctx);
@@ -10712,6 +10811,11 @@ function report2(ctx, update) {
   } catch {
   }
 }
+function delegationField(profile) {
+  if (profile.mode !== "interactive") return {};
+  const services = delegationRequired(profile.enabledServices, profile.scopes);
+  return services.length > 0 ? { delegationRequired: services } : {};
+}
 function capitalize(text3) {
   return text3.charAt(0).toUpperCase() + text3.slice(1);
 }
@@ -11371,7 +11475,7 @@ var Operations = class {
     report2(ctx, { status: "running", operation: entry.id });
     const schema = await this.runtime.schema.resolve(entry.service, [...entry.path, entry.method], ctx.signal);
     this.runtime.assertActive(ctx.signal);
-    return { ok: true, account: target.account, schema, ...appOnly(entry.id) ? { appOnly: true } : {} };
+    return { ok: true, account: target.account, schema, ...restrictionMarks(entry.id) };
   }
   /** Validate a commit against its stored plan without consuming it. */
   inspectPlan(category, input, ctx) {
@@ -11396,7 +11500,7 @@ var Operations = class {
         requestedInlineBytes: helper ? void 0 : request.response?.maxInlineBytes
       });
       const failed = helper ? result.exitCode !== 0 || isApiError(parsed.data) : !parsed.ok;
-      if (failed) throw processError(result, parsed, this.accounts.remediation(request.account, entry.scopes));
+      if (failed) throw processError(result, parsed, this.accounts.remediation(request.account, entry.scopes, entry.service));
       const pages = paged ? capPageItems(parsed.data, itemCap(request, limits)) : void 0;
       const cap = inlineCap(this.runtime.config.execution.maxInlineBytes, request.response?.mode, request.response?.maxInlineBytes);
       const truncated = pages ? Buffer.byteLength(JSON.stringify(pages.data)) > cap : parsed.truncated;
@@ -11460,7 +11564,7 @@ var Operations = class {
       const dry = await this.accounts.run(dryRunArgv, request.account, entry.id, ctx, { scopes: entry.scopes, dryRun: true, cwd: stage?.dir });
       report2(ctx, { status: "parsing", operation: entry.id });
       parsed = parseResult(dry, { maxInlineBytes: this.runtime.config.execution.maxInlineBytes });
-      if (dry.exitCode !== 0 || !parsed.ok) throw processError(dry, parsed, this.accounts.remediation(request.account, entry.scopes));
+      if (dry.exitCode !== 0 || !parsed.ok) throw processError(dry, parsed, this.accounts.remediation(request.account, entry.scopes, entry.service));
     } finally {
       await stage?.dispose();
     }
@@ -11518,11 +11622,12 @@ var Operations = class {
         refuseChanged(plan.files.inputs, staged);
         if (plan.files.output) await stage.prepareOutput(plan.files.output);
       }
-      const scopes = commandIndex().methods.get(plan.operation)?.scopes;
+      const method = commandIndex().methods.get(plan.operation);
+      const scopes = method?.scopes;
       const result = await this.accounts.run(plan.argv, plan.account, plan.operation, ctx, { scopes, cwd: stage?.dir });
       report2(ctx, { status: "parsing", operation: plan.operation });
       const parsed = parseResult(result, { maxInlineBytes: this.runtime.config.execution.maxInlineBytes });
-      if (!parsed.ok) throw processError(result, parsed, this.accounts.remediation(plan.account, scopes));
+      if (!parsed.ok) throw processError(result, parsed, this.accounts.remediation(plan.account, scopes, method?.service));
       const delivered = stage && plan.files?.output ? await stage.deliver(plan.files.output, plan.files.limits) : void 0;
       const file = delivered ? { path: delivered.path, bytes: delivered.bytes, sha256: delivered.sha256 } : void 0;
       this.runtime.plans.complete(plan.id);

package/dist/tui.js

@@ -31,6 +31,7 @@ var account = object(
     clientSource: { enum: CLIENT_SOURCES },
     grantedScopes: texts,
     missingScopes: texts,
+    delegationRequired: texts,
     nextStep: text
   },
   ["alias", "mode", "services", "connected"]
@@ -65,7 +66,7 @@ var isStrings = (value) => Array.isArray(value) && value.every((entry) => typeof
 var optional = (value, check) => value === void 0 || check(value);
 var isText = (value) => typeof value === "string";
 function isAccount(value) {
-  return isRecord(value) && isText(value["alias"]) && MODES.includes(value["mode"]) && isStrings(value["services"]) && typeof value["connected"] === "boolean" && optional(value["integrationID"], isText) && optional(value["needsAuth"], (entry) => entry === true) && optional(value["access"], (entry) => ACCESS.includes(entry)) && optional(value["clientSource"], (entry) => CLIENT_SOURCES.includes(entry)) && optional(value["grantedScopes"], isStrings) && optional(value["missingScopes"], isStrings) && optional(value["nextStep"], isText);
+  return isRecord(value) && isText(value["alias"]) && MODES.includes(value["mode"]) && isStrings(value["services"]) && typeof value["connected"] === "boolean" && optional(value["integrationID"], isText) && optional(value["needsAuth"], (entry) => entry === true) && optional(value["access"], (entry) => ACCESS.includes(entry)) && optional(value["clientSource"], (entry) => CLIENT_SOURCES.includes(entry)) && optional(value["grantedScopes"], isStrings) && optional(value["missingScopes"], isStrings) && optional(value["delegationRequired"], isStrings) && optional(value["nextStep"], isText);
 }
 function isStatus(value) {
   return isRecord(value) && isText(value["pluginVersion"]) && isText(value["hostVersion"]) && optional(value["hostWarning"], isText) && isRecord(value["gws"]) && isText(value["gws"]["path"]) && isText(value["gws"]["version"]) && isStrings(value["services"]) && Array.isArray(value["accounts"]) && value["accounts"].every(isAccount) && optional(value["auditDegraded"], (entry) => typeof entry === "boolean") && isStrings(value["unguardedAgents"]) && optional(value["permissionsBlock"], isText) && optional(value["nextStep"], isText);
@@ -78,6 +79,11 @@ function connectionLabel(account2) {
 function openCodeLabel(status2) {
   return status2.hostWarning ? `${status2.hostVersion} (host untested: ${status2.hostWarning})` : `${status2.hostVersion} (tested)`;
 }
+var DELEGATION_LABEL = "Needs domain-wide delegation";
+function delegationText(account2) {
+  const services = account2.delegationRequired ?? [];
+  return `${services.join(", ")} (a Workspace admin sets it up; then add the scopes to accounts.${account2.alias}.scopes)`;
+}
 var BLOCK_PLACEMENT = "Put this block first in that agent's own permissions, followed by your top-level rules for gws actions. Never put it in the top-level permissions: that would loosen Explore.";
 
 // src/tui.tsx
@@ -248,6 +254,23 @@ function AccountStatus(props) {
         }
       })
     }), null);
+    _$insert(_el$4, _$createComponent(Show, {
+      get when() {
+        return _$memo(() => !!props.account.delegationRequired?.length)() ? props.account : void 0;
+      },
+      children: (account2) => _$createComponent(Row, {
+        label: DELEGATION_LABEL,
+        get value() {
+          return delegationText(account2());
+        },
+        get fg() {
+          return muted();
+        },
+        get muted() {
+          return muted();
+        }
+      })
+    }), null);
     return _el$4;
   })();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joe-broadhead/opencode-gws",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Unofficial OpenCode plugin for Google Workspace (gws CLI)",
   "type": "module",
   "license": "MIT",
@@ -50,10 +50,10 @@
     "docs:coverage": "node scripts/generate-docs.mjs"
   },
   "optionalDependencies": {
-    "@joe-broadhead/opencode-gws-bin-darwin-arm64": "0.0.1",
-    "@joe-broadhead/opencode-gws-bin-darwin-x64": "0.0.1",
-    "@joe-broadhead/opencode-gws-bin-linux-arm64-gnu": "0.0.1",
-    "@joe-broadhead/opencode-gws-bin-linux-x64-gnu": "0.0.1"
+    "@joe-broadhead/opencode-gws-bin-darwin-arm64": "0.0.2",
+    "@joe-broadhead/opencode-gws-bin-darwin-x64": "0.0.2",
+    "@joe-broadhead/opencode-gws-bin-linux-arm64-gnu": "0.0.2",
+    "@joe-broadhead/opencode-gws-bin-linux-x64-gnu": "0.0.2"
   },
   "devDependencies": {
     "@babel/core": "7.29.7",

package/skills/opencode-gws/SKILL.md

@@ -13,7 +13,7 @@ Call `gws_status` before the first Workspace call in a session. It lists account
 
 Omit `account` when `gws_status` shows one account. Pass the alias when it shows more than one. A missing alias is `ACCOUNT_REQUIRED`. An unknown alias is `ACCOUNT_UNKNOWN`.
 
-An account signs in Read-only or Read and write; `gws_status` shows which. The `default` account defaults to Read and write, which covers every method a Google sign-in can run. An operation whose scopes were not granted fails with `AUTH_SCOPE_MISSING` before anything runs: ask the user to sign in again, approve every scope Google lists, and choose Read and write if the error says so. Do not invent a scope. A method that `gws_catalog` or `gws_schema` marks `appOnly` needs a Chat app's or Classroom add-on's own credentials; no sign-in can run it, so use another method.
+An account signs in Read-only or Read and write; `gws_status` shows which. The `default` account defaults to Read and write, which covers every method a Google sign-in can run. An operation whose scopes were not granted fails with `AUTH_SCOPE_MISSING` before anything runs: ask the user to sign in again, approve every scope Google lists, and choose Read and write if the error says so. Do not invent a scope. A method that `gws_catalog` or `gws_schema` marks `appOnly` (`restriction: "app-only"`) needs a Chat app's or Classroom add-on's own credentials; no sign-in can run it, so use another method. A method marked `restriction: "domain-wide-delegation"` (every Keep method) runs only when a Workspace admin has set up domain-wide delegation and `accounts.<alias>.scopes` adds a Keep scope; otherwise tell the user so.
 
 Not signed in: `AUTH_REQUIRED`. The next step is to run `/connect` and choose Google Workspace, or `opencode auth login gws-<alias>`.
 
@@ -115,6 +115,7 @@ An error is `CODE: What happened. Next step: What to do.` Do the next step once.
 | --- | --- |
 | `AUTH_REQUIRED` | Ask the user to sign in as the message says, then retry. |
 | `AUTH_SCOPE_MISSING` | Ask the user to sign in again with the access the message names, or to add the scope. Nothing ran. |
+| `ADMIN_PRIVILEGE_REQUIRED` | The sign-in is valid; the account lacks the Workspace admin privilege the API needs. Do not ask the user to sign in again as the same account. Tell them the message's next step. |
 | `API_DISABLED` | Ask the user to enable the API at the URL in the message, wait about a minute, and retry. |
 | `OPERATION_UNKNOWN` | The id is not in the catalog. Search again with `gws_catalog`. |
 | `HELPER_UNSUPPORTED` | The helper cannot run. Use the method `gws_catalog` names as `alternative`. |

package/skills/opencode-gws-admin/SKILL.md

@@ -26,7 +26,7 @@ Plugin policy cannot allow an admin call. A policy rule can only deny.
 
 ## Admin reports
 
-Read-only at both access levels. The sign-in still needs the admin report scopes from the auth doc.
+Read-only at both access levels. The sign-in still needs the admin report scopes from the auth doc, and the account must be a Workspace admin with the Reports privilege: otherwise every call fails with `ADMIN_PRIVILEGE_REQUIRED`, which signing in again as the same account does not fix.
 
 Activity list, read. `fields` is required because this is a list: