@agent-corpus/policy-manager 0.4.0 → 0.6.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/README.md +95 -10
- package/dist/adapters.d.ts +14 -2
- package/dist/adapters.js +86 -7
- package/dist/audit.js +16 -2
- package/dist/cli.js +27 -3
- package/dist/config.js +11 -3
- package/dist/created.d.ts +44 -0
- package/dist/created.js +236 -0
- package/dist/evidence.d.ts +53 -1
- package/dist/evidence.js +201 -6
- package/dist/flow.d.ts +2 -1
- package/dist/flow.js +856 -76
- package/dist/index.d.ts +3 -2
- package/dist/index.js +3 -2
- package/dist/permissive.d.ts +11 -3
- package/dist/permissive.js +648 -28
- package/dist/policy.d.ts +5 -1
- package/dist/policy.js +132 -30
- package/dist/principle.d.ts +8 -0
- package/dist/principle.js +8 -0
- package/dist/profile.d.ts +8 -0
- package/dist/profile.js +26 -0
- package/dist/recoverable.d.ts +41 -0
- package/dist/recoverable.js +391 -0
- package/dist/redact.d.ts +3 -0
- package/dist/redact.js +140 -0
- package/dist/replay.d.ts +2 -0
- package/dist/replay.js +9 -1
- package/dist/review.d.ts +55 -0
- package/dist/review.js +231 -0
- package/dist/script.d.ts +35 -1
- package/dist/script.js +215 -17
- package/dist/service.d.ts +1 -0
- package/dist/service.js +3 -3
- package/dist/session.d.ts +17 -2
- package/dist/session.js +156 -20
- package/dist/setup.js +3 -1
- package/dist/types.d.ts +21 -3
- package/dist/types.js +12 -1
- package/package.json +2 -2
package/dist/session.d.ts
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
import { type Profile } from "./profile.js";
|
|
2
|
-
import type
|
|
2
|
+
import { type Classification, type Decision, type OutcomeReport, type Request } from "./types.js";
|
|
3
|
+
/** AI approvals per session; beyond this, ambiguous requests go to a human. */
|
|
4
|
+
export declare const MAX_AI_APPROVALS = 50;
|
|
3
5
|
export declare class PolicySession {
|
|
4
6
|
readonly directory: string;
|
|
5
7
|
readonly harness: string;
|
|
@@ -7,8 +9,21 @@ export declare class PolicySession {
|
|
|
7
9
|
readonly profile: Profile;
|
|
8
10
|
private cache;
|
|
9
11
|
private pending;
|
|
12
|
+
private states;
|
|
13
|
+
/** Requests the AI approved, counted once each however often they are retried. */
|
|
14
|
+
private approvedByAi;
|
|
15
|
+
/** Files this session created, and the paths each approved request may create. */
|
|
16
|
+
private created;
|
|
17
|
+
private creating;
|
|
10
18
|
constructor(directory: string, harness: string, sessionId: string, profile?: Profile);
|
|
11
|
-
|
|
19
|
+
private state;
|
|
20
|
+
private remember;
|
|
21
|
+
/**
|
|
22
|
+
* `phase` is the hook event. Only `PreToolUse` runs the classification flow: the first time an
|
|
23
|
+
* ambiguous request arrives it is blocked with an instruction to classify and retry; the next
|
|
24
|
+
* time, with no usable classification, a human is asked and the reason is recorded.
|
|
25
|
+
*/
|
|
26
|
+
review(request: Request, ai?: Classification, phase?: string): Decision;
|
|
12
27
|
record(report: OutcomeReport): void;
|
|
13
28
|
classify(classification: Classification): Decision;
|
|
14
29
|
}
|
package/dist/session.js
CHANGED
|
@@ -1,6 +1,15 @@
|
|
|
1
1
|
import { audit, requestSummary } from "./audit.js";
|
|
2
|
-
import {
|
|
2
|
+
import { creationTargets, pathKey, settle, withCreated, } from "./created.js";
|
|
3
|
+
import { evaluate, hash, requestHash as requestHashOf } from "./policy.js";
|
|
3
4
|
import { strictProfile } from "./profile.js";
|
|
5
|
+
import { redactText } from "./redact.js";
|
|
6
|
+
import { CATEGORIES, } from "./types.js";
|
|
7
|
+
/** How long a classification outcome for one exact request is remembered. */
|
|
8
|
+
const CLASSIFICATION_TTL_MS = 5 * 60_000;
|
|
9
|
+
/** AI approvals per session; beyond this, ambiguous requests go to a human. */
|
|
10
|
+
export const MAX_AI_APPROVALS = 50;
|
|
11
|
+
/** How long after its approval an execution report may still record the files a tool created. */
|
|
12
|
+
const CREATION_REPORT_MS = 15 * 60_000;
|
|
4
13
|
export class PolicySession {
|
|
5
14
|
directory;
|
|
6
15
|
harness;
|
|
@@ -8,50 +17,137 @@ export class PolicySession {
|
|
|
8
17
|
profile;
|
|
9
18
|
cache = new Map();
|
|
10
19
|
pending = new Map();
|
|
20
|
+
states = new Map();
|
|
21
|
+
/** Requests the AI approved, counted once each however often they are retried. */
|
|
22
|
+
approvedByAi = new Set();
|
|
23
|
+
/** Files this session created, and the paths each approved request may create. */
|
|
24
|
+
created = new Map();
|
|
25
|
+
creating = new Map();
|
|
11
26
|
constructor(directory, harness, sessionId, profile = strictProfile) {
|
|
12
27
|
this.directory = directory;
|
|
13
28
|
this.harness = harness;
|
|
14
29
|
this.sessionId = sessionId;
|
|
15
30
|
this.profile = profile;
|
|
16
31
|
}
|
|
17
|
-
|
|
32
|
+
state(requestHash) {
|
|
33
|
+
const state = this.states.get(requestHash);
|
|
34
|
+
if (state && state.expires <= Date.now()) {
|
|
35
|
+
this.states.delete(requestHash);
|
|
36
|
+
return undefined;
|
|
37
|
+
}
|
|
38
|
+
return state;
|
|
39
|
+
}
|
|
40
|
+
remember(requestHash, change) {
|
|
41
|
+
if (this.states.size >= 512)
|
|
42
|
+
this.states.clear();
|
|
43
|
+
this.states.set(requestHash, {
|
|
44
|
+
requested: false,
|
|
45
|
+
invalid: false,
|
|
46
|
+
fallback: false,
|
|
47
|
+
limited: false,
|
|
48
|
+
...this.states.get(requestHash),
|
|
49
|
+
...change,
|
|
50
|
+
expires: Date.now() + CLASSIFICATION_TTL_MS,
|
|
51
|
+
});
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* `phase` is the hook event. Only `PreToolUse` runs the classification flow: the first time an
|
|
55
|
+
* ambiguous request arrives it is blocked with an instruction to classify and retry; the next
|
|
56
|
+
* time, with no usable classification, a human is asked and the reason is recorded.
|
|
57
|
+
*/
|
|
58
|
+
review(request, ai, phase) {
|
|
18
59
|
if (request.sessionId !== this.sessionId || request.harness !== this.harness)
|
|
19
60
|
throw new Error("Session mismatch");
|
|
20
61
|
audit(this.directory, { event: "request", ...requestSummary(request) });
|
|
21
62
|
if (ai &&
|
|
22
|
-
(!
|
|
23
|
-
"code-read",
|
|
24
|
-
"worktree-write",
|
|
25
|
-
"cloud-read",
|
|
26
|
-
"git-read",
|
|
27
|
-
"impactful-write",
|
|
28
|
-
"destructive",
|
|
29
|
-
"sensitive",
|
|
30
|
-
"unknown",
|
|
31
|
-
].includes(ai.category) ||
|
|
63
|
+
(!CATEGORIES.includes(ai.category) ||
|
|
32
64
|
typeof ai.confidence !== "number" ||
|
|
33
65
|
!Number.isFinite(ai.confidence) ||
|
|
66
|
+
(ai.recoverable !== undefined && typeof ai.recoverable !== "boolean") ||
|
|
67
|
+
(ai.rationale !== undefined && typeof ai.rationale !== "string") ||
|
|
34
68
|
!/^[a-f0-9]{64}$/.test(ai.requestHash))) {
|
|
35
69
|
audit(this.directory, {
|
|
36
70
|
event: "decision",
|
|
37
71
|
decision: "human",
|
|
38
72
|
category: "unknown",
|
|
39
73
|
reason: "Malformed AI classification",
|
|
40
|
-
requestHash:
|
|
74
|
+
requestHash: requestHashOf(request),
|
|
41
75
|
});
|
|
42
76
|
throw new Error("Malformed AI classification");
|
|
43
77
|
}
|
|
44
|
-
const key = hash([
|
|
78
|
+
const key = hash([
|
|
79
|
+
requestHashOf(request),
|
|
80
|
+
"policy-v1",
|
|
81
|
+
this.profile.digest ?? this.profile.mode,
|
|
82
|
+
]);
|
|
45
83
|
const entry = this.cache.get(key);
|
|
46
84
|
const cachedAi = entry && entry.expires > Date.now() ? entry.ai : undefined;
|
|
85
|
+
const requestHash = requestHashOf(request);
|
|
86
|
+
const known = ai ? undefined : this.state(requestHash);
|
|
47
87
|
if (ai)
|
|
48
88
|
audit(this.directory, {
|
|
49
89
|
event: "classification",
|
|
50
|
-
requestHash
|
|
90
|
+
requestHash,
|
|
51
91
|
category: ai.category,
|
|
52
92
|
confidence: ai.confidence,
|
|
93
|
+
...(ai.recoverable === undefined ? {} : { recoverable: ai.recoverable }),
|
|
94
|
+
...(ai.rationale ? { rationale: redactText(ai.rationale, 200) } : {}),
|
|
53
95
|
});
|
|
54
|
-
|
|
96
|
+
let decision = withCreated(this.created, () => evaluate(request, ai ?? cachedAi ?? known?.ai, this.profile));
|
|
97
|
+
if (decision.tier === "ambiguous") {
|
|
98
|
+
if (ai && !decision.classification)
|
|
99
|
+
this.remember(requestHash, { invalid: true });
|
|
100
|
+
else if (ai) {
|
|
101
|
+
// The cap is checked when the approval is first given and stored with the outcome, so a
|
|
102
|
+
// retry cannot turn a limited request into an approval.
|
|
103
|
+
if (decision.classification === "approved" &&
|
|
104
|
+
!this.approvedByAi.has(requestHash) &&
|
|
105
|
+
this.approvedByAi.size >= MAX_AI_APPROVALS) {
|
|
106
|
+
decision = {
|
|
107
|
+
...decision,
|
|
108
|
+
decision: "human",
|
|
109
|
+
classification: "fallback",
|
|
110
|
+
fallbackReason: "limit",
|
|
111
|
+
reason: "Session limit on AI approvals reached; a human decides",
|
|
112
|
+
};
|
|
113
|
+
this.remember(requestHash, { limited: true });
|
|
114
|
+
}
|
|
115
|
+
else {
|
|
116
|
+
if (decision.classification === "approved")
|
|
117
|
+
this.approvedByAi.add(requestHash);
|
|
118
|
+
this.remember(requestHash, { ai });
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
if (decision.needsClassification && !ai && phase === "PreToolUse") {
|
|
122
|
+
if (!known?.requested) {
|
|
123
|
+
this.remember(requestHash, { requested: true });
|
|
124
|
+
audit(this.directory, {
|
|
125
|
+
event: "classification-requested",
|
|
126
|
+
requestHash,
|
|
127
|
+
tier: "ambiguous",
|
|
128
|
+
reason: decision.reason,
|
|
129
|
+
redactedCommand: redactText(String(request.input.command ?? request.input.cmd ?? request.tool), 300),
|
|
130
|
+
});
|
|
131
|
+
decision = { ...decision, decision: "deny", classification: "requested" };
|
|
132
|
+
}
|
|
133
|
+
else {
|
|
134
|
+
const fallbackReason = known.limited
|
|
135
|
+
? "limit"
|
|
136
|
+
: known.invalid
|
|
137
|
+
? "invalid-result"
|
|
138
|
+
: "unavailable";
|
|
139
|
+
if (!known.fallback) {
|
|
140
|
+
this.remember(requestHash, { fallback: true });
|
|
141
|
+
audit(this.directory, {
|
|
142
|
+
event: "classification-fallback",
|
|
143
|
+
requestHash,
|
|
144
|
+
fallbackReason,
|
|
145
|
+
});
|
|
146
|
+
}
|
|
147
|
+
decision = { ...decision, classification: "fallback", fallbackReason };
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
}
|
|
55
151
|
if (decision.decision === "human")
|
|
56
152
|
this.cache.delete(key);
|
|
57
153
|
// Evaluation always precedes lookup. Filesystem evidence is never cached.
|
|
@@ -66,13 +162,26 @@ export class PolicySession {
|
|
|
66
162
|
});
|
|
67
163
|
}
|
|
68
164
|
}
|
|
69
|
-
|
|
70
|
-
|
|
165
|
+
// A denied request is final for its remembered state: only a human decision or a request
|
|
166
|
+
// still waiting for its first classification can be classified.
|
|
167
|
+
if ((decision.decision === "human" || decision.classification === "requested") &&
|
|
168
|
+
(["unknown", "cloud-read"].includes(decision.category) || decision.needsClassification) &&
|
|
71
169
|
!ai) {
|
|
72
170
|
if (this.pending.size >= 64)
|
|
73
171
|
this.pending.delete(this.pending.keys().next().value ?? "");
|
|
74
172
|
this.pending.set(decision.requestHash, request);
|
|
75
173
|
}
|
|
174
|
+
// Every decision replaces the pending creations for this request, so a report can only ever
|
|
175
|
+
// settle the most recent approval: an earlier approval whose report never came is forgotten.
|
|
176
|
+
this.creating.delete(decision.requestHash);
|
|
177
|
+
if (decision.decision === "approve") {
|
|
178
|
+
const targets = creationTargets(request, this.created);
|
|
179
|
+
if (targets.length) {
|
|
180
|
+
if (this.creating.size >= 256)
|
|
181
|
+
this.creating.delete(this.creating.keys().next().value ?? "");
|
|
182
|
+
this.creating.set(decision.requestHash, { targets, approvedAt: Date.now() });
|
|
183
|
+
}
|
|
184
|
+
}
|
|
76
185
|
const { ai: classification, ...safe } = decision;
|
|
77
186
|
audit(this.directory, {
|
|
78
187
|
event: "decision",
|
|
@@ -103,7 +212,7 @@ export class PolicySession {
|
|
|
103
212
|
});
|
|
104
213
|
}
|
|
105
214
|
else if (report.event === "execution-result") {
|
|
106
|
-
if (!["completed", "succeeded", "failed", "cancelled"].includes(report.status ?? ""))
|
|
215
|
+
if (!["completed", "succeeded", "failed", "cancelled", "unknown"].includes(report.status ?? ""))
|
|
107
216
|
throw new Error("Invalid execution status");
|
|
108
217
|
if (report.exitCode !== undefined &&
|
|
109
218
|
(!Number.isSafeInteger(report.exitCode) || Math.abs(report.exitCode) > 2147483647))
|
|
@@ -119,6 +228,22 @@ export class PolicySession {
|
|
|
119
228
|
...(report.durationMs === undefined ? {} : { durationMs: report.durationMs }),
|
|
120
229
|
summary: "Harness-reported execution result",
|
|
121
230
|
});
|
|
231
|
+
// A target is the session's only if `settle` proves the file there is its own inode or a new
|
|
232
|
+
// one born after the approval; otherwise any earlier claim on the path is dropped.
|
|
233
|
+
// A report that comes too long after its approval records nothing.
|
|
234
|
+
const pending = this.creating.get(report.requestHash);
|
|
235
|
+
const fresh = pending && Date.now() - pending.approvedAt <= CREATION_REPORT_MS ? pending : undefined;
|
|
236
|
+
for (const target of fresh?.targets ?? []) {
|
|
237
|
+
const now = settle(target, fresh?.approvedAt ?? Number.POSITIVE_INFINITY);
|
|
238
|
+
if (!now)
|
|
239
|
+
this.created.delete(pathKey(target.path));
|
|
240
|
+
else {
|
|
241
|
+
if (this.created.size >= 4096)
|
|
242
|
+
this.created.clear();
|
|
243
|
+
this.created.set(pathKey(target.path), now);
|
|
244
|
+
}
|
|
245
|
+
}
|
|
246
|
+
this.creating.delete(report.requestHash);
|
|
122
247
|
}
|
|
123
248
|
else
|
|
124
249
|
throw new Error("Invalid outcome event");
|
|
@@ -127,8 +252,19 @@ export class PolicySession {
|
|
|
127
252
|
const request = this.pending.get(classification.requestHash);
|
|
128
253
|
if (!request)
|
|
129
254
|
throw new Error("No pending request matches the classification");
|
|
255
|
+
// One classification per request: a verdict, deny or approve, cannot be replaced.
|
|
256
|
+
if (this.state(classification.requestHash)?.ai)
|
|
257
|
+
throw new Error("The request is already classified");
|
|
130
258
|
this.pending.delete(classification.requestHash);
|
|
131
|
-
|
|
259
|
+
try {
|
|
260
|
+
return this.review(request, classification);
|
|
261
|
+
}
|
|
262
|
+
catch (error) {
|
|
263
|
+
// A malformed result is not an approval; the retry will fall back to a human, with the
|
|
264
|
+
// reason recorded for the review.
|
|
265
|
+
this.remember(classification.requestHash, { invalid: true });
|
|
266
|
+
throw error;
|
|
267
|
+
}
|
|
132
268
|
}
|
|
133
269
|
}
|
|
134
270
|
//# sourceMappingURL=session.js.map
|
package/dist/setup.js
CHANGED
|
@@ -127,7 +127,9 @@ export function setupHook(harness, cliPath, options = {}) {
|
|
|
127
127
|
"Start a new harness session to load the hooks.",
|
|
128
128
|
...(harness === "codex"
|
|
129
129
|
? [
|
|
130
|
-
"Open /hooks and explicitly review and trust the installed hooks. Setup does not grant hook trust.",
|
|
130
|
+
"Open /hooks and explicitly review and trust the installed hooks. Setup does not grant hook trust, and Codex skips hooks it has not trusted.",
|
|
131
|
+
"Codex trusts the command text, not the code behind it: an upgrade at the same CLI path keeps trust, so review a new version before upgrading in place. A changed command (a new install path or Node binary) is skipped until you trust it again.",
|
|
132
|
+
"Codex does not support ask in PreToolUse, so a decision that needs a human is returned as a deny and the command does not run; approving it in chat does not unblock it.",
|
|
131
133
|
]
|
|
132
134
|
: []),
|
|
133
135
|
"Native sandbox controls and existing permission rules remain in effect.",
|
package/dist/types.d.ts
CHANGED
|
@@ -1,4 +1,7 @@
|
|
|
1
|
-
export
|
|
1
|
+
export declare const CATEGORIES: readonly ["code-read", "worktree-write",
|
|
2
|
+
/** A recoverable write outside any repository, such as the system temp directory. */
|
|
3
|
+
"temp-write", "cloud-read", "git-read", "impactful-write", "destructive", "sensitive", "unknown"];
|
|
4
|
+
export type Category = (typeof CATEGORIES)[number];
|
|
2
5
|
export interface Request {
|
|
3
6
|
sessionId: string;
|
|
4
7
|
harness: "claude" | "codex" | "copilot";
|
|
@@ -10,22 +13,37 @@ export interface Classification {
|
|
|
10
13
|
category: Category;
|
|
11
14
|
confidence: number;
|
|
12
15
|
requestHash: string;
|
|
16
|
+
/** Whether the action can be undone (merged work, tracked files, anything a backup restores). */
|
|
17
|
+
recoverable?: boolean;
|
|
18
|
+
/** Short free-text reason from the classifier; capped and redacted before it is logged. */
|
|
19
|
+
rationale?: string;
|
|
13
20
|
}
|
|
21
|
+
/** Where an ambiguous request stands in the AI classification flow. */
|
|
22
|
+
export type ClassificationStage = "requested" | "approved" | "denied" | "fallback";
|
|
14
23
|
export interface Decision {
|
|
15
|
-
|
|
24
|
+
/**
|
|
25
|
+
* `deny` is a decision the model sees and works around; `human` asks the person; `native` makes
|
|
26
|
+
* no decision and leaves the request to the harness's own permission flow.
|
|
27
|
+
*/
|
|
28
|
+
decision: "approve" | "human" | "deny" | "native";
|
|
16
29
|
category: Category;
|
|
17
30
|
reason: string;
|
|
18
31
|
requestHash: string;
|
|
19
32
|
cache: "none" | "session";
|
|
20
33
|
cached: boolean;
|
|
21
34
|
needsClassification?: boolean;
|
|
35
|
+
/** `ambiguous`: the deterministic engine could not decide and nothing in code forbids it. */
|
|
36
|
+
tier?: "ambiguous";
|
|
37
|
+
classification?: ClassificationStage;
|
|
38
|
+
/** Why a human was asked after classification could not decide. */
|
|
39
|
+
fallbackReason?: "unavailable" | "invalid-result" | "limit";
|
|
22
40
|
ai?: Classification;
|
|
23
41
|
}
|
|
24
42
|
export interface OutcomeReport {
|
|
25
43
|
requestHash: string;
|
|
26
44
|
event: "human-response" | "execution-result";
|
|
27
45
|
response?: "approved" | "denied";
|
|
28
|
-
status?: "completed" | "succeeded" | "failed" | "cancelled";
|
|
46
|
+
status?: "completed" | "succeeded" | "failed" | "cancelled" | "unknown";
|
|
29
47
|
exitCode?: number;
|
|
30
48
|
durationMs?: number;
|
|
31
49
|
}
|
package/dist/types.js
CHANGED
|
@@ -1,2 +1,13 @@
|
|
|
1
|
-
export
|
|
1
|
+
export const CATEGORIES = [
|
|
2
|
+
"code-read",
|
|
3
|
+
"worktree-write",
|
|
4
|
+
/** A recoverable write outside any repository, such as the system temp directory. */
|
|
5
|
+
"temp-write",
|
|
6
|
+
"cloud-read",
|
|
7
|
+
"git-read",
|
|
8
|
+
"impactful-write",
|
|
9
|
+
"destructive",
|
|
10
|
+
"sensitive",
|
|
11
|
+
"unknown",
|
|
12
|
+
];
|
|
2
13
|
//# sourceMappingURL=types.js.map
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@agent-corpus/policy-manager",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.6.0",
|
|
4
4
|
"description": "Deterministic, session-scoped permission decisions with audit logs and bounded AI classification.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"coding-agent",
|
|
@@ -50,6 +50,6 @@
|
|
|
50
50
|
"postpack": "node -e \"require('fs').rmSync('LICENSE',{force:true})\""
|
|
51
51
|
},
|
|
52
52
|
"dependencies": {
|
|
53
|
-
"@agent-corpus/audit-log": "^0.1.
|
|
53
|
+
"@agent-corpus/audit-log": "^0.1.1"
|
|
54
54
|
}
|
|
55
55
|
}
|