excel-background-verification

Files (1)

• SKILL.md

SKILL.md (first lines)

# Excel Background Verification

Use this skill to verify work in **real Excel with the real pi4office taskpane** without taking over the user's foreground app.

The workflow has two channels:

1. **Computer-use observation** (`pi-computer-use`, strict AX mode) verifies the Excel window/taskpane visually and semantically while asserting the foreground app does not change.
2. **Taskpane background bridge** lets the real taskpane run Office.js probes, controlled scratch writes, and optional prompt submissions from inside Excel via a tokened loopback HTTPS server.

Do not use raw keyboard/mouse/coordinate actions in this workflow. If a step requires foreground focus or raw input, stop and report that the background lane cannot verify that path.

## Prerequisites

- Excel has the dev manifest sideloaded, pointing to `https://localhost:3141/src/taskpane.html`.
- `cert.pem` and `key.pem` exist in the repo root and are trusted by the local WebView.
- `pi-computer-use.app` has macOS Accessibility + Screen Recording permissions.
- Run from the repo root.

## Start the bridge + dev server

```bash
TOKEN_FILE=$(mktemp /tmp/pi-background-verify-token.XXXXXX)
chmod 600 "$TOKEN_FILE"
TOKEN=$(node scripts/background-verify-bridge-server.mjs token)
printf '%s' "$TOKEN" > "$TOKEN_FILE"

PI_BACKGROUND_VERIFY_TOKEN="$TOKEN" \
PI_BACKGROUND_VERIFY_HOST=localhost \
  npm run background:verify:bridge \
  > /tmp/pi-background-verify-bridge-server.log 2>&1 &
echo $! > /tmp/pi-background-verify-bridge-server.pid

VITE_PI_BACKGROUND_VERIFY_URL=https://localhost:3157 \
VITE_PI_BACKGROUND_VERIFY_TOKEN="$TOKEN" \
  npm run dev \
  > /tmp/pi4office-vite-background-verify.log 2>&1 &
echo $! > /tmp/pi4office-vite-background-verify.pid
```

Check server health:

```bash
curl -k https://localhost:3157/health
```

If `clients` is empty, reload the taskpane without foregrounding Excel: use `pi-computer-use` in strict AX mode to press the Pi taskpane close button, then press the ribbon **Open Pi** button. Do not use raw input fallbacks.

If `clients` lists more than one taskpane, pass `--clientId <id-from-health>` to mutating `background:verify:command` calls so writes target the intended workbook. The server refuses untargeted commands when multiple live clients are connected.

## Computer-use observe lane

Run Pi in strict AX mode and allow only observation/search tools unless a semantic AX button press is explicitly required:

```bash
PI_COMPUTER_USE_STEALTH=1 PI_COMPUTER_USE_STRICT_AX=1 \
pi --tools list_apps,list_windows,observe,search_ui,inspect_ui \
  --no-context-files --no-skills \
  -p 'Use only computer-use tools. Do not focus any window and do not call act. Report the frontmost app, observe Microsoft Excel, and find evidence of Pi for Office, Open Pi, the taskpane prompt, model/status footer, and any feature under test.'
```

Required evidence:

- Excel window title/id and `isOnscreen=true`.
- Taskpane evidence (`Pi for Office`, `Open Pi`, prompt/model/status or feature-specific text).
- Frontmost app before/after is the same non-Excel app.
- Optional screenshot saved with a helper script or `observe` image.

## Taskpane bridge commands

The taskpane bridge commands run in the real Excel taskpane process. Use them to **mutate scratch workbook state, read it back, and clean up**; passive read-only probes are only the baseline evidence.

