Run HAIEC from an AI Agent

Core behavior

1. Ask — understand what the user wants evaluated.
2. Preflight — discover tenant, AI System, trusted sources, scopes, and missing setup.
3. Run — start the intended canonical Evaluation once.
4. Understand — retrieve Summary and Agent Audit.
5. Resolve — group open verification items into meaningful evidence actions.
6. Re-evaluate — only when evidence or evaluated source state actually changed.
7. Establish — explain the resulting persisted Evaluation and provide exact UI/report links.

Re-running the same source analysis does not close a gap that requires policy, IAM, deployment, identity, telemetry, or other external evidence. The agent should follow the deterministic resolution category returned by HAIEC.

Approval contract

Before a supported write, upload, runtime test, source change, or other consequential operation, explain the exact action and ask the user to approve it. Only after the user confirms may the agent pass the corresponding HAIEC confirmation field.

User confirmation authorizes the requested HAIEC workflow action.

For this build, user confirmation in the IDE is accepted as the workflow approval signal. This is an execution acknowledgement; it does not independently prove that a production action had path-bound human approval at runtime.

Discovery

Machine-readable entry points:

• /.well-known/haiec-capabilities.json — capability manifest (operations, source modes, statuses).
• /openapi/assurance-v1.yaml — the formal API contract.
• GET /api/v1/systems and GET /api/v1/systems/{systemId}/evaluation-sources — runtime discovery of AI Systems and verified sources.
• GET /api/v1/evidence/binders — discovery of configured evidence destinations for the intake routes.
• https://www.haiec.com/api/mcp — HAIEC Assurance MCP server (Streamable HTTP, Bearer API key) for agent-native tool access.

HAIEC Assurance MCP

MCP is the preferred surface for AI IDEs and agents. It exposes the same canonical operations as the REST API — one bounded tool per operation — over a stateless Streamable HTTP transport. Authentication is the same HAIEC_API_KEY Bearer credential; the tenant is the key's organization and cannot be overridden by tool input.

• If HAIEC MCP is configured in the client → use the MCP tools.
• If only HAIEC_API_KEY is set → use Assurance REST API v1 directly.
• If neither exists → guide the user through the setup on this page.
• Start with haiec_preflight when setup state is unclear — it returns ready, per-check truth, and exact required/optional user actions with URLs (GitHub App install, AI System selection, API key scopes, evidence binders). Telemetry is never required for remote_assurance; a binder is required only for evidence_upload.
• haiec_run_assurance requires a caller-generated idempotencyKey — one UUID per intended run; retries with the same key+payload replay the same run.
• haiec_get_agent_audit includes resolutionGroups — a deterministic grouping of the report's verification items into resolution groups (exact verificationNeeded per group) — use it to explain what is established, what remains open, and the next action instead of asking the user one question per row.
• haiec_get_master_report returns the canonical Master Assurance Report product (bounded by default, detail:"full" for the complete projection) — the same product the dashboard HTML page and Master Report PDF render. links.html / links.pdf hand the user the rendered artifacts; haiec_get_report remains the secondary Assurance Evidence bundle.
• Runtime: haiec_runtime_preflight is a read-only safety plan (executable vs HELD categories, missing acknowledgements). haiec_run_runtime_test requires literal userConfirmedRuntimeTest: true + authorizationAcknowledged: true reflecting actual user statements — held categories never execute. Attach the resulting bound test to a NEW run via haiec_run_assurance attachRuntimeTestId.
• MCP never accepts organizationId, GitHub tokens, installation IDs, or arbitrary repository URLs — and never exposes the key back in tool output.
• Evidence tools (haiec_ingest_structured, haiec_ingest_logs) require evidence:ingest scope plus userConfirmedUpload: true — call them only after the user explicitly approves the upload.
• Setup tools: MCP can perform supported AI System and source setup actions (create system, register asset, bind a GitHub-App-listed repository, verify a source) after explicit user approval. Third-party authorization such as GitHub App installation may still require a browser handoff — HAIEC returns the exact destination rather than fabricating it. HAIEC never treats a caller-supplied repository URL or token as proof of trusted source authority.
• Per-client configuration: Cursor, Claude Code, Devin. The full tool list lives in the capability manifest.

