security(agent): bind inference to durable admission

config/config.exs

@@ -48,6 +48,7 @@ config :phoenix, :filter_parameters, [
   "refresh_token",
   "id_token",
   "device_code",
+  "device_authorization_attempt_id",
   "device_auth_id",
   "user_code",
   "code_verifier",

lib/kodo/agent/evaluation_runner.ex

@@ -488,7 +488,7 @@ defmodule Kodo.Agent.EvaluationRunner do
 
   defp generate(scope, adapter, role, messages, tools) do
     with {:ok, model, reference} <- LLM.resolve_integration(scope, role["model"]) do
-      LLM.generate(scope, model, reference, messages, tools,
+      LLM.generate_evaluation(scope, model, reference, messages, tools,
         adapter: adapter,
         timeout: @timeout,
         reasoning: role["reasoning"]
@@ -498,7 +498,7 @@ defmodule Kodo.Agent.EvaluationRunner do
 
   defp generate_object(scope, adapter, role, messages, schema) do
     with {:ok, model, reference} <- LLM.resolve_integration(scope, role["model"]) do
-      LLM.generate_object(scope, model, reference, messages, schema,
+      LLM.generate_object_evaluation(scope, model, reference, messages, schema,
         adapter: adapter,
         timeout: @timeout,
         reasoning: role["reasoning"]

lib/kodo/agent/execution_route_change.ex

@@ -12,25 +12,47 @@ defmodule Kodo.Agent.ExecutionRouteChange do
   def change(mapping, destination, records \\ @approved_records)
 
   def change(mapping, destination, records) when destination in @routes and is_list(records) do
-    mapping = ModelMapping.snapshot(mapping)
-
-    affected =
-      Enum.filter(mapping["roles"], fn {_role, role_mapping} ->
-        role_mapping["execution_route"] in @routes and
-          role_mapping["execution_route"] != destination
-      end)
-
-    with false <- affected == [],
+    with {:ok, mapping} <- change_mapping(mapping),
+         affected = affected_roles(mapping, destination),
+         false <- affected == [],
          [] <- incompatible_roles(affected, destination, records) do
       {:ok, apply_route(mapping, affected, destination)}
     else
+      {:error, _reason} = error -> error
       true -> {:error, :execution_route_unchanged}
       roles when is_list(roles) -> {:error, {:incompatible_execution_route, roles}}
     end
   end
 
   def change(_mapping, _destination, _records), do: {:error, :unsupported_execution_route}
 
+  defp change_mapping(mapping) do
+    case ModelMapping.validate_snapshot(mapping) do
+      {:ok, snapshot} ->
+        {:ok, snapshot}
+
+      {:error, :invalid_model_mapping_snapshot} ->
+        if explicit_snapshot?(mapping),
+          do: {:error, :invalid_model_mapping_snapshot},
+          else: {:ok, ModelMapping.snapshot(mapping)}
+    end
+  end
+
+  defp explicit_snapshot?(%{"roles" => roles}) when is_map(roles) do
+    Enum.any?(roles, fn {_role, mapping} ->
+      is_map(mapping) and is_map_key(mapping, "capability_contract")
+    end)
+  end
+
+  defp explicit_snapshot?(_mapping), do: false
+
+  defp affected_roles(mapping, destination) do
+    Enum.filter(mapping["roles"], fn {_role, role_mapping} ->
+      role_mapping["execution_route"] in @routes and
+        role_mapping["execution_route"] != destination
+    end)
+  end
+
   defp incompatible_roles(affected, destination, records) do
     for {role, role_mapping} <- affected,
         not compatible?(role, role_mapping, destination, records),
@@ -44,6 +66,8 @@ defmodule Kodo.Agent.ExecutionRouteChange do
         record.destination == destination and
         record.selector == role_mapping["model_selector"] and
         record.role_contract == role_mapping["role_contract"] and
+        record.reasoning == role_mapping["reasoning"] and
+        record.capability_contract == role_mapping["capability_contract"] and
         record.status == :approved
     end)
   end

lib/kodo/agent/loop.ex

@@ -6,6 +6,7 @@ defmodule Kodo.Agent.Loop do
   alias Kodo.Agent.Roles
   alias Kodo.Agent.Tools
   alias Kodo.LLM
+  alias Kodo.LLM.ProviderError
   alias Kodo.RunnerProtocol
   alias Kodo.Runners
   alias Kodo.Sessions
@@ -33,29 +34,21 @@ defmodule Kodo.Agent.Loop do
 
     latest_response = List.last(responses)
 
-    case rehoming_boundary() do
-      :ok ->
-        case within_budget(invocations, tokens, budgets) do
-          :ok ->
-            action = next_action(latest_invocation, latest_response)
-
-            resume_action(
-              action,
-              session_id,
-              projection,
-              events,
-              adapter,
-              budgets,
-              invocations,
-              ownership
-            )
-
-          error ->
-            error
-        end
+    with :ok <- validate_turn_mapping(projection),
+         :ok <- rehoming_boundary(),
+         :ok <- within_budget(invocations, tokens, budgets) do
+      action = next_action(latest_invocation, latest_response)
 
-      error ->
-        error
+      resume_action(
+        action,
+        session_id,
+        projection,
+        events,
+        adapter,
+        budgets,
+        invocations,
+        ownership
+      )
     end
   end
 
@@ -177,7 +170,7 @@ defmodule Kodo.Agent.Loop do
            ),
          :ok <- Phoenix.PubSub.subscribe(Kodo.PubSub, "session:#{context.session_id}"),
          :ok <- Runners.subscribe_lifecycle(),
-         {:ok, review_invocation_id} <-
+         {:ok, {review_invocation_id, admission}} <-
            start_review_invocation(
              context.session_id,
              primary_invocation_id,
@@ -205,7 +198,7 @@ defmodule Kodo.Agent.Loop do
 
              generate_object(
                context.adapter,
-               request,
+               admission,
                [
                  %{"role" => "system", "content" => contract.prompt},
                  %{
@@ -255,7 +248,7 @@ defmodule Kodo.Agent.Loop do
        ) do
     invocation_id = Ecto.UUID.generate()
 
-    case Sessions.append_event(
+    case Sessions.append_admitted_model_event(
            session_id,
            "review_invocation_started",
            %{
@@ -265,20 +258,22 @@ defmodule Kodo.Agent.Loop do
              "provider" => canonical_provider(request),
              "model" => review["model"],
              "model_identity" => request.model.id,
-             "authentication_type" => request.reference.authentication_type,
-             "billing_path" => Atom.to_string(request.reference.billing_path),
+             "authentication_type" => request.credential.authentication_type,
+             "billing_path" => Atom.to_string(request.credential.billing_path),
              "reasoning" => review["reasoning"],
              "role_contract" => contract.id,
              "toolset_version" => contract.toolset_version,
              "capability_validation" => capability_validation,
              "model_mapping" => mapping
            },
+           request.model,
+           request.credential,
            version: 2,
            parent_id: primary_invocation_id,
            ownership: ownership
          ) do
-      {:ok, _event} -> {:ok, invocation_id}
-      error -> error
+      {:ok, {_event, admission}} -> {:ok, {invocation_id, admission}}
+      error -> normalize_admission_error(error, request)
     end
   end
 
@@ -459,7 +454,21 @@ defmodule Kodo.Agent.Loop do
   end
 
   defp turn_mapping(projection) do
-    projection.turn_model_mapping || projection.model_mapping || legacy_mapping(projection.model)
+    case {projection.turn_route_snapshot_present, projection.turn_model_mapping} do
+      {false, _mapping} ->
+        mapping = projection.model_mapping || legacy_mapping(projection.model)
+        ModelMapping.snapshot(mapping)
+
+      {true, snapshot} ->
+        snapshot
+    end
+  end
+
+  defp validate_turn_mapping(projection) do
+    case ModelMapping.validate_snapshot(turn_mapping(projection)) do
+      {:ok, _mapping} -> :ok
+      {:error, _reason} = error -> error
+    end
   end
 
   defp infer(session_id, projection, events, adapter, budgets, invocation, ownership) do
@@ -479,7 +488,7 @@ defmodule Kodo.Agent.Loop do
          {:ok, capability_validation} <-
            adapter.validate_model(primary_model, primary, contract),
          {:ok, request} <- resolve_request(session_id, primary),
-         {:ok, invocation_id} <-
+         {:ok, {invocation_id, admission}} <-
            start_invocation(
              session_id,
              invocation,
@@ -494,7 +503,7 @@ defmodule Kodo.Agent.Loop do
            Sessions.dispatch_if_owner(ownership, fn ->
              generate(
                adapter,
-               request,
+               admission,
                transcript(events, contract, primary["execution_route"] || primary["provider"]),
                tools,
                timeout: budgets[:model_timeout],
@@ -614,7 +623,7 @@ defmodule Kodo.Agent.Loop do
        ) do
     invocation_id = Ecto.UUID.generate()
 
-    case Sessions.append_event(
+    case Sessions.append_admitted_model_event(
            session_id,
            "model_invocation_started",
            %{
@@ -624,19 +633,21 @@ defmodule Kodo.Agent.Loop do
              "provider" => canonical_provider(request),
              "model" => primary["model"],
              "model_identity" => request.model.id,
-             "authentication_type" => request.reference.authentication_type,
-             "billing_path" => Atom.to_string(request.reference.billing_path),
+             "authentication_type" => request.credential.authentication_type,
+             "billing_path" => Atom.to_string(request.credential.billing_path),
              "reasoning" => primary["reasoning"],
              "role_contract" => primary["role_contract"],
              "toolset_version" => primary["toolset_version"],
              "capability_validation" => capability_validation,
              "model_mapping" => mapping
            },
+           request.model,
+           request.credential,
            version: 4,
            ownership: ownership
          ) do
-      {:ok, _event} -> {:ok, invocation_id}
-      error -> error
+      {:ok, {_event, admission}} -> {:ok, {invocation_id, admission}}
+      error -> normalize_admission_error(error, request)
     end
   end
 
@@ -988,7 +999,7 @@ defmodule Kodo.Agent.Loop do
     with :ok <- within_budget(continuation, tokens, state.contract.budget),
          :ok <- rehoming_boundary(),
          {:ok, request} <- resolve_request(state.context.session_id, state.search),
-         {:ok, invocation_id} <-
+         {:ok, {invocation_id, admission}} <-
            start_subagent_invocation(
              state.parent_call,
              state.search,
@@ -1003,7 +1014,7 @@ defmodule Kodo.Agent.Loop do
            Sessions.dispatch_if_owner(state.context.ownership, fn ->
              generate(
                state.context.adapter,
-               request,
+               admission,
                messages,
                Tools.definitions_for_turn(
                  state.contract.toolset_version,
@@ -1119,7 +1130,7 @@ defmodule Kodo.Agent.Loop do
        ) do
     invocation_id = Ecto.UUID.generate()
 
-    case Sessions.append_event(
+    case Sessions.append_admitted_model_event(
            context.session_id,
            "subagent_invocation_started",
            %{
@@ -1130,20 +1141,22 @@ defmodule Kodo.Agent.Loop do
              "provider" => canonical_provider(request),
              "model" => search["model"],
              "model_identity" => request.model.id,
-             "authentication_type" => request.reference.authentication_type,
-             "billing_path" => Atom.to_string(request.reference.billing_path),
+             "authentication_type" => request.credential.authentication_type,
+             "billing_path" => Atom.to_string(request.credential.billing_path),
              "reasoning" => search["reasoning"],
              "role_contract" => contract.id,
              "toolset_version" => contract.toolset_version,
              "capability_validation" => capability_validation,
              "model_mapping" => context.mapping
            },
+           request.model,
+           request.credential,
            version: 2,
            parent_id: context.invocation_id,
            ownership: context.ownership
          ) do
-      {:ok, _event} -> {:ok, invocation_id}
-      error -> error
+      {:ok, {_event, admission}} -> {:ok, {invocation_id, admission}}
+      error -> normalize_admission_error(error, request)
     end
   end
 
@@ -1680,27 +1693,29 @@ defmodule Kodo.Agent.Loop do
   defp resolve_request(session_id, role) do
     with {:ok, scope} <- Sessions.owner_scope(session_id),
          {:ok, model, reference} <-
-           LLM.resolve_integration(scope, ModelMapping.request_model(role)) do
-      {:ok, %{scope: scope, model: model, reference: reference}}
+           LLM.resolve_integration(scope, ModelMapping.request_model(role)),
+         {:ok, credential} <- LLM.admit_credential(scope, model, reference) do
+      {:ok, %{model: model, credential: credential}}
     end
   end
 
-  defp generate(adapter, request, messages, tools, opts) do
-    LLM.generate(
-      request.scope,
-      request.model,
-      request.reference,
+  defp normalize_admission_error({:error, :stale_credential_generation}, request),
+    do: {:error, ProviderError.from_integration(:stale_credential_generation, request.model)}
+
+  defp normalize_admission_error(error, _request), do: error
+
+  defp generate(adapter, admission, messages, tools, opts) do
+    LLM.generate_admitted(
+      admission,
       messages,
       tools,
       Keyword.put(opts, :adapter, adapter)
     )
   end
 
-  defp generate_object(adapter, request, messages, schema, opts) do
-    LLM.generate_object(
-      request.scope,
-      request.model,
-      request.reference,
+  defp generate_object(adapter, admission, messages, schema, opts) do
+    LLM.generate_object_admitted(
+      admission,
       messages,
       schema,
       Keyword.put(opts, :adapter, adapter)