@gonk/eve-host

Eve extension packaging plus small, application-owned helpers for binding a Gonk principal, durable channel/persona identity, and an Eve session to one turn.

What this package does

• Ships an Eve extension with a namespaced dynamic instruction contribution.
• Normalizes direct and MCP callers into one AgentTurnEnvelope (exported from @gonk/eve-host/guard).
• Provides a bound Eve channel that authenticates the caller, verifies application-owned principal/channel/persona/session records, and only then calls Eve's public send surface.
• Derives short-lived, resource-scoped delegations from that authorized turn for direct Gonk calls and authenticated HTTP MCP calls.
• Projects a host-injected Gonk ToolRegistry as Eve-native step-scoped dynamic tools through @gonk/eve-host/tools.

The extension's dynamic instruction is context projection only. It is not an authorization boundary. The application owns ingress authentication, durable binding and membership records, the delegation signer and revocation source, and the mapping from an authorized Eve turn to its downstream MCP client.

import {
  createBoundEveChannel,
  createDelegatedMcpAuthenticator,
  createSignedDelegationProvider,
  makeDelegatedMcpAuthContext,
} from "@gonk/eve-host/guard";

execution.eveSessionId is durable identity. execution.continuationToken is an opaque Eve resume credential; the channel never substitutes one for the other. The channel also requires Eve's authenticated principal to equal the guarded Gonk principal before it can send.

Eve and the neutral execution binding

@gonk/persona deliberately knows nothing about Eve. At the Eve-host boundary, EveMemoryHost accepts the trusted eveSessionId from an authorized Eve turn and writes it to the persona contract as executionSessionId. The value is the same durable execution identity, but the neutral field lets other hosts make the same immutable binding without inheriting Eve vocabulary. Eve's continuationToken remains a separate opaque resume credential and is never stored as the execution binding.

onAuthorizedTurn is the application seam for calling provider.issueForTurn(envelope, ...) and placing the resulting bearer where that turn's Eve-to-Gonk MCP connection can use it. The HTTP authenticator reads the bearer from the real Authorization header, while makeDelegatedMcpAuthContext revalidates it for discovery and every tool call. No caller identity is accepted from tool input or an unsigned header.

Structured-memory read path

EveMemoryHost exposes the read half of the structured-memory contract without moving authorization into model input:

• identityAtSessionStart(turn) caches the authored identity and bounded relationship floor for that verified principal. Repeated calls in the same execution session are byte-identical. identityAfterCompaction(turn) is the explicit cache-rebuild seam.
• buildRecallReadTool(turn) returns a recall_read tool already bound to the authenticated turn. Its input has only query and limit; callers cannot choose a principal, persona, or scope.
• automaticRecallForTurn(turn, text) returns an invisible append-only message containing bounded relevant records not previously delivered in that execution session. Prepend the message to the latest turn. Never append it to the system prompt.

The structured record read currently uses its rebuildable lexical projection. Semantic/vector projection remains additive future work: the canonical records and their audience rules stay authoritative, and lexical recall remains the fallback when embeddings or the vector backend are unavailable.

These helpers prove transport authentication and Gonk authorization parity. They do not implement an interactive approval or human-in-the-loop channel; that remains a separate host policy and UI concern.

Eve-native Gonk tools

Use createGonkToolResolver when the application and Eve run in the same trusted host process and an HTTP MCP bridge would only add another credential and replay path.

// agent/tools/gonk.ts
import { createGonkToolResolver } from "@gonk/eve-host/tools";
import { registry } from "../gonk/registry.js";

export default createGonkToolResolver({
  registry,
  authorizeDiscovery: async ({ tool, context }) =>
    canDiscoverTool(context.session.auth.current, tool),
  makeContext: async ({ eve }) => ({
    signal: eve.abortSignal,
    log,
    cwd: process.cwd(),
    env: process.env,
    auth: await authContextFor(eve.session.auth.current),
  }),
  approval: ({ gonkApproval }) =>
    gonkApproval?.tier === "read" ? "not-applicable" : "user-approval",
});

The resolver runs on Eve's step.started event so the returned tools keep live execute closures. authorizeDiscovery and makeContext are required and fail closed when omitted, including for untyped JavaScript callers. Discovery is filtered per Eve session/channel context, execution always goes through ToolRegistry.invoke with an authenticated Gonk context, and the returned value preserves Gonk's { ok, data/display/error, events } semantics. Eve approval is only a host UI decision; it does not replace Gonk authorization or registry approval policy.

Mounting

// agent/extensions/gonk.ts
export { default } from "@gonk/eve-host";

Eve namespaces its contribution under the mount name. With the example above, the instruction contribution is gonk__identity.

Version support

This package is built and clean-room checked against Eve 0.27.0. eve remains a peer dependency so the consuming agent supplies the runtime.