Agents and Automation

Clean-room contract

Topolo agents do not need Topolo source code or private product knowledge. Public documentation and the credential-scoped application/action catalog are the operational contract. If those surfaces do not publish an endpoint, schema, example, verification step, or recovery path, an agent should report the missing contract instead of guessing.

Install the CLI with Node 20 or newer, then install the same skill and MCP integration for Codex and Claude Code:

npm install -g @topolo/cli
topolo setup
topolo doctor
topolo auth login
topolo auth status --json
topolo whoami --json

For a headless process, authenticate with a Topolo API key instead. Keep the key in a secret manager or process environment; do not write it to a repository.

@topolo/cli owns exact compatible SDK and MCP dependencies. topolo setup registers a resolved local Node entry point, so startup does not use npx, download code at agent launch, or depend on a separately managed global MCP. The setup command writes only host configuration and the public skill; the MCP reads the same credential as the CLI.

For a machine that hosts agents for multiple customer organizations, keep the default registration and add one clearly named registration per context:

topolo context ls --json
topolo setup --name topolo-acme --context org:org_acme --env production
topolo setup --name topolo-personal-staging --context personal --env staging
topolo doctor --name topolo-acme
topolo skills status --name topolo-acme --json

Replace the example context with an exact value returned by context ls. Named setup pins that registration's context and environment without changing the context used by interactive CLI commands. Do not reuse one named agent registration across customer organizations. Doctor reads the pinned context and environment from that exact installed registration, so no shell environment variables are required for verification.

Remove a retired customer registration without disturbing the others:

topolo skills uninstall --name topolo-acme --json
topolo skills status --name topolo-acme --json

Public boundary

Customer agents may use identity, organization context, credential-scoped applications, resources, workspaces, OAuth, integrations, and published action contracts. They must not use first-party scaffolding, application conformance, Seed, fleet audits, platform credentials, provisioning, deployment, release, or staging operations. Those capabilities live in a separately distributed topolo-platform CLI and topolo-platform MCP for approved operators only.

Authentication and authorization

OAuth scopes describe what a token can request. Effective access is narrower: it also depends on the active personal or organization context, application grants, action permissions, optional API-key resource bindings, and target-owned runtime policy.

An action with authorizationMode: "runtime" remains discoverable because its permission depends on concrete input. The target application makes the final decision at invocation time. A 403 is authoritative and should not be retried with guessed fields or another private endpoint.

Use topolo context ls --json and topolo context use <name|personal> --json to change the credential context. Requests cannot override organization identity with a body or query parameter.

Discover before acting

topolo apps --json
topolo services --query web --json
topolo actions --service web --json
topolo actions capabilities --service web --json
topolo actions get app_topolo_web.sites.build --json
topolo actions examples app_topolo_web.sites.build --json

Application results include apiKeyResources, the aliases accepted for resource-scoped credentials and action calls. Action results include exact method/path mapping, input and output JSON Schemas, confirmation policy, and an optional agent contract containing public docs, effects, error recovery, verification, rollback, next actions, and examples.

The public Agent Actions reference renders the same published contract without exposing private runtime origins. Every catalog publication is release-gated at 100% for input schema, concrete output schema, effects, expected errors, docs, examples, verification, recovery classification, and the complete agent contract. Derived structural schemas are explicitly marked with x-topolo-contract-source and x-topolo-contract-precision; agents must not treat structural provenance as field-level semantic precision.

Equivalent MCP tools are:

Validate and plan

Validate exact input locally before any network mutation:

topolo actions validate <action-id> --data '<json>' --json
topolo actions plan <action-id> --data '<json>' --json

actions plan returns schema errors, the resolved request, whether confirmation is required/provided, whether the action is executable, verification steps, rollback action, and next actions. It does not execute the action.

MCP clients use topolo_validate_action and topolo_plan_action for the same flow.

Execute and verify

Automatic read-only actions can be called through MCP topolo_read_action or the CLI action command without confirmation. A mutation requires explicit approval and --confirm:

topolo actions call <action-id> --data '<json>' --confirm --json

Before approval, present the exact action, resolved request, input, resource context, effects, verification, and rollback status from the plan. After execution, perform every published verification step immediately. If verification fails, plan and confirm only the published rollback action; never invent recovery behavior.

Public API fallback

Use topolo api only when public documentation provides the exact service, method, path, input, authorization, and verification contract. Catalog actions are preferred because they package these controls into one credential-scoped definition.

Failure handling

• Authentication errors: sign in again, then repeat identity and discovery.
• Permission denied: surface the denied permission or runtime policy; do not widen or retry.
• Invalid action input: correct the exact reported schema paths.
• Confirmation required: plan, obtain approval, then retry once with confirmation.
• Unknown action/service: repeat bounded discovery.
• Missing schema/docs/examples/verification/recovery: stop the affected operation and report a publication defect.

Every call carries a request id. Preserve it when escalating a platform or application failure.

Change Log / Verification

• Reverified the clean-room workflow on 2026-08-14 against @topolo/cli 0.8.8, including idempotent topolo setup, topolo doctor, status, scoped uninstall, Auth-owned identity, and the 20-tool MCP protocol.
• Documented the one-package setup/doctor path, multi-organization named registrations, and explicit public versus restricted platform boundary on 2026-08-14.
• Published the repository-independent agent workflow on 2026-07-14 with credential-scoped application/resource discovery, action capability discovery, local schema validation, execution planning, explicit confirmation, verification, and rollback guidance for CLI and MCP clients.