Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ This repository is the DeepSeek Harness port of pstack 0.15.43, pinned to https:
- `.agents/skills/<name>/SKILL.md` holds every skill. DSH discovers this directory as a project skill root; `lib/index.js` serves the same tree when the package is installed as a profile bundle.
- `lib/` is the bundle's skill provider. `lib/parse.js` is the pure frontmatter reader used by tests.
- `cordis.patch.yml` inserts the `pstack` row into a profile. `package.json` declares the bundle through `dsh.bundle.patch`.
- `COMPATIBILITY.md` records the DSH metadata limits and the history of the icon regression. Read it before changing the package manifest, icon, locale, or detail document.
- `docs/guide/` is the user guide. `docs/harness/dsh.md` maps the Cursor names the upstream content inherited.
- `automations/benny/` is a dormant Slack triage and repro pack. It is not registered as a skill.

Expand All @@ -18,6 +19,7 @@ This repository is the DeepSeek Harness port of pstack 0.15.43, pinned to https:
- Do not reintroduce Cursor or Antigravity fields such as `subagent_type`, `environment`, `Workspace`, `TypeName`, `model` slugs, `~/.cursor`, or `~/.gemini`.
- Route guidance lives in `~/.agents/pstack-models.md`. A missing file or line means `inherit`. Pass `provider`, `model`, and `reasoning_effort` only when the `subagent` tool exposes them.
- DSH subagents share this machine. Isolate writers with a git worktree passed as `cwd`.
- When porting upstream, re-encode the icon instead of copying `assets/logo.png`. DSH rejects icons over 256 KiB. `COMPATIBILITY.md` records the limit and the measured pixel delta, and `npm test` enforces the limit.

## Validate

