V48 (specification-implementation): Extract PTRR base Agent into generic-agents/PTRR

Mirror the SDIVF pipeline extraction for Agents:
- @bitcode/agent-generics keeps Agent primitives (factoryAgent, QuickAgent, steps, substeps)
- @bitcode/generic-agents-ptrr owns PTRRAgent assembly (factoryPTRRAgent / BC factoryAgentWithPTRR)
- Lazy requires avoid agent-generics ↔ PTRR BC re-export load cycles under ts-jest
- Hierarchy docs updated (FAMILIARIZATION, SOURCE_LAYOUT, V48 NOTES)

Author: geraldarthurdavis

BITCODE_SPEC_V48_NOTES.md

@@ -1618,6 +1618,17 @@ not provider packages.
 HostKind `local` replaces `inline` (BITCODE_PIPELINE_HOST; `inline` accepted as alias).
 Spec G3-4 tables updated to LocalHost / hostKind `local`.
 
+## PTRR base Agent extraction (Garrett, 2026-07-13)
+
+```
+@bitcode/agent-generics                        # Agent primitive (factoryAgent, QuickAgent, substeps)
+  → @bitcode/generic-agents-ptrr               # packages/generic-agents/PTRR (PTRRAgent base)
+```
+
+Preferred hierarchy names: `PTRRAgent`, `factoryPTRRAgent`.
+BC: `factoryAgentWithPTRR` / `factoryAgentWithPTRRGenerations` re-exported from agent-generics.
+Mirrors SDIVF extraction: pipelines-generics → generic-pipelines/SDIVF.
+
 ## MCP hierarchy modularization (Garrett, 2026-07-13)
 
 ```

FAMILIARIZATION.md

@@ -147,15 +147,18 @@ Hierarchy names: `Measurement` → `AbsolutesMeasureAgent` →
 @bitcode/generic-generations-failsafes    failsafes/ — prepared-context types + base
 @bitcode/generic-generations-thinkings    thinkings/ — Reason→Judge→StructuredOutput base
         ↑
-@bitcode/agent-generics                   composes failsafes/thinkings into PTRR Agents
+@bitcode/agent-generics                   Agent primitive (factoryAgent, factoryQuickAgent, substeps)
         ↑
-@bitcode/pipeline-asset-pack              product synthesis / phase agents (no reimplementation)
+@bitcode/generic-agents-ptrr              PTRRAgent base (Plan→Try→Refine→Retry)
+        ↑
+@bitcode/generic-agent-* / product agents specialized prompts/tools (no PTRR reimplementation)
 ```
 
-Package path: `packages/generic-generations/{failsafes,thinkings}/`.
+Package paths: `packages/generic-generations/{failsafes,thinkings}/`,
+`packages/generic-agents/PTRR/`.
 
-**PTRR** (Plan / Try / Refine / Retry) is the agent step model. Each step runs a
-**Failsafes** sequence:
+**PTRR** (Plan / Try / Refine / Retry) is the base Agent step model
+(`@bitcode/generic-agents-ptrr`). Each step runs a **Failsafes** sequence:
 
 1. **PrepareConciseContext** — select execution-state *keys* (not values)
 2. **ChunkThenSum** — task generation; chunk only if request too large
@@ -171,7 +174,11 @@ context domain. `@bitcode/context` retains only process-global `GlobalContext`
 LLM-bound failsafe/thinkings **factories** still execute via `AgentExecution`
 inside `agent-generics` until inverted onto pure Execution + LLM registry.
 
-Factories: `factoryAgent`, `factoryAgentWithPTRR` in `agent-generics`.
+| Layer | Type name | Factory |
+| --- | --- | --- |
+| Primitive | `Agent` | `factoryAgent`, `factoryQuickAgent` |
+| Base + primitive | `PTRRAgent` | `factoryPTRRAgent` (`factoryAgentWithPTRR` BC) |
+| Specific | product agents | specialized configs over `factoryPTRRAgent` |
 
 ### 3.2.0 VCS
 

