Token metadata and provenance join for agent writes

Identity facts beyond a display name — harness, harness version, model —
now travel with the token, not the attribution rows. Minting accepts a
schemaless `metadata` JSON object (capped at 4 KB, non-hash input coerced
to {} rather than failing the mint), and every version, event, and
comment an agent writes records `api_token_id` as a provenance join back
to the token that produced it. actor/author stays the human; agent_name
stays the denormalized display string the history UI already renders.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: HamptonMakes

db/migrate/20260815174515_add_agent_provenance.co_plan.rb

@@ -0,0 +1,23 @@
+# This migration comes from co_plan (originally 20260815000002)
+class AddAgentProvenance < ActiveRecord::Migration[8.1]
+  def change
+    # Identity facts (harness, harness version, model, …) live on the token,
+    # captured at mint time — schemaless, because the set of facts worth
+    # recording grows faster than anyone wants to migrate three tables.
+    add_column :coplan_api_tokens, :metadata, :json
+
+    # Attribution rows keep agent_name as the display string, and point at
+    # the token for everything else. actor/author stays the human.
+    add_column :coplan_plan_versions, :api_token_id, :string, limit: 36
+    add_column :coplan_plan_events, :api_token_id, :string, limit: 36
+    add_column :coplan_comments, :api_token_id, :string, limit: 36
+
+    add_index :coplan_plan_versions, :api_token_id
+    add_index :coplan_plan_events, :api_token_id
+    add_index :coplan_comments, :api_token_id
+
+    add_foreign_key :coplan_plan_versions, :coplan_api_tokens, column: :api_token_id
+    add_foreign_key :coplan_plan_events, :coplan_api_tokens, column: :api_token_id
+    add_foreign_key :coplan_comments, :coplan_api_tokens, column: :api_token_id
+  end
+end

db/schema.rb

@@ -32,7 +32,8 @@ def create
             user: current_user,
             actor_type: api_author_type,
             actor_id: api_user_id,
-            agent_name: api_agent_name
+            agent_name: api_agent_name,
+            api_token_id: api_token_id
           )
 
           if result.success?
@@ -63,7 +64,8 @@ def destroy
             metadata: { content_type: content_type },
             actor_type: api_author_type,
             actor_id: api_user_id,
-            agent_name: api_agent_name
+            agent_name: api_agent_name,
+            api_token_id: api_token_id
           )
 
           head :no_content

engine/app/controllers/coplan/api/v1/attachments_controller.rb

@@ -111,6 +111,13 @@ def api_agent_name
           )
         end
 
+        # The provenance join: attribution rows keep the display string in
+        # agent_name and point here for everything else the token knows
+        # about its run (harness, versions, model — see ApiToken#metadata).
+        def api_token_id
+          @api_token&.id
+        end
+
         def set_plan
           @plan = CoPlan::Plan.find_by(id: params[:plan_id] || params[:id])
           unless @plan

engine/app/controllers/coplan/api/v1/base_controller.rb

@@ -21,7 +21,8 @@ def create
             author_type: api_author_type,
             author_id: current_user&.id,
             body_markdown: params[:body_markdown],
-            agent_name: api_agent_name
+            agent_name: api_agent_name,
+            api_token_id: api_token_id
           )
 
           reason = comment.agent? ? "agent_response" : "new_comment"
@@ -131,7 +132,8 @@ def reply
             author_type: api_author_type,
             author_id: current_user&.id,
             body_markdown: params[:body_markdown],
-            agent_name: api_agent_name
+            agent_name: api_agent_name,
+            api_token_id: api_token_id
           )
 
           reason = comment.agent? ? "agent_response" : "reply"

engine/app/controllers/coplan/api/v1/comments_controller.rb

@@ -42,6 +42,7 @@ def update
             actor_type: api_author_type,
             actor_id: api_user_id,
             agent_name: api_agent_name,
+            api_token_id: api_token_id,
             change_summary: params[:change_summary],
             reason: params[:reason]
           )

engine/app/controllers/coplan/api/v1/content_controller.rb

@@ -136,6 +136,7 @@ def organize
             actor_type: api_author_type,
             actor_label: @api_token&.name,
             agent_name: api_agent_name,
