QueryLayer agent interoperability contract

Status: active beta contract

Last updated: September 1, 2026

Clean-room setup and generic client configuration are documented in agent-onboarding.md. This contract defines the authority boundary; the onboarding guide defines the operator handoff.

QueryLayer treats the agent-facing contract as a first-class product surface. Hermes, Codex, ChatGPT, Claude, Grok, and other clients must be able to use the same governed site capabilities without receiving database ownership or a vendor-specific integration path.

#Transport and identity

• The beta transport is MCP Streamable HTTP over TLS.
• An administrator creates a named connection for one registered agent identity and one exact site.
• The secret is shown once. QueryLayer stores only a prefix and SHA-256 fingerprint.
• Every connection has an expiry, can be revoked immediately, and carries an explicit scope list.
• Local clients send the secret as a bearer token. The QueryLayer Edge Function authenticates it before constructing the MCP server.
• The service-role credential exists only inside the Edge Function. It is never returned to a browser, Astro site, or agent harness.
• A native Hermes profile is bound by its immutable profile_id, never by its mutable canonical or display name.
• QueryLayer stores the current Hermes profile_name only as a routing attribute. Renaming a profile updates that route without creating a new governance identity, permission set, binding, or audit history.
• Runtime discovery is fail-closed. A missing or ambiguous immutable identity becomes unavailable; QueryLayer never substitutes a similarly named agent.

#Native Hermes Desktop session contract

QueryLayer maps one Agent Console conversation to one Hermes-owned stored session. The dashboard opens that exact conversation with:

hermes://sessions/{session_id}?profile_id={immutable_profile_id}

Hermes Desktop resolves the current profile name from the immutable ID, verifies the session under that profile, then uses its normal session-opening path. The protocol works for cold starts and running Desktop instances. A stale profile ID or missing session produces an error and never opens a replacement conversation.

#Site and permission boundary

A connection is locked to the organization, site, agent, and permissions chosen when it was created. Tool handlers use that server-resolved context; client-supplied site or agent identifiers are not accepted as authority.

The initial scopes are:

• site:read
• content:read
• content:write
• topical-map:read
• topical-map:write
• runs:read
• runs:write
• publish:request

A scope is valid only when the underlying QueryLayer agent identity has the corresponding site permission. A connection cannot expand an identity's authority.

#Governed run lifecycle

Every material agent workflow follows this sequence:

1. Begin a run with a stable run type, structured input, required output keys, and human-readable completion conditions.
2. Perform permitted reads or mutations.
3. Record each material result as an immutable run artifact.
4. Finish with one explicit terminal outcome: completed, completed with warnings, needs human input, blocked, failed, or cancelled.

QueryLayer checks required artifact keys when a client requests completion. A run with missing required outputs is stored as blocked with reason code missing_required_outputs; polished prose cannot turn partial work into a successful run.

Run events and artifacts are append-only. They retain the site, connection, agent, harness, timestamps, outcome, reasons, and affected content objects.

#Durable autonomous task contract

AGENT-003 orchestrates; AGENT-002 authorizes and executes governed mutations. A multi-step goal becomes one versioned task plan bound to the currently claimed Agent Console turn, its immutable Hermes profile_id, and its already-existing native session_id.

QueryLayer schedules one dependency-ready step at a time, verifies the step's site permissions, and resumes it through the same Hermes session. Each step retains its operation type, server-assigned risk, dependencies, proposal, result, state, and retry count. Automatic retries stop after two. Missing or ambiguous runtime identity, binding, or session state fails the task closed; the server never invents a replacement profile or session.

Create-content, revision, topical-map, internal-link, and publishing steps still produce typed AGENT-002 proposals. Human approval is a separate authenticated event, and publishing never becomes autonomous merely because it is part of a task plan.

#Content mutation rules

