dsh-stage 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,22 @@
1
+ # Changelog
2
+
3
+ ## 0.1.0
4
+
5
+ - Add the topology protocol MVP: `ctx.stage` with `setTopology()` / `topology()`
6
+ and validated display, window and space snapshots.
7
+ - Add named layouts with display-relative `0..1` zones (`setLayout()` /
8
+ `layouts()`), including normalized-zone and bounds validation.
9
+ - Add `applyLayout()`: computes focused-first window assignments in native
10
+ display units, records the intent in history and returns
11
+ `{ layout, assignments }` without calling any native window API.
12
+ - Add bounded newest-first `history(limit)` for topology, layout, apply and
13
+ undo entries, plus `undo()` for the most recent un-undone apply.
14
+ - Register the plain-object agent tools `stage_topology`, `stage_layout_set`,
15
+ `stage_layout_apply`, `stage_layout_list` and `stage_undo`.
16
+ - Document that 0.1.0 is the topology protocol MVP and that the macOS AX and
17
+ Windows Win32 adapters are planned for 0.2.0.
18
+
19
+ ## 0.0.1
20
+
21
+ - Reserve the `dsh-stage` package name.
22
+ - Publish the bundle manifest and an empty, side-effect-free plugin entry.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 PerryLink contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,199 @@
1
- # Temporary Holding Version
1
+ # Stage · `dsh-stage`
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ > **Topology before action.** Read displays, windows and spaces, describe layouts
4
+ > as display-relative zones, and apply them as recorded, undoable intent.
5
+
6
+ **Status: 0.1.0 is the topology protocol MVP.** Stage validates and records
7
+ topology and layout intent only. It never calls a native window API and cannot
8
+ move a window yet. The **macOS AX adapter and Windows Win32 adapter are planned
9
+ for 0.2.0**. Until an adapter ships, a host integration supplies observations
10
+ through `ctx.stage.setTopology()`.
11
+
12
+ **Not affiliated with DeepSeek.** DeepSeek and DeepSeek Harness are trademarks
13
+ of their respective owners. "Stage" here means arranging windows as a stage; it
14
+ is unrelated to Apple Stage Manager.
15
+
16
+ ## Install
17
+
18
+ ```sh
19
+ dsh plugin --profile web add dsh-stage
20
+ ```
21
+
22
+ Requires Node 22.19+ (or Node 24.9+). No runtime dependencies.
23
+
24
+ ## Host seam
25
+
26
+ The bundle provides `ctx.stage`:
27
+
28
+ ```js
29
+ const stage = ctx.get('stage')
30
+
31
+ stage.setTopology({
32
+ displays: [
33
+ {
34
+ id: 'main',
35
+ bounds: { x: 0, y: 0, w: 1600, h: 1000 },
36
+ workArea: { x: 0, y: 25, w: 1600, h: 950 },
37
+ dpi: 96,
38
+ },
39
+ ],
40
+ windows: [
41
+ {
42
+ id: 'editor',
43
+ displayId: 'main',
44
+ bounds: { x: 40, y: 40, w: 900, h: 700 },
45
+ focused: true,
46
+ },
47
+ ],
48
+ spaces: [{ id: 'desk-1', displayId: 'main', current: true }],
49
+ })
50
+ ```
51
+
52
+ ### Topology
53
+
54
+ - `displays[]`: `id`, `bounds` (`{x, y, w, h}` with positive `w`/`h`) and a
55
+ positive finite `dpi` are required. `workArea` is optional and defaults to
56
+ `bounds`; it is the origin for zones.
57
+ - `windows[]`: `id`, `displayId` and `bounds` are required. `displayId` must
58
+ reference a display in the same call. `focused` is an optional boolean,
59
+ default `false`; at most one window may be focused.
60
+ - `spaces[]`: `id` and `displayId` are required; `index` is a non-negative
61
+ integer (default `0`) and `current` is a boolean (default `false`). Spaces
62
+ are best-effort metadata and do not affect layout.
63
+ - Ids are non-empty strings and unique within their collection. Bounds may
64
+ have negative `x`/`y` (multi-display global space).
65
+ - `topology()` returns the current snapshot:
66
+ `{ schema, displays, windows, spaces, topologyHash, observedAt }`.
67
+ `topologyHash` is a 16-hex-character digest of the three collections.
68
+ Before the first `setTopology()` the collections are empty and both
69
+ `topologyHash` and `observedAt` are `null`.
70
+ - Bounds and zone results stay in the adapter's native/global coordinate
71
+ units. 0.1.0 reports `dpi` as metadata but does not rescale coordinates, so
72
+ mixed-DPI setups never get an implicit conversion.
73
+
74
+ Errors carry a stable `code`: `invalid_topology`, `invalid_display`,
75
+ `invalid_bounds`, `invalid_window`, `invalid_space`, `unknown_display`,
76
+ `duplicate_display`, `duplicate_window`, `duplicate_space`,
77
+ `duplicate_focus`.
78
+
79
+ ### Layouts
80
+
81
+ `setLayout(name, { displayId, zones })` creates or replaces a named layout.
82
+ Each zone is `{ x, y, w, h }` normalized to `0..1` relative to the display's
83
+ `workArea`. A zone needs positive `w`/`h` and must fit:
84
+ `x + w <= 1` and `y + h <= 1`. A layout holds 1 to 20 zones.
85
+
86
+ ```js
87
+ stage.setLayout('halves', {
88
+ displayId: 'main',
89
+ zones: [
90
+ { x: 0, y: 0, w: 0.5, h: 1 },
91
+ { x: 0.5, y: 0, w: 0.5, h: 1 },
92
+ ],
93
+ })
94
+ ```
95
+
96
+ `layouts()` lists definitions sorted by name. Setting an existing name
97
+ replaces it. Definitions can be created before the display is observed; the
98
+ display reference is checked again at apply time.
99
+
100
+ ### Apply, history and undo
101
+
102
+ `applyLayout(name)` requires an observed topology, a registered layout and the
103
+ layout's display. It pairs windows on that display with zones in listed order:
104
+ the focused window first, then windows in observation order. Extra zones stay
105
+ empty and extra windows are untouched. The call returns exactly
106
+ `{ layout, assignments }`:
107
+
108
+ ```json
109
+ {
110
+ "layout": {
111
+ "name": "halves",
112
+ "displayId": "main",
113
+ "zones": [
114
+ { "x": 0, "y": 0, "w": 0.5, "h": 1 },
115
+ { "x": 0.5, "y": 0, "w": 0.5, "h": 1 }
116
+ ]
117
+ },
118
+ "assignments": [
119
+ {
120
+ "windowId": "editor",
121
+ "displayId": "main",
122
+ "zone": 0,
123
+ "rect": { "x": 0, "y": 25, "w": 800, "h": 950 }
124
+ }
125
+ ]
126
+ }
127
+ ```
128
+
129
+ `zone` is the zero-based index into `layout.zones`. `rect` is in the display's
130
+ native units, relative to `workArea`, with fractional values rounded to six
131
+ decimal places. No OS call is made: the record is intent for a future adapter.
132
+
133
+ `history(limit = 20)` returns the newest entries first. Entries have an `id`,
134
+ an ISO `at` and a `type` of `topology`, `layout`, `apply` or `undo`; `limit`
135
+ must be an integer from 1 to 200, and history keeps at most 200 entries.
136
+
137
+ `undo()` reverses the most recent apply that has not already been undone. It
138
+ marks that apply's history entry `undone: true`, appends an `undo` entry and
139
+ returns a receipt:
140
+
141
+ ```json
142
+ {
143
+ "schema": "dsh.stage.undo/v1",
144
+ "undone": {
145
+ "id": "h3",
146
+ "at": "2026-11-20T12:00:00.000Z",
147
+ "layout": {
148
+ "name": "halves",
149
+ "displayId": "main",
150
+ "zones": [
151
+ { "x": 0, "y": 0, "w": 0.5, "h": 1 },
152
+ { "x": 0.5, "y": 0, "w": 0.5, "h": 1 }
153
+ ]
154
+ },
155
+ "assignments": [
156
+ {
157
+ "windowId": "editor",
158
+ "displayId": "main",
159
+ "zone": 0,
160
+ "rect": { "x": 0, "y": 25, "w": 800, "h": 950 }
161
+ }
162
+ ]
163
+ }
164
+ }
165
+ ```
166
+
167
+ With no undoable apply, `undo()` throws `nothing_to_undo`. Error codes for
168
+ apply are `no_topology`, `unknown_layout`, `unknown_display` and
169
+ `invalid_layout` (bad name); history uses `invalid_limit`.
170
+
171
+ Because 0.1.0 performs no native writes, undo is a ledger reversal only.
172
+ Restoring window rectangles, verifying placement and handling user-moved
173
+ windows are adapter concerns for 0.2.0.
174
+
175
+ ## Agent tools
176
+
177
+ | Tool | Input | Returns |
178
+ |---|---|---|
179
+ | `stage_topology` | — | `{ schema, displays, windows, spaces, topologyHash, observedAt }` |
180
+ | `stage_layout_set` | `name`, `displayId`, `zones[]` | `{ layout }` |
181
+ | `stage_layout_apply` | `name` | `{ layout, assignments }` |
182
+ | `stage_layout_list` | — | `{ layouts }` |
183
+ | `stage_undo` | — | undo receipt |
184
+
185
+ All five are plain-object tool definitions with JSON Schema parameters and text
186
+ renderers; they do not depend on `@deepseek-ai/dsh-tools`. The `StageService`
187
+ methods can be used directly without the tool registry, which is how tests and
188
+ future adapters exercise the protocol.
189
+
190
+ ## Scope
191
+
192
+ 0.1.0 does **not** enumerate the real desktop, move or resize windows, request
193
+ accessibility or screen-recording permissions, read Spaces through private
194
+ APIs, persist layouts or emit events. Those belong to the macOS AX and Windows
195
+ Win32 adapters, verification and storage work scheduled for 0.2.0.
196
+
197
+ ## License
198
+
199
+ MIT.
@@ -0,0 +1,4 @@
1
+ # dsh-stage bundle patch: mount the plugin.
2
+ - insert:
3
+ - id: dsh-stage
4
+ name: dsh-stage
package/index.js ADDED
@@ -0,0 +1,338 @@
1
+ /**
2
+ * dsh-stage — display, window and space topology protocol for DeepSeek Harness.
3
+ *
4
+ * 0.1.0 is the topology protocol MVP: the `ctx.stage` service, named layouts
5
+ * made of display-relative 0..1 zones, applied-intent assignments, bounded
6
+ * history and undo. It never calls a native window API; macOS AX and Windows
7
+ * Win32 adapters are scoped for 0.2.0.
8
+ * @module dsh-stage
9
+ */
10
+ import { createHash } from 'node:crypto'
11
+
12
+ /** Cordis plugin name. */
13
+ export const name = 'dsh-stage'
14
+
15
+ /** The protocol is usable without tools; the agent tools need the registry. */
16
+ export const inject = ['tools']
17
+
18
+ /** Stable schema ids for returned values. */
19
+ export const SCHEMAS = { topology: 'dsh.stage.topology/v1', undo: 'dsh.stage.undo/v1' }
20
+
21
+ const MAX_ZONES = 20
22
+ const MAX_HISTORY = 200
23
+ const DEFAULT_HISTORY = 20
24
+ const EPSILON = 1e-9
25
+ const RECT_KEYS = ['x', 'y', 'w', 'h']
26
+
27
+ const fail = (code, message) => Object.assign(new Error(message), { code })
28
+ const isObject = value => value !== null && typeof value === 'object' && !Array.isArray(value)
29
+ const clone = value => structuredClone(value)
30
+ const round = value => Math.round(value * 1e6) / 1e6
31
+ const now = () => new Date().toISOString()
32
+
33
+ function text(value, code, label) {
34
+ if (typeof value !== 'string' || value.trim() === '') throw fail(code, `${label} must be a non-empty string`)
35
+ if (value.includes('\0')) throw fail(code, `${label} must not contain NUL`)
36
+ return value
37
+ }
38
+
39
+ function rectOf(value, label) {
40
+ if (!isObject(value)) throw fail('invalid_bounds', `${label} must be an object`)
41
+ const { x, y, w, h } = value
42
+ if (![x, y, w, h].every(number => typeof number === 'number' && Number.isFinite(number))) {
43
+ throw fail('invalid_bounds', `${label}.x, .y, .w and .h must be finite numbers`)
44
+ }
45
+ if (w <= 0 || h <= 0) throw fail('invalid_bounds', `${label}.w and .h must be positive`)
46
+ return { x, y, w, h }
47
+ }
48
+
49
+ function arrayOf(value, label) {
50
+ if (value === undefined) return []
51
+ if (!Array.isArray(value)) throw fail('invalid_topology', `${label} must be an array`)
52
+ return value
53
+ }
54
+
55
+ function unique(seen, id, code, label) {
56
+ if (seen.has(id)) throw fail(code, `${label} "${id}" is repeated`)
57
+ seen.add(id)
58
+ }
59
+
60
+ function normalizeDisplay(value, index) {
61
+ if (!isObject(value)) throw fail('invalid_display', `displays[${index}] must be an object`)
62
+ const id = text(value.id, 'invalid_display', `displays[${index}].id`)
63
+ const bounds = rectOf(value.bounds, `displays[${index}].bounds`)
64
+ const workArea = value.workArea === undefined ? bounds : rectOf(value.workArea, `displays[${index}].workArea`)
65
+ if (typeof value.dpi !== 'number' || !Number.isFinite(value.dpi) || value.dpi <= 0) {
66
+ throw fail('invalid_display', `displays[${index}].dpi must be a positive finite number`)
67
+ }
68
+ return { id, bounds, workArea, dpi: value.dpi }
69
+ }
70
+
71
+ function normalizeWindow(value, index, displayIds) {
72
+ if (!isObject(value)) throw fail('invalid_window', `windows[${index}] must be an object`)
73
+ const id = text(value.id, 'invalid_window', `windows[${index}].id`)
74
+ const displayId = text(value.displayId, 'invalid_window', `windows[${index}].displayId`)
75
+ if (!displayIds.has(displayId)) throw fail('unknown_display', `windows[${index}].displayId "${displayId}" is not in displays`)
76
+ const bounds = rectOf(value.bounds, `windows[${index}].bounds`)
77
+ const focused = value.focused === undefined ? false : value.focused
78
+ if (typeof focused !== 'boolean') throw fail('invalid_window', `windows[${index}].focused must be a boolean`)
79
+ return { id, displayId, bounds, focused }
80
+ }
81
+
82
+ function normalizeSpace(value, index, displayIds) {
83
+ if (!isObject(value)) throw fail('invalid_space', `spaces[${index}] must be an object`)
84
+ const id = text(value.id, 'invalid_space', `spaces[${index}].id`)
85
+ const displayId = text(value.displayId, 'invalid_space', `spaces[${index}].displayId`)
86
+ if (!displayIds.has(displayId)) throw fail('unknown_display', `spaces[${index}].displayId "${displayId}" is not in displays`)
87
+ const spaceIndex = value.index === undefined ? 0 : value.index
88
+ if (!Number.isInteger(spaceIndex) || spaceIndex < 0) throw fail('invalid_space', `spaces[${index}].index must be a non-negative integer`)
89
+ const current = value.current === undefined ? false : value.current
90
+ if (typeof current !== 'boolean') throw fail('invalid_space', `spaces[${index}].current must be a boolean`)
91
+ return { id, displayId, index: spaceIndex, current }
92
+ }
93
+
94
+ function normalizeZones(value) {
95
+ if (!Array.isArray(value) || value.length === 0) throw fail('invalid_zone', 'zones must be a non-empty array')
96
+ if (value.length > MAX_ZONES) throw fail('invalid_zone', `zones must contain at most ${MAX_ZONES} entries`)
97
+ return value.map((zone, index) => {
98
+ if (!isObject(zone)) throw fail('invalid_zone', `zones[${index}] must be an object`)
99
+ for (const key of RECT_KEYS) {
100
+ const number = zone[key]
101
+ if (typeof number !== 'number' || !Number.isFinite(number) || number < 0 || number > 1) {
102
+ throw fail('invalid_zone', `zones[${index}].${key} must be a finite number within 0..1`)
103
+ }
104
+ }
105
+ if (zone.w === 0 || zone.h === 0) throw fail('invalid_zone', `zones[${index}].w and .h must be positive`)
106
+ if (zone.x + zone.w > 1 + EPSILON || zone.y + zone.h > 1 + EPSILON) {
107
+ throw fail('invalid_zone', `zones[${index}] must fit inside 0..1`)
108
+ }
109
+ return { x: zone.x, y: zone.y, w: zone.w, h: zone.h }
110
+ })
111
+ }
112
+
113
+ const hashTopology = (displays, windows, spaces) => createHash('sha256')
114
+ .update(JSON.stringify({ displays, windows, spaces })).digest('hex').slice(0, 16)
115
+
116
+ const placeZone = (zone, area) => ({
117
+ x: round(area.x + zone.x * area.w), y: round(area.y + zone.y * area.h),
118
+ w: round(zone.w * area.w), h: round(zone.h * area.h),
119
+ })
120
+
121
+ /** Host seam exposed as `ctx.stage`. */
122
+ export class StageService {
123
+ constructor() {
124
+ this._topology = null
125
+ this._layouts = new Map()
126
+ this._history = []
127
+ this._sequence = 0
128
+ }
129
+
130
+ _record(entry) {
131
+ const record = { id: `h${++this._sequence}`, at: now(), ...entry }
132
+ this._history.push(record)
133
+ if (this._history.length > MAX_HISTORY) this._history.splice(0, this._history.length - MAX_HISTORY)
134
+ return record
135
+ }
136
+
137
+ /**
138
+ * Validate and replace the observed topology snapshot. Displays need `id`,
139
+ * `bounds` and a positive `dpi`; windows need `id`, a known `displayId`,
140
+ * `bounds` and an optional boolean `focused`. Spaces are best-effort.
141
+ */
142
+ setTopology(input) {
143
+ if (!isObject(input)) throw fail('invalid_topology', 'topology must be an object')
144
+ const displayIds = new Set()
145
+ const displays = arrayOf(input.displays, 'displays').map((value, index) => {
146
+ const display = normalizeDisplay(value, index)
147
+ unique(displayIds, display.id, 'duplicate_display', 'display id')
148
+ return display
149
+ })
150
+ const windowIds = new Set()
151
+ let focused = 0
152
+ const windows = arrayOf(input.windows, 'windows').map((value, index) => {
153
+ const window = normalizeWindow(value, index, displayIds)
154
+ unique(windowIds, window.id, 'duplicate_window', 'window id')
155
+ if (window.focused) focused += 1
156
+ return window
157
+ })
158
+ if (focused > 1) throw fail('duplicate_focus', 'at most one window may be focused')
159
+ const spaceIds = new Set()
160
+ const spaces = arrayOf(input.spaces, 'spaces').map((value, index) => {
161
+ const space = normalizeSpace(value, index, displayIds)
162
+ unique(spaceIds, space.id, 'duplicate_space', 'space id')
163
+ return space
164
+ })
165
+ const snapshot = {
166
+ schema: SCHEMAS.topology, displays, windows, spaces,
167
+ topologyHash: hashTopology(displays, windows, spaces), observedAt: now(),
168
+ }
169
+ this._topology = snapshot
170
+ this._record({
171
+ type: 'topology', displays: displays.length, windows: windows.length,
172
+ spaces: spaces.length, topologyHash: snapshot.topologyHash,
173
+ })
174
+ return clone(snapshot)
175
+ }
176
+
177
+ /** Read the latest snapshot; an unobserved topology is empty with null hash. */
178
+ topology() {
179
+ return this._topology === null
180
+ ? { schema: SCHEMAS.topology, displays: [], windows: [], spaces: [], topologyHash: null, observedAt: null }
181
+ : clone(this._topology)
182
+ }
183
+
184
+ /** Create or replace a named layout definition. Does not touch topology. */
185
+ setLayout(name, spec) {
186
+ const layoutName = text(name, 'invalid_layout', 'layout name')
187
+ if (!isObject(spec)) throw fail('invalid_layout', 'layout spec must be an object')
188
+ const displayId = text(spec.displayId, 'invalid_layout', 'layout displayId')
189
+ const layout = { name: layoutName, displayId, zones: normalizeZones(spec.zones) }
190
+ this._layouts.set(layoutName, layout)
191
+ this._record({ type: 'layout', name: layoutName, displayId, zones: layout.zones.length })
192
+ return clone(layout)
193
+ }
194
+
195
+ /** All layouts, sorted by name. */
196
+ layouts() {
197
+ return [...this._layouts.values()]
198
+ .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
199
+ .map(item => clone(item))
200
+ }
201
+
202
+ /**
203
+ * Compute and record the intent to place windows of the layout's display.
204
+ * The focused window comes first, then windows in observation order; zones
205
+ * are consumed in listed order. No native API is called.
206
+ */
207
+ applyLayout(name) {
208
+ const layoutName = text(name, 'invalid_layout', 'layout name')
209
+ if (this._topology === null) throw fail('no_topology', 'setTopology() must be called before applyLayout()')
210
+ const layout = this._layouts.get(layoutName)
211
+ if (layout === undefined) throw fail('unknown_layout', `layout "${layoutName}" is not registered`)
212
+ const display = this._topology.displays.find(item => item.id === layout.displayId)
213
+ if (display === undefined) throw fail('unknown_display', `layout display "${layout.displayId}" is not in the current topology`)
214
+ const windows = this._topology.windows
215
+ .map((window, index) => ({ window, index }))
216
+ .filter(item => item.window.displayId === display.id)
217
+ .sort((a, b) => Number(b.window.focused) - Number(a.window.focused) || a.index - b.index)
218
+ .map(item => item.window)
219
+ const assignments = layout.zones.slice(0, windows.length).map((zone, index) => ({
220
+ windowId: windows[index].id, displayId: display.id, zone: index, rect: placeZone(zone, display.workArea),
221
+ }))
222
+ this._record({
223
+ type: 'apply', name: layout.name, displayId: display.id, layout: clone(layout),
224
+ assignments: clone(assignments), topologyHash: this._topology.topologyHash, undone: false,
225
+ })
226
+ return { layout: clone(layout), assignments: clone(assignments) }
227
+ }
228
+
229
+ /** Newest-first history entries, capped by `limit` (default 20, max 200). */
230
+ history(limit = DEFAULT_HISTORY) {
231
+ if (!Number.isInteger(limit) || limit < 1 || limit > MAX_HISTORY) {
232
+ throw fail('invalid_limit', `history limit must be an integer from 1 to ${MAX_HISTORY}`)
233
+ }
234
+ return clone(this._history.slice(-limit).reverse())
235
+ }
236
+
237
+ /** Mark the latest not-yet-undone apply as undone and return its receipt. */
238
+ undo() {
239
+ const entry = [...this._history].reverse().find(item => item.type === 'apply' && item.undone !== true)
240
+ if (entry === undefined) throw fail('nothing_to_undo', 'no applied layout is available to undo')
241
+ entry.undone = true
242
+ entry.undoneAt = now()
243
+ this._record({ type: 'undo', applyId: entry.id, name: entry.name, displayId: entry.displayId })
244
+ return {
245
+ schema: SCHEMAS.undo,
246
+ undone: { id: entry.id, at: entry.at, layout: clone(entry.layout), assignments: clone(entry.assignments) },
247
+ }
248
+ }
249
+ }
250
+
251
+ const TOOL_OUTPUT = {
252
+ schema: { type: 'object', additionalProperties: true },
253
+ render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
254
+ }
255
+
256
+ const objectSchema = (properties, required) => ({
257
+ type: 'object', additionalProperties: false, properties,
258
+ ...(required === undefined ? {} : { required }),
259
+ })
260
+
261
+ const ZONE_SCHEMA = {
262
+ type: 'object', additionalProperties: false,
263
+ properties: Object.fromEntries(RECT_KEYS.map(key => [key, { type: 'number', minimum: 0, maximum: 1 }])),
264
+ required: RECT_KEYS,
265
+ }
266
+
267
+ const tool = (name, description, parameters, execute) => ({
268
+ name, description, parameters, output: TOOL_OUTPUT,
269
+ async execute(args) {
270
+ return execute(args ?? {})
271
+ },
272
+ })
273
+
274
+ /** Plain-object ToolDefinitions; no `@deepseek-ai/dsh-tools` dependency. */
275
+ export function createTools(service) {
276
+ return [
277
+ tool(
278
+ 'stage_topology',
279
+ 'Read the current display/window/space topology snapshot. Topology is supplied '
280
+ + 'by a platform adapter; 0.1.0 ships no native adapter.',
281
+ objectSchema({}),
282
+ () => service.topology(),
283
+ ),
284
+ tool(
285
+ 'stage_layout_set',
286
+ 'Create or replace a named layout of display-relative 0..1 zones. '
287
+ + 'Records a definition only; it does not move windows.',
288
+ objectSchema({
289
+ name: { type: 'string', description: 'Layout name, e.g. "left-right".' },
290
+ displayId: { type: 'string', description: 'Target display id from stage_topology.' },
291
+ zones: {
292
+ type: 'array',
293
+ items: ZONE_SCHEMA,
294
+ minItems: 1,
295
+ maxItems: MAX_ZONES,
296
+ description: 'Normalized zones in application order.',
297
+ },
298
+ }, ['name', 'displayId', 'zones']),
299
+ args => ({
300
+ layout: service.setLayout(args?.name, {
301
+ displayId: args?.displayId,
302
+ zones: args?.zones,
303
+ }),
304
+ }),
305
+ ),
306
+ tool(
307
+ 'stage_layout_apply',
308
+ 'Record a layout application: pair windows on the target display (focused '
309
+ + 'first) with zones, append it to history and return { layout, assignments }. '
310
+ + 'No native window API is called.',
311
+ objectSchema({ name: { type: 'string' } }, ['name']),
312
+ args => service.applyLayout(args?.name),
313
+ ),
314
+ tool(
315
+ 'stage_layout_list',
316
+ 'List every registered layout, sorted by name.',
317
+ objectSchema({}),
318
+ () => ({ layouts: service.layouts() }),
319
+ ),
320
+ tool(
321
+ 'stage_undo',
322
+ 'Undo the most recent applied layout in the Stage ledger. Reverses recorded '
323
+ + 'intent only; native window restore is an adapter concern.',
324
+ objectSchema({}),
325
+ () => service.undo(),
326
+ ),
327
+ ]
328
+ }
329
+
330
+ /** Mount dsh-stage: provide `ctx.stage` and the five `stage_*` tools. */
331
+ export function apply(ctx, _config = {}) {
332
+ const stage = new StageService()
333
+ ctx.provide('stage', stage)
334
+ if (ctx.tools && typeof ctx.tools.register === 'function') {
335
+ for (const item of createTools(stage)) ctx.tools.register(item)
336
+ }
337
+ return stage
338
+ }
package/package.json CHANGED
@@ -1,6 +1,51 @@
1
1
  {
2
2
  "name": "dsh-stage",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "Display, window and space topology protocol for DeepSeek Harness agents, with normalized, reversible layouts.",
5
+ "type": "module",
6
+ "main": "index.js",
7
+ "exports": {
8
+ ".": "./index.js",
9
+ "./package.json": "./package.json"
10
+ },
11
+ "files": [
12
+ "index.js",
13
+ "cordis.patch.yml",
14
+ "README.md",
15
+ "CHANGELOG.md"
16
+ ],
17
+ "keywords": [
18
+ "dsh",
19
+ "dsh-plugin",
20
+ "deepseek-harness",
21
+ "agent-os",
22
+ "stage"
23
+ ],
24
+ "license": "MIT",
25
+ "author": "PerryLink contributors",
26
+ "repository": {
27
+ "type": "git",
28
+ "url": "git+https://github.com/PerryLink/dsh-os.git",
29
+ "directory": "packages/stage"
30
+ },
31
+ "homepage": "https://github.com/PerryLink/dsh-os/tree/main/packages/stage#readme",
32
+ "bugs": {
33
+ "url": "https://github.com/PerryLink/dsh-os/issues"
34
+ },
35
+ "engines": {
36
+ "node": "^22.19.0 || >=24.9.0",
37
+ "dsh": ">=0.2.1-rc.2 <0.3.0 || >=0.2.2-0 <0.3.0"
38
+ },
39
+ "dsh": {
40
+ "manifestVersion": 1,
41
+ "bundle": {
42
+ "patch": "./cordis.patch.yml"
43
+ }
44
+ },
45
+ "scripts": {
46
+ "test": "node --test"
47
+ },
48
+ "publishConfig": {
49
+ "access": "public"
50
+ }
51
+ }