@meistrari/agent-core 0.3.0 → 0.4.0-experimental.0

package/README.md

@@ -160,3 +160,9 @@ using it. Commit generated files with generator changes; CI checks reproducibili
 `agent.change-settings` carries a full `settings: { model, reasoningEffort }` pair through the supervisor wire and the agent protocol. Claude and Codex apply it only at an idle turn boundary, without submitting input, and emit `session.settings.changed` with the command ID and `appliesFrom: next_turn`. Product catalog, provider compatibility and admission ordering remain the caller's responsibility.
 
 The supervisor advertises `capabilities["model-change"] = "v1"` in health. It commits the settings command outcome and inbox status in one SQLite transaction. After a process restart, an interrupted settings command can be reapplied idempotently; prompt commands retain their uncertain-delivery policy and are never retried by this path. Confirmed settings override the immutable bootstrap defaults when resuming the provider. Prompt and user-input-answer commands may carry resolved `settings` so their execution does not rely solely on mutable defaults.
+
+## Reconfiguration before the first command
+
+A bound supervisor accepts a `session.bootstrap` whose body differs from its binding only while its journal has received no command and the bootstrap carries none. The new body replaces the persisted binding after the same admission as the first bootstrap, the agent runtime started for the previous configuration is closed, and the next one opens a fresh provider session (`fresh` on the provider factory) instead of resuming the bound one, so it reads the agent's files again. The supervisor store keeps that reset until a provider session starts from the new body, so a restart or a reconnect in between does not resume the previous one. Once a command arrived, a different body is rejected with `agent-core.bootstrap-configuration-conflict`, as before.
+
+The supervisor advertises `capabilities["reconfigure-before-commands"] = "v1"` in health. A control plane uses it only on sandboxes that report it: an older sandbox keeps rejecting any other configuration after its first bootstrap.

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@meistrari/agent-core",
     "type": "module",
-    "version": "0.3.0",
+    "version": "0.4.0-experimental.0",
     "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",

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

