Agent Engine

@t2000/engine is the agent engine for conversational finance on Sui — the brain behind Audric. It implements Audric Intelligence, a 4-system stack that orchestrates LLM conversations, 26 financial tools, user confirmations, and MCP integrations into a single async-generator loop.

Not a chatbot. A financial agent. Every action still waits on Audric Passport’s tap-to-confirm. The engine never moves money on its own.

Install

npm install @t2000/engine @t2000/sdk

Requires Node.js 18+ · TypeScript 5+ recommended.

Quick Start

import { AISDKEngine, getDefaultTools } from '@t2000/engine';
import { T2000 } from '@t2000/sdk';

const agent = await T2000.create();

const engine = new AISDKEngine({
  anthropicApiKey: process.env.ANTHROPIC_API_KEY,
  agent,
  tools: getDefaultTools(),
});

for await (const event of engine.submitMessage('What is my balance?')) {
  switch (event.type) {
    case 'text_delta':
      process.stdout.write(event.text);
      break;
    case 'tool_start':
      console.log(`\n[calling ${event.toolName}]`);
      break;
    case 'pending_action':
      // Write tool needs approval — client executes, then calls engine.resumeWithToolResult()
      break;
  }
}

The 4 systems

System	One-line	Lives in
🎛️ Agent Harness	26 tools (18 read + 8 write), one agent.	`v2/engine.ts`, `v2/define-tool.ts`, `v2/tool-policy.ts`, `tools/*`
⚡ Reasoning Engine	Thinks before it acts. 12 guards, 3 priority tiers.	`classify-effort.ts`, `guards.ts`, `engine.ts`
🧠 Memory (MemWal)	Knows your finances + remembers your patterns.	Engine: `prepareStep` + `MemoryStore` interface. Backend: `@mysten-incubation/memwal` (audric-side)
📓 AdviceLog	Remembers what it told you.	`record_advice` audric tool + `buildAdviceContext()`

The engine package owns Agent Harness and Reasoning Engine in code, plus the MemoryStore injection point for Memory. The MemWal vector backend, the daily <financial_context> snapshot cron, and the AdviceLog Prisma model are audric-side.

Agent Harness — 26 tools

Type	Count	Examples
Read	18	`balance_check`, `savings_info`, `health_check`, `rates_info`, `transaction_history`, `swap_quote`, `portfolio_analysis`, `token_prices`, `spending_analytics`, `yield_summary`, `resolve_suins`, `pending_rewards`, `render_canvas`, …
Write	8	`save_deposit`, `withdraw`, `send_transfer`, `borrow`, `repay_debt`, `claim_rewards`, `harvest_rewards`, `swap_execute`

Read tools dispatch in parallel mid-stream (AI SDK v6 tool-call event). Write tools require user confirmation — the engine yields a pending_action event; the host client signs + executes; the engine resumes with the result. Saveable assets: USDC + USDsui (per OPERATION_ASSETS.save / borrow). Everything else is sendable / swappable only.

Reasoning Engine — 12 guards

Every write goes through 12 guards across 3 priority tiers. Guards return one of:

{ pass: true } — silent, allowed
{ pass: true, hint: '…' } — allowed, hint injected for LLM context
{ pass: true, warning: '…' } — allowed, warning surfaced in confirm card
{ pass: false, reason: '…' } — BLOCKED, agent narrates and re-asks

Tier	Guards
Safety	Health Factor, Insufficient Balance, Recipient Validation
Financial	USD Threshold, Slippage Cap, Daily Spend Limit
UX	Allowance Reminder, Network Health, Stale Quote

Plus adaptive thinking effort per turn (cheap vs. expensive reasoning), preflight input validation (no LLM round-trip if the input is malformed), and prompt caching for the system prompt + tool definitions.

Memory — MemWal + financial context

Engine assembles the system prompt in 5 layers via prepareStep:

Base systemPrompt
financialContextBlock (daily snapshot from UserFinancialContext)
<memory_recall> — top-K vector facts from MemWal
skillRecipeBlock (multi-step orchestration playbooks)
messages[] (conversation history)

CLI / MCP / tests use InMemoryMemoryStore (default). Production Audric injects MemWalMemoryStore backed by @mysten-incubation/memwal.

import { InMemoryMemoryStore } from '@t2000/engine';

const engine = new AISDKEngine({
  // ...
  memoryStore: new InMemoryMemoryStore(),
});

Wire your own backend by implementing the MemoryStore interface (recall + write).

AdviceLog — never contradict yourself

Every recommendation the agent makes is logged via the record_advice tool (audric-side). The last 30 days of advice are hydrated into the system prompt each turn so the chat doesn’t contradict itself across sessions (“I told you to deposit USDC last week, here’s the update”).

Event types

type EngineEvent =
  | { type: 'text_delta'; text: string }
  | { type: 'thinking_delta'; text: string }
  | { type: 'thinking_done' }
  | { type: 'tool_start'; toolName: string; toolUseId: string; input: unknown }
  | { type: 'tool_result'; toolName: string; toolUseId: string; result: unknown; isError: boolean }
  | { type: 'pending_action'; action: PendingAction }   // write tool, needs user confirm
  | { type: 'canvas'; html: string }
  | { type: 'turn_complete'; stopReason: StopReason }
  | { type: 'usage'; inputTokens: number; outputTokens: number; cacheReadTokens?: number; cacheWriteTokens?: number }
  | { type: 'error'; error: Error }
  | { type: 'stream_started'; streamId: string };       // emitted FIRST when streamCheckpointStore is configured