Investigations — start, leave, return

An investigation groups evidence under user-declared states — "first evidence", "before the incident", "after the fix" — so HAIEC can reconstruct what was established at each point. The user never needs HAIEC's internal fields: the agent translates ordinary language into the explicit scenario binding on each ingestion. - "Start a HAIEC investigation" → haiec_preflight, then haiec_scenario_preflight, then haiec_prepare_scenario (one scenarioRunId per investigation; nothing persists until bound evidence exists). - "This is my first evidence" → ingest with the declared first state. - "Here is the next batch" / "start collecting the next state" → haiec_get_scenario_status returns the deterministic next state — never compute ordering from memory or timestamps. - "What changed?" → haiec_reconstruct_scenario and haiec_compare_scenario_states between declared states. - "Continue my HAIEC investigation" (days later, fresh client) → haiec_preflight → haiec_list_investigations → name the found investigation or present the choices, then continue with the exact scenarioRunId. Identity comes from persisted evidence, never conversational memory. - Live capture: haiec_prepare_scenario_capture returns env vars, a scenario-aware OTel Collector config, and test payloads — it persists nothing until you apply it and HAIEC verifies receipt through haiec_get_scenario_status. - Typed evidence: haiec_ingest_structured accepts an intakeProfile (kpi, alarm, api_transaction, policy, and the telecom profiles) that uses the same mapper as the matching REST intake route — you propose the profile from the file shape, the user approves, and a record that fails the typed schema returns the canonical error, never a silent generic fallback. - Large files: split into bounded chunks, keep the same scenario binding on every chunk, use a stable clientBatchKey per chunk (file digest + chunk index), upload in order, and retry only failed chunks — idempotent keys make replays safe. Investigations persist under the AI System's workspace (Investigations tab). An investigation records what evidence arrived and in what declared order — it is not an Assurance disposition. Only a new Evaluation establishes whether anything changed.

The user never needs to know internal identifiers (scenarioRunId, scenarioSequence), level presets (the optional TM Forum AL0/AL1/AL2 vocabulary), or OTLP resource processors — the agent translates “first evidence” and “next batch” into the explicit binding. Persisted investigations are also visible in the AI System workspace under Investigations.

Rules for agents

• Read HAIEC_BASE_URL, HAIEC_API_KEY, HAIEC_AI_SYSTEM_ID, and HAIEC_SOURCE_ASSET_ID from server-side environment or the developer's non-public config.
• Never display, commit, or log the API key. Never use NEXT_PUBLIC_* for it.
• Never send githubToken, X-GitHub-Token, GITHUB_TOKEN, or organizationId to HAIEC.
• Use only configured Source Asset IDs — never a raw repository URL.
• Always send an Idempotency-Key on run creation; poll run status at 15–30s intervals and stop on terminal failure.
• Report exactly what the API returns: run ID, evaluation ID, disposition, what was established, what was not, limitations, report/agent-audit/passport/dashboard links.
• Prefer GET .../agent-audit over the full report for “what did HAIEC prove / what is missing” questions — it carries narrative.established, unestablished, notAssessed, evidenceGaps, and verificationItems[].verificationNeeded verbatim.
• Never manufacture PASS when evidence is missing, partial, or not assessed — and never translate NOT_ASSESSED or UNKNOWN into FAIL.
• Submit evidence only on explicit user request, only through a configured binder, and only via the canonical intake routes. An ingestion receipt means EVIDENCE_INGESTED — never a closed gap; only a new Evaluation establishes change.
• Running a scan never requires code changes; remediation is a separate user decision.

Canonical flow

configured Source Asset
  → POST /api/v1/assurance/runs
  → poll GET /api/v1/assurance/runs/{runId}
  → GET links.summary → GET links.agentAudit
  → GET links.masterReport (bounded) — canonical Master Assurance Report
  → GET links.masterReport?detail=full only when deeper analysis is required
  → links.report / links.pdf remain the secondary Assurance Evidence artifacts
  → open links.dashboard in the HAIEC Dashboard

