Support

Extentos is pre-1.0 and open source — support today is via GitHub issues, with the source code itself as the primary backstop when something doesn't behave as documented. There's no paid support tier; there's also no SLA. What there is: an active issue tracker, a structured-event-log debugging surface that makes most issues self-diagnosable, and the source for every component (MCP server, native libraries, backend, simulator UI) available to read. This page is where to start when something goes wrong.

Where to file

The repo's bugs.url field in mcp-server/package.json points at the same issue tracker — npm issue links from the package page route there too.

Self-service before filing

Most issues are diagnosable from the developer's machine without escalation. Before opening an issue, run through this:

1. Capture install state with whoami

npx @extentos/mcp-server@latest whoami

Prints the install ID, account ID (if linked), tier, meter remaining, auth expiry, and MCP / library versions. Always include this output in a bug report — it's the single line that tells maintainers what your install actually looks like.

2. Check consent and config state with status

npx @extentos/mcp-server@latest status

Prints consent state (privacy notice accepted / declined), telemetry on/off, install ID, linked account, and effective config dir (~/.extentos/ or whatever EXTENTOS_CONFIG_DIR points at). Useful when an issue might be config-related.

3. Ask the agent to query the structured event log

If the bug is "something happened in a flow," the structured event log is the primary debugging surface. Tell your AI agent:

Run getEventLog with filter "errors" and limit 50 on session <sessionId>

The agent calls the MCP tool; the response is a structured trace of what happened in the simulator session. Include the flowId of the failing flow if you know it — getEventLog({ flowId: "flow_007" }) returns the complete execution trace of one trigger.

4. Run validateIntegration for spec/manifest issues

If the symptom is "agent says everything is fine but the app doesn't run," ask your agent:

Run validateIntegration on this project

validateIntegration checks the spec against the manifest, dependency list, handler coverage, and bootstrap wiring. It catches most class-of-issue mismatches before they become runtime bugs.

5. Check the source

Every component is open source:

If a behavior contradicts what's documented, the source is the authoritative answer. Issue reports that point at the specific source line where the unexpected behavior originates (BrowserSimTransport.kt:218) are easiest to triage.

What to include in a bug report

A useful bug report has six things. Maintainers can act on a bug with this; they often can't without it.

1. Extentos version          — output of `whoami` (mcpVersion + libVersion)
2. Platform                  — Android API level, or iOS version + device model
3. Agent host                — Claude Code / Cursor / Windsurf / Cline / other
4. Steps to reproduce        — exact agent prompts + commands run
5. Expected vs actual        — what should have happened, what did
6. Logs                      — getEventLog output if applicable, otherwise
                                Logcat (Android) / os_log (iOS) / MCP stderr

If the bug involves a simulator session, also include:

• sessionId (if active or recent)
• The flowId of the failing trigger flow
• Whether the simulator browser tab was open
• autoOpenAttempted and autoOpenPlatform from the createSimulatorSession response

If the bug involves real hardware:

• Ray-Ban Meta variant (Gen 1 / Gen 2 / Display)
• Frame style (Wayfarer / Headliner / Skyler / etc.) if relevant
• Bluetooth pairing status before the bug
• Whether the bug repros on LocalSimTransport (Mock Device Kit) too

If the bug involves cross-platform behavior, repro on both iOS and Android if you have access — or note which platform you couldn't test.

Component triage — figuring out which component owns the bug

Extentos has four main components, and one common reason bug reports go cold is mis-routing. Here's the rule of thumb:

Most bugs are at the boundary between two components — e.g., the MCP server generates a manifest, the library reads it. Including getEventLog output usually disambiguates which side actually misbehaved.

Security disclosure

Do not file security issues publicly. Email the maintainer at the address listed in GitHub profile with subject prefix [SECURITY]. Include:

• Affected component (MCP server / library / backend / simulator UI)
• Affected version
• Reproduction steps
• Impact assessment (data exposure, privilege escalation, etc.)
• Whether you've shared this with anyone else

Acknowledgment within 7 days. Patch timeline depends on severity:

• Critical (RCE, auth bypass, mass data exposure): patch within 14 days, coordinated disclosure thereafter
• High (PII exposure, single-user data leak, persistent XSS): patch within 30 days
• Medium / Low: patched in the next minor release

