Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

backendSocket: dsh_list, dsh_install and dsh_remove answer through dsh/wire.ts

dee744f271d47f7
diff --git a/cli/src/backendSocket.dsh.spec.ts b/cli/src/backendSocket.dsh.spec.ts
new file mode 100644
index 000000000..4d8c72cc8
--- /dev/null
+++ b/cli/src/backendSocket.dsh.spec.ts
@@ -0,0 +1,107 @@
+// dsh_list, dsh_install and dsh_remove through the socket a local client (the desktop app) talks to:
+// the replies it gets, the status it is pushed, and what it gets when this daemon cannot do it.
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { BackendSocket } from './backendSocket.js'
+import { env } from './config/env.js'
+import { dshInstallDir, invalidateInstalledDsh, upsertInstalledRecord } from './dsh/installed.js'
+import { resetBundledDshRegistry } from './dsh/registry.js'
+
+describe('the DSH requests on the local socket', () => {
+ let socket: BackendSocket
+ let frames: Array<{ type: string; payload: Record<string, unknown> }>
+ let root: string
+ let savedDshDir: string
+ beforeEach(() => {
+ root = mkdtempSync(join(tmpdir(), 'dsh-socket-'))
+ savedDshDir = env.DSH_DIR
+ env.DSH_DIR = join(root, 'dsh')
+ invalidateInstalledDsh()
+ socket = new BackendSocket('token')
+ frames = []
+ socket.registerLocalClient('local:store', { sendFrame: (frame) => { frames.push(frame as (typeof frames)[number]); return true }, sendBinary: () => true })
+ })
+ afterEach(async () => {
+ await socket.unregisterLocalClient('local:store')
+ await socket.stop()
+ vi.unstubAllGlobals()
+ resetBundledDshRegistry()
+ env.DSH_DIR = savedDshDir
+ invalidateInstalledDsh()
+ rmSync(root, { recursive: true, force: true })
+ })
+
+ const ask = (type: string, payload: Record<string, unknown>): void => socket.handleLocalFrame('local:store', { type, payload })
+ const replies = (type: string): Array<Record<string, unknown>> => frames.filter((frame) => frame.type === `${type}_result`).map((frame) => frame.payload)
+
+ it('dsh_list: what is installed here, then what the registry offers', async () => {
+ vi.stubGlobal('__DSH_REGISTRY__', JSON.stringify([
+ { id: 'acme/thing', name: 'Thing', repo: 'https://example.com/thing.git', engine: 'claude', verified: true },
+ { id: 'acme/other', name: 'Other', repo: 'https://example.com/other.git', engine: 'codex', tier: 1 },
+ ]))
+ resetBundledDshRegistry()
+ mkdirSync(dshInstallDir('acme/thing'), { recursive: true })
+ writeFileSync(join(dshInstallDir('acme/thing'), 'harness.json'), JSON.stringify({ spec: 1, id: 'acme/thing', name: 'Thing here', engine: 'claude' }))
+ upsertInstalledRecord({ id: 'acme/thing', dir: dshInstallDir('acme/thing'), source: 'https://example.com/thing.git', ref: null, commit: null, linked: false, installedAt: 1 })
+ ask('dsh_list', { requestId: 'list-1' })
+ await vi.waitFor(() => expect(replies('dsh_list')).toHaveLength(1))
+ const [reply] = replies('dsh_list')
+ expect(reply.requestId).toBe('list-1')
+ expect((reply.dsh as Array<Record<string, unknown>>).map((row) => [row.id, row.name, row.installed, row.verified, row.tier]))
+ .toEqual([['acme/thing', 'Thing here', true, true, 0], ['acme/other', 'Other', false, false, 1]])
+ })
+
+ it('dsh_remove and dsh_install are refused on a daemon that cannot do them', async () => {
+ ask('dsh_remove', { requestId: 'rm-1', id: 'acme/thing' })
+ ask('dsh_install', { requestId: 'in-1', id: 'acme/thing' })
+ await vi.waitFor(() => expect(replies('dsh_install')).toHaveLength(1))
+ expect(replies('dsh_remove')).toEqual([expect.objectContaining({ requestId: 'rm-1', error: 'UNSUPPORTED_ON_REMOTE' })])
+ expect(replies('dsh_install')).toEqual([expect.objectContaining({ requestId: 'in-1', error: 'UNSUPPORTED_ON_REMOTE' })])
+ })
+
+ it('dsh_install: refuses a request with no usable id or url, before the daemon hears of it', async () => {
+ const asked: unknown[] = []
+ socket.onDshInstall = async (input) => { asked.push(input); return { ok: true, id: 'acme/thing' } }
+ ask('dsh_install', { requestId: 'in-1', id: '../../etc', url: 'https://example.com/\n' })
+ await vi.waitFor(() => expect(replies('dsh_install')).toHaveLength(1))
+ expect(replies('dsh_install')[0]).toMatchObject({ requestId: 'in-1', error: 'INVALID_DSH', detail: 'dsh_install needs an id or a url' })
+ expect(asked).toEqual([])
+ })
+
+ it('dsh_install: pushes each phase under the id asked for, then replies with what was installed', async () => {
+ const asked: unknown[] = []
+ socket.onDshInstall = async (input, progress) => {
+ asked.push(input)
+ progress({ id: null, phase: 'clone', detail: 'cloning' })
+ progress({ id: 'acme/thing', phase: 'doctor' })
+ return { ok: true, id: 'acme/thing' }
+ }
+ ask('dsh_install', { requestId: 'in-2', id: 'acme/thing', ref: 'store-e2e' })
+ await vi.waitFor(() => expect(replies('dsh_install')).toHaveLength(1))
+ expect(asked).toEqual([{ id: 'acme/thing', url: undefined, ref: 'store-e2e' }])
+ expect(frames.filter((frame) => frame.type === 'dsh_install_status').map((frame) => frame.payload)).toEqual([
+ { id: 'acme/thing', phase: 'clone', detail: 'cloning' },
+ { id: 'acme/thing', phase: 'doctor' },
+ ])
+ expect(replies('dsh_install')[0]).toMatchObject({ requestId: 'in-2', ok: true, id: 'acme/thing' })
+ })
+
+ it('dsh_install: a failed install is its error and detail; one that throws is INTERNAL with what was thrown', async () => {
+ socket.onDshInstall = async () => ({ ok: false, error: 'SETUP_FAILED', detail: 'setup exited 1' })
+ ask('dsh_install', { requestId: 'in-3', url: 'https://example.com/thing.git' })
+ await vi.waitFor(() => expect(replies('dsh_install')).toHaveLength(1))
+ socket.onDshInstall = async () => { throw new Error('disk full') }
+ ask('dsh_install', { requestId: 'in-4', url: 'https://example.com/thing.git' })
+ await vi.waitFor(() => expect(replies('dsh_install')).toHaveLength(2))
+ socket.onDshInstall = () => Promise.reject('not an Error')
+ ask('dsh_install', { requestId: 'in-5', url: 'https://example.com/thing.git' })
+ await vi.waitFor(() => expect(replies('dsh_install')).toHaveLength(3))
+ expect(replies('dsh_install')).toEqual([
+ expect.objectContaining({ requestId: 'in-3', error: 'SETUP_FAILED', detail: 'setup exited 1' }),
+ expect.objectContaining({ requestId: 'in-4', error: 'INTERNAL', detail: 'disk full' }),
+ expect.objectContaining({ requestId: 'in-5', error: 'INTERNAL', detail: 'not an Error' }),
+ ])
+ })
+})
diff --git a/cli/src/backendSocket.ts b/cli/src/backendSocket.ts
index bc1e66036..18e0a2577 100644
--- a/cli/src/backendSocket.ts
+++ b/cli/src/backendSocket.ts
@@ -36,10 +36,10 @@ import { parseProjectFolder, prepareProjectFolder, ProjectFolderError } from './
import { preTrustClaudeProject, preTrustCodexProject } from './lib/claudeTrust.js'
import { projectPreview } from './lib/projectPreview.js'
import { agentFrame, type AgentDshContext, type AgentFrame } from './lib/agentFrame.js'
-import { installedDsh, listInstalledDsh } from './dsh/installed.js'
-import { DSH_ID_RE, dshTier, viewerUse } from './dsh/manifest.js'
-import { bundledDshRegistry, registrySourceUrl } from './dsh/registry.js'
+import { installedDsh } from './dsh/installed.js'
+import { DSH_ID_RE } from './dsh/manifest.js'
import type { DshInstallProgress } from './dsh/install.js'
+import { dshInstallReply, dshInstallRequest, dshInstallStatus, dshListRows, dshRemoveId, dshRemoveReply } from './dsh/wire.js'
import { routeVoiceTask } from './lib/voiceRouter.js'
import { tailFile } from './lib/sessions.js'
import { messagesToEvents, windowRawLines, subagentStatsFromRawLines, type SessionEvent } from './lib/normalize.js'
@@ -1471,60 +1471,7 @@ export class BackendSocket {
case 'dsh_list': {
// Which domain-specific harnesses this machine has, plus what the bundled registry offers —
// answered here, on the machine in question, for the same reason `engines_probe` is.
- const installed = listInstalledDsh()
- const seen = new Set<string>()
- const rows: Record<string, unknown>[] = []
- // The store's facts (repo, homepage, upstream, licence, pictures) come from the registry
- // whether or not the package is installed: a manifest does not carry them.
- const facts = (id: string): Record<string, unknown> => {
- const known = bundledDshRegistry().find((entry) => entry.id === id)
- return {
- verified: known?.verified === true,
- // Where a person can read the package: its folder page for a built-in (store/…) one.
- repo: known ? registrySourceUrl(known) : null,
- homepage: known?.homepage ?? null,
- upstream: known?.upstream ?? null,
- license: known?.license ?? null,
- screenshots: known?.screenshots ?? [],
- }
- }
- for (const entry of installed) {
- seen.add(entry.id)
- rows.push({
- id: entry.id,
- kind: entry.manifest.kind ?? 'agent',
- name: entry.manifest.name,
- description: entry.manifest.description ?? null,
- category: entry.manifest.category ?? null,
- author: entry.manifest.author ?? null,
- engine: entry.manifest.engine ?? null,
- installed: true,
- linked: entry.linked === true,
- viewer: !!entry.manifest.viewer,
- viewerUse: viewerUse(entry.manifest),
- tier: dshTier(entry.manifest),
- ...facts(entry.id),
- })
- }
- for (const entry of bundledDshRegistry()) {
- if (seen.has(entry.id)) continue
- rows.push({
- id: entry.id,
- kind: entry.kind ?? 'agent',
- name: entry.name,
- description: entry.description ?? null,
- category: entry.category ?? null,
- author: entry.author ?? null,
- engine: entry.engine ?? null,
- installed: false,
- linked: false,
- viewer: (entry.tier ?? 0) >= 2,
- viewerUse: entry.viewerUse ?? null,
- tier: entry.tier ?? 0,
- ...facts(entry.id),
- })
- }
- reply(type, requestId, { dsh: rows })
+ reply(type, requestId, { dsh: dshListRows() })
return
}
@@ -1534,10 +1481,9 @@ export class BackendSocket {
// longer says installed. Agents already running from it keep running — their processes
// hold what they need — and the store is what asks; it refreshes the list itself.
if (!this.onDshRemove) { reply(type, requestId, { error: 'UNSUPPORTED_ON_REMOTE' }); return }
- const id = typeof payload.id === 'string' && DSH_ID_RE.test(payload.id) ? payload.id : undefined
+ const id = dshRemoveId(payload)
if (!id) { reply(type, requestId, { error: 'INVALID_DSH', detail: 'dsh_remove needs an id' }); return }
- const result = this.onDshRemove(id)
- reply(type, requestId, result.ok ? { ok: true, id } : { error: result.error, detail: result.detail })
+ reply(type, requestId, dshRemoveReply(id, this.onDshRemove(id)))
return
}
@@ -1546,12 +1492,10 @@ export class BackendSocket {
// it is detached from the ordered RPC chain like `engines_probe`, and progress travels as
// `dsh_install_status` pushes the app renders in the create dialog.
if (!this.onDshInstall) { reply(type, requestId, { error: 'UNSUPPORTED_ON_REMOTE' }); return }
- const id = typeof payload.id === 'string' && DSH_ID_RE.test(payload.id) ? payload.id : undefined
- const url = typeof payload.url === 'string' && payload.url.length <= 2048 && !/[\x00-\x1f\x7f]/.test(payload.url) ? payload.url : undefined
- const ref = typeof payload.ref === 'string' && payload.ref.length <= 200 ? payload.ref : undefined
- if (!id && !url) { reply(type, requestId, { error: 'INVALID_DSH', detail: 'dsh_install needs an id or a url' }); return }
- void this.onDshInstall({ id, url, ref }, (p) => this.send({ type: 'dsh_install_status', payload: { ...p, id: p.id ?? id ?? null } }))
- .then((result) => reply(type, requestId, result.ok ? { ok: true, id: result.id } : { error: result.error, detail: result.detail }))
+ const request = dshInstallRequest(payload)
+ if (!request) { reply(type, requestId, { error: 'INVALID_DSH', detail: 'dsh_install needs an id or a url' }); return }
+ void this.onDshInstall(request, (p) => this.send({ type: 'dsh_install_status', payload: dshInstallStatus(p, request) }))
+ .then((result) => reply(type, requestId, dshInstallReply(result)))
.catch((error) => reply(type, requestId, { error: 'INTERNAL', detail: error instanceof Error ? error.message : String(error) }))
return
}
diff --git a/cli/src/dsh/wire.spec.ts b/cli/src/dsh/wire.spec.ts
new file mode 100644
index 000000000..a7a899991
--- /dev/null
+++ b/cli/src/dsh/wire.spec.ts
@@ -0,0 +1,106 @@
+// The DSH wire contract (store/spec/README.md § Wire): what dsh_list rows say, and what dsh_install and
+// dsh_remove accept from a payload and answer.
+import { describe, expect, it } from 'vitest'
+import type { InstalledDsh } from './installed.js'
+import { HARNESS_MONOREPO, type DshRegistryEntry } from './registry.js'
+import { dshInstallReply, dshInstallRequest, dshInstallStatus, dshListRows, dshRemoveId, dshRemoveReply } from './wire.js'
+
+const installed = (manifest: InstalledDsh['manifest'], linked = false): InstalledDsh => ({
+ id: manifest.id, dir: `/Users/example/.harness/dsh/${manifest.id}`, realDir: `/Users/example/.harness/dsh/${manifest.id}`,
+ source: 'https://example.com/x.git', ref: null, commit: null, linked, installedAt: 0, manifest,
+})
+
+describe('dshListRows', () => {
+ const registry: DshRegistryEntry[] = [
+ {
+ id: 'autonomous/typst', name: 'Typst', category: 'Documents', author: 'Autonomous', description: 'Typeset.', engine: 'claude',
+ repo: HARNESS_MONOREPO, ref: 'main', path: 'store/agents/typst', tier: 2, verified: true, viewerUse: 'autonomous/doc-viewer',
+ homepage: 'https://typst.example.com', upstream: 'https://example.com/typst', license: 'MIT', screenshots: ['https://example.com/1.png'],
+ },
+ { id: 'autonomous/doc-viewer', kind: 'viewer', name: 'Doc Viewer', repo: HARNESS_MONOREPO, ref: 'main', path: 'store/viewers/doc-viewer', tier: 2, verified: true },
+ { id: 'acme/bare', name: 'Bare', repo: 'https://example.com/bare.git', engine: 'codex' },
+ ]
+
+ it('an installed harness is its manifest\'s words plus the registry\'s facts, listed once, before what is only offered', () => {
+ const rows = dshListRows([
+ installed({ spec: 1, id: 'autonomous/typst', name: 'Typst (local)', engine: 'claude', viewer: { use: 'autonomous/doc-viewer' } }, true),
+ installed({ spec: 1, id: 'acme/private', kind: 'viewer', name: 'Private', verdict: '.harness/verdict.json', viewer: { command: 'v.sh', url: 'http://127.0.0.1:${port}/' } }),
+ ], registry)
+ expect(rows).toEqual([
+ {
+ id: 'autonomous/typst', kind: 'agent', name: 'Typst (local)', description: null, category: null, author: null, engine: 'claude',
+ installed: true, linked: true, viewer: true, viewerUse: 'autonomous/doc-viewer', tier: 2,
+ verified: true, repo: `${HARNESS_MONOREPO}/tree/main/store/agents/typst`, homepage: 'https://typst.example.com',
+ upstream: 'https://example.com/typst', license: 'MIT', screenshots: ['https://example.com/1.png'],
+ },
+ {
+ id: 'acme/private', kind: 'viewer', name: 'Private', description: null, category: null, author: null, engine: null,
+ installed: true, linked: false, viewer: true, viewerUse: null, tier: 2,
+ verified: false, repo: null, homepage: null, upstream: null, license: null, screenshots: [],
+ },
+ {
+ id: 'autonomous/doc-viewer', kind: 'viewer', name: 'Doc Viewer', description: null, category: null, author: null, engine: null,
+ installed: false, linked: false, viewer: true, viewerUse: null, tier: 2,
+ verified: true, repo: `${HARNESS_MONOREPO}/tree/main/store/viewers/doc-viewer`, homepage: null, upstream: null, license: null, screenshots: [],
+ },
+ {
+ id: 'acme/bare', kind: 'agent', name: 'Bare', description: null, category: null, author: null, engine: 'codex',
+ installed: false, linked: false, viewer: false, viewerUse: null, tier: 0,
+ verified: false, repo: 'https://example.com/bare.git', homepage: null, upstream: null, license: null, screenshots: [],
+ },
+ ])
+ })
+
+ it('an installed harness keeps its own description, category and author; an offered one keeps the registry\'s', () => {
+ const [local, offered] = dshListRows([
+ installed({ spec: 1, id: 'acme/local', name: 'Local', description: 'Mine.', category: 'Tools', author: 'Example', engine: 'codex', verdict: '.harness/verdict.json' }),
+ ], registry.slice(0, 1))
+ expect(local).toMatchObject({ description: 'Mine.', category: 'Tools', author: 'Example', viewer: false, tier: 1 })
+ expect(offered).toMatchObject({ description: 'Typeset.', category: 'Documents', author: 'Autonomous', viewerUse: 'autonomous/doc-viewer' })
+ })
+
+ it('reads this machine and the bundled registry when given nothing', () => {
+ expect(Array.isArray(dshListRows())).toBe(true)
+ })
+})
+
+describe('dsh_remove', () => {
+ it('takes only an owner/name id', () => {
+ expect(dshRemoveId({ id: 'autonomous/marp' })).toBe('autonomous/marp')
+ for (const id of ['../../etc', 'Autonomous/Marp', 'marp', 7, undefined]) expect(dshRemoveId({ id }), String(id)).toBeUndefined()
+ })
+
+ it('answers ok with the id, or the error and its detail', () => {
+ expect(dshRemoveReply('autonomous/marp', { ok: true })).toEqual({ ok: true, id: 'autonomous/marp' })
+ expect(dshRemoveReply('autonomous/marp', { ok: false, error: 'NOT_INSTALLED', detail: 'autonomous/marp is not installed' }))
+ .toEqual({ error: 'NOT_INSTALLED', detail: 'autonomous/marp is not installed' })
+ })
+})
+
+describe('dsh_install', () => {
+ it('keeps a well-formed id, url and ref, and drops each field that is not', () => {
+ expect(dshInstallRequest({ id: 'autonomous/typst', ref: 'store-e2e' })).toEqual({ id: 'autonomous/typst', url: undefined, ref: 'store-e2e' })
+ expect(dshInstallRequest({ url: 'https://example.com/thing.git', ref: 'x'.repeat(201) })).toEqual({ id: undefined, url: 'https://example.com/thing.git', ref: undefined })
+ expect(dshInstallRequest({ id: 'not an id', url: 'https://example.com/thing.git' })).toEqual({ id: undefined, url: 'https://example.com/thing.git', ref: undefined })
+ expect(dshInstallRequest({ id: 'autonomous/typst', url: 'https://example.com/\n', ref: 3 })).toEqual({ id: 'autonomous/typst', url: undefined, ref: undefined })
+ })
+
+ it('is nothing without a usable id or url', () => {
+ for (const payload of [{}, { id: '../x' }, { url: '' }, { url: `https://example.com/${'x'.repeat(2048)}` }, { url: 'https://example.com/' }, { ref: 'main' }]) {
+ expect(dshInstallRequest(payload), JSON.stringify(payload).slice(0, 60)).toBeNull()
+ }
+ })
+
+ it('pushes status under the manifest\'s id once known, else the id asked for, else null', () => {
+ expect(dshInstallStatus({ id: 'autonomous/typst', phase: 'setup', detail: 'toolchain/setup.sh' }, { url: 'https://example.com/x.git' }))
+ .toEqual({ id: 'autonomous/typst', phase: 'setup', detail: 'toolchain/setup.sh' })
+ expect(dshInstallStatus({ id: null, phase: 'clone', line: 'Receiving objects: 40%' }, { id: 'autonomous/typst' }))
+ .toEqual({ id: 'autonomous/typst', phase: 'clone', line: 'Receiving objects: 40%' })
+ expect(dshInstallStatus({ id: null, phase: 'clone' }, { url: 'https://example.com/x.git' })).toEqual({ id: null, phase: 'clone' })
+ })
+
+ it('answers ok with the installed id, or the error and its detail', () => {
+ expect(dshInstallReply({ ok: true, id: 'autonomous/typst' })).toEqual({ ok: true, id: 'autonomous/typst' })
+ expect(dshInstallReply({ ok: false, error: 'DOCTOR_FAILED', detail: 'doctor failed · miss typst' })).toEqual({ error: 'DOCTOR_FAILED', detail: 'doctor failed · miss typst' })
+ })
+})
diff --git a/cli/src/dsh/wire.ts b/cli/src/dsh/wire.ts
new file mode 100644
index 000000000..5bd063374
--- /dev/null
+++ b/cli/src/dsh/wire.ts
@@ -0,0 +1,105 @@
+/**
+ * The DSH requests on the wire — `dsh_list`, `dsh_install`, `dsh_remove` — as backendSocket.ts answers
+ * them on the machine they are asked of: what each reads off a payload and what each replies. The
+ * socket only sends what these return; the contract is store/spec/README.md § Wire.
+ */
+import type { DshInstallProgress } from './install.js'
+import { listInstalledDsh, type InstalledDsh } from './installed.js'
+import { DSH_ID_RE, dshTier, viewerUse } from './manifest.js'
+import { bundledDshRegistry, registrySourceUrl, type DshRegistryEntry } from './registry.js'
+
+/**
+ * `dsh_list`: the harnesses installed on this machine, then what the registry offers that is not.
+ * The store's facts (repo, homepage, upstream, licence, pictures) come from the registry whether or not
+ * the package is installed: a manifest does not carry them.
+ */
+export function dshListRows(
+ installed: readonly InstalledDsh[] = listInstalledDsh(),
+ registry: readonly DshRegistryEntry[] = bundledDshRegistry(),
+): Record<string, unknown>[] {
+ const facts = (id: string): Record<string, unknown> => {
+ const known = registry.find((entry) => entry.id === id)
+ return {
+ verified: known?.verified === true,
+ // Where a person can read the package: its folder page for a built-in (store/…) one.
+ repo: known ? registrySourceUrl(known) : null,
+ homepage: known?.homepage ?? null,
+ upstream: known?.upstream ?? null,
+ license: known?.license ?? null,
+ screenshots: known?.screenshots ?? [],
+ }
+ }
+ const seen = new Set<string>()
+ const rows: Record<string, unknown>[] = []
+ for (const entry of installed) {
+ seen.add(entry.id)
+ rows.push({
+ id: entry.id,
+ kind: entry.manifest.kind ?? 'agent',
+ name: entry.manifest.name,
+ description: entry.manifest.description ?? null,
+ category: entry.manifest.category ?? null,
+ author: entry.manifest.author ?? null,
+ engine: entry.manifest.engine ?? null,
+ installed: true,
+ linked: entry.linked === true,
+ viewer: !!entry.manifest.viewer,
+ viewerUse: viewerUse(entry.manifest),
+ tier: dshTier(entry.manifest),
+ ...facts(entry.id),
+ })
+ }
+ for (const entry of registry) {
+ if (seen.has(entry.id)) continue
+ rows.push({
+ id: entry.id,
+ kind: entry.kind ?? 'agent',
+ name: entry.name,
+ description: entry.description ?? null,
+ category: entry.category ?? null,
+ author: entry.author ?? null,
+ engine: entry.engine ?? null,
+ installed: false,
+ linked: false,
+ viewer: (entry.tier ?? 0) >= 2,
+ viewerUse: entry.viewerUse ?? null,
+ tier: entry.tier ?? 0,
+ ...facts(entry.id),
+ })
+ }
+ return rows
+}
+
+/** `dsh_remove { id }`: the id, when it is one. */
+export function dshRemoveId(payload: Record<string, unknown>): string | undefined {
+ return typeof payload.id === 'string' && DSH_ID_RE.test(payload.id) ? payload.id : undefined
+}
+
+export type DshWireResult = { ok: true } | { ok: false; error: string; detail: string }
+
+export function dshRemoveReply(id: string, result: DshWireResult): Record<string, unknown> {
+ return result.ok ? { ok: true, id } : { error: result.error, detail: result.detail }
+}
+
+export interface DshInstallRequest { id?: string; url?: string; ref?: string }
+
+/**
+ * `dsh_install { id?, url?, ref? }`: what is usable of each field — an id that is one, a URL of bounded
+ * length with no control characters, a ref of bounded length — or null when neither an id nor a URL is.
+ */
+export function dshInstallRequest(payload: Record<string, unknown>): DshInstallRequest | null {
+ const id = typeof payload.id === 'string' && DSH_ID_RE.test(payload.id) ? payload.id : undefined
+ const url = typeof payload.url === 'string' && payload.url.length <= 2048 && !/[\x00-\x1f\x7f]/.test(payload.url) ? payload.url : undefined
+ const ref = typeof payload.ref === 'string' && payload.ref.length <= 200 ? payload.ref : undefined
+ if (!id && !url) return null
+ return { id, url, ref }
+}
+
+/** A `dsh_install_status` push: the phase, under the id asked for until the manifest names one. */
+export function dshInstallStatus(progress: DshInstallProgress, request: DshInstallRequest): Record<string, unknown> {
+ return { ...progress, id: progress.id ?? request.id ?? null }
+}
+
+export function dshInstallReply(result: { ok: true; id: string } | { ok: false; error: string; detail: string }): Record<string, unknown> {
+ return result.ok ? { ok: true, id: result.id } : { error: result.error, detail: result.detail }
+}