Add AgentProf workflows as a Perfetto skill overlay

.github/workflows/ai-skill.yml

@@ -0,0 +1,73 @@
+name: AgentProf AI skill
+
+on:
+  pull_request:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ai-skill-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name != 'release' }}
+
+jobs:
+  build:
+    name: Build and verify AI release artifact
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Prepare pinned Perfetto skill and AgentProf overlay
+        run: python3 tools/perfetto setup
+      - name: Test release packaging
+        run: python3 -m unittest discover -s tools/release -p 'test_*.py'
+      - name: Build and verify the extracted release artifact
+        run: |
+          python3 tools/release/build-ai-skill.py \
+            --revision "$GITHUB_SHA" \
+            --epoch "$(git show -s --format=%ct HEAD)" \
+            --verify
+      - name: Retain verified artifact for PR review or release upload
+        uses: actions/upload-artifact@v4
+        with:
+          name: agentprof-ai-skill
+          path: |
+            artifacts/ai-release/agentprof-ai-skill.zip
+            artifacts/ai-release/agentprof-ai-skill.zip.sha256
+            artifacts/ai-release/agentprof-ai-skill.provenance.json
+            artifacts/ai-release/agentprof-ai-skill.verification.json
+          if-no-files-found: error
+
+  publish:
+    name: Attach AI skill to published release
+    if: github.event_name == 'release'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - uses: actions/download-artifact@v4
+        with:
+          name: agentprof-ai-skill
+          path: ai-release
+      - name: Upload missing matching assets without overwriting
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          python3 tools/release/upload-ai-skill.py \
+            --repo "$GITHUB_REPOSITORY" --tag "$RELEASE_TAG" \
+            --dir ai-release --publish

.github/workflows/ci.yml

@@ -106,6 +106,8 @@ jobs:
           key: perfetto-ui-${{ runner.os }}-${{ hashFiles('third_party/perfetto.toml') }}
       - name: Build UI and Trace Processor WASM
         run: python3 tools/perfetto build-ui
+      - name: Check authored AgentProf SQL formatting
+        run: python3 tools/perfetto check-skills-format --skip-deps
       - name: Typecheck UI
         run: python3 tools/perfetto check-ui --skip-deps
       - name: Install Chromium and system dependencies

CONTRIBUTING.md

@@ -18,6 +18,7 @@ the headers and package metadata. Preserve third-party copyright and license not
 | `packages/claude-tracing/`, `packages/codex-tracing/`, `packages/muse-tracing/` | Harness recording plugins and tests |
 | `packages/agent-tracing/` | Shared trace serialization |
 | `tools/` | Checkout manager and synthetic trace/browser validation |
+| `ai/skills/dev.agentprof/` | Portable workflows overlaid onto the upstream Perfetto skill |
 | `third_party/perfetto.toml` | Upstream Perfetto URL and initial revision pin |
 | `third_party/patches/perfetto/` | Patches to upstream-owned files |
 | `third_party/overlays/perfetto/` | Agent Profiler-owned files, mirroring upstream paths |
@@ -123,6 +124,74 @@ aside, change the pin, and run setup. Resolve conflicts with `git am --continue`
 inside the new checkout, then capture the resulting series. Rebuild and run
 trace/browser checks before landing the update.
 
