@joe-broadhead/opencode-gws 0.0.0 → 0.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joe-broadhead/opencode-gws",
-  "version": "0.0.0",
+  "version": "0.0.1",
   "description": "Unofficial OpenCode plugin for Google Workspace (gws CLI)",
   "type": "module",
   "license": "MIT",
@@ -28,6 +28,7 @@
     "dist",
     "skills",
     "manifest/generated.json",
+    "views",
     "README.md",
     "LICENSE",
     "NOTICE",
@@ -49,10 +50,10 @@
     "docs:coverage": "node scripts/generate-docs.mjs"
   },
   "optionalDependencies": {
-    "@joe-broadhead/opencode-gws-bin-darwin-arm64": "0.0.0",
-    "@joe-broadhead/opencode-gws-bin-darwin-x64": "0.0.0",
-    "@joe-broadhead/opencode-gws-bin-linux-arm64-gnu": "0.0.0",
-    "@joe-broadhead/opencode-gws-bin-linux-x64-gnu": "0.0.0"
+    "@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"
   },
   "devDependencies": {
     "@babel/core": "7.29.7",
@@ -71,5 +72,110 @@
     "typescript": "5.9.3",
     "vitest": "5.0.5",
     "zod": "4.6.7"
+  },
+  "jelly": {
+    "title": "Google Workspace",
+    "tools": [
+      {
+        "name": "gws.status",
+        "permission": "gws.status",
+        "effect": "allow",
+        "readOnly": true
+      },
+      {
+        "name": "gws.catalog",
+        "permission": "gws.catalog",
+        "effect": "allow",
+        "readOnly": true
+      },
+      {
+        "name": "gws.schema",
+        "permission": "gws.schema",
+        "effect": "allow",
+        "readOnly": true
+      },
+      {
+        "name": "gws.read",
+        "permission": "gws.read",
+        "effect": "allow",
+        "readOnly": true
+      },
+      {
+        "name": "gws.plan",
+        "permission": "gws.plan",
+        "effect": "allow",
+        "readOnly": true
+      },
+      {
+        "name": "gws.write",
+        "permission": "gws.write",
+        "effect": "ask",
+        "readOnly": false
+      },
+      {
+        "name": "gws.export",
+        "permission": "gws.export",
+        "effect": "ask",
+        "readOnly": false
+      },
+      {
+        "name": "gws.send",
+        "permission": "gws.send",
+        "effect": "ask",
+        "readOnly": false
+      },
+      {
+        "name": "gws.share",
+        "permission": "gws.share",
+        "effect": "ask",
+        "readOnly": false
+      },
+      {
+        "name": "gws.delete",
+        "permission": "gws.delete",
+        "effect": "ask",
+        "readOnly": false
+      },
+      {
+        "name": "gws.admin",
+        "permission": "gws.admin",
+        "effect": "ask",
+        "readOnly": false
+      }
+    ],
+    "skills": [
+      "opencode-gws",
+      "opencode-gws-recipes",
+      "opencode-gws-admin"
+    ],
+    "rpc": [],
+    "views": [
+      {
+        "v": 1,
+        "id": "gmail-thread",
+        "place": "tool-result",
+        "tools": [
+          "gws_read"
+        ],
+        "title": "Gmail thread",
+        "page": "views/gmail-thread.html",
+        "grants": [
+          "data"
+        ]
+      }
+    ],
+    "signIns": [
+      {
+        "id": "google",
+        "label": "Google Workspace",
+        "integration": "gws-*"
+      }
+    ],
+    "contributes": {
+      "homeFeeds": [],
+      "homeWidgets": [],
+      "workKinds": [],
+      "settings": []
+    }
   }
 }

package/skills/opencode-gws/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: opencode-gws
-description: Use when working with Google Workspace accounts, reads, plans, commits, approvals, or errors.
+description: Use when working with Google Workspace accounts, reads, plans, commits, approvals, errors, or scripts that call these tools without a model.
 ---
 
 # Google Workspace
