@eightstate/agent-client

Framework-neutral ESM client for trusted Eight State Gate capabilities used by agent workloads. It uses only standard Web APIs and requires an explicit Gate origin, a per-request workload-token provider, and optionally an injected fetch implementation.

Gate binds protocol to the stored workload token. Existing tokens remain v1; new coding-worker tokens are v2 and enforce immutable source-event, workload-token, agent-revision, and human-revision run bindings. The optional X-Eightstate-Agent-Protocol header is an optional 1 or 2 assertion and cannot downgrade a v2 token.

import {createAgentClient} from '@eightstate/agent-client'

const client = createAgentClient({
  origin: 'https://gate.example',
  token: async ({signal}) => acquireWorkloadToken(signal),
})

const search = await client.research.search('Eight State release process', {
  signal: AbortSignal.timeout(20_000),
  context: {
    runId: 'run-123',
    taskId: 'task-456',
    humanIdentityRevisionId: 73,
  },
})

The package does not read environment variables or files, launch processes, manage Git repositories, or depend on an agent framework. Callers own policy, retry scheduling, persistence, and credential acquisition. AgentClientError reports retrySafe and commitUncertain; the client never retries writes.

Durable share creation requires an explicit idempotency key. Gate returns a server-verified receipt, and client.shares.verify(content, response) checks that receipt against the exact input bytes before callers clean up local work. Safe PNG, JPEG, and WebP bytes can be shared with kind: 'image'; other binary artifacts use kind: 'bytes'.

GitHub host operations

client.github exposes the trusted-host GitHub boundary:

• repositories() requires github:read.
• gitCredential(repository) requires github:git. Gate verifies the pinned human's access, then returns a display-once GitHub App installation token narrowed to that repository. The human's broad OAuth token is never returned.
• createPullRequest(input) requires github:pr and a stable idempotencyKey.
• verifyPullRequest(input) re-verifies the persisted publication receipt.
• advancePullRequestHead(input) idempotently records and verifies a later pushed branch head for the same pull request.

Linear events identify their immutable source and human attribution with source_event_key, human_identity_revision_id, and linear_user_id. Pass the same human revision as context.humanIdentityRevisionId on subsequent calls so Gate can reject stale or mismatched authority. Pull-request receipts expose the agent revision, immutable original human revision, and the human revision that last advanced the head. Research search/fetch, Linear read/write, share create/verify, and GitHub operations require a stored runId plus sourceEventId; the optional human revision header is only an assertion against Gate's stored run binding. Identity, readiness, and Linear event register/poll/ack operations remain pre-run.

For compatibility, receipt.identity_revision_id remains the agent identity revision. agent_identity_revision_id is the explicit equivalent; human_identity_revision_id identifies the original PR human.

Coordinated rollout

1. Deploy the Agents v2 code with the coding worker disabled and no v2 token.
2. Merge and deploy Gate, which applies additive migration 0015 while legacy v1 tokens and old Gate SQL tables continue to work.
3. Issue a new coding-worker token. Gate stores it as protocol version 2.
4. Configure Agents v2 with that token and enable the coding worker.

Do not issue the v2 coding token before the Agents runtime can persist event source keys and pass run context to every GitHub operation. Existing tokens remain protocol version 1 throughout the staged rollout.

The exact paths, required scopes, risk classifications, and idempotency rules are exported as GITHUB_AGENT_CONTRACTS.