@meistrari/agent-core 0.0.0 → 0.1.0

package/src/provenance.gen.ts

@@ -1,6 +1,6 @@
 // Generated by scripts/write-provenance.ts. Do not edit by hand.
 export const generatedProvenance = {
-    version: "0.0.0",
-    sha: "3a023ce55b472e60cc194b759feac98f7ae61dba",
-    buildTime: "2026-09-04T18:05:02.217Z",
+    version: "0.1.0",
+    sha: "9cd95365c6d39d1f44098fdd8006087c3adabfb4",
+    buildTime: "2026-09-04T20:01:49.852Z",
 } as const

package/src/supervisor/agent-provider-factory.ts

@@ -0,0 +1,189 @@
+import type { AgentProvider, AgentRun } from '../agents'
+import type { AgentInputAttachmentPreparation } from '../agents/materialized-input-attachment'
+import type { AgentEvent, AgentProviderId } from '../protocol'
+import type { EphemeralCredentials, SessionBootstrapBody, SessionBootstrapGitToken } from '../supervisor-protocol/bootstrap'
+import type { WireSendPromptCommand } from '../supervisor-protocol/command-body'
+import type { WireEventBody } from '../supervisor-protocol/event-body'
+import type { SupervisorAgentRunSnapshot } from '../supervisor-protocol/supervisor-agent-run-snapshot'
+import type { SupervisorAgentRuntime, SupervisorProviderFactory } from './provider-factory'
+import type { SupervisorRpcClient } from './rpc-client'
+import { wrapAgentEvent } from '../supervisor-protocol/agent-event-wrapper'
+import { createSupervisorProviderFactory } from './provider-factory'
+
+export interface AgentProviderBindingStore {
+    load: (input: { sessionId: string, provider: AgentProviderId }) => Promise<string | undefined>
+    save: (input: { sessionId: string, provider: AgentProviderId, providerSessionId: string }) => Promise<void>
+}
+
+export interface AgentSupervisorProviderFactoryOptions {
+    createProvider: (input: {
+        bootstrap: SessionBootstrapBody
+        credentials?: EphemeralCredentials
+        gitToken?: SessionBootstrapGitToken
+        rpc: SupervisorRpcClient
+    }) => AgentProvider<'claude'> | AgentProvider<'codex'>
+    bindingStore: AgentProviderBindingStore
+    prepareInputAttachments?: (input: {
+        commandId: string
+        command: WireSendPromptCommand
+        signal: AbortSignal
+    }) => Promise<AgentInputAttachmentPreparation | undefined>
+    onSecretsRefreshed?: (input: {
+        credentials?: EphemeralCredentials
+        gitToken?: SessionBootstrapGitToken
+    }) => void | Promise<void>
+}
+
+export function createAgentSupervisorProviderFactory(
+    options: AgentSupervisorProviderFactoryOptions,
+): SupervisorProviderFactory {
+    return createSupervisorProviderFactory(async (input) => {
+        const provider = options.createProvider(input)
+        if (provider.id !== input.bootstrap.agent.provider)
+            throw new Error(`Provider factory returned ${provider.id} for ${input.bootstrap.agent.provider}.`)
+
+        const previousProviderSessionId = await options.bindingStore.load({
+            sessionId: input.bootstrap.sessionId,
+            provider: provider.id,
+        })
+        const sessionInput = {
+            sessionId: input.bootstrap.sessionId,
+            cwd: input.bootstrap.agent.cwd,
+            workspaceRepositoryRoots: input.bootstrap.repositories.map(repository => repository.root),
+            model: input.bootstrap.agent.model,
+            reasoningEffort: input.bootstrap.agent.reasoningEffort,
+        }
+        const run = provider.id === 'claude'
+            ? previousProviderSessionId
+                ? await provider.resumeSession({ ...sessionInput, provider: 'claude', providerSessionId: previousProviderSessionId }, { signal: input.signal })
+                : await provider.openSession({ ...sessionInput, provider: 'claude' }, { signal: input.signal })
+            : previousProviderSessionId
+                ? await provider.resumeSession({ ...sessionInput, provider: 'codex', providerSessionId: previousProviderSessionId }, { signal: input.signal })
+                : await provider.openSession({ ...sessionInput, provider: 'codex' }, { signal: input.signal })
+
+        await options.bindingStore.save({
+            sessionId: input.bootstrap.sessionId,
+            provider: provider.id,
+            providerSessionId: run.metadata.providerSessionId,
+        })
+
+        return new AgentSupervisorRuntime({
+            run,
+            prepareInputAttachments: options.prepareInputAttachments,
+            onSecretsRefreshed: options.onSecretsRefreshed,
+        })
+    })
+}
+
+class AgentSupervisorRuntime implements SupervisorAgentRuntime {
+    private state: SupervisorAgentRunSnapshot = { status: 'attached', agentState: null }
+    private emit: ((body: WireEventBody) => void) | undefined
+    private readonly pendingEvents: WireEventBody[] = []
+    private readonly eventPump: Promise<void>
+
+    constructor(private readonly input: {
+        run: AgentRun
+        prepareInputAttachments?: AgentSupervisorProviderFactoryOptions['prepareInputAttachments']
+        onSecretsRefreshed?: AgentSupervisorProviderFactoryOptions['onSecretsRefreshed']
+    }) {
+        this.eventPump = this.consumeEvents()
+    }
+
+    snapshot(): SupervisorAgentRunSnapshot {
+        return this.state
+    }
+
+    async handle(input: Parameters<SupervisorAgentRuntime['handle']>[0]): Promise<void> {
+        this.attachEmitter(input.emit)
+        const metadata = this.input.run.metadata
+        if (input.body.type === 'agent.send-prompt') {
+            const inputAttachmentPreparation = await this.input.prepareInputAttachments?.({
+                commandId: input.commandId,
+                command: input.body,
+                signal: input.signal,
+            })
+            await this.input.run.sendPrompt({
+                type: 'agent.send-prompt',
+                provider: metadata.provider,
+                sessionId: metadata.sessionId,
+                providerSessionId: metadata.providerSessionId,
+                commandId: input.commandId,
+                mode: input.body.mode,
+                origin: 'user',
+                prompt: input.body.prompt,
+                author: input.body.user
+                    ? {
+                            name: input.body.user.name,
+                            email: input.body.user.email,
+                            gitEmail: input.body.user.gitEmail,
+                        }
+                    : undefined,
+            }, {
+                signal: input.signal,
+                inputAttachmentPreparation,
+                senderContext: input.body.user?.senderContext,
+            })
+            return
+        }
+        if (input.body.type === 'agent.interrupt') {
+            await this.input.run.interrupt({
+                type: 'agent.interrupt',
+                provider: metadata.provider,
+                sessionId: metadata.sessionId,
+                providerSessionId: metadata.providerSessionId,
+                commandId: input.commandId,
+            }, { signal: input.signal })
+            return
+        }
+        await this.input.run.respondUserInput({
+            type: 'agent.respond-user-input',
+            provider: metadata.provider,
+            sessionId: metadata.sessionId,
+            providerSessionId: metadata.providerSessionId,
+            commandId: input.commandId,
+            requestId: input.body.requestId,
+            answers: input.body.answers,
+        }, { signal: input.signal })
+    }
+
+    async refreshSecrets(input: {
+        credentials?: EphemeralCredentials
+        gitToken?: SessionBootstrapGitToken
+    }): Promise<void> {
+        await this.input.onSecretsRefreshed?.(input)
+    }
+
+    async close(input: { signal: AbortSignal }): Promise<void> {
+        const metadata = this.input.run.metadata
+        await this.input.run.stop({
+            type: 'agent.stop',
+            provider: metadata.provider,
+            sessionId: metadata.sessionId,
+            providerSessionId: metadata.providerSessionId,
+            reason: 'supervisor_closed',
+        }, { signal: input.signal }).catch(() => undefined)
+        await this.eventPump.catch(() => undefined)
+    }
+
+    private attachEmitter(emit: (body: WireEventBody) => void): void {
+        this.emit = emit
+        for (const event of this.pendingEvents.splice(0))
+            emit(event)
+    }
+
+    private async consumeEvents(): Promise<void> {
+        for await (const event of this.input.run.events) {
+            if (event.type === 'session.state.changed')
+                this.state = { status: 'attached', agentState: event.payload.state }
+            this.emitEvent(event)
+        }
+    }
+
+    private emitEvent(event: AgentEvent): void {
+        const wrapped = wrapAgentEvent(event)
+        if (this.emit)
+            this.emit(wrapped)
+        else
+            this.pendingEvents.push(wrapped)
+    }
+}

