feat(kernel): add run-scoped host context

[vishaltandale00]

Context

Prime Agent already has authenticated per-call host-request contracts from #1238, while the broader dispatcher work in the closed #1243 branch was not merged. Embedders still need a generic way to attach host-owned authority or request state to one admitted prompt execution without changing tool definitions, exposing that state to model-generated Python, or storing it in session artifacts.

Changes

• Adds public, factory-validated typed kernel host-handler registration to AgentSession / createAgentSession; the handler table is copied once and remains stable for the session lifetime.
• Adds runContext to in-process prompt() / promptAndWait() options. An opaque execution ID flows through agent tool invocation metadata, while the actual object stays in a private execution-keyed map rather than a process-global or session-global current-context field.
• Mints handler invocation context in the dispatcher with session ID, recursion depth, run context, request ID, generation/currentness, and cancellation signal. Python payload fields cannot select or override this metadata, and handler result fields cannot override reply status.
• Propagates the spawning execution context to sibling and nested RLM children, including inline, runtime-hosted, and daemon-hosted in-process child creation.
• Revokes execution/handler contexts on completion, failure, cancellation, comm close, and kernel teardown. Run-context objects are not added to messages, queued-action recovery snapshots, session JSONL, runtime metadata, or IPython namespace snapshots.
• Documents the SDK and runtime boundary. Session-lifetime handlers can be configured by daemon embedders, but arbitrary runContext objects are consciously not added to the remote daemon/RPC prompt wire format; callers should attach them at the in-process AgentSession host boundary.

Concurrency semantics

Each admitted root action owns a distinct execution scope. Sequential turns in one persistent session therefore resolve different contexts, and parallel sessions use separate keyed maps. Tool calls correlate by opaque execution ID and Jupyter parent message ID; missing correlation yields no run context instead of falling back to another active cell.

Validation

No paid inference was used. Validation used faux provider responses plus local IPython kernels.

• npm run check (Biome with warnings as errors, TypeScript, installer render, browser smoke)
• npx tsx ../../node_modules/vitest/dist/cli.js --run test/suite/agent-session-run-context.test.ts (4 passed)
• npx tsx ../../node_modules/vitest/dist/cli.js --run test/agent-session-recursion.test.ts (98 passed)
• npx tsx ../../node_modules/vitest/dist/cli.js --run test/host-request-contract.test.ts (3 passed)
• npx tsx ../../node_modules/vitest/dist/cli.js --run test/kernel-goal-skill.test.ts test/kernel-agent-message-skill.test.ts (7 passed, 3 environment-gated skipped)
• npx tsx ../../node_modules/vitest/dist/cli.js --run test/suite/agent-session-compaction.test.ts (32 passed)
• npx tsx ../../node_modules/vitest/dist/cli.js --run test/agent.test.ts from packages/agent (25 passed)

Note

Add run-scoped host context to kernel host request handlers in agent sessions

• Introduces a hostRequestHandlers registration API on AgentSession (and createAgentSession/daemon) so callers can bind typed, session-lifetime kernel host handlers using a new createHostRequestHandler factory.
• Each admitted agent run gets an AgentRunScope carrying a runContext (caller-supplied, opaque) and an AbortSignal; this scope is correlated to kernel executions via an executionId and exposed to host handlers through a dispatcher-minted HostRequestContext.
• HostRequestContext now includes sessionId, recursionDepth, and runContext fields; contexts are cryptographically provenance-checked (WeakSet-based) so structurally similar forgeries are rejected.
• Child subagent runs spawned via rlm.run inherit the parent runContext and hostRequestHandlers, with recursionDepth incremented; runContext is memory-only and never serialized to disk or recovery snapshots.
• executionId flows from Agent.prompt/Agent.continue through AgentLoopConfig into each tool's execute call via a new AgentToolExecutionContext parameter.
• Risk: custom handlers that conflict with built-in handler types throw at session construction time; all active host request contexts are aborted when the kernel stops.

^{Macroscope summarized 65e7d31.}

[github-actions]

Hi @vishaltandale00, thanks for your interest in contributing!

This project requires that pull request authors are vouched, and you are not in the list of vouched users.

This PR will be closed automatically. See https://github.com/PrimeIntellect-ai/prime-agent/blob/main/CONTRIBUTING.md for more details.