{"id":76349,"plugin_id":"plugin_asdk_app_6ad3a430b30481919b3d089dabbc9b93","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-11-02T18:12:09.913Z","digest":"6851d329314a08b28addedc8c08430d8df4fa2d0b28dc4103bf18106b07ef90d","against":null,"payload":{"description":"Use when working with OloLand's observability stack — agent_runs, agent_spans, regulator_exports — to inspect a run, replay it, or generate a compliance-framework export. Explains the M1+M2 audit trail, the role-based gating, and the chain-of-custody discipline that makes the trail regulator-defensible.","included_files":[{"relative_path":"agents/openai.yaml","size_in_bytes":468}],"name":"observability-audit-trail","skill_md_contents":"---\nname: observability-audit-trail\ndescription: \"Use when working with OloLand's observability stack \\u2014 agent_runs,\\\n  \\ agent_spans, regulator_exports \\u2014 to inspect a run, replay it, or generate\\\n  \\ a compliance-framework export. Explains the M1+M2 audit trail, the role-based\\\n  \\ gating, and the chain-of-custody discipline that makes the trail regulator-defensible.\"\n---\n\n# Observability Audit Trail\n\nOloLand's M1+M2 observability surface is what turns the marketing claim \"verifiable end-to-end\" from aspiration into shipping artifact. Every agent run produces immutable rows in `agent_runs` and `agent_spans`. Every generated artifact (CIM, IC memo, forensic PDF) gets a lineage row in `output_artifacts`. Every regulator-grade export is a tarball whose SHA-256 is recorded at generation time.\n\n## What is captured\n\n| Table | What | Use |\n|---|---|---|\n| `agent_runs` | One row per top-level agent invocation. Captures `root_prompt_snapshot`, `skill_pack_snapshot`, `subagent_definition_snapshot`, model + harness versions, tokens, cost, status, grader verdict. | The unit of replay. The unit of cost accounting. The unit the regulator wants. |\n| `agent_spans` | One row per observable step inside a run — model call, tool call, compaction event, SSE event. Captures parent_span_id (tree structure), tool_name, model_version, latency_ms, is_error. | The \"show me what actually happened\" surface. |\n| `output_artifacts` | One row per artifact produced (CIM PDF, IC memo, forensic screen). Captures content hash, lineage to the producing run. | Tamper-evidence on generated deliverables. |\n| `regulator_exports` | Tarball metadata — framework, window, deal scope, SHA-256, signed-URL, expiry. | The deliverable for regulators / compliance reviewers. |\n\n## Role gating\n\nRead paths (`list_agent_runs`, `get_agent_run`, `list_agent_spans`, `get_grader_verdict`, `get_regulator_export`) are tenant-scoped — any active member of the company can call them.\n\nWrite paths (`replay_agent_run`, `request_regulator_export`) require the **admin or compliance role** in the calling user's `CompanyMember` row, OR one of the privileged permissions (`agent_runs`, `manage_agent_runs`, `replay_agent_runs`, `regulator_exports`, `manage_regulator_exports`, `compliance_exports`). Superusers bypass the check globally.\n\nSurfaced as `error_code: \"insufficient_role\"` on the MCP rail. If a user hits this and shouldn't, they need their company admin to grant the role on `CompanyMember` — *not* a new API key.\n\n## Replay modes\n\n`current_skills` (default) re-runs the captured `root_prompt_snapshot` against today's harness + skill catalog. Use when validating that a methodology change still produces a correct answer on yesterday's data.\n\n`byte_for_byte` reproduces the run identically — same skills, same subagent definitions, same prompt. Required when a regulator wants the exact output reproduced and verified. Only works for runs that captured *both* `skill_pack_snapshot` and `subagent_definition_snapshot` — pre-2026-05-14 runs return `error_code: \"no_snapshot\"` and cannot be replayed byte-for-byte.\n\n## Chain-of-custody discipline\n\nFor regulator exports, the user's responsibility is to **record the `tarball_sha256` separately from the OloLand system at the moment of download**. The hash is what makes the tarball tamper-evident to a downstream regulator — if it changes by even one bit, the chain-of-custody is broken.\n\nThe reviewer should:\n\n1. Download the tarball via `tarball_uri` (signed link).\n2. Compute the SHA-256 locally with a trusted tool.\n3. Compare to `tarball_sha256` from `get_regulator_export`.\n4. Record the (export_id, sha256, download_timestamp, reviewer_id) tuple in their compliance system.\n\nThat tuple is the audit-defense artifact, not the tarball itself.\n\n## What this is NOT\n\n- **Not real-time monitoring.** The observability tables are post-hoc. For live agent progress, use the SSE stream (`/api/sse/conversation/{session_id}`).\n- **Not a replacement for application logs.** `agent_spans` captures the agent loop's *intent* (this tool was called, this model returned this many tokens). Application-level errors still go to Sentry / Cloud Logging.\n- **Not the only audit surface.** Analyst corrections (`analyst_corrections` table, surfaced via `unsupported OpenAI claim-correction workflow (see unsupported-workflows.json)`) and deal outcomes (`deal_outcomes`, surfaced via `record_deal_outcome`) are separate audit trails for *user judgement on AI output* vs *agent runtime telemetry*.\n\n## Companion tools (MCP)\n\n- `list_agent_runs` — discover run_ids.\n- `get_agent_run` — header + span counts + grader.\n- `list_agent_spans` — full step list.\n- `get_grader_verdict` — grader_passed + rationale.\n- `replay_agent_run` — admin/compliance only.\n- `request_regulator_export` — admin/compliance only.\n- `get_regulator_export` — poll status.\n\nCompanion commands: `ololand-dd-inspect-run`, `ololand-dd-replay-run`, `ololand-dd-regulator-export`.\n\n\n## OpenAI execution requirements\n\nUse the connected MCP server's current tool schemas. Do not invent tool arguments, job-status endpoints, inputs, or outputs. If a referenced tool is unavailable, explain the limitation and request the needed connection or data. Invoke writes only when the user has requested the corresponding action. Do not initiate purchases or payments. An unrun, unsupported, or unavailable procedure is a gap, never a passing result.\n\n\nOpenAI cannot execute local lifecycle hooks. Use the packaged explicit setup/review workflow when requested. Server-side MCP auditing remains authoritative; preserve evidence blockers and human-only approval gates.\n\nClaim-correction submission is unsupported in this OpenAI upload because the current handler records surface=cowork. Do not invoke submit_agent_claim_correction from OpenAI. Explain the limitation and retain proposed correction text for human review without claiming submission. See unsupported-workflows.json for the excluded canonical workflow.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}