package/src/supervisor/bootstrap-binder.ts

@@ -0,0 +1,125 @@
+import type { Logger } from '../logger'
+import type { SessionBootstrapBody } from '../supervisor-protocol/bootstrap'
+import type { SessionBootstrapEnvelope } from '../supervisor-protocol/envelopes/control-plane-to-supervisor'
+import type { RejectedCommandAckEnvelope, RuntimeStateEnvelope } from '../supervisor-protocol/envelopes/supervisor-to-control-plane'
+import type { RuntimeConnectionHandler } from './runtime-handler'
+import { supervisorSessionDirectory, TERMINAL_ERROR_CODE } from './config'
+import { SupervisorConfigurationError } from './errors'
+import { sha256CanonicalJson } from './persistence/json'
+import { SupervisorStore } from './persistence/supervisor-store'
+
+export interface BootstrapAdmission {
+    assertAllowed: (body: SessionBootstrapBody) => Promise<void>
+}
+
+export type SupervisorProcessBinding
+    = | { status: 'unbound' }
+        | { status: 'bound', store: SupervisorStore, sessionId: string }
+
+type BootstrapBinding
+    = | { outcome: 'accepted', runtimeState: RuntimeStateEnvelope, activate: () => Promise<RuntimeConnectionHandler> }
+        | { outcome: 'rejected', ack: RejectedCommandAckEnvelope, terminate: () => void }
+
+export type BootstrapBinder = (input: {
+    envelope: SessionBootstrapEnvelope
+    runtimeConnectionAttemptId: string
+}) => Promise<BootstrapBinding>
+
+export function createBootstrapBinder(input: {
+    stateRoot: string
+    getBinding: () => SupervisorProcessBinding
+    setBinding: (binding: SupervisorProcessBinding) => void
+    admission?: BootstrapAdmission
+    activate: (input: { store: SupervisorStore, envelope: SessionBootstrapEnvelope }) => Promise<RuntimeConnectionHandler>
+    shutdown: (code: number) => void
+    logger: Logger
+}): BootstrapBinder {
+    return async (request) => {
+        try {
+            return await bind(request)
+        }
+        catch (error) {
+            if (!(error instanceof SupervisorConfigurationError))
+                throw error
+            input.logger.error({ code: error.code, err: error }, 'resident supervisor rejected immutable bootstrap configuration')
+            return {
+                outcome: 'rejected',
+                ack: {
+                    kind: 'command.ack',
+                    commandId: request.envelope.body.initialCommand.commandId,
+                    commandSeq: request.envelope.body.initialCommand.commandSeq,
+                    status: 'rejected',
+                    errorCode: error.code,
+                    detail: error.publicMessage.slice(0, 240),
+                },
+                terminate: () => input.shutdown(TERMINAL_ERROR_CODE),
+            }
+        }
+    }
+
+    async function bind(request: {
+        envelope: SessionBootstrapEnvelope
+        runtimeConnectionAttemptId: string
+    }): Promise<BootstrapBinding> {
+        let binding = input.getBinding()
+        if (binding.status === 'unbound') {
+            try {
+                await input.admission?.assertAllowed(request.envelope.body)
+            }
+            catch (cause) {
+                throw new SupervisorConfigurationError({
+                    code: 'agent-core.bootstrap-admission-rejected',
+                    message: 'Supervisor bootstrap admission rejected the immutable configuration.',
+                    publicMessage: 'The sandbox configuration is not allowed.',
+                    cause,
+                })
+            }
+            const sessionDirectory = supervisorSessionDirectory({
+                stateRoot: input.stateRoot,
+                sessionId: request.envelope.body.sessionId,
+            })
+            const store = SupervisorStore.open({ sqlitePath: `${sessionDirectory}/state.sqlite` })
+            try {
+                store.bind({
+                    body: request.envelope.body,
+                    connectionGeneration: request.envelope.connectionGeneration,
+                    runtimeConnectionAttemptId: request.runtimeConnectionAttemptId,
+                })
+            }
+            catch (cause) {
+                store.close()
+                throw cause
+            }
+            binding = { status: 'bound', store, sessionId: request.envelope.body.sessionId }
+            input.setBinding(binding)
+        }
+        else {
+            if (binding.sessionId !== request.envelope.body.sessionId) {
+                throw new SupervisorConfigurationError({
+                    code: 'agent-core.bootstrap-session-conflict',
+                    message: 'Supervisor is already bound to another session.',
+                    publicMessage: 'The sandbox is already bound to another session.',
+                })
+            }
+            const persisted = binding.store.binding()
+            if (!persisted || persisted.bodyHash !== sha256CanonicalJson(request.envelope.body)) {
+                throw new SupervisorConfigurationError({
+                    code: 'agent-core.bootstrap-configuration-conflict',
+                    message: 'Supervisor reconnect bootstrap differs from its immutable binding.',
+                    publicMessage: 'The sandbox configuration cannot change after bootstrap.',
+                })
+            }
+        }
+        const acceptedBinding = binding
+        return {
+            outcome: 'accepted',
+            runtimeState: {
+                kind: 'runtime.state',
+                lastReceivedCommandSeq: acceptedBinding.store.lastReceivedCommandSeq(),
+                nextEventSeq: acceptedBinding.store.localEventMax() + 1,
+                agentRun: acceptedBinding.store.agentRunSnapshot(),
+            },
+            activate: async () => await input.activate({ store: acceptedBinding.store, envelope: request.envelope }),
+        }
+    }
+}

