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 +22 -0
- package/LICENSE +21 -0
- package/README.md +198 -2
- package/cordis.patch.yml +4 -0
- package/index.js +338 -0
- package/package.json +49 -4
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
|
-
#
|
|
1
|
+
# Stage · `dsh-stage`
|
|
2
2
|
|
|
3
|
-
|
|
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.
|
package/cordis.patch.yml
ADDED
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.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
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
|
+
}
|