Home/stef-openclaw-skills
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Defer property assessor email gate

Browse Source
This commit is contained in:
Stefano Fiorini
2026-03-27 23:27:51 -05:00
parent f8c998d579
commit 1f23eac52c
10 changed files with 185 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
skills/property-assessor/SKILL.md
View File

@@ -91,7 +91,8 @@ scripts/property-assessor render-report --input "<report-payload-json>" --output
- try to discover Zillow and HAR listing URLs from the address when no listing URL is provided
- run the approval-safe Zillow/HAR photo extractor chain automatically
- build a purpose-aware report payload
- stop and ask for recipient email(s) before rendering the PDF
- complete the analysis without requiring recipient email(s)
- only stop and ask for recipient email(s) when the user is explicitly rendering or sending the PDF
- render the PDF only after recipient email(s) are known
## Public-record enrichment
@@ -361,6 +362,9 @@ The PDF report should include:
Before rendering or sending the PDF, the skill must know the target recipient email address(es).
This gate applies to the PDF step, not the analysis step.
Do not interrupt a normal assessment run just because recipient email is missing if the user has not yet asked to render or send the PDF.
If the prompt does **not** include target email(s):
- stop
- ask the user for the target email address(es)

28
skills/property-assessor/src/assessment.ts
View File

@@ -20,6 +20,7 @@ export interface AssessPropertyResult {
ok: true;
needsAssessmentPurpose: boolean;
needsRecipientEmails: boolean;
pdfReady: boolean;
message: string;
outputPath: string | null;
reportPayload: ReportPayload | null;
@@ -58,6 +59,13 @@ function asStringArray(value: unknown): string[] {
return [String(value).trim()].filter(Boolean);
}
function shouldRenderPdf(
options: AssessPropertyOptions,
recipientEmails: string[]
): boolean {
return Boolean(options.output || recipientEmails.length);
}
function slugify(value: string): string {
return value
.toLowerCase()
@@ -371,6 +379,7 @@ export async function assessProperty(
ok: true,
needsAssessmentPurpose: true,
needsRecipientEmails: false,
pdfReady: false,
message:
"Missing assessment purpose. Stop and ask the user why they want this property assessed before producing a decision-grade analysis.",
outputPath: null,
@@ -403,12 +412,14 @@ export async function assessProperty(
photoResolution.photoReview
);
const recipientEmails = asStringArray(options.recipientEmails);
const renderPdf = shouldRenderPdf(options, recipientEmails);
if (!recipientEmails.length) {
if (renderPdf && !recipientEmails.length) {
return {
ok: true,
needsAssessmentPurpose: false,
needsRecipientEmails: true,
pdfReady: false,
message:
"Missing target email. Stop and ask the user for target email address(es) before generating or sending the property assessment PDF.",
outputPath: null,
@@ -417,6 +428,20 @@ export async function assessProperty(
};
}
if (!renderPdf) {
return {
ok: true,
needsAssessmentPurpose: false,
needsRecipientEmails: false,
pdfReady: true,
message:
"Assessment payload is ready to render later. Review the analysis now; recipient email is only needed when you want the PDF.",
outputPath: null,
reportPayload,
publicRecords
};
}
const outputPath =
options.output ||
path.join(
@@ -429,6 +454,7 @@ export async function assessProperty(
ok: true,
needsAssessmentPurpose: false,
needsRecipientEmails: false,
pdfReady: true,
message: `Property assessment PDF rendered: ${renderedPath}`,
outputPath: renderedPath,
reportPayload,

34
skills/property-assessor/src/listing-discovery.ts
View File

@@ -1,7 +1,5 @@
import { execFile } from "node:child_process";
import { promisify } from "node:util";
const execFileAsync = promisify(execFile);
import { discoverHarListing } from "../../web-automation/scripts/har-discover.js";
import { discoverZillowListing } from "../../web-automation/scripts/zillow-discover.js";
export interface ListingDiscoveryResult {
attempts: string[];
@@ -9,37 +7,13 @@ export interface ListingDiscoveryResult {
harUrl: string | null;
}
function parseJsonOutput(raw: string, context: string): any {
const text = raw.trim();
if (!text) {
throw new Error(`${context} produced no JSON output.`);
}
return JSON.parse(text);
}
async function runDiscoveryScript(
scriptName: string,
address: string
): Promise<{ listingUrl: string | null; attempts: string[] }> {
const scriptPath = `/Users/stefano/.openclaw/workspace/skills/web-automation/scripts/${scriptName}`;
const { stdout } = await execFileAsync(process.execPath, [scriptPath, address], {
timeout: 120000,
maxBuffer: 2 * 1024 * 1024
});
const payload = parseJsonOutput(stdout, scriptName);
return {
listingUrl: typeof payload.listingUrl === "string" && payload.listingUrl.trim() ? payload.listingUrl.trim() : null,
attempts: Array.isArray(payload.attempts) ? payload.attempts.map(String) : []
};
}
export async function discoverListingSources(address: string): Promise<ListingDiscoveryResult> {
const attempts: string[] = [];
let zillowUrl: string | null = null;
let harUrl: string | null = null;
try {
const result = await runDiscoveryScript("zillow-discover.js", address);
const result = await discoverZillowListing(address);
zillowUrl = result.listingUrl;
attempts.push(...result.attempts);
} catch (error) {
@@ -49,7 +23,7 @@ export async function discoverListingSources(address: string): Promise<ListingDi
}
try {
const result = await runDiscoveryScript("har-discover.js", address);
const result = await discoverHarListing(address);
harUrl = result.listingUrl;
attempts.push(...result.attempts);
} catch (error) {

39
skills/property-assessor/src/photo-review.ts
View File

@@ -1,7 +1,5 @@
import { execFile } from "node:child_process";
import { promisify } from "node:util";
const execFileAsync = promisify(execFile);
import { extractHarPhotos } from "../../web-automation/scripts/har-photos.js";
import { extractZillowPhotos } from "../../web-automation/scripts/zillow-photos.js";
export type PhotoSource = "zillow" | "har";
@@ -21,28 +19,25 @@ export interface PhotoReviewResolution {
discoveredListingUrls: Array<{ label: string; url: string }>;
}
function parseJsonOutput(raw: string, context: string): any {
const text = raw.trim();
if (!text) {
throw new Error(`${context} produced no JSON output.`);
}
return JSON.parse(text);
}
export async function extractPhotoData(
source: PhotoSource,
url: string
): Promise<PhotoExtractionResult> {
const scriptMap: Record<PhotoSource, string> = {
zillow: "zillow-photos.js",
har: "har-photos.js"
};
const scriptPath = `/Users/stefano/.openclaw/workspace/skills/web-automation/scripts/${scriptMap[source]}`;
const { stdout } = await execFileAsync(process.execPath, [scriptPath, url], {
timeout: 180000,
maxBuffer: 5 * 1024 * 1024
});
const payload = parseJsonOutput(stdout, scriptMap[source]);
if (source === "zillow") {
const payload = await extractZillowPhotos(url);
return {
source,
requestedUrl: String(payload.requestedUrl || url),
finalUrl: typeof payload.finalUrl === "string" ? payload.finalUrl : undefined,
expectedPhotoCount: typeof payload.expectedPhotoCount === "number" ? payload.expectedPhotoCount : null,
complete: Boolean(payload.complete),
photoCount: Number(payload.photoCount || 0),
imageUrls: Array.isArray(payload.imageUrls) ? payload.imageUrls.map(String) : [],
notes: Array.isArray(payload.notes) ? payload.notes.map(String) : []
};
}
const payload = await extractHarPhotos(url);
return {
source,
requestedUrl: String(payload.requestedUrl || url),

41
skills/property-assessor/tests/assessment.test.ts
View File

@@ -62,7 +62,7 @@ test("assessProperty asks for assessment purpose before building a decision-grad
assert.equal(result.reportPayload, null);
});
test("assessProperty auto-discovers listing sources, runs Zillow photos first, and asks for recipient email", async () => {
test("assessProperty auto-discovers listing sources, runs Zillow photos first, and does not ask for email during analysis-only runs", async () => {
const result = await assessProperty(
{
address: "4141 Whiteley Dr, Corpus Christi, TX 78418",
@@ -97,9 +97,10 @@ test("assessProperty auto-discovers listing sources, runs Zillow photos first, a
assert.equal(result.ok, true);
assert.equal(result.needsAssessmentPurpose, false);
assert.equal(result.needsRecipientEmails, true);
assert.equal(result.needsRecipientEmails, false);
assert.equal(result.outputPath, null);
assert.match(result.message, /target email/i);
assert.doesNotMatch(result.message, /target email/i);
assert.match(result.message, /ready to render|recipient email is only needed when you want the pdf/i);
assert.equal(result.reportPayload?.subjectProperty?.address, samplePublicRecords.matchedAddress);
assert.equal(result.reportPayload?.publicRecords?.jurisdiction, "Nueces County Appraisal District");
assert.equal(result.reportPayload?.publicRecords?.accountNumber, "14069438");
@@ -117,6 +118,40 @@ test("assessProperty auto-discovers listing sources, runs Zillow photos first, a
assert.deepEqual(result.reportPayload?.recipientEmails, []);
});
test("assessProperty asks for recipient email only when PDF render is explicitly requested", async () => {
const result = await assessProperty(
{
address: "4141 Whiteley Dr, Corpus Christi, TX 78418",
assessmentPurpose: "investment property",
output: path.join(os.tmpdir(), `property-assess-missing-email-${Date.now()}.pdf`)
},
{
resolvePublicRecordsFn: async () => samplePublicRecords,
discoverListingSourcesFn: async () => ({
attempts: ["Zillow discovery located a property page from the address."],
zillowUrl:
"https://www.zillow.com/homedetails/4141-Whiteley-Dr-Corpus-Christi-TX-78418/2103723704_zpid/",
harUrl: null
}),
extractPhotoDataFn: async (source, url) => ({
source,
requestedUrl: url,
finalUrl: url,
expectedPhotoCount: 29,
complete: true,
photoCount: 29,
imageUrls: ["https://photos.example/1.jpg"],
notes: [`${source} extractor succeeded.`]
})
}
);
assert.equal(result.ok, true);
assert.equal(result.needsRecipientEmails, true);
assert.equal(result.outputPath, null);
assert.match(result.message, /target email/i);
});
test("assessProperty falls back to HAR when Zillow photo extraction fails", async () => {
const result = await assessProperty(
{

44
skills/web-automation/scripts/har-discover.js
View File

@@ -1,5 +1,7 @@
#!/usr/bin/env node
import { pathToFileURL } from "node:url";
import {
createPageSession,
dismissCommonOverlays,
@@ -57,8 +59,8 @@ async function collectListingUrl(page) {
});
}
async function main() {
const address = String(process.argv[2] || "").trim();
export async function discoverHarListing(rawAddress) {
const address = String(rawAddress || "").trim();
const identity = parseAddressIdentity(address);
const searchUrl = buildSearchUrl(address);
const { context, page } = await createPageSession({ headless: process.env.HEADLESS !== "false" });
@@ -101,30 +103,36 @@ async function main() {
}
}
process.stdout.write(
`${JSON.stringify(
{
source: "har",
address,
searchUrl,
finalUrl: page.url(),
title: await page.title(),
listingUrl,
attempts,
},
null,
2
)}\n`
);
const result = {
source: "har",
address,
searchUrl,
finalUrl: page.url(),
title: await page.title(),
listingUrl,
attempts,
};
await context.close();
return result;
} catch (error) {
try {
await context.close();
} catch {
// Ignore close errors after the primary failure.
}
throw new Error(`HAR discovery failed: ${error instanceof Error ? error.message : String(error)}`);
}
}
async function main() {
try {
const result = await discoverHarListing(process.argv[2]);
process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
} catch (error) {
fail("HAR discovery failed.", error instanceof Error ? error.message : String(error));
}
}
main();
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
main();
}

21
skills/web-automation/scripts/har-photos.js
View File

@@ -1,5 +1,7 @@
#!/usr/bin/env node
import { pathToFileURL } from "node:url";
import {
clickPhotoEntryPoint,
collectRenderedImageCandidates,
@@ -29,8 +31,8 @@ async function getAnnouncedPhotoCount(page) {
});
}
async function main() {
const requestedUrl = parseTarget(process.argv[2]);
export async function extractHarPhotos(rawUrl) {
const requestedUrl = parseTarget(rawUrl);
const { context, page } = await createPageSession({ headless: process.env.HEADLESS !== "false" });
try {
@@ -68,16 +70,27 @@ async function main() {
notes: ["Opened HAR all-photos flow and extracted large rendered image URLs from the photo page."],
};
process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
await context.close();
return result;
} catch (error) {
try {
await context.close();
} catch {
// Ignore close errors after the primary failure.
}
throw new Error(error instanceof Error ? error.message : String(error));
}
}
async function main() {
try {
const result = await extractHarPhotos(process.argv[2]);
process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
} catch (error) {
fail("HAR photo extraction failed.", error instanceof Error ? error.message : String(error));
}
}
main();
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
main();
}

44
skills/web-automation/scripts/zillow-discover.js
View File

@@ -1,5 +1,7 @@
#!/usr/bin/env node
import { pathToFileURL } from "node:url";
import {
createPageSession,
dismissCommonOverlays,
@@ -61,8 +63,8 @@ async function collectListingUrl(page) {
});
}
async function main() {
const address = String(process.argv[2] || "").trim();
export async function discoverZillowListing(rawAddress) {
const address = String(rawAddress || "").trim();
const identity = parseAddressIdentity(address);
const searchUrl = `https://www.zillow.com/homes/${encodeURIComponent(buildZillowAddressSlug(address))}_rb/`;
const { context, page } = await createPageSession({ headless: process.env.HEADLESS !== "false" });
@@ -105,30 +107,36 @@ async function main() {
}
}
process.stdout.write(
`${JSON.stringify(
{
source: "zillow",
address,
searchUrl,
finalUrl: page.url(),
title: await page.title(),
listingUrl,
attempts,
},
null,
2
)}\n`
);
const result = {
source: "zillow",
address,
searchUrl,
finalUrl: page.url(),
title: await page.title(),
listingUrl,
attempts,
};
await context.close();
return result;
} catch (error) {
try {
await context.close();
} catch {
// Ignore close errors after the primary failure.
}
throw new Error(`Zillow discovery failed: ${error instanceof Error ? error.message : String(error)}`);
}
}
async function main() {
try {
const result = await discoverZillowListing(process.argv[2]);
process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
} catch (error) {
fail("Zillow discovery failed.", error instanceof Error ? error.message : String(error));
}
}
main();
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
main();
}

21
skills/web-automation/scripts/zillow-photos.js
View File

@@ -1,5 +1,7 @@
#!/usr/bin/env node
import { pathToFileURL } from "node:url";
import {
clickPhotoEntryPoint,
createPageSession,
@@ -102,8 +104,8 @@ async function collectZillowStructuredPhotoCandidates(page) {
return extractZillowStructuredPhotoCandidatesFromNextDataScript(scriptText || "");
}
async function main() {
const requestedUrl = parseTarget(process.argv[2]);
export async function extractZillowPhotos(rawUrl) {
const requestedUrl = parseTarget(rawUrl);
const { context, page } = await createPageSession({ headless: process.env.HEADLESS !== "false" });
try {
@@ -167,16 +169,27 @@ async function main() {
notes,
};
process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
await context.close();
return result;
} catch (error) {
try {
await context.close();
} catch {
// Ignore close errors after the primary failure.
}
throw new Error(error instanceof Error ? error.message : String(error));
}
}
async function main() {
try {
const result = await extractZillowPhotos(process.argv[2]);
process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
} catch (error) {
fail("Zillow photo extraction failed.", error instanceof Error ? error.message : String(error));
}
}
main();
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
main();
}