package/src/supervisor/config.ts

@@ -0,0 +1,49 @@
+import { createHash } from 'node:crypto'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+export const CLEAN_EXIT_CODE = 0
+export const RECOVERABLE_ERROR_CODE = 75
+export const TERMINAL_ERROR_CODE = 78
+export const residentSupervisorPort = 8080
+export const residentSupervisorUnixSocketPath = '/run/agent-core/control.sock'
+export const residentSupervisorControlPath = '/control/ws'
+export const residentSupervisorHealthPath = '/health'
+export const sandboxControlAuthorityJwksPath = '/opt/agent-core/control-authority-jwks.json'
+export const e2bSandboxIdPath = '/run/e2b/.E2B_SANDBOX_ID'
+
+export interface ResidentSupervisorConfig {
+    host?: string
+    port?: number
+    unixSocketPath?: string
+    controlPath: string
+    healthPath: string
+    stateRoot: string
+    sandboxIdPath: string
+    authorityJwksPath: string
+}
+
+export function residentSupervisorConfig(input: {
+    homeDir?: string
+    authorityJwksPath?: string
+    sandboxIdPath?: string
+    stateRoot?: string
+    listen?: 'protected-unix' | 'loopback-tcp'
+    port?: number
+} = {}): ResidentSupervisorConfig {
+    const listen = input.listen ?? 'protected-unix'
+    return {
+        ...(listen === 'protected-unix'
+            ? { unixSocketPath: residentSupervisorUnixSocketPath }
+            : { host: '127.0.0.1', port: input.port ?? residentSupervisorPort }),
+        controlPath: residentSupervisorControlPath,
+        healthPath: residentSupervisorHealthPath,
+        stateRoot: input.stateRoot ?? join(input.homeDir ?? homedir(), '.agent-core', 'supervisor'),
+        sandboxIdPath: input.sandboxIdPath ?? e2bSandboxIdPath,
+        authorityJwksPath: input.authorityJwksPath ?? sandboxControlAuthorityJwksPath,
+    }
+}
+
+export function supervisorSessionDirectory(input: { stateRoot: string, sessionId: string }): string {
+    return join(input.stateRoot, createHash('sha256').update(input.sessionId, 'utf8').digest('hex'))
+}

