@meistrari/agent-core 0.1.0 → 0.1.1

package/README.md

@@ -45,3 +45,15 @@ bunx agent-core-supervisor \
 Use `--loopback-tcp` for local and image-build probes. Production images default to the protected Unix socket. The extension module exports `default`, `extensions`, or `createSupervisorExtensions()` matching `SupervisorExtensions`.
 
 Publishing runs from `main` through `.github/workflows/publish.yml` (conventional commits decide the bump).
+
+## Durable command outcomes
+
+A supervisor `received` ACK advances the command delivery cursor only. Implementations of
+`DurableEventSink.record` must atomically store each durable event, project
+`supervisor.command.applied` or `supervisor.command.failed` into command state, and advance the
+ACK floor. Duplicate events must not repeat projections. This keeps outcomes consistent when
+the worker disconnects after persistence but before sending its event ACK.
+
+The former `ConnectionAuthorityStore.projectAppliedCommand` callback has been removed.
+Move that projection into the durable-event transaction; receiving a command does not prove
+that the provider executed it. See `InMemoryRuntimeControlPlane.record` for the test fixture.

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@meistrari/agent-core",
     "type": "module",
-    "version": "0.1.0",
+    "version": "0.1.1",
     "packageManager": "bun@1.3.12",
     "description": "Shared contracts and runtime modules for Tela coding-agent sandboxes: agent protocol, supervisor wire protocol, resident supervisor, worker runtime client, and Claude/Codex harness adapters.",
     "license": "UNLICENSED",
@@ -89,9 +89,9 @@
         }
     },
     "dependencies": {
-        "jose": "^6.1.3",
+        "jose": "6.2.11",
         "pino": "^9.7.0",
-        "ulid": "^3.0.1",
+        "ulid": "3.0.2",
         "zod": "^4.1.12"
     },
     "devDependencies": {
@@ -100,9 +100,9 @@
         "@anthropic-ai/sdk": "0.93.0",
         "@modelcontextprotocol/sdk": "1.29.0",
         "@types/bun": "1.3.12",
-        "@types/pg": "^8.15.5",
+        "@types/pg": "8.23.1",
         "eslint": "^9.30.0",
-        "pg": "^8.16.3",
+        "pg": "8.23.0",
         "typescript": "5.9.3"
     }
 }

package/src/agents/claude/claude-event-mapper.ts

@@ -191,8 +191,20 @@ export function mapClaudeMessage(message: SDKMessage, state: ClaudeEventMapperSt
         // Claude Agent SDK result usage is per completed ask/turn for the stream-json path we use,
         // not a monotonic counter across the long-lived query. Emit it directly so summing
         // normalized usage events gives the run total; do not diff against prior results.
-        if (usage)
-            drafts.push({ type: 'usage', turnId, actor: mainActor, payload: { usage } })
+        if (usage) {
+            drafts.push({ type: 'usage', turnId, actor: mainActor, payload: { usage, accounting: {
+                observationId: message.uuid,
+                mode: 'increment',
+                scopeId: turnId,
+                includesChildren: true,
+                models: Object.fromEntries(Object.entries(message.modelUsage ?? {}).map(([model, counts]) => [model, {
+                    inputTokens: counts.inputTokens,
+                    outputTokens: counts.outputTokens,
+                    cacheReadTokens: counts.cacheReadInputTokens,
+                    cacheWriteTokens: counts.cacheCreationInputTokens,
+                }])),
+            } } })
+        }
         endOpenReasoning(drafts, state, turnId)
         const interruptAccepted = state.interrupt.status === 'accepted' && state.interrupt.turnId === turnId
         drafts.push({ type: 'turn.ended', turnId, actor: mainActor, payload: turnEndedPayload(message, interruptAccepted) })

package/src/agents/claude/claude-run.ts

@@ -285,8 +285,8 @@ export class ClaudeRun implements AgentRun {
     // session identity mismatch are provider protocol drift and fail the run closed. `cancelled`
     // (a steered-over/aborted command) and `discarded` (the session ended with the command still
     // queued) are valid observed states but NEGATIVE terminals — never a positive acceptance, so
-    // they are validated and no-op even when a waiter is pending; the pending prompt's real outcome
-    // is settled by run close/error as delivery-unknown. Valid positive frames without a pending
+    // they reject any pending waiter as delivery-unknown so command processing can advance.
+    // Valid positive frames without a pending
     // waiter are internal lifecycle for already-settled or non-prompt inputs and are ignored.
     private settleAcceptance(frame: ClaudeCommandLifecycleMessage): void {
         const parsed = commandLifecycleFrameSchema.safeParse(frame)
@@ -302,8 +302,12 @@ export class ClaudeRun implements AgentRun {
                 details: { expected: this.metadata.providerSessionId, actual: parsed.data.session_id },
             })
         }
-        if (parsed.data.state === 'cancelled' || parsed.data.state === 'discarded')
+        if (parsed.data.state === 'cancelled' || parsed.data.state === 'discarded') {
+            this.acceptanceWaiters.get(parsed.data.command_uuid)?.reject(new AgentDeliveryUnknownError({
+                message: `Claude command ended as ${parsed.data.state} before acceptance was observed.`,
+            }))
             return
+        }
         this.acceptanceWaiters.get(parsed.data.command_uuid)?.resolve()
     }
 

