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

package/src/agents/agent-operation.ts

@@ -8,4 +8,12 @@ export interface AgentOperationOptions {
     signal?: AbortSignal
     inputAttachmentPreparation?: AgentInputAttachmentPreparation
     senderContext?: AgentSenderContext
+    // Trusted product-rendered context for a person-authored prompt, replacing the default author block.
+    authorContext?: string
+}
+
+export type AgentPromptOperationOptions = AgentOperationOptions & {
+    // `in-order` (the default) defers a `next` prompt while a turn is active. `bypass` is for a
+    // steer the application delivers ahead of queued work; it requires an active turn.
+    submissionOrder?: 'in-order' | 'bypass'
 }

package/src/agents/agent-provider.ts

@@ -9,6 +9,9 @@ import type { AgentRun } from './agent-run'
 
 interface AgentSessionConfigInput {
     sessionId: string
+    sessionWebUrl?: string
+    // An explicit per-session prompt overrides the provider composer; omission preserves its default.
+    instructions?: string
     cwd: string
     workspaceRepositoryRoots: readonly string[]
     reasoningEffort?: AgentReasoningEffort

package/src/agents/agent-run.ts

@@ -1,17 +1,26 @@
 import type {
+    AgentContextCompactionRequestResult,
     AgentEvent,
+    AgentNotifyCommand,
     AgentRunMetadata,
+    CompactContextAgentCommand,
     InterruptAgentCommand,
     RespondUserInputAgentCommand,
     SendPromptCommand,
     StopAgentCommand,
 } from '../protocol'
-import type { AgentOperationOptions } from './agent-operation'
+import type { AgentOperationOptions, AgentPromptOperationOptions } from './agent-operation'
 
 // Whether respond-user-input submitted provider input. `already_delivered` is the durable-store
 // idempotence fact for a redriven duplicate, not a provider prompt-acceptance receipt.
 export type AgentUserInputSubmission = 'submitted' | 'already_delivered'
 
+export interface AgentNotificationAcceptance {
+    kind: 'turn'
+    turnId: string
+    placement: 'started' | 'steered'
+}
+
 // Positive prompt-submission receipt. `turn` carries the provider's real turn identity (Codex: nested
 // `turn.id` from turn/start, flat `turnId` from turn/steer). `submitted` is the stream-submission arm
 // for providers whose input boundary carries no turn identity.
@@ -25,7 +34,10 @@ export interface AgentRun {
     prepareWorkspace: (options?: AgentOperationOptions) => Promise<void>
     // Providers without root registration accept the root without provider I/O.
     addWorkspaceRepositoryRoot: (root: string, options?: AgentOperationOptions) => Promise<void>
-    sendPrompt: (command: SendPromptCommand, options?: AgentOperationOptions) => Promise<AgentPromptAcceptance>
+    sendPrompt: (command: SendPromptCommand, options?: AgentPromptOperationOptions) => Promise<AgentPromptAcceptance>
+    // Optional capabilities: the Claude and Codex runs implement both; other runs may omit them.
+    notify?: (command: AgentNotifyCommand, options?: AgentOperationOptions) => Promise<AgentNotificationAcceptance>
+    compactContext?: (command: CompactContextAgentCommand, options?: AgentOperationOptions) => Promise<AgentContextCompactionRequestResult>
     respondUserInput: (command: RespondUserInputAgentCommand, options?: AgentOperationOptions) => Promise<AgentUserInputSubmission>
     interrupt: (command: InterruptAgentCommand, options?: AgentOperationOptions) => Promise<void>
     stop: (command: StopAgentCommand, options?: AgentOperationOptions) => Promise<void>

package/src/agents/agent-runtime-error.ts

@@ -98,6 +98,23 @@ export class AgentProviderMetadataError extends AgentProviderRuntimeError {
     }
 }
 
+/**
+ * A provider that violated its protocol or omitted required metadata fails the same way on every
+ * attempt: a sandbox keeps its image-baked agent code for its lifetime, so redriving the same input
+ * cannot heal it. Walks the cause chain, so a delivery-unknown outcome caused by one qualifies.
+ */
+export function isDeterministicProviderFailure(error: unknown): boolean {
+    const seen = new Set<unknown>()
+    let current: unknown = error
+    while (current instanceof Error && !seen.has(current)) {
+        if (current instanceof AgentProviderProtocolError || current instanceof AgentProviderMetadataError)
+            return true
+        seen.add(current)
+        current = current.cause
+    }
+    return false
+}
+
 export class AgentRuntimeValidationError extends ValidationError {
     constructor(input: RuntimeValidationErrorInput) {
         const { code = 'agents.validation-failed', ...rest } = input
@@ -136,6 +153,17 @@ export class AgentRunStateError extends AgentRuntimeValidationError {
     }
 }
 
+export class AgentNotificationStoreError extends InfrastructureError {
+    constructor(input: Omit<RuntimeInfrastructureErrorInput, 'code'>) {
+        super({
+            code: 'agents.notification-store-error',
+            publicMessage: 'Agent notification delivery state is unavailable.',
+            retryable: false,
+            ...input,
+        })
+    }
+}
+
 export class AgentUserInputRequestStoreError extends InfrastructureError {
     constructor(input: Omit<RuntimeInfrastructureErrorInput, 'code'>) {
         super({

package/src/agents/agent-session-events.ts

@@ -1,8 +1,10 @@
 import type { AgentReasoningEffort, AgentToolDefinition, SessionConfiguredAgentEvent } from '../protocol'
 import type { AgentEventDraft } from './agent-event-stream'
+import { currentTurnUnavailableReasonMaxLength } from '../protocol'
 
 type SessionConfiguredPayload = SessionConfiguredAgentEvent['payload']
 type SessionConfiguredEventDraft = Extract<AgentEventDraft, { type: 'session.configured' }>
+type SessionSettingsChangedEventDraft = Extract<AgentEventDraft, { type: 'session.settings.changed' }>
 
 export type SessionConfiguredEventInput = Pick<SessionConfiguredPayload, 'model' | 'cwd'> & {
     reasoningEffort?: AgentReasoningEffort
@@ -27,6 +29,37 @@ export function sessionConfiguredEvent(input: SessionConfiguredEventInput): Sess
     }
 }
 
+// Where the provider applied a settings change: `current_turn` when the turn that handles the prompt
+// runs on it (a switched running turn or the turn the prompt started); `next_turn` only when a steer
+// could not switch the running turn. Only that miss carries the provider's reason, when it gave one.
+export type AgentSettingsPlacement
+    = | { appliesFrom: 'current_turn' }
+        | { appliesFrom: 'next_turn', currentTurnUnavailableReason?: string }
+
+export type SessionSettingsChangedEventInput = AgentSettingsPlacement & {
+    model: string
+    reasoningEffort?: AgentReasoningEffort
+    commandId: string
+    turnId?: string
+}
+
+// Emitted by a provider run once a prompt's settings change is applied and its input accepted.
+export function sessionSettingsChangedEvent(input: SessionSettingsChangedEventInput): SessionSettingsChangedEventDraft {
+    return {
+        type: 'session.settings.changed',
+        payload: {
+            model: input.model,
+            reasoningEffort: input.reasoningEffort,
+            commandId: input.commandId,
+            turnId: input.turnId,
+            appliesFrom: input.appliesFrom,
+            ...(input.appliesFrom === 'next_turn' && input.currentTurnUnavailableReason !== undefined
+                ? { currentTurnUnavailableReason: input.currentTurnUnavailableReason.slice(0, currentTurnUnavailableReasonMaxLength) }
+                : {}),
+        },
+    }
+}
+
 export function redactedEnvironment(environment: Record<string, string | undefined>): SessionConfiguredPayload['environment'] {
     return Object.fromEntries(Object.keys(environment).sort().map(key => [key, '[REDACTED]']))
 }

package/src/agents/agent-tool-runner.ts

@@ -1,16 +1,16 @@
 import type { AppError } from '../errors'
-import type { AgentToolResult, JsonValue } from '../protocol'
-import type { AgentTool, AgentToolActor, AgentToolContext } from './agent-tool'
+import type { JsonValue } from '../protocol'
+import type { AgentTool, AgentToolActor, AgentToolContext, AgentToolExecutionResult } from './agent-tool'
 import { isAppError } from '../errors'
 import { AgentOperationAbortedError, AgentToolValidationError } from './agent-runtime-error'
-import { agentToolActorDenialMessage, agentToolAllowsActor } from './agent-tool'
+import { agentToolActorDenialMessage, agentToolAllowsActor, agentToolExecutionResultSchema } from './agent-tool'
 
 export async function runAgentTool(input: {
     tool: AgentTool
     actor: AgentToolActor
     rawInput: JsonValue
     context: AgentToolContext
-}): Promise<AgentToolResult> {
+}): Promise<AgentToolExecutionResult> {
     if (!agentToolAllowsActor(input.tool, input.actor))
         throw new AgentToolValidationError({ message: agentToolActorDenialMessage(input.tool) })
 
@@ -30,7 +30,7 @@ export async function runAgentTool(input: {
         abort()
 
     try {
-        const result = await Promise.race([
+        const result: unknown = await Promise.race([
             input.tool.execute({
                 input: parsed.data,
                 context: {
@@ -41,8 +41,7 @@ export async function runAgentTool(input: {
             waitForAbort(abortController.signal, input.tool.name, input.tool.timeoutMs),
         ])
 
-        validateToolResult(result)
-        return result
+        return parseToolResult(result)
     }
     catch (error) {
         if (!isAppError(error))
@@ -68,7 +67,7 @@ async function waitForAbort(signal: AbortSignal, toolName: string, timeoutMs: nu
     })
 }
 
-function appErrorToolResult(error: AppError): AgentToolResult {
+function appErrorToolResult(error: AppError): AgentToolExecutionResult {
     const serializedDetails = error.details === undefined ? '' : `\n\nDetails:\n${JSON.stringify(error.details, null, 2)}`
     return {
         success: false,
@@ -76,8 +75,10 @@ function appErrorToolResult(error: AppError): AgentToolResult {
     }
 }
 
-function validateToolResult(result: AgentToolResult): void {
-    if (typeof result.success !== 'boolean' || !Array.isArray(result.content)) {
+function parseToolResult(result: unknown): AgentToolExecutionResult {
+    const parsed = agentToolExecutionResultSchema.safeParse(result)
+    if (!parsed.success)
         throw new AgentToolValidationError({ message: 'Tool result must include success and content array.' })
-    }
+
+    return parsed.data
 }

package/src/agents/agent-tool.ts

@@ -1,7 +1,7 @@
 import type { ZodRawShape } from 'zod'
-import type { AgentProviderId, AgentToolDefinition, AgentToolResult, AgentUserInputQuestion } from '../protocol'
+import type { AgentProviderId, AgentToolDefinition, AgentUserInputQuestion } from '../protocol'
 import { z } from 'zod'
-import { jsonObjectSchema } from '../protocol'
+import { agentToolImageContentSchema, agentToolResultSchema, agentToolTextContentSchema, jsonObjectSchema } from '../protocol'
 import { AgentToolValidationError } from './agent-runtime-error'
 
 export interface AgentToolContext {
@@ -23,6 +23,14 @@ export interface AgentToolExecuteInput<TShape extends ZodRawShape = ZodRawShape>
 export type AgentToolActor = 'main' | 'subagent'
 export type AgentToolActorScope = 'all' | 'main'
 
+export const agentToolExecutionResultSchema = agentToolResultSchema.omit({ structuredContent: true, reportedSuccess: true }).extend({
+    content: z.array(z.discriminatedUnion('type', [
+        agentToolTextContentSchema.strict(),
+        agentToolImageContentSchema.strict(),
+    ])),
+}).strict()
+export type AgentToolExecutionResult = z.infer<typeof agentToolExecutionResultSchema>
+
 export interface AgentTool {
     readonly name: string
     readonly description: string
@@ -30,7 +38,7 @@ export interface AgentTool {
     readonly inputShape: ZodRawShape
     readonly inputSchema: z.ZodObject<ZodRawShape>
     readonly timeoutMs: number
-    execute: (input: AgentToolExecuteInput) => Promise<AgentToolResult>
+    execute: (input: AgentToolExecuteInput) => Promise<AgentToolExecutionResult>
     definition: () => AgentToolDefinition
 }
 
@@ -40,7 +48,7 @@ export interface CreateAgentToolInput<TShape extends ZodRawShape> {
     actorScope?: AgentToolActorScope
     inputSchema: z.ZodObject<TShape>
     timeoutMs?: number
-    execute: (input: AgentToolExecuteInput<TShape>) => Promise<AgentToolResult>
+    execute: (input: AgentToolExecuteInput<TShape>) => Promise<AgentToolExecutionResult>
 }
 
 const DEFAULT_TOOL_TIMEOUT_MS = 60_000

package/src/agents/author-context.ts

@@ -4,7 +4,7 @@ import type { AgentSenderContext } from './agent-operation'
 const OPEN_TAG = '<coding-agent-context>'
 const CLOSE_TAG = '</coding-agent-context>'
 
-const AUTHOR_CONTEXT_PATTERN = /^<coding-agent-context>[\s\S]*?<\/coding-agent-context>\n*/
+const AUTHOR_CONTEXT_PATTERN = /^<coding-agent-context(?: [^>]*)?>[\s\S]*?<\/coding-agent-context>\n*/
 const slackMentionPattern = /^<@([\w-]+)(?:\|[^>]*)?>$/u
 
 export function renderAuthorContext(author: AgentAuthor, senderContext: AgentSenderContext = { kind: 'application' }): string {

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

@@ -0,0 +1,40 @@
+import type { AgentError } from '../../protocol'
+
+export type ClaudeAuthFailureReason = 'claude_auth_acquisition_failed' | 'claude_auth_refresh_failed'
+
+/** A credential failure that needs outside action or is terminal; retrying the request cannot fix it. */
+export type ClaudeAuthFailure = Readonly<{
+    reason: ClaudeAuthFailureReason
+    error: AgentError
+}>
+
+export type ClaudeAuthFailureSource = Readonly<{
+    /** Returns the unsubscribe function. */
+    subscribe: (listener: (failure: ClaudeAuthFailure) => void) => () => void
+}>
+
+/**
+ * How Claude Code reaches the Messages API. In the sandbox, `baseUrl` is the supervisor's loopback
+ * provider proxy and `oauthToken` is a fixed placeholder that the proxy exchanges for the
+ * server-issued access token, so no real credential enters the Claude process environment.
+ * `failures` reports credential failures that end a run with a typed reason once it has input.
+ */
+export type ClaudeProviderAuth = Readonly<{
+    baseUrl: string
+    oauthToken: string
+    /**
+     * Makes a credential available before an opened run is published, as Codex acquires auth per
+     * open. Rejects with `AgentNotAcceptedError` when the credential needs external action, so the
+     * open fails instead of publishing a run whose first model request cannot authenticate.
+     */
+    acquire: (input: { signal: AbortSignal }) => Promise<void>
+    /**
+     * The subscription type (for example `max`) of the account the run's credential belongs to, as
+     * far as it is known without waiting: the installed credential's, or before the first
+     * acquisition the control plane's declared type; otherwise `null`. Read when a run spawns
+     * Claude Code, whose environment is then fixed, and again after `acquire` to detect a spawn
+     * that declared the wrong type.
+     */
+    knownSubscriptionType: () => string | null
+    failures: ClaudeAuthFailureSource
+}>

package/src/agents/claude/claude-browser-turn-metadata.ts

@@ -0,0 +1,70 @@
+import type { Options } from '@anthropic-ai/claude-agent-sdk'
+import { randomUUID } from 'node:crypto'
+import { mkdtemp, rename, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+// Named in the image's Claude node_repl definition; its relay reads the file before each tools/call.
+export const turnMetadataPathVariable = 'CODING_AGENT_TURN_METADATA_PATH'
+
+/**
+ * The Codex-shaped turn metadata that Browser Use's first-party runtime requires on every node_repl
+ * call (`session_id`, `turn_id`). Codex's MCP client sends it itself; for Claude, the run records
+ * its own provider session id and current turn id here, and the image's relay adds them to the
+ * call. The directory is private to the run and removed with it.
+ */
+export class ClaudeBrowserTurnMetadata {
+    private constructor(private readonly directory: string, readonly path: string) {}
+
+    static async open(): Promise<ClaudeBrowserTurnMetadata> {
+        // mkdtemp creates the directory with mode 0700.
+        const directory = await mkdtemp(join(tmpdir(), 'claude-turn-metadata-'))
+        return new ClaudeBrowserTurnMetadata(directory, join(directory, 'turn-metadata.json'))
+    }
+
+    /** Atomically replaces the recorded metadata; without an active turn, removes it. */
+    async record(input: { sessionId: string, turnId: string | undefined }): Promise<void> {
+        if (input.turnId === undefined) {
+            await rm(this.path, { force: true })
+            return
+        }
+        const staged = `${this.path}.${randomUUID()}`
+        await writeFile(staged, JSON.stringify({ session_id: input.sessionId, turn_id: input.turnId }), { mode: 0o600, flag: 'wx' })
+        await rename(staged, this.path)
+    }
+
+    async close(): Promise<void> {
+        await rm(this.directory, { recursive: true, force: true })
+    }
+}
+
+/**
+ * Records the metadata before each call to the browser server's tools. Claude Code runs PreToolUse
+ * hooks before it sends the MCP tools/call, so the relay reads the metadata of the call's own turn.
+ * A call whose metadata cannot be recorded is denied rather than sent with a previous turn's ids.
+ */
+export function claudeBrowserTurnMetadataHooks(input: { serverName: string, record: () => Promise<void> }): NonNullable<Options['hooks']> {
+    const prefix = `mcp__${input.serverName}__`
+    return {
+        PreToolUse: [{
+            matcher: `${prefix}.*`,
+            hooks: [async (hookInput) => {
+                if (hookInput.hook_event_name !== 'PreToolUse' || !hookInput.tool_name.startsWith(prefix))
+                    return {}
+                try {
+                    await input.record()
+                    return {}
+                }
+                catch {
+                    return {
+                        hookSpecificOutput: {
+                            hookEventName: 'PreToolUse' as const,
+                            permissionDecision: 'deny' as const,
+                            permissionDecisionReason: 'Browser Use turn metadata could not be recorded for this call.',
+                        },
+                    }
+                }
+            }],
+        }],
+    }
+}

package/src/agents/claude/claude-code-process.ts

@@ -0,0 +1,98 @@
+import type { SpawnedProcess, SpawnOptions } from '@anthropic-ai/claude-agent-sdk'
+import type { ChildProcess } from 'node:child_process'
+import { spawn } from 'node:child_process'
+
+// After the SDK closes the CLI's stdin, Claude Code normally exits within milliseconds; the SDK
+// itself sends SIGTERM after a 2 s grace (SDK 0.3.280). Past this bound the run kills the CLI's
+// whole process group, including tool subprocesses. It stays below the supervisor's 10 s shutdown
+// drain budget and the unit's 15 s TimeoutStopSec.
+export const CLAUDE_PROCESS_EXIT_TIMEOUT_MS = 5_000
+// SIGKILL cannot be caught; this only bounds the wait for the kernel to report the exit.
+const killedExitWaitMs = 1_000
+// Matches the SDK's own stderr tail (2048 characters) for process-exit errors.
+const stderrTailLimit = 2_048
+
+/**
+ * The one Claude Code process of a run. The SDK's `close()` and `return()` do not wait for the CLI
+ * to exit (`return()` gives up after 2 s) and signal only the CLI's pid, so a stopped run could
+ * leave a CLI still writing its transcript while a resume starts a second writer. The run spawns
+ * the CLI through `spawnClaudeCodeProcess` as its own process group so it can await the exit and,
+ * past the bound, kill the group.
+ */
+export class ClaudeCodeProcess {
+    private child: ChildProcess | undefined
+    private exit: Promise<void> | undefined
+    private termination: Promise<void> | undefined
+    private stderr = ''
+
+    constructor(private readonly exitTimeoutMs = CLAUDE_PROCESS_EXIT_TIMEOUT_MS) {}
+
+    /** The SDK `spawnClaudeCodeProcess` hook. A run spawns at most one process. */
+    readonly spawn = (options: SpawnOptions): SpawnedProcess => {
+        if (this.child)
+            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 })
+        this.child = child
+        this.exit = new Promise((resolve) => {
+            child.once('exit', () => resolve())
+            // A failed spawn emits `error` without `exit`; there is no process to wait for.
+            child.once('error', () => {
+                if (child.pid === undefined)
+                    resolve()
+            })
+        })
+        // The SDK reads only stdin/stdout of a custom process; stderr must be drained here.
+        child.stderr?.setEncoding('utf8')
+        child.stderr?.on('data', (chunk: string) => {
+            this.stderr = (this.stderr + chunk).slice(-stderrTailLimit)
+        })
+        return child
+    }
+
+    /** The CLI's last stderr output, which a custom spawn keeps out of the SDK's exit errors. */
+    stderrTail(): string {
+        return this.stderr.trim()
+    }
+
+    /**
+     * Resolves once the CLI has exited. Call after `query.close()`, which sends stdin EOF. Past the
+     * exit bound the process group is killed. Idempotent; resolves at once if nothing was spawned.
+     */
+    async terminate(): Promise<void> {
+        this.termination ??= this.awaitExit()
+        await this.termination
+    }
+
+    private async awaitExit(): Promise<void> {
+        const child = this.child
+        const exit = this.exit
+        if (!child || !exit || child.pid === undefined)
+            return
+        if (await settlesWithin(exit, this.exitTimeoutMs))
+            return
+        try {
+            process.kill(-child.pid, 'SIGKILL')
+        }
+        catch {
+            child.kill('SIGKILL')
+        }
+        await settlesWithin(exit, killedExitWaitMs)
+    }
+}
+
+async function settlesWithin(promise: Promise<void>, ms: number): Promise<boolean> {
+    let timer: ReturnType<typeof setTimeout> | undefined
+    try {
+        return await Promise.race([
+            promise.then(() => true),
+            new Promise<boolean>((resolve) => {
+                timer = setTimeout(() => resolve(false), ms)
+            }),
+        ])
+    }
+    finally {
+        clearTimeout(timer)
+    }
+}

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

@@ -1,9 +1,11 @@
 import type { SDKUserMessage } from '@anthropic-ai/claude-agent-sdk'
 import type { MessageParam } from '@anthropic-ai/sdk/resources'
-import type { AgentAuthor, AgentInputBlock, AgentPrompt } from '../../protocol'
+import type { UUID } from 'node:crypto'
+import type { AgentAuthor, AgentInputBlock, AgentNotifyCommand, AgentPrompt } from '../../protocol'
 import type { AgentSenderContext } from '../agent-operation'
 import type { AgentInputAttachmentPreparation, AgentInputAttachmentProjection, MaterializedAgentInputAttachment } from '../materialized-input-attachment'
 import { Buffer } from 'node:buffer'
+import { serializeAgentNotificationToolOutput } from '../../protocol'
 import { AgentUnsupportedPromptBlockError } from '../agent-runtime-error'
 import { renderAuthorContext } from '../author-context'
 import { filesystemFallbackLabel, nativeAttachmentLabel, nativeImageMimeType, readAttachmentBytes } from '../input-attachment-preparation'
@@ -23,6 +25,9 @@ interface ClaudeUserMessageInput {
     origin?: 'user' | 'supervisor'
     author?: AgentAuthor
     senderContext?: AgentSenderContext
+    authorContext?: string
+    // The session's one-time context block, carried by its first prompt only.
+    sessionContext?: string
 }
 type ClaudeAttachmentProjection
     = | {
@@ -40,6 +45,59 @@ export function toClaudeUserMessage(input: ClaudeUserMessageInput): SDKUserMessa
     return claudeUserMessage(input, claudeMessageContent(input))
 }
 
+export function toClaudeCompactContextMessage(commandId: string): SDKUserMessage {
+    return claudeUserMessage({
+        prompt: { blocks: [{ type: 'text', text: '/compact' }] },
+        commandId,
+        origin: 'supervisor',
+    }, [{ type: 'text', text: '/compact' }])
+}
+
+export const claudeNotificationTag = 'coding_agent_session_notifications'
+
+/**
+ * Claude has no standalone tool-output input, so an application notification is a synthetic
+ * user-role message whose only content is the same bounded `{ commandId, instruction,
+ * notifications }` envelope Codex sends as the `coding_agent/session_notifications` tool output.
+ * The `task-notification` origin makes Claude Code frame it for the model as a non-user message
+ * ("[MESSAGE FROM NON-USER SOURCE - NOT USER INPUT]", CLI 2.1.280). `<`, `>`, and `&` are
+ * JSON-escaped, so an untrusted notification value cannot close the tag and forge a trusted
+ * envelope. Priority `next`: an idle session starts a turn with it.
+ */
+export function toClaudeNotificationMessage(command: Pick<AgentNotifyCommand, 'commandId' | 'instruction' | 'notifications'>): SDKUserMessage {
+    return toClaudeTaskNotificationMessage({ text: claudeNotificationText(command), uuid: deriveMessageId(command.commandId) })
+}
+
+/**
+ * The same non-user framing for already-tagged envelope text, such as steered notifications whose
+ * turn ended before a hook delivered them. The caller owns the input uuid.
+ */
+export function toClaudeTaskNotificationMessage(input: { text: string, uuid: UUID }): SDKUserMessage {
+    return {
+        type: 'user',
+        message: { role: 'user', content: [{ type: 'text', text: input.text }] },
+        parent_tool_use_id: null,
+        priority: 'next',
+        uuid: input.uuid,
+        isSynthetic: true,
+        origin: { kind: 'task-notification' },
+    }
+}
+
+/** The tagged, escaped envelope; also the hook payload for a notification steered into a turn. */
+export function claudeNotificationText(command: Pick<AgentNotifyCommand, 'commandId' | 'instruction' | 'notifications'>): string {
+    const envelope = serializeAgentNotificationToolOutput({
+        commandId: command.commandId,
+        instruction: command.instruction,
+        notifications: command.notifications,
+    })
+    return `<${claudeNotificationTag}>\n${escapeForTaggedJson(envelope)}\n</${claudeNotificationTag}>`
+}
+
+function escapeForTaggedJson(json: string): string {
+    return json.replaceAll('<', '\\u003c').replaceAll('>', '\\u003e').replaceAll('&', '\\u0026')
+}
+
 export async function mapClaudeUserMessage(input: ClaudeUserMessageInput, preparation?: AgentInputAttachmentPreparation): Promise<SDKUserMessage> {
     return preparation
         ? await prepareClaudeUserMessage({ ...input, preparation })
@@ -78,10 +136,12 @@ function claudeUserMessage(input: ClaudeUserMessageInput, content: ClaudeContent
     }
 }
 
-function claudeMessageContent({ prompt, origin = 'user', author, senderContext }: ClaudeUserMessageInput): ClaudeContentBlock[] {
+function claudeMessageContent({ prompt, origin = 'user', author, senderContext, authorContext, sessionContext }: ClaudeUserMessageInput): ClaudeContentBlock[] {
     const blocks = prompt.blocks.map(toClaudeContentBlock)
+    if (sessionContext)
+        blocks.unshift({ type: 'text', text: sessionContext })
     return origin === 'user' && author
-        ? [{ type: 'text', text: renderAuthorContext(author, senderContext) }, ...blocks]
+        ? [{ type: 'text', text: authorContext ?? renderAuthorContext(author, senderContext) }, ...blocks]
         : blocks
 }
 

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

@@ -0,0 +1,55 @@
+import type { McpStdioServerConfig } from '@anthropic-ai/claude-agent-sdk'
+import type { CodexAuthProvider } from '../codex/codex-auth'
+import { turnMetadataPathVariable } from './claude-browser-turn-metadata'
+
+/** One image-owned desktop MCP server, as generated by the sandbox desktop configuration. */
+export type ClaudeDesktopMcpServer = Readonly<{
+    name: string
+    command: string
+    args: readonly string[]
+    env: Readonly<Record<string, string>>
+    // Values the run supplies from its environment (or the browser-auth broker) at spawn time.
+    runtimeEnv: readonly string[]
+}>
+
+/**
+ * The sandbox desktop for Claude: the same Computer Use / Browser Use MCP servers Codex receives,
+ * plus the Codex credential source that Browser Use's first-party runtime requires. The server
+ * named `browserAuth.serverName` receives the run's broker socket as
+ * `CODING_AGENT_BROWSER_AUTH_SOCKET` and its turn metadata file as
+ * `CODING_AGENT_TURN_METADATA_PATH`; the credential itself never enters the Claude environment.
+ */
+export type ClaudeDesktopConfig = Readonly<{
+    servers: readonly ClaudeDesktopMcpServer[]
+    browserAuth: Readonly<{
+        serverName: string
+        codexExecutable: string
+        codexAuth: CodexAuthProvider
+    }>
+}>
+
+export const browserAuthSocketVariable = 'CODING_AGENT_BROWSER_AUTH_SOCKET'
+
+export function claudeDesktopMcpServers(input: {
+    desktop: ClaudeDesktopConfig
+    environment: Readonly<Record<string, string | undefined>>
+    browserAuthSocketPath: string
+    turnMetadataPath: string
+}): Record<string, McpStdioServerConfig> {
+    // Run-owned values reach only the browser server, never another desktop server that names them.
+    const browserRunValues = new Map([
+        [browserAuthSocketVariable, input.browserAuthSocketPath],
+        [turnMetadataPathVariable, input.turnMetadataPath],
+    ])
+    return Object.fromEntries(input.desktop.servers.map((server) => {
+        const runtime: Record<string, string> = {}
+        for (const name of server.runtimeEnv) {
+            const value = server.name === input.desktop.browserAuth.serverName && browserRunValues.has(name)
+                ? browserRunValues.get(name)
+                : input.environment[name]
+            if (value !== undefined)
+                runtime[name] = value
+        }
+        return [server.name, { type: 'stdio', command: server.command, args: [...server.args], env: { ...server.env, ...runtime } }]
+    }))
+}