package/src/supervisor/control-authority-verifier.ts

@@ -0,0 +1,135 @@
+import type { SandboxControlAuthorityClaims } from '../supervisor-protocol/control-authority'
+import { Buffer } from 'node:buffer'
+import { readFile } from 'node:fs/promises'
+import { z } from 'zod'
+import { InfrastructureError, ValidationError } from '../errors'
+import {
+    sandboxControlAuthorityAssertionLifetimeSeconds,
+    sandboxControlAuthorityClaimsSchema,
+    sandboxControlAuthorityClockSkewSeconds,
+    sandboxControlAuthorityProtectedHeaderSchema,
+    sandboxControlAuthorityPublicJwksSchema,
+} from '../supervisor-protocol/control-authority'
+
+const verificationConfigSchema = z.object({
+    issuer: z.string().min(1),
+    jwks: sandboxControlAuthorityPublicJwksSchema,
+}).strict()
+
+export type VerifySupervisorControlAuthority = (input: {
+    assertion: string | null
+    providerSandboxId: string
+    sessionId: string
+    sessionSandboxId: string
+    connectionGeneration: number
+    runtimeConnectionAttemptId: string
+    eventAckFloor: number
+}) => Promise<SandboxControlAuthorityClaims>
+
+export async function createSupervisorControlAuthorityVerifier(input: {
+    jwksPath?: string
+    configuration?: { issuer: string, jwks: unknown }
+}): Promise<VerifySupervisorControlAuthority> {
+    try {
+        const raw = input.configuration ?? JSON.parse(await readFile(requiredPath(input.jwksPath), 'utf8'))
+        const config = verificationConfigSchema.parse(raw)
+        const verificationKeys = new Map<string, CryptoKey>()
+        for (const jwk of config.jwks.keys) {
+            const key = await crypto.subtle.importKey('jwk', jwk, { name: 'ECDSA', namedCurve: 'P-256' }, false, ['verify'])
+            verificationKeys.set(jwk.kid, key)
+        }
+        return async (request) => {
+            if (!request.assertion)
+                throw new ControlAuthorityAdmissionError({ reason: 'missing' })
+            let claims: SandboxControlAuthorityClaims
+            try {
+                const segments = request.assertion.split('.')
+                if (segments.length !== 3)
+                    throw new Error('Authority assertion is not a compact JWS.')
+                const [encodedHeader, encodedPayload, encodedSignature] = segments
+                if (!encodedHeader || !encodedPayload || !encodedSignature)
+                    throw new Error('Authority assertion contains an empty segment.')
+                const protectedHeader = sandboxControlAuthorityProtectedHeaderSchema.parse(JSON.parse(decodeBase64Url(encodedHeader)))
+                const verificationKey = verificationKeys.get(protectedHeader.kid)
+                if (!verificationKey)
+                    throw new Error('Authority assertion key ID is unknown.')
+                const verified = await crypto.subtle.verify(
+                    { name: 'ECDSA', hash: 'SHA-256' },
+                    verificationKey,
+                    Buffer.from(encodedSignature, 'base64url'),
+                    new TextEncoder().encode(`${encodedHeader}.${encodedPayload}`),
+                )
+                if (!verified)
+                    throw new Error('Authority assertion signature is invalid.')
+                claims = sandboxControlAuthorityClaimsSchema.parse(JSON.parse(decodeBase64Url(encodedPayload)))
+                verifyTemporalClaims({ claims, issuer: config.issuer })
+            }
+            catch (cause) {
+                throw new ControlAuthorityAdmissionError({ reason: 'unverified', cause })
+            }
+            if (claims.providerSandboxId !== request.providerSandboxId
+                || claims.sessionId !== request.sessionId
+                || claims.sessionSandboxId !== request.sessionSandboxId
+                || claims.connectionGeneration !== request.connectionGeneration
+                || claims.runtimeConnectionAttemptId !== request.runtimeConnectionAttemptId
+                || claims.eventAckFloor !== request.eventAckFloor) {
+                throw new ControlAuthorityAdmissionError({ reason: 'context-mismatch' })
+            }
+            return claims
+        }
+    }
+    catch (cause) {
+        if (cause instanceof ControlAuthorityConfigurationError)
+            throw cause
+        throw new ControlAuthorityConfigurationError({ cause })
+    }
+}
+
+export class ControlAuthorityConfigurationError extends InfrastructureError {
+    constructor(input: { cause: unknown }) {
+        super({
+            code: 'agent-core.control-authority-configuration-invalid',
+            message: 'Supervisor control-authority verification configuration is invalid.',
+            publicMessage: 'Supervisor control authority is unavailable.',
+            retryable: false,
+            cause: input.cause,
+        })
+    }
+}
+
+class ControlAuthorityAdmissionError extends ValidationError {
+    constructor(input: { reason: 'missing' | 'unverified' | 'context-mismatch', cause?: unknown }) {
+        super({
+            code: 'agent-core.control-authority-admission-denied',
+            message: 'Supervisor control-authority admission was denied.',
+            publicMessage: 'Supervisor control authority is invalid.',
+            details: { reason: input.reason },
+            cause: input.cause,
+        })
+    }
+}
+
+function requiredPath(path: string | undefined): string {
+    if (!path)
+        throw new Error('Control-authority JWKS path is required.')
+    return path
+}
+
+function verifyTemporalClaims(input: { claims: SandboxControlAuthorityClaims, issuer: string }): void {
+    const now = Math.floor(Date.now() / 1_000)
+    if (input.claims.iss !== input.issuer)
+        throw new Error('Authority assertion issuer is invalid.')
+    if (input.claims.iat > now + sandboxControlAuthorityClockSkewSeconds
+        || input.claims.nbf > now + sandboxControlAuthorityClockSkewSeconds
+        || input.claims.exp < now - sandboxControlAuthorityClockSkewSeconds) {
+        throw new Error('Authority assertion is outside its validity interval.')
+    }
+    if (input.claims.exp - input.claims.iat !== sandboxControlAuthorityAssertionLifetimeSeconds)
+        throw new Error('Authority assertion lifetime is invalid.')
+}
+
+function decodeBase64Url(value: string): string {
+    if (!/^[\w-]+$/u.test(value))
+        throw new Error('Authority assertion compact JWS segment is malformed.')
+    return Buffer.from(value, 'base64url').toString('utf8')
+}