Tool permission levels

Level	Behavior
`auto`	Read tools (`balance_check`, `swap_quote`, …). Execute without approval.
`confirm`	Write tools (`save_deposit`, `swap_execute`, …). Yield `pending_action` for client-side signing.
`explicit`	Manual-only, never dispatched by LLM.

USD-aware resolver (resolvePermissionTier(operation, amountUsd, config)) downgrades writes dynamically based on USD value. Under zkLogin (Audric web-v2), every write taps to confirm — the auto-execute path is structurally disabled by design. Under server-signing hosts (@t2000/cli engine usage with a key), sub-threshold writes can auto-execute per the configured preset (conservative / balanced / aggressive).

Streaming + sessions

import {
  AISDKEngine,
  serializeSSE,
  parseSSE,
  MemorySessionStore,
  InMemoryStreamCheckpointStore,
  budgetToolResult,
} from '@t2000/engine';

serializeSSE / parseSSE — wire format helpers for streaming EngineEvent over HTTP.
MemorySessionStore — default SessionStore (in-memory). Hosts inject Redis / Postgres backends.
InMemoryStreamCheckpointStore — replay the live stream after a page reload. Default in CLI / MCP / tests; Audric injects Upstash.
budgetToolResult — caps tool output size with a truncation hint.

MCP integration (external MCPs)

import { McpClientManager, NAVI_MCP_CONFIG, McpPromptAdapter } from '@t2000/engine';

const mcp = new McpClientManager();
await mcp.connect(NAVI_MCP_CONFIG);                // NAVI MCP for live lending reads
const tools = await mcp.listTools();               // wire into AISDKEngine.tools

McpClientManager is backed by @ai-sdk/mcp. McpPromptAdapter is an extension point for consuming MCP prompts as skill recipes — currently dormant; see the design notes in spec/reference/MCP_PROMPTS_INTEGRATION_DECISION.md.

MCP server adapter (expose engine tools)

import { buildMcpTools, registerEngineTools } from '@t2000/engine';

// Build MCP-compatible tools from your engine tool registry
const mcpTools = buildMcpTools(engineTools);

Used by @t2000/mcp internally to expose the engine’s tool definitions as MCP JSON-RPC tools.

What’s in scope vs. host

Engine owns:

LLM orchestration loop (AISDKEngine.submitMessage)
Tool registry, dispatch, permission gates (v2/tool-policy.ts)
12 guards + USD-aware permission resolver
System prompt assembly (5-layer with prepareStep)
MCP client + server adapters
Streaming + checkpointing + session store interfaces

Host owns (e.g. Audric apps/web-v2):

LLM provider keys + model selection (passes via anthropicApiKey or modelInstance)
MemoryStore implementation (MemWal in production, in-memory in tests)
SessionStore + StreamCheckpointStore backends (Redis / Postgres)
Transaction signing + tap-to-confirm UI (engine yields pending_action, host signs)
record_advice tool implementation (AdviceLog Prisma model is audric-side)
<financial_context> snapshot (daily cron; engine just reads the block)

Architecture

User message
    │
    ▼
AISDKEngine.submitMessage()
    │
    ├── LLM Provider (AI SDK v6 streamText via @ai-sdk/anthropic)
    │       ├── text_delta events → streamed to client
    │       ├── tool_start events → AI SDK dispatches isConcurrencySafe reads in parallel
    │       └── pending_action events → client executes write, then resumeWithToolResult()
    │
    ├── Tool registry (v2/tool-policy.ts)
    │       ├── 18 read tools (auto-dispatch, parallel)
    │       └── 8 write tools (confirm-tier, needsApproval round-trip)
    │
    ├── Reasoning layer
    │       ├── classify-effort.ts (cheap vs. expensive thinking)
    │       ├── guards.ts (12 guards, 3 priority tiers)
    │       └── prepareStep (5-layer system prompt assembly)
    │
    ├── Memory layer (engine owns the interface; host owns the backend)
    │       ├── MemoryStore.recall(latestUserMessage) → <memory_recall> block
    │       ├── MemoryStore.write(finishReason, messages) → post-turn analyze
    │       └── financialContextBlock (host-supplied daily snapshot)
    │
    └── Session + streaming
            ├── SessionStore (default: in-memory; prod: Redis)
            ├── StreamCheckpointStore (default: in-memory; prod: Upstash)
            └── Cross-instance abort via AbortSignal threading

Bundling

ESM only (tsup → dist/index.js). Named exports — fully tree-shakeable. Side-effect-free. Version-locked with @t2000/{sdk,cli,mcp} (coordinated releases).

Documentation Index

​Install

​Quick Start

​The 4 systems

​Agent Harness — 26 tools

​Reasoning Engine — 12 guards

​Memory — MemWal + financial context

​AdviceLog — never contradict yourself

​Event types

​Tool permission levels

​Streaming + sessions

​MCP integration (external MCPs)

​MCP server adapter (expose engine tools)

​What’s in scope vs. host

​Architecture

​Bundling

​Links