Module Reference

51 modules, zero dependencies. Use assay context <query> for LLM-ready docs on any module.

assay modules                    # list all modules
assay context "grafana health"   # get detailed docs for LLM

Rust Builtins

Available globally in all .lua scripts — no require needed.

HTTP & Networking

SSE Streaming Example

http.serve(8080, {
  GET = {
    ["/events"] = function(req)
      return {
        sse = function(send)
          send({ data = "connected" })
          sleep(1)
          send({ event = "update", data = json.encode({count = 1}), id = "1" })
          -- stream closes when function returns
        end
      }
    end
  }
})

The send callback accepts event, data, id, and retry fields. SSE headers (text/event-stream, no-cache, keep-alive) are set automatically.

Multi-Value Response Headers

Response handlers can return an array of strings as a header value. Each entry emits the same header name once — required for setting multiple Set-Cookie values in a single response and useful for headers like Link, Vary, and Cache-Control. String values continue to work as before.

http.serve(8080, {
  GET = {
    ["/login"] = function(req)
      return {
        status = 200,
        headers = {
          ["Set-Cookie"] = {
            "session=abc; Path=/; HttpOnly",
            "csrf=xyz; Path=/",
          },
        },
        json = { ok = true },
      }
    end
  }
})

Serialization

System

Cryptography

Database

Templates & Async

Testing & Logging

Stdlib Modules

34 embedded Lua modules loaded via require("assay.<name>"). All follow the client pattern: M.client(url, opts) → client object → c:method().

Monitoring & Observability

Kubernetes & GitOps

Security & Identity

Infrastructure

Data & Storage

Utilities

Ory Stack

Complete Ory identity and authorization stack: Kratos (identity management, login/registration/recovery flows), Hydra (OAuth2 and OpenID Connect server), and Keto (Zanzibar-style ReBAC). Each module can be used independently, or combined via the assay.ory convenience wrapper.

Example: Build all three clients at once and check a permission

local ory = require("assay.ory")

local o = ory.connect({
  kratos_public = "http://kratos-public:4433",
  kratos_admin  = "http://kratos-admin:4434",
  hydra_public  = "https://hydra.example.com",
  hydra_admin   = "http://hydra-admin:4445",
  keto_read     = "http://keto-read:4466",
  keto_write    = "http://keto-write:4467",
})

-- Kratos: introspect a session cookie
local session = o.kratos:whoami(cookie)
log.info("Logged in as: " .. session.identity.traits.email)

-- Hydra: register an OAuth2 client
local client = o.hydra:create_client({
  client_name = "my-app",
  grant_types = { "authorization_code", "refresh_token" },
  redirect_uris = { "https://app.example.com/callback" },
})

-- Keto: check a ReBAC permission
local allowed = o.keto:check("apps", "cc", "admin", "user:alice")
if not allowed then error("permission denied") end

Temporal Workflow Engine

Full Temporal workflow orchestration with two complementary APIs: a native gRPC client (Rust builtin, optional temporal feature) for starting and controlling workflows, and an HTTP REST client (Lua stdlib) for querying the Temporal Web UI.

Native gRPC Client (builtin)

Available globally as temporal when built with --features temporal. Connects directly to the Temporal frontend gRPC service. No require needed.

gRPC Example: Start and Monitor a Workflow

-- Connect to Temporal (gRPC, no require needed)
local client = temporal.connect({
  url = "temporal-frontend.infra:7233",
  namespace = "production",
})

-- Start a promotion workflow
local handle = client:start_workflow({
  task_queue = "promotions",
  workflow_type = "PromoteToEnvironment",
  workflow_id = "promote-prod-v1.2.0",
  input = {
    version = "v1.2.0",
    target_env = "prod",
    triggered_by = "admin@example.com",
  },
})
log.info("Started workflow: " .. handle.run_id)

-- Check status
local info = client:describe_workflow("promote-prod-v1.2.0")
log.info("Status: " .. info.status)  -- RUNNING, COMPLETED, FAILED, etc.

-- Signal the workflow (e.g., approve a step)
client:signal_workflow({
  workflow_id = "promote-prod-v1.2.0",
  signal_name = "approve_deploy",
  input = { approved_by = "admin" },
})

-- Wait for the final result
local result = client:get_result({ workflow_id = "promote-prod-v1.2.0" })
log.info("Workflow completed: " .. json.encode(result))

HTTP REST Client (stdlib)

Loaded via require("assay.temporal"). Talks to the Temporal HTTP API for querying workflows, namespaces, schedules, task queues, and history. Works with any Temporal deployment.

HTTP Example: Query Workflows and History

local temporal = require("assay.temporal")
local c = temporal.client("http://temporal-web:8080", {
  namespace = "production",
  api_key = env.get("TEMPORAL_API_KEY"),
})

-- List running workflows
local result = c:workflows({ query = "WorkflowType='PromoteToEnvironment'" })
for _, exec in ipairs(result.executions or {}) do
  log.info(exec.execution.workflowId .. " — " .. exec.status)
end

-- Get full history for a workflow
local history = c:workflow_history("promote-prod-v1.2.0")
for _, event in ipairs(history.history.events) do
  log.info(event.eventType)
end

