@meistrari/agent-core 0.0.0 → 0.1.0

package/src/supervisor/rpc-client.ts

@@ -0,0 +1,120 @@
+import type { Logger } from '../logger'
+import type { SupervisorRpcMethod, SupervisorRpcResponseEnvelope } from '../supervisor-protocol/rpc'
+import { ulid } from 'ulid'
+
+interface PendingRequest {
+    resolve: (value: unknown) => void
+    reject: (error: unknown) => void
+    timeout: ReturnType<typeof setTimeout>
+    signal: AbortSignal | undefined
+    abort: (() => void) | undefined
+}
+
+export class SupervisorRpcClient {
+    private readonly pending = new Map<string, PendingRequest>()
+    private sendFrame: ((frame: string) => void) | undefined
+
+    constructor(private readonly logger: Logger) {}
+
+    attach(sendFrame: (frame: string) => void): void {
+        this.sendFrame = sendFrame
+    }
+
+    detach(): void {
+        this.sendFrame = undefined
+        this.rejectAll(new Error('Supervisor control connection disconnected.'))
+    }
+
+    async request<T>(input: {
+        method: SupervisorRpcMethod
+        body: unknown
+        deadlineMs: number
+        signal?: AbortSignal
+        validate: (value: unknown) => T
+    }): Promise<T> {
+        const sendFrame = this.sendFrame
+        if (!sendFrame)
+            throw new Error('Supervisor control connection is unavailable.')
+        input.signal?.throwIfAborted()
+        const requestId = ulid()
+        const result = Promise.withResolvers<unknown>()
+        const abort = input.signal
+            ? () => {
+                    sendFrame(JSON.stringify({ kind: 'rpc.cancel', requestId }))
+                    result.reject(input.signal?.reason)
+                }
+            : undefined
+        const timeout = setTimeout(() => {
+            sendFrame(JSON.stringify({ kind: 'rpc.cancel', requestId }))
+            result.reject(new Error(`Supervisor RPC ${input.method} timed out.`))
+        }, input.deadlineMs)
+        timeout.unref?.()
+        this.pending.set(requestId, {
+            resolve: result.resolve,
+            reject: result.reject,
+            timeout,
+            signal: input.signal,
+            abort,
+        })
+        input.signal?.addEventListener('abort', abort as () => void, { once: true })
+        try {
+            sendFrame(JSON.stringify({
+                kind: 'rpc.request',
+                requestId,
+                method: input.method,
+                deadlineMs: input.deadlineMs,
+                body: input.body,
+            }))
+            return input.validate(await result.promise)
+        }
+        finally {
+            this.remove(requestId)
+        }
+    }
+
+    receive(frame: SupervisorRpcResponseEnvelope): void {
+        const pending = this.pending.get(frame.requestId)
+        if (!pending) {
+            this.logger.warn({ requestId: frame.requestId }, 'ignoring unknown supervisor RPC response')
+            return
+        }
+        if (frame.result.status === 'ok')
+            pending.resolve(frame.result.value)
+        else
+            pending.reject(new SupervisorRpcError(frame.result.error))
+    }
+
+    stop(): void {
+        this.sendFrame = undefined
+        this.rejectAll(new Error('Supervisor RPC client stopped.'))
+    }
+
+    private remove(requestId: string): void {
+        const pending = this.pending.get(requestId)
+        if (!pending)
+            return
+        clearTimeout(pending.timeout)
+        if (pending.signal && pending.abort)
+            pending.signal.removeEventListener('abort', pending.abort)
+        this.pending.delete(requestId)
+    }
+
+    private rejectAll(error: Error): void {
+        for (const [requestId, pending] of this.pending) {
+            pending.reject(error)
+            this.remove(requestId)
+        }
+    }
+}
+
+export class SupervisorRpcError extends Error {
+    override readonly name = 'SupervisorRpcError'
+    readonly code: string
+    readonly retryable: boolean
+
+    constructor(input: { code: string, message: string, retryable: boolean }) {
+        super(input.message)
+        this.code = input.code
+        this.retryable = input.retryable
+    }
+}

package/src/supervisor/runtime-handler.ts