```bash
TOKEN=$(cat "$TOKEN_FILE")

PI_BACKGROUND_VERIFY_TOKEN="$TOKEN" PI_BACKGROUND_VERIFY_HOST=localhost npm run background:verify:command -- status
PI_BACKGROUND_VERIFY_TOKEN="$TOKEN" PI_BACKGROUND_VERIFY_HOST=localhost npm run background:verify:command -- officeProbe
PI_BACKGROUND_VERIFY_TOKEN="$TOKEN" PI_BACKGROUND_VERIFY_HOST=localhost npm run background:verify:command -- readUsedRange
PI_BACKGROUND_VERIFY_TOKEN="$TOKEN" PI_BACKGROUND_VERIFY_HOST=localhost npm run background:verify:command -- readRange '{"address":"Sheet1!A1:B5"}'
PI_BACKGROUND_VERIFY_TOKEN="$TOKEN" PI_BACKGROUND_VERIFY_HOST=localhost npm run background:verify:command -- listCharts
PI_BACKGROUND_VERIFY_TOKEN="$TOKEN" PI_BACKGROUND_VERIFY_HOST=localhost npm run background:verify:command -- configureProxy \
  '{"enabled":true,"url":"https://localhost:3003"}'
PI_BACKGROUND_VERIFY_TOKEN="$TOKEN" PI_BACKGROUND_VERIFY_HOST=localhost npm run background:verify:command -- selectModel \
  '{"provider":"openai-codex","modelId":"gpt-5.6-sol"}'
```

### Controlled write smoke

Run this whenever the change affects workbook IO, Office.js host behavior, recovery, chart/range tools, or anything where browser-only tests are too weak:

```bash
PI_BACKGROUND_VERIFY_TOKEN="$TOKEN" PI_BACKGROUND_VERIFY_HOST=localhost npm run background:verify:command -- workbookWriteProbe \
  '{"sheetName":"_pi_background_verify","keepSheet":false}'
```

`workbookWriteProbe` creates or reuses a scratch sheet, writes a marker + numeric inputs + formula, reads the resulting range, then deletes the created scratch sheet or restores the previous scratch range. Its output is the minimum proof that the real hidden taskpane can write to and read from the real workbook without foregrounding Excel.

For custom setup/assert/cleanup:

```bash
PI_BACKGROUND_VERIFY_TOKEN="$TOKEN" PI_BACKGROUND_VERIFY_HOST=localhost npm run background:verify:command -- writeRange \
  '{"address":"Sheet1!A1:B2","values":[["pi background smoke",2],["sum",3]]}'
PI_BACKGROUND_VERIFY_TOKEN="$TOKEN" PI_BACKGROUND_VERIFY_HOST=localhost npm run background:verify:command -- readRange '{"address":"Sheet1!A1:B2"}'
PI_BACKGROUND_VERIFY_TOKEN="$TOKEN" PI_BACKGROUND_VERIFY_HOST=localhost npm run background:verify:command -- clearRange '{"address":"Sheet1!A1:B2","applyTo":"contents"}'
```

When the product path itself is under test, submit an actual prompt through the sidebar instead of only calling Office.js helpers:

```bash
PI_BACKGROUND_VERIFY_TOKEN="$TOKEN" PI_BACKGROUND_VERIFY_HOST=localhost npm run background:verify:command -- submitPrompt \
  '{"text":"Write SMOKE into A1, then report exactly what changed.","waitForIdle":true,"timeoutMs":120000}'
PI_BACKGROUND_VERIFY_TOKEN="$TOKEN" PI_BACKGROUND_VERIFY_HOST=localhost npm run background:verify:command -- readRange '{"address":"Sheet1!A1"}'
```

Use the outputs as verification artifacts:

- `status`: proves taskpane origin, hidden/background visibility, Office/Excel globals, active runtime/model, input state.
- `officeProbe`: proves Office.js can read the real workbook from the hidden taskpane.
- `workbookWriteProbe`: proves the hidden taskpane can perform reversible real workbook writes and read back formula results.
- `writeRange` / `clearRange`: deterministic setup and cleanup for feature-specific smoke tests.

From e1wayt1cket/pi4office, MIT.

More from e1wayt1cket/pi4office