Agentic provenance: framework plugins, AI-coding-harness capture, and provenance analysis

[GueroudjiAmal]

This PR extends Flowcept's provenance capture from scientific workflows to agentic systems: agent frameworks (Academy, LangGraph, CrewAI, AutoGen, LangChain, OpenAI Agents SDK, Claude Agent SDK), AI coding harnesses (Claude Code, Codex CLI, Gemini CLI, Cursor, OpenCode, or anything emitting OpenTelemetry GenAI spans), and a shared provenance-analysis layer that all of these — plus the existing MCP agent, the webservice chat, and the CLI — query through one set of functions.

The framing follows PROV-AGENT: an agentic session is a workflow — a prompt causes a turn, a turn causes tool calls, a tool call edits a file — which is the structure Flowcept already stores and queries. It also adds a Diaspora MQ adapter, which came along on the same branch (see Should this be split? below).

What's included

1. Agent-framework plugins (src/flowcept/agents/{academy,langgraph,crewai,autogen,langchain,openai_agents,claude_agent_sdk}/)

Each plugin captures its framework's execution as Flowcept tasks/workflows. They are declarative — no code changes in user workloads:

plugins:
  langgraph:
    enabled: true
    kind: langgraph
    workflow_name: "langgraph-workflow"
    performance_tracking: true

Flowcept.start() builds, starts, and stops enabled plugins alongside Flowcept, propagating campaign_id so all plugins in a run share a campaign. Running instances are exposed via the new Flowcept.plugins property. Each plugin's interceptor reuses the InstrumentationInterceptor singleton (same MQ connection and buffer) — the pattern the Dask client interceptor already uses. A plugin that fails to start is logged and skipped rather than taking Flowcept down.

2. AI coding harness capture (src/flowcept/agents/harness/ + per-harness plugin modules)

Shared capture core (recorder, tracer, emit, events, prov, state, sanitize, ids, vocab, config, cli, mcp_server) with these sources:

Source	Mechanism
Claude Code	Claude Code plugin (hooks) or hooks in settings.json
Codex CLI, Gemini CLI, Cursor, OpenCode	generic hook adapter + a JSON profile (cli_harness/profiles/*.json)
OpenTelemetry GenAI spans	span exporter, or ingest exported spans
Claude Agent SDK / OpenAI Agents SDK / LangChain / LangGraph	wrapper, tracing processor, callback handler
Custom agents	SessionTracer, or the MCP server's record_event tool

The capture path is deliberately stdlib-only — it imports nothing outside flowcept.agents.harness and the standard library. A harness hook is a fresh process on the interactive critical path, so importing Flowcept's heavy dependencies would cost far more than the capture itself; those are loaded only to read what was captured. Adding a new CLI harness means adding a JSON profile, not writing code.

New entry points: flowcept-harness (sessions/show/report/analyze/install/hook/compare), flowcept-harness-mcp, flowcept-claude-code.

3. Provenance analysis (src/flowcept/agents/prov_analysis/)

Framework-free pure functions over records: list[dict], following the existing data_query_tools/ layering rule (cores are framework-free; MCP/LangChain wrappers are thin): summarize_execution, analyze_errors, analyze_agent_behavior, find_slowest_tasks, cross_framework_links, compare_executions. They handle both the harness-buffer record shape and the framework-plugin shape, degrading gracefully on absent fields.

Four surfaces share this one implementation: the harness MCP server, the Flowcept agent MCP server (new mcp/mcp_tools/analysis_mcp_tools.py, registered in mcp/mcp_server.py), the webservice chat (chat_orchestration/tool_registry.py), and flowcept-harness analyze.

cross_framework_links builds edges from source_agent_id pointers, so a task recorded by one plugin can be linked to the agent that caused it in another.

4. Diaspora MQ adapter

MQDaoDiaspora (commons/daos/mq_dao/mq_dao_diaspora.py), wired into the MQDao.build() dispatch as mq.type: diaspora, plus resources/diaspora/ setup scripts and deployment/compose-diaspora.yml.

5. Smaller core changes

• configs.py: new PLUGINS settings section (defaults to {}; absent config is a no-op).
• autoflush_buffer.py: the timer and flush threads are now daemon=True, so a process can exit even if stop() was never reached.
• .gitignore: core.* → core.[0-9]* so files like core.py are not ignored.

6. Docs, examples, tests, CI

• Sphinx: docs/agent_plugins.rst (+318), docs/harness_plugins.rst (+322), docs/agent.rst and docs/index.rst updates; regenerated OpenAPI spec; +275 lines of README.
• 13 runnable examples under examples/agents/, one per plugin plus a combined multi-framework one.
• 36 new test files: tests/harness/ (12), tests/agents/plugins/ and tests/agents/prov_analysis/ (10), tests/adapters/test_diaspora.py. Coverage includes each capture source, cross-capture and cross-plugin linking, CLI, MCP server, plugin assets, and Flowcept interop.
• CI: pin ruff==0.15.22 in checks.yml and run-tests.yml (unpinned ruff was changing formatting expectations between runs), and a new check that the committed OpenAPI spec matches what the code generates.
• pyproject.toml: new harness_otel, harness_claude_sdk, and diaspora extras.

Backwards compatibility

No existing public API changed. Everything new is opt-in: plugins are off unless plugins: is set, harness capture only runs when hooks/exporters are installed, and the new extras are not part of the default install. The only behavioral change to existing code paths is the daemon=True on the autoflush threads.

Testing

make reformat && make checks      # ruff + Sphinx build
pytest tests/harness tests/agents # new suites

The plugins were exercised end-to-end against the real frameworks and a live Anthropic API key (commit 9d6d654a), and the CLI-harness profiles were validated by replaying recorded Gemini-profile sessions (commit 2d827328). Tests that need network or vendor SDKs skip when the dependency or key is absent.

Notes for reviewers

• Two accidental reverts from the merge base, please confirm before merge. Relative to main, this branch reintroduces psutil_p.connections() in telemetry_capture.py (upstream 06da889c had changed it to net_connections() for Fix deprecated warning in telemetry_capture #155) and drops the # group_id: auto Kafka comment from sample_settings.yaml (upstream fc138b5f). Both were carried in by the older Diaspora branch; happy to fix in this PR.
• The diaspora extra uses a direct git reference (diaspora-stream-api @ git+https://…) and required [tool.hatch.metadata] allow-direct-references = true. PyPI rejects direct-URL dependencies in uploaded metadata, so this may break the release workflow that publishes on pushes to main. Options: drop the extra from this PR, or gate it behind a non-published extra. Guidance welcome.
• Should this be split? The Diaspora MQ adapter is independent of the agentic work; it can be pulled into its own PR if that makes review easier.
• The harness capture path's stdlib-only constraint is load-bearing for interactive latency — worth keeping in mind if a review suggests reusing Flowcept helpers there.