The VM Eye

The VM Eye: your plan, as the virtual machine saw it. Above the waterline there are tasks and dependencies; below it there are method calls, block invocations, and allocated objects, and the VM counts ALL of them without being asked. TracePoint and GC.stat are the periscope: per task we count every :call and :b_call and every object allocated, we prove from VM evidence alone that each agent ran EXACTLY once, and we weigh the framework itself - the honest price, in method …

source on github

a real captured run

THE VM EYE (nothing is free; the VM has receipts)

  task                     method calls    b_calls   allocations
  hoarder (string churn)              4       5002          5012
  monk (pure arithmetic)              1          2             2
  void (does nothing)                 1          2             0

  the wide-angle ledger: 545 method calls to run the whole plan;
  the agents themselves account for 6, so the framework's keep -
  scheduling, fibers, hooks, bookkeeping - cost 539 calls and
  1241 allocations. that's the price of the machinery that
  makes 'just run these in order with retries' a one-liner.

  exactly-once, per the VM: each workload's :b_call fired once - true
  (not asserted from the framework's bookkeeping - from the VM's)

  what the periscope teaches: allocation profiles are personalities
  (the hoarder's 5012 objects vs the monk's 2 - same wall-clock
  ballpark, different GC futures); the framework tax is REAL and
  measurable and worth every call until it isn't - now you know the
  number to watch; and 'the task ran exactly once' can be verified
  beneath every abstraction, at the level where nothing can lie,
  because the VM was never told what it's looking at. observability
  usually means asking the framework to confess. TracePoint is
  asking the machine.

source

# frozen_string_literal: true

# The VM Eye: your plan, as the virtual machine saw it. Above the
# waterline there are tasks and dependencies; below it there are
# method calls, block invocations, and allocated objects, and the
# VM counts ALL of them without being asked. TracePoint and GC.stat
# are the periscope: per task we count every :call and :b_call and
# every object allocated, we prove from VM evidence alone that each
# agent ran EXACTLY once, and we weigh the framework itself - the
# honest price, in method calls, of running three tasks that do
# nothing. Nothing is free. The VM has receipts.
#
#   bundle exec ruby examples/vm_eye.rb
#
# Runs offline; exits 1 unless the VM's ledger balances.
# (Attribution requires concurrency 1: to observe cleanly, the
# observer must first flatten the schedule. The VM eye changes the
# thing it looks at - it says so on the tin.)

require class="s">"bundler/setup"
require class="s">"agentic"

Agentic.logger.level = class="y">:fatal

# Each lambda's opening line is its VM signature; the inner blocks
# live on their own lines so the signatures stay distinct
WORKLOADS = {
  class="s">"hoarder (string churn)" => lambda {
    5_000.times.map { class="s">"str" * 2 }.last
  },
  class="s">"monk (pure arithmetic)" => lambda {
    (1..50_000).sum
  },
  class="s">"void (does nothing)" => lambda {
  }
}.freeze
LAMBDA_LINES = WORKLOADS.transform_values { |l| l.source_location[1] }.freeze

def with_vm_eye
  stats = {calls: 0, b_calls: 0, lambda_hits: Hash.new(0)}
  tracer = TracePoint.new(class="y">:call, class="y">:b_call) do |tp|
    stats[class="y">:calls] += 1 if tp.event == class="y">:call
    if tp.event == class="y">:b_call
      stats[class="y">:b_calls] += 1
      stats[class="y">:lambda_hits][tp.lineno] += 1 if tp.path == __FILE__
    end
  end
  allocated_before = GC.stat(class="y">:total_allocated_objects)
  tracer.enable
  yield
  tracer.disable
  stats[class="y">:allocations] = GC.stat(class="y">:total_allocated_objects) - allocated_before
  stats
end

# --- per-task periscope: each agent observed alone (hence one lane) -----------------
orchestrator = Agentic:class="y">:PlanOrchestrator.new(concurrency_limit: 1)
per_task = {}
WORKLOADS.each do |name, work|
  task = Agentic:class="y">:Task.new(description: name, agent_spec: {class="s">"name" => name, class="s">"instructions" => class="s">"w"})
  orchestrator.add_task(task, agent: ->(_t) { per_task[name] = with_vm_eye { work.call } and class="y">:done })
end

# the whole plan under one wide-angle lens, framework and all
total = with_vm_eye { orchestrator.execute_plan }

puts class="s">"THE VM EYE (nothing is free; the VM has receipts)"
puts
puts format(class="s">"  %-24s %12s %10s %13s", class="s">"task", class="s">"method calls", class="s">"b_calls", class="s">"allocations")
per_task.each do |name, s|
  puts format(class="s">"  %-24s %12d %10d %13d", name, s[class="y">:calls], s[class="y">:b_calls], s[class="y">:allocations])
end
puts

agent_sum = per_task.values.sum { |s| s[class="y">:calls] }
framework_tax = total[class="y">:calls] - agent_sum
puts class="s">"  the wide-angle ledger: #{total[class="y">:calls]} method calls to run the whole plan;"
puts class="s">"  the agents themselves account for #{agent_sum}, so the framework's keep -"
puts class="s">"  scheduling, fibers, hooks, bookkeeping - cost #{framework_tax} calls and"
puts class="s">"  #{total[class="y">:allocations] - per_task.values.sum { |s| s[class="y">:allocations] }} allocations. that's the price of the machinery that"
puts class="s">"  makes 'just run these in order with retries' a one-liner."
puts

# exactly-once, proven from VM evidence alone: each workload lambda's
# body (identified by source line) fired exactly one :b_call
exactly_once = WORKLOADS.keys.all? { |name| total[class="y">:lambda_hits][LAMBDA_LINES[name]] == 1 }
puts class="s">"  exactly-once, per the VM: each workload's class="y">:b_call fired once - #{exactly_once}"
puts class="s">"  (not asserted from the framework's bookkeeping - from the VM's)"
puts

failures = []
failures << class="s">"exactly-once violated (per the VM)" unless exactly_once
hoarder = per_task[class="s">"hoarder (string churn)"]
monk = per_task[class="s">"monk (pure arithmetic)"]
void = per_task[class="s">"void (does nothing)"]
failures << class="s">"the hoarder didn't hoard" unless hoarder[class="y">:allocations] > 5_000
failures << class="s">"the monk allocated like a hoarder" unless monk[class="y">:allocations] < hoarder[class="y">:allocations] / 50
failures << class="s">"the void was truly free (impossible)" unless void[class="y">:allocations] >= 0 && total[class="y">:calls] > agent_sum

puts class="s">"  what the periscope teaches: allocation profiles are personalities"
puts class="s">"  (the hoarder's #{hoarder[class="y">:allocations]} objects vs the monk's #{monk[class="y">:allocations]} - same wall-clock"
puts class="s">"  ballpark, different GC futures); the framework tax is REAL and"
puts class="s">"  measurable and worth every call until it isn't - now you know the"
puts class="s">"  number to watch; and 'the task ran exactly once' can be verified"
puts class="s">"  beneath every abstraction, at the level where nothing can lie,"
puts class="s">"  because the VM was never told what it's looking at. observability"
puts class="s">"  usually means asking the framework to confess. TracePoint is"
puts class="s">"  asking the machine."
exit(failures.empty? ? 0 : 1)