dsh-completion-guard 0.2.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.
- package/CHANGELOG.md +83 -0
- package/CHANGELOG.zh-CN.md +83 -0
- package/LICENSE +202 -0
- package/README.md +100 -0
- package/README.zh-CN.md +100 -0
- package/cordis.patch.yml +5 -0
- package/dist/domain/index.d.ts +2 -0
- package/dist/domain/index.js +3 -0
- package/dist/domain-BN3_AuUr.js +1997 -0
- package/dist/index-Dk4SkQ8H.d.ts +448 -0
- package/dist/index.d.ts +17 -0
- package/dist/index.js +1125 -0
- package/docs/ARCHITECTURE.md +42 -0
- package/docs/COMPATIBILITY.md +169 -0
- package/docs/LOCAL_ACCEPTANCE.md +337 -0
- package/docs/PORTING_NOTES.md +14 -0
- package/docs/PRIVACY.md +23 -0
- package/docs/UPSTREAM_BASE.md +22 -0
- package/package.json +70 -0
|
@@ -0,0 +1,448 @@
|
|
|
1
|
+
//#region src/domain/canonicalize.d.ts
|
|
2
|
+
declare function normalizeClause(text: string): string;
|
|
3
|
+
/**
|
|
4
|
+
* Canonicalize a filesystem path for subject matching. Windows-style paths are
|
|
5
|
+
* normalized (drive letter, both separator kinds, `.`/`..`, duplicate
|
|
6
|
+
* separators) and case-folded, because Windows paths compare case-insensitively
|
|
7
|
+
* and treat `/` and `\` as equivalent. POSIX-style paths are normalized but
|
|
8
|
+
* keep their case, so a case-sensitive filesystem is never made insensitive.
|
|
9
|
+
* Exactly one canonicalizer is shared by contract capture and evidence
|
|
10
|
+
* extraction so a Windows contract subject and a Windows evidence subject match.
|
|
11
|
+
*/
|
|
12
|
+
declare function canonicalizePath(value: string): string;
|
|
13
|
+
declare function sha256(text: string): string;
|
|
14
|
+
declare function digestStrings(values: readonly string[]): string;
|
|
15
|
+
declare function sanitizeClauseText(text: string): string;
|
|
16
|
+
declare function sanitizeUrl(value: string): string;
|
|
17
|
+
//#endregion
|
|
18
|
+
//#region src/domain/types.d.ts
|
|
19
|
+
type GuardItemKind = "requirement" | "acceptance" | "prohibition";
|
|
20
|
+
type GuardItemStatus = "pending" | "passed" | "superseded";
|
|
21
|
+
type GuardIntegrity = "valid" | "unknown" | "corrupt";
|
|
22
|
+
type EvidenceOutcome = "success" | "failure" | "unknown";
|
|
23
|
+
type GuardOperation = "create" | "write" | "modify" | "read" | "run" | "verify";
|
|
24
|
+
interface VerificationContract {
|
|
25
|
+
subject?: string;
|
|
26
|
+
surface?: "artifact" | "ui" | "visual" | "scope";
|
|
27
|
+
enforced: boolean;
|
|
28
|
+
/** Explicitly-required tool/method (e.g. 'bash'); when set, a successful
|
|
29
|
+
* evidence from that tool must be present in addition to artifact/scope
|
|
30
|
+
* coverage before the item can close. */
|
|
31
|
+
method?: string;
|
|
32
|
+
/** Explicitly-required operation/effect (e.g. 'create', 'read'). When set
|
|
33
|
+
* alongside `method`, the method evidence must have performed that operation
|
|
34
|
+
* on the same canonical subject — mentioning the file is not enough. */
|
|
35
|
+
operation?: GuardOperation;
|
|
36
|
+
}
|
|
37
|
+
interface GuardItem {
|
|
38
|
+
id: string;
|
|
39
|
+
revision: number;
|
|
40
|
+
kind: GuardItemKind;
|
|
41
|
+
sourceMessageId: string;
|
|
42
|
+
normalizedText: string;
|
|
43
|
+
textSha256: string;
|
|
44
|
+
status: GuardItemStatus;
|
|
45
|
+
supersededBy?: string;
|
|
46
|
+
verification: VerificationContract;
|
|
47
|
+
}
|
|
48
|
+
interface GuardEvidence {
|
|
49
|
+
id: string;
|
|
50
|
+
epoch: number;
|
|
51
|
+
callId: string;
|
|
52
|
+
rootCallId: string;
|
|
53
|
+
toolName: string;
|
|
54
|
+
toolResultSeq: number;
|
|
55
|
+
outcome: EvidenceOutcome;
|
|
56
|
+
capabilities: string[];
|
|
57
|
+
subjects: string[];
|
|
58
|
+
surfaces: Array<"artifact" | "ui" | "visual" | "scope">;
|
|
59
|
+
boundedSummarySha256: string;
|
|
60
|
+
/** Executables invoked by a shell-tool command (e.g. 'pnpm', 'git'); present
|
|
61
|
+
* only for command evidence, so an executable-method constraint ("使用 pnpm")
|
|
62
|
+
* can be verified against the command that actually ran. */
|
|
63
|
+
executables?: string[];
|
|
64
|
+
/** Operations with their paths, parsed from the evidence's command or tool
|
|
65
|
+
* payload (quote-aware). A subject mention alone proves nothing; the evidence
|
|
66
|
+
* must show the requested operation on the target. */
|
|
67
|
+
operations?: Array<{
|
|
68
|
+
op: GuardOperation;
|
|
69
|
+
path?: string;
|
|
70
|
+
}>;
|
|
71
|
+
}
|
|
72
|
+
interface EvidenceBinding {
|
|
73
|
+
itemId: string;
|
|
74
|
+
evidenceIds: string[];
|
|
75
|
+
}
|
|
76
|
+
interface GuardCheckpoint {
|
|
77
|
+
id: string;
|
|
78
|
+
epoch: number;
|
|
79
|
+
contractRevision: number;
|
|
80
|
+
openDigest: string;
|
|
81
|
+
bindingDigest: string;
|
|
82
|
+
bindings: EvidenceBinding[];
|
|
83
|
+
result: "certified" | "incomplete" | "unknown";
|
|
84
|
+
}
|
|
85
|
+
interface GuardProjection {
|
|
86
|
+
enabled: boolean;
|
|
87
|
+
epoch: number;
|
|
88
|
+
contractRevision: number;
|
|
89
|
+
items: Map<string, GuardItem>;
|
|
90
|
+
evidence: Map<string, GuardEvidence>;
|
|
91
|
+
checkpoints: GuardCheckpoint[];
|
|
92
|
+
lastObservedSourceSeq: number;
|
|
93
|
+
lastGuardEventSeq: number;
|
|
94
|
+
lastRecoveryDigest?: string;
|
|
95
|
+
continuationAttempts: Map<number, number>;
|
|
96
|
+
integrity: GuardIntegrity;
|
|
97
|
+
}
|
|
98
|
+
declare function createProjection(): GuardProjection;
|
|
99
|
+
interface DeriveScope {
|
|
100
|
+
/** Session working directory; used as the scope subject for captured clauses. */
|
|
101
|
+
cwd?: string;
|
|
102
|
+
}
|
|
103
|
+
interface DeriveConfig {
|
|
104
|
+
activation: "opt-in" | "always";
|
|
105
|
+
}
|
|
106
|
+
interface DeriveResult {
|
|
107
|
+
projection: GuardProjection;
|
|
108
|
+
/** True when the log contains a compaction summary the agent must recover from. */
|
|
109
|
+
compacted: boolean;
|
|
110
|
+
/** True when an off→on enablement transition was derived in this log. */
|
|
111
|
+
enablementTransitioned: boolean;
|
|
112
|
+
/** Sequence of the last compaction summary in the log, or -1 when none. */
|
|
113
|
+
lastCompactionSeq: number;
|
|
114
|
+
}
|
|
115
|
+
interface DerivedEnvelope {
|
|
116
|
+
seq: number;
|
|
117
|
+
type: string;
|
|
118
|
+
data?: unknown;
|
|
119
|
+
}
|
|
120
|
+
//#endregion
|
|
121
|
+
//#region src/domain/capture.d.ts
|
|
122
|
+
interface ClassifiedClause {
|
|
123
|
+
kind: GuardItemKind;
|
|
124
|
+
body: string;
|
|
125
|
+
}
|
|
126
|
+
declare function classifyClause(text: string): ClassifiedClause;
|
|
127
|
+
/**
|
|
128
|
+
* Detect an explicitly named tool/method in a clause ("使用 bash 创建",
|
|
129
|
+
* "via bash", "bash to create"). Returns the canonical tool id (e.g. 'bash')
|
|
130
|
+
* or undefined when no explicit method is named.
|
|
131
|
+
*/
|
|
132
|
+
declare function extractMethod(text: string): string | undefined;
|
|
133
|
+
/**
|
|
134
|
+
* Whether a whole user message reads as an informational report (acceptance
|
|
135
|
+
* receipt, progress summary, pasted log) rather than a task instruction.
|
|
136
|
+
* Evaluation is deliberately conservative: reports are detected only when the
|
|
137
|
+
* shape is clearly report-like (markdown headings, bold key/value lines, list
|
|
138
|
+
* or table rows, evidence terms) AND no sentence opens with an imperative, and
|
|
139
|
+
* any question mark keeps the message a task. False positives here would drop
|
|
140
|
+
* real instructions, so plain short sentences are never treated as reports.
|
|
141
|
+
*/
|
|
142
|
+
declare function isInformationalMessage(text: string): boolean;
|
|
143
|
+
/**
|
|
144
|
+
* Detect an explicit operation/effect in a clause ("创建" → create,
|
|
145
|
+
* "读取" → read, "运行" → run). Returns the first operation named, or undefined
|
|
146
|
+
* when the clause requests no specific effect.
|
|
147
|
+
*/
|
|
148
|
+
declare function extractOperation(text: string): GuardOperation | undefined;
|
|
149
|
+
interface CaptureScope {
|
|
150
|
+
/** Session working directory; used as the scope subject when no artifact path is named. */
|
|
151
|
+
cwd?: string;
|
|
152
|
+
}
|
|
153
|
+
declare function extractArtifactPaths(text: string): string[];
|
|
154
|
+
/**
|
|
155
|
+
* Split a single human message into independently tracked clauses. Sentence
|
|
156
|
+
* boundaries and embedded prohibition keywords delimit segments so a compound
|
|
157
|
+
* instruction such as "Modify src/a.ts and src/b.ts. Do not push." yields
|
|
158
|
+
* separate items instead of collapsing into one artifact.
|
|
159
|
+
*/
|
|
160
|
+
interface ClauseSegment {
|
|
161
|
+
kind: GuardItemKind;
|
|
162
|
+
body: string;
|
|
163
|
+
paths: string[];
|
|
164
|
+
}
|
|
165
|
+
declare function segmentClauses(text: string): ClauseSegment[];
|
|
166
|
+
/**
|
|
167
|
+
* Build a GuardItem from an already-classified clause body and a resolved
|
|
168
|
+
* verification subject/surface.
|
|
169
|
+
*/
|
|
170
|
+
declare function captureItem(kind: GuardItemKind, body: string, sourceMessageId: string, id: string, revision: number, subject: string, surface: "artifact" | "scope", method?: string, operation?: GuardOperation): GuardItem;
|
|
171
|
+
/**
|
|
172
|
+
* Capture one contract clause. Every captured item receives a concrete
|
|
173
|
+
* verification contract: a named artifact path (artifact surface) or the
|
|
174
|
+
* session scope (scope surface), so an unrelated file read can never close it.
|
|
175
|
+
*/
|
|
176
|
+
declare function captureClause(text: string, sourceMessageId: string, id: string, revision: number, scope?: CaptureScope): GuardItem;
|
|
177
|
+
//#endregion
|
|
178
|
+
//#region src/domain/checkpoint.d.ts
|
|
179
|
+
interface RejectedBinding {
|
|
180
|
+
itemId: string;
|
|
181
|
+
reason: string;
|
|
182
|
+
hint?: string;
|
|
183
|
+
}
|
|
184
|
+
interface CheckpointResult {
|
|
185
|
+
status: GuardCheckpoint["result"];
|
|
186
|
+
contractRevision: number;
|
|
187
|
+
openItems: string[];
|
|
188
|
+
rejectedBindings: RejectedBinding[];
|
|
189
|
+
checkpoint?: GuardCheckpoint;
|
|
190
|
+
}
|
|
191
|
+
declare function certifyCheckpoint(projection: GuardProjection, bindings: EvidenceBinding[], id: string): CheckpointResult;
|
|
192
|
+
//#endregion
|
|
193
|
+
//#region src/domain/conversation.d.ts
|
|
194
|
+
type UserInteractionKind = "instruction" | "conversational";
|
|
195
|
+
/**
|
|
196
|
+
* Classify a direct user message (or one clause of it) as an actionable
|
|
197
|
+
* `instruction` or a session-layer `conversational` utterance. Only
|
|
198
|
+
* conversational results drop capture, so the classifier fails closed:
|
|
199
|
+
* everything it cannot confidently recognize as session-layer talk stays an
|
|
200
|
+
* instruction and is captured exactly as before.
|
|
201
|
+
*
|
|
202
|
+
* Order matters: progression and prohibition leads first, then strong task
|
|
203
|
+
* features (artifact path, explicit method, or a non-negated operation verb
|
|
204
|
+
* outside progression/meta spans), then the meta-question and meta-comment
|
|
205
|
+
* forms, and finally a progression lead over a featureless remainder.
|
|
206
|
+
*/
|
|
207
|
+
declare function classifyUserInteraction(text: string): UserInteractionKind;
|
|
208
|
+
//#endregion
|
|
209
|
+
//#region src/domain/derive.d.ts
|
|
210
|
+
/**
|
|
211
|
+
* Pure, deterministic re-derivation of the guard projection from the DSH
|
|
212
|
+
* native event log. Context Guard never writes custom session events, so every
|
|
213
|
+
* piece of state is derived from `command/run`, `user/message`, `tool/call`,
|
|
214
|
+
* `tool/result`, `tool/code-dispatch-start`, `tool/code-dispatch`, and
|
|
215
|
+
* `compaction/summary`.
|
|
216
|
+
*/
|
|
217
|
+
declare function deriveProjection(sourceEvents: readonly DerivedEnvelope[], config: DeriveConfig, scope: DeriveScope, durableConfirmed: boolean): DeriveResult;
|
|
218
|
+
//#endregion
|
|
219
|
+
//#region src/domain/evidence.d.ts
|
|
220
|
+
interface ToolCallInput {
|
|
221
|
+
callId: string;
|
|
222
|
+
name: string;
|
|
223
|
+
arguments: string;
|
|
224
|
+
/** Code-mode dispatch root; falls back to `callId` when the harness does not carry one. */
|
|
225
|
+
rootCallId?: string;
|
|
226
|
+
}
|
|
227
|
+
interface ToolResultInput {
|
|
228
|
+
seq: number;
|
|
229
|
+
error?: unknown;
|
|
230
|
+
meta?: unknown;
|
|
231
|
+
textContent: string;
|
|
232
|
+
}
|
|
233
|
+
declare function extractTextContent(content: readonly unknown[]): string;
|
|
234
|
+
interface ToolOperation {
|
|
235
|
+
op: GuardOperation;
|
|
236
|
+
path?: string;
|
|
237
|
+
}
|
|
238
|
+
declare function isDeterministicCheck(command: string): boolean;
|
|
239
|
+
interface ToolSubject {
|
|
240
|
+
capabilities: string[];
|
|
241
|
+
subjects: string[];
|
|
242
|
+
surfaces: Array<"artifact" | "ui" | "visual" | "scope">;
|
|
243
|
+
outcome?: EvidenceOutcome;
|
|
244
|
+
executables?: string[];
|
|
245
|
+
operations?: ToolOperation[];
|
|
246
|
+
}
|
|
247
|
+
declare function extractToolSubject(call: ToolCallInput, result: ToolResultInput, defaultCwd?: string): ToolSubject;
|
|
248
|
+
declare function evidenceFromPersistedToolResult(call: ToolCallInput, result: ToolResultInput, epoch: number, evidenceId: string, defaultCwd?: string): GuardEvidence;
|
|
249
|
+
declare function withDurability(evidence: GuardEvidence, confirmed: boolean): GuardEvidence;
|
|
250
|
+
//#endregion
|
|
251
|
+
//#region src/domain/goal-gate.d.ts
|
|
252
|
+
declare function hasCurrentCertificate(projection: GuardProjection): boolean;
|
|
253
|
+
/**
|
|
254
|
+
* Denies `update_goal(action=complete)` while the guard is enabled and no
|
|
255
|
+
* current completion certificate exists. The gate itself has no bypass; a
|
|
256
|
+
* workflow that genuinely finished but cannot certify (for example a contract
|
|
257
|
+
* polluted by session-layer talk, or evidence that lives in another session)
|
|
258
|
+
* has three explicit remediation routes:
|
|
259
|
+
*
|
|
260
|
+
* 1. `/context-guard off` disables the guard, so completion is no longer
|
|
261
|
+
* gated. Use only after the user confirms the work is actually done.
|
|
262
|
+
* 2. `/context-guard clear` supersedes every pending requirement and
|
|
263
|
+
* acceptance under a `CLEAR:<revision>` sentinel (prohibitions are
|
|
264
|
+
* retained) and bumps the contract revision; an empty-binding checkpoint
|
|
265
|
+
* can then certify while the guard stays enabled.
|
|
266
|
+
* 3. `update_goal(action=blocked)` records the blocker truthfully, which is
|
|
267
|
+
* never denied by this gate.
|
|
268
|
+
*/
|
|
269
|
+
declare function goalCompletionDenial(projection: GuardProjection, toolName: string, argumentsValue: unknown, configuredToolName?: string): string | undefined;
|
|
270
|
+
//#endregion
|
|
271
|
+
//#region src/domain/manifest.d.ts
|
|
272
|
+
/**
|
|
273
|
+
* The single source of truth for the certifiable command surface (v0.2).
|
|
274
|
+
*
|
|
275
|
+
* Every enumeration that decides which command shapes can produce evidence
|
|
276
|
+
* lives HERE, loaded by the parsers and by the contract capture. Adding a tool
|
|
277
|
+
* or a task verb is a data change, not a code change. The manifest is shipped
|
|
278
|
+
* with the package and is intentionally NOT runtime-writable: widening the
|
|
279
|
+
* surface lowers the evidence bar, so it must change only through a reviewed
|
|
280
|
+
* release, never through local configuration.
|
|
281
|
+
*/
|
|
282
|
+
interface OperationVerbEntry {
|
|
283
|
+
op: GuardOperation;
|
|
284
|
+
/** RegExp source, matched case-insensitively; array order = priority. */
|
|
285
|
+
pattern: string;
|
|
286
|
+
}
|
|
287
|
+
interface CommandSurfaceManifest {
|
|
288
|
+
/** POSIX file-effect tools (`printf`, `echo`, `touch`, `cat`). */
|
|
289
|
+
fileTools: string[];
|
|
290
|
+
/** POSIX read-only inspection tools; pathish args become read effects. */
|
|
291
|
+
readTools: string[];
|
|
292
|
+
/** POSIX run-executable whitelist (any supported simple command gets run semantics). */
|
|
293
|
+
runExecutables: string[];
|
|
294
|
+
/** PowerShell external-executable whitelist (mirrors runExecutables). */
|
|
295
|
+
pwshExternalExecutables: string[];
|
|
296
|
+
/**
|
|
297
|
+
* Clause verb → operation mapping. Order matters: the first matching group
|
|
298
|
+
* wins, and the group order is create → modify → read → verify → run.
|
|
299
|
+
*/
|
|
300
|
+
operationVerbs: OperationVerbEntry[];
|
|
301
|
+
}
|
|
302
|
+
declare const COMMAND_SURFACE_MANIFEST: CommandSurfaceManifest;
|
|
303
|
+
interface ManifestIssue {
|
|
304
|
+
path: string;
|
|
305
|
+
message: string;
|
|
306
|
+
}
|
|
307
|
+
/**
|
|
308
|
+
* Validate the manifest invariants the parsers and capture depend on:
|
|
309
|
+
* - every collection is non-empty, sorted-case-insensitively, and duplicate-free
|
|
310
|
+
* - external executables mirror the POSIX run set exactly
|
|
311
|
+
* - verb groups exist once, in the documented priority order, and compile
|
|
312
|
+
* (they compile by construction when validated, so a typo cannot silently
|
|
313
|
+
* widen or break the surface).
|
|
314
|
+
*/
|
|
315
|
+
declare function validateManifest(manifest?: CommandSurfaceManifest): ManifestIssue[];
|
|
316
|
+
//#endregion
|
|
317
|
+
//#region src/domain/matching.d.ts
|
|
318
|
+
declare function isVerifyingCapability(evidence: GuardEvidence): boolean;
|
|
319
|
+
/** The facets a single evidence contributes to for an item. */
|
|
320
|
+
interface EvidenceFacetCoverage {
|
|
321
|
+
artifact: boolean;
|
|
322
|
+
effect: boolean;
|
|
323
|
+
method: boolean;
|
|
324
|
+
verify: boolean;
|
|
325
|
+
run: boolean;
|
|
326
|
+
}
|
|
327
|
+
declare function evidenceCoverage(item: GuardItem, evidence: GuardEvidence): EvidenceFacetCoverage;
|
|
328
|
+
/**
|
|
329
|
+
* Whether a single evidence can close an enforced item on its own. This is the
|
|
330
|
+
* conservative per-evidence check; the certifier additionally verifies that the
|
|
331
|
+
* whole binding satisfies every required facet.
|
|
332
|
+
*/
|
|
333
|
+
declare function evidenceMatchesItem(item: GuardItem, evidence: GuardEvidence): boolean;
|
|
334
|
+
/**
|
|
335
|
+
* Whether a whole binding (a set of evidence ids) satisfies the fixed v0.1
|
|
336
|
+
* binding invariants:
|
|
337
|
+
*
|
|
338
|
+
* - run: the method (or run) evidence alone closes the contract — no extra
|
|
339
|
+
* read or unrelated deterministic-check is required.
|
|
340
|
+
* - create/write/modify: BOTH a method evidence (method + operation + subject)
|
|
341
|
+
* and a state-verification evidence on the same subject are required.
|
|
342
|
+
* - read: a successful read evidence matching method, read operation and
|
|
343
|
+
* subject satisfies the method side and the object side at once.
|
|
344
|
+
* - verify: only explicit read/verify/deterministic-check evidence on the
|
|
345
|
+
* subject closes; unrelated scope calls cannot be spliced in.
|
|
346
|
+
* - explicit method without a parsable operation fails closed.
|
|
347
|
+
* - a non-enforced item (prohibition) is acknowledged by any valid success
|
|
348
|
+
* evidence.
|
|
349
|
+
*/
|
|
350
|
+
declare function bindingSatisfies(projection: GuardProjection, item: GuardItem, evidenceIds: string[]): boolean;
|
|
351
|
+
//#endregion
|
|
352
|
+
//#region src/domain/recovery.d.ts
|
|
353
|
+
interface RecoveryOptions {
|
|
354
|
+
rejectedBindings?: Array<{
|
|
355
|
+
itemId: string;
|
|
356
|
+
reason: string;
|
|
357
|
+
}>;
|
|
358
|
+
charBudget?: number;
|
|
359
|
+
}
|
|
360
|
+
declare const DEFAULT_RECOVERY_CHAR_BUDGET = 4e3;
|
|
361
|
+
/**
|
|
362
|
+
* An actionable one-line hint for how an open item's verification contract can
|
|
363
|
+
* be closed. It never weakens the contract; it only names the missing facet so
|
|
364
|
+
* the agent can produce the right evidence shape instead of reverse-engineering
|
|
365
|
+
* the guard. When `evidenceIds` is given, the hint accounts for what those
|
|
366
|
+
* evidence already cover.
|
|
367
|
+
*/
|
|
368
|
+
declare function closingHint(projection: GuardProjection, item: GuardItem, evidenceIds?: string[]): string;
|
|
369
|
+
declare function openItems(projection: GuardProjection): GuardItem[];
|
|
370
|
+
/**
|
|
371
|
+
* Content identity of a rendered recovery packet, bound to the contract
|
|
372
|
+
* revision and epoch it was rendered from. The runtime compares digests before
|
|
373
|
+
* re-injecting, so a repeatedly re-armed recovery with unchanged content is
|
|
374
|
+
* injected once instead of looping (v0.2.1).
|
|
375
|
+
*/
|
|
376
|
+
declare function recoveryDigest(packet: string, projection: GuardProjection): string;
|
|
377
|
+
declare function renderRecoveryPacket(projection: GuardProjection, options?: RecoveryOptions): string;
|
|
378
|
+
//#endregion
|
|
379
|
+
//#region src/domain/shell-parse.d.ts
|
|
380
|
+
/**
|
|
381
|
+
* v0.1 certifiable command subset parser.
|
|
382
|
+
*
|
|
383
|
+
* This is NOT a general Bash or PowerShell static analyzer. Only a small,
|
|
384
|
+
* auditable grammar is supported: a single foreground simple command whose
|
|
385
|
+
* grammar parses fully. Anything else returns `status: 'unsupported'` (or
|
|
386
|
+
* `'malformed'` for unterminated quotes) with EMPTY executables and operations,
|
|
387
|
+
* so an unrecognized command can never certify an operation. False negatives
|
|
388
|
+
* are preferred over false positives: uncertain commands stay incomplete.
|
|
389
|
+
*/
|
|
390
|
+
type ShellParseStatus = "supported" | "unsupported" | "malformed";
|
|
391
|
+
interface ParsedShell {
|
|
392
|
+
status: ShellParseStatus;
|
|
393
|
+
/** Human-readable reason when the command is not supported (or malformed). */
|
|
394
|
+
reason?: string;
|
|
395
|
+
executables: string[];
|
|
396
|
+
operations: Array<{
|
|
397
|
+
op: GuardOperation;
|
|
398
|
+
path?: string;
|
|
399
|
+
}>;
|
|
400
|
+
malformed: boolean;
|
|
401
|
+
}
|
|
402
|
+
/**
|
|
403
|
+
* Whether an executable carries run semantics (as opposed to the tiny
|
|
404
|
+
* file/read tool subset). Used for scope-subject attribution of a pathless
|
|
405
|
+
* run operation; `echo` or `cat` never becomes a subject-carrying run.
|
|
406
|
+
*/
|
|
407
|
+
declare function isRunExecutable(executable: string): boolean;
|
|
408
|
+
/**
|
|
409
|
+
* Parse one POSIX shell command against the v0.1 supported surface: a single
|
|
410
|
+
* foreground simple command made of an env-assignment prefix, one whitelisted
|
|
411
|
+
* executable and literal arguments, with at most one `>`/`>>` redirect to a
|
|
412
|
+
* literal path. Compound syntax (`;`, `&&`, `||`, pipes, background, subshells,
|
|
413
|
+
* command substitution, heredocs, unclosed quotes, dynamic eval/source,
|
|
414
|
+
* variable/glob paths) makes the WHOLE command unsupported with no partial
|
|
415
|
+
* results.
|
|
416
|
+
*/
|
|
417
|
+
declare function parseShellCommand(command: string): ParsedShell;
|
|
418
|
+
/**
|
|
419
|
+
* Parse one PowerShell command against the v0.2 subset: a single, directly
|
|
420
|
+
* invoked whitelisted cmdlet (Set-Content / Add-Content / New-Item /
|
|
421
|
+
* Out-File / Get-Content) whose path comes from an explicit named path
|
|
422
|
+
* parameter, or a whitelisted external executable (git, pnpm, node, …) with
|
|
423
|
+
* all-literal arguments. Unquoted `N>&M` diagnostic stream duplication is
|
|
424
|
+
* stripped. Multi-statements (`;`), pipelines (`|`), the call operator (`&`),
|
|
425
|
+
* script blocks, dot sourcing, .NET/dynamic invocation,
|
|
426
|
+
* variable/expression/subexpression paths, positional paths, and unknown
|
|
427
|
+
* parameters make the WHOLE command unsupported.
|
|
428
|
+
*/
|
|
429
|
+
declare function parsePwshCommand(command: string): ParsedShell;
|
|
430
|
+
//#endregion
|
|
431
|
+
//#region src/domain/stop-policy.d.ts
|
|
432
|
+
type CompletionDisposition = "complete" | "user_wait" | "external_wait" | "report";
|
|
433
|
+
declare function isWholeTaskCompletionClaim(text: string): boolean;
|
|
434
|
+
declare function classifyCompletionClaim(text: string): CompletionDisposition;
|
|
435
|
+
interface TurnStoppingDecision {
|
|
436
|
+
action: "continue" | "stop";
|
|
437
|
+
reason?: string;
|
|
438
|
+
}
|
|
439
|
+
declare function decideTurnStopping(projection: GuardProjection, assistantText: string, turn: number, maxAttempts: number): TurnStoppingDecision;
|
|
440
|
+
declare function latestAssistantText(events: readonly {
|
|
441
|
+
type: string;
|
|
442
|
+
data: unknown;
|
|
443
|
+
}[]): string;
|
|
444
|
+
//#endregion
|
|
445
|
+
//#region src/domain/supersession.d.ts
|
|
446
|
+
declare function supersedeItem(items: Map<string, GuardItem>, oldId: string, replacement: GuardItem): boolean;
|
|
447
|
+
//#endregion
|
|
448
|
+
export { extractOperation as $, hasCurrentCertificate as A, UserInteractionKind as B, isVerifyingCapability as C, sha256 as Ct, OperationVerbEntry as D, ManifestIssue as E, extractTextContent as F, CaptureScope as G, CheckpointResult as H, extractToolSubject as I, captureClause as J, ClassifiedClause as K, isDeterministicCheck as L, ToolResultInput as M, ToolSubject as N, validateManifest as O, evidenceFromPersistedToolResult as P, extractMethod as Q, withDurability as R, evidenceMatchesItem as S, sanitizeUrl as St, CommandSurfaceManifest as T, RejectedBinding as U, classifyUserInteraction as V, certifyCheckpoint as W, classifyClause as X, captureItem as Y, extractArtifactPaths as Z, recoveryDigest as _, createProjection as _t, decideTurnStopping as a, DerivedEnvelope as at, bindingSatisfies as b, normalizeClause as bt, ParsedShell as c, GuardCheckpoint as ct, parsePwshCommand as d, GuardItem as dt, isInformationalMessage as et, parseShellCommand as f, GuardItemKind as ft, openItems as g, VerificationContract as gt, closingHint as h, GuardProjection as ht, classifyCompletionClaim as i, DeriveScope as it, ToolCallInput as j, goalCompletionDenial as k, ShellParseStatus as l, GuardEvidence as lt, RecoveryOptions as m, GuardOperation as mt, CompletionDisposition as n, DeriveConfig as nt, isWholeTaskCompletionClaim as o, EvidenceBinding as ot, DEFAULT_RECOVERY_CHAR_BUDGET as p, GuardItemStatus as pt, ClauseSegment as q, TurnStoppingDecision as r, DeriveResult as rt, latestAssistantText as s, EvidenceOutcome as st, supersedeItem as t, segmentClauses as tt, isRunExecutable as u, GuardIntegrity as ut, renderRecoveryPacket as v, canonicalizePath as vt, COMMAND_SURFACE_MANIFEST as w, evidenceCoverage as x, sanitizeClauseText as xt, EvidenceFacetCoverage as y, digestStrings as yt, deriveProjection as z };
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import { $ as extractOperation, A as hasCurrentCertificate, B as UserInteractionKind, C as isVerifyingCapability, Ct as sha256, D as OperationVerbEntry, E as ManifestIssue, F as extractTextContent, G as CaptureScope, H as CheckpointResult, I as extractToolSubject, J as captureClause, K as ClassifiedClause, L as isDeterministicCheck, M as ToolResultInput, N as ToolSubject, O as validateManifest, P as evidenceFromPersistedToolResult, Q as extractMethod, R as withDurability, S as evidenceMatchesItem, St as sanitizeUrl, T as CommandSurfaceManifest, U as RejectedBinding, V as classifyUserInteraction, W as certifyCheckpoint, X as classifyClause, Y as captureItem, Z as extractArtifactPaths, _ as recoveryDigest, _t as createProjection, a as decideTurnStopping, at as DerivedEnvelope, b as bindingSatisfies, bt as normalizeClause, c as ParsedShell, ct as GuardCheckpoint, d as parsePwshCommand, dt as GuardItem, et as isInformationalMessage, f as parseShellCommand, ft as GuardItemKind, g as openItems, gt as VerificationContract, h as closingHint, ht as GuardProjection, i as classifyCompletionClaim, it as DeriveScope, j as ToolCallInput, k as goalCompletionDenial, l as ShellParseStatus, lt as GuardEvidence, m as RecoveryOptions, mt as GuardOperation, n as CompletionDisposition, nt as DeriveConfig, o as isWholeTaskCompletionClaim, ot as EvidenceBinding, p as DEFAULT_RECOVERY_CHAR_BUDGET, pt as GuardItemStatus, q as ClauseSegment, r as TurnStoppingDecision, rt as DeriveResult, s as latestAssistantText, st as EvidenceOutcome, t as supersedeItem, tt as segmentClauses, u as isRunExecutable, ut as GuardIntegrity, v as renderRecoveryPacket, vt as canonicalizePath, w as COMMAND_SURFACE_MANIFEST, x as evidenceCoverage, xt as sanitizeClauseText, y as EvidenceFacetCoverage, yt as digestStrings, z as deriveProjection } from "./index-Dk4SkQ8H.js";
|
|
2
|
+
import { Context } from "@deepseek-ai/cordis";
|
|
3
|
+
import z from "@deepseek-ai/schemastery";
|
|
4
|
+
|
|
5
|
+
//#region src/config.d.ts
|
|
6
|
+
declare const Config: z<{
|
|
7
|
+
activation: string;
|
|
8
|
+
}>;
|
|
9
|
+
//#endregion
|
|
10
|
+
//#region src/runtime.d.ts
|
|
11
|
+
declare const name = "context-guard";
|
|
12
|
+
declare const inject: readonly ["sessions", "commands"];
|
|
13
|
+
declare function apply(ctx: Context, rawConfig?: {
|
|
14
|
+
activation?: unknown;
|
|
15
|
+
}): void;
|
|
16
|
+
//#endregion
|
|
17
|
+
export { COMMAND_SURFACE_MANIFEST, CaptureScope, CheckpointResult, ClassifiedClause, ClauseSegment, CommandSurfaceManifest, CompletionDisposition, Config, DEFAULT_RECOVERY_CHAR_BUDGET, DeriveConfig, DeriveResult, DeriveScope, DerivedEnvelope, EvidenceBinding, EvidenceFacetCoverage, EvidenceOutcome, GuardCheckpoint, GuardEvidence, GuardIntegrity, GuardItem, GuardItemKind, GuardItemStatus, GuardOperation, GuardProjection, ManifestIssue, OperationVerbEntry, ParsedShell, RecoveryOptions, RejectedBinding, ShellParseStatus, ToolCallInput, ToolResultInput, ToolSubject, TurnStoppingDecision, UserInteractionKind, VerificationContract, apply, bindingSatisfies, canonicalizePath, captureClause, captureItem, certifyCheckpoint, classifyClause, classifyCompletionClaim, classifyUserInteraction, closingHint, createProjection, decideTurnStopping, deriveProjection, digestStrings, evidenceCoverage, evidenceFromPersistedToolResult, evidenceMatchesItem, extractArtifactPaths, extractMethod, extractOperation, extractTextContent, extractToolSubject, goalCompletionDenial, hasCurrentCertificate, inject, isDeterministicCheck, isInformationalMessage, isRunExecutable, isVerifyingCapability, isWholeTaskCompletionClaim, latestAssistantText, name, normalizeClause, openItems, parsePwshCommand, parseShellCommand, recoveryDigest, renderRecoveryPacket, sanitizeClauseText, sanitizeUrl, segmentClauses, sha256, supersedeItem, validateManifest, withDurability };
|