@meistrari/agent-core 0.2.0-experimental.0 → 0.2.0-experimental.1

package/src/supervisor/runtime-handler.ts

@@ -6,12 +6,15 @@ import type { EventEnvelope } from '../supervisor-protocol/envelopes/supervisor-
 import type { WireEventBody } from '../supervisor-protocol/event-body'
 import type { SupervisorStore } from './persistence/supervisor-store'
 import type { SupervisorAgentRuntime, SupervisorProviderFactory } from './provider-factory'
+import { ZodError } from 'zod'
 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 { EphemeralFrameBuffer } from './ephemeral-frame-buffer'
+import { SupervisorPersistenceError } from './errors'
+import { commandSequenceConflictCode } from './persistence/supervisor-store'
 import { SupervisorRpcClient } from './rpc-client'
 
 export interface ResidentSupervisorSocket {
@@ -99,8 +102,24 @@ export class SupervisorRuntimeHandler implements RuntimeConnectionHandler {
                 this.schedulePendingCommands()
             }
             catch (error) {
-                this.dependencies.logger.warn({ err: error }, 'rejecting invalid supervisor command')
-                socket.close(1008, 'Supervisor command was rejected.')
+                const rejection = this.dependencies.store.binding()?.body.commandTransport === 'wss-v1'
+                    ? terminalCommandRejection(error)
+                    : undefined
+                if (!rejection) {
+                    this.dependencies.logger.warn({ err: error }, 'rejecting invalid supervisor command')
+                    socket.close(1008, 'Supervisor command was rejected.')
+                    return
+                }
+                // wss-v1: answer a terminal rejection so the worker persists it instead of
+                // redelivering the same command on every reconnect.
+                this.dependencies.logger.warn({ err: error, commandSeq: frame.commandSeq, errorCode: rejection.errorCode }, 'rejecting supervisor command')
+                this.sendRetained(encodeWireFrame({
+                    kind: 'command.ack',
+                    commandId: frame.commandId,
+                    commandSeq: frame.commandSeq,
+                    status: 'rejected',
+                    ...rejection,
+                }))
             }
             return
         }
@@ -328,3 +347,12 @@ function frameText(data: string | ArrayBuffer | Uint8Array): string {
         return data
     return new TextDecoder().decode(data)
 }
+
+/** Only failures the same frame would reproduce are terminal; storage faults still close the socket. */
+function terminalCommandRejection(error: unknown): { errorCode: string, detail: string } | undefined {
+    if (error instanceof ZodError)
+        return { errorCode: 'supervisor.command.invalid-body', detail: 'Command body failed wire validation.' }
+    if (error instanceof SupervisorPersistenceError && error.code === commandSequenceConflictCode)
+        return { errorCode: 'supervisor.command.conflicting-duplicate', detail: error.message.slice(0, 240) }
+    return undefined
+}

package/src/supervisor-protocol/bootstrap.ts

@@ -59,12 +59,15 @@ export const sessionBootstrapBodySchema = z.object({
     }),
     gitBotIdentity: gitIdentitySchema.optional(),
     profile: sessionProfileSchema.optional(),
