@fro.bot/systematic 3.31.6 → 3.32.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/HARNESSES.md +18 -0
- package/README.md +1 -1
- package/agents/research/connections-researcher.md +101 -0
- package/dist/ce-connect-helper.d.ts +76 -0
- package/dist/cli.js +1 -1
- package/dist/{index-c95n6n53.js → index-nrbdgp4m.js} +277 -228
- package/dist/index.js +68 -3
- package/dist/lib/bundled-names.d.ts +3 -3
- package/dist/lib/config-protected-fields.d.ts +1 -1
- package/dist/lib/config-schema.d.ts +6 -0
- package/dist/lib/config.d.ts +10 -0
- package/dist/lib/connect-config.d.ts +197 -0
- package/dist/lib/connect-evidence.d.ts +312 -0
- package/dist/lib/connect-helper-core.d.ts +399 -0
- package/dist/lib/connect-state.d.ts +427 -0
- package/dist/lib/opencode-v2-tool-guard.d.ts +40 -0
- package/dist/lib/opencode-v2.d.ts +3 -1
- package/dist/lib/pi-subagents-personas.d.ts +1 -0
- package/dist/lib/validation.d.ts +1 -0
- package/dist/pi.js +53 -6
- package/package.json +3 -1
- package/skills/ce-compound/SKILL.md +39 -2
- package/skills/ce-compound/references/candidate-input.md +91 -0
- package/skills/ce-compound-refresh/SKILL.md +48 -2
- package/skills/ce-connect/SKILL.md +201 -0
- package/skills/ce-connect/references/candidate-contract.md +97 -0
- package/skills/ce-connect/references/headless-and-outcomes.md +86 -0
- package/skills/ce-connect/scripts/connect.mjs +9739 -0
|
@@ -0,0 +1,427 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Run state for `ce:connect`: the state root, the lock, published runs, the
|
|
3
|
+
* ledger and the prune. It answers three questions: may two runs overlap, what
|
|
4
|
+
* did a run publish, and has a candidate already been proposed or decided.
|
|
5
|
+
*
|
|
6
|
+
* Import rule: node builtins, `connect-config.ts` and `connect-evidence.ts`
|
|
7
|
+
* only. The `ce:connect` helper bundles this module, so it must never import
|
|
8
|
+
* zod, `config.ts` or `config-schema.ts`.
|
|
9
|
+
*
|
|
10
|
+
* Layout under the state root (directories 0700, files 0600):
|
|
11
|
+
*
|
|
12
|
+
* lock/holder.json the held lock: pid, process start time, nonce
|
|
13
|
+
* runs/<id>/ a published run
|
|
14
|
+
* runs/<id>.tmp/ a run being staged
|
|
15
|
+
* ledger.json the ledger
|
|
16
|
+
*
|
|
17
|
+
* Staging and publishing: a run is built in `runs/<id>.tmp/` and the rename to
|
|
18
|
+
* `runs/<id>/` is the commit. The ledger is rewritten after it, with a
|
|
19
|
+
* temporary file and a rename. A crash between the two leaves a committed run
|
|
20
|
+
* whose candidates are missing from the ledger, so the next run proposes them
|
|
21
|
+
* once more. Leftover `.tmp` directories are removed by the prune.
|
|
22
|
+
*
|
|
23
|
+
* The lock is a directory made with `mkdir`, which is atomic. The holder file
|
|
24
|
+
* is written under a temporary name and renamed into place. A lock is stale
|
|
25
|
+
* when its holder is dead, or when the pid is alive with a different start
|
|
26
|
+
* time (the pid was reused). A start time that cannot be read means busy,
|
|
27
|
+
* never stale. To reclaim, the stale directory is renamed to a unique name and
|
|
28
|
+
* the moved holder's nonce must equal the one that was judged stale; a
|
|
29
|
+
* mismatch means a live lock was moved, so it is put back and the caller is
|
|
30
|
+
* busy. A lock with no readable holder is reclaimable after ten minutes.
|
|
31
|
+
*
|
|
32
|
+
* The ledger is minimal: identities, source paths, fingerprints, status and a
|
|
33
|
+
* reason. It holds no excerpt and is never evidence. Its writers copy named
|
|
34
|
+
* fields only, so extra fields on a candidate never reach the file.
|
|
35
|
+
*/
|
|
36
|
+
import { type ContainerRefusal } from './connect-config.js';
|
|
37
|
+
/** A lock directory with no usable holder is reclaimable after this long. */
|
|
38
|
+
export declare const HOLDERLESS_LOCK_MAX_AGE_MS: number;
|
|
39
|
+
/** A published run directory is pruned once it is older than this. */
|
|
40
|
+
export declare const RUN_RETENTION_MS: number;
|
|
41
|
+
export type StateRootRefusal = ContainerRefusal
|
|
42
|
+
/** The root, or the runs directory, is a symlink. */
|
|
43
|
+
| 'symlink' | 'not-directory'
|
|
44
|
+
/** Another user owns the directory. */
|
|
45
|
+
| 'foreign-owner' | 'unwritable';
|
|
46
|
+
export type StateRootResult = {
|
|
47
|
+
readonly status: 'ok';
|
|
48
|
+
readonly root: string;
|
|
49
|
+
/** An existing root had loose permissions and was set to 0700. */
|
|
50
|
+
readonly tightened: boolean;
|
|
51
|
+
} | {
|
|
52
|
+
readonly status: 'refused';
|
|
53
|
+
readonly reason: StateRootRefusal;
|
|
54
|
+
};
|
|
55
|
+
export interface StateRootOptions {
|
|
56
|
+
/** Main roots of the allowed projects. State may not live in one. */
|
|
57
|
+
readonly allowedRoots: readonly string[];
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* Check and create the state root. A root that sits in a checkout, in an
|
|
61
|
+
* allowed project, or that is (or has a `runs` directory that is) a symlink is
|
|
62
|
+
* refused; a looser existing root is tightened to 0700. Never throws.
|
|
63
|
+
*/
|
|
64
|
+
export declare function prepareStateRoot(root: string, options: StateRootOptions): StateRootResult;
|
|
65
|
+
/**
|
|
66
|
+
* What the lock needs to know about other processes. It is a seam so tests can
|
|
67
|
+
* script a process table.
|
|
68
|
+
*/
|
|
69
|
+
export interface ProcessTable {
|
|
70
|
+
/** Whether a process with this pid exists. */
|
|
71
|
+
isAlive(pid: number): boolean;
|
|
72
|
+
/** An opaque value that is stable for the life of one process, or undefined when unknown. */
|
|
73
|
+
startTime(pid: number): string | undefined;
|
|
74
|
+
}
|
|
75
|
+
/**
|
|
76
|
+
* The start time field of a Linux `/proc/<pid>/stat` line (field 22). The
|
|
77
|
+
* command name is parenthesised and may itself hold parentheses, so the fields
|
|
78
|
+
* are counted from the last `)`.
|
|
79
|
+
*/
|
|
80
|
+
export declare function parseLinuxStartTime(stat: string): string | undefined;
|
|
81
|
+
/**
|
|
82
|
+
* The start time of a process: `ps -o lstart=` through argv, no shell, on
|
|
83
|
+
* macOS; `/proc/<pid>/stat` on Linux. Undefined for a dead process, an invalid
|
|
84
|
+
* pid, an unsupported platform or any read failure.
|
|
85
|
+
*/
|
|
86
|
+
export declare function processStartTime(pid: number): string | undefined;
|
|
87
|
+
export declare const systemProcessTable: ProcessTable;
|
|
88
|
+
export interface LockHooks {
|
|
89
|
+
/** Runs after a reclaimer has judged a lock stale and before it moves it. A test seam for races. */
|
|
90
|
+
readonly afterObserve?: () => void;
|
|
91
|
+
}
|
|
92
|
+
export interface LockOptions {
|
|
93
|
+
/** The pid recorded as the holder. Defaults to this process. */
|
|
94
|
+
readonly pid?: number;
|
|
95
|
+
readonly processes?: ProcessTable;
|
|
96
|
+
/** Milliseconds since the epoch. Defaults to `Date.now`. */
|
|
97
|
+
readonly now?: () => number;
|
|
98
|
+
readonly hooks?: LockHooks;
|
|
99
|
+
}
|
|
100
|
+
/** Proof of a held lock. Pass it to the operations that need the lock. */
|
|
101
|
+
export interface LockHandle {
|
|
102
|
+
readonly root: string;
|
|
103
|
+
readonly nonce: string;
|
|
104
|
+
readonly pid: number;
|
|
105
|
+
}
|
|
106
|
+
export type LockBusyReason =
|
|
107
|
+
/** The holder is alive and its start time matches. */
|
|
108
|
+
'held'
|
|
109
|
+
/** The holder is alive but its start time cannot be compared. */
|
|
110
|
+
| 'holder-unverifiable'
|
|
111
|
+
/** The lock has no usable holder and is less than ten minutes old. */
|
|
112
|
+
| 'holderless-recent'
|
|
113
|
+
/** Another process changed the lock while it was being reclaimed. */
|
|
114
|
+
| 'reclaim-contended';
|
|
115
|
+
export type LockReclaimReason = 'holder-dead' | 'pid-reused' | 'holderless-expired';
|
|
116
|
+
/** What was reclaimed. The caller records it in the run record. */
|
|
117
|
+
export interface LockReclaim {
|
|
118
|
+
readonly reason: LockReclaimReason;
|
|
119
|
+
readonly previousPid?: number;
|
|
120
|
+
readonly previousNonce?: string;
|
|
121
|
+
}
|
|
122
|
+
export type LockResult = {
|
|
123
|
+
readonly status: 'acquired';
|
|
124
|
+
readonly lock: LockHandle;
|
|
125
|
+
readonly reclaimed?: LockReclaim;
|
|
126
|
+
} | {
|
|
127
|
+
readonly status: 'busy';
|
|
128
|
+
readonly reason: LockBusyReason;
|
|
129
|
+
} | {
|
|
130
|
+
readonly status: 'failed';
|
|
131
|
+
readonly reason: 'not-a-directory' | 'unwritable';
|
|
132
|
+
};
|
|
133
|
+
/**
|
|
134
|
+
* Take the lock, reclaiming it when its holder is verifiably gone. Never
|
|
135
|
+
* throws. A busy result carries no handle, so a busy run cannot publish,
|
|
136
|
+
* prune or decide.
|
|
137
|
+
*/
|
|
138
|
+
export declare function acquireLock(root: string, options?: LockOptions): LockResult;
|
|
139
|
+
/**
|
|
140
|
+
* Release a lock this handle holds. A lock whose holder file carries another
|
|
141
|
+
* nonce belongs to someone else and is left alone (`lost`). Never throws.
|
|
142
|
+
*/
|
|
143
|
+
export declare function releaseLock(handle: LockHandle): 'released' | 'lost' | 'failed';
|
|
144
|
+
export type UnlockResult = {
|
|
145
|
+
readonly status: 'unlocked';
|
|
146
|
+
readonly holder?: {
|
|
147
|
+
readonly pid: number;
|
|
148
|
+
readonly nonce: string;
|
|
149
|
+
};
|
|
150
|
+
} | {
|
|
151
|
+
readonly status: 'no-lock';
|
|
152
|
+
} | {
|
|
153
|
+
readonly status: 'failed';
|
|
154
|
+
readonly reason: 'unwritable';
|
|
155
|
+
};
|
|
156
|
+
/**
|
|
157
|
+
* Remove the lock whoever holds it: the manual escape for a lock the
|
|
158
|
+
* verification rules will not reclaim. Anything at the lock path goes, a
|
|
159
|
+
* symlink included, and nothing behind a symlink is touched. Never throws.
|
|
160
|
+
*/
|
|
161
|
+
export declare function forceUnlock(root: string): UnlockResult;
|
|
162
|
+
/** A sortable, unique run id: a UTC timestamp and eight hex characters. */
|
|
163
|
+
export declare function newRunId(now?: number): string;
|
|
164
|
+
/** A source file a candidate rests on. An undefined fingerprint means the file is missing. */
|
|
165
|
+
export interface SourceRef {
|
|
166
|
+
readonly role: string;
|
|
167
|
+
readonly path: string;
|
|
168
|
+
readonly fingerprint: string | undefined;
|
|
169
|
+
}
|
|
170
|
+
/** A file in the target project the candidate cites. */
|
|
171
|
+
export interface TargetEvidenceRef {
|
|
172
|
+
readonly path: string;
|
|
173
|
+
readonly fingerprint: string;
|
|
174
|
+
}
|
|
175
|
+
export interface CandidateRecord {
|
|
176
|
+
readonly kind: string;
|
|
177
|
+
/** The target project's main-root identity. */
|
|
178
|
+
readonly target: string;
|
|
179
|
+
/** The rule id the helper's index issued. */
|
|
180
|
+
readonly ruleId: string;
|
|
181
|
+
readonly sources: readonly SourceRef[];
|
|
182
|
+
readonly targetEvidence: readonly TargetEvidenceRef[];
|
|
183
|
+
}
|
|
184
|
+
/**
|
|
185
|
+
* The identity of a candidate: kind, target, rule id and the normalized
|
|
186
|
+
* (role, path) of each source. Fingerprints and target evidence are not part
|
|
187
|
+
* of it, so a changed file reopens the same entry instead of making a new one.
|
|
188
|
+
*/
|
|
189
|
+
export declare function candidateIdentity(candidate: CandidateRecord): string;
|
|
190
|
+
export type LedgerStatus = 'candidate' | 'promoted' | 'rejected';
|
|
191
|
+
export type ReopenReason = 'sources changed' | 'target changed';
|
|
192
|
+
export interface LedgerSource {
|
|
193
|
+
readonly role: string;
|
|
194
|
+
readonly path: string;
|
|
195
|
+
readonly fingerprint: string;
|
|
196
|
+
}
|
|
197
|
+
/** The state an entry had before it was reopened. */
|
|
198
|
+
export interface LedgerHistoryItem {
|
|
199
|
+
readonly status: LedgerStatus;
|
|
200
|
+
readonly reason?: string;
|
|
201
|
+
readonly destination?: string;
|
|
202
|
+
readonly reopened?: ReopenReason;
|
|
203
|
+
readonly sources: readonly LedgerSource[];
|
|
204
|
+
readonly targetEvidence: readonly TargetEvidenceRef[];
|
|
205
|
+
readonly recordedAt: string;
|
|
206
|
+
}
|
|
207
|
+
export interface LedgerEntry {
|
|
208
|
+
readonly id: string;
|
|
209
|
+
readonly kind: string;
|
|
210
|
+
readonly target: string;
|
|
211
|
+
readonly ruleId: string;
|
|
212
|
+
readonly sources: readonly LedgerSource[];
|
|
213
|
+
readonly targetEvidence: readonly TargetEvidenceRef[];
|
|
214
|
+
readonly status: LedgerStatus;
|
|
215
|
+
readonly reason?: string;
|
|
216
|
+
readonly destination?: string;
|
|
217
|
+
readonly reopened?: ReopenReason;
|
|
218
|
+
readonly history: readonly LedgerHistoryItem[];
|
|
219
|
+
readonly recordedAt: string;
|
|
220
|
+
}
|
|
221
|
+
/**
|
|
222
|
+
* That a rule was covered by a committed run: the rule id, the hash of the
|
|
223
|
+
* learning as it was then, and the run. It holds no text. A rule whose current
|
|
224
|
+
* hash differs is not covered.
|
|
225
|
+
*/
|
|
226
|
+
export interface CoverageRecord {
|
|
227
|
+
readonly ruleId: string;
|
|
228
|
+
readonly hash: string;
|
|
229
|
+
readonly runId: string;
|
|
230
|
+
/** ISO time of the commit. */
|
|
231
|
+
readonly at: string;
|
|
232
|
+
/**
|
|
233
|
+
* The key of the project the rule belongs to. A rule id is a hash of the
|
|
234
|
+
* project root and the path, so this is the only way to tell later whose
|
|
235
|
+
* rule a record is. Absent on a record written before it was kept.
|
|
236
|
+
*/
|
|
237
|
+
readonly project?: string;
|
|
238
|
+
}
|
|
239
|
+
export interface Ledger {
|
|
240
|
+
readonly version: 1;
|
|
241
|
+
readonly entries: readonly LedgerEntry[];
|
|
242
|
+
/** Absent when no committed run has covered a rule. */
|
|
243
|
+
readonly coverage?: readonly CoverageRecord[];
|
|
244
|
+
}
|
|
245
|
+
export type LedgerRead = {
|
|
246
|
+
readonly status: 'ok';
|
|
247
|
+
readonly ledger: Ledger;
|
|
248
|
+
} | {
|
|
249
|
+
readonly status: 'unreadable';
|
|
250
|
+
readonly reason: 'invalid' | 'too-large' | 'unreadable';
|
|
251
|
+
};
|
|
252
|
+
/**
|
|
253
|
+
* Read the ledger. A missing file is an empty ledger. A file that is corrupt,
|
|
254
|
+
* oversize or not a regular file is unreadable and is never replaced by an
|
|
255
|
+
* empty one, so a bad file cannot silently drop history. This is `ledger show`.
|
|
256
|
+
*/
|
|
257
|
+
export declare function readLedger(root: string): LedgerRead;
|
|
258
|
+
/** What the ledger says about one candidate. */
|
|
259
|
+
export type CandidateStanding = {
|
|
260
|
+
readonly standing: 'new';
|
|
261
|
+
readonly id: string;
|
|
262
|
+
/** Other entries for the same kind, target and rule whose source content matches under another path. A human decides. */
|
|
263
|
+
readonly possibleMatches: readonly string[];
|
|
264
|
+
} | {
|
|
265
|
+
readonly standing: 'suppressed';
|
|
266
|
+
readonly id: string;
|
|
267
|
+
readonly priorStatus: LedgerStatus;
|
|
268
|
+
} | {
|
|
269
|
+
readonly standing: 'reopened';
|
|
270
|
+
readonly id: string;
|
|
271
|
+
readonly reason: ReopenReason;
|
|
272
|
+
readonly priorStatus: LedgerStatus;
|
|
273
|
+
/** Where the promoted learning lives, when a promoted entry's sources changed. */
|
|
274
|
+
readonly refreshPointer?: string;
|
|
275
|
+
} | {
|
|
276
|
+
readonly standing: 'unresolved';
|
|
277
|
+
readonly id: string;
|
|
278
|
+
readonly missing: readonly string[];
|
|
279
|
+
};
|
|
280
|
+
/**
|
|
281
|
+
* Decide what the ledger says about a candidate, without writing:
|
|
282
|
+
*
|
|
283
|
+
* - a missing source is `unresolved`, never `changed`;
|
|
284
|
+
* - no prior entry is `new`;
|
|
285
|
+
* - unchanged source and target fingerprints are `suppressed`, whatever the
|
|
286
|
+
* prior status;
|
|
287
|
+
* - a changed source fingerprint is `reopened` as "sources changed" (with a
|
|
288
|
+
* refresh pointer when the prior entry was promoted);
|
|
289
|
+
* - otherwise a changed target fingerprint is `reopened` as "target changed".
|
|
290
|
+
*/
|
|
291
|
+
export declare function classifyCandidate(ledger: Ledger, candidate: CandidateRecord): CandidateStanding;
|
|
292
|
+
/**
|
|
293
|
+
* What a committed run covered. The ledger keeps coverage for the rules in
|
|
294
|
+
* `indexed` only, so a rule whose learning is gone is dropped, and records
|
|
295
|
+
* `covered` rules at the hash `indexed` gives them.
|
|
296
|
+
*/
|
|
297
|
+
export interface CoverageUpdate {
|
|
298
|
+
readonly runId: string;
|
|
299
|
+
/** Every rule the run indexed, with the hash of its learning and its project's key. */
|
|
300
|
+
readonly indexed: ReadonlyArray<{
|
|
301
|
+
readonly ruleId: string;
|
|
302
|
+
readonly hash: string;
|
|
303
|
+
readonly project?: string;
|
|
304
|
+
}>;
|
|
305
|
+
/** Rule ids, each in `indexed`, that a complete family covered. */
|
|
306
|
+
readonly covered: readonly string[];
|
|
307
|
+
/**
|
|
308
|
+
* What the run could not see. A record is dropped only when its rule is
|
|
309
|
+
* absent from a project the run inventoried in full:
|
|
310
|
+
*
|
|
311
|
+
* - `prunable`: keys of the projects that were. Records of any other project
|
|
312
|
+
* stay. Left out, every project counts as read in full.
|
|
313
|
+
* - `retain`: rules whose file was skipped or changed, kept as they are.
|
|
314
|
+
* - `pruneUnattributed`: whether a record with no project key may be dropped.
|
|
315
|
+
* It may not when some project was not read in full, because the record
|
|
316
|
+
* could be that project's. Defaults to true.
|
|
317
|
+
*/
|
|
318
|
+
readonly prunable?: readonly string[];
|
|
319
|
+
readonly retain?: readonly string[];
|
|
320
|
+
readonly pruneUnattributed?: boolean;
|
|
321
|
+
}
|
|
322
|
+
export interface PublishInput {
|
|
323
|
+
readonly runId: string;
|
|
324
|
+
/** File name to content. Names are single path segments. */
|
|
325
|
+
readonly files: Readonly<Record<string, string>>;
|
|
326
|
+
readonly candidates: readonly CandidateRecord[];
|
|
327
|
+
/** Left out, the ledger's coverage is kept as it is. */
|
|
328
|
+
readonly coverage?: CoverageUpdate;
|
|
329
|
+
}
|
|
330
|
+
export interface PublishOptions {
|
|
331
|
+
/** Milliseconds since the epoch, for ledger timestamps. Defaults to `Date.now`. */
|
|
332
|
+
readonly now?: () => number;
|
|
333
|
+
readonly hooks?: {
|
|
334
|
+
/** Runs once the run is staged and before the rename commits it. A test seam for a crash. */
|
|
335
|
+
readonly beforeCommit?: () => void;
|
|
336
|
+
/** Runs after the rename committed the run and before the ledger is rewritten. A test seam for a crash. */
|
|
337
|
+
readonly afterCommit?: () => void;
|
|
338
|
+
};
|
|
339
|
+
}
|
|
340
|
+
export type PublishFailure = 'lock-lost' | 'invalid-run-id' | 'invalid-file-name' | 'invalid-candidate' | 'invalid-coverage' | 'run-exists' | 'ledger-unreadable' | 'write-failed';
|
|
341
|
+
export type PublishResult = {
|
|
342
|
+
readonly status: 'published';
|
|
343
|
+
readonly runDir: string;
|
|
344
|
+
readonly outcomes: readonly CandidateStanding[];
|
|
345
|
+
/** The rename committed the run; the ledger rewrite can still fail after it. */
|
|
346
|
+
readonly ledger: {
|
|
347
|
+
readonly written: true;
|
|
348
|
+
} | {
|
|
349
|
+
readonly written: false;
|
|
350
|
+
readonly error: string;
|
|
351
|
+
};
|
|
352
|
+
} | {
|
|
353
|
+
readonly status: 'failed';
|
|
354
|
+
readonly reason: PublishFailure;
|
|
355
|
+
};
|
|
356
|
+
/**
|
|
357
|
+
* Publish a run: stage `runs/<id>.tmp/`, rename it to `runs/<id>/` (the
|
|
358
|
+
* commit), then rewrite the ledger. The lock must be held. The ledger is read
|
|
359
|
+
* before anything is staged, so an unreadable ledger publishes nothing. A
|
|
360
|
+
* failure to rewrite the ledger after the commit is reported, not undone: the
|
|
361
|
+
* run stays and its candidates are proposed again next time.
|
|
362
|
+
*/
|
|
363
|
+
export declare function publishRun(root: string, lock: LockHandle, input: PublishInput, options?: PublishOptions): PublishResult;
|
|
364
|
+
export type RewriteResult = 'rewritten' | 'failed';
|
|
365
|
+
/**
|
|
366
|
+
* Replace files of a run that is already committed, each by a temporary file
|
|
367
|
+
* and a rename inside the run directory, owner-only. For a run whose outcome
|
|
368
|
+
* changed after the commit. The lock must be held. A name that is not in the
|
|
369
|
+
* run already, or is not a plain file name, is refused.
|
|
370
|
+
*/
|
|
371
|
+
export declare function rewriteRunFiles(root: string, lock: LockHandle, runId: string, files: Readonly<Record<string, string>>): RewriteResult;
|
|
372
|
+
export type PruneResult = {
|
|
373
|
+
readonly status: 'pruned';
|
|
374
|
+
readonly removedRuns: readonly string[];
|
|
375
|
+
readonly removedStaging: readonly string[];
|
|
376
|
+
/** Entries that matched but could not be removed. */
|
|
377
|
+
readonly failed: readonly string[];
|
|
378
|
+
} | {
|
|
379
|
+
readonly status: 'failed';
|
|
380
|
+
readonly reason: 'lock-lost' | 'unreadable';
|
|
381
|
+
};
|
|
382
|
+
export interface PruneOptions {
|
|
383
|
+
readonly now?: () => number;
|
|
384
|
+
}
|
|
385
|
+
/**
|
|
386
|
+
* Remove published runs older than thirty days and every leftover staging
|
|
387
|
+
* directory. The lock is held, so a staging directory is a crash leftover.
|
|
388
|
+
* Symlinks, files and names that are not run ids are ignored, and the ledger
|
|
389
|
+
* is never touched.
|
|
390
|
+
*/
|
|
391
|
+
export declare function pruneRuns(root: string, lock: LockHandle, options?: PruneOptions): PruneResult;
|
|
392
|
+
export interface DecideInput {
|
|
393
|
+
readonly id: string;
|
|
394
|
+
readonly status: 'promoted' | 'rejected';
|
|
395
|
+
/** One line, 500 characters at most. Required for both statuses. */
|
|
396
|
+
readonly reason: string;
|
|
397
|
+
/** Where a promoted learning was written. Ignored for `rejected`. */
|
|
398
|
+
readonly destination?: string;
|
|
399
|
+
}
|
|
400
|
+
export type DecideResult = {
|
|
401
|
+
readonly status: 'decided';
|
|
402
|
+
readonly entry: LedgerEntry;
|
|
403
|
+
} | {
|
|
404
|
+
readonly status: 'busy';
|
|
405
|
+
readonly reason: LockBusyReason;
|
|
406
|
+
} | {
|
|
407
|
+
readonly status: 'failed';
|
|
408
|
+
readonly reason: 'invalid-input' | 'unknown-candidate' | 'lock-failed' | 'ledger-unreadable' | 'write-failed';
|
|
409
|
+
};
|
|
410
|
+
/**
|
|
411
|
+
* Record a decision on a ledger entry. It takes the lock, so a busy lock makes
|
|
412
|
+
* it fail without writing, and rewrites the ledger by temp-and-rename. Both
|
|
413
|
+
* statuses need a reason.
|
|
414
|
+
*/
|
|
415
|
+
export declare function decideLedgerEntry(root: string, input: DecideInput, options?: LockOptions): DecideResult;
|
|
416
|
+
export type ClearResult = {
|
|
417
|
+
readonly status: 'cleared';
|
|
418
|
+
readonly removed: boolean;
|
|
419
|
+
} | {
|
|
420
|
+
readonly status: 'busy';
|
|
421
|
+
readonly reason: LockBusyReason;
|
|
422
|
+
} | {
|
|
423
|
+
readonly status: 'failed';
|
|
424
|
+
readonly reason: 'lock-failed' | 'write-failed';
|
|
425
|
+
};
|
|
426
|
+
/** Delete the ledger under the lock (`ledger clear`). A busy lock changes nothing. */
|
|
427
|
+
export declare function clearLedger(root: string, options?: LockOptions): ClearResult;
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
import type { V2Installer } from './opencode-v2.js';
|
|
2
|
+
/**
|
|
3
|
+
* Read-only tool guard for OpenCode v2.
|
|
4
|
+
*
|
|
5
|
+
* A v2 agent's own `permission:` rules are evaluated before a session's rules,
|
|
6
|
+
* so a session-level allow lifts them, and `execute` (Code Mode) reaches
|
|
7
|
+
* host-native tools no frontmatter key can name. This guard does not use rules.
|
|
8
|
+
* It registers one `execute.before` hook. The host triggers that hook for every
|
|
9
|
+
* tool call a session makes, before the call is looked up or run: a call the
|
|
10
|
+
* model makes directly, a call to a tool the agent was never offered, and each
|
|
11
|
+
* call made from inside Code Mode, which arrives under the host-native tool
|
|
12
|
+
* name (`opencode_*`) with the session's agent. The hook sees the agent's name
|
|
13
|
+
* and the tool's name, and a throw fails that one call with the message as the
|
|
14
|
+
* tool's error, leaving the session running.
|
|
15
|
+
*
|
|
16
|
+
* The rule is an allowlist keyed on the agent's name. A listed agent may call
|
|
17
|
+
* only the tools in {@link READ_ONLY_TOOL_ALLOWLIST}; anything else, including
|
|
18
|
+
* a tool this code has never heard of, is refused. Every other agent is left
|
|
19
|
+
* alone. Nothing here reads the agent's definition or any frontmatter field.
|
|
20
|
+
*
|
|
21
|
+
* The throw is deliberate and is not routed through the adapter's never-throw
|
|
22
|
+
* guard, which would swallow it and let the call run.
|
|
23
|
+
*
|
|
24
|
+
* Registration fails closed. A failed `hook` call is not swallowed here: it
|
|
25
|
+
* rejects, and `setupOpenCodeV2` then leaves the agents this guard protects out
|
|
26
|
+
* of the plan, because a read-only agent without its allowlist is not read-only.
|
|
27
|
+
*/
|
|
28
|
+
/** Agents that may use only the read-only tools. Matched by exact name. */
|
|
29
|
+
export declare const READ_ONLY_AGENT_NAMES: readonly string[];
|
|
30
|
+
/** The only tools a read-only agent may call. Matched by exact name. */
|
|
31
|
+
export declare const READ_ONLY_TOOL_ALLOWLIST: readonly string[];
|
|
32
|
+
export type ToolCallVerdict = {
|
|
33
|
+
readonly allowed: true;
|
|
34
|
+
} | {
|
|
35
|
+
readonly allowed: false;
|
|
36
|
+
readonly message: string;
|
|
37
|
+
};
|
|
38
|
+
/** Pure decision: may `agent` call `tool`? Never throws. */
|
|
39
|
+
export declare function decideToolCall(agent: unknown, tool: unknown): ToolCallVerdict;
|
|
40
|
+
export declare const installToolGuard: V2Installer;
|
|
@@ -31,6 +31,7 @@ export interface V2InstallInput {
|
|
|
31
31
|
export type V2Installer = (input: V2InstallInput) => Promise<void> | void;
|
|
32
32
|
export interface V2Installers {
|
|
33
33
|
agents: V2Installer;
|
|
34
|
+
toolGuard: V2Installer;
|
|
34
35
|
skills: V2Installer;
|
|
35
36
|
search: V2Installer;
|
|
36
37
|
commands: V2Installer;
|
|
@@ -92,6 +93,7 @@ export interface OpenCodeV2Deps {
|
|
|
92
93
|
/**
|
|
93
94
|
* Runs the v2 `setup` for one location: one config load, one snapshot, then
|
|
94
95
|
* each installer in turn. Rejects on invalid config. An installer failure is
|
|
95
|
-
* reported and never stops the next installer.
|
|
96
|
+
* reported and never stops the next installer. A tool guard that does not
|
|
97
|
+
* register is reported, and the agents it protects are not installed.
|
|
96
98
|
*/
|
|
97
99
|
export declare function setupOpenCodeV2(ctx: Plugin.Context, deps: OpenCodeV2Deps): Promise<void>;
|
|
@@ -41,6 +41,7 @@ export interface ManifestEntry {
|
|
|
41
41
|
* - agents/research/slack-researcher.md — CRITICAL: requires Slack MCP environment.
|
|
42
42
|
* - agents/research/learnings-researcher.md — not curated: it reads the host project's docs/solutions/ layout, so curating it is a separate decision.
|
|
43
43
|
* - agents/workflow/pr-comment-resolver.md — WARNING: "Spawned by the resolve-pr-feedback skill".
|
|
44
|
+
* - agents/research/connections-researcher.md — not curated, on purpose: a curated persona is exported with a description only, so a host that reads it gets every tool. This agent is safe only with a tool allowlist, and the pi-subagents persona format has none. Revisit only with a per-persona tool allowlist.
|
|
44
45
|
*/
|
|
45
46
|
export interface CuratedPersonaEntry {
|
|
46
47
|
relPath: string;
|
package/dist/lib/validation.d.ts
CHANGED
|
@@ -7,6 +7,7 @@ export interface PermissionConfig {
|
|
|
7
7
|
edit?: PermissionSetting;
|
|
8
8
|
bash?: PermissionSetting | Record<string, PermissionSetting>;
|
|
9
9
|
webfetch?: PermissionSetting;
|
|
10
|
+
websearch?: PermissionSetting;
|
|
10
11
|
doom_loop?: PermissionSetting;
|
|
11
12
|
external_directory?: PermissionSetting;
|
|
12
13
|
task?: PermissionSetting;
|
package/dist/pi.js
CHANGED
|
@@ -12607,8 +12607,8 @@ import fs10 from "node:fs";
|
|
|
12607
12607
|
import os5 from "node:os";
|
|
12608
12608
|
import path10 from "node:path";
|
|
12609
12609
|
import {
|
|
12610
|
-
parse as
|
|
12611
|
-
printParseErrorCode as
|
|
12610
|
+
parse as parseJsonc3,
|
|
12611
|
+
printParseErrorCode as printParseErrorCode3
|
|
12612
12612
|
} from "jsonc-parser";
|
|
12613
12613
|
|
|
12614
12614
|
// src/lib/bundled-names.ts
|
|
@@ -12623,6 +12623,7 @@ var BUNDLED_AGENT_NAMES = [
|
|
|
12623
12623
|
"cli-readiness-reviewer",
|
|
12624
12624
|
"code-simplicity-reviewer",
|
|
12625
12625
|
"coherence-reviewer",
|
|
12626
|
+
"connections-researcher",
|
|
12626
12627
|
"correctness-reviewer",
|
|
12627
12628
|
"data-migrations-reviewer",
|
|
12628
12629
|
"deployment-verification-agent",
|
|
@@ -12661,6 +12662,7 @@ var BUNDLED_AGENT_QUALIFIED_IDS = [
|
|
|
12661
12662
|
"document-review/scope-guardian-reviewer",
|
|
12662
12663
|
"document-review/security-lens-reviewer",
|
|
12663
12664
|
"research/best-practices-researcher",
|
|
12665
|
+
"research/connections-researcher",
|
|
12664
12666
|
"research/framework-docs-researcher",
|
|
12665
12667
|
"research/git-history-analyzer",
|
|
12666
12668
|
"research/issue-intelligence-analyst",
|
|
@@ -12697,6 +12699,7 @@ var BUNDLED_SKILL_NAMES = [
|
|
|
12697
12699
|
"ce:brainstorm",
|
|
12698
12700
|
"ce:compound",
|
|
12699
12701
|
"ce:compound-refresh",
|
|
12702
|
+
"ce:connect",
|
|
12700
12703
|
"ce:ideate",
|
|
12701
12704
|
"ce:plan",
|
|
12702
12705
|
"ce:review",
|
|
@@ -12737,6 +12740,15 @@ var OPENCODE_AGENT_COLOR_TOKENS = [
|
|
|
12737
12740
|
"info"
|
|
12738
12741
|
];
|
|
12739
12742
|
|
|
12743
|
+
// src/lib/connect-config.ts
|
|
12744
|
+
import {
|
|
12745
|
+
parse as parseJsonc2,
|
|
12746
|
+
printParseErrorCode as printParseErrorCode2
|
|
12747
|
+
} from "jsonc-parser";
|
|
12748
|
+
var MAX_ALLOW_PROJECTS = 64;
|
|
12749
|
+
var MAX_ALLOW_PROJECT_LENGTH = 4096;
|
|
12750
|
+
var MAX_CONNECT_CONFIG_BYTES = 1024 * 1024;
|
|
12751
|
+
|
|
12740
12752
|
// src/lib/removed-names.ts
|
|
12741
12753
|
var REMOVED_BUNDLED_SKILL_NAMES = [
|
|
12742
12754
|
"andrew-kane-gem-writer",
|
|
@@ -13036,6 +13048,18 @@ var BootstrapSchema = object({
|
|
|
13036
13048
|
description: "Bootstrap prompt configuration",
|
|
13037
13049
|
examples: [{ enabled: true }, { enabled: false }]
|
|
13038
13050
|
});
|
|
13051
|
+
var ConnectSettingsSchema = trustProtected(object({
|
|
13052
|
+
allow_projects: array(string2().min(1).max(MAX_ALLOW_PROJECT_LENGTH)).max(MAX_ALLOW_PROJECTS).optional().meta({
|
|
13053
|
+
description: `Main repository roots that \`ce:connect\` may read for contradictions and transferable lessons. Each entry is an absolute or \`~\`-prefixed path to the root of a repository checkout, not a subdirectory and not a linked worktree. At most ${MAX_ALLOW_PROJECTS} entries; an entry that matches no repository is reported by the run and does not widen the list. The lists in user, user.local, custom and custom.local config are merged as a union. Omitted or empty, it allows no project.`,
|
|
13054
|
+
examples: [["~/src/github.com/me/app", "/srv/checkouts/shared-lib"]]
|
|
13055
|
+
})
|
|
13056
|
+
}).strict().meta({
|
|
13057
|
+
description: "Cross-project connections. User-owned only: valid in user config or OPENCODE_CONFIG_DIR config, and a project config setting it has the whole block ignored with a warning, because a repository cannot grant itself access to other projects. A block with an unknown key or a bad value is unreadable and counts as an empty allow list.",
|
|
13058
|
+
examples: [
|
|
13059
|
+
{ allow_projects: ["~/src/github.com/me/app"] },
|
|
13060
|
+
{ allow_projects: [] }
|
|
13061
|
+
]
|
|
13062
|
+
}));
|
|
13039
13063
|
function createSystematicConfigSchema(opts) {
|
|
13040
13064
|
const {
|
|
13041
13065
|
agentNames,
|
|
@@ -13085,6 +13109,7 @@ function createSystematicConfigSchema(opts) {
|
|
|
13085
13109
|
examples: [true, false]
|
|
13086
13110
|
})).default(false),
|
|
13087
13111
|
search: SearchSettingsSchema.optional(),
|
|
13112
|
+
connect: ConnectSettingsSchema.optional(),
|
|
13088
13113
|
disabled_skills: array(_enum([...skillNames, ...removedSkillNames])).default([]).meta({
|
|
13089
13114
|
description: "Array of bundled skill names to disable globally. Unknown skill names are rejected at parse time.",
|
|
13090
13115
|
examples: [["ce:plan", "ce:review"]]
|
|
@@ -13416,7 +13441,10 @@ var PROTECTED_OVERLAY_FIELD_PATHS = {
|
|
|
13416
13441
|
pi: "categories.*.pi"
|
|
13417
13442
|
}
|
|
13418
13443
|
};
|
|
13419
|
-
var PROJECT_ALWAYS_PROTECTED_FIELDS = new Set([
|
|
13444
|
+
var PROJECT_ALWAYS_PROTECTED_FIELDS = new Set([
|
|
13445
|
+
"allow_project_profiles",
|
|
13446
|
+
"connect"
|
|
13447
|
+
]);
|
|
13420
13448
|
var PROJECT_PROTECTED_SEARCH_FIELDS = [
|
|
13421
13449
|
["enabled", "search.enabled"],
|
|
13422
13450
|
["allow_project_sources", "search.allow_project_sources"]
|
|
@@ -13529,12 +13557,12 @@ function loadJsoncFile(filePath, maxBytes, emptyIsAbsent) {
|
|
|
13529
13557
|
if (emptyIsAbsent && content.trim() === "")
|
|
13530
13558
|
return null;
|
|
13531
13559
|
const errors = [];
|
|
13532
|
-
const parsed =
|
|
13560
|
+
const parsed = parseJsonc3(content, errors, {
|
|
13533
13561
|
allowTrailingComma: true
|
|
13534
13562
|
});
|
|
13535
13563
|
if (errors.length > 0) {
|
|
13536
13564
|
const error = errors[0];
|
|
13537
|
-
const message = error ? `${
|
|
13565
|
+
const message = error ? `${printParseErrorCode3(error.error)} at offset ${error.offset}` : "unknown parse error";
|
|
13538
13566
|
throw configFileError(filePath, `JSONC parse error: ${message}`);
|
|
13539
13567
|
}
|
|
13540
13568
|
if (!isRecord3(parsed)) {
|
|
@@ -13801,6 +13829,13 @@ function collectProjectProtectedFields(rawConfig, trust, allowProjectProfiles) {
|
|
|
13801
13829
|
sourceKind: "project"
|
|
13802
13830
|
}
|
|
13803
13831
|
] : [],
|
|
13832
|
+
...Object.hasOwn(rawConfig, "connect") ? [
|
|
13833
|
+
{
|
|
13834
|
+
fieldPath: "connect",
|
|
13835
|
+
outcome: "blocked",
|
|
13836
|
+
sourceKind: "project"
|
|
13837
|
+
}
|
|
13838
|
+
] : [],
|
|
13804
13839
|
...collectSearchProtectedFields(rawConfig.search),
|
|
13805
13840
|
...collectOverlayProtectedFields(rawConfig.agents, "agents"),
|
|
13806
13841
|
...collectOverlayProtectedFields(rawConfig.categories, "categories")
|
|
@@ -14170,6 +14205,16 @@ function buildProfileEntry(profileSelection) {
|
|
|
14170
14205
|
function unionDisabledList(sources, key) {
|
|
14171
14206
|
return sources.reduce((merged, source) => mergeArraysUnique(merged, source.config[key]), mergeArraysUnique(DEFAULT_CONFIG[key], undefined));
|
|
14172
14207
|
}
|
|
14208
|
+
function mergeConnect(sources) {
|
|
14209
|
+
const blocks = sources.flatMap((source) => source.config.connect === undefined ? [] : [source.config.connect]);
|
|
14210
|
+
if (blocks.length === 0)
|
|
14211
|
+
return {};
|
|
14212
|
+
return {
|
|
14213
|
+
connect: {
|
|
14214
|
+
allow_projects: blocks.reduce((merged, block) => mergeArraysUnique(merged, block.allow_projects), [])
|
|
14215
|
+
}
|
|
14216
|
+
};
|
|
14217
|
+
}
|
|
14173
14218
|
function mergeBootstrap(sources) {
|
|
14174
14219
|
const merged = { ...DEFAULT_CONFIG.bootstrap };
|
|
14175
14220
|
for (const source of sources)
|
|
@@ -14261,6 +14306,7 @@ function loadConfigLayers(projectDir, options, attempt) {
|
|
|
14261
14306
|
attempt.projectContributed = projectSource !== null;
|
|
14262
14307
|
emitTopLevelProtectedFieldWarning(projectSource, "profiles", `\`profiles\` in project config (%PATH%) is only valid in user config or OPENCODE_CONFIG_DIR config and has been ignored. Its bundles are not selectable even if this project also sets \`profile\`.`, boundedProjectStrip.sink);
|
|
14263
14308
|
emitTopLevelProtectedFieldWarning(projectSource, "allow_project_profiles", `\`allow_project_profiles\` in project config (%PATH%) is only valid in user config or OPENCODE_CONFIG_DIR config and has been ignored.`, boundedProjectStrip.sink);
|
|
14309
|
+
emitTopLevelProtectedFieldWarning(projectSource, "connect", `\`connect\` in project config (%PATH%) is only valid in user config or OPENCODE_CONFIG_DIR config and has been ignored.`, boundedProjectStrip.sink);
|
|
14264
14310
|
emitProjectSearchProtectedWarnings(projectSource, boundedProjectStrip.sink);
|
|
14265
14311
|
const suppressedStripCount = boundedProjectStrip.suppressedCount();
|
|
14266
14312
|
if (suppressedStripCount > 0) {
|
|
@@ -14330,7 +14376,8 @@ function loadConfigLayers(projectDir, options, attempt) {
|
|
|
14330
14376
|
skills_as_commands: lastDefined(sources, "skills_as_commands") ?? DEFAULT_CONFIG.skills_as_commands,
|
|
14331
14377
|
allow_project_profiles: allowProjectProfiles,
|
|
14332
14378
|
...mergedSearch.settings && { search: mergedSearch.settings },
|
|
14333
|
-
...mergedSearch.unreadable && { searchUnreadable: true }
|
|
14379
|
+
...mergedSearch.unreadable && { searchUnreadable: true },
|
|
14380
|
+
...mergeConnect(sources)
|
|
14334
14381
|
};
|
|
14335
14382
|
const droppedSkills = computeDroppedNames(result.disabled_skills, CURRENT_SKILL_NAMES_SET);
|
|
14336
14383
|
warnDroppedNames(droppedSkills, "disabled_skills", warned, undefined, warningSink);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fro.bot/systematic",
|
|
3
|
-
"version": "3.
|
|
3
|
+
"version": "3.32.0",
|
|
4
4
|
"description": "Compound-engineering loops for OpenCode, Pi, and Claude Code",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"homepage": "https://fro.bot/systematic",
|
|
@@ -63,6 +63,8 @@
|
|
|
63
63
|
"review-schema:drift": "bun scripts/generate-review-artifact-schema.ts --check",
|
|
64
64
|
"ce-review-validator:build": "bun scripts/generate-ce-review-validator.ts",
|
|
65
65
|
"ce-review-validator:drift": "bun scripts/generate-ce-review-validator.ts --check",
|
|
66
|
+
"ce-connect-helper:build": "bun scripts/generate-ce-connect-helper.ts",
|
|
67
|
+
"ce-connect-helper:drift": "bun scripts/generate-ce-connect-helper.ts --check",
|
|
66
68
|
"agent-browser:build": "bun scripts/generate-agent-browser-skill.ts",
|
|
67
69
|
"agent-browser:drift": "bun scripts/generate-agent-browser-skill.ts --check",
|
|
68
70
|
"pi-personas:generate": "bun scripts/generate-pi-subagents-personas.ts",
|