@@ -0,0 +1,309 @@
+import type { Logger } from '../logger'
+import type { EphemeralCredentials, SessionBootstrapGitToken } from '../supervisor-protocol/bootstrap'
+import type { WireCommandBody } from '../supervisor-protocol/command-body'
+import type { CommandEnvelope } from '../supervisor-protocol/envelopes/control-plane-to-supervisor'
+import type { EventEnvelope } from '../supervisor-protocol/envelopes/supervisor-to-control-plane'
+import type { WireEventBody } from '../supervisor-protocol/event-body'
+import type { SupervisorStore } from './persistence/supervisor-store'
+import type { SupervisorAgentRuntime, SupervisorProviderFactory } from './provider-factory'
+import { jsonUtf8ByteLength } from '../protocol'
+import { durabilityOf } from '../supervisor-protocol/durability'
+import { wireEventBodySchema } from '../supervisor-protocol/event-body'
+import { maxDurableEventBytes, maxEphemeralDeltaBytes } from '../supervisor-protocol/payload-overflow'
+import { decodeControlPlaneFrame, encodeWireFrame } from '../supervisor-protocol/wire-codec'
+import { SupervisorRpcClient } from './rpc-client'
+
+export interface ResidentSupervisorSocket {
+    send: (data: string) => number
+    close: (code?: number, reason?: string) => void
+    ping: (data?: string | Uint8Array) => number
+}
+
+export interface RuntimeConnectionHandler {
+    attach: (input: { socket: ResidentSupervisorSocket, generation: number, eventAckFloor: number }) => void
+    receive: (socket: ResidentSupervisorSocket, data: string | ArrayBuffer | Uint8Array) => void
+    detach: (socket: ResidentSupervisorSocket) => void
+    drain: (socket: ResidentSupervisorSocket) => void
+}
+
+export class SupervisorRuntimeHandler implements RuntimeConnectionHandler {
+    private readonly rpc: SupervisorRpcClient
+    private readonly lifecycleController = new AbortController()
+    private socket: ResidentSupervisorSocket | undefined
+    private agent: SupervisorAgentRuntime | undefined
+    private createAgentTask: Promise<SupervisorAgentRuntime> | undefined
+    private processing = Promise.resolve()
+    private eventAckFloor = 0
+    private stopped = false
+    private readonly retainedFrames: string[] = []
+    private readonly heartbeatTimer: ReturnType<typeof setInterval>
+
+    constructor(private readonly dependencies: {
+        store: SupervisorStore
+        providerFactory: SupervisorProviderFactory
+        credentials?: EphemeralCredentials
+        gitToken?: SessionBootstrapGitToken
+        logger: Logger
+        onFatal: (error: unknown) => void
+    }) {
+        this.rpc = new SupervisorRpcClient(dependencies.logger)
+        this.heartbeatTimer = setInterval(() => {
+            if (this.socket) {
+                this.emit({
+                    type: 'supervisor.heartbeat',
+                    payload: { unackedEventCount: Math.max(0, this.dependencies.store.localEventMax() - this.eventAckFloor) },
+                })
+            }
+        }, 15_000)
+        this.heartbeatTimer.unref?.()
+    }
+
+    attach(input: { socket: ResidentSupervisorSocket, generation: number, eventAckFloor: number }): void {
+        if (this.stopped) {
+            input.socket.close(1008, 'Supervisor runtime is stopping.')
+            return
+        }
+        const previous = this.socket
+        this.socket = input.socket
+        this.eventAckFloor = input.eventAckFloor
+        this.retainedFrames.length = 0
+        if (previous && previous !== input.socket)
+            previous.close(1008, 'Connection generation was superseded.')
+        this.rpc.attach(frame => this.sendRetained(frame))
+        for (const event of this.dependencies.store.eventsAfter(input.eventAckFloor))
+            this.sendEvent(event)
+        this.schedulePendingCommands()
+    }
+
+    receive(socket: ResidentSupervisorSocket, data: string | ArrayBuffer | Uint8Array): void {
+        if (this.socket !== socket || this.stopped)
+            return
+        const decoded = decodeControlPlaneFrame(frameText(data))
+        if (decoded.kind !== 'ok') {
+            socket.close(1002, 'Malformed control frame.')
+            return
+        }
+        const frame = decoded.frame
+        if (frame.kind === 'command') {
+            try {
+                this.dependencies.store.receiveCommand(frame)
+                this.sendRetained(encodeWireFrame({
+                    kind: 'command.ack',
+                    commandId: frame.commandId,
+                    commandSeq: frame.commandSeq,
+                    status: 'received',
+                }))
+                this.schedulePendingCommands()
+            }
+            catch (error) {
+                this.dependencies.logger.warn({ err: error }, 'rejecting invalid supervisor command')
+                socket.close(1008, 'Supervisor command was rejected.')
+            }
+            return
+        }
+        if (frame.kind === 'event.ack') {
+            if (frame.highWaterMark > this.dependencies.store.localEventMax()) {
+                socket.close(1008, 'Supervisor event ACK is ahead of local state.')
+                return
+            }
+            this.eventAckFloor = Math.max(this.eventAckFloor, frame.highWaterMark)
+            return
+        }
+        if (frame.kind === 'rpc.response') {
+            this.rpc.receive(frame)
+            return
+        }
+        socket.close(1008, 'Bootstrap is valid only before runtime attachment.')
+    }
+
+    detach(socket: ResidentSupervisorSocket): void {
+        if (this.socket !== socket)
+            return
+        this.socket = undefined
+        this.retainedFrames.length = 0
+        this.rpc.detach()
+    }
+
+    drain(socket: ResidentSupervisorSocket): void {
+        if (this.socket !== socket)
+            return
+        this.flushRetained()
+    }
+
+    async refreshSecrets(input: {
+        credentials?: EphemeralCredentials
+        gitToken?: SessionBootstrapGitToken
+    }): Promise<void> {
+        this.dependencies.credentials = input.credentials
+        this.dependencies.gitToken = input.gitToken
+        await this.agent?.refreshSecrets?.(input)
+    }
+
+    async stop(reason: 'sigterm' | 'sigint' | 'fatal_error' = 'sigterm'): Promise<void> {
+        if (this.stopped)
+            return
+        this.stopped = true
+        clearInterval(this.heartbeatTimer)
+        this.lifecycleController.abort(new DOMException('Supervisor is stopping.', 'AbortError'))
+        this.emit({ type: 'supervisor.shutting_down', payload: { reason } })
+        const agent = await this.createAgentTask?.catch(() => undefined) ?? this.agent
+        if (agent) {
+            const closeController = new AbortController()
+            await agent.close({ signal: closeController.signal }).catch(error => this.dependencies.logger.warn({ err: error }, 'agent runtime close failed'))
+        }
+        this.rpc.stop()
+        this.socket?.close(1001, 'Supervisor runtime stopped.')
+        this.socket = undefined
+        await this.processing.catch(() => undefined)
+    }
+
+    private schedulePendingCommands(): void {
+        this.processing = this.processing.then(async () => {
+            const agent = await this.agentRuntime()
+            for (const command of this.dependencies.store.pendingCommands())
+                await this.processCommand({ agent, command })
+        }).catch((error) => {
+            this.dependencies.logger.error({ err: error }, 'supervisor command processing failed')
+            if (!this.stopped)
+                this.dependencies.onFatal(error)
+        })
+    }
+
+    private async agentRuntime(): Promise<SupervisorAgentRuntime> {
+        if (this.agent)
+            return this.agent
+        if (!this.createAgentTask) {
+            const binding = this.dependencies.store.binding()
+            if (!binding)
+                throw new Error('Supervisor runtime cannot start without a binding.')
+            const initialSecrets = {
+                credentials: this.dependencies.credentials,
+                gitToken: this.dependencies.gitToken,
+            }
+            this.createAgentTask = this.dependencies.providerFactory.create({
+                bootstrap: binding.body,
+                ...initialSecrets,
+                rpc: this.rpc,
+                signal: this.lifecycleController.signal,
+            }).then(async (agent) => {
+                if ((this.dependencies.credentials !== initialSecrets.credentials
+                    || this.dependencies.gitToken !== initialSecrets.gitToken) && agent.refreshSecrets) {
+                    await agent.refreshSecrets({
+                        credentials: this.dependencies.credentials,
+                        gitToken: this.dependencies.gitToken,
+                    })
+                }
+                this.agent = agent
+                const snapshot = agent.snapshot()
+                this.dependencies.store.setAgentRunSnapshot(snapshot)
+                this.emit({ type: 'supervisor.agent_run.changed', payload: { agentRun: snapshot } })
+                return agent
+            })
+        }
+        return await this.createAgentTask
+    }
+
+    private async processCommand(input: {
+        agent: SupervisorAgentRuntime
+        command: CommandEnvelope & { body: WireCommandBody }
+    }): Promise<void> {
+        try {
+            await input.agent.handle({
+                commandId: input.command.commandId,
+                commandSeq: input.command.commandSeq,
+                body: input.command.body,
+                signal: this.lifecycleController.signal,
+                emit: body => this.emit(body),
+            })
+            this.dependencies.store.markCommand({ commandSeq: input.command.commandSeq, status: 'applied' })
+            this.emit({
+                type: 'supervisor.command.applied',
+                payload: {
+                    commandId: input.command.commandId,
+                    commandSeq: input.command.commandSeq,
+                    bodyType: input.command.body.type,
+                },
+            })
+        }
+        catch {
+            if (this.lifecycleController.signal.aborted)
+                return
+            this.dependencies.store.markCommand({ commandSeq: input.command.commandSeq, status: 'failed' })
+            this.emit({
+                type: 'supervisor.command.failed',
+                payload: {
+                    commandId: input.command.commandId,
+                    commandSeq: input.command.commandSeq,
+                    bodyType: input.command.body.type,
+                    failure: {
+                        type: 'command',
+                        detail: 'Agent command execution failed.',
+                    },
+                },
+            })
+        }
+    }
+
+    private emit(body: WireEventBody): void {
+        const occurredAt = new Date().toISOString()
+        const parsedBody = wireEventBodySchema.parse(body)
+        if (durabilityOf(parsedBody.type) === 'ephemeral') {
+            if (jsonUtf8ByteLength(parsedBody) > maxEphemeralDeltaBytes)
+                throw new Error(`Ephemeral event exceeds ${maxEphemeralDeltaBytes} bytes.`)
+            this.sendEvent({ kind: 'event', delivery_semantics: 'ephemeral', occurredAt, body: parsedBody })
+            return
+        }
+        if (jsonUtf8ByteLength(parsedBody) > maxDurableEventBytes)
+            throw new Error(`Durable event exceeds ${maxDurableEventBytes} bytes and must use overflow storage.`)
+        this.sendEvent(this.dependencies.store.appendDurableEvent({ occurredAt, body: parsedBody }))
+    }
+
+    private sendEvent(event: EventEnvelope): void {
+        const frame = encodeWireFrame(event)
+        if (event.delivery_semantics === 'ephemeral') {
+            if (this.dependencies.store.localEventMax() > this.eventAckFloor || this.retainedFrames.length > 0)
+                return
+            this.socket?.send(frame)
+            return
+        }
+        this.sendRetained(frame)
+    }
+
+    private sendRetained(frame: string): void {
+        const socket = this.socket
+        if (!socket)
+            return
+        if (this.retainedFrames.length > 0) {
+            this.retainFrame(frame)
+            this.flushRetained()
+            return
+        }
+        if (socket.send(frame) < 0)
+            this.retainFrame(frame)
+    }
+
+    private retainFrame(frame: string): void {
+        if (this.retainedFrames.length >= 5_000) {
+            this.socket?.close(1011, 'Supervisor control backpressure limit exceeded.')
+            return
+        }
+        this.retainedFrames.push(frame)
+    }
+
+    private flushRetained(): void {
+        const socket = this.socket
+        if (!socket)
+            return
+        while (this.retainedFrames.length > 0) {
+            if (socket.send(this.retainedFrames[0]!) < 0)
+                return
+            this.retainedFrames.shift()
+        }
+    }
+}
+
+function frameText(data: string | ArrayBuffer | Uint8Array): string {
+    if (typeof data === 'string')
+        return data
+    return new TextDecoder().decode(data)
+}