docs(agent): clarify agents api loop ownership boundary (#1648)

Author: chubes4

docs/development/agents-api-extraction-map.md

@@ -6,7 +6,7 @@ Parent issue: [Explore splitting Agents API out of Data Machine](https://github.
 
 Strategy update: [Agents API blocker: update extraction docs around in-repo module strategy](https://github.com/Extra-Chill/data-machine/issues/1640)
 
-Related blockers: [standalone extraction umbrella](https://github.com/Extra-Chill/data-machine/issues/1596), [standalone skeleton plan](https://github.com/Extra-Chill/data-machine/issues/1618), [in-repo module boundary](https://github.com/Extra-Chill/data-machine/issues/1631), [candidate relocation](https://github.com/Extra-Chill/data-machine/issues/1632), [wp-ai-client dependency contract](https://github.com/Extra-Chill/data-machine/issues/1633), and [ai-http-client removal](https://github.com/Extra-Chill/data-machine/issues/1027).
+Related blockers: [standalone extraction umbrella](https://github.com/Extra-Chill/data-machine/issues/1596), [standalone skeleton plan](https://github.com/Extra-Chill/data-machine/issues/1618), [in-repo module boundary](https://github.com/Extra-Chill/data-machine/issues/1631), [candidate relocation](https://github.com/Extra-Chill/data-machine/issues/1632), [wp-ai-client dependency contract](https://github.com/Extra-Chill/data-machine/issues/1633), [built-in loop ownership](https://github.com/Extra-Chill/data-machine/issues/1634), and [ai-http-client removal](https://github.com/Extra-Chill/data-machine/issues/1027).
 
 ## Current Strategy
 
@@ -26,6 +26,7 @@ Treat `data-machine/agents-api/` like WordPress core substrate while it still li
 
 - `agents-api` must not import Data Machine product namespaces.
 - Data Machine may import and consume `agents-api` as product code.
+- `agents-api` owns runner interfaces, value objects, and generic contracts first; Data Machine keeps `AIConversationLoop` and the built-in compatibility runner while they still carry Data Machine job, flow, handler, logging, transcript, and legacy result-shape assumptions.
 - Data Machine keeps flows, pipelines, jobs, handlers, queues, retention, pending actions, content operations, and admin UI.
 - Later standalone extraction means moving the already-bounded module into its own plugin/repo and adding plugin bootstrap, release, dependency, and distribution ceremony.
 - `ai-http-client` is not future architecture. It is only packaging precedent for bundled-then-extracted code.
@@ -93,6 +94,20 @@ The current namespace is intentionally mixed while extraction stays in place. Tr
 
 Exit rule for this in-place phase: do not physically move broad namespaces just because they sit under `Engine\AI`. Move only once a class is generic by dependency direction, vocabulary, and tests; otherwise document it as a Data Machine adapter or product surface.
 
+## Built-In Loop Ownership Decision
+
+The in-repo `agents-api` module does not own Data Machine's built-in loop implementation yet. Its current ownership line is the generic contract surface: runner interfaces, request/result value objects, message envelopes, runtime tool declarations, and collaborator contracts that a loop can depend on without knowing Data Machine product concepts.
+
+Data Machine keeps `AIConversationLoop` and `BuiltInAgentConversationRunner` until the compatibility loop no longer needs Data Machine-owned assumptions. The loop must stay outside `agents-api` while it knows about or directly preserves any of these product concerns:
+
+- job, flow, pipeline, flow-step, handler, or queue payload keys.
+- Data Machine logging and transcript metadata.
+- adjacent-handler completion semantics.
+- historical `AIConversationLoop::execute()` result normalization.
+- `ai-http-client` / `chubes_ai_*` provider compatibility.
+
+Future extraction can move a generic loop only after those concerns are pushed behind collaborators such as completion policy, transcript persister, provider caller, request assembler, event sink, and Data Machine adapters. Until then, the enforceable boundary is: `agents-api` defines the contract shape; Data Machine owns the built-in compatibility loop that implements it for existing pipelines and chat callers.
+
 ## Agents API Public Candidate
 
 These are closest to generic public contracts. Most should be extracted as contracts/value objects before services.

docs/development/agents-api-pre-extraction-audit.md

@@ -4,7 +4,7 @@ Parent issue: [Explore splitting Agents API out of Data Machine](https://github.
 
 Strategy issue: [Agents API blocker: update extraction docs around in-repo module strategy](https://github.com/Extra-Chill/data-machine/issues/1640)
 
-Related blockers: [standalone extraction umbrella](https://github.com/Extra-Chill/data-machine/issues/1596), [standalone skeleton plan](https://github.com/Extra-Chill/data-machine/issues/1618), [in-repo module boundary](https://github.com/Extra-Chill/data-machine/issues/1631), [candidate relocation](https://github.com/Extra-Chill/data-machine/issues/1632), [wp-ai-client dependency contract](https://github.com/Extra-Chill/data-machine/issues/1633), and [ai-http-client removal](https://github.com/Extra-Chill/data-machine/issues/1027).
+Related blockers: [standalone extraction umbrella](https://github.com/Extra-Chill/data-machine/issues/1596), [standalone skeleton plan](https://github.com/Extra-Chill/data-machine/issues/1618), [in-repo module boundary](https://github.com/Extra-Chill/data-machine/issues/1631), [candidate relocation](https://github.com/Extra-Chill/data-machine/issues/1632), [wp-ai-client dependency contract](https://github.com/Extra-Chill/data-machine/issues/1633), [built-in loop ownership](https://github.com/Extra-Chill/data-machine/issues/1634), and [ai-http-client removal](https://github.com/Extra-Chill/data-machine/issues/1027).
 
 This audit records the remaining work after the first in-place untangling wave. The boundary is now mostly visible: Data Machine owns pipelines and automation; the future Agents API owns generic agent runtime primitives. The next phase is to make those primitives live behind an in-repo `data-machine/agents-api/` module boundary while they still ship with Data Machine.
 
@@ -27,6 +27,7 @@ Treat `data-machine/agents-api/` like WordPress core substrate while it still li
 - `agents-api` owns the WordPress-shaped agent runtime vocabulary and contracts.
 - Data Machine consumes `agents-api` as product code.
 - `agents-api` must not import Data Machine product namespaces.
+- `agents-api` owns runner interfaces, value objects, and generic contracts first; Data Machine keeps `AIConversationLoop` and the built-in compatibility runner until the loop no longer carries Data Machine job, flow, handler, logging, transcript, or legacy payload/result assumptions.
 - Data Machine keeps flows, pipelines, jobs, handlers, queues, retention, pending actions, content operations, and admin UI.
 - Later standalone extraction means moving the already-bounded module into its own plugin/repo and adding plugin bootstrap, dependency, release, and distribution ceremony.
 
@@ -72,7 +73,7 @@ Before standalone extraction, the in-repo module should satisfy these gates:
 
 ### 1. Runner Facade
 
-`AIConversationLoop` still carries the old runtime name and owns built-in loop execution. It should not be physically extracted until the generic loop and the Data Machine completion/transcript policies are separated further.
+`AIConversationLoop` still carries the old runtime name and owns built-in loop execution. It should not be physically extracted until the generic loop and the Data Machine completion/transcript policies are separated further. The current decision for [#1634](https://github.com/Extra-Chill/data-machine/issues/1634) is to keep `AIConversationLoop` and `BuiltInAgentConversationRunner` in Data Machine, while `agents-api` grows the runner contracts and value objects that a future generic loop would consume.
 
 Target shape:
 
@@ -81,6 +82,7 @@ Target shape:
 - `AIConversationLoop` remains a Data Machine compatibility facade until callers are moved to the new name.
 - `AgentConversationCompletionPolicyInterface` and `AgentConversationTranscriptPersisterInterface` are in-place runtime collaborator seams; Data Machine provides the current handler-completion and transcript adapters.
 - A future `AgentConversationLoop` or `WP_Agent_Runner` should not know about `job_id`, `flow_step_id`, `pipeline_id`, or handler completion policy.
+- The built-in compatibility loop must not move into `agents-api` while it preserves historical `AIConversationLoop::execute()` result normalization, Data Machine logging/transcript metadata, adjacent-handler completion, or `ai-http-client` / `chubes_ai_*` provider compatibility.
 
 ### 2. Runtime Hooks And Filters
 

tests/agents-api-bootstrap-smoke.php

@@ -68,6 +68,8 @@ function assert_agents_api_equals( $expected, $actual, string $name, array &$fai
 assert_agents_api_equals( true, class_exists( 'DataMachine\\Engine\\AI\\AgentConversationResult' ), 'AgentConversationResult contract is available', $failures, $passes );
 assert_agents_api_equals( true, class_exists( 'DataMachine\\Engine\\AI\\Tools\\RuntimeToolDeclaration' ), 'RuntimeToolDeclaration contract is available', $failures, $passes );
 assert_agents_api_equals( false, class_exists( 'DataMachine\\Engine\\Agents\\AgentRegistry', false ), 'Data Machine registry is not loaded by module bootstrap', $failures, $passes );
+assert_agents_api_equals( false, class_exists( 'DataMachine\\Engine\\AI\\AIConversationLoop', false ), 'Data Machine compatibility loop is not loaded by module bootstrap', $failures, $passes );
+assert_agents_api_equals( false, class_exists( 'DataMachine\\Engine\\AI\\BuiltInAgentConversationRunner', false ), 'Data Machine built-in runner is not loaded by module bootstrap', $failures, $passes );
 
 echo "\n[2] Public registration hook collects definitions once and stays side-effect free:\n";
 add_action(
@@ -96,6 +98,7 @@ static function (): void {
 
 echo "\n[3] agents-api files do not import Data Machine product namespaces:\n";
 $forbidden_import = false;
+$forbidden_loop   = false;
 $iterator         = new RecursiveIteratorIterator( new RecursiveDirectoryIterator( __DIR__ . '/../agents-api' ) );
 foreach ( $iterator as $file ) {
 	if ( ! $file->isFile() || 'php' !== $file->getExtension() ) {
@@ -105,10 +108,18 @@ static function (): void {
 	$source = (string) file_get_contents( $file->getPathname() );
 	if ( preg_match( '/(?:use\s+|new\s+|extends\s+|implements\s+|::|instanceof\s+)\\?DataMachine\\\\/', $source ) ) {
 		$forbidden_import = true;
+	}
+
+	if ( preg_match( '/\\b(?:AIConversationLoop|BuiltInAgentConversationRunner)\\b/', $source ) ) {
+		$forbidden_loop = true;
+	}
+
+	if ( $forbidden_import || $forbidden_loop ) {
 		break;
 	}
 }
 assert_agents_api_equals( false, $forbidden_import, 'agents-api has no DataMachine namespace imports', $failures, $passes );
+assert_agents_api_equals( false, $forbidden_loop, 'agents-api does not contain Data Machine loop implementation classes', $failures, $passes );
 
 if ( $failures ) {
 	echo "\nFAILED: " . count( $failures ) . " Agents API bootstrap assertions failed.\n";