feat(contracts): RunTurnInput gains tabId/turnId/providerOpts; FinishReason union (resolves runtime CR-1/2/3)

2 files changed, 35 insertions, 3 deletions

diff --git a/packages/kernel/src/contracts/index.ts b/packages/kernel/src/contracts/index.ts
index 1c3393f..0b578cb 100644
--- a/packages/kernel/src/contracts/index.ts
+++ b/packages/kernel/src/contracts/index.ts
@@ -82,6 +82,7 @@ export type {
 } from "./provider.js";
 export type {
 	EventEmitter,
+	FinishReason,
 	RunTurnInput,
 	RunTurnResult,
 } from "./runtime.js";
diff --git a/packages/kernel/src/contracts/runtime.ts b/packages/kernel/src/contracts/runtime.ts
index 15f4869..ff994af 100644
--- a/packages/kernel/src/contracts/runtime.ts
+++ b/packages/kernel/src/contracts/runtime.ts
@@ -10,7 +10,7 @@
 import type { ChatMessage } from "./conversation.js";
 import type { ToolDispatchPolicy } from "./dispatch.js";
 import type { AgentEvent } from "./events.js";
-import type { ProviderContract, Usage } from "./provider.js";
+import type { ProviderContract, ProviderStreamOptions, Usage } from "./provider.js";
 import type { ToolContract } from "./tool.js";
 
 /**
@@ -20,6 +20,21 @@ import type { ToolContract } from "./tool.js";
 export type EventEmitter = (event: AgentEvent) => void;
 
 /**
+ * Why a turn ended. Known kernel/provider reasons are enumerated for ergonomics;
+ * the trailing `(string & {})` keeps the type open for provider-specific reasons
+ * passed through verbatim without losing autocomplete on the known values.
+ */
+export type FinishReason =
+	| "stop"
+	| "tool-calls"
+	| "length"
+	| "content-filter"
+	| "max-steps"
+	| "error"
+	| "aborted"
+	| (string & {});
+
+/**
  * Input to `runTurn` — everything the kernel needs to execute one turn.
  * All fields are resolved by the session-orchestrator before calling;
  * the kernel never reads config or resolves providers/tools itself.
@@ -40,6 +55,22 @@ export interface RunTurnInput {
 	/** The emitter the kernel calls for each outward event. */
 	readonly emit: EventEmitter;
 
+	/**
+	 * Identifiers used to attribute every emitted `AgentEvent`. The kernel does
+	 * not generate these — the session-orchestrator owns turn/tab identity and
+	 * passes them in, so events are traceable to their conversation.
+	 */
+	readonly tabId: string;
+	readonly turnId: string;
+
+	/**
+	 * Optional per-turn provider options (model, temperature, maxTokens,
+	 * systemPrompt). The orchestrator resolves these; the kernel forwards them
+	 * verbatim to `provider.stream` and never interprets them. A provider may
+	 * also be pre-configured at construction and ignore these.
+	 */
+	readonly providerOpts?: ProviderStreamOptions;
+
 	/** Cancellation signal for the entire turn. */
 	readonly signal?: AbortSignal;
 }
@@ -55,6 +86,6 @@ export interface RunTurnResult {
 	/** Aggregated token usage across all steps in the turn. */
 	readonly usage: Usage;
 
-	/** Why the turn ended (e.g. "stop", "max-steps", "error", "aborted"). */
-	readonly finishReason: string;
+	/** Why the turn ended. */
+	readonly finishReason: FinishReason;
 }