package/src/supervisor/create-supervisor-runtime.ts

@@ -0,0 +1,25 @@
+import type { Logger } from '../logger'
+import type { BootstrapAdmission } from './bootstrap-binder'
+import type { ResidentSupervisorConfig } from './config'
+import type { SupervisorProviderFactory } from './provider-factory'
+import { createResidentSupervisor } from './resident'
+
+export interface SupervisorExtensions {
+    profile: { name: string, version: number, requiredRpcMethods: readonly string[] }
+    providerFactory: SupervisorProviderFactory
+    admission?: BootstrapAdmission
+}
+
+export async function createSupervisorRuntime(input: {
+    config: ResidentSupervisorConfig
+    extensions: SupervisorExtensions
+    logger: Logger
+}) {
+    return await createResidentSupervisor({
+        config: input.config,
+        logger: input.logger,
+        providerFactory: input.extensions.providerFactory,
+        profile: input.extensions.profile,
+        admission: input.extensions.admission,
+    })
+}

package/src/supervisor/errors.ts

@@ -0,0 +1,24 @@
+import { InfrastructureError, ValidationError } from '../errors'
+
+export class SupervisorConfigurationError extends ValidationError {
+    constructor(input: { code?: string, message: string, publicMessage?: string, cause?: unknown }) {
+        super({
+            code: input.code ?? 'agent-core.supervisor-invalid-config',
+            message: input.message,
+            publicMessage: input.publicMessage ?? 'Supervisor configuration is invalid.',
+            cause: input.cause,
+        })
+    }
+}
+
+export class SupervisorPersistenceError extends InfrastructureError {
+    constructor(input: { code?: string, message: string, cause?: unknown }) {
+        super({
+            code: input.code ?? 'agent-core.supervisor-persistence-failed',
+            message: input.message,
+            publicMessage: 'Supervisor local persistence failed.',
+            retryable: false,
+            cause: input.cause,
+        })
+    }
+}

