Skip to content

Relewise/relewise-agent-plugins / plugins/relewise/skills/relewise-agent-gateway

relewise-agent-gateway

Unverified

Provides the shared execution layer for Relewise Agent Gateway. Use whenever another Relewise skill needs to discover Datasets or execute an operation through the bundled CLI, MCP, or direct REST, and when diagnosing transport or authentication failures.

references/transport-selection.md

View on GitHub
# Transport selection

Transport permissions are Dataset-specific and cannot be known before identity and Dataset policy discovery. Treat discovery as a bootstrap phase, then choose the transport for the requested operation.

## Bootstrap

Honor the user's authentication and transport requirements throughout discovery and fallback. For OAuth-only requests, use the host-managed Agent Gateway MCP connection throughout setup and verification.

Attempt identity discovery in this order until one permitted authenticated route succeeds:

1. Registered Agent Gateway MCP: `get_me` (prefer the host-managed OAuth connection when it is connected).
2. Bundled CLI: `me` or `datasets`.
3. Authenticated direct REST: `GET /api/v1/me` using operation `IdentityGetCurrentUser`.

For connection setup or repair, perform the MCP connection preflight below to establish the Agent Gateway MCP connection state before selecting a setup route.

### MCP connection preflight

- Match the connection to the installed Relewise plugin's MCP declaration: server `relewise-agent-gateway`, endpoint `https://my.relewise.com/agents/mcp`. Find its `get_me` tool through the host's available or discoverable tools and use that tool to verify identity.
- If tools are missing, inspect this server's registration, enabled state, and authentication status using supported host controls or CLI commands. Limit configuration reads to these non-secret fields. Determine whether the connection needs enabling, sign-in, startup repair, or tool refresh.
- For setup, start the client's supported OAuth login/reconnect flow for this registered server. Determine current commands from host help or official documentation and reuse the existing registration. When login requires a client control available only to the user, give the precise action and keep verification pending.
- Classify login failures from observed evidence: unsupported OAuth, sign-in/consent failure, or discovery/transport failure. For discovery failures such as redirects, invalid metadata, or network errors, keep OAuth setup pending and identify the next diagnostic or corrective action.
- When discovery fails, inspect bounded unauthenticated responses from the declared MCP endpoint and follow its advertised `resource_metadata` URL. Record the request method, response status, redirect location, and authentication challenge. Compare GET and MCP initialization POST when their behavior matters. Ground the diagnosis in the observed responses and label any unverified explanation as a hypothesis.
- After successful sign-in, refresh tools as supported and call this server's `get_me`. Report pending refresh/restart or a specific blocker when verification cannot yet complete. Keep OAuth tokens, authorization codes, and client secrets within the client's credential handling.

### Dataset discovery

Retain the returned non-secret authentication metadata with the candidate Datasets. For empty discovery or a missing expected Dataset, route to the setup skill's [Dataset access guidance](../../relewise-setup/references/dataset-access.md). For policy/access denials, use that guidance to explain the required user action while preserving the denial and current authentication method.

Use the successful identity response to resolve the requested Dataset without guessing its ID. If several Datasets plausibly match and the choice changes the answer, ask the user to choose.

Retrieve that Dataset's details through the working bootstrap route:

- CLI: `dataset <dataset-id>`.
- MCP: `get_dataset_details`.
- Direct REST: operation `CoreGetDataset`.

The effective policy reports `restApiEnabled`, `mcpEnabled`, and enabled `areas`.

## Retain state at the correct scope

For workflows with several calls, retain verified findings instead of repeating discovery:

- **Task scope:** Retain the resolved CLI path and whether the local CLI can execute. Also retain observed availability of registered MCP and direct REST credentials or connections. A genuinely missing or incompatible local executable applies across Datasets.
- **Dataset scope:** Retain access validation and the effective Agent Gateway policy separately for every Dataset used in the workflow. Do not apply one Dataset's transport, Area, permission, or policy result to another Dataset.
- **Operation scope:** Confirm that the requested capability has an exact REST operation or MCP tool on the candidate transport, and use that transport's own schema.

Bootstrap identity and Dataset discovery once when the retained results are sufficient. Retrieve policy once for each involved Dataset, then select and reuse a preferred transport for that Dataset and requested capability. A workflow spanning several Datasets may legitimately mix CLI, MCP, and direct REST. Re-select when the Dataset changes, the next capability is not exposed by the preferred transport, or a classified failure changes that transport's availability.

Do not treat a Dataset-specific policy or permission denial as a task-wide transport failure. Conversely, do not repeatedly try a task-wide missing executable for every Dataset. Preserve call ordering when later calls depend on earlier results or when the domain skill defines a mutation workflow.

## Select the operation transport

After policy discovery, use this preference order:

1. Use registered MCP when it is connected, `mcpEnabled` is true, the requested Area is enabled, and the capability has an exact MCP tool. This is preferred for a host-managed OAuth connection.
2. Use the bundled CLI when it works, `restApiEnabled` is true, the requested Area is enabled, and the capability has an exact REST operation.
3. Use direct REST when `restApiEnabled` is true, the requested Area is enabled, the capability has an exact REST operation, and no preferred MCP or CLI route is usable.

Do not infer that an operation is permitted merely because bootstrap discovery succeeded. Apply the selected Dataset's effective policy to every Dataset-scoped operation.

## Classify failures before falling back

- **Local CLI unavailable:** Missing launcher, unsupported OS or architecture, permission-to-execute failure, or an incompatible executable. Continue to MCP, then direct REST when available.
- **Credential unavailable to one transport:** Another transport may be tried only when it has an independently configured credential. A protected MCP credential, for example, may work even when the CLI environment variable is absent.
- **Network or transient transport failure:** Try another policy-permitted transport when it offers an independent connection path. Avoid identical retries; retry once only when the request warrants it.
- **Authentication rejected:** Determine which credential type the transport uses. For OAuth, the connection may be expired, revoked, or require reconnecting. For PAT authentication, the PAT may be missing, malformed, expired, revoked, or rejected. Do not expose credentials. Try another transport only when it has an independently configured credential, not as a way to evade rejection.
- **Validation error:** Correct the request from the selected transport's schema. Do not switch transports to evade validation.
- **Dataset access, permission, Area, or policy denial:** Stop. Do not bypass the denial through another transport.

Accumulate relevant preflight and bootstrap findings. Report one concise diagnosis and the most useful corrective action instead of treating every unavailable candidate as a separate failure.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall