dsh-act 0.0.1 → 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 CHANGED
@@ -1,5 +1,22 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.0
4
+
5
+ - Add `ActService` (`register` / `unregister` / `get` / `list` / `invoke`) exposed
6
+ as the Host service `ctx.act`.
7
+ - Validate action ids (`^[a-z][a-z0-9_.-]{1,63}$`), risk and `execute`, and reject
8
+ duplicate ids.
9
+ - Gate `write` and `danger` actions through the optional Allow service
10
+ (`check({ subject, capability: 'act:invoke:<id>', scope })`); return
11
+ `grant_required` instead of throwing when the service is absent or denies.
12
+ - Return `{ ok: true, actionId, result }` on success and `{ ok: false,
13
+ code: 'action_failed', message }` when `execute` throws.
14
+ - Add built-in `echo`, `now` and `list` read actions.
15
+ - Register the `act_list` and `act_invoke` agent tools using plain tool
16
+ definitions (no `@deepseek-ai/dsh-tools` dependency).
17
+ - Add `node --test` coverage for registration, filtering, invocation, denial,
18
+ authorized writes, execution failures and duplicate ids.
19
+
3
20
  ## 0.0.1
4
21
 
5
22
  - Reserve the `dsh-act` package name.
package/README.md CHANGED
@@ -1,9 +1,16 @@
1
1
  # Act · `dsh-act`
2
2
 
3
- > Typed action registry and natural-language action panel for DeepSeek Harness.
3
+ > Typed action registry and agent-facing action bus for DeepSeek Harness.
4
4
 