package/src/supervisor/index.ts

@@ -0,0 +1,34 @@
+export { createAgentSupervisorProviderFactory } from './agent-provider-factory'
+export type { AgentProviderBindingStore, AgentSupervisorProviderFactoryOptions } from './agent-provider-factory'
+export {
+    CLEAN_EXIT_CODE,
+    RECOVERABLE_ERROR_CODE,
+    residentSupervisorConfig,
+    TERMINAL_ERROR_CODE,
+} from './config'
+export type { ResidentSupervisorConfig } from './config'
+export { createSupervisorControlAuthorityVerifier } from './control-authority-verifier'
+export type { VerifySupervisorControlAuthority } from './control-authority-verifier'
+export { createSupervisorRuntime } from './create-supervisor-runtime'
+export type { SupervisorExtensions } from './create-supervisor-runtime'
+export type {
+    InitializedWorkspaceRepository,
+    InstructionComposer,
+    LargePayloadStore,
+    MaterializedAgentInputAttachment,
+    ProviderCredentialsSource,
+    RepositorySyncAction,
+    SupervisorAgentTool,
+    SupervisorBroker,
+    SupervisorExtensionContext,
+    ToolRegistryFactory,
+    TurnHooks,
+    WorkspacePreparer,
+    WorkspaceSync,
+    WorkspaceSyncContext,
+} from './ports'
+export { createSupervisorProviderFactory } from './provider-factory'
+export type { SupervisorAgentRuntime, SupervisorProviderFactory } from './provider-factory'
+export { createResidentSupervisor } from './resident'
+export type { ResidentSupervisor } from './resident'
+export { SupervisorRpcClient, SupervisorRpcError } from './rpc-client'

