@363045841yyt/klinechart-ai-runtime 0.1.0

package/src/__tests__/serialization.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect } from 'vitest'
+import {
+  serialize,
+  deserialize,
+  ChartSerializationError,
+} from '../serialization'
+
+describe('serialize', () => {
+  it('produces a SerializedChartState with schemaVersion 1 and a parseable timestamp', () => {
+    const out = serialize({
+      label: 'Test setup',
+      viewport: { zoomLevel: 5, visibleFrom: 0, visibleTo: 100 },
+    })
+    expect(out.schemaVersion).toBe(1)
+    expect(out.label).toBe('Test setup')
+    expect(Date.parse(out.snapshotTakenAt)).not.toBeNaN()
+    expect(out.controllers.viewport?.zoomLevel).toBe(5)
+  })
+
+  it('omits absent controllers from the output', () => {
+    const out = serialize({})
+    expect(out.controllers.viewport).toBeUndefined()
+    expect(out.controllers.theme).toBeUndefined()
+  })
+
+  it('includes all controller blocks when provided', () => {
+    const out = serialize({
+      viewport: { zoomLevel: 1, visibleFrom: 0, visibleTo: 10 },
+      theme: 'dark',
+      indicators: [{ definitionId: 'MA', params: { period: 20 } }],
+      alerts: [
+        {
+          id: 'a1',
+          name: 'BTC 100k',
+          predicate: {
+            kind: 'price-cross',
+            price: 100_000,
+            direction: 'up',
+          },
+          oneShot: true,
+        },
+      ],
+    })
+    expect(out.controllers.viewport).toBeDefined()
+    expect(out.controllers.theme).toBe('dark')
+    expect(out.controllers.indicators).toHaveLength(1)
+    expect(out.controllers.alerts).toHaveLength(1)
+  })
+})
+
+describe('deserialize', () => {
+  it('round-trips through JSON', () => {
+    const original = serialize({ label: 'a', theme: 'dark' })
+    const back = deserialize(JSON.stringify(original))
+    expect(back.schemaVersion).toBe(1)
+    expect(back.label).toBe('a')
+    expect(back.controllers.theme).toBe('dark')
+  })
+
+  it('throws ChartSerializationError on invalid JSON', () => {
+    expect(() => deserialize('not json')).toThrowError(ChartSerializationError)
+  })
+
+  it('throws on non-object root', () => {
+    expect(() => deserialize('"a string"')).toThrowError(
+      /NOT_OBJECT|root must be/,
+    )
+  })
+
+  it('throws on wrong schemaVersion', () => {
+    const bad = JSON.stringify({
+      schemaVersion: 2,
+      snapshotTakenAt: new Date().toISOString(),
+      controllers: {},
+    })
+    expect(() => deserialize(bad)).toThrowError(/schemaVersion/)
+  })
+
+  it('throws on missing/invalid snapshotTakenAt', () => {
+    const bad = JSON.stringify({
+      schemaVersion: 1,
+      controllers: {},
+    })
+    expect(() => deserialize(bad)).toThrowError(/INVALID_TIMESTAMP|ISO/)
+  })
+
+  it('throws when controllers is missing', () => {
+    const bad = JSON.stringify({
+      schemaVersion: 1,
+      snapshotTakenAt: new Date().toISOString(),
+    })
+    expect(() => deserialize(bad)).toThrowError(
+      /MISSING_CONTROLLERS|controllers/,
+    )
+  })
+
+  it('NEVER eval()s — payload is data-only', () => {
+    const evil = JSON.stringify({
+      schemaVersion: 1,
+      snapshotTakenAt: new Date().toISOString(),
+      controllers: {
+        alerts: [
+          {
+            id: 'a',
+            name: 'a',
+            predicate: { evil: 'process.exit(1)' },
+            oneShot: true,
+          },
+        ],
+      },
+    })
+    const back = deserialize(evil)
+    const a = back.controllers.alerts?.[0]
+    expect(a?.predicate).toEqual({ evil: 'process.exit(1)' })
+  })
+})