package/src/agents/codex/codex-event-mapper.ts

@@ -3,6 +3,7 @@ import type { AgentWorkStatus } from '../../protocol/agent-work'
 import type { AgentEventDraft } from '../agent-event-stream'
 import type { CodexJsonRpcMessage, CodexServerNotification } from './codex-json-rpc-client'
 import type { ServerNotificationParamsByMethod } from './codex-protocol'
+import { createHash } from 'node:crypto'
 import { jsonObjectSchema, jsonValueSchema } from '../../protocol'
 import { CANONICAL_TOOL } from '../../protocol/agent-tool-name'
 import { createRuntimeWorkItemId } from '../agent-id'
@@ -96,7 +97,19 @@ export function mapCodexNotification(notification: CodexNotification, state: Cod
             const usage = usageFromTokenUsage(notification.params.tokenUsage)
             if (!usage)
                 return []
-            return emitOrBufferByThread({ draft: { type: 'usage', turnId: notification.params.turnId, payload: { usage } }, threadId: notification.params.threadId, state })
+            return emitOrBufferByThread({ draft: { type: 'usage', turnId: notification.params.turnId, payload: {
+                usage,
+                accounting: {
+                    observationId: createHash('sha256').update(notification.params.threadId).update(JSON.stringify(notification.params.tokenUsage.total)).digest('hex'),
+                    mode: 'cumulative',
+                    scopeId: notification.params.threadId,
+                    includesChildren: false,
+                    usage: {
+                        ...usageFromCounts(notification.params.tokenUsage.total),
+                        inputTokens: Math.max(0, notification.params.tokenUsage.total.inputTokens - notification.params.tokenUsage.total.cachedInputTokens),
+                    },
+                },
+            } }, threadId: notification.params.threadId, state })
         }
         case 'turn/plan/updated':
             if (!state.startedTurnIds.has(notification.params.turnId) || notification.params.threadId !== state.mainThreadId)

package/src/protocol/agent-event.ts

@@ -4,7 +4,7 @@ import { agentRunMetadataSchema } from './agent-metadata'
 import { agentPayloadOverflowSchema } from './agent-overflow'
 import { agentProviderIdSchema } from './agent-provider'
 import { agentToolCallStatusSchema, agentToolResultSchema } from './agent-tool'
-import { agentUsageSchema } from './agent-usage'
+import { agentUsageAccountingSchema, agentUsageSchema } from './agent-usage'
 import { agentUserInputAnswersSchema, agentUserInputQuestionSchema } from './agent-user-input'
 import { agentWorkObservationSchema } from './agent-work'
 
@@ -265,6 +265,7 @@ export const usageAgentEventSchema = agentTurnEventBaseSchema.extend({
     type: z.literal('usage'),
     payload: z.object({
         usage: agentUsageSchema,
+        accounting: agentUsageAccountingSchema.optional(),
     }).strict(),
 }).strict()
 

package/src/protocol/agent-usage.ts

@@ -12,3 +12,17 @@ export const agentUsageSchema = z.object({
 }).strict()
 
 export type AgentUsage = z.infer<typeof agentUsageSchema>
