@meistrari/agent-core 0.2.0-experimental.6 → 0.2.0-experimental.7

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@meistrari/agent-core",
     "type": "module",
-    "version": "0.2.0-experimental.6",
+    "version": "0.2.0-experimental.7",
     "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/claude/claude-code-process.ts

@@ -25,7 +25,7 @@ export class ClaudeCodeProcess {
     private termination: Promise<void> | undefined
     private stderr = ''
 
-    constructor(private readonly exitTimeoutMs = CLAUDE_PROCESS_EXIT_TIMEOUT_MS) {}
+    constructor(private readonly exitTimeoutMs = CLAUDE_PROCESS_EXIT_TIMEOUT_MS, private readonly processLauncher?: string) {}
 
     /** The SDK `spawnClaudeCodeProcess` hook. A run spawns at most one process. */
     readonly spawn = (options: SpawnOptions): SpawnedProcess => {
@@ -33,10 +33,10 @@ export class ClaudeCodeProcess {
             throw new Error('Claude Code process already spawned for this run.')
         // `detached` makes the CLI a process-group leader. The forwarded signal aborts only after the
         // SDK's graceful stdin-EOF window, as for the SDK's own spawn.
-        const child = spawn(options.command, options.args, { cwd: options.cwd, env: options.env, signal: options.signal, stdio: ['pipe', 'pipe', 'pipe'], detached: true, windowsHide: true })
+        const child = spawn(this.processLauncher ?? options.command, this.processLauncher ? [options.command, ...options.args] : options.args, { cwd: options.cwd, env: options.env, signal: options.signal, stdio: ['pipe', 'pipe', 'pipe'], detached: true, windowsHide: true })
         this.child = child
         this.exit = new Promise((resolve) => {
-            child.once('exit', () => resolve())
+            child.once(this.processLauncher ? 'close' : 'exit', () => resolve())
             // A failed spawn emits `error` without `exit`; there is no process to wait for.
             child.once('error', () => {
                 if (child.pid === undefined)
@@ -70,15 +70,21 @@ export class ClaudeCodeProcess {
         const exit = this.exit
         if (!child || !exit || child.pid === undefined)
             return
-        if (await settlesWithin(exit, this.exitTimeoutMs))
+        // A fork/wait launcher can exit while its CLI still holds the stdio pipes.
+        // For launchers, await close and clean the group even if the wrapper already exited.
+        if (await settlesWithin(exit, this.exitTimeoutMs) && !this.processLauncher)
             return
         try {
             process.kill(-child.pid, 'SIGKILL')
         }
-        catch {
+        catch (error) {
+            if (this.processLauncher && process.platform !== 'win32' && (error as NodeJS.ErrnoException).code !== 'ESRCH')
+                throw error
             child.kill('SIGKILL')
         }
-        await settlesWithin(exit, killedExitWaitMs)
+        const closed = await settlesWithin(exit, killedExitWaitMs)
+        if (this.processLauncher && !closed)
+            throw new Error('Claude launcher process group did not close after SIGKILL.')
     }
 }
 

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

@@ -71,6 +71,14 @@ export interface ClaudeProviderConfig {
     desktop?: ClaudeDesktopConfig | null
     tools?: readonly AgentTool[]
     executable?: string
+    /**
+     * Trusted launcher invoked as <CLI executable> <CLI args>; owns any privilege drop.
+     * Preserve stdio and the process group: exec the CLI or keep children in that group.
+     * On Windows, the launcher must exec the CLI in place (group signals are unavailable).
+     */
+    processLauncher?: string
+    /** Private provider stores; defaults to the CLI transcript directory when omitted. */
+    runtimeStateRoot?: string
     environment?: Record<string, string | undefined>
     nativeToolActorBridge?: ClaudeNativeToolActorBridge
     startupDeadlineMs?: number
@@ -139,6 +147,8 @@ export class ClaudeProvider implements AgentProvider<'claude'> {
     private readonly desktop: ClaudeDesktopConfig | null
     private readonly tools: readonly AgentTool[]
     private readonly executable: string | undefined
+    private readonly processLauncher: string | undefined
+    private readonly runtimeStateRoot: string | undefined
     private readonly environment: Record<string, string | undefined>
     private readonly nativeToolActorBridge: ClaudeNativeToolActorBridge | undefined
     private readonly startupDeadlineMs: number
@@ -156,6 +166,8 @@ export class ClaudeProvider implements AgentProvider<'claude'> {
         this.desktop = config.desktop ?? null
         this.tools = config.tools ?? []
         this.executable = config.executable
+        this.processLauncher = config.processLauncher
+        this.runtimeStateRoot = config.runtimeStateRoot
         this.environment = config.environment ?? {}
         this.nativeToolActorBridge = config.nativeToolActorBridge
         this.startupDeadlineMs = config.startupDeadlineMs ?? CLAUDE_STARTUP_DEADLINE_MS
@@ -202,10 +214,10 @@ export class ClaudeProvider implements AgentProvider<'claude'> {
         const runtime = createClaudeToolRuntimeRef({ turnId: () => state.currentTurnId })
         // The transcript location is a pre-input fact; session-local stores live beside it.
         const transcriptPath = join(configDir, 'projects', encodeClaudeProjectPath(input.cwd), `${expectedSessionId}.jsonl`)
-        const steeredNotifications = ClaudeSteeredNotificationStore.open({ sessionId: input.sessionId, transcriptPath })
+        const steeredNotifications = ClaudeSteeredNotificationStore.open({ sessionId: input.sessionId, transcriptPath, rootDir: this.runtimeStateRoot })
         const resources = await this.openRunResources({ input, expectedSessionId, signal: abortController.signal })
         const { nativeToolActorRun, workspaceSkills, selectedRepositoryInstructions, browserAuthBroker, browserTurnMetadata } = resources
-        const claudeProcess = new ClaudeCodeProcess()
+        const claudeProcess = new ClaudeCodeProcess(undefined, this.processLauncher)
         const declaredSubscriptionType = this.auth ? fetchFreeSubscriptionType(this.auth.knownSubscriptionType()) : undefined
         const runtimeMcpServers = toClaudeMcpServers({
             tools,
@@ -302,7 +314,7 @@ export class ClaudeProvider implements AgentProvider<'claude'> {
             const [userInputRequests, initialization, , sessionContext] = await Promise.all([
                 UserInputRequestStore.open({
                     sessionId: metadata.sessionId,
-                    rootDir: userInputRequestStoreRootFromTranscriptPath(metadata.transcriptPath),
+                    rootDir: this.runtimeStateRoot ?? userInputRequestStoreRootFromTranscriptPath(metadata.transcriptPath),
                 }),
                 awaitClaudeInitialization({ query, signal: abortController.signal, deadlineMs: this.startupDeadlineMs }),
                 this.auth?.acquire({ signal: abortController.signal }),
@@ -314,8 +326,12 @@ export class ClaudeProvider implements AgentProvider<'claude'> {
             if (this.auth && declaredSubscriptionType !== undefined && declaredSubscriptionType !== fetchFreeSubscriptionType(this.auth.knownSubscriptionType()) && !params.respawnedForSubscriptionType) {
                 query.close()
                 inputQueue.close()
-                await claudeProcess.terminate()
-                await closeRunResources(resources)
+                try {
+                    await claudeProcess.terminate()
+                }
+                finally {
+                    await closeRunResources(resources)
+                }
                 return await this.openRun({ ...params, respawnedForSubscriptionType: true })
             }
 
@@ -372,8 +388,12 @@ export class ClaudeProvider implements AgentProvider<'claude'> {
             query.close()
             inputQueue.close()
             // A failed open (for example a missed initialize deadline) must not leave its CLI behind.
-            await claudeProcess.terminate()
-            await closeRunResources(resources)
+            try {
+                await claudeProcess.terminate()
+            }
+            finally {
+                await closeRunResources(resources)
+            }
             throw error
         }
     }

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

@@ -879,18 +879,31 @@ export class ClaudeRun implements AgentRun {
             cause: error,
         }))
         this.ended = this.endAfterProcessExit(reason, error)
+        // Autonomous stream failure may finish without a stop caller; keep rejection observed.
+        void this.ended.catch(() => undefined)
     }
 
-    // session.ended means the CLI is gone: the terminal events wait for its exit (bounded by
+    // A successful session.ended means the CLI is gone: the terminal events wait for its exit (bounded by
     // CLAUDE_PROCESS_EXIT_TIMEOUT_MS, then a process-group kill). close() is idempotent and sends
     // the stdin EOF the CLI exits on.
     private async endAfterProcessExit(reason: 'completed' | 'stopped' | 'interrupted' | 'failed', error: AgentError | undefined): Promise<void> {
         this.closeQuery()
-        await this.process.terminate()
-        this.events.push({ type: 'session.ended', payload: error ? { reason, error } : { reason } })
-        this.events.push({ type: 'session.state.changed', payload: { state: reason === 'failed' ? 'failed' : 'stopped' } })
-        this.events.end()
-        void this.onFinished().catch(() => undefined)
+        try {
+            await this.process.terminate()
+            this.events.push({ type: 'session.ended', payload: error ? { reason, error } : { reason } })
+            this.events.push({ type: 'session.state.changed', payload: { state: reason === 'failed' ? 'failed' : 'stopped' } })
+        }
+        catch (cause) {
+            const shutdownError = { ...serializeAgentError(cause), code: 'agents.provider-shutdown-failed' }
+            this.events.push({ type: 'error', payload: { message: 'Claude CLI shutdown could not be confirmed.', fatal: true, source: 'runtime', error: shutdownError } })
+            this.events.push({ type: 'session.ended', payload: { reason: 'failed', error: shutdownError } })
+            this.events.push({ type: 'session.state.changed', payload: { state: 'failed' } })
+            throw cause
+        }
+        finally {
+            this.events.end()
+            await this.onFinished().catch(() => undefined)
+        }
     }
 
     // Reports the request's one result; later calls return the reported one. The caller decides

package/src/agents/claude/claude-steered-notifications.ts

@@ -48,9 +48,9 @@ export interface SteeredNotificationDelivery {
 export class ClaudeSteeredNotificationStore {
     private constructor(private readonly filePath: string, private file: StoreFile) {}
 
-    static open(input: { sessionId: string, transcriptPath: string }): ClaudeSteeredNotificationStore {
+    static open(input: { sessionId: string, transcriptPath: string, rootDir?: string }): ClaudeSteeredNotificationStore {
         const filePath = join(
-            dirname(input.transcriptPath),
+            input.rootDir ?? dirname(input.transcriptPath),
             storeDirectoryName,
             Buffer.from(input.sessionId, 'utf8').toString('base64url'),
             storeFileName,

package/src/agents/codex/codex-json-rpc-client.ts

@@ -59,7 +59,9 @@ export class CodexJsonRpcClient {
     readonly child: ChildProcessWithoutNullStreams
     private nextId = 0
     private stopped = false
+    private shutdown: Promise<void> | undefined
     private readonly closed: Promise<void>
+    private readonly processGroup: boolean
     private readonly pending = new Map<string, {
         method: ClientRequestMethod
         resolve: (value: unknown) => void
@@ -70,6 +72,7 @@ export class CodexJsonRpcClient {
         executable: string,
         options: {
             cwd: string
+            processLauncher?: string
             environment?: Record<string, string | undefined>
             configOverrides?: readonly string[]
             onMessage: (message: CodexJsonRpcMessage) => void
@@ -78,10 +81,13 @@ export class CodexJsonRpcClient {
             maxLineBytes?: number
         },
     ) {
-        this.child = spawn(executable, ['app-server', '--listen', 'stdio://', ...(options.configOverrides ?? []).flatMap(value => ['-c', value])], {
+        this.processGroup = options.processLauncher !== undefined && process.platform !== 'win32'
+        const args = ['app-server', '--listen', 'stdio://', ...(options.configOverrides ?? []).flatMap(value => ['-c', value])]
+        this.child = spawn(options.processLauncher ?? executable, options.processLauncher ? [executable, ...args] : args, {
             cwd: options.cwd,
             env: options.environment,
             stdio: 'pipe',
+            detached: this.processGroup,
         })
         this.closed = new Promise(resolve => this.child.once('close', () => resolve()))
 
@@ -229,9 +235,16 @@ export class CodexJsonRpcClient {
     }
 
     async closeInputAndStop(): Promise<void> {
+        this.shutdown ??= this.drainAndStop()
+        await this.shutdown
+    }
+
+    private async drainAndStop(): Promise<void> {
         if (this.stopped) {
             if (!await waitForClosed(this.closed, PROCESS_SHUTDOWN_GRACE_MS))
-                await terminateChild(this.child, this.closed)
+                await terminateChild(this.child, this.closed, this.processGroup)
+            if (this.processGroup)
+                signalProcessGroup(this.child, 'SIGKILL')
             return
         }
         this.stopped = true
@@ -242,9 +255,10 @@ export class CodexJsonRpcClient {
         // EOF/drain and process exit share one grace window. Never wait separately for a
         // buffered stdin write: a child that stops reading must still reach signal escalation.
         this.child.stdin.end()
-        if (await waitForClosed(this.closed, PROCESS_SHUTDOWN_GRACE_MS))
-            return
-        await terminateChild(this.child, this.closed)
+        if (!await waitForClosed(this.closed, PROCESS_SHUTDOWN_GRACE_MS))
+            await terminateChild(this.child, this.closed, this.processGroup)
+        if (this.processGroup)
+            signalProcessGroup(this.child, 'SIGKILL')
     }
 
     async stop(): Promise<void> {
@@ -288,7 +302,17 @@ export class CodexJsonRpcClient {
     }
 }
 
-async function terminateChild(child: ChildProcessWithoutNullStreams, closed: Promise<void>): Promise<void> {
+async function terminateChild(child: ChildProcessWithoutNullStreams, closed: Promise<void>, processGroup: boolean): Promise<void> {
+    if (processGroup) {
+        // The launcher may already be gone while the CLI retains its pipes. Signal the
+        // retained group regardless of the wrapper's exitCode, and bound the close wait.
+        for (const signal of ['SIGINT', 'SIGTERM', 'SIGKILL'] as const) {
+            signalProcessGroup(child, signal)
+            if (await waitForClosed(closed, signal === 'SIGKILL' ? 1_000 : PROCESS_SHUTDOWN_GRACE_MS))
+                return
+        }
+        throw new Error('Codex launcher process group did not close after SIGKILL.')
+    }
     if (child.exitCode !== null || child.signalCode !== null) {
         await closed
         return
@@ -308,6 +332,18 @@ async function terminateChild(child: ChildProcessWithoutNullStreams, closed: Pro
     await closed
 }
 
+function signalProcessGroup(child: ChildProcessWithoutNullStreams, signal: NodeJS.Signals): void {
+    if (child.pid === undefined)
+        return
+    try {
+        process.kill(-child.pid, signal)
+    }
+    catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'ESRCH')
+            throw error
+    }
+}
+
 async function waitForClosed(closed: Promise<void>, timeoutMs: number): Promise<boolean> {
     return await new Promise<boolean>((resolve) => {
         const timer = setTimeout(() => resolve(false), timeoutMs)

package/src/agents/codex/codex-provider.ts

@@ -54,6 +54,14 @@ export interface CodexProviderConfig {
     auth: CodexAuthProvider | CodexAuthentication
     tools?: readonly AgentTool[]
     executable?: string
+    /**
+     * Trusted launcher invoked as <CLI executable> <CLI args>; owns any privilege drop.
+     * Preserve stdio and the process group: exec the CLI or keep children in that group.
+     * On Windows, the launcher must exec the CLI in place (group signals are unavailable).
+     */
+    processLauncher?: string
+    /** Private provider stores; defaults to the CLI transcript directory when omitted. */
+    runtimeStateRoot?: string
     environment?: Record<string, string | undefined>
     onStartupStage?: (fact: CodexStartupStageFact) => void
     instructions?: InstructionComposer
@@ -111,6 +119,8 @@ export class CodexProvider implements AgentProvider<'codex'> {
     private readonly tools: readonly AgentTool[]
     private readonly executable: string
     private readonly environment: Record<string, string | undefined>
+    private readonly processLauncher: string | undefined
+    private readonly runtimeStateRoot: string | undefined
     private readonly auth: CodexAuthentication
     /** The validated endpoint of an API key login that names one. */
     private readonly apiKeyEndpoint: string | undefined
@@ -130,6 +140,8 @@ export class CodexProvider implements AgentProvider<'codex'> {
         this.tools = config.tools ?? []
         this.executable = config.executable ?? 'codex'
         this.environment = config.environment ?? {}
+        this.processLauncher = config.processLauncher
+        this.runtimeStateRoot = config.runtimeStateRoot
         this.onStartupStage = config.onStartupStage
         this.instructions = config.instructions ?? emptyInstructionComposer
         this.sessionContext = config.sessionContext
@@ -458,6 +470,7 @@ export class CodexProvider implements AgentProvider<'codex'> {
 
         try {
             client = new CodexJsonRpcClient(this.executable, {
+                processLauncher: this.processLauncher,
                 cwd,
                 environment: holder.browserAuthBroker
                     ? { ...this.environment, CODING_AGENT_BROWSER_AUTH_SOCKET: holder.browserAuthBroker.socketPath }
@@ -637,7 +650,7 @@ export class CodexProvider implements AgentProvider<'codex'> {
             }),
             UserInputRequestStore.open({
                 sessionId: metadata.sessionId,
-                rootDir: userInputRequestStoreRootFromTranscriptPath(metadata.transcriptPath),
+                rootDir: this.runtimeStateRoot ?? userInputRequestStoreRootFromTranscriptPath(metadata.transcriptPath),
             }),
             pendingSessionContext({
                 compose: this.sessionContext,

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

@@ -21,6 +21,7 @@ import type { CodexEventMapperState } from './codex-event-mapper'
 import type { CodexJsonRpcClient } from './codex-json-rpc-client'
 import type { ClientRequestResponsesByMethod, CodexUserInput } from './codex-protocol'
 import { serializeAgentNotificationToolOutput } from '../../protocol'
+import { serializeAgentError } from '../agent-error-serializer'
 import { AgentEventStream } from '../agent-event-stream'
 import { AgentDeliveryUnknownError, AgentNotAcceptedError, AgentPromptDeferredError, AgentRunStateError } from '../agent-runtime-error'
 import { sessionSettingsChangedEvent } from '../agent-session-events'
@@ -146,7 +147,7 @@ export class CodexRun implements AgentRun {
             sessionId: this.metadata.sessionId,
             providerSessionId: this.metadata.providerSessionId,
             reason: 'aborted',
-        }))
+        }).catch(() => undefined))
     }
 
     pushEvent(draft: AgentEventDraft): void {
@@ -639,8 +640,20 @@ export class CodexRun implements AgentRun {
         const revocation = new Promise<void>((resolve) => {
             resolve(this.onStop())
         })
-        void Promise.all([this.client.stop(), revocation])
-            .then(finalize)
+        void Promise.allSettled([this.client.stop(), revocation])
+            .then((outcomes) => {
+                const failure = outcomes.find(outcome => outcome.status === 'rejected')
+                if (!failure) {
+                    finalize()
+                    return
+                }
+                const error = { ...serializeAgentError(failure.reason), code: 'agents.provider-shutdown-failed' }
+                this.events.push({ type: 'error', payload: { message: 'Codex run shutdown could not be confirmed.', fatal: true, source: 'runtime', error } })
+                this.events.push({ type: 'session.ended', payload: { reason: 'failed', error } })
+                this.events.push({ type: 'session.state.changed', payload: { state: 'failed' } })
+                this.events.end()
+                throw failure.reason
+            })
             .then(stopping.resolve, stopping.reject)
     }
 

package/src/agents/input-attachment-preparation.ts

@@ -1,5 +1,5 @@
-import type { Buffer } from 'node:buffer'
 import type { MaterializedAgentInputAttachment } from './materialized-input-attachment'
+import { Buffer } from 'node:buffer'
 import { readFile } from 'node:fs/promises'
 import { AgentInputAttachmentPreparationFailure } from './input-attachment.errors'
 
@@ -8,7 +8,9 @@ type NativeImageMimeType = 'image/jpeg' | 'image/png' | 'image/gif' | 'image/web
 export async function readAttachmentBytes(attachment: MaterializedAgentInputAttachment, signal: AbortSignal): Promise<Buffer> {
     signal.throwIfAborted()
     try {
-        const bytes = await readFile(attachment.localPath, { signal })
+        const bytes = attachment.readBytes
+            ? Buffer.from(await attachment.readBytes(signal))
+            : await readFile(attachment.localPath, { signal })
         signal.throwIfAborted()
         return bytes
     }

package/src/agents/materialized-input-attachment.ts

@@ -6,6 +6,8 @@ export type MaterializedAgentInputAttachment = Readonly<{
     byteSize: number
     sha256: string
     localPath: string
+    /** Read as the file owner when the provider uses a different process identity. */
+    readBytes?: (signal: AbortSignal) => Promise<Uint8Array>
 }>
 
 export type AgentInputAttachmentProjection = Readonly<{

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.2.0-experimental.6",
-    sha: "1b8f8c0c8cc698990c1b0ed9e03c417216bc0316",
-    buildTime: "2026-10-02T20:59:57.760Z",
+    version: "0.2.0-experimental.7",
+    sha: "c27666274441cd3c81ffc5934ca115dffbe234ee",
+    buildTime: "2026-10-14T20:20:44.640Z",
 } as const