dsh-ring 0.0.1 → 0.1.1

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.
Files changed (4) hide show
  1. package/CHANGELOG.md +31 -0
  2. package/README.md +109 -7
  3. package/index.js +342 -7
  4. package/package.json +26 -3
package/CHANGELOG.md CHANGED
@@ -1,5 +1,36 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.1
4
+
5
+ - Make `expired` terminal for direct decisions: `ack()` and `resolve()` on an
6
+ expired case now throw `E_STATE` instead of moving it back to an active state.
7
+ The only in-place way to reopen a case is an explicit `escalate(id, { to })`
8
+ late page; otherwise raise a new case. A case decided after it expired is
9
+ still marked `late`.
10
+ - Keep `tick()` from ever re-escalating a `resolved` case (already enforced;
11
+ now covered by a regression test), and never revive a closed case.
12
+ - Make receipts immutable evidence: stored entries are frozen, append-only and
13
+ never rewritten; every read and every `tick()` result returns defensive
14
+ copies, so mutating a returned receipt cannot change the ledger.
15
+ - Add state-machine tests for expired ack/resolve refusal, late pages, and
16
+ resolved-case ticks.
17
+
18
+ ## 0.1.0
19
+
20
+ - Add `RingService` at `ctx.ring`: `raise`, `tick`, `ack`, `escalate`, `resolve`,
21
+ `get`, `list` and `receipts`.
22
+ - Add the SLA state machine: `pending -> notified -> acked -> resolved`, with
23
+ `escalated` and `expired` branches. Illegal transitions throw `E_STATE`.
24
+ - Add the deterministic SLA clock (`tick(now)`): t0 0s, t1 3m, t2 10m, t3 30m,
25
+ and a 60-minute default case TTL. Missed steps collapse into one catch-up
26
+ escalation per case per tick.
27
+ - Record delivery, escalation, ack, decision and expiry receipts locally. No
28
+ notification, IM or voice channel is contacted in this release; those land in
29
+ 0.2.0.
30
+ - Add plain tool definitions `ring_raise`, `ring_ack`, `ring_escalate`,
31
+ `ring_list` and `ring_receipts`.
32
+ - Ack is explicitly not approval: v0 never approves remotely.
33
+
3
34
  ## 0.0.1
4
35
 
5
36
  - Reserve the `dsh-ring` package name.
package/README.md CHANGED
@@ -1,9 +1,17 @@
1
1
  # Ring · `dsh-ring`
2
2
 
3
- > Approval SLA and escalation receipts for DeepSeek Harness: ack, escalate, audit.
3
+ > **Approval SLA, not a notification app.** Raise a blocking approval, page on a
4
+ > fixed t0–t3 schedule, stop on ack, record every step as a local receipt.
4
5
 
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.
6
+ **Status: 0.1.1 — SLA state machine MVP.** Cases advance only through explicit
7
+ `tick(now)` calls, and every delivery is recorded locally. **No notification is
8
+ actually sent.** IM (webhook) and voice channels are planned for **0.2.0**.
9
+ **v0 only acknowledges; it never approves remotely** — ack is not approval, and
10
+ the final decision still comes from the Web/host approval seam.
11
+
12
+ This is the approval-paging package, not the unrelated zero-star `dsh-ring`
13
+ sound-effect plugin that may occupy the same npm name. A `@perrylink/dsh-ring`
14
+ mirror is planned.
7
15
 
8
16
  **Not affiliated with DeepSeek.** DeepSeek and DeepSeek Harness are trademarks
9
17
  of their respective owners.
@@ -12,10 +20,104 @@ of their respective owners.
12
20
 
