Minimal runtime core for agent turn orchestration.

vanna-agent-core provides deterministic turn execution primitives:

1. Turn contracts (UserTurn, RuntimeTurnResult, RuntimeError)
2. Ordered event stream writer
3. In-memory session manager with idempotency cache
4. Runtime lifecycle guard (local vs cloud ownership)
5. Pluggable runTurn(...) orchestration with dependency injection hooks
6. Prompt builder helpers (runtime policy, personality context, extensions)

1. No provider SDK binding (OpenAI/Anthropic/etc)
2. No UI/client framework (TUI/web/desktop)
3. No domain-specific trading logic
4. No gateway/websocket transport implementation

npm install vanna-agent-core

git clone <your-repo-url> agent-core
cd agent-core
npm install
npm test
npm run typecheck

Run the examples:

node examples/minimal-run.mjs
node examples/custom-hooks.mjs

import { createAgentRuntime } from "vanna-agent-core/runtime";

const runtime = createAgentRuntime({
  stateRoot: "/tmp/agent-core-demo",
  execute: async ({ emit, input }) => {
    emit("assistant", "delta", { delta: "Hello" });
    return { ok: true, outputText: `Echo: ${input.message}` };
  }
});

const result = await runtime.turn({
  sessionKey: "demo-session",
  message: "Hello",
  runtimeMode: "local"
});

console.log(result.ok, result.outputText, result.events.length);

Typical app wiring:

1. Create one AgentRuntime instance at service startup.
2. In each API route or worker job, call runtime.turn(...).
3. Forward onEvent callbacks to logs/websocket/UI if needed.

See docs/BUILDING_ON_TOP.md for an end-to-end integration recipe.

runTurn flow:

1. Validate input
2. Resolve session + idempotency
3. Acquire runtime lifecycle lock for workspace/mode
4. Optionally load context via contextProvider
5. Build system prompt
6. Execute model/tool runtime via injected execute
7. Persist in-memory session turn + emit deterministic event stream

createAgentRuntime/runTurn supports these hooks:

1. contextProvider(request) for prompt extensions / metadata
2. promptBuilder(context) for custom prompt assembly
3. execute(input) for your model/tool runner
4. errorClassifier(error) for custom runtime error mapping
5. onEvent(event) for streaming observers

npm test
npm run typecheck

1. examples/minimal-run.mjs
2. examples/custom-hooks.mjs

Use these guides when integrating this package into your own runtime:

1. docs/BUILDING_ON_TOP.md
2. docs/API.md

Current version is 0.x; API can change while extraction stabilizes. Semver policy and contract details are in docs/API.md.