mirror of https://github.com/okieselbach/AutopilotMonitor.git synced 2026-10-24 04:32:32 +00:00

Files

T

Oliver Kieselbach bbb55034e3 feat(versioning): one version contract for agent, backend and MCP

All three components now report <major>.<minor>.<build> plus a 7-char commit
and a build timestamp. The backend had been pinned at a hand-written 1.0.0
since inception and starts at 1.5.1000; the MCP server's package.json version
was bumped by hand and starts at 1.5.300, and it now reports its own commit on
/health instead of only the documentation bundle's.

The build number keeps coming from a counter blob reserved before the build
with ETag-CAS, but there is now one implementation instead of two copies:
.github/scripts/Request-BuildNumber.ps1, called by all three workflows and by
the local build.ps1. It lives under .github/ because scripts/Deployment/ is
gitignored (those scripts carry SAS tokens) and would therefore be absent from
a CI checkout; scripts/Build/ and scripts/Release/ are shadowed by the
[Bb]uild/ and [Rr]elease/ artifact ignores.

The counter cannot be replaced by the published manifest, which is the obvious
simplification to reach for: version.json is written only on stable publish, so
two consecutive dev builds would derive the same number and the second would
overwrite the first's artifact. git rev-list --count fails the same way, two
builds of one commit collide.

Both deploy workflows now poll their health endpoint until it reports exactly
the version and commit just deployed, and publish versions/<component>.json
only then. A green deploy step alone means the package was accepted, not that
it is being served -- so a manifest that disagrees with the live endpoint now
means the running instance drifted (rollback, stale revision) rather than a
pipeline that stopped halfway. The agent manifest gains the same commit and
buildUtc fields additively; the bootstrap reads it by field name, so older
installers ignore them, and sha256/bootstrapVersion stay untouched.

Requires the versions container plus AZURE_BLOB_VERSIONS_SAS_TOKEN and the two
seeded counters (backend 999, mcp 299) before the first deploy run.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-07-22 17:41:03 +02:00

3.8 KiB

Raw Blame History

okf_version

okf_version
0.1

Autopilot Monitor — Technical Knowledge Bundle

Contributor-facing technical documentation for Autopilot Monitor, organized as an Open Knowledge Format (OKF) knowledge bundle. Customer-facing product documentation lives at https://docs.autopilotmonitor.com (separate repository).

Architecture

Architecture Guide - High-level architecture overview and solution layout for contributors.
Version Contract - One version shape for agent, backend and MCP: the ETag-CAS counter blob that mints build numbers, and the manifests published only after a deploy is verified live.

Agent

V2 Agent - How the on-device agent works: runtime overview, decision engine (reducer, signals, completion arms), logs & persistence (signal log, snapshot, crash recovery), Hello wizard un-skip (why a single "WHfB disabled" read never decides completion), Autopilot ZTD diagnostics (event IDs, diagnostic registry, endpoints, error-code map).
Build Counter Blob - How agent build numbers are minted: shared counter blob with ETag-CAS so local and CI builds never collide; CI additionally attests build provenance (Sigstore).
Agent Endpoint Migration - How the backend re-homes agents to a new API base URL via the config channel (backend move or per-tenant region move): live-fetch-only, allowlist-validated on both sides, one hop, kill wins.
MDM Reboot Coalescing - Attributing the mid-ESP coalesced reboot ("second sign-in") to the device-assigned policy URIs that forced it: aggregated DM-Enterprise 2800 observations (neutral, flush-time watermark) + the ANALYZE-ESP-005 advisory gated on an actually-observed reboot.

Rules

Gather Rule Phase Scoping, One-Shot Triggers & Emit-on-Change - Restricting gather rules to enrollment phases (activePhases / activeFromPhase sticky latch), one-shot collection at a phase's start/end (phase_change / phase_exit), and emitMode "on_change" result-dedup.
Gather Rule Guardrails - Why the allowlists in rules/guardrails.json are enforced on the agent and nowhere else, which hard blocks survive unrestricted mode, and the rule that every collector must call a guard and emit security_warning on refusal.

Backend

Business Timestamps - Why the Azure Tables system Timestamp is never authoritative (migrations reset it), and the OccurredUtc + RowKey-decode compensation for AuditLogs/OpsEvents/Events after the 2026-07-18 migration.

MCP Server

MCP Docs Corpus - How the published customer documentation becomes the search_docs corpus: CRLF-safe heading chunking, build-time embedding as a third precomputed section, and why a docs edit needs an MCP redeploy.

Security & Identity

MCP OAuth Flow - Who authenticates where when connecting an AI client to the MCP server; two identities, three parties plus Entra ID.

Conventions for this bundle

Every concept document is a markdown file with YAML frontmatter; type is mandatory, title, description, resource, tags, and timestamp are recommended.
Use standard relative markdown links between documents (e.g. agent/overview.md, ../architecture.md). Do NOT use the spec's /-prefixed bundle-absolute form — GitHub resolves those against the repo root (missing /docs) and navigation breaks.
Record notable additions and changes in log.md.
index.md and log.md are reserved names — never use them for concept documents.

3.8 KiB Raw Blame History