package/src/__tests__/sessionRegistry.test.ts

@@ -0,0 +1,139 @@
+import { describe, it, expect } from 'vitest'
+import { SessionRegistry, type SessionHandle } from '../sessionRegistry'
+import type { ToolCall, ToolResult } from '../executeTool'
+
+function createMockHandle(sessionId: string): SessionHandle {
+  return {
+    sessionId,
+    executeTool: async (call: ToolCall): Promise<ToolResult> => ({
+      success: true,
+      data: { handled: call.name },
+    }),
+  }
+}
+
+describe('SessionRegistry', () => {
+  it('registers and retrieves a session', () => {
+    const registry = new SessionRegistry()
+    const handle = createMockHandle('s1')
+    registry.register('s1', handle)
+    expect(registry.get('s1')).toBe(handle)
+    expect(registry.has('s1')).toBe(true)
+  })
+
+  it('unregisters a session', () => {
+    const registry = new SessionRegistry()
+    registry.register('s1', createMockHandle('s1'))
+    registry.unregister('s1')
+    expect(registry.get('s1')).toBeUndefined()
+    expect(registry.has('s1')).toBe(false)
+  })
+
+  it('returns active session ids', () => {
+    const registry = new SessionRegistry()
+    registry.register('s1', createMockHandle('s1'))
+    registry.register('s2', createMockHandle('s2'))
+    expect(registry.getActiveSessionIds()).toEqual(['s1', 's2'])
+  })
+
+  it('returns empty array when no sessions', () => {
+    const registry = new SessionRegistry()
+    expect(registry.getActiveSessionIds()).toEqual([])
+  })
+
+  it('handles duplicate registration gracefully', () => {
+    const registry = new SessionRegistry()
+    const oldHandle = createMockHandle('s1')
+    const newHandle = createMockHandle('s1')
+    registry.register('s1', oldHandle)
+    registry.register('s1', newHandle)
+    expect(registry.get('s1')).toBe(newHandle)
+  })
+})
+
+describe('SessionRegistry - state management', () => {
+  it('initializes with empty state on register', () => {
+    const registry = new SessionRegistry()
+    registry.register('s1', createMockHandle('s1'))
+    expect(registry.getState('s1')).toEqual({})
+  })
+
+  it('updates state for a session', () => {
+    const registry = new SessionRegistry()
+    registry.register('s1', createMockHandle('s1'))
+    registry.updateState('s1', {
+      volumeProfile: {
+        controllerId: 'volumeProfile',
+        summary: 'VP ready',
+        facts: { ready: true },
+      },
+    })
+    expect(registry.getState('s1')?.volumeProfile?.summary).toBe('VP ready')
+  })
+
+  it('merges state on multiple updates', () => {
+    const registry = new SessionRegistry()
+    registry.register('s1', createMockHandle('s1'))
+    registry.updateState('s1', {
+      vp: { controllerId: 'vp', summary: 'VP', facts: {} },
+    })
+    registry.updateState('s1', {
+      alerts: { controllerId: 'alerts', summary: 'Alerts', facts: {} },
+    })
+    const state = registry.getState('s1')!
+    expect(state.vp?.summary).toBe('VP')
+    expect(state.alerts?.summary).toBe('Alerts')
+  })
+
+  it('clears state on unregister', () => {
+    const registry = new SessionRegistry()
+    registry.register('s1', createMockHandle('s1'))
+    registry.updateState('s1', {
+      vp: { controllerId: 'vp', summary: 'VP', facts: {} },
+    })
+    registry.unregister('s1')
+    expect(registry.getState('s1')).toBeUndefined()
+  })
+})
+
+describe('SessionRegistry - summary generation', () => {
+  it('returns placeholder when no controllers described', () => {
+    const registry = new SessionRegistry()
+    registry.register('s1', createMockHandle('s1'))
+    expect(registry.getSummary('s1')).toBe('No controllers described.')
+  })
+
+  it('builds summary from controller descriptions', () => {
+    const registry = new SessionRegistry()
+    registry.register('s1', createMockHandle('s1'))
+    registry.updateState('s1', {
+      vp: {
+        controllerId: 'volumeProfile',
+        summary: 'POC at 50000, VA 49000-51000',
+        facts: { poc: 50000 },
+      },
+    })
+    const summary = registry.getSummary('s1')
+    expect(summary).toContain('volumeProfile')
+    expect(summary).toContain('POC at 50000')
+  })
+
+  it('joins multiple controller summaries', () => {
+    const registry = new SessionRegistry()
+    registry.register('s1', createMockHandle('s1'))
+    registry.updateState('s1', {
+      vp: { controllerId: 'vp', summary: 'VP ready', facts: {} },
+      alerts: { controllerId: 'alerts', summary: '3 rules', facts: {} },
+    })
+    const summary = registry.getSummary('s1')
+    expect(summary).toContain('VP ready')
+    expect(summary).toContain('3 rules')
+  })
+
+  it('returns "No controllers described" when state is empty object', () => {
+    const registry = new SessionRegistry()
+    registry.register('s1', createMockHandle('s1'))
+    registry.updateState('s1', {})
+    expect(registry.getSummary('s1')).toBe('No controllers described.')
+  })
+})

