The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
// Canonical local authority wire adapter. Remote legacy transports keep their
// existing protocol; unsupported explicit semantics fail before network admission.
import { randomUuid } from '@hermes/shared'
export const CANONICAL_GATEWAY_PROTOCOL = 'hermes-gateway-v1'
/** Dial `/api/ws` or a sibling stream beside it. A local gateway's one-use ticket leaves the URL
* for the gateway subprotocol; a remote route keeps its own query credential. */
export function openGatewaySocket(url: string): WebSocket {
const parsed = new URL(url)
if (!parsed.searchParams.has('native_dial')) {return new WebSocket(url)}
const ticket = parsed.searchParams.get('ticket')
if (!ticket) {throw new Error('Native gateway requires a fresh private ticket')}
parsed.searchParams.delete('ticket')
return new WebSocket(parsed.toString(), [CANONICAL_GATEWAY_PROTOCOL, `hermes-gateway-ticket.${ticket}`])
}
export const canonicalProfile = (profile: unknown): string =>
typeof profile === 'string' && profile ? profile : 'default'
export const canonicalSessionKey = (sessionId: unknown, profile?: unknown): string =>
JSON.stringify([canonicalProfile(profile), sessionId])
const admissionObservers = new Set<(admissionId: string, status: string) => void>()
/** Every `prompt.submit` this Desktop's canonical clients send (composer, edit and regenerate,
* Quick Entry, bots) reports its accepted admission here, whichever surface sent it. */
export function observeCanonicalAdmissions(observer: (admissionId: string, status: string) => void): () => void {
admissionObservers.add(observer)
return () => admissionObservers.delete(observer)
}
/** Live events and retained snapshots must describe the same answerable card. */
export function canonicalPromptParams(kind: unknown, sessionId: string, prompt: Record<string, unknown>): Record<string, unknown> {
const choices = Array.isArray(prompt.choices) ? prompt.choices : []
return kind === 'clarify'
? { session_id: sessionId, answers: prompt.answers,
questions: Array.isArray(prompt.questions) ? prompt.questions : [{ qid: prompt.prompt_id, question: prompt.question, choices, multi_select: prompt.multi_select }] }
: { session_id: sessionId, request_id: prompt.prompt_id, command: prompt.command, description: prompt.description, choices,
allow_permanent: choices.includes('always'), edit: prompt.edit }
}
// Only the authenticated adapter can establish this renderer-side provenance;
// a JSON-RPC payload's ordinary `profile` property cannot impersonate it.
const canonicalOwners = new WeakMap<object, string>()
export const canonicalOwnerProfile = (value: object): string | undefined => canonicalOwners.get(value)
export const recordCanonicalOwner = (value: object, profile: string): void => { canonicalOwners.set(value, profile) }
// Mirrors hermes_cli/gateway_mutations.slash_mutation: the typed directives
// that are canonical mutations, not gateway-executed slash commands. Model
// flags (--global/--once/--refresh) have no canonical mutation and stay on the
// exec path so the authority refuses them explicitly.
export function slashMutation(command: string): { operation: string; payload: Record<string, unknown> } | null {
const [name, ...rest] = command.trim().replace(/^\/+/, '').split(/\s+/)
const arg = rest.join(' ').trim()
if (name === 'model') {
if (!arg || arg.startsWith('-') || /(^|\s)--/.test(arg)) { return null }
const [model, ...flags] = arg.split(/\s+/)
return flags.length ? null : { operation: 'model', payload: { model } }
}
const field = ({ branch: 'title', compress: 'focus' } as Record<string, string>)[name]
if (!field) { return null }
return { operation: name, payload: arg ? { [field]: arg } : {} }
}
// The composer picker's `config.set key=model` value: `<model> --provider <id> [--session]`. The
// canonical model mutation is always session-scoped policy (the authority never rewrites
// config.yaml from it), so `--session` carries no extra meaning; any other flag has no canonical
// field and stays on config.set for the authority to refuse explicitly.
export function pickerModelMutation(value: unknown): { model: string; provider: string } | null {
const [model, ...flags] = String(value ?? '').trim().split(/\s+/)
const sessionOnly = flags.at(-1) === '--session'
const rest = sessionOnly ? flags.slice(0, -1) : flags
if (!model || model.startsWith('-') || rest.length !== 2 || rest[0] !== '--provider' || !rest[1] || rest[1].startsWith('-')) {
return null
}
return { model, provider: rest[1] }
}
function mutationSummary(operation: string, value: Record<string, unknown>): string {
if (operation === 'model') {
// `/model reset` already on the configured default answers with the owner's note.
return typeof value.note === 'string' ? value.note : `model: ${value.model}${value.provider ? ` (${value.provider})` : ''}`
}
if (operation === 'branch') { return `branch: ${value.branched_session_id}` }
if (operation === 'compress') {
return value.status === 'preview' ? (value.lines as string[]).join('\n') : `compress: ${value.target_session_id ?? value.session_id}`
}
return `${operation}: ok`
}
// Explicit desktop methods that travel as canonical `session.mutate`.
// `session.branch_stored` / `session.branch_whole` are legacy whole-history branches keyed by a
// stored parent id; the authority has ONE branch, a `branch` mutation on the parent, whose child
// is a local route the authority can restore (a legacy-minted child has no local policy and every
// resume on it answers not_found).
// A message-level branch (`count` = the selected prefix) keeps rows through `through_message_id`.
// Without that durable id the authority would copy the whole history, so it refuses instead.
function branchBoundary(params: Record<string, unknown>): Record<string, unknown> {
const through = params.through_message_id
if (typeof through === 'number' && Number.isInteger(through) && through > 0) { return { through_message_id: through } }
if (params.count !== undefined) { throw new Error('This message is not saved yet; wait for it to settle, then branch from it again') }
return {}
}
const RELAY_HANDLE = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/
const RELAY_SENDER_STAMP = /^(Message from 🤖 [\s\S]+? \(@)[A-Za-z0-9_-]+(\): )/u
// The canonical `bot_relay.deliver` is a closed key set without the legacy `from_*` sender
// fields. Translate them as the legacy bridge did (tui_gateway/methods_bot_relay.py): a bot
// author keyed by the sender's connection (`delivery_turn_author`), and the message's
// `(@handle)` stamp qualified with that connection so a reply never lands on the recipient's
// own same-named bot (#103731; `<handle>@<connection>` always resolves there).
function canonicalBotDelivery(params: Record<string, unknown>): Record<string, unknown> {
const { from_profile: rawProfile, from_handle: rawHandle, from_connection: rawConnection, ...rest } = params
const [profile, connection] = [String(rawProfile ?? '').trim(), String(rawConnection ?? '').trim()]
const handle = String(rawHandle ?? '').trim().replace(/^@/, '')
if (!profile) { return rest }
const author = { id: connection ? `bot:${connection}/${profile}` : `bot:${profile}`, name: handle || profile, is_bot: true }
const qualify = typeof rest.message === 'string' && RELAY_HANDLE.test(handle) && RELAY_HANDLE.test(connection)
const message = qualify ? String(rest.message).replace(RELAY_SENDER_STAMP, `$1${handle}@${connection}$2`) : rest.message
return { ...rest, message, author }
}
// The legacy `prompt.submit` truncation keys (edit / regenerate / restore). The owner has no such
// keys: the cut is a revision-fenced `rewind` mutation on the user row, then a plain submit. The
// deep-cut confirm (#133716) guards the legacy sidecar's implicit cut; the owner's rewind names its
// row explicitly and the user already confirmed before Desktop sent it, so it is dropped here too.
const TRUNCATE_KEYS = ['confirm_truncate', 'confirm_empty_truncate', 'confirm_deep_truncate', 'truncate_before_row_id',
'truncate_before_message_id', 'truncate_before_user_ordinal', 'rebind_survivor_row_ids']
export function splitRewindSubmit(params: Record<string, unknown>): { rewind: Record<string, unknown> | null; submit: Record<string, unknown> } | null {
if (!TRUNCATE_KEYS.some(key => key in params)) { return null }
const row = params.truncate_before_row_id
const submit = Object.fromEntries(Object.entries(params).filter(([key]) => !TRUNCATE_KEYS.includes(key)))
if (typeof row === 'number' && Number.isInteger(row) && row > 0) {
return { rewind: { session_id: params.session_id, target_message_id: row, ...(params.profile !== undefined ? { profile: params.profile } : {}) }, submit }
}
// Only a durable row id names the owner's cut; a message id or ordinal would be a guess.
if (['truncate_before_row_id', 'truncate_before_message_id', 'truncate_before_user_ordinal'].some(key => key in params)) {
throw new Error('This message is not saved yet; wait for it to settle, then edit it again')
}
return { rewind: null, submit }
}
// Session verbs only the legacy sidecar implements: it looks the session up in its own table,
// which never holds an owner session, and answers `session not found` (read by the renderer as a
// reaped runtime). Refused by name until the owner serves them.
// `preview.restart` is served by the owner (gateway/session_tui_side.py).
const SIDECAR_SESSION_VERBS = new Set(['handoff.request', 'handoff.state', 'handoff.fail'])
// The manage_connections card's calls the owner serves for a session-owned operation (gateway/session_connections.py); any other session-owned connector call stays refused.
const OWNER_CONNECTION_VERBS = new Set([
'connection.respond',
'connectors.operation.status',
'connectors.operation.wake',
'connectors.connect'
])
// `config.set` keys the owner serves (tui_gateway/contracts/canonical_projections.py::CanonicalConfigSetParams;
// gateway/session_tui_config.py), with the keys that take a `scope` (`reasoning --global`, the
// Shift+click global yolo zap).
const CANONICAL_CONFIG_KEYS = new Set([
'busy', 'verbose', 'yolo', 'model', 'reasoning', 'fast', 'personality', 'approvals.mode', 'voice.voice_chat_mode',
'display.message_reactions', 'display.in_app_tips', 'display.in_app_tours'
])
const SCOPED_CONFIG_KEYS = new Set(['reasoning', 'yolo'])
// The one guard between a Desktop producer and the owner's closed contracts: translate a legacy
// shape the owner has a canonical form for, refuse by name what it does not serve.
function canonicalProducerFrame(method: string, params: Record<string, unknown>): Record<string, unknown> {
// Any other key, or a scope on a key without one: refuse before the wire, like Ink, instead of a
// bare invalid_params.
if (method === 'config.set' && (!CANONICAL_CONFIG_KEYS.has(String(params.key)) || ('scope' in params && !SCOPED_CONFIG_KEYS.has(String(params.key))))) {
throw new Error(`Changing ${params.key}${'scope' in params ? ` (${params.scope})` : ''} is not available on the shared gateway yet`)
}
const sessionConnector =
method.startsWith('connect') &&
(params.owner as { type?: unknown } | undefined)?.type === 'session' &&
!OWNER_CONNECTION_VERBS.has(method)
if (SIDECAR_SESSION_VERBS.has(method) || sessionConnector) {
throw new Error(`${method} is not available on the shared gateway yet`)
}
// The owner admits identified input only. An identityless producer (session tile, quick entry,
// bot chats) is a fresh send on every call, which is what the legacy wire did with it.
if (method === 'prompt.submit' && !params.submission_id && !params.input_id) { return { ...params, submission_id: randomUuid() } }
return method === 'bot_relay.deliver' ? canonicalBotDelivery(params) : params
}
// The levels `hermes_constants.parse_reasoning_effort` accepts: a session `/reasoning <level>` is the
// owner's `reasoning` mutation; the display words (show/hide/full/clamp) are config.yaml writes.
const REASONING_EFFORTS = new Set(['none', 'false', 'disabled', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max', 'ultra'])
// Frozen-policy edits: a session-scope `/reasoning <level>` (`--global` stays the named refusal, no
// owner config-write verb) and Move to project, which re-homes the execution cwd and TERMINAL_CWD
// with the row (`session_key` names the sidebar row).
function policyEdit(method: string, params: Record<string, unknown>): { session: unknown; operation: string; payload: Record<string, unknown> } | null {
const effort = String(params.value ?? '').trim().toLowerCase()
if (method === 'config.set' && params.key === 'reasoning' && params.scope !== 'global' && REASONING_EFFORTS.has(effort)) {
return { session: params.session_id, operation: 'reasoning', payload: { effort } }
}
// The composer's folder picker on an open chat (main's session.cwd.set) is the same re-home.
if (method === 'session.cwd.set') { return { session: params.session_id, operation: 'workspace', payload: { cwd: params.cwd } } }
return method === 'session.workspace.move' ? { session: params.session_key, operation: 'workspace', payload: { cwd: params.cwd } } : null
}
// Desktop methods that become `session.mutate` once prepareMutation chose an operation.
const POLICY_EDIT_METHODS = new Set(['slash.exec', 'config.set', 'session.workspace.move', 'session.cwd.set'])
const BRANCH_METHODS = new Set(['session.branch', 'session.branch_stored', 'session.branch_whole'])
// Value-setting mutations: re-applying one is harmless, so a later acknowledged edit retires it.
const VALUE_OPERATIONS = new Set(['rename', 'archive', 'model', 'reasoning', 'workspace'])
// `session.model`: a whole canonical model selection (model / provider / reasoning) plus the owner's
// token, as the owner asked it (a deferred pick's confirmation): the same request the TUI resends.
const MUTATION_METHODS = new Set(['session.title', 'session.archive', 'session.compress', 'session.rewind', 'session.model', ...BRANCH_METHODS])
export class CanonicalDesktopProtocol {
private creates = new Map<string, string>()
private revisions = new Map<string, number>()
private mutations = new Map<string, Record<string, unknown>>()
private generations = new Map<string, number>()
private prompts = new Map<string, Record<string, unknown>>()
// admission_id → generation of a turn the authority recovered as `unknown`
// (owner died mid-turn). Only these rows may be acknowledged, and only with
// the generation the authority stamped on them, never the live one.
private unknownAdmissions = new Map<string, { session_id: string; profile: string; generation: number }>()
// [owner, model payload] → the owner's one-time token from a `confirmation_required` model
// answer (a guarded target: cost / data policy / large context; nothing was written). The
// dialog's resend (`confirm_expensive_model: true`, the legacy handshake every Desktop surface
// speaks) carries it as `payload.confirm`. It is spent by the owner's ANSWER to that resend,
// not by sending it: until an answer (applied, refused, re-refused with a fresh token) arrives,
// `sent` keeps the token so a retry after a lost reply re-sends the exact same token-bearing
// request (same retained request id) instead of a new unconfirmed mutation. A re-refusal
// replaces it with an unsent token, so it is never auto-confirmed.
private modelConfirmations = new Map<string, { token: string; sent: boolean }>()
failure(params: Record<string, unknown>, error: unknown) {
const reason = (error as { data?: { reason?: string } })?.data?.reason
// The owner answered (a typed refusal): the confirmed request's outcome is known. A transport
// failure carries no reason; its outcome is unknown and the token stays for the exact retry.
if (typeof reason === 'string') { this.settleModelConfirmation(params) }
// Any typed refusal of a rewind wrote nothing. A derived /undo or /retry is retained by operation
// alone, so keeping the refused request would resend it for every later /undo instead of deriving.
if (typeof reason === 'string' && params.operation === 'rewind') { this.forgetMutation(params) }
// A typed busy refusal of a rewind or a move wrote nothing either; the retry is a new request at the new revision.
if (reason !== 'revision_conflict' && reason !== 'stale_generation' && !(reason === 'session_busy' && ['rewind', 'workspace'].includes(params.operation as string))) { return }
// A confirmed fence refusal did not mutate. Ambiguous transport failures keep
// the original revision/id so a retry cannot overwrite another user's edit.
this.forgetMutation(params)
// The owner names its current fences on the refusal: adopt them so the next attempt presents them.
const data = (error as { data?: { revision?: unknown; execution_generation?: unknown } })?.data
const owner = canonicalSessionKey(params.session_id, params.profile)
// An older request's refusal can arrive after a newer edit committed: never move the fences backwards.
if (typeof data?.revision === 'number' && data.revision > (this.revisions.get(owner) ?? -1)) { this.revisions.set(owner, data.revision) }
if (typeof data?.execution_generation === 'number' && data.execution_generation > (this.generations.get(owner) ?? -1)) {
this.generations.set(owner, data.execution_generation)
}
}
// A fence refusal of a value pick (model / reasoning) that named fresh fences is retried once at them:
// re-applying the same value is harmless, unlike a CAS edit of shared metadata. Only while it is still the
// session's current retained request: a newer pick retired it, and re-preparing it would undo that pick.
retryableFence(params: Record<string, unknown>, error: unknown): boolean {
const data = (error as { data?: { reason?: unknown; revision?: unknown } })?.data
const current = [...this.mutations.values()].some(mutation => mutation.request_id === params.request_id)
return current && ['model', 'reasoning'].includes(params.operation as string) && typeof data?.revision === 'number'
&& (data.reason === 'revision_conflict' || data.reason === 'stale_generation')
}
// Wire method for a prepared request: composer metadata, branch and the
// typed `/model <name>` / `/branch [title]` / `/compress [focus]` directives
// and the dedicated compress action all travel as canonical `session.mutate`;
// everything else keeps its name.
wire(method: string, prepared: Record<string, unknown> = {}): string {
if (MUTATION_METHODS.has(method)) { return 'session.mutate' }
// The warm-cache re-attach: canonical attach is `session.resume`, which
// rebinds the live event transport and returns the same snapshot shape.
if (method === 'session.activate') { return 'session.resume' }
return POLICY_EDIT_METHODS.has(method) && typeof prepared.operation === 'string' ? 'session.mutate' : method
}
// `derived`: the payload was derived from a snapshot (a typed /undo or /retry names the Nth newest user
// turn). Keyed by operation alone, as Ink's mutateCanonical and the classic PreparedMutations do: a
// retry after a lost reply re-presents the original target, never one re-derived from a transcript the
// first attempt already rewound.
private retainedMutation(sessionId: unknown, profile: unknown, operation: string, payload: Record<string, unknown>, withGeneration: boolean, derived = false): Record<string, unknown> {
const owner = canonicalSessionKey(sessionId, profile)
const key = JSON.stringify([owner, operation, derived ? null : payload])
this.retireMutations(owner, key)
const retained = this.mutations.get(key)
if (retained) { return retained }
const revision = this.revisions.get(owner)
if (revision === undefined) { throw new Error('Session revision unavailable; reopen the session before editing metadata') }
const generation = this.generations.get(owner)
if (withGeneration && generation === undefined) { throw new Error('Session execution identity unavailable; reconnect before this command') }
const mutation: Record<string, unknown> = { session_id: sessionId, request_id: randomUuid(), expected_revision: revision,
...(withGeneration ? { expected_generation: generation } : {}), operation, payload }
this.mutations.set(key, mutation)
return mutation
}
prepare(method: string, params: Record<string, unknown>): Record<string, unknown> {
const prepared = this.preparePayload(method, params)
// Routing belongs to the envelope, independently of the canonical payload.
// Creation applies its own default-profile normalization.
return method !== 'session.create' && params.profile !== undefined ? { ...prepared, profile: params.profile } : prepared
}
private fencedMutation(method: string, params: Record<string, unknown>, fenced: { operation: string; payload: Record<string, unknown> }): Record<string, unknown> {
// An edit / regenerate / restore names its target explicitly; a typed /undo or /retry derives it.
const derived = method === 'session.rewind' && params.derived_target === true
// A replay-only probe only ever re-presents the retained rewind (localAnswer handles the rest).
if (derived && params.replay_only === true && !this.retainsDerivedRewind(params.session_id, params.profile)) {
throw new Error('No retained rewind to replay')
}
return this.retainedMutation(params.session_id, params.profile, fenced.operation, fenced.payload, true, derived)
}
// A typed /undo or /retry whose reply was lost is still retained for its exact retry.
private retainsDerivedRewind(sessionId: unknown, profile: unknown): boolean {
return this.mutations.has(JSON.stringify([canonicalSessionKey(sessionId, profile), 'rewind', null]))
}
// A request this protocol answers without the owner, or undefined. A replay-only /undo or /retry
// probe with no retained rewind owes nothing: no request is sent, and the command derives its target.
localAnswer(method: string, params: Record<string, unknown>): Record<string, unknown> | undefined {
if (method === 'session.rewind' && params.replay_only === true && !this.retainsDerivedRewind(params.session_id, params.profile)) {
return { session_id: params.session_id, status: 'nothing', rewound_count: 0 }
}
return undefined
}
// Drop the retained request the owner answered: its outcome is known, so no retry may resend it.
private forgetMutation(params: Record<string, unknown>) {
for (const [key, mutation] of this.mutations) { if (mutation.request_id === params.request_id) { this.mutations.delete(key) } }
}
// Only a session's very next control may retry an ambiguous one: any other verb retires the rest.
private retireMutations(owner: string, keep?: string) {
for (const key of [...this.mutations.keys()]) { if (key !== keep && JSON.parse(key)[0] === owner) { this.mutations.delete(key) } }
}
private preparePayload(method: string, params: Record<string, unknown>): Record<string, unknown> {
const mutation = this.prepareMutation(method, params)
if (mutation) { return mutation }
if (method === 'prompt.submit') { this.retireMutations(canonicalSessionKey(params.session_id, params.profile)) }
if (method === 'session.create') { return this.prepareCreate(params) }
if (method === 'session.activate') {
return { session_id: params.session_id, source: 'desktop', ...(params.profile ? { profile: params.profile } : {}) }
}
// N93: a watch window's legacy `lazy` attach is not in the owner's resume contract (the owner
// holds the agent; nothing to defer). It skipped the REST prefetch, so it takes the transcript.
if (method === 'session.resume' && 'lazy' in params) {
const { lazy: _lazy, ...resume } = params
return { ...resume, omit_messages: false }
}
if (method === 'session.interrupt' || method === 'session.redirect' || method === 'session.steer') {
const generation = params.execution_generation ?? this.generations.get(canonicalSessionKey(params.session_id, params.profile))
if (typeof generation !== 'number') { throw new Error('Session execution identity unavailable; reconnect before controlling this turn') }
return { ...params, session_id: params.session_id, execution_generation: generation }
}
if (method === 'prompt.resolve_unknown') {
const lost = this.unknownAdmissions.get(canonicalSessionKey(params.admission_id, params.profile))
if (!lost || lost.session_id !== params.session_id || lost.profile !== canonicalProfile(params.profile)) { throw new Error('Admission is not an unknown lost turn; reopen the session before acknowledging') }
return { session_id: params.session_id, admission_id: params.admission_id, execution_generation: lost.generation }
}
if (method === 'approval.respond' || method === 'clarify.respond') { return this.preparePromptResponse(method, params) }
return canonicalProducerFrame(method, params)
}
// Metadata, branch and typed slash directives that travel as canonical `session.mutate`; null otherwise.
private prepareMutation(method: string, params: Record<string, unknown>): Record<string, unknown> | null {
const field = ({ 'session.title': 'title', 'session.archive': 'archived' } as Record<string, string>)[method]
if (field) { return this.retainedMutation(params.session_id, params.profile, field === 'title' ? 'rename' : 'archive', { [field]: params[field] }, false) }
// Branch and compress fence the execution generation like the slash directives.
const fenced = ({
'session.branch': () => ({ operation: 'branch', payload: branchBoundary(params) }),
'session.compress': () => ({ operation: 'compress', payload: params.focus_topic ? { focus: String(params.focus_topic) } : {} }),
'session.rewind': () => ({ operation: 'rewind', payload: { target_message_id: params.target_message_id } })
} as Record<string, () => { operation: string; payload: Record<string, unknown> }>)[method]?.()
if (fenced) { return this.fencedMutation(method, params, fenced) }
if (method === 'session.model') {
const payload = { ...(params.payload as Record<string, unknown>), ...(typeof params.confirm === 'string' ? { confirm: params.confirm } : {}) }
return this.retainedMutation(params.session_id, params.profile, 'model', payload, true)
}
if (method === 'session.branch_stored' || method === 'session.branch_whole') {
// The stored-parent form names the parent as `parent_session_id`; the live form as `session_id`.
const parent = params.parent_session_id ?? params.session_id
const payload = typeof params.title === 'string' && params.title ? { title: params.title } : {}
return this.retainedMutation(parent, params.profile, 'branch', payload, true)
}
const policy = policyEdit(method, params)
if (policy) { return this.retainedMutation(policy.session, params.profile, policy.operation, policy.payload, true) }
if (method === 'config.set' && params.key === 'model') {
const pick = pickerModelMutation(params.value)
if (pick) { return this.retainedMutation(params.session_id, params.profile, 'model', this.confirmedModel(params, pick), true) }
}
if (method === 'slash.exec') {
const directive = slashMutation(String(params.command ?? ''))
if (directive) {
const payload = directive.operation === 'model' ? this.confirmedModel(params, directive.payload) : directive.payload
return this.retainedMutation(params.session_id, params.profile, directive.operation, payload, true)
}
}
return null
}
private modelConfirmationKey(params: Record<string, unknown>, payload: Record<string, unknown>): string {
const { confirm: _token, ...target } = payload
return JSON.stringify([canonicalSessionKey(params.session_id, params.profile), target])
}
// A user-confirmed resend of a guarded model target presents the owner's token. While that
// confirmed request's outcome is unknown (reply lost), any retry of the same target is the same
// confirmed intent and re-sends it verbatim: the token is part of the retained mutation's key,
// so the retry keeps its request id and the owner resolves it as an exact retry.
private confirmedModel(params: Record<string, unknown>, payload: Record<string, unknown>): Record<string, unknown> {
const key = this.modelConfirmationKey(params, payload)
const confirmation = this.modelConfirmations.get(key)
if (!confirmation || !(params.confirm_expensive_model || confirmation.sent)) { return payload }
confirmation.sent = true
return { ...payload, confirm: confirmation.token }
}
// The owner answered a token-bearing model request: that token is spent.
private settleModelConfirmation(params: Record<string, unknown>): void {
const payload = params.payload as Record<string, unknown> | undefined
if (params.operation !== 'model' || typeof payload?.confirm !== 'string') { return }
const key = this.modelConfirmationKey(params, payload)
if (this.modelConfirmations.get(key)?.token === payload.confirm) { this.modelConfirmations.delete(key) }
}
// The composer's per-session create options in the owner's create contract: the effort is the
// frozen launch `reasoning`; a manual model pick keeps its `provider`; the speed pick is `service_tier` (main: an explicit tier wins, Fast
// pins priority, Normal pins normal over a profile tier, omitted inherits); `cwd_explicit` is the
// provenance that lets a named profile's own workspace beat an inherited cwd.
private prepareCreate(input: Record<string, unknown>): Record<string, unknown> {
const { reasoning_effort: effort, fast, service_tier: picked, ...params } = input
const tier = typeof picked === 'string' && picked ? picked : fast === true ? 'priority' : fast === false ? 'normal' : undefined
if (typeof effort === 'string' && effort) { params.reasoning = effort }
if (tier) { params.service_tier = tier }
if (typeof params.cwd_explicit !== 'boolean') { delete params.cwd_explicit }
const allowed = new Set(['request_id', 'source', 'cwd', 'model', 'provider', 'toolsets', 'reasoning', 'profile', 'cols', 'title', 'hidden', 'follow_profile_config', 'service_tier', 'cwd_explicit'])
const unsupported = Object.keys(params).filter(key => !allowed.has(key))
if (unsupported.length) { throw new Error(`Canonical gateway does not support explicit session options: ${unsupported.join(', ')}`) }
// RT-26: the picked profile always rides, `default` included: a socket launched as a named
// profile (active-profile.json) reads an omitted profile as its own launch profile.
const result = Object.fromEntries(Object.entries(params).filter(([key, value]) =>
['request_id', 'cwd', 'model', 'provider', 'toolsets', 'reasoning', 'title', 'hidden', 'follow_profile_config', 'service_tier', 'cwd_explicit'].includes(key) || (key === 'profile' && typeof value === 'string' && value !== '')))
const key = JSON.stringify(result)
const requestId = params.request_id ?? this.creates.get(key) ?? randomUuid()
this.creates.set(key, String(requestId))
return { ...result, request_id: requestId, source: 'gui' }
}
private preparePromptResponse(method: string, params: Record<string, unknown>): Record<string, unknown> {
const id = String(params.prompt_id ?? params.request_id ?? '')
const prompt = this.prompts.get(canonicalSessionKey(id, params.profile))
const sessionId = params.session_id ?? prompt?.session_id
if (!prompt || prompt.session_id !== sessionId || prompt.profile !== canonicalProfile(params.profile) ||
prompt.execution_generation !== this.generations.get(canonicalSessionKey(sessionId, params.profile))) {
throw new Error('Prompt is stale or unavailable; reconnect before responding')
}
const field = method === 'approval.respond' ? 'choice' : 'answer'
return { session_id: sessionId, execution_generation: prompt.execution_generation, prompt_id: id, [field]: params[field] }
}
private reconcileUnknownAdmissions(sid: string, profile: string, pending: Array<Record<string, unknown>>): void {
for (const [id, lost] of this.unknownAdmissions) {
if (lost.session_id === sid && lost.profile === profile) { this.unknownAdmissions.delete(id) }
}
for (const row of pending) {
if (row?.status === 'unknown' && typeof row.admission_id === 'string' && typeof row.execution_generation === 'number') {
this.unknownAdmissions.set(canonicalSessionKey(row.admission_id, profile), { session_id: sid, profile, generation: row.execution_generation })
}
}
}
// Turns advance the CAS revision without a session.updated event; the pending session.info fanout
// is where a viewer learns the value its next mutation must present. N91: another viewer's
// committed mutation broadcasts its receipt as session.updated: adopt it monotonically (a
// replayed older receipt never rewinds) and settle this viewer's superseded retained edits.
private adoptEventRevision(type: string, sid: string, profile: string, payload: Record<string, unknown>): void {
const owner = canonicalSessionKey(sid, profile)
const revision = payload.revision
if (typeof revision !== 'number') { return }
if (type === 'session.info') { this.revisions.set(owner, revision) }
if (type === 'session.updated' && (payload.session_id ?? sid) === sid && revision > (this.revisions.get(owner) ?? -1)) {
this.revisions.set(owner, revision)
this.retireSupersededMutations({ session_id: sid, profile }, revision)
}
}
event(event: { type: string; session_id?: string; profile?: string; execution_generation?: unknown; payload?: unknown }) {
const payload = event.payload as Record<string, unknown> | undefined
if (!payload || !event.session_id) { return }
const sid = event.session_id
const profile = canonicalProfile(event.profile)
const owner = canonicalSessionKey(sid, profile)
if (Array.isArray(payload.pending)) { payload.pending_submissions = payload.pending.map(row => ({ ...row, user: row.text })) }
const generation = event.execution_generation ?? payload.execution_generation
if (typeof generation === 'number') {
const current = this.generations.get(owner) ?? -1
if (generation < current) { return }
this.generations.set(owner, generation)
}
// C20: only a frame that passed the generation fence may retire a live Discard action.
if (Array.isArray(payload.pending)) { this.reconcileUnknownAdmissions(sid, profile, payload.pending) }
this.adoptEventRevision(event.type, sid, profile, payload)
// A pick deferred during a turn asked at the boundary (a guarded target): keep the owner's token, so
// the user's confirmed resend of that target carries it exactly like an idle pick's confirmation.
if (event.type === 'session.updated' && payload.operation === 'model' && payload.status === 'confirmation_required'
&& typeof payload.confirm === 'string' && payload.payload && typeof payload.payload === 'object') {
this.modelConfirmations.set(this.modelConfirmationKey({ session_id: sid, profile }, payload.payload as Record<string, unknown>), { token: payload.confirm, sent: false })
}
if (typeof payload.prompt_id === 'string') {
if (event.type.endsWith('.settled')) { this.prompts.delete(canonicalSessionKey(payload.prompt_id, profile));
return }
if (event.type === 'approval.request' || event.type === 'clarify.request') {
payload.request_id = payload.prompt_id
this.prompts.set(canonicalSessionKey(payload.prompt_id, profile), { ...payload, session_id: sid, profile })
}
}
}
result(method: string, params: Record<string, unknown>, value: any): any {
if (!value || typeof value !== 'object') { return value }
const mutation = MUTATION_METHODS.has(method) || (POLICY_EDIT_METHODS.has(method) && typeof params.operation === 'string')
this.adoptRevision(params, value, mutation)
if (mutation) { return this.mutationReceipt(method, params, value) }
if (method === 'session.create') {
for (const [key, id] of this.creates) { if (id === params.request_id) { this.creates.delete(key) } }
}
if (method === 'prompt.submit' || method === 'prompt.resolve_unknown') { return this.admissionReceipt(method, params, value) }
if (method === 'session.resume' || method === 'session.create' || method === 'session.activate') { return this.snapshotResult(value, params.profile) }
if (method === 'session.events.since') {
for (const event of value.events ?? []) { this.event({ ...event, profile: canonicalProfile(params.profile) }) }
}
return value
}
// An exact-retry mutation receipt replays its ORIGINAL revision; never move the CAS value backwards.
private adoptRevision(params: Record<string, unknown>, value: any, mutation: boolean): void {
if (typeof value.session_id !== 'string' || typeof value.revision !== 'number') { return }
const owner = canonicalSessionKey(value.session_id, params.profile)
if (!mutation || value.revision >= (this.revisions.get(owner) ?? -1)) { this.revisions.set(owner, value.revision) }
}
private admissionReceipt(method: string, params: Record<string, unknown>, value: any): any {
if (method === 'prompt.submit') {
// TUI-26: a bare stop phrase typed into a LOCAL voice chat ended that chat on the owner and
// admitted nothing. An allowlisted no-admission variant: only these fields pass through.
if (value.voice_stopped === true && value.admission_id === undefined && value.ref === undefined) {
return { voice_stopped: true, session_id: params.session_id, submission_id: params.submission_id ?? params.input_id }
}
if (value.ref?.session_id !== params.session_id || typeof value.admission_id !== 'string') {
throw new Error('Canonical admission receipt destination mismatch')
}
for (const observe of admissionObservers) { observe(value.admission_id, String(value.status ?? '')) }
return { ...value, session_id: value.ref.session_id, submission_id: params.submission_id ?? params.input_id }
}
if (value.ref?.session_id !== params.session_id || value.admission_id !== params.admission_id) {
throw new Error('Canonical admission receipt destination mismatch')
}
this.unknownAdmissions.delete(canonicalSessionKey(params.admission_id, params.profile))
return { ...value, session_id: value.ref.session_id }
}
private mutationReceipt(method: string, params: Record<string, unknown>, value: any): any {
if (value.session_id !== params.session_id) { throw new Error('Metadata receipt destination mismatch') }
this.forgetMutation(params)
this.settleModelConfirmation(params)
this.retireSupersededMutations(params, value.revision)
if (params.operation === 'model' && value.status === 'confirmation_required' && typeof value.confirm === 'string') {
// The owner wrote nothing: answer in the legacy handshake (`confirm_required` +
// `confirm_message`) so the shared confirm dialog asks, and keep the token for its resend.
this.modelConfirmations.set(this.modelConfirmationKey(params, params.payload as Record<string, unknown>), { token: value.confirm, sent: false })
const refusal = { ...value, confirm_required: true }
return method === 'slash.exec' ? { ...refusal, type: 'exec', output: value.confirm_message } : refusal
}
if (BRANCH_METHODS.has(method)) {
return { ...value, session_id: value.branched_session_id, stored_session_id: value.branched_session_id, parent_session_id: params.session_id, message_count: value.copied_messages }
}
if (method === 'slash.exec') { return { ...value, type: 'exec', output: mutationSummary(params.operation as string, value) } }
// A pick on a running session is recorded for the next turn (the legacy `deferred` answer).
if (params.operation === 'model' && value.status === 'deferred') { return { ...value, ok: true, deferred: true } }
// The legacy config.set answer every reasoning caller reads (`result.value`).
return params.operation === 'reasoning' ? { ...value, ok: true, value: value.effort } : { ...value, ok: true }
}
// An acknowledged mutation at revision R settles every older retained value-setting request of
// the same owner: it either applied before R or can only be refused, so replaying its request
// id would return a stale receipt for a later, equal edit. Its confirmed model token goes with
// it. Branch/compress stay retained: a new request id there would execute a second time.
private retireSupersededMutations(params: Record<string, unknown>, revision: unknown): void {
if (typeof revision !== 'number') { return }
const owner = canonicalSessionKey(params.session_id, params.profile)
for (const [key, mutation] of this.mutations) {
const [keyOwner, operation] = JSON.parse(key)
if (keyOwner === owner && VALUE_OPERATIONS.has(operation) && (mutation.expected_revision as number) < revision) {
this.mutations.delete(key)
this.settleModelConfirmation({ ...mutation, profile: params.profile })
}
}
}
private snapshotResult(value: any, route: unknown): any {
const sid = value.session_id
const profile = canonicalProfile(route)
this.event({ type: 'session.info', session_id: sid, profile, payload: value })
const prompts = (value.prompts ?? []).map((prompt: Record<string, unknown>) => {
const projected = { ...prompt, request_id: prompt.prompt_id }
this.event({ type: `${prompt.kind}.request`, session_id: sid, profile, payload: projected })
return projected
})
// The owner's server requests (setup cards, batch clarify, sudo) ride beside the projected prompts.
const open_requests = [...(value.open_requests ?? []), ...prompts.map((prompt: Record<string, unknown>) => ({
id: prompt.prompt_id, method: prompt.kind, params: canonicalPromptParams(prompt.kind, sid, prompt)
}))]
return { ...value, open_requests, pending_approval: prompts.find((p: any) => p.kind === 'approval'), pending_clarify: prompts.find((p: any) => p.kind === 'clarify'), info: { ...value.info, stored_session_id: value.stored_session_id, pending_submissions: value.pending_submissions, replay_epoch: value.replay_epoch, last_sequence: value.last_sequence, execution_generation: value.execution_generation, running: value.running } }
}
// The canonical compress receipt carries counts, not the retained transcript;
// the compress action repaints only from `messages`, so resume the session
// through the normal request path (which also re-primes revision/generation).
async settle(method: string, params: Record<string, unknown>, value: any, request: (method: string, params: Record<string, unknown>) => Promise<any>): Promise<any> {
if (method !== 'session.compress' && !(method === 'slash.exec' && params.operation === 'compress')) { return value }
// `--preview` in the focus argument is a read-only report: no transcript changed.
if (value?.status === 'preview') { return { ...value, host_ack: { output: (value.lines as string[]).join('\n') } } }
const resumed = await request('session.resume', { session_id: params.session_id, ...(params.profile !== undefined ? { profile: params.profile } : {}) })
return { ...value, messages: resumed.messages, info: resumed.info, host_ack: { output: `compressed context: ${value.message_count} messages retained` } }
}
}