5
- **Status: 0.0.1 name reservation.** The working design lives in the
6
- [dsh-os design notes](https://github.com/PerryLink/dsh-os#readme). A functional MVP is planned for 0.1.0.
5
+ **Status: 0.1.0 MVP:服务/tools;UI/CLI 下一版**
6
+
7
+ 0.1.0 ships the Host service `ctx.act` and the `act_list` / `act_invoke` agent
8
+ tools. The action panel, natural-language router, preview/undo/audit pipeline
9
+ and the `dsh-act` CLI are planned for the next release.
10
+
11
+ Act is an **action bus**, not a repository task runner such as `dsh-actions`:
12
+ plugins register typed `ActionDescriptor`s once, and humans, agents and future
13
+ front-ends invoke the same actions through one registry and one grant check.
7
14
 
8
15
  **Not affiliated with DeepSeek.** DeepSeek and DeepSeek Harness are trademarks
9
16
  of their respective owners.
@@ -14,8 +21,85 @@ of their respective owners.
14
21
  dsh plugin --profile web add dsh-act
15
22
  ```
16
23
 
17
- ## Design
24
+ Plain ESM, Node.js 22+, no runtime dependencies and no build step.
25
+
26
+ ## Service
27
+
28
+ The plugin exposes `ctx.act`:
29
+
30
+ ```js
31
+ const act = ctx.get('act')
32
+
33
+ const dispose = act.register({
34
+ id: 'workspace.open', // ^[a-z][a-z0-9_.-]{1,63}$
35
+ title: 'Open workspace file',
36
+ description: 'Open one file in the editor.',
37
+ risk: 'write', // read | write | danger
38
+ parameters: { type: 'object', additionalProperties: true },
39
+ async execute(args, meta) {
40
+ return { opened: args.path, session: meta?.sessionId }
41
+ },
42
+ })
43
+
44
+ act.get('workspace.open') // descriptor | undefined
45
+ act.list('open') // substring filter over id/title/description
46
+ act.list({ text: 'open', riskMax: 'write' })
47
+ await act.invoke('echo', { text: 'hi' }, { subject: 'session-42' })
48
+ dispose()
49
+ ```
50
+
51
+ `register()` validates the id, title, risk and `execute`; duplicate ids throw
52
+ `action_exists`. Results are structured and never throw for expected failures:
53
+
54
+ | Outcome | Value |
55
+ | --- | --- |
56
+ | Success | `{ ok: true, actionId, result }` |
57
+ | Unknown id | `{ ok: false, code: 'action_not_found', actionId }` |
58
+ | Missing grant | `{ ok: false, code: 'grant_required', actionId, capability }` |
59
+ | `execute` threw | `{ ok: false, code: 'action_failed', message }` |
60
+
61
+ ## Grant checks
62
+
63
+ `read` actions run directly. `write` and `danger` actions first call the
64
+ optional Allow service:
65
+
66
+ ```js
67
+ const allow = ctx.get('allow')
68
+ const decision = await allow.check({
69
+ subject: meta?.subject ?? meta?.sessionId ?? 'anonymous',
70
+ capability: `act:invoke:${id}`,
71
+ scope: meta?.scope,
72
+ })
73
+ ```
74
+
75
+ If Allow is absent, the check throws, or the decision is not affirmative,
76
+ `invoke()` returns `grant_required` and does **not** execute the action
77
+ (fail-closed). Affirmative decisions are `true`, `'allow'`, or an object with
78
+ `granted`/`allowed`/`allow`/`permitted === true`, `decision`/`status === 'allow'`,
79
+ or `ok === true`.
80
+
81
+ ## Built-in actions
82
+
83
+ | id | risk | result |
84
+ | --- | --- | --- |
85
+ | `echo` | read | `{ text }` — echoes `args.text` |
86
+ | `now` | read | `{ now }` — ISO 8601 timestamp |
87
+ | `list` | read | `{ actions }` — action summaries (`id`, `title`, `risk`, `description?`) |
88
+
89
+ ## Agent tools
90
+
91
+ - `act_list` — read-only; optional `query` string; returns `{ actions }`.
92
+ - `act_invoke` — `id` required, `args` optional object. The effective risk is the
93
+ target descriptor's risk; `write`/`danger` actions still go through the Allow
94
+ check above. The plugin injects the `tools` service for both tools.
95
+
96
+ ## Test
97
+
98
+ ```sh
99
+ cd packages/act
100
+ node --test
101
+ ```
102
+
103
+ ## License
18
104
 
19
- - Host seam: `ctx.act` (planned)
20
- - Agent tools and CLI are declared in the package's design doc.
21
- - License: MIT.
105
+ MIT.
package/index.js CHANGED
@@ -1,13 +1,288 @@
1
1
  /**
2
- * dsh-act — Typed action registry and natural-language action panel for DeepSeek Harness.
2
+ * dsh-act — typed action registry and agent-facing action bus for DeepSeek Harness.
3
3
  *
4
- * 0.0.1 placeholder: the bundle loads and provides a stable package name.
5
- * The functional implementation lands in 0.1.0.
4
+ * 0.1.0 MVP: Host service `ctx.act` with descriptor validation, optional Allow
5
+ * grant checks for write/danger actions, three read-only built-ins and the
6
+ * `act_list` / `act_invoke` agent tools. Plain ESM, no runtime dependencies.
6
7
  * @module dsh-act
7
8
  */
8
9
 
9
10
  /** Cordis plugin name. */
10
11
  export const name = 'dsh-act'
11
12
 
12
- /** Mount the plugin. The 0.0.1 placeholder intentionally has no side effects. */
13
- export function apply() {}
13
+ /** The service is usable without tools; the agent tools need the tool registry. */
14
+ export const inject = ['tools']
15
+
16
+ const ID_PATTERN = /^[a-z][a-z0-9_.-]{1,63}$/
17
+ const RISKS = ['read', 'write', 'danger']
18
+ const RISK_RANK = { read: 0, write: 1, danger: 2 }
19
+
20
+ function invalid(actionId, message) {
21
+ return Object.assign(new Error(message), { code: 'invalid_action', actionId })
22
+ }
23
+
24
+ /** Validate the descriptor fields this MVP relies on. */
25
+ function validate(descriptor) {
26
+ if (descriptor === null || typeof descriptor !== 'object' || Array.isArray(descriptor)) {
27
+ throw invalid(undefined, 'action descriptor must be an object')
28
+ }
29
+ if (typeof descriptor.id !== 'string' || !ID_PATTERN.test(descriptor.id)) {
30
+ throw invalid(descriptor.id, `invalid action id: ${String(descriptor.id)}`)
31
+ }
32
+ if (typeof descriptor.title !== 'string' || descriptor.title.trim() === '') {
33
+ throw invalid(descriptor.id, `action "${descriptor.id}" requires a non-empty title`)
34
+ }
35
+ if (!RISKS.includes(descriptor.risk)) {
36
+ throw invalid(descriptor.id, `action "${descriptor.id}" requires risk read, write or danger`)
37
+ }
38
+ if (typeof descriptor.execute !== 'function') {
39
+ throw invalid(descriptor.id, `action "${descriptor.id}" requires an execute function`)
40
+ }
41
+ if (descriptor.description !== undefined && typeof descriptor.description !== 'string') {
42
+ throw invalid(descriptor.id, `action "${descriptor.id}" description must be a string`)
43
+ }
44
+ if (descriptor.parameters !== undefined
45
+ && (descriptor.parameters === null || typeof descriptor.parameters !== 'object'
46
+ || Array.isArray(descriptor.parameters))) {
47
+ throw invalid(descriptor.id, `action "${descriptor.id}" parameters must be a JSON Schema object`)
48
+ }
49
+ if (descriptor.undo !== undefined && typeof descriptor.undo !== 'function') {
50
+ throw invalid(descriptor.id, `action "${descriptor.id}" undo must be a function`)
51
+ }
52
+ }
53
+
54
+ function matches(action, text) {
55
+ const haystack = [action.id, action.title, action.description ?? '']
56
+ return haystack.some(field => field.toLowerCase().includes(text))
57
+ }
58
+
59
+ /** Lossless-JSON view of a descriptor (functions are omitted). */
60
+ export function summarize(action) {
61
+ const summary = { id: action.id, title: action.title, risk: action.risk }
62
+ if (action.description !== undefined) summary.description = action.description
63
+ return summary
64
+ }
65
+
66
+ /** The built-in read-only actions. */
67
+ function builtins(service) {
68
+ return [
69
+ {
70
+ id: 'echo',
71
+ title: 'Echo',
72
+ description: 'Echo the supplied text.',
73
+ risk: 'read',
74
+ parameters: {
75
+ type: 'object',
76
+ additionalProperties: false,
77
+ properties: { text: { type: 'string', description: 'Text to echo.' } },
78
+ required: ['text'],
79
+ },
80
+ execute(args) {
81
+ return { text: typeof args?.text === 'string' ? args.text : '' }
82
+ },
83
+ },
84
+ {
85
+ id: 'now',
86
+ title: 'Current time',
87
+ description: 'Return the current time as an ISO 8601 string.',
88
+ risk: 'read',
89
+ parameters: { type: 'object', additionalProperties: false, properties: {} },
90
+ execute() {
91
+ return { now: new Date().toISOString() }
92
+ },
93
+ },
94
+ {
95
+ id: 'list',
96
+ title: 'List actions',
97
+ description: 'List registered actions.',
98
+ risk: 'read',
99
+ parameters: {
100
+ type: 'object',
101
+ additionalProperties: false,
102
+ properties: { query: { type: 'string', description: 'Optional text filter.' } },
103
+ },
104
+ execute(args) {
105
+ return { actions: service.list(args?.query).map(summarize) }
106
+ },
107
+ },
108
+ ]
109
+ }
110
+
111
+ /** Recipient-side view of an Allow `check()` decision. Fail closed. */
112
+ function granted(decision) {
113
+ if (decision === true || decision === 'allow') return true
114
+ if (decision === null || typeof decision !== 'object') return false
115
+ return decision.granted === true
116
+ || decision.allowed === true
117
+ || decision.allow === true
118
+ || decision.permitted === true
119
+ || decision.decision === 'allow'
120
+ || decision.status === 'allow'
121
+ || decision.ok === true
122
+ }
123
+
124
+ /** Typed action registry exposed to other plugins as `ctx.act`. */
125
+ export class ActService {
126
+ #actions = new Map()
127
+ #ctx
128
+
129
+ constructor(ctx) {
130
+ this.#ctx = ctx
131
+ }
132
+
133
+ /**
134
+ * Register an action descriptor. Returns a disposer that unregisters it.
135
+ * @throws {Error} `invalid_action` or `action_exists`.
136
+ */
137
+ register(descriptor) {
138
+ validate(descriptor)
139
+ if (this.#actions.has(descriptor.id)) {
140
+ throw Object.assign(new Error(`action "${descriptor.id}" is already registered`), {
141
+ code: 'action_exists',
142
+ actionId: descriptor.id,
143
+ })
144
+ }
145
+ const action = Object.freeze({ ...descriptor })
146
+ this.#actions.set(action.id, action)
147
+ return () => (this.#actions.get(action.id) === action ? this.#actions.delete(action.id) : false)
148
+ }
149
+
150
+ /** Remove an action; returns whether it was registered. */
151
+ unregister(id) {
152
+ return this.#actions.delete(id)
153
+ }
154
+
155
+ /** Look up one action descriptor. */
156
+ get(id) {
157
+ return this.#actions.get(id)
158
+ }
159
+
160
+ /**
161
+ * List actions, optionally filtered by a text substring (string query) or
162
+ * `{ text, riskMax }`. Insertion order is preserved.
163
+ */
164
+ list(query) {
165
+ let actions = [...this.#actions.values()]
166
+ if (typeof query === 'string') {
167
+ const text = query.trim().toLowerCase()
168
+ return text === '' ? actions : actions.filter(action => matches(action, text))
169
+ }
170
+ if (query === null || typeof query !== 'object') return actions
171
+ if (typeof query.text === 'string' && query.text.trim() !== '') {
172
+ const text = query.text.trim().toLowerCase()
173
+ actions = actions.filter(action => matches(action, text))
174
+ }
175
+ if (query.riskMax !== undefined) {
176
+ const max = RISK_RANK[query.riskMax]
177
+ if (max === undefined) throw invalid(undefined, `invalid riskMax: ${String(query.riskMax)}`)
178
+ actions = actions.filter(action => RISK_RANK[action.risk] <= max)
179
+ }
180
+ return actions
181
+ }
182
+
183
+ /**
184
+ * Invoke an action. `read` runs directly; `write`/`danger` require an
185
+ * explicit Allow grant. Never throws for action, grant or execution failure.
186
+ */
187
+ async invoke(id, args, meta) {
188
+ const action = this.#actions.get(id)
189
+ if (action === undefined) return { ok: false, code: 'action_not_found', actionId: id }
190
+
191
+ const capability = `act:invoke:${action.id}`
192
+ if (action.risk !== 'read' && !(await this.#authorized(capability, meta))) {
193
+ return { ok: false, code: 'grant_required', actionId: action.id, capability }
194
+ }
195
+
196
+ try {
197
+ return { ok: true, actionId: action.id, result: await action.execute(args, meta) }
198
+ } catch (error) {
199
+ return {
200
+ ok: false,
201
+ code: 'action_failed',
202
+ message: error instanceof Error ? error.message : String(error),
203
+ }
204
+ }
205
+ }
206
+
207
+ async #authorized(capability, meta) {
208
+ const allow = typeof this.#ctx?.get === 'function' ? this.#ctx.get('allow') : undefined
209
+ if (allow === undefined || allow === null || typeof allow.check !== 'function') return false
210
+ const subject = meta?.subject ?? meta?.sessionId ?? 'anonymous'
211
+ try {
212
+ return granted(await allow.check({ subject, capability, scope: meta?.scope }))
213
+ } catch {
214
+ return false
215
+ }
216
+ }
217
+ }
218
+
219
+ /** `act_list` tool: read-only action discovery. */
220
+ function listTool(service) {
221
+ return {
222
+ name: 'act_list',
223
+ description: 'List registered Act actions with their id, title and risk.',
224
+ parameters: {
225
+ type: 'object',
226
+ additionalProperties: false,
227
+ properties: { query: { type: 'string', description: 'Optional id/title/description filter.' } },
228
+ },
229
+ output: {
230
+ schema: { type: 'object', additionalProperties: true },
231
+ render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
232
+ },
233
+ async execute(args) {
234
+ return { actions: service.list(args?.query).map(summarize) }
235
+ },
236
+ }
237
+ }
238
+
239
+ /**
240
+ * `act_invoke` tool. It has no static risk of its own: ActService.invoke applies
241
+ * the target descriptor's risk, so write/danger actions still need a grant.
242
+ */
243
+ function invokeTool(service) {
244
+ return {
245
+ name: 'act_invoke',
246
+ description: 'Invoke a registered Act action by id. '
247
+ + 'write and danger actions return grant_required until the Allow service grants '
248
+ + 'capability "act:invoke:<id>" for the caller.',
249
+ parameters: {
250
+ type: 'object',
251
+ additionalProperties: false,
252
+ properties: {
253
+ id: { type: 'string', description: 'Registered action id, e.g. "echo".' },
254
+ args: { type: 'object', additionalProperties: true, description: 'Action arguments.' },
255
+ },
256
+ required: ['id'],
257
+ },
258
+ output: {
259
+ schema: { type: 'object', additionalProperties: true },
260
+ render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
261
+ },
262
+ async execute(args, exec) {
263
+ if (typeof args?.id !== 'string' || args.id === '') {
264
+ throw Object.assign(new Error('act_invoke requires a non-empty string id'), {
265
+ code: 'invalid_arguments',
266
+ })
267
+ }
268
+ const meta = { origin: 'tool' }
269
+ const subject = exec?.agent?.session?.id ?? exec?.agent?.id
270
+ if (subject !== undefined) meta.subject = subject
271
+ return service.invoke(args.id, args.args, meta)
272
+ },
273
+ }
274
+ }
275
+
276
+ /**
277
+ * Mount dsh-act: provide `ctx.act`, register built-ins and the two agent tools.
278
+ * @param {object} ctx - Cordis context.
279
+ * @param {object} [_config] - Reserved for 0.2.0; unused by the MVP.
280
+ */
281
+ export function apply(ctx, _config = {}) {
282
+ const service = new ActService(ctx)
283
+ for (const descriptor of builtins(service)) service.register(descriptor)
284
+ ctx.provide('act', service)
285
+ ctx.tools.register(listTool(service))
286
+ ctx.tools.register(invokeTool(service))
287
+ return service
288
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-act",
3
- "version": "0.0.1",
3
+ "version": "0.1.0",
4
4
  "description": "Typed action registry and natural-language action panel for DeepSeek Harness.",
5
5
  "type": "module",
6
6
  "main": "index.js",
@@ -44,5 +44,8 @@
44
44
  },
45
45
  "publishConfig": {
46
46
  "access": "public"
47
+ },
48
+ "scripts": {
49
+ "test": "node --test"
47
50
  }
48
51
  }