package/src/__tests__/toolSchemas.test.ts

@@ -0,0 +1,149 @@
+import { describe, it, expect } from 'vitest'
+import {
+  ALL_TOOLS,
+  TOOL_GROUPS,
+  CHART_NAVIGATION_TOOLS,
+  INDICATOR_TOOLS,
+  ALERT_TOOLS,
+  REPLAY_TOOLS,
+  findTool,
+} from '../toolSchemas'
+
+describe('ALL_TOOLS structural invariants', () => {
+  it('every tool has a unique name', () => {
+    const names = ALL_TOOLS.map((t) => t.name)
+    expect(new Set(names).size).toBe(names.length)
+  })
+
+  it('every tool name follows controller.method convention', () => {
+    for (const tool of ALL_TOOLS) {
+      expect(tool.name).toMatch(/^[a-z][a-zA-Z]+\.[a-zA-Z]+$/)
+    }
+  })
+
+  it('every tool has a non-trivial description (>= 30 chars)', () => {
+    for (const tool of ALL_TOOLS) {
+      expect(tool.description.length).toBeGreaterThanOrEqual(30)
+    }
+  })
+
+  it('every tool inputSchema is type: object with properties', () => {
+    for (const tool of ALL_TOOLS) {
+      expect(tool.inputSchema.type).toBe('object')
+      if (tool.inputSchema.type === 'object') {
+        expect(typeof tool.inputSchema.properties).toBe('object')
+      }
+    }
+  })
+
+  it('safety is one of the three legal values', () => {
+    const legal = new Set(['readonly', 'mutates-state', 'destroys-state'])
+    for (const tool of ALL_TOOLS) {
+      expect(legal.has(tool.safety)).toBe(true)
+    }
+  })
+})
+
+describe('TOOL_GROUPS coverage', () => {
+  it('ALL_TOOLS is the union of every group', () => {
+    const union = [
+      ...TOOL_GROUPS.navigation,
+      ...TOOL_GROUPS.indicators,
+      ...TOOL_GROUPS.alerts,
+      ...TOOL_GROUPS.replay,
+    ]
+    expect(union.length).toBe(ALL_TOOLS.length)
+  })
+
+  it('each group has at least one tool', () => {
+    for (const [name, group] of Object.entries(TOOL_GROUPS)) {
+      expect(group.length).toBeGreaterThan(0)
+      void name
+    }
+  })
+
+  it('CHART_NAVIGATION_TOOLS includes zoomToLevel + setTheme', () => {
+    const names = CHART_NAVIGATION_TOOLS.map((t) => t.name)
+    expect(names).toContain('chart.zoomToLevel')
+    expect(names).toContain('chart.setTheme')
+  })
+
+  it('INDICATOR_TOOLS includes add/remove/updateParams', () => {
+    const names = INDICATOR_TOOLS.map((t) => t.name)
+    expect(names).toEqual(
+      expect.arrayContaining([
+        'indicators.add',
+        'indicators.remove',
+        'indicators.updateParams',
+      ]),
+    )
+  })
+
+  it('ALERT_TOOLS includes the two add-variants + remove', () => {
+    const names = ALERT_TOOLS.map((t) => t.name)
+    expect(names).toContain('alerts.addPriceCross')
+    expect(names).toContain('alerts.addIndicatorCross')
+    expect(names).toContain('alerts.remove')
+  })
+
+  it('REPLAY_TOOLS includes seek/play/pause/setSpeed', () => {
+    const names = REPLAY_TOOLS.map((t) => t.name)
+    expect(names).toEqual(
+      expect.arrayContaining([
+        'replay.seekTo',
+        'replay.play',
+        'replay.pause',
+        'replay.setSpeed',
+      ]),
+    )
+  })
+})
+
+describe('findTool', () => {
+  it('returns the tool when name matches', () => {
+    const t = findTool('chart.zoomToLevel')
+    expect(t).not.toBeNull()
+    expect(t?.name).toBe('chart.zoomToLevel')
+  })
+
+  it('returns null for unknown name', () => {
+    expect(findTool('chart.nonexistent')).toBeNull()
+    expect(findTool('')).toBeNull()
+  })
+})
+
+describe('inputSchema correctness — spot checks', () => {
+  it('chart.zoomToLevel requires `level` and clamps to 1-20', () => {
+    const t = findTool('chart.zoomToLevel')!
+    expect(t.inputSchema.type).toBe('object')
+    if (t.inputSchema.type === 'object') {
+      expect(t.inputSchema.required).toContain('level')
+      const level = t.inputSchema.properties.level
+      expect(level?.type).toBe('integer')
+      if (level?.type === 'integer') {
+        expect(level.minimum).toBe(1)
+        expect(level.maximum).toBe(20)
+      }
+    }
+  })
+
+  it('chart.setTheme uses an enum to constrain values', () => {
+    const t = findTool('chart.setTheme')!
+    if (t.inputSchema.type === 'object') {
+      const theme = t.inputSchema.properties.theme
+      expect(theme?.type).toBe('string')
+      if (theme?.type === 'string') {
+        expect(theme.enum).toEqual(['light', 'dark'])
+      }
+    }
+  })
+
+  it('alerts.addPriceCross required fields enforce id+name+price+direction+oneShot', () => {
+    const t = findTool('alerts.addPriceCross')!
+    if (t.inputSchema.type === 'object') {
+      expect(t.inputSchema.required).toEqual(
+        expect.arrayContaining(['id', 'name', 'price', 'direction', 'oneShot']),
+      )
+    }
+  })
+})