+
+/**
+ * Accounting semantics are separate from display counters. Consumers persist
+ * observations/checkpoints before acknowledging events, including across runs.
+ */
+export const agentUsageAccountingSchema = z.object({
+    observationId: z.string().min(1),
+    mode: z.enum(['increment', 'cumulative']),
+    scopeId: z.string().min(1),
+    includesChildren: z.boolean(),
+    usage: agentUsageSchema.optional(),
+    model: z.string().min(1).optional(),
+    models: z.record(z.string(), agentUsageSchema).optional(),
+}).strict()

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.1.0",
-    sha: "9cd95365c6d39d1f44098fdd8006087c3adabfb4",
-    buildTime: "2026-09-04T20:01:49.852Z",
+    version: "0.1.1",
+    sha: "00ac4425fb84e86e0adabba1067485b94f45c100",
+    buildTime: "2026-09-08T17:04:18.818Z",
 } as const

package/src/supervisor/bootstrap-binder.ts

@@ -34,7 +34,12 @@ export function createBootstrapBinder(input: {
     shutdown: (code: number) => void
     logger: Logger
 }): BootstrapBinder {
+    let pending = Promise.resolve()
     return async (request) => {
+        const previous = pending
+        const released = Promise.withResolvers<void>()
+        pending = released.promise
+        await previous
         try {
             return await bind(request)
         }
@@ -55,6 +60,9 @@ export function createBootstrapBinder(input: {
                 terminate: () => input.shutdown(TERMINAL_ERROR_CODE),
             }
         }
+        finally {
+            released.resolve()
+        }
     }
 
     async function bind(request: {

package/src/supervisor/websocket-server.ts

@@ -381,6 +381,7 @@ export class ResidentSupervisorWebSocketServer {
                 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 }

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

@@ -26,6 +26,7 @@ EphemeralEventSink, RpcDispatcher, BootstrapProvider, SessionFailureSink, Runtim
     readonly ephemeralEventLog: Array<Parameters<EphemeralEventSink['publish']>[0]> = []
     readonly readySnapshots: SupervisorAgentRunSnapshot[] = []
     readonly projectedCommandSequences: number[] = []
+    readonly failedCommandSequences: number[] = []
     readonly failureLog: Array<{ kind: string, code?: string, detail?: string }> = []
     readonly rpcCalls: SupervisorRpcRequestEnvelope[] = []
     onDurableRecord: ((event: DurableEventEnvelope) => void | Promise<void>) | undefined
@@ -105,7 +106,7 @@ EphemeralEventSink, RpcDispatcher, BootstrapProvider, SessionFailureSink, Runtim
         return {
             renewed,
             ...(renewed ? { leaseExpiresAt: new Date(Date.now() + 30_000) } : {}),
-            hasOutstandingCommand: this.projectedCommandSequences.length < this.commandLog.length - 1,
+            hasOutstandingCommand: this.projectedCommandSequences.length + this.failedCommandSequences.length < this.commandLog.length,
         }
     }
 
@@ -131,10 +132,6 @@ EphemeralEventSink, RpcDispatcher, BootstrapProvider, SessionFailureSink, Runtim
         return this.claimed && input.generation === this.generation
     }
 
-    async projectAppliedCommand(input: { commandSeq: number }): Promise<void> {
-        this.projectedCommandSequences.push(input.commandSeq)
-    }
-
     async initial(): Promise<CommandEnvelope | undefined> {
         return this.commandLog[0]
     }
@@ -157,6 +154,10 @@ EphemeralEventSink, RpcDispatcher, BootstrapProvider, SessionFailureSink, Runtim
             return { status: 'duplicate', highWaterMark: this.ackFloor }
         if (event.seq !== this.ackFloor + 1)
             return { status: 'gap' }
+        if (event.body.type === 'supervisor.command.applied')
+            this.projectedCommandSequences.push(event.body.payload.commandSeq)
+        if (event.body.type === 'supervisor.command.failed')
+            this.failedCommandSequences.push(event.body.payload.commandSeq)
         this.durableEventLog.push(event)
         this.ackFloor = event.seq
         await this.onDurableRecord?.(event)

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

@@ -98,11 +98,6 @@ export class SessionCommandPump {
                         return
                     }
                     this.afterSequence = ack.commandSeq
-                    await this.dependencies.authorityStore.projectAppliedCommand({
-                        sessionSandboxId: this.dependencies.sessionSandboxId,
-                        runtimeConnectionId: this.dependencies.runtimeConnectionId,
-                        commandSeq: ack.commandSeq,
-                    })
                 }
             }
         }

