@zclaudia/agent-runtime

Portable execution host for agent runtime plugins built against @zclaudia/plugin-sdk.

It activates a plugin through its manifest entrypoint, normalizes provider events, tracks run and provider session state, emits versioned host-neutral events, and exposes injectable permission and session-store ports. It intentionally has no dependency on the ZClaudia application.

Install

pnpm add @zclaudia/agent-runtime @zclaudia/plugin-sdk

Run an adapter

import { AgentRuntime } from '@zclaudia/agent-runtime';
import type { ExternalAgentAdapter } from '@zclaudia/plugin-sdk/providers';

const adapter: ExternalAgentAdapter = {
  type: 'example',
  async *run(input) {
    yield { type: 'assistant_delta', content: `Hello ${input}` };
    yield { type: 'provider_turn_finished' };
  },
};

const runtime = new AgentRuntime();
const run = runtime.start({
  adapter,
  input: 'world',
  cwd: process.cwd(),
});

for await (const event of run.events) {
  console.log(event);
}

await run.done;

Use loadAgentPlugin from @zclaudia/agent-runtime/plugin-host when the adapter comes from an installed plugin manifest. Session stores and event normalization are available from the session-store and normalize subpath exports.

Design boundary

This package owns host-neutral run orchestration only. Provider contracts live in @zclaudia/plugin-sdk; host tool exposure lives in @zclaudia/agent-tool-bridge; application persistence, HTTP routes, and UI state remain the responsibility of the embedding host.

Development

pnpm install
pnpm check

Node.js 22.19 or newer is required.

Release

The Publish to npm workflow uses npm trusted publishing. Create a GitHub release whose tag exactly matches v${package.json.version} (for example, v0.1.0) after configuring this repository as a trusted publisher for @zclaudia/agent-runtime.