@meistrari/agent-core 0.3.1-experimental.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.1-experimental.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/provenance.gen.ts

@@ -1,6 +1,6 @@
 // Generated by scripts/write-provenance.ts. Do not edit by hand.
 export const generatedProvenance = {
-    version: "0.3.1-experimental.0",
-    sha: "0fe0d37e1a4d2965fb8da08b3160ac676f1229e1",
-    buildTime: "2026-10-26T12:38:01.769Z",
+    version: "0.4.0-experimental.0",
+    sha: "91be1614dad53cf32cfbdceccd8c1209b21686e9",
+    buildTime: "2026-10-29T14:15:16.414Z",
 } as const

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

@@ -82,7 +82,7 @@ export async function createResidentSupervisor(input: {
             })
         }
         else {
-            await handler.refreshSecrets({
+            await handler.rebind({
                 credentials: activation.envelope.credentials,
                 gitToken: activation.envelope.gitToken,
             })
@@ -106,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()