package/src/createWithMcp.ts

@@ -0,0 +1,28 @@
+import {
+  createChartController,
+  type ChartMountOptions,
+  type ChartController,
+} from '@363045841yyt/klinechart-core'
+import { executeTool } from './executeTool'
+
+export interface CreateChartWithMcpOptions extends ChartMountOptions {
+  mcp: {
+    wsUrl?: string
+    autoReconnect?: boolean
+  }
+}
+
+export function createChartControllerWithMcp(
+  opts: CreateChartWithMcpOptions,
+): ChartController {
+  let ctrl: ChartController
+  ctrl = createChartController({
+    ...opts,
+    mcp: {
+      wsUrl: opts.mcp.wsUrl,
+      autoReconnect: opts.mcp.autoReconnect,
+      onToolCall: (call) => executeTool(ctrl, call),
+    },
+  })
+  return ctrl
+}

package/src/describeControllers.ts

@@ -0,0 +1,166 @@
+import type { ControllerDescription } from './types'
+
+export interface VolumeProfileSnapshot {
+  poc: number
+  vah: number
+  val: number
+  totalVolume: number
+  vaVolume: number
+}
+
+export function describeVolumeProfileState(
+  state: VolumeProfileSnapshot | null,
+): ControllerDescription {
+  if (state === null) {
+    return {
+      controllerId: 'volumeProfile',
+      summary:
+        'Volume Profile has not been computed yet — no bars have been ingested.',
+      facts: { ready: false },
+    }
+  }
+
+  const vaPercent =
+    state.totalVolume > 0 ? (state.vaVolume / state.totalVolume) * 100 : 0
+  const vaSpan = state.vah - state.val
+
+  return {
+    controllerId: 'volumeProfile',
+    summary:
+      `Volume Profile shows the Point of Control at ${state.poc.toFixed(2)} — ` +
+      `the price level with the highest traded volume. The Value Area runs from ` +
+      `${state.val.toFixed(2)} (VAL) to ${state.vah.toFixed(2)} (VAH), spanning ` +
+      `${vaSpan.toFixed(2)} and containing ${vaPercent.toFixed(1)}% of total volume.`,
+    facts: {
+      poc: state.poc,
+      vah: state.vah,
+      val: state.val,
+      vaSpan: Number(vaSpan.toFixed(8)),
+      vaPercent: Number(vaPercent.toFixed(2)),
+      totalVolume: state.totalVolume,
+    },
+  }
+}
+
+export interface AnchoredVwapSeriesSnapshot {
+  label: string
+  barIndex: number
+  vwap: number
+  upper1: number
+  lower1: number
+  upper2: number
+  lower2: number
+}
+
+export function describeAnchoredVwap(
+  activeAnchors: ReadonlyArray<AnchoredVwapSeriesSnapshot>,
+  latestPrice: number | null,
+): ControllerDescription {
+  if (activeAnchors.length === 0) {
+    return {
+      controllerId: 'anchoredVwap',
+      summary: 'No Anchored VWAP series are active.',
+      facts: { count: 0 },
+    }
+  }
+
+  const lines: string[] = []
+  for (const a of activeAnchors) {
+    const rel =
+      latestPrice === null
+        ? ''
+        : latestPrice > a.upper1
+          ? ' (price above 1\u03c3 upper band \u2014 overextended)'
+          : latestPrice < a.lower1
+            ? ' (price below 1\u03c3 lower band \u2014 overextended)'
+            : ''
+    lines.push(
+      `"${a.label}" at ${a.vwap.toFixed(2)}, \u00b11\u03c3 [${a.lower1.toFixed(2)}, ${a.upper1.toFixed(2)}]${rel}`,
+    )
+  }
+
+  return {
+    controllerId: 'anchoredVwap',
+    summary:
+      `${activeAnchors.length} Anchored VWAP series active. ` +
+      lines.join('; ') +
+      '.',
+    facts: {
+      count: activeAnchors.length,
+      anchors: lines.join(' | '),
+    },
+  }
+}
+
+export interface FootprintLatestBarSnapshot {
+  barIndex: number
+  delta: number
+  totalVolume: number
+  imbalanceCount: number
+  maxImbalanceRatio: number
+}
+
+export function describeFootprintLatestBar(
+  bar: FootprintLatestBarSnapshot | null,
+  cumulativeDelta: number,
+): ControllerDescription {
+  if (bar === null) {
+    return {
+      controllerId: 'footprint',
+      summary: 'Footprint controller has no bars yet.',
+      facts: { ready: false },
+    }
+  }
+
+  const tone =
+    bar.delta > 0
+      ? 'buy-dominated'
+      : bar.delta < 0
+        ? 'sell-dominated'
+        : 'balanced'
+
+  const imbalance =
+    bar.imbalanceCount > 0
+      ? `${bar.imbalanceCount} diagonal imbalance${bar.imbalanceCount === 1 ? '' : 's'} ` +
+        `(max ratio ${bar.maxImbalanceRatio.toFixed(1)}\u00d7)`
+      : 'no imbalances flagged'
+
+  return {
+    controllerId: 'footprint',
+    summary:
+      `Latest footprint bar #${bar.barIndex} is ${tone} with delta ${bar.delta.toFixed(0)} ` +
+      `against ${bar.totalVolume.toFixed(0)} total volume. ${imbalance}. ` +
+      `Cumulative delta across visible bars: ${cumulativeDelta.toFixed(0)}.`,
+    facts: {
+      barIndex: bar.barIndex,
+      delta: bar.delta,
+      tone,
+      totalVolume: bar.totalVolume,
+      imbalanceCount: bar.imbalanceCount,
+      maxImbalanceRatio: Number(bar.maxImbalanceRatio.toFixed(2)),
+      cumulativeDelta,
+    },
+  }
+}
+
+export interface AlertSnapshot {
+  rulesEnabled: number
+  rulesTotal: number
+  recentEventsCount: number
+}
+
+export function describeAlerts(state: AlertSnapshot): ControllerDescription {
+  return {
+    controllerId: 'alerts',
+    summary:
+      state.rulesTotal === 0
+        ? 'No alert rules configured.'
+        : `${state.rulesEnabled} of ${state.rulesTotal} alert rules are enabled. ` +
+          `${state.recentEventsCount} recent events buffered.`,
+    facts: {
+      rulesEnabled: state.rulesEnabled,
+      rulesTotal: state.rulesTotal,
+      recentEventsCount: state.recentEventsCount,
+    },
+  }
+}

