@meistrari/agent-core 0.0.0 → 0.1.1

package/src/supervisor/websocket-server.ts

@@ -0,0 +1,435 @@
+import type { Server, ServerWebSocket } from 'bun'
+import type { Buffer } from 'node:buffer'
+import type { Logger } from '../logger'
+import type { BootstrapBinder } from './bootstrap-binder'
+import type { ResidentSupervisorConfig } from './config'
+import type { VerifySupervisorControlAuthority } from './control-authority-verifier'
+import type { RuntimeConnectionHandler } from './runtime-handler'
+import {
+    supervisorBootstrapRejectionReceiptCloseCode,
+    supervisorBootstrapRejectionReceiptCloseReason,
+} from '../supervisor-protocol/bootstrap-rejection-receipt'
+import { sandboxControlAuthorityHeaderName } from '../supervisor-protocol/control-authority'
+import { decodeControlPlaneFrame, encodeWireFrame } from '../supervisor-protocol/wire-codec'
+
+const sessionHeader = 'x-coding-agent-session-id'
+const sessionSandboxHeader = 'x-coding-agent-session-sandbox-id'
+const runtimeConnectionAttemptHeader = 'x-coding-agent-runtime-connection-attempt-id'
+const controlAuthorityHeader = sandboxControlAuthorityHeaderName.toLowerCase()
+const generationHeader = 'x-coding-agent-connection-generation'
+const eventAckHeader = 'x-coding-agent-event-ack'
+const e2bSandboxHeader = 'e2b-sandbox-id'
+const nativePingIntervalMs = 15_000
+const idleTimeoutSeconds = 60
+const maximumControlFrameBytes = 128 * 1024
+const protocolErrorCloseCode = 1002
+const policyViolationCloseCode = 1008
+const internalErrorCloseCode = 1011
+const terminalRejectionReceiptBudgetMs = 5_000
+const listenerStopBudgetMs = 500
+
+interface SocketData {
+    sessionId: string
+    runtimeConnectionAttemptId: string
+    generation: number
+    eventAckFloor: number
+    handler?: RuntimeConnectionHandler
+    runtimeAttached: boolean
+    messageChain: Promise<void>
+    terminalRejection?: {
+        terminate: () => void
+        timeout: ReturnType<typeof setTimeout>
+    }
+}
+
+export interface SupervisorBootstrapStartupStageFact {
+    event: 'sandbox.startup-stage'
+    stage: 'bootstrap-persisted' | 'bootstrap-readiness-sent'
+    outcome: 'success' | 'failure'
+    duration: number
+    sessionId: string
+}
+
+interface Dependencies {
+    config: ResidentSupervisorConfig
+    logger: Logger
+    health: () => unknown
+    getBoundSessionId: () => string | undefined
+    getLocalEventMax: () => number
+    verifyControlAuthority: VerifySupervisorControlAuthority
+    acceptBoundConnectionGeneration: (input: { generation: number, runtimeConnectionAttemptId: string }) => void
+    bindBootstrap: BootstrapBinder
+    onStartupStage: (fact: SupervisorBootstrapStartupStageFact) => void
+}
+
+export class ResidentSupervisorWebSocketServer {
+    private readonly sockets = new Set<ServerWebSocket<SocketData>>()
+    private server: Server<SocketData> | undefined
+    private pingTimer: ReturnType<typeof setInterval> | undefined
+    private localSandboxId: string | undefined
+    private localSandboxIdRead: Promise<string> | undefined
+    private authoritativeSocket: ServerWebSocket<SocketData> | undefined
+
+    constructor(private readonly dependencies: Dependencies) {}
+
+    start(): void {
+        if (this.server)
+            return
+        const { config } = this.dependencies
+        const websocket: Bun.WebSocketHandler<SocketData> = {
+            perMessageDeflate: false,
+            maxPayloadLength: maximumControlFrameBytes,
+            idleTimeout: idleTimeoutSeconds,
+            open: socket => this.onOpen(socket),
+            message: (socket, message) => this.onMessage(socket, message),
+            close: (socket, code, reason) => this.onClose(socket, code, reason),
+            drain: socket => this.onDrain(socket),
+        }
+        if (config.unixSocketPath) {
+            this.server = Bun.serve<SocketData>({
+                unix: config.unixSocketPath,
+                fetch: async (request, server) => await this.handleRequest(request, server),
+                websocket,
+            })
+        }
+        else {
+            this.server = Bun.serve<SocketData>({
+                hostname: config.host,
+                port: config.port,
+                idleTimeout: idleTimeoutSeconds,
+                fetch: async (request, server) => await this.handleRequest(request, server),
+                websocket,
+            })
+        }
+        this.pingTimer = setInterval(() => {
+            for (const socket of this.sockets)
+                socket.ping()
+        }, nativePingIntervalMs)
+        this.pingTimer.unref?.()
+    }
+
+    port(): number | undefined {
+        return this.server?.port
+    }
+
+    async stop(): Promise<void> {
+        if (this.pingTimer)
+            clearInterval(this.pingTimer)
+        this.pingTimer = undefined
+        for (const socket of this.sockets) {
+            this.cancelPendingTerminalRejection(socket)
+            socket.close(1001, 'Supervisor listener stopping.')
+            socket.terminate()
+        }
+        this.sockets.clear()
+        this.authoritativeSocket = undefined
+        const server = this.server
+        this.server = undefined
+        if (server) {
+            const stopping = server.stop(true)
+            const completed = await Promise.race([
+                stopping.then(() => true),
+                Bun.sleep(listenerStopBudgetMs).then(() => false),
+            ])
+            if (!completed) {
+                this.dependencies.logger.warn({}, 'supervisor listener stop exceeded its drain budget')
+                void stopping.catch(error => this.dependencies.logger.warn({ err: error }, 'supervisor listener stopped with an error'))
+            }
+        }
+    }
+
+    private async handleRequest(request: Request, server: Server<SocketData>): Promise<Response | undefined> {
+        const url = new URL(request.url)
+        if (request.method === 'GET' && url.pathname === this.dependencies.config.healthPath) {
+            return Response.json(this.dependencies.health())
+        }
+        if (request.method !== 'GET' || url.pathname !== this.dependencies.config.controlPath)
+            return new Response('Not found', { status: 404 })
+
+        const sessionId = request.headers.get(sessionHeader)
+        const sessionSandboxId = request.headers.get(sessionSandboxHeader)
+        const runtimeConnectionAttemptId = request.headers.get(runtimeConnectionAttemptHeader)
+        const authorityAssertion = request.headers.get(controlAuthorityHeader)
+        const sandboxId = request.headers.get(e2bSandboxHeader)
+        const generation = parseBoundedInteger(request.headers.get(generationHeader), 1)
+        const eventAckFloor = parseBoundedInteger(request.headers.get(eventAckHeader), 0)
+        const boundSessionId = this.dependencies.getBoundSessionId()
+        if (!sandboxId || !sessionId || !sessionSandboxId || !runtimeConnectionAttemptId
+            || generation === undefined || eventAckFloor === undefined) {
+            return new Response('Invalid supervisor routing headers.', { status: 400 })
+        }
+        let localSandboxId: string
+        try {
+            localSandboxId = await this.getLocalSandboxId()
+        }
+        catch (error) {
+            this.dependencies.logger.error({ err: error }, 'failed to read local E2B sandbox identity')
+            return new Response('Local sandbox identity is unavailable.', { status: 503 })
+        }
+        if (sandboxId !== localSandboxId)
+            return new Response('E2B sandbox identity mismatch.', { status: 409 })
+        try {
+            await this.dependencies.verifyControlAuthority({
+                assertion: authorityAssertion,
+                providerSandboxId: sandboxId,
+                sessionId,
+                sessionSandboxId,
+                connectionGeneration: generation,
+                runtimeConnectionAttemptId,
+                eventAckFloor,
+            })
+        }
+        catch {
+            return new Response('Supervisor control authority is invalid.', { status: 401 })
+        }
+        if (boundSessionId && sessionId !== boundSessionId)
+            return new Response('Supervisor session binding mismatch.', { status: 409 })
+        if (eventAckFloor > this.dependencies.getLocalEventMax())
+            return new Response('Supervisor event ACK floor is ahead of local state.', { status: 409 })
+        if (boundSessionId) {
+            try {
+                this.dependencies.acceptBoundConnectionGeneration({ generation, runtimeConnectionAttemptId })
+            }
+            catch (error) {
+                this.dependencies.logger.warn({ err: error }, 'rejecting supervisor connection generation')
+                return new Response('Supervisor connection generation is stale.', { status: 409 })
+            }
+        }
+
+        const upgraded = server.upgrade(request, {
+            data: {
+                sessionId,
+                runtimeConnectionAttemptId,
+                generation,
+                eventAckFloor,
+                runtimeAttached: false,
+                messageChain: Promise.resolve(),
+            },
+        })
+        return upgraded ? undefined : new Response('WebSocket upgrade failed.', { status: 400 })
+    }
+
+    private async getLocalSandboxId(): Promise<string> {
+        if (this.localSandboxId)
+            return this.localSandboxId
+
+        const read = this.localSandboxIdRead ?? readLocalSandboxId(this.dependencies.config.sandboxIdPath)
+        this.localSandboxIdRead = read
+        try {
+            const sandboxId = await read
+            this.localSandboxId = sandboxId
+            return sandboxId
+        }
+        finally {
+            if (this.localSandboxIdRead === read)
+                this.localSandboxIdRead = undefined
+        }
+    }
+
+    private onOpen(socket: ServerWebSocket<SocketData>): void {
+        this.sockets.add(socket)
+        const previous = this.authoritativeSocket
+        this.authoritativeSocket = socket
+        if (previous && previous !== socket) {
+            this.cancelPendingTerminalRejection(previous)
+            this.sockets.delete(previous)
+            if (previous.data.runtimeAttached) {
+                previous.data.runtimeAttached = false
+                previous.data.handler?.detach(previous)
+            }
+            previous.close(policyViolationCloseCode, 'Connection attempt was superseded.')
+            previous.terminate()
+        }
+    }
+
+    private onMessage(socket: ServerWebSocket<SocketData>, message: string | Buffer): void {
+        socket.data.messageChain = socket.data.messageChain.then(async () => {
+            const bootstrapHandlingStartedAt = performance.now()
+            if (!this.isAuthoritativeLive(socket) || socket.data.terminalRejection)
+                return
+            const decoded = decodeControlPlaneFrame(typeof message === 'string' ? message : message.toString('utf8'))
+            const handler = socket.data.handler
+            if (handler && (decoded.kind !== 'ok' || decoded.frame.kind !== 'session.bootstrap')) {
+                if (socket.data.runtimeAttached)
+                    handler.receive(socket, message)
+                return
+            }
+            if (decoded.kind !== 'ok' || decoded.frame.kind !== 'session.bootstrap') {
+                socket.close(protocolErrorCloseCode, 'Expected session bootstrap as first frame.')
+                return
+            }
+            if (decoded.frame.body.sessionId !== socket.data.sessionId
+                || decoded.frame.connectionGeneration !== socket.data.generation) {
+                socket.close(policyViolationCloseCode, 'Bootstrap does not match upgrade headers.')
+                return
+            }
+
+            let binding: Awaited<ReturnType<BootstrapBinder>>
+            try {
+                binding = await this.dependencies.bindBootstrap({
+                    envelope: decoded.frame,
+                    runtimeConnectionAttemptId: socket.data.runtimeConnectionAttemptId,
+                })
+                this.observeBootstrapStage({
+                    stage: 'bootstrap-persisted',
+                    outcome: binding.outcome === 'accepted' ? 'success' : 'failure',
+                    startedAt: bootstrapHandlingStartedAt,
+                    sessionId: socket.data.sessionId,
+                })
+            }
+            catch (error) {
+                this.observeBootstrapStage({
+                    stage: 'bootstrap-persisted',
+                    outcome: 'failure',
+                    startedAt: bootstrapHandlingStartedAt,
+                    sessionId: socket.data.sessionId,
+                })
+                throw error
+            }
+            if (!this.isAuthoritativeLive(socket)) {
+                this.observeBootstrapStage({
+                    stage: 'bootstrap-readiness-sent',
+                    outcome: 'failure',
+                    startedAt: bootstrapHandlingStartedAt,
+                    sessionId: socket.data.sessionId,
+                })
+                return
+            }
+            const readiness = binding.outcome === 'accepted' ? binding.runtimeState : binding.ack
+            let sendResult: number
+            try {
+                sendResult = socket.send(encodeWireFrame(readiness))
+                this.observeBootstrapStage({
+                    stage: 'bootstrap-readiness-sent',
+                    outcome: binding.outcome === 'accepted' && sendResult >= 0 ? 'success' : 'failure',
+                    startedAt: bootstrapHandlingStartedAt,
+                    sessionId: socket.data.sessionId,
+                })
+            }
+            catch (error) {
+                this.observeBootstrapStage({
+                    stage: 'bootstrap-readiness-sent',
+                    outcome: 'failure',
+                    startedAt: bootstrapHandlingStartedAt,
+                    sessionId: socket.data.sessionId,
+                })
+                throw error
+            }
+            if (sendResult < 0) {
+                socket.close(internalErrorCloseCode, binding.outcome === 'accepted'
+                    ? 'Supervisor bootstrap readiness delivery failed.'
+                    : 'Supervisor bootstrap ACK delivery failed.')
+                return
+            }
+            if (binding.outcome === 'rejected') {
+                this.awaitTerminalRejectionReceipt({ socket, terminate: binding.terminate })
+                return
+            }
+            const activated = await binding.activate()
+            this.attachIfLive({ socket, handler: activated })
+        }).catch((error: unknown) => {
+            this.dependencies.logger.error({ err: error }, 'resident supervisor connection failed')
+            socket.close(internalErrorCloseCode, 'Supervisor bootstrap failed.')
+        })
+    }
+
+    private observeBootstrapStage(input: {
+        stage: SupervisorBootstrapStartupStageFact['stage']
+        outcome: SupervisorBootstrapStartupStageFact['outcome']
+        startedAt: number
+        sessionId: string
+    }): void {
+        try {
+            this.dependencies.onStartupStage({
+                event: 'sandbox.startup-stage',
+                stage: input.stage,
+                outcome: input.outcome,
+                duration: Math.max(0, Math.round(performance.now() - input.startedAt)),
+                sessionId: input.sessionId,
+            })
+        }
+        catch {
+            // Startup telemetry is best effort and cannot alter bootstrap behavior.
+        }
+    }
+
+    private onClose(socket: ServerWebSocket<SocketData>, code: number, reason: string): void {
+        const terminalRejection = socket.data.terminalRejection
+        const receiptConfirmed = terminalRejection !== undefined
+            && this.authoritativeSocket === socket
+            && code === supervisorBootstrapRejectionReceiptCloseCode
+            && reason === supervisorBootstrapRejectionReceiptCloseReason
+        if (terminalRejection) {
+            clearTimeout(terminalRejection.timeout)
+            socket.data.terminalRejection = undefined
+        }
+        this.sockets.delete(socket)
+        if (this.authoritativeSocket === socket)
+            this.authoritativeSocket = undefined
+        if (socket.data.runtimeAttached)
+            socket.data.handler?.detach(socket)
+        if (receiptConfirmed)
+            terminalRejection?.terminate()
+    }
+
+    private awaitTerminalRejectionReceipt(input: {
+        socket: ServerWebSocket<SocketData>
+        terminate: () => void
+    }): void {
+        const timeout = setTimeout(() => {
+            if (input.socket.data.terminalRejection?.terminate !== input.terminate)
+                return
+            input.socket.data.terminalRejection = undefined
+            input.socket.close(internalErrorCloseCode, 'Supervisor rejection receipt was not observed.')
+            input.terminate()
+        }, terminalRejectionReceiptBudgetMs)
+        timeout.unref?.()
+        input.socket.data.terminalRejection = { terminate: input.terminate, timeout }
+    }
+
+    private cancelPendingTerminalRejection(socket: ServerWebSocket<SocketData>): void {
+        const pending = socket.data.terminalRejection
+        if (!pending)
+            return
+        clearTimeout(pending.timeout)
+        socket.data.terminalRejection = undefined
+    }
+
+    private onDrain(socket: ServerWebSocket<SocketData>): void {
+        if (socket.data.runtimeAttached && this.isAuthoritativeLive(socket))
+            socket.data.handler?.drain(socket)
+    }
+
+    private attachIfLive(input: {
+        socket: ServerWebSocket<SocketData>
+        handler: RuntimeConnectionHandler
+    }): void {
+        if (!this.isAuthoritativeLive(input.socket))
+            return
+        input.socket.data.handler = input.handler
+        input.handler.attach({
+            socket: input.socket,
+            generation: input.socket.data.generation,
+            eventAckFloor: input.socket.data.eventAckFloor,
+        })
+        input.socket.data.runtimeAttached = true
+    }
+
+    private isAuthoritativeLive(socket: ServerWebSocket<SocketData>): boolean {
+        return this.sockets.has(socket) && this.authoritativeSocket === socket
+    }
+}
+
+function parseBoundedInteger(value: string | null, minimum: number): number | undefined {
+    if (value === null || !/^\d+$/u.test(value))
+        return undefined
+    const parsed = Number(value)
+    return Number.isSafeInteger(parsed) && parsed >= minimum ? parsed : undefined
+}
+
+async function readLocalSandboxId(path: string): Promise<string> {
+    const sandboxId = (await Bun.file(path).text()).trim()
+    if (!sandboxId)
+        throw new Error('E2B sandbox identity file is empty.')
+    return sandboxId
+}