@@ -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`.
 
-The default sign-in is read-only. A write, send, share, delete, or export whose scopes were not granted fails with `AUTH_SCOPE_MISSING` before anything runs. Ask the user to sign in again with Read and write, or to add the scope named in the error. Do not invent a scope.
+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.
 
 Not signed in: `AUTH_REQUIRED`. The next step is to run `/connect` and choose Google Workspace, or `opencode auth login gws-<alias>`.
 
@@ -88,6 +88,25 @@ Add this block first in **that agent's own** `permissions`, then any rules the u
 
 Do not put that block in the top-level `permissions`. Top-level rules apply after every agent's base rules and would loosen Explore.
 
+## Scripts
+
+When the user wants a job that runs without you, such as a cron job, a shell script, or another program, it can call these tools through the OpenCode server. The RPC `google-workspace.gws.tools` has one method per tool, with the same input and output: `status`, `catalog`, `schema`, `read`, and `plan` are `gws_status`, `gws_catalog`, `gws_schema`, `gws_read`, and `gws_plan`. `describe` lists the methods with their input and output as JSON Schema. The commit tools are not methods: a script can plan, but only a commit tool, approved in the plan's session, applies the change.
+
+A script runs as a session that names an agent, under that agent's permission rules and the session's own. Have the script create its session once, with `opencode api post /api/session` and a body such as `{"title":"mail digest","agent":"build"}`, then keep the returned id. Session rules can narrow the script further, for example a deny on `gws.*` followed by an allow on `gws.read` for `personal:gmail.users.messages.list`.
+
+Each call is `opencode api post /api/rpc/google-workspace.gws.tools/<method>` with this body:
+
+```json
+{
+  "input": {
+    "sessionID": "SESSION_ID",
+    "input": { "operation": "gmail.users.messages.list", "params": { "userId": "me", "q": "is:unread" }, "fields": "messages(id),nextPageToken" }
+  }
+}
+```
+
+The result is `{ "output": ... }`, the tool's output, with the same untrusted Workspace content. A refusal is the error `failed`, with `data.code` and `data.next` from the table below. No one answers a prompt for a script, so an ask on its call is refused with `PERMISSION_DENIED`: the script needs an allow rule, or no rule, for what it does. Reads have no ask rule.
+
 ## Errors
 
 An error is `CODE: What happened. Next step: What to do.` Do the next step once. Do not loop.
@@ -102,3 +121,6 @@ An error is `CODE: What happened. Next step: What to do.` Do the next step once.
 | `POLICY_DENIED` | Stop. Tell the user. Do not rephrase the call to get around the deny. |
 | `GWS_VALIDATION_ERROR` | Fix the request. `gws_schema` shows the parameters. List and search need `fields`. |
 | `CANCELLED` | Do not retry unless the user asks. A commit that was already running may have been applied. Check with `gws_read` before planning again. |
+| `SESSION_UNKNOWN` | A script named a session that does not exist. Have it create a session and keep that id. |
+| `SESSION_AGENT_REQUIRED` | The script's session names no agent. Create the session with `agent`. |
+| `PERMISSION_DENIED` | The agent's or the session's rules deny the script's call, or would ask. Tell the user. An allow rule for that action is the fix; do not route around it. |

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

@@ -14,7 +14,7 @@ Search with `gws_catalog` and check `gws_schema` before you call. If `executable
 
 An operation whose category is `admin` needs all of these before `gws_plan` will accept it:
 
-1. `admin.enabled` is true.
+1. `admin.enabled` is true, which is the default.
 2. The service is in `admin.allowedServices` (the default list is the services that have an admin-class entry).
 3. The plan includes a non-empty `reason` when `admin.requireReason` is true, which is the default.
 
@@ -76,7 +76,7 @@ Most subscription methods never run. A status read can:
 
 ## Model Armor
 