package/src/executeTool.ts

@@ -0,0 +1,92 @@
+import type { ChartController } from '@363045841yyt/klinechart-core'
+import { findTool } from './toolSchemas'
+
+export interface ToolCall {
+  name: string
+  input: Record<string, unknown>
+}
+
+export interface ToolResult {
+  success: boolean
+  error?: string
+  data?: unknown
+}
+
+export function executeTool(
+  chart: ChartController,
+  call: ToolCall,
+): ToolResult {
+  const schema = findTool(call.name)
+  if (!schema) {
+    return { success: false, error: `Unknown tool: ${call.name}` }
+  }
+
+  switch (call.name) {
+    case 'chart.zoomToLevel': {
+      const { level, anchorX } = call.input as {
+        level: number
+        anchorX?: number
+      }
+      chart.zoomToLevel(level, anchorX)
+      return { success: true }
+    }
+
+    case 'chart.setTheme': {
+      const { theme } = call.input as { theme: 'light' | 'dark' }
+      chart.setTheme(theme)
+      return { success: true }
+    }
+
+    case 'indicators.add': {
+      const { definitionId } = call.input as { definitionId: string }
+      const def = chart.catalog.find((d) => d.id === definitionId)
+      const role = def?.role ?? 'main'
+      const instanceId = chart.addIndicator(definitionId, role)
+      return { success: true, data: { instanceId } }
+    }
+
+    case 'indicators.remove': {
+      const { instanceId } = call.input as { instanceId: string }
+      const ok = chart.removeIndicator(instanceId)
+      return ok
+        ? { success: true }
+        : { success: false, error: `Indicator ${instanceId} not found` }
+    }
+
+    case 'indicators.updateParams': {
+      const { instanceId, params } = call.input as {
+        instanceId: string
+        params: Record<string, unknown>
+      }
+      const ok = chart.updateIndicatorParams(instanceId, params)
+      return ok
+        ? { success: true }
+        : { success: false, error: `Indicator ${instanceId} not found` }
+    }
+
+    // Alerts controller does not exist on main yet — placeholder
+    case 'alerts.addPriceCross':
+    case 'alerts.addIndicatorCross':
+    case 'alerts.remove': {
+      return {
+        success: false,
+        error: `"${call.name}" is not implemented — alerts controller is not available`,
+      }
+    }
+
+    // Replay controller does not exist on main yet — placeholder
+    case 'replay.seekTo':
+    case 'replay.play':
+    case 'replay.pause':
+    case 'replay.setSpeed': {
+      return {
+        success: false,
+        error: `"${call.name}" is not implemented — replay controller is not available`,
+      }
+    }
+
+    default: {
+      return { success: false, error: `No handler registered for ${call.name}` }
+    }
+  }
+}