-- Check task queue health
local tq = c:task_queue("promotions")
log.info("Active pollers: " .. #tq.pollers)

When to Use Which

AI Agent & Workflow

Integrate with AI agent platforms, GitHub, Gmail, and Google Calendar — all via native HTTP, zero shell dependencies.

assay.openclaw

OpenClaw AI agent platform integration. Invoke tools, send messages, manage state, spawn sub-agents, approval gates, LLM tasks.

local openclaw = require("assay.openclaw")
local c = openclaw.client()  -- auto-discovers $OPENCLAW_URL + $OPENCLAW_TOKEN

-- Invoke any OpenClaw tool
local result = c:invoke("message", "send", { target = "#general", message = "Hello!" })

-- Shorthand: send message
c:send("discord", "#alerts", "Service is down!")
c:notify("ops-team", "Deployment complete")

-- Persistent state
c:state_set("last-deploy", { version = "1.2.3", time = time() })
local prev = c:state_get("last-deploy")

-- Diff detection
local diff = c:diff("pr-state", new_snapshot)
if diff.changed then log.info("State changed!") end

-- LLM task
local answer = c:llm_task("Summarize this PR", { model = "claude-sonnet" })

-- Cron jobs
c:cron_add({ schedule = "0 9 * * *", task = "daily-report" })

-- Sub-agents
c:spawn("Fix the login bug", { model = "gpt-4o" })

assay.github

GitHub REST API client. PRs, issues, actions, repositories, GraphQL. No gh CLI dependency.

local github = require("assay.github")
local c = github.client()  -- uses $GITHUB_TOKEN

-- Pull requests
local pr = c:pr_view("owner/repo", 123)
local prs = c:pr_list("owner/repo", { state = "open" })
local reviews = c:pr_reviews("owner/repo", 123)
c:pr_merge("owner/repo", 123, { merge_method = "squash" })

-- Issues
local issues = c:issue_list("owner/repo", { labels = "bug", state = "open" })
local issue = c:issue_get("owner/repo", 42)
c:issue_create("owner/repo", "Bug title", "Description", { labels = {"bug"} })
c:issue_comment("owner/repo", 42, "Fixed in PR #123")

-- Actions
local runs = c:runs_list("owner/repo", { status = "completed" })
local run = c:run_get("owner/repo", 12345)

-- GraphQL
local data = c:graphql("query { viewer { login } }")

assay.gmail

Gmail REST API with OAuth2 token auto-refresh. Search, read, reply, send emails.

local gmail = require("assay.gmail")
local c = gmail.client({
  credentials_file = "/path/to/credentials.json",
  token_file = "/path/to/token.json",
})

-- Search emails
local emails = c:search("newer_than:1d is:unread", { max = 20 })

-- Read a message
local msg = c:get("message-id-here")

-- Reply to an email
c:reply("message-id", { body = "Thanks for the update!" })

-- Send new email
c:send("user@example.com", "Subject", "Email body")

-- List labels
local labels = c:labels()

assay.gcal

Google Calendar REST API with OAuth2 token auto-refresh. Events CRUD, calendar list.

local gcal = require("assay.gcal")
local c = gcal.client({
  credentials_file = "/path/to/credentials.json",
  token_file = "/path/to/token.json",
})

-- List upcoming events
local events = c:events({ timeMin = "2026-04-05T00:00:00Z", maxResults = 10 })

-- Get specific event
local event = c:event_get("event-id")

-- Create event
c:event_create({
  summary = "Team standup",
  start = { dateTime = "2026-04-06T09:00:00Z" },
  ["end"] = { dateTime = "2026-04-06T09:30:00Z" },
})

-- Update / delete
c:event_update("event-id", updated_event)
c:event_delete("event-id")

-- List all calendars
local calendars = c:calendars()

assay.oauth2

Google OAuth2 token management. File-based credentials loading, automatic access token refresh, token persistence.

local oauth2 = require("assay.oauth2")

-- Load credentials and token from default paths
-- (~/.config/gog/credentials.json and ~/.config/gog/token.json)
local auth = oauth2.from_file()

-- Or specify custom paths
local auth = oauth2.from_file("/path/to/credentials.json", "/path/to/token.json")

-- Refresh access token
auth:refresh()

-- Persist updated token back to file
auth:save()

-- Get auth headers for API calls
local headers = auth:headers()
-- Returns: {Authorization = "Bearer ...", ["Content-Type"] = "application/json"}

-- Use with http builtins
local resp = http.get("https://www.googleapis.com/calendar/v3/calendars/primary/events", {
  headers = auth:headers()
})

assay.email_triage

Email classification and triage. Deterministic rule-based categorization or OpenClaw LLM-assisted classification into action, reply, and FYI buckets.

local email_triage = require("assay.email_triage")
local gmail = require("assay.gmail")

local gc = gmail.client({
  credentials_file = "/path/to/credentials.json",
  token_file = "/path/to/token.json",
})

-- Fetch recent emails
local emails = gc:search("newer_than:1d", { max = 50 })

-- Deterministic categorization (no LLM needed)
local buckets = email_triage.categorize(emails)
log.info("Needs reply: " .. #buckets.needs_reply)
log.info("Needs action: " .. #buckets.needs_action)
log.info("FYI: " .. #buckets.fyi)

-- LLM-assisted triage via OpenClaw (smarter classification)
local openclaw = require("assay.openclaw")
local oc = openclaw.client()
local smart_buckets = email_triage.categorize_llm(emails, oc)

Custom Modules

Place .lua files in ./modules/ (project-local) or ~/.assay/modules/ (global). Or set ASSAY_MODULES_PATH to override the global directory. They are auto-discovered and appear in assay modules output.

./modules/
  myapi.lua        # require("assay.myapi")
~/.assay/modules/
  company.lua      # require("assay.company")

For LLM agents: llms.txt · llms-full.txt