dsh-ring 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.
Files changed (4) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/README.md +101 -7
  3. package/index.js +337 -7
  4. package/package.json +4 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,21 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.0
4
+
5
+ - Add `RingService` at `ctx.ring`: `raise`, `tick`, `ack`, `escalate`, `resolve`,
6
+ `get`, `list` and `receipts`.
7
+ - Add the SLA state machine: `pending -> notified -> acked -> resolved`, with
8
+ `escalated` and `expired` branches. Illegal transitions throw `E_STATE`.
9
+ - Add the deterministic SLA clock (`tick(now)`): t0 0s, t1 3m, t2 10m, t3 30m,
10
+ and a 60-minute default case TTL. Missed steps collapse into one catch-up
11
+ escalation per case per tick.
12
+ - Record delivery, escalation, ack, decision and expiry receipts locally. No
13
+ notification, IM or voice channel is contacted in this release; those land in
14
+ 0.2.0.
15
+ - Add plain tool definitions `ring_raise`, `ring_ack`, `ring_escalate`,
16
+ `ring_list` and `ring_receipts`.
17
+ - Ack is explicitly not approval: v0 never approves remotely.
18
+
3
19
  ## 0.0.1
4
20
 
5
21
  - 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.0 — 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,96 @@ 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`). A decision after expiry is kept and 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 --late 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
+ - An acked case is never escalated automatically. An expired case can only be
71
+ escalated with an explicit `to` target (a late page), never by `tick`; later
72
+ ticks leave that page open for a decision.
73
+ - Every tick records at most one escalation receipt — the highest due level —
74
+ so jumping straight to t3 emits t0 plus one t3 catch-up instead of a burst.
75
+ - Nothing is sent over a network, spawned, or written to the session log.
76
+
77
+ ## Receipts
78
+
79
+ ```js
80
+ { id, caseId, kind, at, channel?, by?, to? }
81
+ ```
82
+
83
+ `kind` is one of `delivery` (t0), `escalation` (t1–t3), `ack`, `decision` or
84
+ `expiry`. `channel` is the recorded target channel; `by` is the acknowledging
85
+ principal; `to` is the SLA level or explicit escalation target. Receipts are
86
+ evidence only — they do not prove a channel delivered anything.
87
+
88
+ ## Agent tools
89
+
90
+ | Tool | Arguments |
91
+ |---|---|
92
+ | `ring_raise` | `source`, optional `risk`, `ttlMs`, `escalationChain` |
93
+ | `ring_ack` | `id`, `by` |
94
+ | `ring_escalate` | `id`, optional `to` |
95
+ | `ring_list` | optional `status` |
96
+ | `ring_receipts` | `id` |
97
+
98
+ Tools are plain `ToolDefinition` objects and return `{ case }`, `{ cases }` or
99
+ `{ receipts }`. There is deliberately no model-facing `ring_resolve`: the model
100
+ can raise, list, page and acknowledge, but only the human/approval seam records
101
+ the decision.
102
+
103
+ ## Errors
104
+
105
+ | Code | Meaning |
106
+ |---|---|
107
+ | `E_STATE` | Illegal state transition (e.g. acking a resolved case, auto-escalating an expired one) |
108
+ | `E_NOT_FOUND` | Unknown case id |
109
+ | `E_INPUT` | Invalid argument, risk, status, timestamp or escalation target |
110
+ | `E_TTL` | Invalid `ttlMs` |
111
+ | `E_CHAIN` | Invalid or duplicate escalation chain |
16
112
 
17
- ## Design
113
+ ## License
18
114
 
19
- - Host seam: `ctx.ring` (planned)
20
- - Agent tools and CLI are declared in the package's design doc.
21
- - License: MIT.
115
+ MIT.
package/index.js CHANGED
@@ -1,13 +1,343 @@
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
+ const at = readTimestamp(this.clock(), 'clock')
211
+ const late = kase.state === 'expired' || at > kase.expiresAt
212
+ kase.state = 'resolved'
213
+ kase.decision = decision
214
+ kase.resolvedAt = at
215
+ kase.updatedAt = at
216
+ if (late) kase.late = true
217
+ this.#record(kase, 'decision', at)
218
+ return clone(kase)
219
+ }
220
+
221
+ /** Return all receipts for one case, in insertion order. */
222
+ receipts(id) {
223
+ const kase = this.#mustGet(id)
224
+ return this.#receipts.filter(receipt => receipt.caseId === kase.id).map(clone)
225
+ }
226
+
227
+ /** Advance open cases to `now`: expire, deliver t0, then at most one escalation. */
228
+ tick(now = this.clock()) {
229
+ const at = readTimestamp(now, 'now')
230
+ const receipts = []
231
+ const changed = new Set()
232
+ for (const kase of this.#cases.values()) {
233
+ if (kase.state === 'resolved' || kase.state === 'expired' || kase.expiredAt !== undefined) continue
234
+ if (at >= kase.expiresAt) {
235
+ kase.state = 'expired'
236
+ kase.expiredAt = at
237
+ kase.updatedAt = at
238
+ receipts.push(this.#record(kase, 'expiry', at))
239
+ changed.add(kase.id)
240
+ continue
241
+ }
242
+ if (kase.state === 'pending') {
243
+ const t0 = kase.escalationChain.find(entry => entry.level === 0 && at >= kase.createdAt + entry.afterMs)
244
+ if (t0 === undefined) continue
245
+ kase.state = 'notified'
246
+ kase.notifiedAt = at
247
+ kase.updatedAt = at
248
+ receipts.push(this.#record(kase, 'delivery', at, { channel: t0.channel, to: 't0' }))
249
+ changed.add(kase.id)
250
+ }
251
+ if (!['notified', 'escalated'].includes(kase.state)) continue
252
+ const due = kase.escalationChain
253
+ .filter(entry => entry.level > kase.level && at >= kase.createdAt + entry.afterMs)
254
+ .sort((a, b) => a.level - b.level)
255
+ const next = due.at(-1)
256
+ if (next === undefined) continue
257
+ kase.state = 'escalated'
258
+ kase.level = next.level
259
+ kase.escalatedAt = at
260
+ kase.updatedAt = at
261
+ receipts.push(this.#record(kase, 'escalation', at, { channel: next.channel, to: `t${next.level}` }))
262
+ changed.add(kase.id)
263
+ }
264
+ return {
265
+ now: at,
266
+ receipts,
267
+ cases: [...changed].map(id => clone(this.#cases.get(id))),
268
+ }
269
+ }
270
+
271
+ #mustGet(id) {
272
+ const key = readId(id)
273
+ const kase = this.#cases.get(key)
274
+ if (kase === undefined) fail('E_NOT_FOUND', `ring case "${key}" is not registered`)
275
+ return kase
276
+ }
277
+
278
+ #record(kase, kind, at, extra = {}) {
279
+ const receipt = { id: randomUUID(), caseId: kase.id, kind, at, ...extra }
280
+ this.#receipts.push(receipt)
281
+ return clone(receipt)
282
+ }
283
+ }
284
+
285
+ const OUTPUT = { schema: { type: 'object', additionalProperties: true }, render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }] }
286
+ const argsSchema = (properties, required) => ({ type: 'object', additionalProperties: false, properties, ...(required === undefined ? {} : { required }) })
287
+
288
+ const CHAIN_SCHEMA = {
289
+ type: 'array',
290
+ description: 'Full SLA chain; omit for t0 0s, t1 3m, t2 10m, t3 30m.',
291
+ items: {
292
+ anyOf: [
293
+ { type: 'number', minimum: 0 },
294
+ { type: 'object', additionalProperties: false, properties: { level: { type: 'integer', minimum: 0 }, afterMs: { type: 'number', minimum: 0 }, channel: { type: 'string' } } },
295
+ ],
296
+ },
297
+ }
298
+
299
+ const tool = (name, description, parameters, execute) => ({ name, description, parameters, output: OUTPUT, execute })
300
+
301
+ /** Plain ToolDefinition objects; no dependency on `@deepseek-ai/dsh-tools`. */
302
+ export function createTools(service) {
303
+ return [
304
+ tool('ring_raise', 'Raise a pending approval case with an SLA escalation chain (local receipts only; nothing is sent).',
305
+ argsSchema({
306
+ source: { type: 'string', description: 'Origin, e.g. approval, hook, act or manual.' },
307
+ risk: { type: 'string', enum: RISKS, description: 'Defaults to write.' },
308
+ ttlMs: { type: 'number', minimum: 1, description: 'Case lifetime in ms; defaults to 60 minutes.' },
309
+ escalationChain: CHAIN_SCHEMA,
310
+ }, ['source']),
311
+ async args => ({ case: service.raise(args ?? {}) })),
312
+ tool('ring_ack', 'Acknowledge and claim a case. Ack stops escalation but is not approval.',
313
+ argsSchema({
314
+ id: { type: 'string' },
315
+ by: { type: 'string', description: 'Principal acknowledging the case.' },
316
+ }, ['id', 'by']),
317
+ async args => ({ case: service.ack(args?.id, { by: args?.by }) })),
318
+ tool('ring_escalate', 'Escalate a case to a chain level (number or t1..t3) or target label; omit to target the next level.',
319
+ argsSchema({
320
+ id: { type: 'string' },
321
+ to: { type: ['integer', 'string'], description: 'Escalation level or target label.' },
322
+ }, ['id']),
323
+ async args => ({ case: service.escalate(args?.id, args?.to === undefined ? {} : { to: args.to }) })),
324
+ tool('ring_list', 'List approval cases, optionally filtered by status.',
325
+ argsSchema({
326
+ status: { type: 'string', enum: STATES },
327
+ }),
328
+ async args => ({ cases: service.list(args?.status === undefined ? {} : { status: args.status }) })),
329
+ tool('ring_receipts', 'List the audit receipts for one case (delivery, escalation, ack, decision or expiry).',
330
+ argsSchema({ id: { type: 'string' } }, ['id']),
331
+ async args => ({ receipts: service.receipts(args?.id) })),
332
+ ]
333
+ }
334
+
335
+ /** Mount the plugin at `ctx.ring` and register the five agent tools. */
336
+ export function apply(ctx, config = {}) {
337
+ const service = new RingService(ctx, config)
338
+ ctx.provide('ring', service)
339
+ if (ctx.tools && typeof ctx.tools.register === 'function') {
340
+ for (const tool of createTools(service)) ctx.tools.register(tool)
341
+ }
342
+ return service
343
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-ring",
3
- "version": "0.0.1",
3
+ "version": "0.1.0",
4
4
  "description": "Approval SLA and escalation receipts for DeepSeek Harness: ack, escalate, audit.",
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
  }