-No access level requests Model Armor scopes. The account needs `https://www.googleapis.com/auth/cloud-platform` in `scopes`, and the user must sign in again so the grant is on the token. The Model Armor helpers cannot run. Do not invent a call. Tell the user, and use `gws_catalog` if they still want a Discovery method.
+Read and write requests `https://www.googleapis.com/auth/cloud-platform` for Model Armor; Read-only requests nothing for it. The Model Armor helpers cannot run. Do not invent a call. Tell the user, and use `gws_catalog` if they still want a Discovery method.
 
 ## Workflow
 

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

@@ -23,6 +23,26 @@ Unread inbox, read:
 }
 ```
 
+Mail between two times, read. `after:` and `before:` take Unix seconds; `newer_than:` and `older_than:` take only days, months, or years:
+
+```json
+{
+  "operation": "gmail.users.messages.list",
+  "params": { "userId": "me", "q": "after:1767225600 before:1767312000", "maxResults": 100 },
+  "fields": "messages(id,threadId),nextPageToken"
+}
+```
+
+Sender, subject, and date of one message, read, without the body:
+
+```json
+{
+  "operation": "gmail.users.messages.get",
+  "params": { "userId": "me", "id": "MESSAGE_ID", "format": "metadata", "metadataHeaders": ["From", "Subject"] },
+  "fields": "id,threadId,snippet,internalDate,payload/headers"
+}
+```
+
 One message, read. Prefer the helper when you want the text, not the raw payload:
 
 ```json

package/views/gmail-thread.html

