fix: make property-assessor safer for whatsapp runs
This commit is contained in:
180
docs/plans/2026-03-28-property-assessor-whatsapp-safe-runtime.md
Normal file
180
docs/plans/2026-03-28-property-assessor-whatsapp-safe-runtime.md
Normal file
@@ -0,0 +1,180 @@
|
||||
# Property Assessor WhatsApp-Safe Runtime Implementation Plan
|
||||
|
||||
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
||||
|
||||
**Goal:** Keep WhatsApp property-assessor runs moving by failing fast on silent discovery/photo hangs, avoiding helper subprocesses during core analysis, and reserving subprocess use to the final PDF render attempt only.
|
||||
|
||||
**Architecture:** Add small timeout guards around the existing in-process listing discovery and photo extraction calls so one quiet browser-backed task cannot stall the entire assessment. Tighten the live skill and published docs so messaging runs treat chat-native source collection as the default path and helper commands as non-chat or final-render-only tools.
|
||||
|
||||
**Tech Stack:** TypeScript, Node test runner, existing OpenClaw property-assessor skill, existing OpenClaw web-automation modules, Markdown docs.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Add failing timeout tests for discovery and photo extraction
|
||||
|
||||
**Files:**
|
||||
- Modify: `skills/property-assessor/tests/assessment.test.ts`
|
||||
|
||||
**Step 1: Write the failing test**
|
||||
|
||||
Add tests that stub discovery/photo functions with never-resolving promises and assert that:
|
||||
- listing discovery returns `null` URLs and records timeout attempts
|
||||
- photo extraction returns `not completed` instead of hanging forever
|
||||
|
||||
**Step 2: Run test to verify it fails**
|
||||
|
||||
Run: `npm test -- --test-name-pattern "times out"`
|
||||
Expected: FAIL because current code never times out or records timeout attempts.
|
||||
|
||||
**Step 3: Write minimal implementation**
|
||||
|
||||
Implement the smallest timeout wrapper needed for the tests to pass.
|
||||
|
||||
**Step 4: Run test to verify it passes**
|
||||
|
||||
Run: `npm test -- --test-name-pattern "times out"`
|
||||
Expected: PASS
|
||||
|
||||
**Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add skills/property-assessor/tests/assessment.test.ts
|
||||
git commit -m "test: cover stalled discovery and photo extraction"
|
||||
```
|
||||
|
||||
### Task 2: Implement hard timeout guards in the live assessment path
|
||||
|
||||
**Files:**
|
||||
- Create: `skills/property-assessor/src/async-timeout.ts`
|
||||
- Modify: `skills/property-assessor/src/listing-discovery.ts`
|
||||
- Modify: `skills/property-assessor/src/photo-review.ts`
|
||||
|
||||
**Step 1: Write the failing test**
|
||||
|
||||
Use the tests from Task 1 as the red phase.
|
||||
|
||||
**Step 2: Run test to verify it fails**
|
||||
|
||||
Run: `npm test -- --test-name-pattern "times out"`
|
||||
Expected: FAIL
|
||||
|
||||
**Step 3: Write minimal implementation**
|
||||
|
||||
Add:
|
||||
- a shared timeout helper for async operations
|
||||
- timeout-wrapped Zillow/HAR discovery in `listing-discovery.ts`
|
||||
- timeout-wrapped Zillow/HAR photo extraction in `photo-review.ts`
|
||||
- clear timeout attempt messages so the assessment can continue honestly
|
||||
|
||||
**Step 4: Run test to verify it passes**
|
||||
|
||||
Run: `npm test -- --test-name-pattern "times out"`
|
||||
Expected: PASS
|
||||
|
||||
**Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add skills/property-assessor/src/async-timeout.ts skills/property-assessor/src/listing-discovery.ts skills/property-assessor/src/photo-review.ts skills/property-assessor/tests/assessment.test.ts
|
||||
git commit -m "fix: fail fast on stalled property-assessor extraction steps"
|
||||
```
|
||||
|
||||
### Task 3: Tighten live skill instructions for WhatsApp-safe execution
|
||||
|
||||
**Files:**
|
||||
- Modify: `../skills/property-assessor/SKILL.md`
|
||||
|
||||
**Step 1: Write the failing test**
|
||||
|
||||
No automated test. Use the documented runtime rule as the spec:
|
||||
- WhatsApp/messaging runs must avoid helper subprocesses for core analysis
|
||||
- only the final PDF render attempt may use the helper subprocess path
|
||||
- `update?` must remain status-only
|
||||
|
||||
**Step 2: Run verification to confirm current docs are wrong**
|
||||
|
||||
Run: `rg -n "scripts/property-assessor assess|node zillow-photos|node har-photos|Good:" ../skills/property-assessor/SKILL.md`
|
||||
Expected: current doc still presents helper commands as normal chat-safe core workflow.
|
||||
|
||||
**Step 3: Write minimal implementation**
|
||||
|
||||
Update the live skill doc to:
|
||||
- prefer `web_search`, `web_fetch`, and bounded `web-automation` for core assessment
|
||||
- forbid `scripts/property-assessor assess`, `node zillow-photos.js`, `node har-photos.js`, and ad hoc `curl` as the default WhatsApp core path
|
||||
- allow a single final PDF render attempt only after a decision-grade verdict exists
|
||||
|
||||
**Step 4: Run verification**
|
||||
|
||||
Run: `sed -n '1,220p' ../skills/property-assessor/SKILL.md`
|
||||
Expected: the WhatsApp-safe runtime rules are explicit and unambiguous.
|
||||
|
||||
**Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add ../skills/property-assessor/SKILL.md
|
||||
git commit -m "docs: clarify whatsapp-safe property-assessor execution"
|
||||
```
|
||||
|
||||
### Task 4: Mirror the runtime guidance into the published repo docs
|
||||
|
||||
**Files:**
|
||||
- Modify: `docs/property-assessor.md`
|
||||
- Modify: `docs/web-automation.md`
|
||||
|
||||
**Step 1: Write the failing test**
|
||||
|
||||
No automated test. The spec is consistency with the live skill instructions.
|
||||
|
||||
**Step 2: Run verification to confirm current docs drift**
|
||||
|
||||
Run: `rg -n "node zillow-photos|node har-photos|assess --address" docs/property-assessor.md docs/web-automation.md`
|
||||
Expected: current docs still imply subprocess-heavy commands are the standard chat path.
|
||||
|
||||
**Step 3: Write minimal implementation**
|
||||
|
||||
Document:
|
||||
- chat-native assessment first
|
||||
- timeout-protected discovery/photo extraction behavior
|
||||
- final-render-only subprocess attempt from messaging runs
|
||||
|
||||
**Step 4: Run verification**
|
||||
|
||||
Run: `sed -n '1,220p' docs/property-assessor.md && sed -n '1,220p' docs/web-automation.md`
|
||||
Expected: published docs match the live skill behavior.
|
||||
|
||||
**Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add docs/property-assessor.md docs/web-automation.md
|
||||
git commit -m "docs: document whatsapp-safe property assessment flow"
|
||||
```
|
||||
|
||||
### Task 5: Verify the focused runtime behavior
|
||||
|
||||
**Files:**
|
||||
- Modify: `skills/property-assessor/tests/assessment.test.ts`
|
||||
- Verify: `skills/property-assessor/src/*.ts`
|
||||
- Verify: `../skills/property-assessor/SKILL.md`
|
||||
- Verify: `docs/property-assessor.md`
|
||||
- Verify: `docs/web-automation.md`
|
||||
|
||||
**Step 1: Run focused tests**
|
||||
|
||||
Run: `npm test`
|
||||
Expected: all `property-assessor` tests pass, including timeout coverage.
|
||||
|
||||
**Step 2: Run targeted source verification**
|
||||
|
||||
Run: `rg -n "withTimeout|timed out|final PDF render" skills/property-assessor/src ../skills/property-assessor/SKILL.md docs/property-assessor.md docs/web-automation.md`
|
||||
Expected: timeout guards and the final-render-only messaging rule are present.
|
||||
|
||||
**Step 3: Inspect git status**
|
||||
|
||||
Run: `git status --short`
|
||||
Expected: only intended files are modified.
|
||||
|
||||
**Step 4: Commit**
|
||||
|
||||
```bash
|
||||
git add skills/property-assessor/src/async-timeout.ts skills/property-assessor/src/listing-discovery.ts skills/property-assessor/src/photo-review.ts skills/property-assessor/tests/assessment.test.ts ../skills/property-assessor/SKILL.md docs/property-assessor.md docs/web-automation.md docs/plans/2026-03-28-property-assessor-whatsapp-safe-runtime.md
|
||||
git commit -m "fix: make property-assessor safer for whatsapp runs"
|
||||
```
|
||||
Reference in New Issue
Block a user