+            api_token_id: api_token_id,
             dry_run: params[:dry_run].to_s == "true"
           )
           unless result.success?

engine/app/controllers/coplan/api/v1/libraries_controller.rb

@@ -213,6 +213,7 @@ def commit_version(current_content, result)
             actor_type: api_author_type,
             actor_id: api_user_id,
             agent_name: api_agent_name,
+            api_token_id: api_token_id,
             change_summary: params[:change_summary],
             diff_unified: diff.presence,
             operations_json: result[:applied],

engine/app/controllers/coplan/api/v1/operations_controller.rb

@@ -106,7 +106,7 @@ def update
             if params.key?(:folder_id) || params.key?(:folder_path)
               folder = resolve_folder_params
               return if performed? # resolve_folder_params rendered an error
-              result = Plans::Place.call(plan: @plan, folder: folder, actor: current_user, actor_type: api_author_type, agent_name: api_agent_name)
+              result = Plans::Place.call(plan: @plan, folder: folder, actor: current_user, actor_type: api_author_type, agent_name: api_agent_name, api_token_id: api_token_id)
               unless result.success?
                 render json: { error: result.error }, status: :unprocessable_content
                 raise ActiveRecord::Rollback
@@ -126,15 +126,15 @@ def update
             Plans::LogEvent.call(
               plan: @plan, actor: current_user, event_type: "title_changed",
               before: old_title, after: @plan.title,
-              actor_type: api_author_type, actor_id: api_user_id, agent_name: api_agent_name
+              actor_type: api_author_type, actor_id: api_user_id, agent_name: api_agent_name, api_token_id: api_token_id
             )
           end
 
           if @plan.saved_change_to_visibility? && @plan.published? && old_visibility == "draft"
             Plans::LogEvent.call(
               plan: @plan, actor: current_user, event_type: "published",
               before: "draft", after: "published",
-              actor_type: api_author_type, actor_id: api_user_id, agent_name: api_agent_name
+              actor_type: api_author_type, actor_id: api_user_id, agent_name: api_agent_name, api_token_id: api_token_id
             )
             CoPlan::Analytics.track(
               "plan_published",
@@ -149,7 +149,7 @@ def update
             Plans::LogEvent.call(
               plan: @plan, actor: current_user,
               event_type: @plan.archived? ? "archived" : "unarchived",
-              actor_type: api_author_type, actor_id: api_user_id, agent_name: api_agent_name
+              actor_type: api_author_type, actor_id: api_user_id, agent_name: api_agent_name, api_token_id: api_token_id
             )
           end
 
@@ -158,13 +158,13 @@ def update
             (new_tag_names - old_tag_names).each do |added|
               Plans::LogEvent.call(
                 plan: @plan, actor: current_user, event_type: "tag_added", after: added,
-                actor_type: api_author_type, actor_id: api_user_id, agent_name: api_agent_name
+                actor_type: api_author_type, actor_id: api_user_id, agent_name: api_agent_name, api_token_id: api_token_id
               )
             end
             (old_tag_names - new_tag_names).each do |removed|
               Plans::LogEvent.call(
                 plan: @plan, actor: current_user, event_type: "tag_removed", before: removed,
-                actor_type: api_author_type, actor_id: api_user_id, agent_name: api_agent_name
+                actor_type: api_author_type, actor_id: api_user_id, agent_name: api_agent_name, api_token_id: api_token_id
               )
             end
           end
@@ -183,7 +183,7 @@ def update
                 Plans::LogEvent.call(
                   plan: @plan, actor: current_user, event_type: "reference_added",
                   after: ref.url, metadata: { title: ref.title, reference_type: ref.reference_type },
-                  actor_type: api_author_type, actor_id: api_user_id, agent_name: api_agent_name
+                  actor_type: api_author_type, actor_id: api_user_id, agent_name: api_agent_name, api_token_id: api_token_id
                 )
               end
             end

engine/app/controllers/coplan/api/v1/plans_controller.rb

@@ -41,7 +41,8 @@ def commit
             session: @session,
             change_summary: params[:change_summary],
             actor_id: api_user_id,
-            agent_name: api_agent_name
+            agent_name: api_agent_name,
+            api_token_id: api_token_id
           )
 
           response = {