package/src/worker-runtime-client/connection-attempt.ts

@@ -31,6 +31,7 @@ export class SessionSandboxConnectionAttempt {
 
     constructor(private readonly dependencies: {
         claim: ConnectionClaim
+        establishmentDeadline: number
         replicaId: string
         trafficTokenEncryptionKey: string
         signControlAuthority: ControlAuthoritySigner
@@ -96,7 +97,7 @@ export class SessionSandboxConnectionAttempt {
             signal: this.controller.signal,
             onMessage: frame => this.processor ? this.processor.receive(frame) : queuedFrames.push(frame),
             onClose: close => closed.resolve(close),
-        }), performance.now() + this.dependencies.timings.dialTimeoutMs, this.controller.signal, () => new ConnectionClosedError({
+        }), Math.min(this.dependencies.establishmentDeadline, performance.now() + this.dependencies.timings.dialTimeoutMs), this.controller.signal, () => new ConnectionClosedError({
             ready: false,
             detail: 'Supervisor connection dial timed out.',
         }))
@@ -160,7 +161,15 @@ export class SessionSandboxConnectionAttempt {
             ...secrets,
         }))
 
-        const readiness = await processor.waitForReadiness({ signal: this.controller.signal }).catch(async (error: unknown) => {
+        const readiness = await beforeDeadline(Promise.race([
+            processor.waitForReadiness({ signal: this.controller.signal }),
+            closed.promise.then((close) => {
+                throw new ConnectionClosedError({ ready: false, detail: `${close.code}:${close.reason}` })
+            }),
+        ]), Math.min(this.dependencies.establishmentDeadline, performance.now() + 10_000), this.controller.signal, () => new ConnectionClosedError({
+            ready: false,
+            detail: 'Supervisor bootstrap timed out.',
+        })).catch(async (error: unknown) => {
             if (error instanceof BootstrapRejectedAckError) {
                 await processor.acknowledgeBootstrapRejection(error.ack)
                 throw new DeterministicEstablishmentError(error.ack.errorCode, error.ack.detail, true)

package/src/worker-runtime-client/ports.ts

@@ -44,7 +44,6 @@ export interface ConnectionAuthorityStore {
     markConnectionReconnecting: (input: { sessionSandboxId: string, generation: number }) => Promise<void>
     releaseConnection: (input: { sessionSandboxId: string, generation: number, reason: string }) => Promise<void>
     markConnectionRetryExhausted: (input: { sessionSandboxId: string, generation: number, replicaId: string }) => Promise<boolean>
-    projectAppliedCommand: (input: { sessionSandboxId: string, runtimeConnectionId: string, commandSeq: number }) => Promise<void>
 }
 
 export interface CommandSource {
@@ -58,6 +57,9 @@ export type DurableEventResult
 
 export interface DurableEventSink {
     getAckFloor: (input: { sessionSandboxId: string }) => Promise<number>
+    // Atomically persist the event, advance the ACK floor, and project its command outcome.
+    // Only supervisor.command.applied marks a command applied; received ACKs never do.
+    // Replayed events must not duplicate projections, including after reconnect.
     record: (input: SessionSandboxRef & { runtimeConnectionId: string, event: DurableEventEnvelope }) => Promise<DurableEventResult>
 }
 

package/src/worker-runtime-client/sandbox-connection-runtime.ts

@@ -154,6 +154,7 @@ class OwnedConnection {
             while (!this.controller.signal.aborted) {
                 const attempt = new SessionSandboxConnectionAttempt({
                     claim,
+                    establishmentDeadline,
                     replicaId: this.dependencies.replicaId,
                     trafficTokenEncryptionKey: this.dependencies.trafficTokenEncryptionKey,
                     signControlAuthority: this.dependencies.signControlAuthority,