@@ -57,6 +57,9 @@ export interface CodexEventMapperState {
     readonly endedSubagentIds: Set<string>
     readonly subagentByThreadId: Map<string, CodexSubagentRef>
     readonly subagentById: Map<string, CodexSubagentRef>
+    readonly ownerTurnIdBySubagentId: Map<string, string>
+    readonly draftsAwaitingOwnerByActorId: Map<string, AgentEventDraft[]>
+    readonly unreportedEndedSubagentsByParent: Map<string, Map<string, string>>
     readonly subagentNameByThreadId: Map<string, string>
     readonly pendingDraftsByThreadId: Map<string, CodexUnownedTurnEventDraft[]>
     readonly turnErrorsById: Map<string, AgentError>
@@ -80,6 +83,9 @@ export function createCodexEventMapperState(): CodexEventMapperState {
         endedSubagentIds: new Set(),
         subagentByThreadId: new Map(),
         subagentById: new Map(),
+        ownerTurnIdBySubagentId: new Map(),
+        draftsAwaitingOwnerByActorId: new Map(),
+        unreportedEndedSubagentsByParent: new Map(),
         subagentNameByThreadId: new Map(),
         pendingDraftsByThreadId: new Map(),
         turnErrorsById: new Map(),
@@ -106,6 +112,52 @@ export function cacheCodexThreadMetadata(thread: CodexThreadMetadata, state: Cod
 }
 
 export function mapCodexNotification(notification: CodexNotification, state: CodexEventMapperState): AgentEventDraft[] {
+    return attributeSubagentDraftsToOwnerTurn(mapNotificationDrafts(notification, state), state)
+}
+
+function attributeSubagentDraftsToOwnerTurn(drafts: AgentEventDraft[], state: CodexEventMapperState): AgentEventDraft[] {
+    return drafts.flatMap(draft => attributeSubagentDraft(draft, state))
+}
+
+function attributeSubagentDraft(draft: AgentEventDraft, state: CodexEventMapperState): AgentEventDraft[] {
+    if (!('actor' in draft) || draft.actor.type !== 'subagent')
+        return [draft]
+    const { subagentId, parentActorId } = draft.actor
+    if (draft.type === 'turn.started' || draft.type === 'turn.ended')
+        return []
+    let ownerTurnId = state.ownerTurnIdBySubagentId.get(subagentId)
+    if (!ownerTurnId && draft.type === 'subagent.started') {
+        ownerTurnId = parentActorId === mainActor.actorId ? draft.turnId : state.ownerTurnIdBySubagentId.get(parentActorId)
+        if (ownerTurnId)
+            state.ownerTurnIdBySubagentId.set(subagentId, ownerTurnId)
+        else
+            return awaitOwner(parentActorId, draft, state)
+    }
+    if (!ownerTurnId && parentActorId === mainActor.actorId)
+        ownerTurnId = state.currentMainTurn.status === 'open' ? state.currentMainTurn.turnId : draft.turnId
+    if (!ownerTurnId)
+        return awaitOwner(subagentId, draft, state)
+    if (draft.type === 'subagent.ended') {
+        const pending = state.unreportedEndedSubagentsByParent.get(parentActorId) ?? new Map<string, string>()
+        pending.set(subagentId, draft.payload.status)
+        state.unreportedEndedSubagentsByParent.set(parentActorId, pending)
+    }
+    const attributed: AgentEventDraft = { ...draft, turnId: ownerTurnId }
+    if (draft.type !== 'subagent.started')
+        return [attributed]
+    const awaiting = state.draftsAwaitingOwnerByActorId.get(subagentId) ?? []
+    state.draftsAwaitingOwnerByActorId.delete(subagentId)
+    return [attributed, ...attributeSubagentDraftsToOwnerTurn(awaiting, state)]
+}
+
+function awaitOwner(actorId: string, draft: AgentEventDraft, state: CodexEventMapperState): AgentEventDraft[] {
+    const awaiting = state.draftsAwaitingOwnerByActorId.get(actorId) ?? []
+    awaiting.push(draft)
+    state.draftsAwaitingOwnerByActorId.set(actorId, awaiting)
+    return []
+}
+
+function mapNotificationDrafts(notification: CodexNotification, state: CodexEventMapperState): AgentEventDraft[] {
     // Codex has many app-server notifications; the runtime maps the subset that has a provider-neutral AgentEvent.
 
     switch (notification.method) {
@@ -265,11 +317,11 @@ function toolCallStart(item: CodexStartedItem): { toolName: string, input: JsonV
         return undefined
 
     if (item.type === 'commandExecution')
-        return { toolName, input: toJsonObject({ command: Array.isArray(item.command) ? item.command.join(' ') : String(item.command ?? ''), cwd: item.cwd }) }
+        return { toolName, input: toJsonObject({ command: unwrapShellCommand(Array.isArray(item.command) ? item.command.join(' ') : String(item.command ?? '')), cwd: item.cwd }) }
     if (item.type === 'webSearch')
         return { toolName, input: toJsonObject({ query: optionalNonEmpty(item.query) }) }
     if (item.type === 'fileChange')
-        return { toolName, input: jsonInput({ files: item.changes.map(change => removeUndefined({ path: change.path, kind: change.kind?.type })) }) }
+        return { toolName, input: jsonInput({ file_path: item.changes.map(change => change.path).join(', '), files: item.changes.map(change => removeUndefined({ path: change.path, kind: change.kind?.type })) }) }
     if (item.type === 'imageView')
         return { toolName, input: toJsonObject({ path: item.path }) }
     if (item.type === 'imageGeneration')
@@ -283,6 +335,17 @@ function toolCallStart(item: CodexStartedItem): { toolName: string, input: JsonV
     return undefined
 }
 
+const SHELL_WRAPPER = /^(?:\/(?:usr\/)?bin\/)?(?:ba|z)?sh -l?c (?:'((?:[^']|'\\'')*)'|"((?:[^"\\]|\\.)*)")$/s
+
+export function unwrapShellCommand(command: string): string {
+    const match = SHELL_WRAPPER.exec(command.trim())
+    if (!match)
+        return command
+    if (match[1] !== undefined)
+        return match[1].replaceAll(`'\\''`, `'`)
+    return match[2]!.replace(/\\([\\"$`])/g, '$1')
+}
+
 function toolNameForItem(item: CodexStartedItem | CodexCompletedItem): string | undefined {
     if (item.type === 'commandExecution')
         return CANONICAL_TOOL.bash
@@ -586,6 +649,7 @@ function mapCollabAgentToolCompleted({ turnId, threadId, item, mapperState }: {
                 toolCallId: item.id,
                 toolName: item.tool,
                 status: item.status === 'failed' ? 'failed' as const : 'completed' as const,
+                output: item.status === 'failed' ? undefined : collabToolOutput(collabToolSummary(item, mapperState)),
                 error: item.status === 'failed' ? { message: `Codex ${item.tool} failed.` } : undefined,
             }),
         },
@@ -666,7 +730,7 @@ function mapSubAgentActivityCompleted(input: { turnId: string, threadId: string,
         state.subagentById.set(item.agentThreadId, actor)
         return [
             ...emitOrBufferByThread({ draft: { type: 'tool.call.started', turnId, payload: { toolCallId: item.id, toolName: 'spawnAgent' } }, threadId, state }),
-            ...emitOrBufferByThread({ draft: { type: 'tool.call.completed', turnId, payload: { toolCallId: item.id, toolName: 'spawnAgent', status: 'completed' } }, threadId, state }),
+            ...emitOrBufferByThread({ draft: { type: 'tool.call.completed', turnId, payload: { toolCallId: item.id, toolName: 'spawnAgent', status: 'completed', output: collabToolOutput(item.agentPath) } }, threadId, state }),
             {
                 type: 'subagent.started',
                 turnId,
@@ -680,7 +744,7 @@ function mapSubAgentActivityCompleted(input: { turnId: string, threadId: string,
     if (item.kind === 'interacted') {
         return [
             ...emitOrBufferByThread({ draft: { type: 'tool.call.started', turnId, payload: { toolCallId: item.id, toolName: 'sendInput' } }, threadId, state }),
-            ...emitOrBufferByThread({ draft: { type: 'tool.call.completed', turnId, payload: { toolCallId: item.id, toolName: 'sendInput', status: 'completed' } }, threadId, state }),
+            ...emitOrBufferByThread({ draft: { type: 'tool.call.completed', turnId, payload: { toolCallId: item.id, toolName: 'sendInput', status: 'completed', output: collabToolOutput(item.agentPath) } }, threadId, state }),
         ]
     }
 
@@ -703,6 +767,26 @@ function mapSubAgentActivityCompleted(input: { turnId: string, threadId: string,
     }]
 }
 
+function collabToolSummary(item: CodexCollabAgentToolCompletedItem, state: CodexEventMapperState): string {
+    const name = (threadId: string) => state.subagentByThreadId.get(threadId)?.name ?? state.subagentNameByThreadId.get(threadId) ?? threadId
+    const parentActorId = item.senderThreadId === state.mainThreadId ? mainActor.actorId : item.senderThreadId
+    const unreported = state.unreportedEndedSubagentsByParent.get(parentActorId)
+    const states = Object.entries(item.agentsStates).map(([threadId, agentState]) => {
+        unreported?.delete(threadId)
+        return `${name(threadId)}: ${agentState.status}`
+    })
+    if (states.length)
+        return states.join('\n')
+    if (item.receiverThreadIds.length)
+        return item.receiverThreadIds.map(name).join('\n')
+    state.unreportedEndedSubagentsByParent.delete(parentActorId)
+    return [...unreported ?? []].map(([threadId, status]) => `${name(threadId)}: ${status}`).join('\n') || item.tool
+}
+
+function collabToolOutput(text: string): AgentToolResult {
+    return { success: true, content: [{ type: 'text', text }] }
+}
+
 function mapChildTurnCompleted(input: {
     threadId: string
     turnId: string
@@ -853,10 +937,9 @@ function subagentPayloadRef(actor: CodexSubagentRef): Pick<CodexSubagentRef, 'ac
 
 function collabToolInput(item: CodexCollabAgentToolStartedItem): JsonObject {
     return toJsonObject({
-        senderThreadId: item.senderThreadId,
-        receiverThreadIds: item.receiverThreadIds.join(','),
-        prompt: item.prompt,
-        model: item.model,
+        prompt: optionalNonEmpty(item.prompt),
+        receiverThreadIds: optionalNonEmpty(item.receiverThreadIds.join(',')),
+        model: optionalNonEmpty(item.model),
         reasoningEffort: typeof item.reasoningEffort === 'string' ? item.reasoningEffort : undefined,
     })
 }

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.3.0",
-    sha: "8cc96eb90e17628946dfd6f7cc0bac298722a4c1",
-    buildTime: "2026-10-20T14:46:27.024Z",
+    version: "0.4.0-experimental.0",
+    sha: "91be1614dad53cf32cfbdceccd8c1209b21686e9",
+    buildTime: "2026-10-29T14:15:16.414Z",
 } as const

package/src/steps/projector.ts

@@ -152,14 +152,16 @@ export class DurableStepProjector {
                 : event.type.startsWith('reasoning.') ? 'reasoning' : undefined
         if (!kind || !('turnId' in event)) {
             const frames: WireEventBody[] = []
-            if (event.type === 'turn.ended' || event.type === 'session.ended') {
+            if (event.type === 'turn.ended' || event.type === 'session.ended' || event.type === 'subagent.ended') {
                 for (const row of this.db.query<{ body: string, last_event_id: string | null }, []>('select body, last_event_id from steps').all()) {
                     const step = JSON.parse(row.body) as StepDetailV1
                     if (step.sessionId !== event.sessionId || step.providerSessionId !== event.providerSessionId)
                         continue
                     if ((step.status !== 'running' && row.last_event_id !== event.eventId) || (event.type === 'turn.ended' && (step.turnId !== event.turnId || step.actor.actorId !== event.actor.actorId)))
                         continue
-                    step.status = event.type === 'turn.ended' && event.payload.status === 'failed' ? 'failed' : 'interrupted'
+                    if (event.type === 'subagent.ended' && step.actor.actorId !== event.actor.actorId)
+                        continue
+                    step.status = event.type !== 'session.ended' && event.payload.status === 'failed' ? 'failed' : 'interrupted'
                     step.incomplete = true
                     step.endedAt = event.timestamp
                     frames.push(...await this.finish(step))

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

@@ -86,10 +86,12 @@ export function createAgentSupervisorProviderFactory(
         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 previousProviderSessionId = input.fresh
+            ? undefined
+            : await options.bindingStore.load({
+                    sessionId: input.bootstrap.sessionId,
+                    provider: provider.id,
+                })
         const sessionInput = {
             sessionId: input.bootstrap.sessionId,
             cwd: input.bootstrap.agent.cwd,

package/src/supervisor/bootstrap-binder.ts

@@ -111,11 +111,27 @@ export function createBootstrapBinder(input: {
             }
             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.',
-                })
+                // Before any command the configuration has run nothing, so a session may still
+                // replace it; once a command arrived it is the configuration of what ran.
+                if (!persisted || request.envelope.body.initialCommand || binding.store.lastReceivedCommandSeq() !== 0) {
+                    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.',
+                    })
+                }
+                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 replacement configuration.',
+                        publicMessage: 'The sandbox configuration is not allowed.',
+                        cause,
+                    })
+                }
+                binding.store.reconfigure(request.envelope.body)
             }
         }
         const acceptedBinding = binding

package/src/supervisor/persistence/supervisor-store.ts

@@ -158,6 +158,37 @@ export class SupervisorStore {
         }
     }
 
+    /**
+     * Replaces the bootstrap body of a binding that has not received a command yet: nothing has
+     * run under the previous configuration, so the next agent runtime starts from this one.
+     */
+    reconfigure(body: SessionBootstrapBody): PersistedSupervisorBinding {
+        const transaction = this.database.transaction(() => {
+            const existing = this.bootstrapRow()
+            if (!existing)
+                throw new Error('Supervisor is not bound.')
+            const binding = bindingFromRow(existing)
+            if (binding.body.sessionId !== body.sessionId)
+                throw new Error('Supervisor is already bound to another session.')
+            if (body.initialCommand || this.lastReceivedCommandSeq() !== 0)
+                throw new Error('Supervisor configuration cannot change after a command.')
+            const bodyJson = canonicalJson(body)
+            const bodyHash = sha256CanonicalJson(body)
+            this.database.query(`
+                UPDATE bootstrap SET body_json = ?, body_hash = ?, updated_at = ? WHERE id = ?
+            `).run(bodyJson, bodyHash, new Date().toISOString(), bootstrapId)
+            this.database.query(`INSERT INTO metadata (key, value) VALUES ('provider_session_reset', ?)
+                ON CONFLICT(key) DO UPDATE SET value = excluded.value`).run(bodyHash)
+            return { ...binding, body, bodyHash }
+        })
+        try {
+            return transaction()
+        }
+        catch (cause) {
+            throw new SupervisorPersistenceError({ message: 'Failed to reconfigure supervisor bootstrap.', cause })
+        }
+    }
+
     acceptConnectionAttempt(input: {
         connectionGeneration: number
         runtimeConnectionAttemptId: string
@@ -217,6 +248,18 @@ export class SupervisorStore {
         })()
     }
 
+    /**
+     * A reconfiguration left the provider session bound before it on disk: the next agent runtime
+     * opens a new one, across restarts, until one is started from the replaced configuration.
+     */
+    providerSessionResetPending(): boolean {
+        return Boolean(this.database.query('SELECT 1 FROM metadata WHERE key = \'provider_session_reset\'').get())
+    }
+
+    clearProviderSessionReset(bodyHash: string): void {
+        this.database.query('DELETE FROM metadata WHERE key = \'provider_session_reset\' AND value = ?').run(bodyHash)
+    }
+
     /** Restore accepted defaults in application order; the bootstrap remains immutable. */
     appliedSettings(): AgentSettingsChange | undefined {
         const row = this.database.query<{ value: string }, []>('SELECT value FROM metadata WHERE key = \'applied_settings\'').get()

package/src/supervisor/provider-factory.ts

@@ -31,6 +31,8 @@ export interface SupervisorProviderFactory {
         signal: AbortSignal
         emit?: (body: WireEventBody) => void
         onFatal?: (error: unknown) => void
+        /** Open a new provider session rather than resume the one bound before a reconfiguration. */
+        fresh?: boolean
     }) => Promise<SupervisorAgentRuntime>
 }
 

package/src/supervisor/resident.ts

@@ -75,13 +75,14 @@ export async function createResidentSupervisor(input: {
                 credentials: activation.envelope.credentials,
                 gitToken: activation.envelope.gitToken,
                 logger: input.logger,
-                onFatal: error => requestShutdown(
-                    error instanceof SupervisorConfigurationError ? TERMINAL_ERROR_CODE : RECOVERABLE_ERROR_CODE,
-                ),
+                onFatal: (error) => {
+                    input.logger.error({ err: error }, 'Supervisor agent runtime failed')
+                    requestShutdown(error instanceof SupervisorConfigurationError ? TERMINAL_ERROR_CODE : RECOVERABLE_ERROR_CODE)
+                },
             })
         }
         else {
-            await handler.refreshSecrets({
+            await handler.rebind({
                 credentials: activation.envelope.credentials,
                 gitToken: activation.envelope.gitToken,
             })
@@ -105,7 +106,7 @@ export async function createResidentSupervisor(input: {
             binding: binding.status,
             profile: input.profile,
             agentCore: agentCoreProvenance(),
-            capabilities: { 'model-change': 'v1' },
+            capabilities: { 'model-change': 'v1', 'reconfigure-before-commands': 'v1' },
         }),
         getBoundSessionId: () => binding.status === 'bound' ? binding.sessionId : undefined,
         getLocalEventMax: () => binding.status === 'bound' ? binding.store.localEventMax() : 0,

package/src/supervisor/runtime-handler.ts

@@ -39,6 +39,7 @@ export class SupervisorRuntimeHandler implements RuntimeConnectionHandler {
     private processing = Promise.resolve()
     private eventAckFloor = 0
     private stopped = false
+    private agentBodyHash: string | undefined
     private readonly retainedFrames: string[] = []
     private readonly ephemeralFrames = new EphemeralFrameBuffer()
     private readonly heartbeatTimer: ReturnType<typeof setInterval>
@@ -164,6 +165,32 @@ export class SupervisorRuntimeHandler implements RuntimeConnectionHandler {
         await this.agent?.refreshSecrets?.(input)
     }
 
+    /**
+     * A bootstrap was accepted. When the binding took another configuration before any command,
+     * the agent started from the previous one is closed and the next starts from the new one;
+     * otherwise the agent keeps running with the bootstrap's secrets.
+     */
+    async rebind(input: {
+        credentials?: EphemeralCredentials
+        gitToken?: SessionBootstrapGitToken
+    }): Promise<void> {
+        if (!this.agentBodyHash || this.agentBodyHash === this.dependencies.store.binding()?.bodyHash) {
+            if (this.agent && this.agentBodyHash)
+                this.dependencies.store.clearProviderSessionReset(this.agentBodyHash)
+            await this.refreshSecrets(input)
+            return
+        }
+        this.dependencies.credentials = input.credentials
+        this.dependencies.gitToken = input.gitToken
+        await this.processing.catch(() => undefined)
+        const agent = await this.createAgentTask?.catch(() => undefined) ?? this.agent
+        this.agent = undefined
+        this.createAgentTask = undefined
+        this.agentBodyHash = undefined
+        if (agent)
+            await agent.close({ signal: new AbortController().signal }).catch(error => this.dependencies.logger.warn({ err: error }, 'agent runtime close failed'))
+    }
+
     async stop(reason: 'sigterm' | 'sigint' | 'fatal_error' = 'sigterm'): Promise<void> {
         if (this.stopped)
             return
@@ -206,14 +233,18 @@ export class SupervisorRuntimeHandler implements RuntimeConnectionHandler {
                 credentials: this.dependencies.credentials,
                 gitToken: this.dependencies.gitToken,
             }
+            const fresh = this.dependencies.store.providerSessionResetPending()
+            this.agentBodyHash = binding.bodyHash
             this.createAgentTask = this.dependencies.providerFactory.create({
                 bootstrap: { ...binding.body, agent: { ...binding.body.agent, ...this.dependencies.store.appliedSettings() } },
                 ...initialSecrets,
+                ...(fresh && { fresh }),
                 rpc: this.rpc,
                 signal: this.lifecycleController.signal,
                 emit: body => this.emit(body),
                 onFatal: error => this.dependencies.onFatal(error),
             }).then(async (agent) => {
+                this.dependencies.store.clearProviderSessionReset(binding.bodyHash)
                 await agent.ready?.()
                 const previousEventMax = this.dependencies.store.localEventMax()
                 this.dependencies.store.recoverCommandDispatches()