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