package/src/supervisor/persistence/json.ts

@@ -0,0 +1,21 @@
+import { createHash } from 'node:crypto'
+import { z } from 'zod'
+
+export function canonicalJson(value: unknown): string {
+    return JSON.stringify(sortJsonValue(value)) ?? 'null'
+}
+
+export function sha256CanonicalJson(value: unknown): string {
+    return createHash('sha256').update(canonicalJson(value)).digest('hex')
+}
+
+function sortJsonValue(value: unknown): unknown {
+    if (Array.isArray(value))
+        return value.map(sortJsonValue)
+    const objectValue = z.record(z.string(), z.unknown()).safeParse(value)
+    if (!objectValue.success)
+        return value
+    return Object.fromEntries(
+        Object.keys(objectValue.data).sort().map(key => [key, sortJsonValue(objectValue.data[key])]),
+    )
+}

package/src/supervisor/persistence/state-discovery.ts

@@ -0,0 +1,56 @@
+import { readdir, stat } from 'node:fs/promises'
+import { join } from 'node:path'
+import { SupervisorPersistenceError } from '../errors'
+import { SupervisorStore } from './supervisor-store'
+
+export async function discoverPersistedSupervisorState(input: {
+    stateRoot: string
+}): Promise<{ store: SupervisorStore, sessionId: string } | undefined> {
+    let entries
+    try {
+        entries = await readdir(input.stateRoot, { withFileTypes: true })
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return undefined
+        throw error
+    }
+    const stores: SupervisorStore[] = []
+    let selected: { store: SupervisorStore, sessionId: string } | undefined
+    try {
+        for (const entry of entries) {
+            if (!entry.isDirectory() || entry.isSymbolicLink())
+                continue
+            const sqlitePath = join(input.stateRoot, entry.name, 'state.sqlite')
+            try {
+                const databaseStat = await stat(sqlitePath)
+                if (!databaseStat.isFile())
+                    continue
+            }
+            catch (error) {
+                if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+                    continue
+                throw error
+            }
+            const store = SupervisorStore.open({ sqlitePath })
+            stores.push(store)
+            const binding = store.binding()
+            if (!binding)
+                continue
+            if (selected) {
+                throw new SupervisorPersistenceError({
+                    code: 'agent-core.supervisor-multiple-bindings',
+                    message: 'Resident supervisor found more than one session binding.',
+                })
+            }
+            selected = { store, sessionId: binding.body.sessionId }
+        }
+        return selected
+    }
+    finally {
+        for (const store of stores) {
+            if (store !== selected?.store)
+                store.close()
+        }
+    }
+}