• Agent-created content uses the same immutable content_revisions table and template contract as dashboard-created content.
• A draft is attributed to the exact agent, connection, and governed run.
• Creating a draft never publishes it.
• Agent publishing and unpublishing must enter the existing QueryLayer publish lifecycle proposal and approval workflow. Each typed lifecycle item declares action=publish with the exact current draft revision, or action=unpublish with no revision ID so the server targets the current live pointer. No MCP tool may update published_revision_id directly.
• Agent archive and restore operations use a separate high-risk content_lifecycle proposal with the exact archived_at snapshot. A live page must be unpublished first; restoring never republishes it. Only an owner or administrator can approve either action, and browser clients cannot update archived_at directly.
• Early pilots keep final publishing under explicit human control.

#Current beta tools

• querylayer_site_context
• querylayer_list_content
• querylayer_list_evidence
• querylayer_list_evidence_reverification
• querylayer_list_topical_map
• querylayer_list_topical_strategy_opportunities
• querylayer_propose_topical_strategy_opportunities
• querylayer_claim_console_task
• querylayer_complete_console_task
• querylayer_create_task_plan
• querylayer_create_proposal
• querylayer_begin_run
• querylayer_record_artifact
• querylayer_finish_run
• querylayer_create_draft
• querylayer_record_claim_evidence
• querylayer_request_publish_approval
• querylayer_list_content_briefs
• querylayer_propose_content_brief_draft
• querylayer_list_content_source_packages
• querylayer_list_content_source_records
• querylayer_stage_content_source_package
• querylayer_propose_content_source_draft
• querylayer_list_proposals
• querylayer_form_screening_metrics

The tool set expands around content briefs and quality checks. Tools remain small and composable so every compliant MCP client can use them without QueryLayer-specific orchestration code. Imported topical strategy artifacts are planning inputs with provenance and reconciliation state, not measured live search performance or publishing instructions. Agents may read the opportunity queue and turn selected opportunities into a typed AGENT-002 proposal, but may not mutate the topical map directly. Human approval of page-oriented topical work commissions one immutable content brief. Authorized harnesses can read those briefs with querylayer_list_content_briefs and submit attributable contributor output with querylayer_propose_content_brief_draft; that submission creates an inert AGENT-002 card and cannot publish. Editorial source packages use a separate immutable staging ledger. Agents can stage and inspect checksummed records, but staging creates no content item, revision, proposal, or publishing job; deterministic warnings and invalid records remain visible for human disposition. Task planning only schedules governed steps; it never bypasses the proposal, approval, or publishing contracts.

Evidence re-verification state is available to agents through querylayer_list_evidence_reverification under the existing content:read grant (the beta vocabulary does not add a separate evidence:read scope). The read is always bound to the authenticated connection's organization, site, and agent context, and returns only bounded target, due-job, attempt-status, and open-review metadata. Observed bodies, excerpts, observation payloads, reviewer notes, secrets, and all semantic or publication mutations remain outside this tool.

Form abuse intelligence is available through querylayer_form_screening_metrics under site:read. It returns bounded aggregate counts by day, form, decision, and reason only. Submission payloads, contact details, actors, network markers, and raw screening signals remain unavailable to agents; rejected-event totals follow the bounded FORM-003 retention window.

#Client expectations

QueryLayer does not require a particular model vendor or agent runtime. A client must support authenticated Streamable HTTP MCP and preserve tool results accurately. Hermes and Codex are the first conformance clients because both are locally available during the private pilot. ChatGPT, Claude, Grok, and other MCP clients use the same endpoint and grant semantics.

#Revocation and incident behavior

• Revoked or expired connections fail authentication before tool discovery.
• Authentication failures reveal no site or agent metadata.
• Tokens are never written to audit detail, application logs, or public APIs.
• A leaked token is handled by revoking its connection and issuing a new one; existing immutable run history remains intact.
• Consequential client-side actions such as publishing remain subject to QueryLayer permissions, policy gates, and human approval even when a connection is valid.