package/src/supervisor-protocol/bootstrap.ts

@@ -67,7 +67,7 @@ export const sessionBootstrapBodySchema = z.object({
 }).strict().superRefine((body, context) => {
     const workspacePrefix = `${body.agent.cwd}/`
     for (const [index, repository] of body.repositories.entries()) {
-        if (!repository.root.startsWith(workspacePrefix)) {
+        if (repository.root !== body.agent.cwd && !repository.root.startsWith(workspacePrefix)) {
             context.addIssue({
                 code: 'custom',
                 path: ['repositories', index, 'root'],

package/src/template-onboarding.ts

@@ -0,0 +1,47 @@
+import z from 'zod'
+import { sessionProfileNameSchema } from './supervisor-protocol/profile'
+
+const sha256Schema = z.string().regex(/^[0-9a-f]{64}$/u)
+const componentNameSchema = z.string().max(64).regex(/^[a-z][a-z0-9.-]*$/u)
+const componentVersionSchema = z.string().min(1).max(256)
+
+/**
+ * Immutable provenance supplied when a service onboards one of its E2B
+ * templates. The owning service persists this record; agent-core deliberately
+ * has no global template registry or preferred template ID.
+ */
+export const sandboxTemplateOnboardingSchema = z.object({
+    owner: z.object({
+        service: sessionProfileNameSchema,
+        profileVersion: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+    }).strict(),
+    provider: z.literal('e2b'),
+    templateId: z.string().min(1).max(512),
+    agentCore: z.object({
+        version: z.string().min(1).max(256),
+        sha: z.string().regex(/^[0-9a-f]{40}$/u),
+    }).strict(),
+    supervisorEntrySha256: sha256Schema,
+    runtimeHash: sha256Schema,
+    components: z.record(componentNameSchema, componentVersionSchema).refine(
+        components => Object.keys(components).length <= 64,
+        { message: 'A template may declare at most 64 versioned components.' },
+    ),
+    onboardedAt: z.iso.datetime(),
+}).strict()
+
+export type SandboxTemplateOnboarding = z.infer<typeof sandboxTemplateOnboardingSchema>
+
+export interface SandboxTemplateOnboardingStore {
+    upsert: (registration: SandboxTemplateOnboarding) => Promise<void>
+}
+
+/** Validates locally, then delegates persistence to the service-owned store. */
+export async function onboardSandboxTemplate(input: {
+    registration: unknown
+    store: SandboxTemplateOnboardingStore
+}): Promise<SandboxTemplateOnboarding> {
+    const registration = sandboxTemplateOnboardingSchema.parse(input.registration)
+    await input.store.upsert(registration)
+    return registration
+}

package/src/testing/es256-test-keys.ts

@@ -0,0 +1,73 @@
+import type { SandboxControlAuthorityPublicJwks } from '../supervisor-protocol/control-authority'
+import { sandboxControlAuthorityPublicJwksSchema } from '../supervisor-protocol/control-authority'
+import { createControlAuthoritySigner } from '../worker-runtime-client/control-authority-signer'
+
+export interface TestControlAuthority {
+    issuer: string
+    keyId: string
+    signingJwk: Record<string, unknown>
+    publicJwks: SandboxControlAuthorityPublicJwks
+    sign: Awaited<ReturnType<typeof createControlAuthoritySigner>>['sign']
+}
+
+export async function createTestControlAuthority(input: {
+    issuer?: string
+    keyId?: string
+} = {}): Promise<TestControlAuthority> {
+    const issuer = input.issuer ?? 'agent-core-loopback'
+    const keyId = input.keyId ?? 'loopback-key'
+    const pair = await crypto.subtle.generateKey(
+        { name: 'ECDSA', namedCurve: 'P-256' },
+        true,
+        ['sign', 'verify'],
+    )
+    const [privateMaterial, publicMaterial] = await Promise.all([
+        crypto.subtle.exportKey('jwk', pair.privateKey),
+        crypto.subtle.exportKey('jwk', pair.publicKey),
+    ])
+    const { x, y, d } = requiredEcPrivateMaterial(privateMaterial)
+    const signingJwk: Record<string, unknown> = {
+        kty: 'EC',
+        crv: 'P-256',
+        x,
+        y,
+        d,
+        kid: keyId,
+        alg: 'ES256',
+        use: 'sig',
+        key_ops: ['sign'],
+    }
+    const publicJwks = sandboxControlAuthorityPublicJwksSchema.parse({
+        keys: [{
+            kty: 'EC',
+            crv: 'P-256',
+            x: requiredCoordinate(publicMaterial.x, 'x'),
+            y: requiredCoordinate(publicMaterial.y, 'y'),
+            kid: keyId,
+            alg: 'ES256' as const,
+            use: 'sig' as const,
+            key_ops: ['verify'],
+        }],
+    })
+    const signer = await createControlAuthoritySigner({
+        issuer,
+        activeKeyId: keyId,
+        signingJwk,
+        publicJwks,
+    })
+    return { issuer, keyId, signingJwk, publicJwks: signer.publicJwks, sign: signer.sign }
+}
+
+function requiredEcPrivateMaterial(jwk: { x?: string, y?: string, d?: string }): { x: string, y: string, d: string } {
+    return {
+        x: requiredCoordinate(jwk.x, 'x'),
+        y: requiredCoordinate(jwk.y, 'y'),
+        d: requiredCoordinate(jwk.d, 'd'),
+    }
+}
+
+function requiredCoordinate(value: string | undefined, name: string): string {
+    if (!value)
+        throw new Error(`Generated EC test key is missing ${name}.`)
+    return value
+}