+## AgentProf AI workflows
+
+Keep portable workflow pages and SQL under
+`ai/skills/dev.agentprof/workflows/agentprof/`. This namespace is an overlay source,
+not another installed skill. Setup links it into the pinned Perfetto skill;
+changes to the upstream router remain a small ordered patch. Reuse shared
+Perfetto references and packaging instead of copying them.
+
+The two reader exports are generated from UI SQL and preserve its explicit
+`INDEXED BY` hints. Do not independently format these generated files: the pinned
+formatter drops those hints. Format authored query resources with Perfetto's
+formatter; CI checks them after the UI build prepares its toolchain.
+
+```bash
+python3 tools/perfetto setup
+npm run build:skills-sql
+python3 tools/perfetto check-skills-format
+PERFETTO_TRACE_PROCESSOR=/path/to/local/trace_processor npm run test:skills
+cd third_party/src/perfetto
+python3 tools/release/build_ai_agents.py --output ../../../artifacts/ai-agents
+```
+
+The upstream command only assembles local output without a commit/push option.
+The installed skill is `artifacts/ai-agents/plugins/perfetto/skills/perfetto/`.
+The SQL exports are checked against the UI reader, but run with only a trace
+and Trace Processor. Tests cover packaging, overlay collisions, all four harness
+recordings, missing measurements, prompt-level turns, capture scoping and overlap.
+No model calls are needed. Run model-based Perfetto evals separately only with
+explicit approval; do not attach private traces to eval artifacts.
+
+### Build the AI release artifact
+
+After `python3 tools/perfetto setup`, run:
+
+```bash
+python3 -m unittest discover -s tools/release -p 'test_*.py'
+python3 tools/release/build-ai-skill.py \
+  --revision FULL_AGENTPROF_COMMIT_SHA \
+  --epoch SOURCE_COMMIT_UNIX_SECONDS \
+  --verify
+```
+
+Replace the two provenance placeholders with the source commit's full SHA and
+Unix timestamp. The builder invokes Perfetto's existing packager and writes
+`artifacts/ai-release/agentprof-ai-skill.zip`, its SHA-256, provenance and a runtime
+verification report. The ZIP contains only the assembled `perfetto/` skill,
+including licenses and the exact upstream wrapper, not Google's marketplace
+metadata. ZIP paths, timestamps and permissions are deterministic for identical
+inputs.
+
+`--verify` extracts the ZIP, verifies its contents and executable permissions,
+independently hashes the native prebuilt selected by its wrapper, runs the SQL
+suite against the extracted resources and reviewed recordings, and exercises a
+warm Unix-socket session with the packaged launcher. It does not substitute a
+Meta or locally built Trace Processor. The initial native download needs network
+access; a missing/incompatible runtime is a failure, not a skipped release check.
+
+The **Build and verify AI release artifact** PR check in
+`.github/workflows/ai-skill.yml` runs this path and retains the ZIP/checksums/report
+as an Actions artifact for review before landing. Existing recorder/UI checks
+remain unchanged. Only a `release.published` event enables the separate upload
+job; it attaches assets to that existing release without creating a release or
+overwriting existing assets. A rerun compares existing assets byte-for-byte,
+accepts matching ones and uploads only missing files; a mismatch fails without
+replacement. No model calls or new captures are required.
+
+See [ai/README.md](ai/README.md) for upstream contribution and overlay import.
+
 ## Useful bug reports
 
 Include the harness revision, UI revision, recording settings, expected

README.md

@@ -26,6 +26,33 @@ or load your recordings. Captured subagent sessions appear within their primary
 session. Multiple files can be opened together with clock alignment from the
 recorded snapshots.
 