The Extentos library architecture is designed to minimize blast radius — RealMetaTransport doesn't connect to the Extentos backend; AI provider keys are BYOK and never leave your app; app_callback payloads (which may contain end-user data) never reach Extentos servers. Most security-relevant code paths are in the MCP server and the simulator backend; these are the areas most worth careful review by external researchers.

See security and data handling for the full architectural privacy story.

Response expectations

Pre-1.0 means honest expectations:

• Bug acknowledgment: typically 1–3 business days. Sometimes longer when the maintainer is heads-down on the next release.
• Bug fix timeline: triaged by severity. Crashes, data corruption, or security issues land in a same-week patch release. Feature gaps, minor inconsistencies, or polish items land in the next minor (@0.0.x → @0.0.x+1).
• Feature requests: read and considered, but no commitment to a timeline. The roadmap is community-shaped — popular requests with clear use cases land sooner.
• Vendor-add requests (e.g., "add Mentra G1"): tracked but require the vendor's SDK to be public + sufficiently mature. See vendors for current roadmap state.

There is no paid support tier with a faster SLA at launch — this may change post-1.0.

When the agent itself can debug

A frequently-overlooked debugging path: ask your AI agent to triage. Modern AI coding agents reading a structured getEventLog response can often pinpoint the failing layer faster than a human scanning the same trace. Try:

The flow with triggerId "describe_scene" failed. Run getEventLog with filter
"errors" and flowId for that flow, read the trace, and tell me which layer
of the stack failed (transport, trigger, block, callback, or system).

The agent has direct access to the MCP debug surface; it can correlate transport events with block executions and callback completions. Often this surfaces the actual bug without needing to file an issue.

If the agent can't figure it out either, that trace becomes excellent evidence in the bug report — paste both the agent's analysis and the raw event log.

Frequently asked questions

What's the difference between filing an issue and asking my agent for help?

Your agent has the structured event log, the project state via inspectIntegration, and full source-code access. It can fix many issues without escalation — config problems, missing handlers, manifest mismatches, version drift between the spec and the library. File an issue when the agent has tried, the trace is conclusive, and the bug is in Extentos itself rather than the developer's project. The repo benefits more from "verified Extentos bug" reports than from "agent and I are confused" threads.

How do I attach long log files to a GitHub issue?

GitHub issues support file attachments up to 25 MB. For longer event-log dumps, attach as .txt or paste a GitHub Gist link. Don't paste 5000-line logs inline — they bury the issue summary.

Is there a Discord, Slack, or community forum?

No formal community channel at launch. GitHub issues are the canonical surface. A Discussions tab may be enabled later as the user base grows.

Can I get paid support / consulting?

Not at launch. Extentos is fully self-service today. If a paid support tier ships post-1.0, it will be announced via the changelog.

What if I want to contribute a fix instead of just reporting?

PRs welcome on the main repo. Open an issue first to discuss the change, then submit the PR — this avoids the "I implemented X, but you actually wanted Y" scenario. There's no formal CONTRIBUTING.md yet (pre-1.0); reasonable conventions apply (follow existing code style, include tests where infrastructure exists, keep PRs scoped).

How do I know if a bug is already known?

Search the issues before filing. If you find a close match, comment on the existing issue with your repro details rather than filing a duplicate. If yours is similar but materially different (different platform, different agent host, different symptom), file a new issue and link the related one.

What if the docs say one thing but the code does another?

The code wins. File a [docs] issue with the contradicting doc URL and the source-code path that proves the actual behavior. The maintainers care about doc accuracy because misaligned docs poison AI-agent recommendations downstream.

Can I email the maintainer directly for non-security issues?

Email is reserved for security disclosure. For everything else, file an issue — it's the canonical record, and other developers benefit from the discussion. The maintainer reads issues with at least the same priority as email.

Related

• FAQ — most-asked questions, often resolved without filing
• Security — what we collect, what we don't, end-user privacy guarantees
• Changelog — release history, what's been fixed
• Auth — whoami, logout, install state and identity
• GitHub repository — source code, issue tracker, releases