Google Workspace (gws)

Z.E.N.'s gws connector exposes the whole Google Workspace surface (Gmail, Drive, Calendar, Docs, Sheets, Slides, Tasks, Chat, Forms, Meet) as tools that tool: workflow nodes can invoke.

Tools are populated lazily. The first time a workflow calls gws.gmail.users.messages.list, the connector probes gws schema gmail.users.messages.list to discover the method's args + auth shape, registers the tool, and runs the call. Settings → Tools shows what's been discovered so far.

Install gws

# macOS
brew install zedeyestudios/tap/gws

# Or from source
cargo install gws

After install:

gws --version
gws auth status

If auth status reports unauthenticated, run gws auth login and walk through the OAuth flow. You can only call methods after the relevant scopes are authorized.

Verify Z.E.N. picked it up

Z.E.N.'s gws connector is built in. With gws on PATH the daemon registers it at boot:

curl -s http://localhost:3090/api/connectors | jq '.connectors[] | select(.id == "gws")'

Should report hasAuth: true, toolCount: <some number>, and enabled: true. Settings → Connectors shows it with the local_cli chip.

Common tools

Tool id	What it does
gws.gmail.users.messages.list	List Gmail messages by query
gws.gmail.users.messages.get	Fetch one Gmail message body
gws.gmail.users.messages.send	Send a Gmail draft
gws.drive.files.list	List Drive files
gws.drive.files.get	Get Drive file metadata
gws.calendar.events.list	List Calendar events
gws.calendar.events.insert	Create a Calendar event
gws.docs.documents.get	Read a Google Doc
gws.sheets.spreadsheets.values.get	Read a Sheets range

The full list is whatever gws schema --list returns — Z.E.N. doesn't pin a subset.

A workflow that uses gws

name: morning-gmail-triage
description: List unread Gmail messages, summarize with an agent.
nodes:
  - id: fetch
    tool: gws.gmail.users.messages.list
    tool_args:
      userId: me
      q: is:unread newer_than:1d
      maxResults: 50

  - id: summarize
    depends_on: [fetch]
    agent:
      harness: hermes/acp
      prompt: |
        Below are the headers of my unread Gmail from the last 24 hours.
        Group by category (invoices / meetings / newsletters / personal),
        and flag anything that needs a response today.

        Messages: $fetch.output

The gws.gmail.users.messages.list tool returns parsed JSON, so $fetch.output is the array the agent can read directly.

Authentication

Auth is owned by gws, not Z.E.N. The connector manifest declares auth.owner: gws and hasAuth: true so the UI knows credentials are involved; Z.E.N. never holds the OAuth tokens itself. Rotating a Google account or scopes is a gws operation:

gws auth login
gws auth status

After auth status reports a new token, tool: calls pick up the change automatically (next invocation reaches gws which reads its own auth cache).

Per-account vs single-account

gws supports multiple Google accounts via --account <email>. To call a tool on a specific account, pass it through tool_args:

- id: send-from-work
  tool: gws.gmail.users.messages.send
  tool_args:
    userId: me
    "--account": you@work.example.com
    raw: <base64 RFC 822>

Args starting with -- are forwarded as CLI flags. If you call gws.* tools across multiple accounts often, consider setting gws account set <email> as a workflow setup step.

Gotchas

• Lazy tool discovery means the first call is slower. gws schema <method> runs once per method to populate the tool's arg schema. Cached after.
• Daemon PATH stripping. If gws --version works in your terminal but the daemon reports the gws connector as unavailable, the daemon's PATH (launchd) doesn't reach gws. Symlink gws into /usr/local/bin or set PATH in ~/.zen/.env.
• Scope errors come back from gws. If a tool returns a 403 about missing scopes, gws auth login --add-scope <scope> fixes it. Z.E.N. doesn't intercept these.
• outputFormat: json is the default. Some gws subcommands have a --format text mode for human reading. Don't use those in tool: nodes; $node.output parsing will fail.

Reference

Tool registry concept: Tools Connector manifest spec: Connectors gws repo: https://github.com/zedeyestudios/gws