Add product-safe agent intake projections

Author: nshkrdotcom

README.md

@@ -95,10 +95,11 @@ redaction, and tenant-scoped checks.
 The workspace currently exposes these product-facing families:
 
 - **Work and runtime:** `AppKit.WorkControl`, `AppKit.WorkSurface`,
-  `AppKit.HeadlessSurface`, `AppKit.RuntimeSurface`, and
+  `AppKit.HeadlessSurface`, `AppKit.AgentIntake`, `AppKit.RuntimeSurface`, and
   `AppKit.RunGovernance` provide governed run start/control, runtime
-  projections, headless state/readback, live-effect receipts, and product-safe
-  runtime profile application.
+  projections, agent run start/turn/cancel/cursor catch-up/pending summaries,
+  headless state/readback, live-effect receipts, and product-safe runtime
+  profile application.
 - **Operator and review:** `AppKit.OperatorSurface` and
   `AppKit.ReviewSurface` provide queue/detail/review readbacks, review
   decisions, lower-read leases, stream-attach leases, and operator-visible
@@ -134,6 +135,15 @@ refs, dispatch refs, receipt refs, evidence refs, and trace summary hashes
 without exposing Mezzanine, Citadel, Jido Integration, Execution Plane, or
 AITrace internals to product code.
 
+The native agent foundation uses `AppKit.AgentIntake` as the product-safe
+surface for agent runs. Products may submit an `AgentRunRequest`, submit a
+`TurnSubmission`, cancel a run, catch up from an `AgentRunCursor`, and list
+`AgentPendingInteraction` summaries. Those DTOs carry refs, summaries, bounded
+kinds, and cursors only. Product code must not import AgentInterop contracts,
+runtime receipts, lower ledger truth, generated protocol modules, raw
+endpoints, provider payloads, credentials, raw prompts, AX runtime names, or
+A2A names.
+
 The dedicated Synapse conformance command is owned by StackLab:
 
 ```bash

bridges/mezzanine_bridge/lib/app_kit/bridges/mezzanine_bridge.ex

@@ -471,6 +471,16 @@ defmodule AppKit.Bridges.MezzanineBridge do
     AgentIntakeAdapter.await_agent_outcome(context, run_ref, request, opts)
   end
 
+  @impl AppKit.Core.Backends.AgentIntakeBackend
+  def catch_up_agent_events(%RequestContext{} = context, cursor, opts) do
+    AgentIntakeAdapter.catch_up_agent_events(context, cursor, opts)
+  end
+
+  @impl AppKit.Core.Backends.AgentIntakeBackend
+  def list_pending_interactions(%RequestContext{} = context, request, opts) do
+    AgentIntakeAdapter.list_pending_interactions(context, request, opts)
+  end
+
   @impl AppKit.EffectSurface
   def propose_effect(%RequestContext{} = context, effect_params, opts) do
     EffectAdapter.propose_effect(context, effect_params, opts)

bridges/mezzanine_bridge/lib/app_kit/bridges/mezzanine_bridge/agent_intake_adapter.ex

@@ -10,7 +10,7 @@ defmodule AppKit.Bridges.MezzanineBridge.AgentIntakeAdapter do
     RuntimeReadbackMapping
   }
 
-  alias AppKit.Core.AgentIntake.RunOutcomeFuture
+  alias AppKit.Core.AgentIntake.{AgentRunEventPage, RunOutcomeFuture}
   alias AppKit.Core.RequestContext
   alias AppKit.Core.RuntimeReadback.CommandResult
 
@@ -89,4 +89,26 @@ defmodule AppKit.Bridges.MezzanineBridge.AgentIntakeAdapter do
       {:error, :agent_turn_runtime_not_available}
     end
   end
+
+  @impl true
+  def catch_up_agent_events(%RequestContext{}, cursor, opts) do
+    if RuntimeMapping.runtime_available?(RuntimeMapping.agent_runtime(opts)) do
+      AgentRunEventPage.new(%{
+        cursor: cursor,
+        events: [],
+        has_more?: false
+      })
+    else
+      {:error, :agent_turn_runtime_not_available}
+    end
+  end
+
+  @impl true
+  def list_pending_interactions(%RequestContext{}, _request, opts) do
+    if RuntimeMapping.runtime_available?(RuntimeMapping.agent_runtime(opts)) do
+      {:ok, []}
+    else
+      {:error, :agent_turn_runtime_not_available}
+    end
+  end
 end

bridges/mezzanine_bridge/test/app_kit/bridges/mezzanine_bridge_contract_characterization_test.exs

@@ -174,7 +174,9 @@ defmodule AppKit.Bridges.MezzanineBridgeContractCharacterizationTest do
         start_agent_run: 3,
         submit_agent_turn: 3,
         cancel_agent_run: 3,
-        await_agent_outcome: 4
+        await_agent_outcome: 4,
+        catch_up_agent_events: 3,
+        list_pending_interactions: 3
       ]
     },
     %{

core/app_kit_core/README.md

@@ -27,6 +27,8 @@ Current contract groups:
   suppression visibility projection
 - runtime projection DTOs for source binding, workspace, execution, lower
   receipt, evidence, review, operator-command, and runtime-event facts
+- native agent intake DTOs for agent run requests, turn submissions, cursor
+  catch-up, event pages, pending interaction summaries, and pending queries
 - extension supply-chain DTOs for pack integrity posture, pack bundle schema,
   and connector-admission projection
 - northbound backend behaviours for work queries, reviews, and installations
@@ -112,6 +114,15 @@ retention disabled without changing provider-effect or readback semantics.
 `AppKit.Core.Result` and `AppKit.Core.RunRef` remain part of the current
 northbound contract set and are not treated as temporary coexistence shims.
 
+`AppKit.AgentIntake` is the product-facing native agent boundary. Product code
+uses AppKit DTOs for run start, turn submission, cancellation, cursor catch-up,
+and pending interaction summaries. These DTOs expose opaque refs and bounded
+summary fields only. They reject lower selectors, raw transport endpoints,
+generated protocol module names, provider payloads, credential fields, raw
+prompt shortcut fields, AX runtime vocabulary, and A2A vocabulary. AgentInterop
+descriptors, runtime receipts, and ledger truth are lower-owner concepts and
+are not AppKit product APIs.
+
 Default runtime backend configuration for the surface packages belongs under
 the `:app_kit_core` OTP application. The workspace no longer uses a synthetic
 `:app_kit` config namespace for surface backends.