Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

6.2 KB
Raw Blame
/** Private model-control messages. All terminal effects need a separate, revocable core grant. */
import type { ModelControlCheck, ModelControlInput, RuntimeProfileErrorCode } from '../facets/modelControl.js'
import type { RuntimeCatalogModel, RuntimeProfile, RuntimeSession } from '../facets/runtime.js'
import { record, type ReaderEngine } from './protocol.js'
import { runtimeContext } from './runtimeProtocol.js'
import { CONTROL_BYTES, controlEnvelope, controlSize, controlToken } from './controlWire.js'
import { screenCapture } from './screenProtocol.js'

export const MODEL_CONTROL_VERSION = 1
export const MODEL_CONTROL_CAPABILITIES = 'engine_model_control_capabilities'
export const MODEL_CONTROL_VALIDATE = 'engine_model_control_validate'
export const MODEL_CONTROL_APPLY = 'engine_model_control_apply'
export const MODEL_CONTROL_HOST = 'engine.modelControl'
export const MODEL_CONTROL_WAIT_MS = 30_000
export const MODEL_CONTROL_CHECK_MS = 5_000
export const MODEL_CONTROL_QUERY_MS = 10_000
export const MODEL_CONTROL_IN_FLIGHT = 4
export const MODEL_CONTROL_QUERIES = 128
export const MODEL_CONTROL_WRITES = 32
export const MODEL_CONTROL_BYTES = CONTROL_BYTES
export const MODEL_CONTROL_ERRORS: readonly RuntimeProfileErrorCode[] = ['AGENT_NOT_FOUND', 'INVALID_RUNTIME_PROFILE', 'BUSY',
  'UNSUPPORTED_CLI_VERSION', 'MODEL_UNAVAILABLE', 'EFFORT_UNSUPPORTED', 'PLAN_SCOPE_AMBIGUOUS', 'CONFIRM_TIMEOUT', 'TMUX_FAILED']
const EMPTY_STATE = { model: null, effort: null, mode: 'unknown' as const, cliVersion: null, observedAt: null }
const fields = (value: Record<string, unknown>, names: string[]) => Object.keys(value).every(key => names.includes(key))
const text = (v: unknown, max: number): v is string => typeof v === 'string' && v.length <= max
const label = (v: unknown): v is string => text(v, 2000) && !!v && !/[\x00-\x1f\x7f]/.test(v)
export const modelControlToken = controlToken
export const modelControlSize = controlSize

export function modelControlCatalog(value: unknown): value is RuntimeCatalogModel[] {
  return Array.isArray(value) && value.length <= 512 && value.every(m => record(m)
    && fields(m, ['slug', 'displayName', 'listed', 'defaultEffort', 'efforts']) && label(m.slug) && text(m.displayName, 2000)
    && typeof m.listed === 'boolean' && text(m.defaultEffort, 200) && Array.isArray(m.efforts) && m.efforts.length <= 64 && m.efforts.every(label))
}

function profile(value: unknown, session: RuntimeSession, engine: ReaderEngine): RuntimeProfile | null {
  const context = runtimeContext({ session, state: EMPTY_STATE,
    control: { target: value, before: null, modelConfirmed: false, effortConfirmed: false } }, engine)
  const target = context?.control?.target
  return target && label(target.model) && label(target.effort) ? target : null
}

export function modelControlInput(value: unknown, engine: ReaderEngine): ModelControlInput | null {
  if (!record(value) || !fields(value, ['session', 'target', 'current', 'options', 'catalog'])) return null
  const context = runtimeContext({ session: value.session, state: EMPTY_STATE }, engine)
  if (!context) return null
  const target = profile(value.target, context.session, engine)
  const current = value.current === null ? null : profile(value.current, context.session, engine)
  if (!target || !modelControlCatalog(value.catalog) || (value.current !== null && !current) || !Array.isArray(value.options) || value.options.length > 4096
    || !value.options.every(o => record(o) && fields(o, ['id', 'displayName']) && text(o.id, 32768) && text(o.displayName, 32768))) return null
  return { session: context.session, target, current, catalog: structuredClone(value.catalog), options: value.options.map(o => ({ id: o.id, displayName: o.displayName })) }
}

export function modelControlCheck(value: unknown, engine: ReaderEngine): ModelControlCheck | null {
  if (!record(value) || !fields(value, ['session', 'target', 'stage', 'state', 'catalog', 'pane'])
    || (value.stage !== 'target' && value.stage !== 'scope') || !modelControlCatalog(value.catalog)) return null
  const context = runtimeContext({ session: value.session, state: value.state }, engine)
  if (!context) return null
  const target = profile(value.target, context.session, engine)
  const pane = value.pane
  if (!target || (pane !== undefined && (!record(pane) || !fields(pane, ['idle', 'plan', 'dialog', 'draft'])
    || !['idle', 'plan', 'dialog', 'draft'].every(k => typeof pane[k] === 'boolean')))) return null
  return { session: context.session, state: context.state, target, stage: value.stage, catalog: structuredClone(value.catalog),
    ...(pane === undefined ? {} : { pane: { idle: pane.idle as boolean, plan: pane.plan as boolean, dialog: pane.dialog as boolean, draft: pane.draft as boolean } }) }
}

export type ModelControlAction =
  | { kind: 'catalog' }
  | { kind: 'capture'; lines: number }
  | { kind: 'text'; text: string }
  | { kind: 'key'; key: string }
  | { kind: 'waitForModel'; ms: number }
  | { kind: 'waitForProfile'; ms: number }
  | { kind: 'confirmEffort'; effort: string }

export function modelControlAction(value: unknown): value is ModelControlAction {
  if (!record(value)) return false
  if (value.kind === 'catalog') return fields(value, ['kind'])
  if (value.kind === 'capture') return fields(value, ['kind', 'lines']) && Number.isInteger(value.lines) && Number(value.lines) >= 1 && Number(value.lines) <= 100
  if (value.kind === 'text') return fields(value, ['kind', 'text']) && label(value.text)
  if (value.kind === 'key') return fields(value, ['kind', 'key']) && typeof value.key === 'string' && /^(?:Enter|Escape|[1-9])$/.test(value.key)
  if (value.kind === 'confirmEffort') return fields(value, ['kind', 'effort']) && label(value.effort)
  return (value.kind === 'waitForModel' || value.kind === 'waitForProfile') && fields(value, ['kind', 'ms'])
    && Number.isInteger(value.ms) && Number(value.ms) > 0 && Number(value.ms) <= 8000
}

export function modelControlAnswer(action: ModelControlAction, value: unknown): boolean {
  if (action.kind === 'catalog') return modelControlCatalog(value)
  if (action.kind === 'capture') return value === null || screenCapture(value)
  return typeof value === 'boolean'
}

export function modelControlEnvelope(payload: Record<string, unknown>, names: string[]): boolean {
  return controlEnvelope(payload, MODEL_CONTROL_VERSION, names)
}