eve

Use @onkeiki/eve to run an Eve application as an external Keiki harness. Keiki continues to receive channel messages, manage turn scheduling and delivery, and record the Keiki trace.

Install and mount

The integration requires Node.js 24 or later:

npm install @onkeiki/eve

Or run npx @onkeiki/cli init in your app to do this setup for you (see CLI).

Mount the extension in your Eve app:

import keiki from '@onkeiki/eve'

export default keiki()

The extension accepts signingSecret and instructions settings. Instructions are enabled by default; disable them with keiki({ instructions: false }).

Configure Keiki push

The extension mounts this custom-channel route:

POST /keiki/v1/dispatch

Use the route's full, externally reachable URL as the SDK dispatchUrl:

const kit = AgentKit.create({
  // ...
  harness: {
    type: 'external',
    connectivity: 'push',
    dispatchUrl: 'https://your-eve-app.example/keiki/v1/dispatch',
    timeoutMs: '10 minutes',
  },
})

Keiki signs each push with the agent's external-harness signing secret. Create it once with POST /api/v1/developer/agents/:agentId/harness/signing-secret; the returned secret is shown once. kit.sync() does not create it. Store it in your Eve application's secret manager as KEIKI_SIGNING_SECRET, or provide it in the extension configuration:

export default keiki({ signingSecret: process.env.KEIKI_SIGNING_SECRET })

See the external harness contract for payload verification, turn API responses, and signing details.

Serving several agents

Resolve the signing secret by the dispatch's agent ID:

const secrets: Record<string, string> = { agentA: secretA, agentB: secretB }

export default keiki({
  signingSecret: ({ agentId }) => secrets[agentId],
})

Returning nothing rejects the push with 401 unknown_agent. The resolver runs before the signature is verified, so use a local map or cache rather than making a network call on every request. Eve calls it on every push.

Turns, tools, and delivery

Each Keiki agent and conversation pair has its own Eve channel-local session. New deliveries create a session; later turns for that pair are queued in the same session. Inbound message text is joined with blank lines, and replies include their quoted text. The extension passes Keiki instructions through Eve's channel context option by default; Eve appends channel context to session history. Set instructions: false to omit it.

Retried push dispatches are deduplicated per session using the most recent 20 Keiki turn IDs.

Eve's turn.started event requests Keiki typing. Each non-empty message.completed event is sent through the turn-scoped /messages endpoint, including interim text emitted before an Eve tool call. Eve completion, failure, and cancellation events settle the Keiki turn. The extension does not stream message.appended events; Keiki receives completed assistant messages rather than live token streaming.

The extension adds a dynamic Keiki MCP connection for each turn. Eve's connection_search and connection_execute tools can discover and call Keiki tools, including reply, files, reactions, and channel integrations. Keiki controls whether completed answers are delivered; it captures held-back or steered turns without delivering their answers to the contact.

Mid-turn messages

With midTurnStrategy: 'append', push-mode Eve deliveries that arrive while a turn is running are steered into the existing Eve session. Eve reports the arrival sequence numbers it accepted when completing the matching Keiki turn; messages it did not consume are returned to Keiki's queue and answered by a later turn. An arrival that reaches Eve after the session run ends can be forwarded to a new framework run while the Keiki turn is closing; turn API calls then receive 409 turn_closed, and Keiki requeues the unconsumed message.

Eve 0.72 applies steering before assistant answer output starts; reasoning and search progress do not count as answer output. If output has started, steering waits for the next committed workflow boundary. An executing tool is allowed to finish and checkpoint before the correction is applied. These are Eve's documented steering semantics.

Eve approval prompts and input requests are not bridged to Keiki. Keiki owns the channel and delivery credentials. Keiki's provider credentials and platform API keys are not sent to Eve; the Eve app may use its own model-provider credentials. The app does receive a short-lived ht_ turn token so it can call that turn's API. Never log or reuse this token.

Relay mode

Relay mode requires a connected Keiki development relay (keiki dev); it is not shipped yet. For this extension, use push mode with a dispatch URL Keiki can reach.