internal-docs/BITCODE_SOURCE_LAYOUT.md

@@ -204,7 +204,7 @@ packages/generic-<family>/          # README only (no package.json)
 
 | Family | Nested examples | Package names |
 | --- | --- | --- |
-| `generic-agents/` | `vcs/`, `danger-wall/`, … | `@bitcode/generic-agents-*` |
+| `generic-agents/` | `PTRR/`, `vcs/`, `danger-wall/`, … | `@bitcode/generic-agents-ptrr`, `@bitcode/generic-agent-*` |
 | `generic-tools/` | `web-search/`, `vcs/`, … | `@bitcode/generic-tools-*` |
 | `generic-pipelines/` | `SDIVF/` | `@bitcode/generic-pipelines-sdivf` (`SDIVFPipeline`) |
 | `generic-llms/` | `xAI/`, `OpenAI/`, `Anthropic/`, `Google/`, `defaults/`, `registry/` | `@bitcode/generic-llms-*` (+ aggregator `@bitcode/generic-llms`) |

packages/agent-generics/README.md

@@ -1,11 +1,24 @@
 # Agent Generics
 
-Agents execute decisions through PTRR methodology with hierarchical prompt accumulation using typed Generations.
+Agent **primitives**: execution, registries, substeps, `factoryAgent` / `factoryQuickAgent`.
+
+## Hierarchy
+
+```
+@bitcode/agent-generics              # this package (Agent primitive)
+        ↑
+@bitcode/generic-agents-ptrr         # PTRRAgent base (Plan→Try→Refine→Retry)
+        ↑
+product / generic-agent-*            # specialized agents
+```
+
+PTRR base factories (`factoryPTRRAgent` / BC `factoryAgentWithPTRR`) live in
+`@bitcode/generic-agents-ptrr` and are re-exported here for compatibility.
 
 ## Quick vs. PTRR Agents
 
-- Agent (PTRR): Canonical, sequences Plan → Try → Refine → Retry. Each generation uses the 3×3 failsafed generation pattern by default.
-- QuickAgent: Minimal, single‑generation agent for setup/utility behaviors where PTRR is unnecessary. Uses standard Execution state and registry access.
+- **PTRRAgent** (`@bitcode/generic-agents-ptrr`): sequences Plan → Try → Refine → Retry. Each generation uses the 3×3 failsafed generation pattern by default.
+- **QuickAgent** (this package): Minimal, single‑generation agent for setup/utility behaviors where PTRR is unnecessary.
 
 Create a QuickAgent:
 

packages/agent-generics/jest.config.cjs

@@ -19,6 +19,8 @@ module.exports = {
     '^@bitcode/asset-packs-settle$': '<rootDir>/../asset-packs/settle/src/index.ts',
     '^@bitcode/agent-generics/agents/factories$': '<rootDir>/../agent-generics/src/agents/factories.ts',
     '^@bitcode/agent-generics/types$': '<rootDir>/../agent-generics/src/types.ts',
+    '^@bitcode/generic-agents-ptrr$': '<rootDir>/../generic-agents/PTRR/src/index.ts',
+    '^@bitcode/generic-agents-ptrr/(.*)$': '<rootDir>/../generic-agents/PTRR/src/$1',
     '^@bitcode/generic-llms$': '<rootDir>/../generic-llms/registry/src/index.ts',
     '^@bitcode/generic-llms/defaults$': '<rootDir>/../generic-llms/defaults/src/index.ts',
     '^@bitcode/generic-llms-defaults$': '<rootDir>/../generic-llms/defaults/src/index.ts',

packages/agent-generics/package.json

@@ -16,6 +16,7 @@
     "@bitcode/generation-generics": "workspace:*",
     "@bitcode/generic-generations-failsafes": "workspace:*",
     "@bitcode/generic-generations-thinkings": "workspace:*",
+    "@bitcode/generic-agents-ptrr": "workspace:*",
     "@bitcode/generic-llms": "workspace:*",
     "@bitcode/prompts": "workspace:*",
     "@bitcode/tools-generics": "workspace:*",
@@ -37,6 +38,13 @@
   "exports": {
     ".": "./src/index.ts",
     "./agents/factories": "./src/agents/factories.ts",
-    "./types": "./src/types.ts"
+    "./types": "./src/types.ts",
+    "./execution": "./src/execution/index.ts",
+    "./substeps/factories": "./src/substeps/factories.ts",
+    "./diagnostics/instrumentation": "./src/diagnostics/instrumentation.ts",
+    "./steps/failsafe-sequence": "./src/steps/failsafe-sequence.ts",
+    "./steps/factories": "./src/steps/factories.ts",
+    "./steps/step-schemas": "./src/steps/step-schemas.ts",
+    "./steps/*": "./src/steps/*"
   }
 }

