dsh-ring 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,22 @@
1
+ # Changelog
2
+
3
+ ## 0.1.0
4
+
5
+ - Add `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
+
19
+ ## 0.0.1
20
+
21
+ - Reserve the `dsh-ring` 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,115 @@
1
- # Temporary Holding Version
1
+ # Ring · `dsh-ring`
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ > **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.
5
+
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.
15
+
16
+ **Not affiliated with DeepSeek.** DeepSeek and DeepSeek Harness are trademarks
17
+ of their respective owners.
18
+
19
+ ## Install
20
+
21
+ ```sh
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
+
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 |
112
+
113
+ ## License
114
+
115
+ MIT.
@@ -0,0 +1,4 @@
1
+ # dsh-ring bundle patch: mount the plugin.
2
+ - insert:
3
+ - id: dsh-ring
4
+ name: dsh-ring
package/index.js ADDED
@@ -0,0 +1,343 @@
1
+ /**
2
+ * dsh-ring — approval SLA and escalation receipts for DeepSeek Harness.
3
+ *
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
8
+ */
9
+ import { randomUUID } from 'node:crypto'
10
+
11
+ export const name = 'dsh-ring'
12
+ export const inject = ['tools']
13
+
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,51 @@
1
1
  {
2
2
  "name": "dsh-ring",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "Approval SLA and escalation receipts for DeepSeek Harness: ack, escalate, audit.",
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
+ "ring"
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/ring"
30
+ },
31
+ "homepage": "https://github.com/PerryLink/dsh-os/tree/main/packages/ring#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
+ "publishConfig": {
46
+ "access": "public"
47
+ },
48
+ "scripts": {
49
+ "test": "node --test"
50
+ }
51
+ }