+    commandTransport: z.literal('wss-v1').optional(),
     initialCommand: z.object({
         commandId: z.string().min(1),
         commandSeq: z.literal(1),
         body: wireCommandBodySchema,
-    }).strict(),
+    }).strict().optional(),
 }).strict().superRefine((body, context) => {
+    if (body.commandTransport === 'wss-v1' ? body.initialCommand !== undefined : body.initialCommand === undefined)
+        context.addIssue({ code: 'custom', path: ['initialCommand'], message: 'wss-v1 bootstraps without a command; legacy bootstrap requires command one.' })
     const workspacePrefix = `${body.agent.cwd}/`
     for (const [index, repository] of body.repositories.entries()) {
         if (repository.root !== body.agent.cwd && !repository.root.startsWith(workspacePrefix)) {

package/src/supervisor-protocol/command-body.ts

@@ -1,5 +1,5 @@
 import z from 'zod'
-import { agentPromptModeSchema, agentPromptSchema, agentUserInputAnswersSchema, jsonObjectSchema, jsonUtf8ByteLength } from '../protocol'
+import { agentPromptModeSchema, agentPromptSchema, agentReasoningEffortSchema, agentUserInputAnswersSchema, jsonObjectSchema, jsonUtf8ByteLength } from '../protocol'
 
 const wireSenderContextSchema = z.discriminatedUnion('kind', [
     z.object({ kind: z.literal('application') }).strict(),
@@ -40,7 +40,9 @@ export const wireCommandExtensionsSchema = jsonObjectSchema.refine(
 const wireSendPromptCommandSchema = z.object({
     type: z.literal('agent.send-prompt'),
     mode: agentPromptModeSchema,
+    turnId: z.string().min(1).optional(),
     model: z.string().trim().min(1).max(256).optional(),
+    reasoningEffort: agentReasoningEffortSchema.optional(),
     prompt: agentPromptSchema,
     attachments: z.array(wireInputAttachmentRefSchema).superRefine((attachments, context) => {
         const attachmentIds = new Set<string>()
@@ -60,6 +62,7 @@ const wireSendPromptCommandSchema = z.object({
 
 const wireInterruptCommandSchema = z.object({
     type: z.literal('agent.interrupt'),
+    turnId: z.string().min(1).optional(),
 }).strict()
 
 const wireRespondUserInputCommandSchema = z.object({

package/src/supervisor-protocol/envelopes/supervisor-to-control-plane.ts

@@ -14,6 +14,7 @@ export const commandAckErrorCodeSchema = z.string()
 
 export const runtimeStateEnvelopeSchema = z.object({
     kind: z.literal('runtime.state'),
+    sourceId: z.string().uuid().optional(),
     lastReceivedCommandSeq: z.number().int().nonnegative(),
     nextEventSeq: eventSequenceSchema,
     agentRun: supervisorAgentRunSnapshotSchema,

package/src/testing/in-memory-runtime-control-plane.ts

@@ -9,6 +9,7 @@ import type {
     CommandSource,
     ConnectionAuthorityStore,
     ConnectionClaim,
+    ConnectionReadinessRejection,
     DurableEventSink,
     EphemeralEventSink,
     RpcDispatcher,
@@ -19,18 +20,37 @@ import { ulid } from 'ulid'
 
 type NotificationCallbacks = Parameters<RuntimeNotifications['start']>[0]
 
+/** Admission state of an in-memory command; only wss-v1 selection consults it. */
+type InMemoryCommandStatus = 'queued' | 'dispatched' | 'received' | 'withdrawn' | 'rejected'
+
+/** Code the fixture answers when a session sandbox announces a different journal than it pinned. */
+export const inMemoryJournalIdentityChangedCode = 'testing.journal-identity-changed'
+
 export class InMemoryRuntimeControlPlane implements ConnectionAuthorityStore, CommandSource, DurableEventSink,
 EphemeralEventSink, RpcDispatcher, BootstrapProvider, SessionFailureSink, RuntimeNotifications {
     readonly durableEventLog: DurableEventEnvelope[] = []
     readonly durableRecordAttempts: number[] = []
     readonly ephemeralEventLog: Array<Parameters<EphemeralEventSink['publish']>[0]> = []
     readonly readySnapshots: SupervisorAgentRunSnapshot[] = []
+    /** `lastReceivedCommandSeq` announced by each accepted bootstrap, in readiness order. */
+    readonly readyReceivedSequences: number[] = []
     readonly projectedCommandSequences: number[] = []
     readonly failedCommandSequences: number[] = []
+    /** wss-v1 receipts, in the order the pump persisted them. */
+    readonly receivedCommandSequences: number[] = []
+    /** wss-v1 terminal rejections, in the order the pump persisted them. */
+    readonly rejectedCommands: Array<{ commandSeq: number, errorCode: string, detail?: string }> = []
+    /** Journal identity announced by each accepted readiness, in order. */
+    readonly readyJournalSourceIds: Array<string | undefined> = []
+    /** Every wss-v1 selection with the receipts that were durable when it ran. */
+    readonly pendingSelections: Array<{ commandSeq: number | undefined, receivedBefore: number[] }> = []
     readonly failureLog: Array<{ kind: string, code?: string, detail?: string }> = []
     readonly rpcCalls: SupervisorRpcRequestEnvelope[] = []
     onDurableRecord: ((event: DurableEventEnvelope) => void | Promise<void>) | undefined
-    private readonly commandLog: CommandEnvelope[]
+    private readonly commandLog: Array<CommandEnvelope & { body: WireCommandBody }>
+    private readonly commandStatus = new Map<number, InMemoryCommandStatus>()
+    private readonly wssV1: boolean
+    private pinnedJournalSourceId: string | undefined
     private notifications: NotificationCallbacks | undefined
     private claimed = false
     private generation = 0
@@ -41,30 +61,49 @@ EphemeralEventSink, RpcDispatcher, BootstrapProvider, SessionFailureSink, Runtim
         ref: { sessionId: string, sessionSandboxId: string, providerSandboxId: string }
         trafficAccessTokenEncrypted: string
         bootstrap: Omit<SessionBootstrapBody, 'sessionId' | 'initialCommand'>
-        initialCommand: { commandId: string, body: WireCommandBody }
+        /** Required by the legacy bootstrap, forbidden by `commandTransport: 'wss-v1'`. */
+        initialCommand?: { commandId: string, body: WireCommandBody }
         secrets?: Awaited<ReturnType<BootstrapProvider['issueEphemeralSecrets']>>
         rpcHandlers?: Readonly<Record<string, (body: unknown) => unknown | Promise<unknown>>>
+        /** Journal this session sandbox was already bound to before the runtime under test started. */
+        pinnedJournalSourceId?: string
     }) {
-        this.commandLog = [{
-            kind: 'command',
-            commandId: input.initialCommand.commandId,
-            commandSeq: 1,
-            body: input.initialCommand.body,
-        }]
+        this.wssV1 = input.bootstrap.commandTransport === 'wss-v1'
+        this.pinnedJournalSourceId = input.pinnedJournalSourceId
+        if (this.wssV1 === (input.initialCommand !== undefined))
+            throw new Error('wss-v1 bootstraps without an initial command; the legacy bootstrap requires one.')
+        this.commandLog = input.initialCommand
+            ? [{
+                    kind: 'command',
+                    commandId: input.initialCommand.commandId,
+                    commandSeq: 1,
+                    body: input.initialCommand.body,
+                }]
+            : []
+        for (const command of this.commandLog)
+            this.commandStatus.set(command.commandSeq, 'queued')
     }
 
     enqueueCommand(input: { commandId?: string, body: WireCommandBody }): CommandEnvelope {
-        const command: CommandEnvelope = {
-            kind: 'command',
+        const command = {
+            kind: 'command' as const,
             commandId: input.commandId ?? ulid(),
             commandSeq: this.commandLog.length + 1,
             body: input.body,
         }
         this.commandLog.push(command)
+        this.commandStatus.set(command.commandSeq, 'queued')
         this.notifications?.onCommandsReady(this.input.ref.sessionId)
         return command
     }
 
+    /** Withdraw an admitted command before dispatch; its sequence stays allocated, leaving a gap. */
+    withdrawCommand(commandSeq: number): void {
+        if (this.commandStatus.get(commandSeq) !== 'queued')
+            throw new Error(`Command ${commandSeq} is not queued and cannot be withdrawn.`)
+        this.commandStatus.set(commandSeq, 'withdrawn')
+    }
+
     demandConnection(): void {
         this.notifications?.onConnectionDemand(this.input.ref.sessionSandboxId)
     }
@@ -106,7 +145,9 @@ EphemeralEventSink, RpcDispatcher, BootstrapProvider, SessionFailureSink, Runtim
         return {
             renewed,
             ...(renewed ? { leaseExpiresAt: new Date(Date.now() + 30_000) } : {}),
-            hasOutstandingCommand: this.projectedCommandSequences.length + this.failedCommandSequences.length < this.commandLog.length,
+            hasOutstandingCommand: this.wssV1
+                ? this.deliverableCommands().length > 0
+                : this.projectedCommandSequences.length + this.failedCommandSequences.length < this.commandLog.length,
         }
     }
 
@@ -114,13 +155,32 @@ EphemeralEventSink, RpcDispatcher, BootstrapProvider, SessionFailureSink, Runtim
         return this.claimed && input.generation === this.generation
     }
 
-    async markConnectionReady(input: { generation: number, agentRunSnapshot: SupervisorAgentRunSnapshot }): Promise<boolean> {
+    async markConnectionReady(input: {
+        generation: number
+        lastReceivedCommandSeq: number
+        agentRunSnapshot: SupervisorAgentRunSnapshot
+        journalSourceId?: string
+    }): Promise<boolean | ConnectionReadinessRejection> {
         if (!this.claimed || input.generation !== this.generation)
             return false
+        if (this.pinnedJournalSourceId !== undefined && input.journalSourceId !== this.pinnedJournalSourceId) {
+            return {
+                ready: false,
+                code: inMemoryJournalIdentityChangedCode,
+                detail: `Session sandbox is pinned to journal ${this.pinnedJournalSourceId}; supervisor announced ${input.journalSourceId ?? 'none'}.`,
+            }
+        }
+        this.pinnedJournalSourceId ??= input.journalSourceId
         this.readySnapshots.push(input.agentRunSnapshot)
+        this.readyReceivedSequences.push(input.lastReceivedCommandSeq)
+        this.readyJournalSourceIds.push(input.journalSourceId)
         return true
     }
 
+    journalSourceId(): string | undefined {
+        return this.pinnedJournalSourceId
+    }
+
     async markConnectionReconnecting(): Promise<void> {}
 
     async releaseConnection(input: { generation: number }): Promise<void> {
@@ -137,9 +197,35 @@ EphemeralEventSink, RpcDispatcher, BootstrapProvider, SessionFailureSink, Runtim
     }
 
     async next(input: { afterSequence: number }): Promise<CommandEnvelope | undefined> {
+        if (this.wssV1)
+            throw new Error('wss-v1 never advances a cumulative command cursor.')
         return this.commandLog.find(command => command.commandSeq > input.afterSequence)
     }
 
+    /** wss-v1 selection: cancel and steer jump the queue; withdrawn commands leave gaps. */
+    async pending(): Promise<CommandEnvelope | undefined> {
+        if (!this.wssV1)
+            throw new Error('Individual command selection requires commandTransport wss-v1.')
+        // Yield like a database round trip so admissions made in the same tick are visible.
+        await Promise.resolve()
+        const deliverable = this.deliverableCommands()
+        const selected = deliverable.find(command => isPriorityCommand(command.body)) ?? deliverable[0]
+        this.pendingSelections.push({ commandSeq: selected?.commandSeq, receivedBefore: [...this.receivedCommandSequences] })
+        if (selected)
+            this.commandStatus.set(selected.commandSeq, 'dispatched')
+        return selected
+    }
+
+    async received(input: { commandId: string, commandSeq: number }): Promise<void> {
+        this.settleDispatched(input, 'received')
+        this.receivedCommandSequences.push(input.commandSeq)
+    }
+
+    async rejected(input: { commandId: string, commandSeq: number, errorCode: string, detail?: string }): Promise<void> {
+        this.settleDispatched(input, 'rejected')
+        this.rejectedCommands.push({ commandSeq: input.commandSeq, errorCode: input.errorCode, detail: input.detail })
+    }
+
     async getAckFloor(): Promise<number> {
         return this.ackFloor
     }
@@ -203,4 +289,24 @@ EphemeralEventSink, RpcDispatcher, BootstrapProvider, SessionFailureSink, Runtim
     async stop(): Promise<void> {
         this.notifications = undefined
     }
+
+    private settleDispatched(input: { commandId: string, commandSeq: number }, status: 'received' | 'rejected'): void {
+        const command = this.commandLog[input.commandSeq - 1]
+        if (!command || command.commandId !== input.commandId)
+            throw new Error(`Receipt for unknown command ${input.commandSeq}.`)
+        if (this.commandStatus.get(input.commandSeq) !== 'dispatched')
+            throw new Error(`Command ${input.commandSeq} was not dispatched.`)
+        this.commandStatus.set(input.commandSeq, status)
+    }
+
+    private deliverableCommands(): Array<CommandEnvelope & { body: WireCommandBody }> {
+        return this.commandLog.filter((command) => {
+            const status = this.commandStatus.get(command.commandSeq)
+            return status === 'queued' || status === 'dispatched'
+        })
+    }
+}
+
+function isPriorityCommand(body: WireCommandBody): boolean {
+    return body.type === 'agent.interrupt' || (body.type === 'agent.send-prompt' && body.mode === 'steer')
 }

package/src/testing/index.ts

@@ -1,6 +1,6 @@
 export { createTestControlAuthority } from './es256-test-keys'
 export type { TestControlAuthority } from './es256-test-keys'
-export { InMemoryRuntimeControlPlane } from './in-memory-runtime-control-plane'
+export { inMemoryJournalIdentityChangedCode, InMemoryRuntimeControlPlane } from './in-memory-runtime-control-plane'
 export { createLoopbackSupervisorConnectionOpener } from './loopback-supervisor-connection'
 export { createScriptedProvider } from './scripted-provider'
 export type { ScriptedCommandContext } from './scripted-provider'

package/src/worker-runtime-client/command-pump.ts

@@ -3,11 +3,19 @@ import type { CommandAckEnvelope } from '../supervisor-protocol/envelopes/superv
 import type { CommandSource, ConnectionAuthorityStore, SupervisorConnection } from './ports'
 import { encodeWireFrame } from '../supervisor-protocol/wire-codec'
 
+export class CommandAckTimeoutError extends Error {
+    constructor() {
+        super('agent-core.command-ack-timeout')
+        this.name = 'CommandAckTimeoutError'
+    }
+}
+
 export class SessionCommandPump {
     private afterSequence: number
     private running = false
     private stopped = false
     private wakePending = false
+    private readonly idleWaiters = new Set<() => void>()
     private pending: {
         commandId: string
         commandSeq: number
@@ -19,13 +27,20 @@ export class SessionCommandPump {
         sessionSandboxId: string
         runtimeConnectionId: string
         afterSequence: number
+        individualReceipts?: boolean
+        ackTimeoutMs?: number
+        onFailure?: (error: unknown) => void
         commands: CommandSource
-        authorityStore: ConnectionAuthorityStore
+        authorityStore?: ConnectionAuthorityStore
         connection: SupervisorConnection
         logger: Logger
         onRejected: (ack: Extract<CommandAckEnvelope, { status: 'rejected' }>) => Promise<void>
     }) {
         this.afterSequence = dependencies.afterSequence
+        if (dependencies.ackTimeoutMs !== undefined && (!Number.isSafeInteger(dependencies.ackTimeoutMs) || dependencies.ackTimeoutMs < 1))
+            throw new RangeError('ackTimeoutMs must be a positive safe integer')
+        if (dependencies.individualReceipts && (!dependencies.commands.pending || !dependencies.commands.received || !dependencies.commands.rejected))
+            throw new Error('wss-v1 requires individual command selection, receipt persistence and rejection persistence')
     }
 
     start(): void {
@@ -43,7 +58,7 @@ export class SessionCommandPump {
     acknowledge(ack: CommandAckEnvelope): void {
         const pending = this.pending
         if (!pending) {
-            if (ack.status === 'received' && ack.commandSeq <= this.afterSequence)
+            if (ack.status === 'received' && (this.dependencies.individualReceipts || ack.commandSeq <= this.afterSequence))
                 return
             this.dependencies.logger.warn({ commandSeq: ack.commandSeq }, 'closing after an unsolicited command acknowledgement')
             this.dependencies.connection.close(1008, 'Command ACK has no pending command.')
@@ -75,6 +90,13 @@ export class SessionCommandPump {
         return this.afterSequence
     }
 
+    /** Stop dispatch and wait for any in-flight selection/send/receipt to settle. */
+    async close(): Promise<void> {
+        this.stop()
+        if (this.running)
+            await new Promise<void>(resolve => this.idleWaiters.add(resolve))
+    }
+
     private async run(): Promise<void> {
         if (this.running)
             return
@@ -83,26 +105,58 @@ export class SessionCommandPump {
             while (!this.stopped && this.wakePending) {
                 this.wakePending = false
                 while (!this.stopped) {
-                    const command = await this.dependencies.commands.next({
-                        sessionId: this.dependencies.sessionId,
-                        runtimeConnectionId: this.dependencies.runtimeConnectionId,
-                        afterSequence: this.afterSequence,
-                    })
+                    const command = this.dependencies.individualReceipts
+                        ? await this.dependencies.commands.pending!({ sessionId: this.dependencies.sessionId, runtimeConnectionId: this.dependencies.runtimeConnectionId })
+                        : await this.dependencies.commands.next({
+                                sessionId: this.dependencies.sessionId,
+                                runtimeConnectionId: this.dependencies.runtimeConnectionId,
+                                afterSequence: this.afterSequence,
+                            })
+                    if (this.stopped)
+                        return
                     if (!command)
                         break
                     const ack = await this.sendAndWait(command)
                     if (this.stopped)
                         return
                     if (ack.status === 'rejected') {
+                        if (!this.dependencies.individualReceipts) {
+                            await this.dependencies.onRejected(ack)
+                            return
+                        }
+                        // Terminal for this command only: persist it so `pending` never offers it again,
+                        // then keep delivering the rest of the session's work.
+                        await this.dependencies.commands.rejected!({
+                            sessionId: this.dependencies.sessionId,
+                            runtimeConnectionId: this.dependencies.runtimeConnectionId,
+                            commandId: ack.commandId,
+                            commandSeq: ack.commandSeq,
+                            errorCode: ack.errorCode,
+                            detail: ack.detail,
+                        })
                         await this.dependencies.onRejected(ack)
-                        return
+                        continue
                     }
-                    this.afterSequence = ack.commandSeq
+                    if (this.dependencies.individualReceipts) {
+                        await this.dependencies.commands.received!({
+                            sessionId: this.dependencies.sessionId,
+                            runtimeConnectionId: this.dependencies.runtimeConnectionId,
+                            commandId: ack.commandId,
+                            commandSeq: ack.commandSeq,
+                        })
+                    }
+                    this.afterSequence = Math.max(this.afterSequence, ack.commandSeq)
                 }
             }
         }
+        catch (error) {
+            this.fail(error)
+        }
         finally {
             this.running = false
+            for (const resolve of this.idleWaiters)
+                resolve()
+            this.idleWaiters.clear()
             if (!this.stopped && this.wakePending)
                 void this.run()
         }
@@ -110,18 +164,39 @@ export class SessionCommandPump {
 
     private async sendAndWait(command: NonNullable<Awaited<ReturnType<CommandSource['next']>>>): Promise<CommandAckEnvelope> {
         const waiter = Promise.withResolvers<CommandAckEnvelope>()
+        const timeout = this.dependencies.ackTimeoutMs === undefined ? undefined : setTimeout(() => this.fail(new CommandAckTimeoutError()), this.dependencies.ackTimeoutMs)
         this.pending = {
             commandId: command.commandId,
             commandSeq: command.commandSeq,
-            settle: waiter.resolve,
+            settle: (ack) => {
+                clearTimeout(timeout)
+                waiter.resolve(ack)
+            },
         }
         try {
             await this.dependencies.connection.send(encodeWireFrame(command))
             return await waiter.promise
         }
         finally {
+            clearTimeout(timeout)
             if (this.pending?.commandId === command.commandId)
                 this.pending = undefined
         }
     }
+
+    private fail(error: unknown): void {
+        if (this.stopped)
+            return
+        this.dependencies.logger.warn({ err: error }, 'command delivery failed; reconnect and reconcile durable attempts')
+        try {
+            this.dependencies.onFailure?.(error)
+        }
+        catch (callbackError) {
+            this.dependencies.logger.warn({ err: callbackError }, 'command failure callback failed')
+        }
+        finally {
+            this.stop()
+            this.dependencies.connection.close(1011, 'Command delivery failed.')
+        }
+    }
 }