13
21
  ```sh
14
22
  dsh plugin --profile web add dsh-ring
23
+ # or
24
+ npm install dsh-ring
25
+ ```
26
+
27
+ Requires Node 22.19+ (or Node 24.9+). No runtime dependencies.
28
+
29
+ ## Service
30
+
31
+ The bundle provides `ctx.ring`:
32
+
33
+ ```js
34
+ const kase = ctx.ring.raise({ source: 'approval', risk: 'write' })
35
+ ctx.ring.tick(Date.now()) // t0: pending -> notified
36
+ ctx.ring.ack(kase.id, { by: 'alice@example.com' }) // ack, not approve
37
+ ctx.ring.resolve(kase.id, { decision: 'allowed-once' }) // final decision
38
+ const receipts = ctx.ring.receipts(kase.id)
39
+ ```
40
+
41
+ | Method | Purpose |
42
+ |---|---|
43
+ | `raise({ source, risk = 'write', ttlMs?, escalationChain? })` | Create a `pending` case. `source` is free-form (`approval`, `job`, `hook`, `act`, `manual`, …). `ttlMs` defaults to 60 minutes. |
44
+ | `tick(now?)` | Advance every open case to `now`. Returns `{ now, receipts, cases }`; at most one catch-up escalation per case per call. |
45
+ | `ack(id, { by })` | Claim the case (`acked`), stop escalation, keep a receipt. |
46
+ | `escalate(id, { to? })` | Move to `escalated` at a chain level (`1`, `"t2"`) or record a free-form target label. Omit `to` to advance one level. |
47
+ | `resolve(id, { decision })` | Record the human outcome (`resolved`). An expired case must be re-paged first; a decision recorded after expiry is marked `late`. |
48
+ | `list({ status? })` | Case snapshots, optionally filtered by one status or an array of statuses. |
49
+ | `receipts(id)` | All receipts for a case, in insertion order. |
50
+
51
+ `raise`, `ack`, `escalate` and `resolve` return a defensive copy of the case;
52
+ `get(id)` is also available for a single snapshot.
53
+
54
+ ## SLA and states
55
+
56
+ Default chain: **t0 = 0 s (local), t1 = 3 min (local), t2 = 10 min (webhook),
57
+ t3 = 30 min (voice)**. A case expires after 60 minutes. The chain is a full
58
+ replacement when passed to `raise`; entries may be numbers (`afterMs`) or
59
+ `{ level?, afterMs, channel? }`.
60
+
15
61
  ```
62
+ pending --t0--> notified --ack--> acked --decision--> resolved
63
+ | | |
64
+ +--t1..t3------> escalated ------+ (ack stops further escalation)
65
+ any open state --expiresAt--> expired --escalate(to)--> escalated --decision--> resolved
66
+ ```
67
+
68
+ - `expired` and `resolved` are not touched by later ticks.
69
+ - Acking, escalating or resolving a closed case throws `E_STATE`.
70
+ - Expired is terminal for direct decisions: `ack()` and `resolve()` on an
71
+ expired case throw `E_STATE`. The only in-place way to reopen it is an
72
+ explicit late page — `escalate(id, { to })` — after which a decision is
73
+ accepted (and marked `late`); otherwise raise a new case. `tick` never
74
+ revives an expired case.
75
+ - An acked case is never escalated automatically. A late page is never
76
+ repeated by `tick`; later ticks leave that page open for a decision.
77
+ - Every tick records at most one escalation receipt — the highest due level —
78
+ so jumping straight to t3 emits t0 plus one t3 catch-up instead of a burst.
79
+ - Nothing is sent over a network, spawned, or written to the session log.
80
+
81
+ ## Receipts
82
+
83
+ ```js
84
+ { id, caseId, kind, at, channel?, by?, to? }
85
+ ```
86
+
87
+ `kind` is one of `delivery` (t0), `escalation` (t1–t3), `ack`, `decision` or
88
+ `expiry`. `channel` is the recorded target channel; `by` is the acknowledging
89
+ principal; `to` is the SLA level or explicit escalation target.
90
+
91
+ Receipts are immutable, append-only evidence: stored entries are frozen and
92
+ never rewritten, and every read (and every `tick()` result) returns defensive
93
+ copies, so mutating a returned receipt cannot change the ledger. Receipts prove
94
+ what the ledger recorded, not that a channel delivered anything.
95
+
96
+ ## Agent tools
97
+
98
+ | Tool | Arguments |
99
+ |---|---|
100
+ | `ring_raise` | `source`, optional `risk`, `ttlMs`, `escalationChain` |
101
+ | `ring_ack` | `id`, `by` |
102
+ | `ring_escalate` | `id`, optional `to` |
103
+ | `ring_list` | optional `status` |
104
+ | `ring_receipts` | `id` |
105
+
106
+ Tools are plain `ToolDefinition` objects and return `{ case }`, `{ cases }` or
107
+ `{ receipts }`. There is deliberately no model-facing `ring_resolve`: the model
108
+ can raise, list, page and acknowledge, but only the human/approval seam records
109
+ the decision.
110
+
111
+ ## Errors
112
+
113
+ | Code | Meaning |
114
+ |---|---|
115
+ | `E_STATE` | Illegal state transition (e.g. acking a resolved case, auto-escalating an expired one) |
116
+ | `E_NOT_FOUND` | Unknown case id |
117
+ | `E_INPUT` | Invalid argument, risk, status, timestamp or escalation target |
118
+ | `E_TTL` | Invalid `ttlMs` |
119
+ | `E_CHAIN` | Invalid or duplicate escalation chain |
16
120
 