Expand All @@ -26,4 +28,4 @@ npm install --omit=peer
npm test
```

`npm test` checks skill frontmatter, the poteto-mode principle and playbook indexes, relative Markdown links, the bundle manifest, and leftover Cursor/Antigravity tokens. CI also runs the shell and TypeScript script checks under `.agents/skills/poteto-mode/scripts`. The slow statechart integration suite runs in a separate scheduled job.
`npm test` checks skill frontmatter, the poteto-mode principle and playbook indexes, relative Markdown links, the bundle manifest, the plugin icon limits, and leftover Cursor/Antigravity tokens. CI also runs the shell and TypeScript script checks under `.agents/skills/poteto-mode/scripts`. The slow statechart integration suite runs in a separate scheduled job.
81 changes: 81 additions & 0 deletions COMPATIBILITY.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
# DSH compatibility

DeepSeek Harness reads a bundle's display metadata from package files before it evaluates any plugin code. A value that breaks a limit is reported in **Settings → Plugins** as a **Package metadata error**, for example:

```text
Package metadata error: Plugin metadata for dsh-pstack: Error: /…/node_modules/dsh-pstack/package.json: icon exceeds 256 KiB
```

The skills still load, but the plugin row loses its icon and the profile reports a broken package. This file records the limits that produce that error, the rules that keep this repository inside them, and the history of the one time we crossed a limit.

## Metadata limits

| Surface | Limit | This bundle |
| --- | --- | --- |
| `package.json` `icon` | At most 262,144 bytes (256 KiB). SVG, PNG, JPEG, or WebP. A path relative to the package root that stays inside the package after resolving symlinks, and names a regular file. A manifest `icon` wins over an exported `./icon`. | [`assets/logo.webp`](./assets/logo.webp), 236,818 bytes, 512×512 WebP. See [Icon encoding](#icon-encoding). |
| Locale | `locale/en.json`; `meta.title` and `meta.description` must be non-empty strings. Other locale files use a language id as the filename. | Not exported. DSH falls back to `package.json` `name` and `description`. |
| Detail document | The file named by `meta.detail` is limited to `pluginManager.detailMaxBytes`, 1 MiB by default. | Not exported. DSH shows [README.md](./README.md). |
| Bundle patch | `dsh.bundle.patch` must name an existing file. The patch must insert a row whose `name` equals the package name. | `./cordis.patch.yml` inserts the `pstack` row. |
| Runtime | Node `^22.19.0 || >=24.0.0`; peers `@deepseek-ai/cordis@^4.0.1` and `@deepseek-ai/dsh-skill@^0.2.1-rc.2`. | DSH skips the whole bundle when its peers do not match the running runtime. See [README.md](./README.md#compatibility). |

DSH measures the raw file bytes, not decoded pixels. A 512×512 image can pass or fail depending only on how it is encoded. The host limit is `MAX_ICON_BYTES = 256 * 1024` in the package metadata reader; the same reader rejects absolute paths, URLs, files outside the package, unsupported extensions, and non-regular files.

## Rules for this repository

- **Never copy the upstream icon byte-for-byte.** `cursor/plugins` ships `assets/logo.png` at 361,140 bytes (353 KiB), which DSH rejects. Re-encode it. Lossless PNG and lossless WebP of those pixels are still over 262,144 bytes. The shipped file is [`assets/logo.webp`](./assets/logo.webp). Its pixel delta is in [Icon encoding](#icon-encoding).
- **Keep the icon in `files`.** `npm pack` filters by the `files` list; the `assets` directory entry covers the icon.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is not the same artwork. the 59,835-byte palette png from fbc1aae changes 252,331/262,144 pixels vs the 0.15.43 / upstream rgb file (max channel 29, channel-sum 62). the ImageChops rgba getbbox check is a false negative (difference alpha is 0, so bbox is always none). re-encode losslessly if it fits under 256 kib; otherwise document the real delta and don't say the pixels are unchanged.

- **Run the gate before opening a PR.** `npm test` fails when the declared icon is missing, outside the package, not SVG/PNG/JPEG/WebP, over 256 KiB, inconsistent with its extension's magic bytes, or absent from `files`.
- **Check the packed artifact when packaging changes.** `npm pack --dry-run` must list the icon, and a scratch profile install must render it without a metadata diagnostic.
- **Do not raise the limit.** The 256 KiB ceiling belongs to DSH, not this package. Shrink or re-encode the image instead.
- **Do not edit the installed copy by hand.** Fix the package, reinstall it into the profile, and restart the profile.

## Icon encoding

The upstream artwork is the 361,140-byte file at `71980e0` (`assets/logo.png`, 512×512, 8-bit RGB, 30,424 colors). DSH's limit is 262,144 raw bytes. These lossless encodings keep every RGB pixel and still miss that limit.

| Encoder | Bytes |
| --- | --- |
| oxipng 9.1.5 `-o max --zopfli --zi 15` | 360,735 |
| zopflipng 1.0.3 `--iterations=15 --filters=0me` | 361,471, larger than the input, so the 361,140-byte file remains |
| cwebp 1.5.0 `-lossless -z 9 -metadata none` | 270,696 |
| cwebp 1.3.2 `-lossless -z 9 -metadata none`, and Pillow 10.2 lossless WebP | 275,910 |

Pull request review 5934203113 measured a Pillow lossless WebP of this artwork at 270,552 bytes. That figure and the 270,696-byte cwebp 1.5.0 file are both above 262,144. Decoded pixels for every lossless row in the table match the upstream file.

The shipped file is `assets/logo.webp`, 236,818 bytes, from libwebp 1.5.0. Regenerate it from the upstream bytes at `71980e0`:

```bash
git show 71980e071d3fe27e4db538c74a16c6a0c3f9f04b:assets/logo.png > /tmp/upstream-logo.png
cwebp -near_lossless 99 -z 9 -metadata none /tmp/upstream-logo.png -o assets/logo.webp
```

`-near_lossless` moves some pixels by a small integer, then compresses the result losslessly. For this image, levels 80 through 99 emit the same bytes. Level 100 is the 270,696-byte lossless file.

Compare RGB after decoding. An RGBA `ImageChops` bounding box stays empty when every alpha difference is 0, including when RGB differs. A changed pixel is one whose R, G, or B differs. Channel delta is the absolute difference in one channel. Channel-sum is those three differences added at one pixel. Alpha is counted on its own. `dwebp` from libwebp 1.5.0 and Pillow 10.2 decode this WebP to the same RGB pixels.

| Asset | Bytes | Pixels changed | Max channel delta | Max channel-sum | Alpha delta |
| --- | --- | --- | --- | --- | --- |
| Upstream 8-bit RGB | 361,140 | 0 / 262,144 | 0 | 0 | 0 |
| Shipped WebP | 236,818 | 102,105 / 262,144 | 1 | 3 | 0 |
| `fbc1aae` palette PNG | 59,835 | 252,331 / 262,144 | 29 | 62 | 0 |

The shipped WebP's absolute RGB channel differences sum to 176,315. Every changed pixel moves by 1 in one or more channels, and no channel moves by more than 1. The palette PNG is the previous 211-color stand-in. Its RGBA difference has no bounding box because the alpha difference is 0 everywhere, while the RGB difference covers the whole 512×512 image.

Lossy WebP at `-q 100` fits in 95,282 bytes and is a worse picture. 251,832 pixels change, and the max channel delta is 86.

## Why the regression happened

- **2026-10-26, `fbc1aae`:** the original 361,140-byte icon was replaced with a 59,835-byte palette PNG. DSH accepted the bundle. That file is not the same artwork. The delta is in the table above.
- **2026-11-09, `e12d636` ("Fix portreview audit issues 16-27"):** audit issue #27 restored the upstream icon byte-for-byte to match `cursor/plugins` at `c742dd6`. That brought back the 361,140-byte file and produced the error in 0.15.43.
- **Fix:** ship the 236,818-byte WebP and gate `npm test` on the icon, so copying the upstream file back fails CI instead of failing at install time. Do not put the `fbc1aae` palette PNG back.

## Recovering an installed profile

A profile installed before the fix keeps the oversized icon in its own `node_modules`. Reinstall the bundle and restart the profile:

```bash
dsh plugin --profile <profile> add github:pstack-ports/dsh-pstack
dsh --profile <profile>
```

Then confirm the pstack row in **Settings → Plugins** shows the logo and no red metadata error.
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,8 @@ two things that look like bugs but are not:
- DSH reads `package.json` — `dsh.bundle.patch`, `icon`, and `engines.dsh` when present. it does not read `plugin.json`; that manifest is for other agent-plugin ecosystems.
- the `@deepseek-ai/*` peers come from the DSH installation, not from this package, so install it with `dsh plugin add`. a standalone `npm install` will not resolve them.

the packaging limits that produce a **Package metadata error** — including the 256 KiB icon ceiling — are in [COMPATIBILITY.md](./COMPATIBILITY.md).

## get started

two steps:
Expand Down
Binary file removed assets/logo.png
Binary file not shown.
Binary file added assets/logo.webp
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
3 changes: 2 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
"url": "git+https://github.com/pstack-ports/dsh-pstack.git"
},
"license": "MIT",
"icon": "./assets/logo.png",
"icon": "./assets/logo.webp",
"type": "module",
"main": "lib/index.js",
"exports": {
Expand All @@ -29,6 +29,7 @@
"cordis.patch.yml",
"plugin.json",
"AGENTS.md",
"COMPATIBILITY.md",
"README.md",
"LICENSE"
],
Expand Down
71 changes: 66 additions & 5 deletions scripts/validate.mjs
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
#!/usr/bin/env node
import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
import { dirname, join, relative, resolve, sep } from 'node:path'
import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs'
import { dirname, extname, isAbsolute, join, relative, resolve, sep, win32 } from 'node:path'
import process from 'node:process'
import { fileURLToPath } from 'node:url'
import { parse as parseYaml } from 'yaml'
Expand Down Expand Up @@ -99,7 +99,7 @@ for (const field of ['name', 'version', 'description']) {
if (manifest.dsh?.bundle?.patch !== './cordis.patch.yml') {
fail('package.json must declare dsh.bundle.patch = ./cordis.patch.yml')
}
for (const required of ['lib', '.agents', 'cordis.patch.yml', 'plugin.json', 'AGENTS.md', 'README.md', 'LICENSE']) {
for (const required of ['lib', '.agents', 'cordis.patch.yml', 'plugin.json', 'AGENTS.md', 'COMPATIBILITY.md', 'README.md', 'LICENSE']) {
if (!(manifest.files ?? []).includes(required)) fail(`package.json files must include "${required}"`)
}
const plugin = JSON.parse(readFileSync(join(ROOT, 'plugin.json'), 'utf8'))
Expand All @@ -123,6 +123,67 @@ else {
}
}

// 3b. The declared icon stays inside the DSH metadata limits.
// DSH reads package.json without evaluating the plugin; an oversized icon
// becomes "Package metadata error: ... icon exceeds 256 KiB" in the plugin row.
const MAX_ICON_BYTES = 256 * 1024
const ICON_EXTENSIONS = new Set(['.svg', '.png', '.jpg', '.jpeg', '.webp'])

function iconProblem(icon) {
if (typeof icon !== 'string' || icon.trim() === '') {
return 'package.json must declare a non-empty "icon" path so DSH can render the plugin row'
}
if (isAbsolute(icon) || win32.isAbsolute(icon) || /^[A-Za-z][A-Za-z\d+.-]*:/u.test(icon)) {
return `package.json icon "${icon}" must be a relative file path`
}
const declared = join(ROOT, icon)
if (!existsSync(declared)) return `package.json icon "${icon}" does not exist`
const file = realpathSync(declared)
const local = relative(realpathSync(ROOT), file)
if (local === '..' || local.startsWith(`..${sep}`) || isAbsolute(local)) {
return `package.json icon "${icon}" must remain inside the package`
}
const extension = extname(file).toLowerCase()
if (!ICON_EXTENSIONS.has(extension)) {
return `package.json icon "${icon}" must be SVG, PNG, JPEG, or WebP`
}
const stat = statSync(file)
if (!stat.isFile()) return `package.json icon "${icon}" must be a regular file`
if (stat.size > MAX_ICON_BYTES) {
return `package.json icon "${icon}" is ${stat.size} bytes and exceeds 256 KiB (${MAX_ICON_BYTES} bytes); DSH will reject it. Re-encode the image.`
}
const bytes = readFileSync(file)
if (bytes.length > MAX_ICON_BYTES) {
return `package.json icon "${icon}" is ${bytes.length} bytes and exceeds 256 KiB (${MAX_ICON_BYTES} bytes); DSH will reject it. Re-encode the image.`
}
const head = bytes.subarray(0, 512)
const isJpeg = head[0] === 0xff && head[1] === 0xd8 && head[2] === 0xff
let valid = false
if (extension === '.png') {
valid = head.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))
} else if (extension === '.jpg' || extension === '.jpeg') {
valid = isJpeg
} else if (extension === '.webp') {
valid = head.subarray(0, 4).toString('ascii') === 'RIFF'
&& head.subarray(8, 12).toString('ascii') === 'WEBP'
} else {
valid = /<svg[\s>]/u.test(bytes.toString('utf8'))
}
if (!valid) {
return `package.json icon "${icon}" does not contain ${extension.slice(1).toUpperCase()} data`
}
const packed = relative(ROOT, file).split(sep).join('/')
const covered = (manifest.files ?? []).some((entry) => {
const path = entry.replace(/^\.\//u, '').replace(/\/$/u, '')
return packed === path || packed.startsWith(`${path}/`)
})
if (!covered) return `package.json files must include icon "${icon}"`
return undefined
}

const iconFailure = iconProblem(manifest.icon)
if (iconFailure !== undefined) fail(iconFailure)

// 4. Relative Markdown links resolve.
function checkLinks(file) {
const raw = readFileSync(file, 'utf8')
Expand All @@ -139,7 +200,7 @@ function checkLinks(file) {
}
}
}
for (const file of [join(ROOT, 'README.md')]) checkLinks(file)
for (const file of [join(ROOT, 'README.md'), join(ROOT, 'COMPATIBILITY.md')]) checkLinks(file)
walk(join(ROOT, 'docs'), (file) => {
if (file.endsWith('.md')) checkLinks(file)
})
Expand Down Expand Up @@ -180,4 +241,4 @@ if (problems.length > 0) {
for (const problem of problems) console.error(`ERROR: ${problem}`)
process.exit(1)
}
console.log(`Validated ${candidates.length} skills, ${diskPlaybooks.size} playbooks, ${indexedPrinciples.size} principles, and the DSH bundle manifest.`)
console.log(`Validated ${candidates.length} skills, ${diskPlaybooks.size} playbooks, ${indexedPrinciples.size} principles, the DSH bundle manifest, and the plugin icon.`)
Loading