optional, explicit user request only:
  GET /api/v1/evidence/binders → POST /api/ingest/* or /api/otlp/v1/*
  → attach receipt.producerRunId to a NEW run (producerId: structured-ingress)
  → compare old vs new evaluation facts

Telemetry and evidence ingestion are OPTIONAL — static Assurance needs only the key, AI System, and verified Source Asset. Ready-to-use agent instructions exist per tool: Cursor, Claude Code, Devin, and a generic agent guide for everything else.

When something fails

Translate known error codes into the exact user action. Do not turn optional evidence setup into a global Assurance blocker.

When HAIEC is not connected — local Quick Check

## When the user asks to "run HAIEC" — decision sequence 1. FULL ASSURANCE — HAIEC MCP or API key is configured and reachable: use the normal Assurance workflow (haiec_preflight → haiec_run_assurance → poll → summary → agent audit). 2. SETUP REQUIRED — HAIEC MCP is connected but haiec_preflight reports setup incomplete: explain the exact missing steps from preflight verbatim. If a local repository is available, you may also offer a Quick Check (below) — never in place of completing setup. 3. NO HAIEC CONNECTION — no API key or MCP configured, local repository available: say exactly — "Full HAIEC Assurance is not connected for this repository. I can still run HAIEC's independent local developer-security tools for a preliminary source-security review. These results are not a HAIEC Assurance Evaluation and will not appear in the HAIEC Assurance dashboard." Offer, only with the user's approval before installing or running: - AI AppSec (npx -y ai-appsec) — deterministic static source-security analysis for AI/agent code (requires Semgrep installed separately). - MCP Tenant Isolation (npx -y mcp-tenant-isolation mcp) — only when the repository builds MCP servers or tools. ## Presenting Quick Check results Inspect the repository deeply and propose fixes, but keep three kinds of statements clearly separate: - DETERMINISTIC PACKAGE FINDING — exactly what the scanner reported (rule, file, line). Quote it; never rewrite it as a HAIEC finding. - AI REPOSITORY INTERPRETATION — your reading in this codebase's context (reachability, exploitability, affected paths). - AI RECOMMENDATION — likely remediation and what to verify. Lead with the most important findings first, name the affected files, state the package's limitations, and close with what a full HAIEC Assurance Evaluation could additionally answer (capability and action-path analysis, authority/policy evidence, runtime evidence, Guided Assurance, Agent Audit, Reports, Passport). After the check, say: "These were independent HAIEC developer-security checks performed locally. They do not create a HAIEC Assurance Evaluation and are not stored in your HAIEC Assurance dashboard. Full HAIEC Assurance adds broader capability and action-path analysis, authority and policy evidence, runtime evidence, Guided Assurance, Agent Audit, Reports and Passport." Truth locks: - AI_APPSEC_RESULT != HAIEC_ASSURANCE_EVALUATION - MCP_TENANT_ISOLATION_RESULT != HAIEC_ASSURANCE_EVALUATION - FREE_LOCAL_CHECK != FULL_HAIEC_ASSURANCE - LOCAL_PACKAGE_RESULT != HAIEC_DASHBOARD_EVIDENCE

Try these with your AI

• “Check whether HAIEC is ready to evaluate this system.”
• “Run HAIEC Assurance on the connected source.”
• “Explain my HAIEC result in plain English.”
• “What did HAIEC establish?”
• “What remains unknown or not assessed?”
• “Group the open evidence questions and tell me which ones you can help resolve.”
• “What evidence is missing?”
• “Show me the highest-consequence action paths.”
• “Which capabilities are code-capable but not runtime-observed?”
• “Help me connect the evidence HAIEC says is missing.”
• “Can these logs help close any HAIEC evidence gaps?”
• “Submit these logs to HAIEC and rerun Assurance.”
• “Configure telemetry for this project, but ask before changing my files.”
• “Run the authorized runtime preflight.”
• “Compare this Evaluation with the previous one.”
• “Open the exact HAIEC report for this run.”
• “Start a HAIEC investigation.”
• “This is my first evidence.”
• “Here is the next batch — start collecting the next state.”
• “Continue my HAIEC investigation.”
• “What changed between my first evidence and the latest state?”
• “Where does the proof stop?”