17
- ## Design
121
+ ## License
18
122
 
19
- - Host seam: `ctx.ring` (planned)
20
- - Agent tools and CLI are declared in the package's design doc.
21
- - License: MIT.
123
+ MIT.
package/index.js CHANGED
@@ -1,13 +1,348 @@
1
1
  /**
2
- * dsh-ring — Approval SLA and escalation receipts for DeepSeek Harness: ack, escalate, audit.
2
+ * dsh-ring — approval SLA and escalation receipts 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.
6
- * @module dsh-ring
4
+ * 0.1.0 MVP: `ctx.ring` is an in-memory approval-case ledger with a deterministic
5
+ * SLA state machine advanced by `tick(now)`. Nothing is delivered: every step
6
+ * writes a local receipt, so the ledger is auditable without channel credentials.
7
+ * Plain ESM, no runtime dependencies. @module dsh-ring
7
8
  */
9
+ import { randomUUID } from 'node:crypto'
8
10
 
9
- /** Cordis plugin name. */
10
11
  export const name = 'dsh-ring'
12
+ export const inject = ['tools']
11
13
 
12
- /** Mount the plugin. The 0.0.1 placeholder intentionally has no side effects. */
13
- export function apply() {}
14
+ /** States; `resolved` and `expired` close a case for tick purposes. */
15
+ export const STATES = ['pending', 'notified', 'escalated', 'acked', 'resolved', 'expired']
16
+ export const RISKS = ['read', 'write', 'exec', 'danger']
17
+ export const DEFAULT_TTL_MS = 60 * 60 * 1000
18
+
19
+ /** Default SLA: t0 0s, t1 3m, t2 10m, t3 30m; case TTL is 60m. */
20
+ export const DEFAULT_ESCALATION_CHAIN = Object.freeze([
21
+ { level: 0, afterMs: 0, channel: 'local' },
22
+ { level: 1, afterMs: 3 * 60 * 1000, channel: 'local' },
23
+ { level: 2, afterMs: 10 * 60 * 1000, channel: 'webhook' },
24
+ { level: 3, afterMs: 30 * 60 * 1000, channel: 'voice' },
25
+ ])
26
+
27
+ const MAX_TEXT = 128
28
+ const CHAIN_DEFAULT_CHANNEL = level => (level >= 3 ? 'voice' : level === 2 ? 'webhook' : 'local')
29
+ const clone = value => structuredClone(value)
30
+ const isObject = value => value !== null && typeof value === 'object' && !Array.isArray(value)
31
+
32
+ function fail(code, message) {
33
+ throw Object.assign(new Error(message), { code })
34
+ }
35
+
36
+ function readText(value, field, code = 'E_INPUT', max = MAX_TEXT) {
37
+ if (typeof value !== 'string' || value.trim() === '') fail(code, `${field} must be a non-empty string`)
38
+ const text = value.trim()
39
+ if (text.length > max) fail(code, `${field} must be at most ${max} characters`)
40
+ return text
41
+ }
42
+
43
+ const readId = value => readText(value, 'id')
44
+
45
+ function readTimestamp(value, label) {
46
+ if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
47
+ fail('E_INPUT', `${label} must be a finite non-negative timestamp`)
48
+ }
49
+ return value
50
+ }
51
+
52
+ function readTtl(value) {
53
+ if (value === undefined || value === null) return DEFAULT_TTL_MS
54
+ if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
55
+ fail('E_TTL', 'ttlMs must be a positive finite number of milliseconds')
56
+ }
57
+ return value
58
+ }
59
+
60
+ /** Accept a full replacement chain: numbers, or `{ level?, afterMs, channel? }`. */
61
+ function normalizeChain(input) {
62
+ if (input === undefined || input === null) return DEFAULT_ESCALATION_CHAIN.map(entry => ({ ...entry }))
63
+ if (!Array.isArray(input) || input.length === 0) fail('E_CHAIN', 'escalationChain must be a non-empty array')
64
+ const entries = input.map((item, index) => {
65
+ let level = index
66
+ let afterMs
67
+ let channel
68
+ if (typeof item === 'number') afterMs = item
69
+ else if (isObject(item)) {
70
+ afterMs = item.afterMs ?? item.after ?? item.at
71
+ if (item.level !== undefined) level = item.level
72
+ channel = item.channel
73
+ } else fail('E_CHAIN', `escalationChain[${index}] must be a number or an object`)
74
+ if (!Number.isInteger(level) || level < 0) fail('E_CHAIN', `escalationChain[${index}].level must be an integer >= 0`)
75
+ if (typeof afterMs !== 'number' || !Number.isFinite(afterMs) || afterMs < 0) {
76
+ fail('E_CHAIN', `escalationChain[${index}].afterMs must be a finite number >= 0`)
77
+ }
78
+ channel = channel === undefined ? CHAIN_DEFAULT_CHANNEL(level) : readText(channel, 'channel', 'E_CHAIN', 64)
79
+ return { level, afterMs, channel }
80
+ })
81
+ if (!entries.some(entry => entry.level === 0)) entries.push({ level: 0, afterMs: 0, channel: 'local' })
82
+ const seen = new Set()
83
+ for (const entry of entries) {
84
+ if (seen.has(entry.level)) fail('E_CHAIN', `duplicate escalation level: ${entry.level}`)
85
+ seen.add(entry.level)
86
+ }
87
+ return entries.sort((a, b) => a.afterMs - b.afterMs || a.level - b.level)
88
+ }
89
+
90
+ /** Host seam `ctx.ring`: an in-memory ledger with a deterministic SLA clock. */
91
+ export class RingService {
92
+ #cases = new Map()
93
+ #receipts = []
94
+
95
+ constructor(ctx, config = {}) {
96
+ this.ctx = ctx
97
+ if (!isObject(config)) fail('E_INPUT', 'config must be an object')
98
+ this.clock = typeof config.now === 'function' ? config.now : () => Date.now()
99
+ readTimestamp(this.clock(), 'config.now()')
100
+ }
101
+
102
+ /** Create a pending case. t0 is delivered by the next `tick` at/after createdAt. */
103
+ raise(input) {
104
+ if (!isObject(input)) fail('E_INPUT', 'raise input must be an object')
105
+ const source = readText(input.source, 'source', 'E_INPUT', 64)
106
+ const risk = input.risk === undefined ? 'write' : input.risk
107
+ if (!RISKS.includes(risk)) fail('E_INPUT', `risk must be one of ${RISKS.join(', ')}`)
108
+ const ttlMs = readTtl(input.ttlMs)
109
+ const escalationChain = normalizeChain(input.escalationChain)
110
+ const at = readTimestamp(this.clock(), 'clock')
111
+ const kase = {
112
+ id: randomUUID(),
113
+ source,
114
+ risk,
115
+ state: 'pending',
116
+ level: 0,
117
+ createdAt: at,
118
+ updatedAt: at,
119
+ expiresAt: at + ttlMs,
120
+ escalationChain,
121
+ }
122
+ this.#cases.set(kase.id, kase)
123
+ return clone(kase)
124
+ }
125
+
126
+ /** Return a case snapshot by id, or `undefined`. */
127
+ get(id) {
128
+ const kase = this.#cases.get(readId(id))
129
+ return kase === undefined ? undefined : clone(kase)
130
+ }
131
+
132
+ /** List case snapshots in creation order, optionally filtered by status/statuses. */
133
+ list(query = {}) {
134
+ if (!isObject(query)) fail('E_INPUT', 'list query must be an object')
135
+ let filter = null
136
+ if (query.status !== undefined) {
137
+ const statuses = Array.isArray(query.status) ? query.status : [query.status]
138
+ filter = new Set()
139
+ for (const status of statuses) {
140
+ if (!STATES.includes(status)) fail('E_INPUT', `status must be one of ${STATES.join(', ')}`)
141
+ filter.add(status)
142
+ }
143
+ }
144
+ return [...this.#cases.values()]
145
+ .filter(kase => filter === null || filter.has(kase.state))
146
+ .map(clone)
147
+ }
148
+
149
+ /** Acknowledge a case: claim responsibility and stop further escalation. */
150
+ ack(id, options = {}) {
151
+ const kase = this.#mustGet(id)
152
+ if (!isObject(options)) fail('E_INPUT', 'ack options must be an object')
153
+ const by = readText(options.by, 'by')
154
+ if (!['pending', 'notified', 'escalated'].includes(kase.state)) fail('E_STATE', `cannot ack a case in state "${kase.state}"`)
155
+ const at = readTimestamp(this.clock(), 'clock')
156
+ kase.state = 'acked'
157
+ kase.ackedAt = at
158
+ kase.ackedBy = by
159
+ kase.updatedAt = at
160
+ this.#record(kase, 'ack', at, { by })
161
+ return clone(kase)
162
+ }
163
+
164
+ /**
165
+ * Move a case to `escalated`. `to` is a chain level (number or `t<N>`) or a
166
+ * free-form target label; omit it to advance one level automatically.
167
+ */
168
+ escalate(id, options = {}) {
169
+ const kase = this.#mustGet(id)
170
+ if (!isObject(options)) fail('E_INPUT', 'escalate options must be an object')
171
+ if (kase.state === 'resolved') fail('E_STATE', 'cannot escalate a resolved case')
172
+ if (kase.state === 'acked') fail('E_STATE', 'cannot escalate an acked case; ack stops escalation')
173
+ if (kase.state === 'expired' && options.to === undefined) fail('E_STATE', 'expired case needs an explicit target')
174
+ const at = readTimestamp(this.clock(), 'clock')
175
+ let level
176
+ let target
177
+ if (options.to === undefined) {
178
+ const next = kase.escalationChain.find(entry => entry.level > kase.level)
179
+ if (next === undefined) fail('E_STATE', `case is already at escalation level ${kase.level}`)
180
+ level = next.level
181
+ target = `t${level}`
182
+ } else if (typeof options.to === 'number' || /^t?\d+$/i.test(String(options.to).trim())) {
183
+ const requested = typeof options.to === 'number' ? options.to : Number(String(options.to).trim().replace(/^t/i, ''))
184
+ const entry = kase.escalationChain.find(item => item.level === requested)
185
+ if (!Number.isInteger(requested) || requested === 0 || entry === undefined) fail('E_INPUT', `unknown escalation target: ${String(options.to)}`)
186
+ if (requested <= kase.level && kase.state !== 'expired') fail('E_INPUT', `escalation target t${requested} must be above level ${kase.level}`)
187
+ level = Math.max(requested, kase.level)
188
+ target = `t${requested}`
189
+ } else {
190
+ target = readText(options.to, 'to', 'E_INPUT', 64)
191
+ const next = kase.escalationChain.find(entry => entry.level > kase.level)
192
+ if (next === undefined) fail('E_STATE', `case is already at escalation level ${kase.level}`)
193
+ level = next.level
194
+ }
195
+ const entry = kase.escalationChain.find(item => item.level === level)
196
+ kase.state = 'escalated'
197
+ kase.level = level
198
+ kase.escalatedAt = at
199
+ kase.updatedAt = at
200
+ this.#record(kase, 'escalation', at, { channel: entry?.channel, to: target })
201
+ return clone(kase)
202
+ }
203
+
204
+ /** Record the human decision for a case. Ack is not approval; this is. */
205
+ resolve(id, options = {}) {
206
+ const kase = this.#mustGet(id)
207
+ if (!isObject(options)) fail('E_INPUT', 'resolve options must be an object')
208
+ const decision = readText(options.decision, 'decision', 'E_INPUT', 64)
209
+ if (kase.state === 'resolved') fail('E_STATE', 'case is already resolved')
210
+ if (kase.state === 'expired') {
211
+ fail('E_STATE', 'cannot resolve an expired case; escalate it with an explicit target or raise a new case')
212
+ }
213
+ const at = readTimestamp(this.clock(), 'clock')
214
+ const late = kase.expiredAt !== undefined || at > kase.expiresAt
215
+ kase.state = 'resolved'
216
+ kase.decision = decision
217
+ kase.resolvedAt = at
218
+ kase.updatedAt = at
219
+ if (late) kase.late = true
220
+ this.#record(kase, 'decision', at)
221
+ return clone(kase)
222
+ }
223
+
224
+ /** Return all receipts for one case, in insertion order. */
225
+ receipts(id) {
226
+ const kase = this.#mustGet(id)
227
+ return this.#receipts.filter(receipt => receipt.caseId === kase.id).map(clone)
228
+ }
229
+
230
+ /** Advance open cases to `now`: expire, deliver t0, then at most one escalation. */
231
+ tick(now = this.clock()) {
232
+ const at = readTimestamp(now, 'now')
233
+ const receipts = []
234
+ const changed = new Set()
235
+ for (const kase of this.#cases.values()) {
236
+ if (kase.state === 'resolved' || kase.state === 'expired' || kase.expiredAt !== undefined) continue
237
+ if (at >= kase.expiresAt) {
238
+ kase.state = 'expired'
239
+ kase.expiredAt = at
240
+ kase.updatedAt = at
241
+ receipts.push(this.#record(kase, 'expiry', at))
242
+ changed.add(kase.id)
243
+ continue
244
+ }
245
+ if (kase.state === 'pending') {
246
+ const t0 = kase.escalationChain.find(entry => entry.level === 0 && at >= kase.createdAt + entry.afterMs)
247
+ if (t0 === undefined) continue
248
+ kase.state = 'notified'
249
+ kase.notifiedAt = at
250
+ kase.updatedAt = at
251
+ receipts.push(this.#record(kase, 'delivery', at, { channel: t0.channel, to: 't0' }))
252
+ changed.add(kase.id)
253
+ }
254
+ if (!['notified', 'escalated'].includes(kase.state)) continue
255
+ const due = kase.escalationChain
256
+ .filter(entry => entry.level > kase.level && at >= kase.createdAt + entry.afterMs)
257
+ .sort((a, b) => a.level - b.level)
258
+ const next = due.at(-1)
259
+ if (next === undefined) continue
260
+ kase.state = 'escalated'
261
+ kase.level = next.level
262
+ kase.escalatedAt = at
263
+ kase.updatedAt = at
264
+ receipts.push(this.#record(kase, 'escalation', at, { channel: next.channel, to: `t${next.level}` }))
265
+ changed.add(kase.id)
266
+ }
267
+ return {
268
+ now: at,
269
+ receipts,
270
+ cases: [...changed].map(id => clone(this.#cases.get(id))),
271
+ }
272
+ }
273
+
274
+ #mustGet(id) {
275
+ const key = readId(id)
276
+ const kase = this.#cases.get(key)
277
+ if (kase === undefined) fail('E_NOT_FOUND', `ring case "${key}" is not registered`)
278
+ return kase
279
+ }
280
+
281
+ #record(kase, kind, at, extra = {}) {
282
+ // Receipts are append-only evidence: freeze the stored entry so no later
283
+ // code path can rewrite history, and hand callers a mutable copy.
284
+ const receipt = Object.freeze({ id: randomUUID(), caseId: kase.id, kind, at, ...extra })
285
+ this.#receipts.push(receipt)
286
+ return clone(receipt)
287
+ }
288
+ }
289
+
290
+ const OUTPUT = { schema: { type: 'object', additionalProperties: true }, render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }] }
291
+ const argsSchema = (properties, required) => ({ type: 'object', additionalProperties: false, properties, ...(required === undefined ? {} : { required }) })
292
+
293
+ const CHAIN_SCHEMA = {
294
+ type: 'array',
295
+ description: 'Full SLA chain; omit for t0 0s, t1 3m, t2 10m, t3 30m.',
296
+ items: {
297
+ anyOf: [
298
+ { type: 'number', minimum: 0 },
299
+ { type: 'object', additionalProperties: false, properties: { level: { type: 'integer', minimum: 0 }, afterMs: { type: 'number', minimum: 0 }, channel: { type: 'string' } } },
300
+ ],
301
+ },
302
+ }
303
+
304
+ const tool = (name, description, parameters, execute) => ({ name, description, parameters, output: OUTPUT, execute })
305
+
306
+ /** Plain ToolDefinition objects; no dependency on `@deepseek-ai/dsh-tools`. */
307
+ export function createTools(service) {
308
+ return [
309
+ tool('ring_raise', 'Raise a pending approval case with an SLA escalation chain (local receipts only; nothing is sent).',
310
+ argsSchema({
311
+ source: { type: 'string', description: 'Origin, e.g. approval, hook, act or manual.' },
312
+ risk: { type: 'string', enum: RISKS, description: 'Defaults to write.' },
313
+ ttlMs: { type: 'number', minimum: 1, description: 'Case lifetime in ms; defaults to 60 minutes.' },
314
+ escalationChain: CHAIN_SCHEMA,
315
+ }, ['source']),
316
+ async args => ({ case: service.raise(args ?? {}) })),
317
+ tool('ring_ack', 'Acknowledge and claim a case. Ack stops escalation but is not approval.',
318
+ argsSchema({
319
+ id: { type: 'string' },
320
+ by: { type: 'string', description: 'Principal acknowledging the case.' },
321
+ }, ['id', 'by']),
322
+ async args => ({ case: service.ack(args?.id, { by: args?.by }) })),
323
+ tool('ring_escalate', 'Escalate a case to a chain level (number or t1..t3) or target label; omit to target the next level.',
324
+ argsSchema({
325
+ id: { type: 'string' },
326
+ to: { type: ['integer', 'string'], description: 'Escalation level or target label.' },
327
+ }, ['id']),
328
+ async args => ({ case: service.escalate(args?.id, args?.to === undefined ? {} : { to: args.to }) })),
329
+ tool('ring_list', 'List approval cases, optionally filtered by status.',
330
+ argsSchema({
331
+ status: { type: 'string', enum: STATES },
332
+ }),
333
+ async args => ({ cases: service.list(args?.status === undefined ? {} : { status: args.status }) })),
334
+ tool('ring_receipts', 'List the audit receipts for one case (delivery, escalation, ack, decision or expiry).',
335
+ argsSchema({ id: { type: 'string' } }, ['id']),
336
+ async args => ({ receipts: service.receipts(args?.id) })),
337
+ ]
338
+ }
339
+
340
+ /** Mount the plugin at `ctx.ring` and register the five agent tools. */
341
+ export function apply(ctx, config = {}) {
342
+ const service = new RingService(ctx, config)
343
+ ctx.provide('ring', service)
344
+ if (ctx.tools && typeof ctx.tools.register === 'function') {
345
+ for (const tool of createTools(service)) ctx.tools.register(tool)
346
+ }
347
+ return service
348
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-ring",
3
- "version": "0.0.1",
3
+ "version": "0.1.1",
4
4
  "description": "Approval SLA and escalation receipts for DeepSeek Harness: ack, escalate, audit.",
5
5
  "type": "module",
6
6
  "main": "index.js",
@@ -34,15 +34,38 @@
34
34
  },
35
35
  "engines": {
36
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"
37
+ "dsh": ">=0.2.1-rc.2 <0.3.0-0"
38
38
  },
39
39
  "dsh": {
40
40
  "manifestVersion": 1,
41
41
  "bundle": {
42
42
  "patch": "./cordis.patch.yml"
43
+ },
44
+ "os": {
45
+ "service": "ring",
46
+ "provides": [
47
+ "ring"
48
+ ],
49
+ "capabilities": [
50
+ "notify"
51
+ ],
52
+ "tools": [
53
+ "ring_raise",
54
+ "ring_ack",
55
+ "ring_escalate",
56
+ "ring_list",
57
+ "ring_receipts"
58
+ ],
59
+ "ui": null,
60
+ "stability": "experimental",
61
+ "since": "0.1.0"
43
62
  }
44
63
  },
45
64
  "publishConfig": {
46
- "access": "public"
65
+ "access": "public",
66
+ "registry": "https://registry.npmjs.org/"
67
+ },
68
+ "scripts": {
69
+ "test": "node --test"
47
70
  }
48
71
  }