packages/agent-generics/src/__tests__/factory-agent-ptrr-prompt-hierarchy.test.ts

@@ -1,6 +1,6 @@
 // @ts-nocheck
 import { z } from 'zod';
-import { factoryAgentWithPTRR } from '../agents/factories';
+import { factoryAgentWithPTRR } from '@bitcode/generic-agents-ptrr';
 
 const OutputSchema = z.object({
   ok: z.boolean()
@@ -38,34 +38,34 @@ describe('factoryAgentWithPTRR Bitcode prompt hierarchy', () => {
         prompt: promptRegistry('system'),
         stepPrompts: {
           plan: () => promptRegistry('plan')
-        }
-      } as any)
-    ).toThrow(/missing try, refine, retry step Prompt registries/u);
+        } as any
+      })
+    ).toThrow(/missing try, refine, retry/u);
   });
 
-  it('accepts the explicit prompt plus stepPrompts carrier', () => {
+  it('accepts primary prompt + stepPrompts carrier', () => {
     const agent = factoryAgentWithPTRR({
-      name: 'complete-explicit-prompt-carrier',
+      name: 'primary-carrier',
       outputSchema: OutputSchema,
       prompt: promptRegistry('system'),
       stepPrompts: stepPromptRegistry(),
-      enforceLLM: false
+      enforceLLM: false,
     });
-
+    expect(agent.name).toBe('primary-carrier');
     expect(agent.steps).toHaveLength(4);
   });
 
-  it('accepts the compact prompts carrier with system plus complete PTRR steps', () => {
+  it('accepts compact prompts.system + plan/try/refine/retry carrier', () => {
     const agent = factoryAgentWithPTRR({
-      name: 'complete-compact-prompt-carrier',
+      name: 'compact-carrier',
       outputSchema: OutputSchema,
       prompts: {
         system: promptRegistry('system'),
         ...stepPromptRegistry()
       },
-      enforceLLM: false
+      enforceLLM: false,
     });
-
+    expect(agent.name).toBe('compact-carrier');
     expect(agent.steps).toHaveLength(4);
   });
 });

packages/agent-generics/src/__tests__/ptrr-step-schemas.test.ts

@@ -18,8 +18,17 @@ jest.mock('../steps/factories', () => {
     factoryRetryStep: step('retry'),
   };
 });
+jest.mock('@bitcode/agent-generics/steps/factories', () => {
+  const step = (type: string) => jest.fn(() => Object.assign(async (input: any) => input, { type }));
+  return {
+    factoryPlanStep: step('plan'),
+    factoryTryStep: step('try'),
+    factoryRefineStep: step('refine'),
+    factoryRetryStep: step('retry'),
+  };
+});
 
-import { factoryAgentWithPTRR } from '../agents/factories';
+import { factoryAgentWithPTRR } from '@bitcode/generic-agents-ptrr';
 import { factoryPlanStep, factoryTryStep, factoryRefineStep, factoryRetryStep } from '../steps/factories';
 import { PlanStepOutputSchema } from '../steps/step-schemas';