+## AI analysis skills
+
+The recording integrations and analysis skills are installed separately. Download
+`agentprof-ai-skill.zip` and its `.sha256` file from an
+[AgentProf release](https://github.com/dreveman/agentprof/releases), verify the
+checksum, and extract the archive into a temporary directory. It contains one
+`perfetto/` skill folder; place that folder in your agent's skills directory.
+The ZIP becomes available with releases containing this workflow. Before the
+first release, build it from source as described in [CONTRIBUTING.md](CONTRIBUTING.md).
+
+The skill combines upstream Perfetto instructions with AgentProf workflows for
+slow runs, model performance, tools/delegation, context pressure, run comparisons
+and runtime resources. It bundles Perfetto's Trace Processor launcher, which
+downloads and verifies a pinned native binary on first use. No AgentProf checkout
+or UI is needed for analysis.
+
+**Do not silently overwrite an existing `perfetto` skill.** This is an
+AgentProf-enhanced replacement, not a second side-by-side skill. Back up the
+existing installation and replace it only deliberately; other installed skills
+should remain untouched. The `dev.agentprof` name identifies the source overlay,
+not the installed skill. The archive does not contain a marketplace installer.
+
+For example, ask your agent: “Use the Perfetto skill to investigate the slowest
+turns in this AgentProf trace. Report measurement coverage and do not quote tool
+arguments or prompts.” Review trace contents before sharing them; the skills do
+not upload recordings or call a model to generate test traces.
+
 ## Why record a trace instead of only reading a transcript?
 
 A session transcript is useful for understanding what an agent said, requested,

ai/README.md

@@ -0,0 +1,28 @@
+# AgentProf AI workflow overlay
+
+`skills/dev.agentprof/` is a source overlay, not an independently installed skill.
+It adds the `agentprof` workflow domain to Perfetto's existing `perfetto` skill.
+There is no copied router, bootstrap, binary wrapper or package manifest here.
+
+`python3 tools/perfetto setup` links `skills/dev.agentprof/workflows/` into the
+pinned checkout's `ai/skills/perfetto/workflows/`. The small router edit is kept
+in the normal Perfetto patch series. The upstream bundler packages the resulting
+single skill unchanged; see [CONTRIBUTING.md](../CONTRIBUTING.md).
+
+The workflows ship standalone SQL. `tools/generate-skills-sql.ts` exports the
+shared reader and turn-attribution SQL from AgentProf's tested UI queries, with
+an isolated `agentprof_skill_*` namespace and without prompt/tool payloads. This
+is an AgentProf maintenance step, not a runtime or upstream packaging dependency.
+The two reader exports are marked generated and retain the reader's explicit
+index hints; do not independently format them. Authored query resources use the
+pinned Perfetto SQL formatter, checked by `tools/perfetto check-skills-format`.
+`npm run build:skills-sql` refreshes the two exports; `npm run check` verifies them.
+
+For an upstream Perfetto contribution, copy `skills/dev.agentprof/workflows/`
+to `ai/skills/perfetto/workflows/` and apply only the skill-router patch. No
+AgentProf checkout manager or generated build dependency belongs in that change.
+
+An environment with its own Perfetto bootstrap can import the same
+`skills/dev.agentprof/` namespace as a workflow-only overlay. Keep its environment
+override separate. Remove the backport once the pinned upstream source includes
+these workflows rather than silently replacing imported upstream files.

ai/skills/dev.agentprof/workflows/agentprof/analyze_context_pressure.md

@@ -0,0 +1,52 @@
+# Analyze AgentProf context pressure
+
+Use for context growth, model-window pressure, composition changes and compaction.
+First initialize and select captures using
+[investigate an agent run]($SKILL_ROOT/workflows/agentprof/investigate_agent_run.md).
+Reuse its warm session.
+
+## 1. Establish measurement basis and coverage
+
+```bash
+trace_processor query --remote SESSION --query-file $SKILL_ROOT/workflows/agentprof/scripts/context_summary.sql
+```
+
+One row per capture reports its recorded peak/window/share plus the latest
+snapshot's ID, timestamp, stage, model, basis, coverage, estimated/reported totals,
+configured/effective window, compaction threshold, omitted changes and category
+composition. Show the snapshot timestamp: it may be stale relative to the peak.
+Do not present latest composition as the composition at peak pressure.
+
+No snapshots means detailed context composition is unavailable. A recorded context
+counter peak can still be useful; NULL is not an empty context. Estimated tokens
+may be character-based and are not tokenizer-exact. Provider-reported input usage,
+estimated retained context and cumulative input counters are different quantities.
+Model window/share is usable only when its window is unambiguous and positive.
+Do not sum independent child-agent context windows.
+
+## 2. Explain changes and compaction
+
+```bash
+trace_processor query --remote SESSION --query-file $SKILL_ROOT/workflows/agentprof/scripts/context_changes.sql
+trace_processor query --remote SESSION --query-file $SKILL_ROOT/workflows/agentprof/scripts/compactions.sql
+```
+
+The top 50 retained changes report signed deltas, category/change type, basis,
+baseline, previous/current estimates and source operation where recorded. Preserve
+negative changes and baseline resets. Do not subtract estimates across basis
+changes; omitted changes prevent a complete item-level reconciliation. Labels and
+content are deliberately excluded.
+
+Compactions report event IDs/timestamps, incomplete status, measured completed
+duration and before/after tokens. NULL or incomplete duration is not zero. Where
+both totals use comparable recorded semantics, compute reduction and report the
+compaction's time cost. A smaller context does not by itself prove faster inference
+or preserved task quality.
+
+## 3. Report
+
+State peak pressure and the window definition, snapshot coverage/basis, largest
+supported growth/removal categories, and compaction trade-offs. For latency
+correlation, inspect model-response IDs in the same capture; sparse snapshots do
+not establish the exact context submitted with every request. Follow shared
+report/privacy rules. Do not recover omitted content from harness journals.

ai/skills/dev.agentprof/workflows/agentprof/analyze_model_performance.md

@@ -0,0 +1,68 @@
+# Analyze AgentProf model performance
+
+Use for response latency, first-content latency, token throughput and model/provider
+comparisons. First initialize and select captures using
+[investigate an agent run]($SKILL_ROOT/workflows/agentprof/investigate_agent_run.md).
+Reuse that warm session and its scope; do not rerun setup unnecessarily.
+
+## 1. Compare like measurements
+
+```bash
+trace_processor query --remote SESSION --query-file $SKILL_ROOT/workflows/agentprof/scripts/model_summary.sql
+```
+
+Rows are grouped by capture, provider, raw model identity and recorded timing
+semantics. Columns include response/incomplete counts, duration sample count,
+mean/median/p95 duration, first-content mean/sample count, reported usage/sample
+counts, and output-token throughput/sample count. Median is the middle value
+(or mean of two middle values); p95 is nearest-rank. Small samples are descriptive,
+not a reliable estimate of a population tail.
+
+Only completed measured responses contribute to latency and throughput. Known
+zero tokens are retained; unknown tokens are NULL. Throughput is reported output
+tokens divided by the sum of eligible response durations, **not wall-clock output
+rate** or streaming-only decode speed. Show its denominator and sample count.
+
+Do not collapse timing groups:
+
+- Pi generally records native response spans and first content.
+- Claude can record request durations including retries; request placement may
+  come from journal observations or native modifications.
+- Codex plugin-only transcript completions report usage without measured model
+  duration or first content. A timestamped completion is not a latency sample.
+- Muse native durations do not imply first-content timestamps.
+
+First content can include reasoning or tool-call data. It is not necessarily the
+first visible text token. Provider input/cache accounting also differs: preserve
+reported fields; do not assume a universal cache-hit denominator or sum cached
+input into input totals twice. Pricing requires a separately verified rate table.
+
+## 2. Inspect the slow responses and request phase
+
+```bash
+trace_processor query --remote SESSION --query-file $SKILL_ROOT/workflows/agentprof/scripts/slow_responses.sql
+trace_processor query --remote SESSION --query-file $SKILL_ROOT/workflows/agentprof/scripts/request_headers.sql
+```
+
+The first query returns at most 50 response IDs, start timestamps, timing labels,
+measured duration/first content, reported tokens and incomplete flags. The second
+returns up to 50 provider-request spans with recorded phase and timing labels.
+Interpret a span as request-to-headers only when its phase establishes that
+boundary; otherwise report the recorded request span without inventing its end
+semantics. Request-to-headers is neither first content nor full response duration. No rows
+means no such spans were recorded. Do not add request spans to response duration
+or infer retry counts from a retries-inclusive label.
+
+`model-call` script lifecycles are not native assistant responses; queueing and
+wrapper work may be included. Their durations belong in
+[tools and delegation]($SKILL_ROOT/workflows/agentprof/analyze_tools_and_delegation.md),
+not this throughput denominator.
+
+## 3. Report
+
+State which provider/model/timing cohort dominates measured latency, the sample
+counts and missing coverage, and specific response IDs to investigate. Distinguish
+high first-content latency from a long overall response only where both are
+recorded. Token volume and context may correlate with latency; these recordings
+alone do not prove a provider bottleneck or task quality improvement. Follow the
+shared report/privacy rules in the entry workflow.