reactifact 0.16.0__tar.gz → 0.16.1__tar.gz

{reactifact-0.16.0/reactifact.egg-info → reactifact-0.16.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reactifact
-Version: 0.16.0
+Version: 0.16.1
 Summary: Reactive, artifact-driven agent runtime: agents transform versioned, typed, provenance-aware artifacts inside an evolving context
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/bzdvdn/reactifact

{reactifact-0.16.0 → reactifact-0.16.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "reactifact"
-version = "0.16.0"
+version = "0.16.1"
 description = "Reactive, artifact-driven agent runtime: agents transform versioned, typed, provenance-aware artifacts inside an evolving context"
 readme = "README.md"
 requires-python = ">=3.11"

{reactifact-0.16.0 → reactifact-0.16.1}/reactifact/__init__.py

@@ -51,7 +51,7 @@ from .tools import FunctionTool, Tool, ToolError, ToolOutput, tool
 from .triggers import Trigger
 from .types import register as register_type
 
-__version__ = "0.16.0"
+__version__ = "0.16.1"
 
 __all__ = [
     "Agent",

{reactifact-0.16.0 → reactifact-0.16.1}/reactifact/tracing/__init__.py

@@ -9,6 +9,7 @@ from ..tools import ToolRun
 from .columns import TraceColumn
 from .langfuse import LangfuseTracer
 from .models import (
+    AgentContract,
     AgentSpan,
     ArtifactRef,
     LLMCall,
@@ -30,6 +31,7 @@ from .store import (
 from .tracer import CompositeTracer, RecordingLLM, RunTracer, Tracer
 
 __all__ = [
+    "AgentContract",
     "AgentSpan",
     "ArtifactRef",
     "CompositeTracer",

{reactifact-0.16.0 → reactifact-0.16.1}/reactifact/tracing/models.py

@@ -90,6 +90,20 @@ class TagAssignment(BaseModel):
     updated_at: datetime | None = None
 
 
+class AgentContract(BaseModel):
+    """The agent's declared contract, recorded on each span for the UI.
+
+    `consumes`/`produces`/`tools` are the *declared* names (not only what ran),
+    so the dashboard can show a consume/produce that never fired as a muted
+    chip instead of hiding it.
+    """
+
+    consumes: list[str] = Field(default_factory=list)
+    produces: list[str] = Field(default_factory=list)
+    tools: list[str] = Field(default_factory=list)
+    priority: int = 0
+
+
 class ProduceRun(BaseModel):
     """One produce execution within an agent span (§54).
 
@@ -113,6 +127,10 @@ class AgentSpan(BaseModel):
     #: ``Consume``) — e.g. ``DraftAnswer`` vs ``FinalResponse`` for an agent that
     #: consumes both. ``event_type`` alone (created/updated) can't tell them apart.
     event_artifact_type: str = ""
+    #: The concrete artifact whose change triggered this span.
+    event_artifact_id: str = ""
+    #: The agent's declared consumes/produces/tools (for the UI contract view).
+    contract: AgentContract = Field(default_factory=AgentContract)
     #: The produces that ran for this event, in execution order.
     produces: list[ProduceRun] = Field(default_factory=list)
     #: Tool executions that happened during this agent run (name/latency/status).

{reactifact-0.16.0 → reactifact-0.16.1}/reactifact/tracing/postgres.py

@@ -25,6 +25,7 @@ from typing import Any
 from ..tools import ToolRun
 from .columns import SpanArtifacts, TraceColumn, extract_columns
 from .models import (
+    AgentContract,
     AgentSpan,
     ArtifactRef,
     LLMCall,
@@ -81,7 +82,9 @@ class PostgresStore:
                         relations JSONB NOT NULL DEFAULT '[]',
                         llm_calls JSONB NOT NULL DEFAULT '[]',
                         produces JSONB NOT NULL DEFAULT '[]',
-                        tools JSONB NOT NULL DEFAULT '[]'
+                        tools JSONB NOT NULL DEFAULT '[]',
+                        event_artifact_id TEXT NOT NULL DEFAULT '',
+                        contract JSONB NOT NULL DEFAULT '{}'
                     )
                     """
                 )
@@ -139,6 +142,14 @@ class PostgresStore:
                     "ALTER TABLE spans ADD COLUMN IF NOT EXISTS "
                     "tools JSONB NOT NULL DEFAULT '[]'"
                 )
+                await cur.execute(
+                    "ALTER TABLE spans ADD COLUMN IF NOT EXISTS "
+                    "event_artifact_id TEXT NOT NULL DEFAULT ''"
+                )
+                await cur.execute(
+                    "ALTER TABLE spans ADD COLUMN IF NOT EXISTS "
+                    "contract JSONB NOT NULL DEFAULT '{}'"
+                )
             await conn.commit()
         finally:
             await conn.close()
@@ -178,8 +189,8 @@ class PostgresStore:
                     await cur.execute(
                         "INSERT INTO spans (run_id, agent, event_type, event_artifact_type, "
                         "latency_ms, error, started_at, reads, writes, relations, llm_calls, "
-                        "produces, tools) "
-                        "VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s)",
+                        "produces, tools, event_artifact_id, contract) "
+                        "VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s)",
                         (
                             trace.id,
                             span.agent,
@@ -206,6 +217,10 @@ class PostgresStore:
                             psycopg.types.json.Jsonb(
                                 [tr.model_dump(mode="json") for tr in span.tools]
                             ),
+                            span.event_artifact_id,
+                            psycopg.types.json.Jsonb(
+                                span.contract.model_dump(mode="json")
+                            ),
                         ),
                     )
             await conn.commit()
@@ -413,7 +428,8 @@ class PostgresStore:
                     return None
                 await cur.execute(
                     "SELECT agent, event_type, event_artifact_type, latency_ms, error, "
-                    "started_at, reads, writes, relations, llm_calls, produces, tools "
+                    "started_at, reads, writes, relations, llm_calls, produces, tools, "
+                    "event_artifact_id, contract "
                     "FROM spans WHERE run_id = %s ORDER BY id",
                     (trace_id,),
                 )
@@ -443,6 +459,8 @@ class PostgresStore:
                 llm_calls=[LLMCall(**d) for d in r[9]],
                 produces=[ProduceRun(**d) for d in r[10]],
                 tools=[ToolRun(**d) for d in r[11]],
+                event_artifact_id=r[12],
+                contract=AgentContract(**r[13]),
             )
             for r in span_rows
         ]

{reactifact-0.16.0 → reactifact-0.16.1}/reactifact/tracing/store.py

@@ -28,6 +28,7 @@ from typing import Any, Protocol
 from ..tools import ToolRun
 from .columns import SpanArtifacts, TraceColumn, extract_columns
 from .models import (
+    AgentContract,
     AgentSpan,
     ArtifactRef,
     LLMCall,
@@ -185,7 +186,9 @@ class TraceStore:
                 relations TEXT NOT NULL DEFAULT '[]',
                 llm_calls TEXT NOT NULL DEFAULT '[]',
                 produces TEXT NOT NULL DEFAULT '[]',
-                tools TEXT NOT NULL DEFAULT '[]'
+                tools TEXT NOT NULL DEFAULT '[]',
+                event_artifact_id TEXT NOT NULL DEFAULT '',
+                contract TEXT NOT NULL DEFAULT '{}'
             );
             CREATE TABLE IF NOT EXISTS tags (
                 name TEXT PRIMARY KEY,
@@ -235,6 +238,14 @@ class TraceStore:
             self._conn.execute(
                 "ALTER TABLE spans ADD COLUMN tools TEXT NOT NULL DEFAULT '[]'"
             )
+        if "event_artifact_id" not in cols:
+            self._conn.execute(
+                "ALTER TABLE spans ADD COLUMN event_artifact_id TEXT NOT NULL DEFAULT ''"
+            )
+        if "contract" not in cols:
+            self._conn.execute(
+                "ALTER TABLE spans ADD COLUMN contract TEXT NOT NULL DEFAULT '{}'"
+            )
         run_cols = {row[1] for row in self._conn.execute("PRAGMA table_info(runs)")}
         if "prompt_tokens" not in run_cols:
             self._conn.execute(
@@ -347,8 +358,8 @@ class TraceStore:
             self._conn.execute(
                 "INSERT INTO spans (run_id, agent, event_type, event_artifact_type, "
                 "latency_ms, error, started_at, reads, writes, relations, llm_calls, "
-                "produces, tools) "
-                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                "produces, tools, event_artifact_id, contract) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
                 (
                     trace.id,
                     span.agent,
@@ -363,6 +374,8 @@ class TraceStore:
                     json.dumps([c.model_dump(mode="json") for c in span.llm_calls]),
                     json.dumps([p.model_dump(mode="json") for p in span.produces]),
                     json.dumps([t.model_dump(mode="json") for t in span.tools]),
+                    span.event_artifact_id,
+                    json.dumps(span.contract.model_dump(mode="json")),
                 ),
             )
         self._conn.commit()
@@ -617,7 +630,8 @@ class TraceStore:
             return None
         span_rows = self._conn.execute(
             "SELECT agent, event_type, event_artifact_type, latency_ms, error, started_at, "
-            "reads, writes, relations, llm_calls, produces, tools "
+            "reads, writes, relations, llm_calls, produces, tools, "
+            "event_artifact_id, contract "
             "FROM spans WHERE run_id = ? ORDER BY id",
             (trace_id,),
         ).fetchall()
@@ -637,6 +651,8 @@ class TraceStore:
                 llm_calls=[LLMCall(**d) for d in json.loads(r[9])],
                 produces=[ProduceRun(**d) for d in json.loads(r[10])],
                 tools=[ToolRun(**d) for d in json.loads(r[11])],
+                event_artifact_id=r[12],
+                contract=AgentContract(**json.loads(r[13])),
             )
             for r in span_rows
         ]

{reactifact-0.16.0 → reactifact-0.16.1}/reactifact/tracing/templates/app.css

@@ -6,6 +6,7 @@
   --text:#17171f; --muted:#6b6b7a; --faint:#9a9aae;
   --accent:#4f46e5; --accent-soft:#eef0ff; --accent-strong:#4338ca;
   --ok:#15803d; --ok-soft:#e9f7ef; --err:#b91c1c; --err-soft:#fdeeee;
+  --tool:#b45309; --tool-soft:#fdf1e3;
   --warn:#b45309; --warn-soft:#fef3c7; --hover:#f3f3f7; --chip:#eef0ff; --chip-text:#4338ca;
   --shadow-sm:0 1px 2px rgba(16,16,30,.05);
   --shadow:0 1px 2px rgba(16,16,30,.04),0 4px 14px rgba(16,16,30,.06);
@@ -20,6 +21,7 @@ html.dark{
   --text:#e8e8f0; --muted:#9a9aae; --faint:#6f6f82;
   --accent:#8b93ff; --accent-soft:#232448; --accent-strong:#a9b1ff;
   --ok:#3ecf7c; --ok-soft:#123522; --err:#f97c7c; --err-soft:#3c1718;
+  --tool:#fbbf24; --tool-soft:#3a2a10;
   --warn:#fbbf24; --warn-soft:#3a2c0c; --hover:#1e1f29; --chip:#262a48; --chip-text:#a9b1ff;
   --shadow-sm:0 1px 2px rgba(0,0,0,.4);
   --shadow:0 1px 2px rgba(0,0,0,.4),0 8px 24px rgba(0,0,0,.35);
@@ -274,6 +276,24 @@ details.agent>summary:hover{background:var(--hover);}
 .chip.produce.noop{background:var(--panel-alt);color:var(--muted);border:1px solid var(--border);}
 .chip.produce .ops{background:rgba(21,128,61,.16);color:var(--ok);border-radius:7px;padding:0 6px;font-size:10px;font-variant-numeric:tabular-nums;}
 .chip.produce.noop .ops.zero{background:var(--border);color:var(--faint);}
+.chip.tool{background:var(--tool-soft);color:var(--tool);}
+.consume{display:inline-flex;align-items:center;gap:4px;font-family:var(--mono);font-size:11.5px;color:var(--chip-text);background:var(--chip);border-radius:6px;padding:1px 7px;white-space:nowrap;}
+.consume.muted{color:var(--muted);background:transparent;border:1px dashed var(--border-strong);}
+.tl-track-wrap{min-width:0;}
+.chip.muted,.consume.muted{opacity:.55;}
+[data-filter-kind]{cursor:pointer;}
+[data-filter-kind].active{outline:2px solid var(--accent);outline-offset:1px;}
+.contract-flow{display:inline-flex;align-items:center;gap:6px;flex-wrap:wrap;min-width:0;}
+.cf-label{font-size:10px;text-transform:uppercase;letter-spacing:.45px;color:var(--muted);white-space:nowrap;}
+.trigger{display:inline-flex;align-items:center;gap:5px;font-size:11px;color:var(--muted);white-space:nowrap;}
+.trigger code{font-size:10.5px;}
+.produce-row{display:flex;align-items:center;gap:8px;padding:3px 0;font-size:12px;}
+.produce-row.muted{opacity:.6;}
+.filter-note{display:flex;align-items:center;gap:8px;margin:0 0 10px;font-size:12px;color:var(--muted);}
+.tl-subs{position:relative;height:8px;margin-top:2px;}
+.tl-sub{position:absolute;top:0;height:6px;border-radius:3px;opacity:.9;min-width:2px;}
+.tl-sub.produce{background:var(--ok);}
+.tl-sub.tool{background:var(--tool);}
 .spans{display:flex;flex-direction:column;gap:8px;}
 details.node{border:1px solid var(--border);border-left:3px solid var(--accent);border-radius:var(--r-sm);background:var(--panel);overflow:hidden;}
 details.node summary{display:flex;align-items:center;gap:10px;padding:9px 14px;cursor:pointer;font-size:13px;}

{reactifact-0.16.0 → reactifact-0.16.1}/reactifact/tracing/templates/ui_run.html

@@ -57,6 +57,7 @@
           <h2>Work</h2>
           <div class="spacer"></div>
           <input class="input" id="trace-search" type="search" placeholder="search spans…" style="min-width:180px"/>
+          <span id="chip-filter" class="hint"></span>
           <div class="seg" id="view-seg">
             <button class="seg-btn active" data-view="tree">Tree</button>
             <button class="seg-btn" data-view="timeline">Timeline</button>
@@ -186,7 +187,8 @@ function artsBlock(arts){
   return chips+'<div class="art-list">'+first+'<details class="io-more" open><summary>… + '+(n-SHOWN)+' more</summary>'+rest+'</details></div>';
 }
 
-let TRACE=null,VIEW='tree',FILTER='';
+let TRACE=null,VIEW='tree',FILTER='',CHIP_FILTER=null;
+const AGENT_CONTRACTS={};
 function render(t){
   TRACE=t;
   document.title='Trace #'+t.id+' · reactifact';
@@ -218,8 +220,30 @@ function renderFields(fields){
       '<div class="fv'+(empty?' empty':'')+'">'+escapeHtml(empty?'—':String(v))+'</div></div>';
   }).join('');
 }
+function uniq(a){return [...new Set(a.filter(Boolean))];}
+function shortId(id){return id?String(id).slice(0,8):'';}
+function chipHtml(kind,value,opts){
+  opts=opts||{};
+  const cls=kind==='consume'?'consume':'chip '+kind;
+  const active=CHIP_FILTER&&CHIP_FILTER.kind===kind&&CHIP_FILTER.value===value;
+  const count=opts.count?' <span class="ops">'+opts.count+'</span>':'';
+  return '<span class="'+cls+(opts.muted?' muted':'')+(active?' active':'')+'" '+
+    'data-filter-kind="'+kind+'" data-filter-value="'+escapeHtml(value)+'" '+
+    'title="'+escapeHtml(opts.title||value)+'">'+escapeHtml(value)+count+'</span>';
+}
+function contractOf(agent,list){
+  const withContract=list.find(s=>s.contract&&((s.contract.consumes||[]).length||(s.contract.produces||[]).length||(s.contract.tools||[]).length));
+  return withContract?withContract.contract:{consumes:[],produces:[],tools:[],priority:0};
+}
 function spanMatches(s,f){
-  const hay=[s.agent,s.event_type,s.event_artifact_type||'',s.error||''];
+  if(CHIP_FILTER){
+    const k=CHIP_FILTER.kind,v=CHIP_FILTER.value,c=s.contract||{};
+    if(k==='consume'&&!(s.event_artifact_type===v||(s.reads||[]).some(a=>a.data_type===v)||(c.consumes||[]).includes(v)))return false;
+    if(k==='produce'&&!((s.produces||[]).some(p=>p.name===v)||(c.produces||[]).includes(v)))return false;
+    if(k==='tool'&&!((s.tools||[]).some(t=>t.tool===v)||(c.tools||[]).includes(v)))return false;
+  }
+  if(!f)return true;
+  const hay=[s.agent,s.event_type,s.event_artifact_type||'',s.event_artifact_id||'',s.error||''];
   for(const p of (s.produces||[]))hay.push(p.name||'');
   for(const a of (s.reads||[]).concat(s.writes||[]))hay.push(a.data_type||'',a.data||'');
   for(const c of (s.llm_calls||[]))hay.push(c.provider||'',c.model||'',c.response||'',...(c.messages||[]).map(m=>m.content||''));
@@ -227,7 +251,11 @@ function spanMatches(s,f){
 }
 function renderWork(){
   const spans=(TRACE&&TRACE.spans)||[];const f=FILTER.trim().toLowerCase();
-  const filtered=f?spans.filter(s=>spanMatches(s,f)):spans;
+  const filtered=spans.filter(s=>spanMatches(s,f));
+  const cf=document.getElementById('chip-filter');
+  if(cf)cf.innerHTML=CHIP_FILTER
+    ? 'filter: '+escapeHtml(CHIP_FILTER.kind)+' '+escapeHtml(CHIP_FILTER.value)+' <button class="btn sm" data-clear-filter>clear</button>'
+    : '';
   if(VIEW==='timeline')renderTimeline(filtered);else renderTree(filtered);
 }
 function renderTree(spans){
@@ -253,57 +281,85 @@ function renderTimeline(spans){
     const prods=(s.produces||[]).map(p=>p.name).join('+');
     const toolCount=(s.tools||[]).length;
     const label=escapeHtml(s.agent)+' · '+escapeHtml(s.event_artifact_type||s.event_type||'span')+(prods?' → '+escapeHtml(prods):'')+(toolCount?' · '+toolCount+' tools':'');const llm=(s.llm_calls||[]).length;
+    let subs='';let pcursor=r.start;
+    for(const p of (s.produces||[])){
+      const w=Math.max(0.3,(Number(p.latency_ms)||0)/total*100);
+      subs+='<span class="tl-sub produce" style="left:'+(pcursor/total*100)+'%;width:'+w+'%" title="'+escapeHtml(p.name)+' — '+Number(p.latency_ms||0).toFixed(1)+' ms"></span>';
+      pcursor+=Number(p.latency_ms)||0;
+    }
+    for(const tool of (s.tools||[])){
+      let ts=r.start;
+      if(tool.started_at){const d=new Date(tool.started_at).getTime()-origin;if(isFinite(d))ts=Math.max(0,d);}
+      const w=Math.max(0.3,(Number(tool.latency_ms)||0)/total*100);
+      subs+='<span class="tl-sub tool" style="left:'+(ts/total*100)+'%;width:'+w+'%" title="'+escapeHtml(tool.tool)+' — '+Number(tool.latency_ms||0).toFixed(1)+' ms"></span>';
+    }
     html+='<div class="tl-row"><div class="tl-label" title="'+label+'">'+label+(llm?' <span class="sub">'+llm+' llm</span>':'')+'</div>'+
-      '<div class="tl-track"><div class="tl-bar'+(s.error?' err':'')+'" style="left:'+left+'%;width:'+width+'%" title="'+label+' — '+r.dur.toFixed(1)+' ms"><span class="lbl">'+r.dur.toFixed(0)+' ms</span></div></div></div>';
+      '<div class="tl-track-wrap"><div class="tl-track"><div class="tl-bar'+(s.error?' err':'')+'" style="left:'+left+'%;width:'+width+'%" title="'+label+' — '+r.dur.toFixed(1)+' ms"><span class="lbl">'+r.dur.toFixed(0)+' ms</span></div></div>'+
+      (subs?'<div class="tl-subs">'+subs+'</div>':'')+'</div></div>';
   }
   el.innerHTML=html+'</div>';
 }
 function agentHtml(agent,list){
-  const ms=list.reduce((a,s)=>a+Number(s.latency_ms||0),0)/list.length;let writes=0,llm=0;const readsAgg={};
-  for(const s of list){writes+=(s.writes||[]).length;llm+=(s.llm_calls||[]).length;
-    for(const r of s.reads||[]){const t=r.data_type||'artifact';readsAgg[t]=(readsAgg[t]||0)+1;}}
-  const chips=Object.entries(readsAgg).map(([t,n])=>'<span class="chip">'+escapeHtml(t)+' '+n+'</span>').join('');
-  const consumes=[...new Set(list.map(s=>s.event_artifact_type).filter(Boolean))];
-  const prods=[...new Set(list.flatMap(s=>(s.produces||[]).map(p=>p.name)))];
-  const flow=(consumes.length||prods.length)
-    ? '<span class="flow"><span class="c-side">'+consumes.map(c=>'<span class="consume">'+escapeHtml(c)+'</span>').join('')+
-      '</span><span class="arrow">→</span><span class="produces">'+prods.map(n=>'<span class="chip produce">'+escapeHtml(n)+'</span>').join('')+'</span></span>'
-    : '';
+  const contract=contractOf(agent,list);AGENT_CONTRACTS[agent]=contract;
+  const actualConsumes=uniq(list.flatMap(s=>[s.event_artifact_type,...(s.reads||[]).map(r=>r.data_type)]));
+  const actualProduces=uniq(list.flatMap(s=>(s.produces||[]).map(p=>p.name)));
+  const actualTools=uniq(list.flatMap(s=>(s.tools||[]).map(t=>t.tool)));
+  const consumes=uniq([...(contract.consumes||[]),...actualConsumes]);
+  const produces=uniq([...(contract.produces||[]),...actualProduces]);
+  const tools=uniq([...(contract.tools||[]),...actualTools]);
+  const consumeChips=consumes.map(v=>chipHtml('consume',v,{muted:!actualConsumes.includes(v)})).join('');
+  const produceChips=produces.map(v=>chipHtml('produce',v,{muted:!actualProduces.includes(v)})).join('');
+  const toolChips=tools.map(v=>chipHtml('tool',v,{muted:!actualTools.includes(v)})).join('');
+  let writes=0,llm=0,total=0;
+  for(const s of list){writes+=(s.writes||[]).length;llm+=(s.llm_calls||[]).length;total+=Number(s.latency_ms||0);}
+  const flow='<span class="contract-flow"><span class="cf-label">consumes</span>'+consumeChips+
+    '<span class="arrow">→</span><span class="cf-label">produces</span>'+produceChips+'</span>';
   return '<details class="agent" open><summary><span class="caret">▸</span><b>'+escapeHtml(agent)+'</b>'+
     flow+
-    '<span class="muted">'+list.length+' spans · '+ms.toFixed(1)+' ms avg</span>'+
-    '<span class="stat">'+writes+' writes · '+llm+' llm</span></summary>'+
-    '<div class="agent-body">'+(chips?'<div class="chips">'+chips+'</div>':'')+
-    '<div class="spans">'+list.map(spanHtml).join('')+'</div></div></details>';
+    '<span class="muted">'+list.length+' spans · '+(total/list.length).toFixed(1)+' ms avg</span>'+
+    '<span class="stat">'+writes+' writes · '+llm+' llm'+(actualTools.length?' · '+actualTools.length+' tools':'')+'</span>'+
+    '<button class="btn sm" data-contract-agent="'+escapeHtml(agent)+'">contract</button></summary>'+
+    '<div class="agent-body">'+
+      (toolChips?'<div class="chips"><span class="cf-label">tools</span>'+toolChips+'</div>':'')+
+      '<div class="spans">'+list.map(spanHtml).join('')+'</div></div></details>';
 }
 function spanHtml(s){
   const ok=!s.error;const errBlock=s.error?'<div class="err-box">'+escapeHtml(s.error)+'</div>':'';
-  const reads=(s.reads||[]).length?('<div class="io"><h3>reads</h3>'+artsBlock(s.reads)+'</div>'):'';
-  const writes=(s.writes||[]).length?('<div class="io"><h3>writes</h3>'+artsBlock(s.writes)+'</div>'):'';
+  const c=s.contract||{};
+  const actualConsumes=uniq([s.event_artifact_type,...(s.reads||[]).map(r=>r.data_type)]);
+  const actualProduces=uniq((s.produces||[]).map(p=>p.name));
+  const consumes=uniq([...(c.consumes||[]),...actualConsumes]);
+  const produces=uniq([...(c.produces||[]),...actualProduces]);
+  const consumeChips=consumes.map(v=>chipHtml('consume',v,{muted:!actualConsumes.includes(v)})).join('');
+  const produceChips=produces.map(v=>chipHtml('produce',v,{muted:!actualProduces.includes(v)})).join('');
+  const trigger=s.event_artifact_type
+    ? '<span class="trigger">triggered by '+chipHtml('consume',s.event_artifact_type,{title:'artifact '+(s.event_artifact_id||'')})+
+      (s.event_artifact_id?' <code>'+escapeHtml(shortId(s.event_artifact_id))+'</code>':'')+'</span>'
+    : '<span class="trigger">event '+escapeHtml(s.event_type||'')+'</span>';
+  const flow='<span class="contract-flow"><span class="cf-label">consumes</span>'+consumeChips+
+    '<span class="arrow">→</span><span class="cf-label">produces</span>'+produceChips+'</span>';
+  const reads=(s.reads||[]).length?('<div class="io"><h3>Consumes / inputs</h3>'+artsBlock(s.reads)+'</div>'):'';
+  const writes=(s.writes||[]).length?('<div class="io"><h3>Outputs / writes</h3>'+artsBlock(s.writes)+'</div>'):'';
   const io=(reads||writes)?'<div class="io-grid">'+reads+writes+'</div>':'';
   const llm=(s.llm_calls||[]).map(llmHtml).join('');
   const toolCount=(s.tools||[]).length;
   return '<details class="node"><summary>'+
     '<span class="caret">▸</span><span class="s-dot '+(ok?'ok':'err')+'"></span>'+
-    '<span class="nid">'+escapeHtml(s.agent)+'</span>'+
-    flowHtml(s.event_artifact_type, s.event_type, s.produces)+
+    '<span class="nid">'+escapeHtml(s.agent)+'</span>'+trigger+
+    flow+
     '<span class="stat">'+Number(s.latency_ms).toFixed(1)+' ms · '+(s.llm_calls||[]).length+' llm'+(toolCount?' · '+toolCount+' tools':'')+(ok?'':' · failed')+'</span></summary>'+
-    '<div class="node-body">'+errBlock+io+toolsBlock(s.tools)+(llm?'<div class="llm"><h3>LLM calls</h3>'+llm+'</div>':'')+'</div></details>';
+    '<div class="node-body">'+errBlock+io+producesBlock(s.produces,c)+toolsBlock(s.tools)+(llm?'<div class="llm"><h3>LLM calls</h3>'+llm+'</div>':'')+'</div></details>';
 }
-function flowHtml(consume, eventType, produces){
-  const c=consume
-    ? '<span class="consume" title="Consume — artifact whose change triggered this agent">'+escapeHtml(consume)+'</span>'
-    : '<span class="consume muted">event</span>';
-  const ev=eventType?'<span class="ev">'+escapeHtml(eventType)+'</span>':'';
-  const list=produces||[];
-  const right=list.length?list.map(produceChip).join(''):'<span class="muted">no produce ran</span>';
-  return '<span class="flow"><span class="c-side">'+c+ev+'</span>'+
-    '<span class="arrow" aria-hidden="true">→</span><span class="produces">'+right+'</span></span>';
-}
-function produceChip(p){
-  const ops=Number(p.operations||0);const ms=Number(p.latency_ms||0);
-  return '<span class="chip produce'+(ops?'':' noop')+'" title="'+escapeHtml(p.name)+' — '+ms.toFixed(1)+' ms">'+
-    escapeHtml(p.name)+'<span class="ops'+(ops?'':' zero')+'">'+(ops?('+'+ops):'0')+'</span></span>';
+function producesBlock(list,contract){
+  const actual=list||[];const declared=(contract&&contract.produces)||[];
+  const names=uniq([...declared,...actual.map(p=>p.name)]);
+  if(!names.length)return '';
+  const rows=names.map(n=>{
+    const p=actual.find(x=>x.name===n);
+    if(!p)return '<div class="produce-row muted"><span class="chip produce muted">'+escapeHtml(n)+'</span><span class="muted">did not run</span></div>';
+    return '<div class="produce-row"><span class="chip produce" data-filter-kind="produce" data-filter-value="'+escapeHtml(n)+'">'+escapeHtml(n)+'</span><span class="muted">'+Number(p.operations||0)+' ops · '+Number(p.latency_ms||0).toFixed(1)+' ms</span></div>';
+  }).join('');
+  return '<div class="llm"><h3>Produces</h3>'+rows+'</div>';
 }
 function artHtml(a){
   const op=('<span class="tag">'+escapeHtml(a.op_type||'read')+'</span>');
@@ -453,10 +509,26 @@ document.getElementById('data-modal-close').addEventListener('click',closeDataMo
 document.getElementById('data-modal').addEventListener('click',(e)=>{if(e.target.id==='data-modal')closeDataModal();});
 document.addEventListener('keydown',(e)=>{if(e.key==='Escape')closeDataModal();});
 document.getElementById('agents').addEventListener('click',(e)=>{
+  const chip=e.target.closest('[data-filter-kind]');
+  if(chip){
+    e.preventDefault();e.stopPropagation();
+    const kind=chip.getAttribute('data-filter-kind'),value=chip.getAttribute('data-filter-value');
+    CHIP_FILTER=(CHIP_FILTER&&CHIP_FILTER.kind===kind&&CHIP_FILTER.value===value)?null:{kind:kind,value:value};
+    renderWork();return;
+  }
+  const contractBtn=e.target.closest('[data-contract-agent]');
+  if(contractBtn){
+    e.preventDefault();e.stopPropagation();
+    const a=contractBtn.getAttribute('data-contract-agent');
+    openDataModal('Contract: '+a,JSON.stringify(AGENT_CONTRACTS[a]||{},null,2));return;
+  }
   const el=e.target.closest('[data-art-key]');if(!el)return;
   const key=el.getAttribute('data-art-key');
   if(ARTIFACTS[key]!==undefined)openDataModal('Artifact '+key,ARTIFACTS[key]);
 });
+document.addEventListener('click',(e)=>{
+  if(e.target.closest('[data-clear-filter]')){CHIP_FILTER=null;renderWork();}
+});
 document.getElementById('copy-link').addEventListener('click',()=>copyTo('copy-link',location.href,'link'));
 document.getElementById('copy-json').addEventListener('click',()=>copyTo('copy-json',TRACE?JSON.stringify(TRACE,null,2):'','json'));
 document.getElementById('toggle-json').addEventListener('click',(e)=>{

{reactifact-0.16.0 → reactifact-0.16.1}/reactifact/tracing/tracer.py

@@ -25,7 +25,15 @@ from typing import TYPE_CHECKING, Any
 
 from ..patches import Create, Link, Update
 from ..providers import LLMProvider, LLMRequest, LLMResponse, LLMResponseChunk
-from .models import AgentSpan, ArtifactRef, LLMCall, ProduceRun, RelationRef, RunTrace
+from .models import (
+    AgentContract,
+    AgentSpan,
+    ArtifactRef,
+    LLMCall,
+    ProduceRun,
+    RelationRef,
+    RunTrace,
+)
 from .store import TraceSink, TraceStore
 
 if TYPE_CHECKING:
@@ -460,6 +468,20 @@ class RunTracer:
         if self.tracer is None:
             return None
         try:
+            consumes = [
+                getattr(c.artifact_type, "__name__", str(c.artifact_type))
+                for c in (agent.consumes or [])
+                if c.artifact_type is not None
+            ]
+            produces_declared = [
+                getattr(p, "name", type(p).__name__) for p in (agent.produces or [])
+            ]
+            declared_tools = getattr(agent, "tools", ()) or ()
+            if isinstance(declared_tools, dict):
+                declared_tools = declared_tools.values()
+            tools_declared = [
+                getattr(t, "name", type(t).__name__) for t in declared_tools
+            ]
             span = AgentSpan(
                 agent=agent.name,
                 event_type=event.type.value,
@@ -468,6 +490,13 @@ class RunTracer:
                     if isinstance(event.artifact_type, type)
                     else str(event.artifact_type)
                 ),
+                event_artifact_id=event.artifact_id,
+                contract=AgentContract(
+                    consumes=consumes,
+                    produces=produces_declared,
+                    tools=tools_declared,
+                    priority=agent.priority,
+                ),
                 produces=[
                     ProduceRun(name=name, operations=operations, latency_ms=latency)
                     for name, operations, latency in (produces or [])

{reactifact-0.16.0 → reactifact-0.16.1/reactifact.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reactifact
-Version: 0.16.0
+Version: 0.16.1
 Summary: Reactive, artifact-driven agent runtime: agents transform versioned, typed, provenance-aware artifacts inside an evolving context
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/bzdvdn/reactifact

{reactifact-0.16.0 → reactifact-0.16.1}/tests/test_public_api.py

@@ -249,6 +249,7 @@ FROZEN: dict[str, frozenset[str]] = {
     ),
     "reactifact.tracing": frozenset(
         {
+            "AgentContract",
             "AgentSpan",
             "ArtifactRef",
             "CompositeTracer",

{reactifact-0.16.0 → reactifact-0.16.1}/tests/test_trace_ui.py

@@ -17,7 +17,7 @@ def test_span_renderer_defines_the_tool_count_it_uses():
     threw a ReferenceError and left the whole Work section empty."""
     html = _ui_run_html()
     start = html.index("function spanHtml(s){")
-    end = html.index("function flowHtml", start)
+    end = html.index("function producesBlock", start)
     body = html[start:end]
 
     assert "const toolCount" in body
@@ -31,3 +31,14 @@ def test_artifact_preview_opens_the_full_data_modal():
     assert "openDataModal" in html
     assert 'id="data-modal"' in html
     assert "const ARTIFACTS={}" in html
+
+
+def test_work_ui_has_contract_flow_and_chip_filters():
+    html = _ui_run_html()
+    assert "contract-flow" in html
+    assert "data-contract-agent" in html
+    assert "data-filter-kind" in html
+    assert "Consumes / inputs" in html
+    assert "Outputs / writes" in html
+    assert "tl-sub produce" in html
+    assert "tl-sub tool" in html

{reactifact-0.16.0 → reactifact-0.16.1}/tests/test_tracing.py

@@ -146,6 +146,10 @@ def test_runtime_records_spans_and_trace(tmp_path):
     assert trace.outcome == "completed"
     # greeter span: read the question, created the answer
     greeter = next(s for s in trace.spans if s.agent == "Greeter")
+    assert greeter.event_artifact_id == ctx.list_artifacts(Question)[0].id
+    assert greeter.contract.consumes == ["Question"]
+    assert greeter.contract.produces == []
+    assert greeter.contract.tools == []
     assert any(
         r.artifact_id == ctx.list_artifacts(Question)[0].id for r in greeter.reads
     )
@@ -187,6 +191,7 @@ def test_runtime_records_which_produce_ran(tmp_path):
     assert span.event_artifact_type == "Question"
     assert [p.name for p in span.produces] == ["Emit"]
     assert span.produces[0].operations >= 1
+    assert span.contract.produces == ["Emit", "NeverRuns"]
 
 
 def test_runtime_records_a_produce_that_raised(tmp_path):
@@ -1100,6 +1105,8 @@ def test_runtime_records_tool_runs(tmp_path):
     assert span.tools[0].chars == len("found")
     assert span.tools[0].produce == "UsesTool"
     assert span.tools[0].output == "found"
+    assert span.contract.consumes == ["Question"]
+    assert span.contract.produces == ["UsesTool"]
 
 
 def test_tool_args_are_opt_in_and_redacted(tmp_path):