feat(kernel): listModels/ModelInfo + per-turn cwd contracts; add transport-contract wire package

4 files changed, 38 insertions, 0 deletions

diff --git a/packages/kernel/src/contracts/index.ts b/packages/kernel/src/contracts/index.ts
index a4c965a..6f6954e 100644
--- a/packages/kernel/src/contracts/index.ts
+++ b/packages/kernel/src/contracts/index.ts
@@ -83,6 +83,7 @@ export type {
 } from "./logging.js";
 export type {
 	FinishEvent,
+	ModelInfo,
 	ProviderContract,
 	ProviderErrorEvent,
 	ProviderEvent,
diff --git a/packages/kernel/src/contracts/provider.ts b/packages/kernel/src/contracts/provider.ts
index 62dc8e9..ee58c1d 100644
--- a/packages/kernel/src/contracts/provider.ts
+++ b/packages/kernel/src/contracts/provider.ts
@@ -104,6 +104,17 @@ export interface ProviderStreamOptions {
 }
 
 /**
+ * Metadata describing a single model a provider can serve. Returned by
+ * `listModels` so a catalog (e.g. the credential-store) can enumerate the
+ * `<credentialName>/<model>` choices a client may select. Kept minimal — `id`
+ * is the wire model identifier; `displayName` is an optional human label.
+ */
+export interface ModelInfo {
+	readonly id: string;
+	readonly displayName?: string;
+}
+
+/**
  * What a provider extension registers with the kernel. The kernel calls
  * `stream` and consumes the async iterable of events — it never knows which
  * concrete LLM API is behind it.
@@ -122,4 +133,13 @@ export interface ProviderContract {
 		tools: readonly ToolContract[],
 		opts?: ProviderStreamOptions,
 	) => AsyncIterable<ProviderEvent>;
+
+	/**
+	 * Enumerate the models this provider can serve, each in its own way (e.g. an
+	 * OpenAI-compatible provider GETs `/v1/models`). Optional: a provider that
+	 * cannot (or chooses not to) enumerate omits it, and a catalog simply lists
+	 * none for it. A future multi-credential design may pass per-credential
+	 * credentials in; today the provider uses the key it resolved at activate.
+	 */
+	readonly listModels?: () => Promise<readonly ModelInfo[]>;
 }
diff --git a/packages/kernel/src/contracts/runtime.ts b/packages/kernel/src/contracts/runtime.ts
index 1e8f14f..8917709 100644
--- a/packages/kernel/src/contracts/runtime.ts
+++ b/packages/kernel/src/contracts/runtime.ts
@@ -76,6 +76,15 @@ export interface RunTurnInput {
 	readonly signal?: AbortSignal;
 
 	/**
+	 * Working directory for this turn's tool execution. The kernel does NOT
+	 * interpret it — it forwards the value verbatim to each `ToolExecuteContext.cwd`
+	 * so tools resolve/contain paths against it. It never enters the model prompt,
+	 * so it does not affect prompt caching. When omitted, tools fall back to their
+	 * own configured/default workdir.
+	 */
+	readonly cwd?: string;
+
+	/**
 	 * Optional logger for structured span instrumentation. The runtime opens
 	 * turn/step/tool-call spans using this logger. If omitted, no spans are
 	 * emitted (backward-compatible with callers that don't yet pass a logger).
diff --git a/packages/kernel/src/contracts/tool.ts b/packages/kernel/src/contracts/tool.ts
index 0699d05..f617f42 100644
--- a/packages/kernel/src/contracts/tool.ts
+++ b/packages/kernel/src/contracts/tool.ts
@@ -62,6 +62,14 @@ export interface ToolExecuteContext {
 	 * turnId, and spanId automatically.
 	 */
 	readonly log: Logger;
+
+	/**
+	 * Working directory for this turn, forwarded verbatim from `RunTurnInput.cwd`.
+	 * Tools that touch the filesystem resolve and contain paths against it.
+	 * Optional: when omitted, a tool falls back to its own configured/default
+	 * workdir. The kernel never interprets it.
+	 */
+	readonly cwd?: string;
 }
 
 /**