dsh-browser-verify 0.1.4 → 0.1.5

package/README.md

@@ -18,7 +18,7 @@ verification is just tool calls.
 ## Quick start
 
 ```sh
-dsh plugin --profile web add dsh-browser-verify@0.1.4
+dsh plugin --profile web add dsh-browser-verify@0.1.5
 ```
 
 1. **Install** with the command above (or see [Install](#install)).
@@ -85,7 +85,7 @@ browser_screenshot
 ## Install
 
 ```sh
-dsh plugin --profile web add dsh-browser-verify@0.1.4
+dsh plugin --profile web add dsh-browser-verify@0.1.5
 ```
 
 The version is pinned on purpose: pnpm 11 holds back packages published in the

package/README.zh.md

@@ -12,7 +12,7 @@
 ## 快速上手
 
 ```sh
-dsh plugin --profile web add dsh-browser-verify@0.1.4
+dsh plugin --profile web add dsh-browser-verify@0.1.5
 ```
 
 1. **安装**（更多方式见 [安装](#安装)）。
@@ -74,7 +74,7 @@ browser_screenshot
 ## 安装
 
 ```sh
-dsh plugin --profile web add dsh-browser-verify@0.1.4
+dsh plugin --profile web add dsh-browser-verify@0.1.5
 ```
 
 版本故意钉死：pnpm 11 会暂缓 24 小时内新发布的包，裸写 `add dsh-browser-verify`（latest）会在发布当天装到上一个版本。`--profile web`

package/lib/index.js

@@ -29,6 +29,18 @@ function selectOrphanDirs(entries, nowMs, ageMs, prefix) {
 }
 //#endregion
 //#region src/attachments.ts
+/**
+* Formats a stored screenshot can carry: Playwright captures PNG, and the
+* attachment store re-encodes above its normalization budget (JPEG, or WebP
+* when the source keeps alpha). Every entry is a possible store fact — never
+* assume PNG.
+*/
+const SCREENSHOT_MEDIA_TYPES = [
+	"image/png",
+	"image/jpeg",
+	"image/webp",
+	"image/gif"
+];
 function imageRefFromValue(image) {
 	return {
 		attachmentId: AttachmentId(image.attachmentId),
@@ -36,14 +48,44 @@ function imageRefFromValue(image) {
 		bytes: image.bytes,
 		width: image.width,
 		height: image.height,
-		...image.name === void 0 ? {} : { name: image.name }
+		...image.name === void 0 ? {} : { name: image.name },
+		...image.originalDimensions === void 0 ? {} : { originalDimensions: image.originalDimensions }
+	};
+}
+/**
+* Build the tool value from the store reference alone. Every fact — format,
+* byte length, dimensions — is copied from what the store actually published,
+* because the read path re-derives them from the stored bytes and rejects any
+* reference that disagrees. Restating a constant here (e.g. PNG for a capture
+* the store normalized to JPEG) writes a self-contradicting attachment
+* reference into immutable history, which fails every later model request.
+* @param ref - reference returned by `saveImage`.
+* @param sha256 - digest of the captured bytes.
+* @param identicalToPrevious - whether this capture repeated the previous one.
+* @returns the tool-facing value projected into the model context.
+*/
+function screenshotValueFrom(ref, sha256, identicalToPrevious) {
+	return {
+		image: {
+			attachmentId: String(ref.attachmentId),
+			mediaType: ref.mediaType,
+			bytes: ref.bytes,
+			width: ref.width,
+			height: ref.height,
+			...ref.name === void 0 ? {} : { name: ref.name },
+			...ref.originalDimensions === void 0 ? {} : { originalDimensions: ref.originalDimensions }
+		},
+		sha256,
+		identicalToPrevious
 	};
 }
 function renderScreenshotBlocks(value) {
 	const dup = value.identicalToPrevious ? "（与上一张截图哈希相同，疑似页面未刷新；请 browser_open 重开场景后重试）" : "";
+	const original = value.image.originalDimensions;
+	const scaled = original === void 0 ? "" : `（原图 ${original.width}x${original.height}，已按宿主预算缩放）`;
 	return [{
 		type: "text",
-		text: `<type>screenshot</type>\n<content>\n${value.image.mediaType}, ${value.image.width}x${value.image.height} px, ${value.image.bytes} bytes, sha256 ${value.sha256.slice(0, 12)}${dup}\n</content>`
+		text: `<type>screenshot</type>\n<content>\n${value.image.mediaType}, ${value.image.width}x${value.image.height} px${scaled}, ${value.image.bytes} bytes, sha256 ${value.sha256.slice(0, 12)}${dup}\n</content>`
 	}, {
 		type: "image",
 		attachment: imageRefFromValue(value.image)
@@ -380,7 +422,7 @@ function registerBrowserTools(ctx) {
 							},
 							mediaType: {
 								type: "string",
-								enum: ["image/png"],
+								enum: [...SCREENSHOT_MEDIA_TYPES],
 								required: true
 							},
 							bytes: {
@@ -395,7 +437,21 @@ function registerBrowserTools(ctx) {
 								type: "integer",
 								required: true
 							},
-							name: { type: "string" }
+							name: { type: "string" },
+							originalDimensions: {
+								type: "object",
+								additionalProperties: false,
+								properties: {
+									width: {
+										type: "number",
+										required: true
+									},
+									height: {
+										type: "number",
+										required: true
+									}
+								}
+							}
 						}
 					},
 					sha256: {
@@ -414,19 +470,7 @@ function registerBrowserTools(ctx) {
 			await assertImageCapable(ctx, exec);
 			return driver.withScenario(async (scenario) => {
 				const shot = await scenario.screenshot({ fullPage: args.fullPage });
-				const ref = await saveScreenshot(ctx, shot.data, args.name);
-				return {
-					image: {
-						attachmentId: String(ref.attachmentId),
-						mediaType: "image/png",
-						bytes: ref.bytes,
-						width: ref.width,
-						height: ref.height,
-						...ref.name === void 0 ? {} : { name: ref.name }
-					},
-					sha256: shot.sha256,
-					identicalToPrevious: shot.identicalToPrevious
-				};
+				return screenshotValueFrom(await saveScreenshot(ctx, shot.data, args.name), shot.sha256, shot.identicalToPrevious);
 			});
 		}
 	}));

package/lib/types/attachments.d.ts

@@ -7,6 +7,13 @@
 import type { Context } from '@deepseek-ai/cordis';
 import type { ImageAttachmentRef, ImageMediaType } from '@deepseek-ai/dsh-attachment';
 import type { ContentBlock } from '@deepseek-ai/dsh-llm';
+/**
+ * Formats a stored screenshot can carry: Playwright captures PNG, and the
+ * attachment store re-encodes above its normalization budget (JPEG, or WebP
+ * when the source keeps alpha). Every entry is a possible store fact — never
+ * assume PNG.
+ */
+export declare const SCREENSHOT_MEDIA_TYPES: readonly ["image/png", "image/jpeg", "image/webp", "image/gif"];
 export interface ScreenshotImage {
     attachmentId: string;
     mediaType: ImageMediaType;
@@ -14,6 +21,11 @@ export interface ScreenshotImage {
     width: number;
     height: number;
     name?: string;
+    /** Present only when the store downscaled the capture; the pre-scaling pixels. */
+    originalDimensions?: {
+        width: number;
+        height: number;
+    };
 }
 export interface ScreenshotValue {
     image: ScreenshotImage;
@@ -21,6 +33,19 @@ export interface ScreenshotValue {
     identicalToPrevious: boolean;
 }
 export declare function imageRefFromValue(image: ScreenshotImage): ImageAttachmentRef;
+/**
+ * Build the tool value from the store reference alone. Every fact — format,
+ * byte length, dimensions — is copied from what the store actually published,
+ * because the read path re-derives them from the stored bytes and rejects any
+ * reference that disagrees. Restating a constant here (e.g. PNG for a capture
+ * the store normalized to JPEG) writes a self-contradicting attachment
+ * reference into immutable history, which fails every later model request.
+ * @param ref - reference returned by `saveImage`.
+ * @param sha256 - digest of the captured bytes.
+ * @param identicalToPrevious - whether this capture repeated the previous one.
+ * @returns the tool-facing value projected into the model context.
+ */
+export declare function screenshotValueFrom(ref: ImageAttachmentRef, sha256: string, identicalToPrevious: boolean): ScreenshotValue;
 export declare function renderScreenshotBlocks(value: ScreenshotValue): ContentBlock[];
 /** Persist screenshot bytes, mapping store refusals to actionable errors. */
 export declare function saveScreenshot(ctx: Context, data: Buffer, name: string | undefined): Promise<ImageAttachmentRef>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-browser-verify",
   "description": "Read-only browser verification tools for the DeepSeek Harness web GUI: browser_open / browser_mock / browser_assert / browser_screenshot — verify a page (H5/desktop) in ≤4 tool calls with mock interception, DOM assertions, and screenshots that auto-project into the model context.",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "type": "module",
   "packageManager": "pnpm@11.7.0",
   "engines": {

package/src/attachments.ts

@@ -10,6 +10,16 @@ import type { ImageAttachmentRef, ImageMediaType } from '@deepseek-ai/dsh-attach
 import { AttachmentError, AttachmentId } from '@deepseek-ai/dsh-attachment'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 
+/**
+ * Formats a stored screenshot can carry: Playwright captures PNG, and the
+ * attachment store re-encodes above its normalization budget (JPEG, or WebP
+ * when the source keeps alpha). Every entry is a possible store fact — never
+ * assume PNG.
+ */
+export const SCREENSHOT_MEDIA_TYPES = [
+  'image/png', 'image/jpeg', 'image/webp', 'image/gif',
+] as const satisfies readonly ImageMediaType[]
+
 export interface ScreenshotImage {
   attachmentId: string
   mediaType: ImageMediaType
@@ -17,6 +27,8 @@ export interface ScreenshotImage {
   width: number
   height: number
   name?: string
+  /** Present only when the store downscaled the capture; the pre-scaling pixels. */
+  originalDimensions?: { width: number; height: number }
 }
 
 export interface ScreenshotValue {
@@ -33,6 +45,39 @@ export function imageRefFromValue(image: ScreenshotImage): ImageAttachmentRef {
     width: image.width,
     height: image.height,
     ...image.name === undefined ? {} : { name: image.name },
+    ...image.originalDimensions === undefined ? {} : { originalDimensions: image.originalDimensions },
+  }
+}
+
+/**
+ * Build the tool value from the store reference alone. Every fact — format,
+ * byte length, dimensions — is copied from what the store actually published,
+ * because the read path re-derives them from the stored bytes and rejects any
+ * reference that disagrees. Restating a constant here (e.g. PNG for a capture
+ * the store normalized to JPEG) writes a self-contradicting attachment
+ * reference into immutable history, which fails every later model request.
+ * @param ref - reference returned by `saveImage`.
+ * @param sha256 - digest of the captured bytes.
+ * @param identicalToPrevious - whether this capture repeated the previous one.
+ * @returns the tool-facing value projected into the model context.
+ */
+export function screenshotValueFrom(
+  ref: ImageAttachmentRef,
+  sha256: string,
+  identicalToPrevious: boolean,
+): ScreenshotValue {
+  return {
+    image: {
+      attachmentId: String(ref.attachmentId),
+      mediaType: ref.mediaType,
+      bytes: ref.bytes,
+      width: ref.width,
+      height: ref.height,
+      ...ref.name === undefined ? {} : { name: ref.name },
+      ...ref.originalDimensions === undefined ? {} : { originalDimensions: ref.originalDimensions },
+    },
+    sha256,
+    identicalToPrevious,
   }
 }
 
@@ -40,10 +85,12 @@ export function renderScreenshotBlocks(value: ScreenshotValue): ContentBlock[] {
   const dup = value.identicalToPrevious
     ? '（与上一张截图哈希相同，疑似页面未刷新；请 browser_open 重开场景后重试）'
     : ''
+  const original = value.image.originalDimensions
+  const scaled = original === undefined ? '' : `（原图 ${original.width}x${original.height}，已按宿主预算缩放）`
   return [
     {
       type: 'text',
-      text: `<type>screenshot</type>\n<content>\n${value.image.mediaType}, ${value.image.width}x${value.image.height} px, ${value.image.bytes} bytes, sha256 ${value.sha256.slice(0, 12)}${dup}\n</content>`,
+      text: `<type>screenshot</type>\n<content>\n${value.image.mediaType}, ${value.image.width}x${value.image.height} px${scaled}, ${value.image.bytes} bytes, sha256 ${value.sha256.slice(0, 12)}${dup}\n</content>`,
     },
     { type: 'image', attachment: imageRefFromValue(value.image) },
   ]

package/src/tools/index.ts

@@ -7,7 +7,7 @@
 import type { Context } from '@deepseek-ai/cordis'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import { BrowserDriver } from '../browser/driver.ts'
-import { assertImageCapable, renderScreenshotBlocks, saveScreenshot } from '../attachments.ts'
+import { assertImageCapable, renderScreenshotBlocks, saveScreenshot, SCREENSHOT_MEDIA_TYPES, screenshotValueFrom } from '../attachments.ts'
 import { withTimeout } from './timeout.ts'
 
 /** Parse a positive-integer env var; NaN/zero/negative falls back to the default. */
@@ -150,11 +150,19 @@ export function registerBrowserTools(ctx: Context): void {
             required: true,
             properties: {
               attachmentId: { type: 'string', required: true },
-              mediaType: { type: 'string', enum: ['image/png'], required: true },
+              mediaType: { type: 'string', enum: [...SCREENSHOT_MEDIA_TYPES], required: true },
               bytes: { type: 'integer', required: true },
               width: { type: 'integer', required: true },
               height: { type: 'integer', required: true },
               name: { type: 'string' },
+              originalDimensions: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                  width: { type: 'number', required: true },
+                  height: { type: 'number', required: true },
+                },
+              },
             },
           },
           sha256: { type: 'string', required: true },
@@ -168,18 +176,8 @@ export function registerBrowserTools(ctx: Context): void {
       return driver.withScenario(async scenario => {
         const shot = await scenario.screenshot({ fullPage: args.fullPage })
         const ref = await saveScreenshot(ctx, shot.data, args.name)
-        return {
-          image: {
-            attachmentId: String(ref.attachmentId),
-            mediaType: 'image/png' as const,
-            bytes: ref.bytes,
-            width: ref.width,
-            height: ref.height,
-            ...ref.name === undefined ? {} : { name: ref.name },
-          },
-          sha256: shot.sha256,
-          identicalToPrevious: shot.identicalToPrevious,
-        }
+        // Facts come from the store ref: a normalized capture is no longer a PNG.
+        return screenshotValueFrom(ref, shot.sha256, shot.identicalToPrevious)
       })
     },
   }))