Graph Runtime And Governance

Graph runtime and governance

Diagnose from observed state, preserve governance boundaries, and prove recovery with the same public path users depend on.

Keep installation profile, manifest, topology, connector rollout, and upgrade work in agent-utilities-deployment.

Action reference

Argument evaluation (AIF)

graph_argument represents and evaluates structured arguments in the Argument Interchange Format (AIFdb/arg-tech.org): I-nodes (claims — each one IS a :Belief) linked through S-nodes — RA (inference), CA (conflict), PA (preference) — plus the AIF+ TA (transition)/YA (illocutionary) dialogue extensions. Actions: import_aif (validates node arity first — an RA/CA needs ≥1 premise + exactly 1 conclusion, a PA needs ≥2 premises + exactly 1 conclusion — then writes through the shared ChangeEnvelope path; an RA/CA-node also mints the derived SUPPORTS/ATTACKS edge), export_aif (best-effort, degrades to an empty map rather than raising), evaluate (projects the CA/PA structure to Dung form and hands the I-node ids to the REAL engine argumentation solver — eg-epistemic's Method::ResolveConflict, grounded/preferred/stable semantics; no second solver is implemented here), and add_scheme (register a new named AIF Scheme template, e.g. a Waltonian scheme). evaluate requires the opt-in epistemic-tms engine feature. Honest limits: RA-node support is written as a SUPPORTS edge for provenance, but classical Dung semantics are attack-only — support doesn't feed the grounded/preferred/stable computation itself (it DOES feed the always-on confidence propagation the epistemic answer layer reads); PA-node preference filtering only ever discounts one side of a MUTUAL (symmetric) CA-conflict; import is fail-loud, export is fail-soft.

Workflow

1. Establish scope and safety

• Identify the affected tenant, graph, session, service, and time window.
• Separate read-only diagnosis from mutating remediation.
• Capture the current state before changing configuration or runtime data.
• Never request or display a secret value; work with secret identifiers and health status only.

Use the skill directly for a bounded health, trace, audit, or configuration check. Delegate a multi-layer incident only when independent diagnosis and dependency-ordered remediation will improve recovery.

2. Inspect the runtime

Trace a failure from the user-visible symptom to the first failing tool call, then to its runtime dependency. Prefer evidence from the existing doctor, metrics, traces, and audit surfaces over speculative configuration changes.

3. Manage tool visibility responsibly

Use the intent verbs ask, find, write, act, manage, and why when a small tool surface is appropriate. Use find_tools or list_catalog to discover a capability, load_tools to expose only what the current task needs, and unload_tools when finished. Pin an exact tool when ambiguity would be unsafe.

The six intent verbs (MCP_TOOL_MODE=intent, graph-os's default profile — the granular surface still registers fully, REST + _execute_tool unaffected; verbs just front it for small/cheap-LLM sessions): <verb>(intent="<natural language>", hints_json="{...}", execute=true). hints_json={"tool": "..."} pins an exact tool, bypassing ranking entirely; execute=false returns only the routing decision.

Resolution ranks each candidate against its generated Capability Power Descriptor (falling back per-capability to a lexical score over its docstring, never a silent gap), blends in a learned reward EMA from a durable-bandit outcome loop (a capability that keeps failing under a verb sinks in the ranking), and serves a repeated (verb, intent, hints) from a small bounded cache. find(...) never dispatches, so it never records an outcome. Reclaiming context is a manage concern, not a 7th verb — manage(intent="...", hints_json='{"action": "load", "tools": [...], "auto_unload": true}') pulls a tool in for one call and auto-retracts it right after.

Onboarding a brand-new child MCP server (as opposed to using one that already exists) keeps three surfaces in lockstep: the mcp_config*.json server entry (command/args/env), the README mcp_config examples (regenerated from the one authoritative env set), and the live registry — graph_configure(action="register_mcp", config_key="<name>", config_value="{...}") merges the entry and persists it. Verify with list_catalog()/find_tools(...)/multiplexer_status, then load_tools(servers= ["<name>"]).

4. Remediate minimally

For diagnosis, audit, or review-only work, report the observed cause, supporting evidence, and remediation plan, then stop before changing configuration or state.

• Change one causal condition at a time.
• Preserve tenant, role, approval, and audit context.
• Prefer idempotent recovery actions.
• Keep a rollback path for configuration and state changes.

5. Verify recovery

• Re-run the original failing operation through its normal entry point.
• Confirm health, traces, and audit records agree.
• Check that the fix did not weaken policy or expose additional tools.
• Record the root cause, evidence, action, and remaining risk.

Coverage governance

Every registered Graph-OS verb must appear in exactly one retained domain skill's agents/graph-os.yaml sidecar. Run the coverage command after changing the tool surface or skill taxonomy:

python -m agent_utilities.mcp.skill_coverage
pytest tests/unit/test_gateway_mcp_parity.py -q      # tool <-> REST-route <-> skill legs

This is the third parity leg (tool⇄REST-route are the other two): every verb in kg_server.REGISTERED_TOOLS (minus a small, justified exemption list) is wrapped by a domain skill's agents/graph-os.yaml, and no domain skill's coverage points at a dead verb. A verb with no covering skill is uncovered; a coverage entry pointing at a non-existent verb is an orphan — fix both before merge, or add the verb to the exemption list with a written justification.

Keep coverage metadata out of SKILL.md frontmatter.

Use an economy model for health classification, trace filtering, and checklist verification. Escalate security, policy, or ambiguous root-cause decisions.

Guardrails

• Do not log credentials, tokens, raw secret values, or private unrelated data.
• Do not disable policy or audit controls to make a check pass.
• Do not treat a healthy process as proof that the user-visible operation works.
• Escalate when recovery needs new authority or an irreversible external action.