Grok Bot Native Surfaces Evidence
Evidence and automation gates for optional Grok Bot native integrations
Grok Bot native surfaces — product evidence catalog (#209)
Prompt-first procedure: Describe the outcome you want in your agent conversation. The agent should select and load the appropriate AIWG assets, explain material changes, request any needed approval, and report verification evidence. Exact commands and flags appear only in the CLI reference.
Status: Operator handoff drafts available; native writers evidence-gated
Date: 2026-09-20 Parent: #209 ADR: `docs/architecture/adr-grokbot-provider-target.md` Provider guide: `docs/integrations/grokbot-quickstart.md`
Purpose
Maintainer-approved interim scope (2026-09-20)
the agent-owned bot-handoff operation now emits operator-reviewed drafts for routines, teammate profiles, connector recommendations and memory references. See handoff format and review steps. This resolves the interim-generator decision below; native installers remain gated.
The earlier blanket statement that Grok Bot has no API is too broad. The Cursor Admin API documents `GET /grok-bot/capabilities`, including the team's `localExecution` ceiling. This can support a separately scoped team-policy reader for #244; it does not establish individual machine reachability or effective local policy. No such probe is implemented by the handoff generator.
Current connector UX uses Marketplace rather than the older Settings → Plugins wording below. Native routine/profile/memory import contracts and an automated connector installer were not established by this review.
For AI coding tasks in CI, use the separate Grok Build provider and verification path. Grok Bot Admin API access is not a dependency of Grok Build deployment. The historical catalog below records why the original native writers were deferred.
Catalog each optional Grok Bot native surface from #209 against public product docs (operator-reproducible UX) and record what is still missing for an AIWG-consumable import/API/reload contract. This cycle progresses evidence and issue decomposition only. It does not invent filesystem writers, silent installs, or capability-matrix claims that AIWG installs routines / MCP / CreateAgent profiles / memory / machines.
Child issues (one surface each)
| # | Surface |
|---|---|
| #241 | Routines/cron import generator |
| #242 | CreateAgent/teammate template projection |
| #243 | Connector/MCP install profile |
| #244 | Registered-machine health probe (read-only) |
| #245 | Memory reference helper (no secret scrape) |
Evidence PR: #240.
Scaffolding modules (fail-closed)
Typed contracts + kill-switches live under `src/providers/grokbot-natives/` (see grokbot-native-adapters-scaffolding.md). Status remains evidence-gated — scaffolding refuses writers until the Decision gate below is satisfied. Default OFF; baseline the agent-owned use operation is unchanged.
| Child | Module entry |
|---|---|
| #244 | `registeredMachineHealthProbe` |
| #245 | `memoryReferenceHelper` |
| #241 | `generateRoutinesImportStub` |
| #242 | `projectCreateAgentStub` |
| #243 | `buildConnectorInstallProfileStub` |
Product evidence sources (2026-09)
| Doc | URL | Relevance |
|---|---|---|
| Overview | https://docs.x.ai/grok-bot/overview | Shared cloud computer; connectors; skills/routines as product UX |
| Bots (Create / profile) | https://docs.x.ai/grok-bot/bots | Create new agent, Edit Profile, duplicate/share/delete Bot |
| Skills, routines, automations | https://docs.x.ai/grok-bot/skills-routines-and-automations | Skills via chat / Plugins; routines via schedule or event; manage UI |
| Computer and apps | https://docs.x.ai/grok-bot/computer-and-apps | Plugins/connectors; shared `/workspace`; local computer separate |
| FAQ | https://docs.x.ai/grok-bot/faq | Skill vs routine; memory; local vs cloud computer |
| Chat and collaboration | https://docs.x.ai/grok-bot/chat-and-collaboration | `@` mentions for Bots/groups/routines/connectors; `/` for skills |
| Approvals / local computer (adjacent) | https://docs.x.ai/grok-bot/approvals-security-and-privacy | Settings → General → Agent → Execution on Local Computer |
| Settings (adjacent) | https://docs.x.ai/grok-bot/settings-and-notifications | Timezone for routines; local-computer execution setting |
Critical ADR constraint: these pages document operator UX (ask the Bot; Settings → Plugins; View conversation details → Routines). They do not publish an AIWG-consumable import/API contract, on-disk schema, reload hook, or CLI for writers.
Global disablement / ownership rules (all surfaces)
Until a surface is unblocked by explicit product import/API evidence:
1. Keep AIWG baseline the agent-owned use operation discover-first only. 2. Do not write routines, Bot profiles, connector configs, machine registrations, or memory stores. 3. Do not flip the capability matrix to claim AIWG installs those natives. 4. Any future adapter must be opt-in, confirmation-gated, and disableable without breaking baseline deploy. 5. Never overwrite operator-authored skills, profile, shared/project memory, routines, connectors, or teammate definitions (ADR ownership).
Surface 1 — Routines / cron (and event triggers)
| Field | Value |
|---|---|
| Child tracking | #241 routines/cron import generator |
| Product doc | https://docs.x.ai/grok-bot/skills-routines-and-automations |
| Related | FAQ skill-vs-routine; Settings timezone; chat `@` routines |
Verified (UX)
- A skill is how; a routine is when (schedule or, where supported, event).
- Operators create routines by asking the owning Bot (natural-language
schedule, inputs, approval boundary, failure policy).
- Event triggers may use Cursor account integrations (e.g. Slack/GitHub
notification) — separate from Plugins.
- Management UI: Bot → View conversation details → Routines (enable/pause,
test run, edit, inspect runs, delete). Caps: ≤50 routines/Bot; 20 recent runs.
- Background routines can run with the laptop closed (cloud computer).
Missing (AIWG contract)
- No published import format (JSON/YAML/TOML), filesystem path, or API to
create/update routines from an external tool.
- No documented reload/sync hook after an out-of-band write.
- No schema for schedule timezone binding beyond “Settings timezone.”
- No idempotent upsert / ownership marker contract for AIWG-managed entries.
Proposed AIWG adapter shape (when unblocked)
- Scaffolding: `src/providers/grokbot-natives/routines.ts` (`generateRoutinesImportStub`) — fail-closed; flag `AIWG_GROKBOT_NATIVE_ROUTINES`.
- Generator only after import contract exists: map AIWG scheduled intents →
product import payload; dry-run by default; write only with explicit confirmation and a disable flag (e.g. `AIWG_GROKBOT_ROUTINES=0`).
- Until then, the only safe interim (if maintainer authorizes) is a
prompt/handoff pack under `AIWG_GROKBOT_SKILLS_DIR` that emits operator instructions to paste/ask the Bot — never silent install.
Disablement requirement
Feature flag / env kill-switch; removing the adapter must leave baseline `grokbot` deploy and doctor unchanged.
Surface 2 — CreateAgent / teammate template projection
| Field | Value |
|---|---|
| Child tracking | #242 CreateAgent/teammate template projection |
| Product doc | https://docs.x.ai/grok-bot/bots |
| Related | Overview; chat-and-collaboration group chats / handoffs |
Verified (UX)
- Create flow: New → Create new agent → Edit Profile (name, title,
description, avatar).
- Bots can suggest/create focused Bots; Duplicate copies profile/settings/
enabled skills/routines/avatar but not conversation history, learned memory, or attachments.
- Share via public link → recipient Add to Grok Bot (copy; no computer/
logins/history transfer).
- Group chats (2–6 Bots) and Bot-to-Bot async handoffs are product UX for
teammate coordination.
Missing (AIWG contract)
- No stable CreateAgent / profile API or import schema for projecting AIWG
agent definitions into Grok Bot profiles.
- No documented on-disk profile path AIWG may write.
- No reload contract after external profile mutation.
- No mapping guarantee between AIWG agent IDs and Grok Bot identities.
Proposed AIWG adapter shape (when unblocked)
- Scaffolding: `src/providers/grokbot-natives/create-agent.ts` (`projectCreateAgentStub`) — fail-closed; flag `AIWG_GROKBOT_NATIVE_CREATE_AGENT`.
- Project curated AIWG agent templates → product profile import (or API),
opt-in per agent, with ownership markers and “never overwrite operator description” rules.
- Until unblocked: discover/show only; optional handoff prompts describing
recommended Bot jobs — no profile writers.
Disablement requirement
Per-surface toggle; baseline must not call CreateAgent or claim teammate install in status/matrix.
Surface 3 — Connector / MCP install profile
| Field | Value |
|---|---|
| Child tracking | #243 connector/MCP install profile |
| Product doc | https://docs.x.ai/grok-bot/computer-and-apps |
| Related | Skills/Plugins (`Settings → Plugins`); overview connectors mention |
Verified (UX)
- Connectors appear as Plugins: Settings → Plugins → Add → browser auth.
- In chat, `@` attaches a connector; `/` references a saved skill.
- Prefer connector over browser when available; connectors are account-wide.
- Packaged skills also install/enable via Settings → Plugins → Yours.
Missing (AIWG contract)
- No published MCP/connector config file format, install API, or reload
procedure AIWG can drive.
- No documented way to register an AIWG MCP sidecar as a Grok Bot Plugin
without operator UI.
- No attestation that AIWG may write connector credentials or plugin state
(must not).
Proposed AIWG adapter shape (when unblocked)
- Scaffolding: `src/providers/grokbot-natives/connector-install-profile.ts` (`buildConnectorInstallProfileStub`) — recommend-only; flag `AIWG_GROKBOT_NATIVE_CONNECTORS`.
- Emit an install profile (declarative list of recommended connectors +
operator steps) and, only if product documents it, a non-secret config fragment applied via documented import/reload.
- Never store OAuth tokens or scrape plugin secrets.
Disablement requirement
Opt-in profile generation only; default deploy must not install or claim MCP connectors for `grokbot`.
Surface 4 — Registered-machine health probe (read-only)
| Field | Value |
|---|---|
| Child tracking | #244 registered-machine health probe (read-only) |
| Product doc | https://docs.x.ai/grok-bot/computer-and-apps |
| Related | Approvals (Execution on Local Computer); FAQ; Settings |
Verified (UX)
- Primary runtime is a persistent shared cloud computer (`/workspace`,
browser, terminal) — account-scoped, not per-Bot.
- Local computer is separate: Bot runs local commands only when enabled and
approved under Settings → General → Agent → Execution on Local Computer (Ask every time / always / never).
- Cloud recover/update/reset flows exist in Settings → Beta; they are product
UI, not an AIWG API.
- Docs describe policy and separation; they do not expose a “registered
machine bridge” import or health endpoint for external tools.
Missing (AIWG contract)
- No published machine-registration API, bridge ID schema, or health probe
endpoint AIWG can call.
- No documented local-agent status JSON/path for read-only polling.
- Linux local-computer details are thinner than macOS/Windows wording in places;
do not invent paths.
Proposed AIWG adapter shape (when unblocked)
- Scaffolding: `src/providers/grokbot-natives/registered-machine-health.ts` (`registeredMachineHealthProbe`) — read-only; flag `AIWG_GROKBOT_NATIVE_MACHINE_PROBE`.
- Read-only probe: report reachability / policy mode if product exposes a
safe status surface; never enable local execution, never register machines, never write credentials.
- Until then: doctor/status may only state “Grok-owned; no AIWG machine
bridge.”
Disablement requirement
Probe must be skippable; failures must not fail baseline the agent-owned use operation.
Surface 5 — Memory reference helper (no secret scrape)
| Field | Value |
|---|---|
| Child tracking | #245 memory reference helper (no secret scrape) |
| Product doc | https://docs.x.ai/grok-bot/bots (What a Bot remembers); FAQ; overview |
| Related | ADR discover-first: store references/summaries — never full bodies |
Verified (UX)
- Bots retain stable preferences, role context, and summaries; conversations
and learned context are per-Bot.
- Shared files / browser sessions / handoffs move context between Bots on the
shared computer.
- Product guidance: for consequential decisions, check the current source —
memory is not authoritative.
- Duplicate Bot does not copy learned memory.
Missing (AIWG contract)
- No published memory import/export API, on-disk memory schema, or approved
write path for external tools.
- No safe “append reference note” contract distinct from scraping secrets/
sessions/files on the shared computer.
Proposed AIWG adapter shape (when unblocked)
- Scaffolding: `src/providers/grokbot-natives/memory-reference-helper.ts` (`memoryReferenceHelper`) — proposals only; flag `AIWG_GROKBOT_NATIVE_MEMORY_REF`.
- Helper that proposes operator-approved short references/summaries (paths,
issue URLs, the agent’s stable-asset loader pointers) for the operator to paste or approve — never scrape clipboard, cookies, credentials, or full artifact bodies.
- Align with ADR: references/summaries only.
Disablement requirement
Default off; must not run as part of baseline deploy; no secret scrape ever.
Decision gate (unblock criteria)
A child surface may move from Blocked to implementation only when all are true:
1. Public product docs (or maintainer-attested operator evidence) publish an import/API/reload contract suitable for automation. 2. Contract is cited in the implementation PR with reproduction steps. 3. Adapter is isolated (tests + docs section), confirmation-gated, and disableable without affecting baseline `grokbot`. 4. Capability matrix remains honest (native capability ≠ AIWG installer).
Explicit non-goals this cycle
- Inventing `~/.grokbot` (or any default) writers for routines / profiles /
connectors / memory / machines.
- Silent Plugin or routine installs.
- Claiming live-refresh or Cursor reload wording for these surfaces.
- Folding xAI Grok Build into this provider.
Original questions and current disposition
1. Interim handoff generation approved on 2026-09-20. The command prints drafts; retain them in the canonical artifact store before an explicit provider export. 2. Native installation priority remains separate. None of these optional Bot integrations gates AIWG deployment to Grok Build CI jobs.
Related: baseline loading (not #209 writers)
Default path for AIWG on a Grok Bot cloud computer is global install, not a Steward Bot:
See grokbot-cloud-session-global-install.md.
`AIWG_GROKBOT_SKILLS_DIR` + the agent-owned use operation (+ project `use` in repos). Steward Bot only when mutating Grok-native routines/teammates/connectors.