@@ -0,0 +1,193 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Gmail thread</title>
+<style>
+  :root { color: var(--jelly-text, #222); background: var(--jelly-surface, #fff); font: 14px/1.45 var(--jelly-font, system-ui, sans-serif); }
+  body { margin: 0; padding: 12px 14px; }
+  h1 { font-size: 15px; font-weight: 600; margin: 0 0 10px; }
+  ol { list-style: none; margin: 0; padding: 0; display: grid; gap: 10px; }
+  li { border: 1px solid var(--jelly-border, #ddd); border-radius: var(--jelly-radius, 8px); background: var(--jelly-raised, transparent); padding: 10px 12px; }
+  .head { display: flex; flex-wrap: wrap; gap: 4px 12px; justify-content: space-between; margin-bottom: 6px; }
+  .from { font-weight: 600; overflow-wrap: anywhere; }
+  .at, .note { color: var(--jelly-muted, #666); font-size: 12px; }
+  .body { white-space: pre-wrap; overflow-wrap: anywhere; margin: 0; }
+</style>
+</head>
+<body>
+<main id="thread" aria-live="polite"></main>
+<script>
+// jelly-view.js: a client of Jelly's view bridge. Paste it into the page's own <script>:
+// a sealed page loads no script by URL and is given no global. Call jellyView() as the
+// script starts; it resolves with the client when the app says hello.
+function jellyView() {
+  return new Promise((resolve) => {
+    addEventListener("message", function hello(event) {
+      const said = event.data;
+      if (event.source !== parent || said?.v !== 1 || said.kind !== "hello" || !event.ports[0])
+        return;
+      removeEventListener("message", hello);
+      const port = event.ports[0];
+      const listeners = new Set();
+      const latest = new Map();
+      const queue = [];
+      let sequence = 0;
+      let current;
+      const theme = (tokens) => {
+        const style = document.documentElement.style;
+        for (const [name, value] of Object.entries(tokens))
+          if (name === "scheme") style.colorScheme = value;
+          else style.setProperty(`--jelly-${name}`, value);
+      };
+      // The app answers one request at a time, so requests go in turn.
+      const next = () => {
+        if (current !== undefined || queue.length === 0) return;
+        current = queue.shift();
+        current.timer = setTimeout(
+          () => settle({ ok: false, error: "No answer from the app" }),
+          15000,
+        );
+        port.postMessage(current.message);
+      };
+      const settle = (answer) => {
+        const done = current;
+        current = undefined;
+        clearTimeout(done.timer);
+        if (answer.ok) done.resolve(answer.value);
+        else done.reject(new Error(answer.error));
+        next();
+      };
+      port.onmessage = ({ data }) => {
+        if (data?.v !== 1) return;
+        if (typeof data.kind !== "string") {
+          if (current !== undefined && data.re === current.message.id) settle(data);
+          return;
+        }
+        // A call waiting for the person is answered by `until`, not in 15 s.
+        if (data.kind === "rpc.waiting" && data.re === current?.message.id) {
+          clearTimeout(current.timer);
+          current.timer = setTimeout(
+            () => settle({ ok: false, error: "No answer from the app" }),
+            Math.max(0, Date.parse(data.until) - Date.now()) + 15000,
+          );
+        }
+        if (data.kind === "theme.changed") theme(data.theme);
+        // A wait is news only while it lasts, so a later listener is not told of it.
+        if (data.kind !== "rpc.waiting") latest.set(data.kind, data);
+        for (const listener of listeners) listener(data);
+      };
+      port.start();
+      theme(said.theme);
+      const request = (op, fields = {}) =>
+        new Promise((resolve, reject) => {
+          queue.push({ resolve, reject, message: { ...fields, v: 1, id: String(++sequence), op } });
+          next();
+        });
+      resolve({
+        hello: said,
+        // A listener first hears the latest push of each kind that came before it.
+        on(listener) {
+          for (const push of latest.values()) listener(push);
+          listeners.add(listener);
+          return () => listeners.delete(listener);
+        },
+        request,
+        data: () => request("data.get"),
+        state: () => request("state.get"),
+        setState: (revision, data) => request("state.set", { revision, data }),
+        call: (method, input = {}) => request("rpc.call", { method, input }),
+        openAgent: (prefill) => request("open-agent", prefill === undefined ? {} : { prefill }),
+        resize: (height) =>
+          request("resize", { height: Math.min(1200, Math.max(1, Math.ceil(height))) }),
+        decline: () => request("decline"),
+      });
+    });
+  });
+}
+
+/**
+ * gws_read's answer for gmail.users.threads.get, as a subject and its messages.
+ * Null for any other operation, so the view declines and the call keeps its
+ * ordinary look. Bodies come from the text/plain part when the read asked for
+ * it, else from Gmail's snippet; nothing is fetched and no HTML is rendered.
+ */
+function threadOf(output) {
+  if (!output || output.operation !== "gmail.users.threads.get") return null;
+  const data = output.data || {};
+  const messages = Array.isArray(data.messages) ? data.messages : [];
+  if (messages.length === 0) return null;
+  const header = (message, name) => {
+    const headers = (message.payload && message.payload.headers) || [];
+    const found = headers.find((entry) => String(entry.name).toLowerCase() === name);
+    return found ? String(found.value) : "";
+  };
+  const plain = (part) => {
+    if (!part) return "";
+    if (part.mimeType === "text/plain" && part.body && typeof part.body.data === "string") {
+      const binary = atob(part.body.data.replace(/-/g, "+").replace(/_/g, "/"));
+      return new TextDecoder().decode(Uint8Array.from(binary, (c) => c.charCodeAt(0)));
+    }
+    for (const child of part.parts || []) {
+      const text = plain(child);
+      if (text !== "") return text;
+    }
+    return "";
+  };
+  return {
+    subject: header(messages[0], "subject") || "(no subject)",
+    messages: messages.map((message) => {
+      const time = Number(message.internalDate);
+      return {
+        from: header(message, "from") || "Unknown sender",
+        at: Number.isFinite(time) && time > 0 ? new Date(time).toISOString() : header(message, "date"),
+        body: (plain(message.payload) || String(message.snippet || "")).trim().slice(0, 4000),
+      };
+    }),
+    truncated: output.truncated === true,
+  };
+}
+
+function draw(root, thread) {
+  root.replaceChildren();
+  const title = document.createElement("h1");
+  title.textContent = thread.subject;
+  const list = document.createElement("ol");
+  for (const message of thread.messages) {
+    const item = document.createElement("li");
+    const head = document.createElement("div");
+    head.className = "head";
+    const from = document.createElement("span");
+    from.className = "from";
+    from.textContent = message.from;
+    const at = document.createElement("time");
+    at.className = "at";
+    at.textContent = message.at.replace("T", " ").replace(/:\d\d\.\d+Z$/, " UTC");
+    at.dateTime = message.at;
+    const body = document.createElement("p");
+    body.className = "body";
+    body.textContent = message.body || "No text in this message.";
+    head.append(from, at);
+    item.append(head, body);
+    list.append(item);
+  }
+  root.append(title, list);
+  if (thread.truncated) {
+    const note = document.createElement("p");
+    note.className = "note";
+    note.textContent = "Gmail's answer was cut short; not every message is shown.";
+    root.append(note);
+  }
+}
+
+if (typeof document !== "undefined" && document.getElementById("thread")) {
+  jellyView().then(async (view) => {
+    const thread = threadOf((await view.data())?.output);
+    if (thread === null) return view.decline();
+    draw(document.getElementById("thread"), thread);
+    view.resize(document.documentElement.scrollHeight);
+  });
+}
+</script>
+</body>
+</html>

package/views/jelly-view.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The types of `jelly-view.js`, for a page written or checked with TypeScript:
+ * `/// <reference path="./jelly-view.d.ts" />`. They mirror the bridge envelopes
+ * in Jelly's contracts (`protocol/contracts/src/view-bridge.ts`); the page itself
+ * carries only the JavaScript.
+ */
+
+type JellyViewPlace = "tool-result" | "home-widget" | "settings-section";
+type JellyViewGrant = "data" | "state" | "rpc" | "open-agent";
+
+/** The fixed theme token set; the helper sets each as `--jelly-<name>` on the page. */
+interface JellyViewTheme {
+  text: string;
+  muted: string;
+  surface: string;
+  raised: string;
+  border: string;
+  accent: string;
+  "on-accent": string;
+  danger: string;
+  font: string;
+  radius: string;
+  scheme: "light" | "dark";
+}
+
+interface JellyViewHello {
+  v: 1;
+  kind: "hello";
+  /** `package` is null for a Home app an agent made. */
+  view: { package: string | null; id: string; title: string; place: JellyViewPlace };
+  grants: JellyViewGrant[];
+  /** The methods `call` may name. */
+  rpc: string[];
+  theme: JellyViewTheme;
+}
+
+/** A view's state: JSON of at most 64 KB, and the revision a write must name. */
+interface JellyViewState {
+  revision: number;
+  data: unknown;
+}
+
+type JellyViewPush =
+  | { v: 1; kind: "data.changed"; data: unknown }
+  | ({ v: 1; kind: "state.changed" } & JellyViewState)
+  | { v: 1; kind: "theme.changed"; theme: JellyViewTheme }
+  | { v: 1; kind: "visibility"; visible: boolean }
+  /** The call with request id `re` waits for the person, at most until `until` (ISO time). */
+  | { v: 1; kind: "rpc.waiting"; re: string; until: string };
+
+interface JellyView {
+  hello: JellyViewHello;
+  /** Hear pushes; returns the way to stop. */
+  on(listener: (push: JellyViewPush) => void): () => void;
+  /** Any request by its op, for one the helper has no name for. */
+  request(op: string, fields?: Record<string, unknown>): Promise<unknown>;
+  /** The place's data (the `data` grant). */
+  data(): Promise<unknown>;
+  /** The view's state (the `state` grant). */
+  state(): Promise<JellyViewState>;
+  /** Replace the state if `revision` is still the stored one; rejects on a conflict. */
+  setState(revision: number, data: unknown): Promise<JellyViewState>;
+  /** One of the methods the hello lists (the `rpc` grant). */
+  call(method: string, input?: unknown): Promise<unknown>;
+  /** Start a message for the person to send; it is never sent (the `open-agent` grant). */
+  openAgent(prefill?: string): Promise<null>;
+  /** The height the page needs, in CSS pixels, up to 1200: a hint the app may draw shorter. */
+  resize(height: number): Promise<null>;
+  /** Not mine: the app closes the frame and keeps its ordinary look. */
+  decline(): Promise<null>;
+}
+
+declare function jellyView(): Promise<JellyView>;

package/views/jelly-view.js

@@ -0,0 +1,87 @@
+// jelly-view.js: a client of Jelly's view bridge. Paste it into the page's own <script>:
+// a sealed page loads no script by URL and is given no global. Call jellyView() as the
+// script starts; it resolves with the client when the app says hello.
+function jellyView() {
+  return new Promise((resolve) => {
+    addEventListener("message", function hello(event) {
+      const said = event.data;
+      if (event.source !== parent || said?.v !== 1 || said.kind !== "hello" || !event.ports[0])
+        return;
+      removeEventListener("message", hello);
+      const port = event.ports[0];
+      const listeners = new Set();
+      const latest = new Map();
+      const queue = [];
+      let sequence = 0;
+      let current;
+      const theme = (tokens) => {
+        const style = document.documentElement.style;
+        for (const [name, value] of Object.entries(tokens))
+          if (name === "scheme") style.colorScheme = value;
+          else style.setProperty(`--jelly-${name}`, value);
+      };
+      // The app answers one request at a time, so requests go in turn.
+      const next = () => {
+        if (current !== undefined || queue.length === 0) return;
+        current = queue.shift();
+        current.timer = setTimeout(
+          () => settle({ ok: false, error: "No answer from the app" }),
+          15000,
+        );
+        port.postMessage(current.message);
+      };
+      const settle = (answer) => {
+        const done = current;
+        current = undefined;
+        clearTimeout(done.timer);
+        if (answer.ok) done.resolve(answer.value);
+        else done.reject(new Error(answer.error));
+        next();
+      };
+      port.onmessage = ({ data }) => {
+        if (data?.v !== 1) return;
+        if (typeof data.kind !== "string") {
+          if (current !== undefined && data.re === current.message.id) settle(data);
+          return;
+        }
+        // A call waiting for the person is answered by `until`, not in 15 s.
+        if (data.kind === "rpc.waiting" && data.re === current?.message.id) {
+          clearTimeout(current.timer);
+          current.timer = setTimeout(
+            () => settle({ ok: false, error: "No answer from the app" }),
+            Math.max(0, Date.parse(data.until) - Date.now()) + 15000,
+          );
+        }
+        if (data.kind === "theme.changed") theme(data.theme);
+        // A wait is news only while it lasts, so a later listener is not told of it.
+        if (data.kind !== "rpc.waiting") latest.set(data.kind, data);
+        for (const listener of listeners) listener(data);
+      };
+      port.start();
+      theme(said.theme);
+      const request = (op, fields = {}) =>
+        new Promise((resolve, reject) => {
+          queue.push({ resolve, reject, message: { ...fields, v: 1, id: String(++sequence), op } });
+          next();
+        });
+      resolve({
+        hello: said,
+        // A listener first hears the latest push of each kind that came before it.
+        on(listener) {
+          for (const push of latest.values()) listener(push);
+          listeners.add(listener);
+          return () => listeners.delete(listener);
+        },
+        request,
+        data: () => request("data.get"),
+        state: () => request("state.get"),
+        setState: (revision, data) => request("state.set", { revision, data }),
+        call: (method, input = {}) => request("rpc.call", { method, input }),
+        openAgent: (prefill) => request("open-agent", prefill === undefined ? {} : { prefill }),
+        resize: (height) =>
+          request("resize", { height: Math.min(1200, Math.max(1, Math.ceil(height))) }),
+        decline: () => request("decline"),
+      });
+    });
+  });
+}