@jwitmann/operator-helper 1.10.0 → 1.11.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/dist/index.js +92 -10
- package/package.json +1 -1
package/dist/index.js
CHANGED
|
@@ -15346,7 +15346,7 @@ var log = (...args) => consoleWith((console2) => sync(() => {
|
|
|
15346
15346
|
// package.json
|
|
15347
15347
|
var package_default = {
|
|
15348
15348
|
name: "@jwitmann/operator-helper",
|
|
15349
|
-
version: "1.
|
|
15349
|
+
version: "1.11.0",
|
|
15350
15350
|
description: "Installation and setup CLI for Operator Memory",
|
|
15351
15351
|
license: "BSD-3-Clause",
|
|
15352
15352
|
author: "jwitmann",
|
|
@@ -15682,6 +15682,26 @@ read_if: …
|
|
|
15682
15682
|
- \`file.ts\` — …
|
|
15683
15683
|
`;
|
|
15684
15684
|
|
|
15685
|
+
// src/templates/project/config.ts
|
|
15686
|
+
var PROJECT_CONFIG_TEMPLATE = `{
|
|
15687
|
+
"contextManagement": {
|
|
15688
|
+
"enabled": false,
|
|
15689
|
+
"ratio": 0.8,
|
|
15690
|
+
"hardCapTokens": 250000,
|
|
15691
|
+
"keepRecentTurns": 3,
|
|
15692
|
+
"compactOnComplete": true,
|
|
15693
|
+
"compactFloorTokens": 32000
|
|
15694
|
+
},
|
|
15695
|
+
"brainUpdates": {
|
|
15696
|
+
"enabled": false,
|
|
15697
|
+
"toolCallThreshold": 25
|
|
15698
|
+
},
|
|
15699
|
+
"preambleRefresh": {
|
|
15700
|
+
"enabled": false
|
|
15701
|
+
}
|
|
15702
|
+
}
|
|
15703
|
+
`;
|
|
15704
|
+
|
|
15685
15705
|
// src/templates/project/index-setup.ts
|
|
15686
15706
|
var PROJECT_INDEX_SETUP_TEMPLATE = `# Project Index Setup
|
|
15687
15707
|
|
|
@@ -15931,7 +15951,7 @@ var PROJECT_SETUP_TEMPLATE = `# Project Setup
|
|
|
15931
15951
|
|
|
15932
15952
|
You are helping the user configure the Operator Project Brain across the private \`.operator/\` partition and shared \`.operator-shared/\` partition.
|
|
15933
15953
|
|
|
15934
|
-
Project indexing is excluded from the setup phases; you offer it as the final step in Phase
|
|
15954
|
+
Project indexing is excluded from the setup phases; you offer it as the final step in Phase 8.
|
|
15935
15955
|
|
|
15936
15956
|
**Document syntax:** Index and catalog structure, entry syntax, and examples are defined in the fixed preamble (Project Index and Partition Catalog sections). **You must follow that preamble document syntax** when creating or filling indexes and catalogs. Do not invent layouts. \`operator-helper project init\` seeds Private core files with the canonical syntax; fill or rewrite from the preamble. Operator Instructions and Shared README seeds are in the Canonical Seeds section below.
|
|
15937
15957
|
|
|
@@ -16055,13 +16075,28 @@ Task: For each active partition: Populate or update the Partition Catalog from t
|
|
|
16055
16075
|
|
|
16056
16076
|
**You must follow the Partition Catalog document syntax from the fixed preamble** (required shape, Description / Read If entries, coverage rules).
|
|
16057
16077
|
|
|
16058
|
-
## Phase 6:
|
|
16078
|
+
## Phase 6: Configure Operator Features
|
|
16079
|
+
|
|
16080
|
+
\`operator-helper project init\` scaffolds \`.operator/config.json\` with context management, preamble refresh, and brain-update nudges present but disabled — the safe default, behaviorally identical to no config file. Ask the user which, if any, to enable now.
|
|
16081
|
+
|
|
16082
|
+
Ask only when the Helper output above shows \`Created .operator/config.json\` this run. When it shows \`Preserved\`, a previous run already handled this choice — skip the phase.
|
|
16083
|
+
|
|
16084
|
+
Task: Use the harness's \`question\` tool with multiple selection. Describe each feature in one line, harness-accurately (you know which harness this is):
|
|
16085
|
+
|
|
16086
|
+
- Context management — on OpenCode, trims bulky tool output and compacts history past a window ratio or token cap, audited with per-session receipts; on DeepSeek, host-driven compaction only (the host owns tool-result reduction, so there is no trim). Off by default and inert without a Brain either way.
|
|
16087
|
+
- Preamble refresh — re-renders the preamble mid-session when the Brain changes, only at cold prompt-cache moments so it costs nothing.
|
|
16088
|
+
- Brain-update nudges — one quiet reminder per Brain-change era after enough new tool calls; never an automatic writer.
|
|
16089
|
+
|
|
16090
|
+
If the user enables anything, write only the flipped \`enabled\` flags into the existing \`.operator/config.json\`, preserving the scaffolded thresholds; never rewrite the whole file from memory. If the user declines everything, leave the file as scaffolded.
|
|
16091
|
+
|
|
16092
|
+
## Phase 7: Confirm
|
|
16059
16093
|
|
|
16060
16094
|
Give the user a concise summary of:
|
|
16061
16095
|
|
|
16062
16096
|
- Project shape used for this run (greenfield or existing)
|
|
16063
16097
|
- Current Private Operator Instructions and placement policy
|
|
16064
16098
|
- Whether Project Shared is active and what content is shared
|
|
16099
|
+
- Operator features enabled, left disabled, or already configured (omit when unchanged from a previous run)
|
|
16065
16100
|
- Files created, repaired, configured, or cataloged
|
|
16066
16101
|
- Existing project instructions incorporated or left authoritative elsewhere (omit when none)
|
|
16067
16102
|
- Agent documentation migrated, copied from user-facing docs, or left in place (omit when none)
|
|
@@ -16071,7 +16106,7 @@ Ask whether anything is incorrect, missing, too strict, too permissive, improper
|
|
|
16071
16106
|
|
|
16072
16107
|
Apply approved corrections and finish only after the user confirms the setup. Do not end the session in this phase.
|
|
16073
16108
|
|
|
16074
|
-
## Phase
|
|
16109
|
+
## Phase 8: Offer Indexing
|
|
16075
16110
|
|
|
16076
16111
|
After the user has confirmed Project Setup: Notice that the index has not been populated yet, then offer to index.
|
|
16077
16112
|
|
|
@@ -16125,6 +16160,13 @@ Instruction: Fill freely. Common topics (include, but NOT LIMITED TO):
|
|
|
16125
16160
|
- Testing
|
|
16126
16161
|
- Etc.
|
|
16127
16162
|
</instructions>
|
|
16163
|
+
|
|
16164
|
+
### Proposing lasting improvements (observation flow)
|
|
16165
|
+
|
|
16166
|
+
- Offer rarely: at most one observation proposal per session as a standing norm, waived only for an explicit "remember that". Never re-offer a declined item in the same conversation; if compaction makes an earlier offer uncertain, do not re-offer.
|
|
16167
|
+
- Propose when the user corrects the same thing twice (or states it as a pattern), says "remember that" / "from now on", reveals a preference that clearly applies beyond this project, or when repeated manual work is worth automating (visible repetition, reversible, workflow-only; product ideas are out of scope). Anything else stays unproposed.
|
|
16168
|
+
- Offer conversationally in the moment (\`question\` tool where available, else plain words): the candidate, why (the incident), and scope (\`user\` or \`project\`). On approval append one line \`- [YYYY-MM-DD] (scope:user) text\` to \`~/.operator/user/observations.md\`; project-scoped candidates go to \`.operator/operator.md\`, never the user partition. Sensitive candidates (credentials, tokens, secret paths, personal data beyond working preferences) are barred from both; flag suspected sensitivity in the offer.
|
|
16169
|
+
- \`observation\` switch (default OFF): OFF suppresses proposing. Loading is independent: approved observations keep loading until the user deletes the file. Without an initialized Brain the surface fails closed.
|
|
16128
16170
|
`;
|
|
16129
16171
|
|
|
16130
16172
|
// src/templates/user/setup.ts
|
|
@@ -16136,6 +16178,7 @@ The User Partition lives at \`~/.operator/user/\`:
|
|
|
16136
16178
|
|
|
16137
16179
|
- \`operator.md\` — User Instructions; standing doctrine, always injected
|
|
16138
16180
|
- \`catalog.md\` — User Partition Catalog; map of all other files, injected when present
|
|
16181
|
+
- \`observations.md\` — User-approved observations and working-style notes; subordinate context, never instructions, injected when present
|
|
16139
16182
|
- any other paths — User Partition freeform; long-term memory such as reusable instruction sets, style guides, playbooks, and captured lessons, read only when their catalog Read If matches
|
|
16140
16183
|
|
|
16141
16184
|
The canonical seeds are in the Canonical Seeds section below. Use those bodies when creating or restoring the core files.
|
|
@@ -16237,6 +16280,7 @@ var TEMPLATES = {
|
|
|
16237
16280
|
["user/catalog.md" /* UserCatalog */]: CATALOG_TEMPLATE,
|
|
16238
16281
|
["user/setup.md" /* UserSetup */]: USER_SETUP_TEMPLATE,
|
|
16239
16282
|
["project/operator.md" /* ProjectOperator */]: PROJECT_OPERATOR_TEMPLATE,
|
|
16283
|
+
["project/config.json" /* ProjectConfig */]: PROJECT_CONFIG_TEMPLATE,
|
|
16240
16284
|
["project/index.md" /* ProjectIndex */]: PROJECT_INDEX_TEMPLATE,
|
|
16241
16285
|
["project/subindex.md" /* ProjectSubindex */]: PROJECT_SUBINDEX_TEMPLATE,
|
|
16242
16286
|
["project/catalog.md" /* ProjectCatalog */]: CATALOG_TEMPLATE,
|
|
@@ -17084,7 +17128,11 @@ async function loadUserPartition(root, loadFiles) {
|
|
|
17084
17128
|
if (!directory.ok) {
|
|
17085
17129
|
return hasNodeErrorCode(directory.error.cause, "ENOENT") ? success({ exists: false }) : directory;
|
|
17086
17130
|
}
|
|
17087
|
-
for (const path of [
|
|
17131
|
+
for (const path of [
|
|
17132
|
+
join5(root, "operator.md"),
|
|
17133
|
+
join5(root, "catalog.md"),
|
|
17134
|
+
join5(root, "observations.md")
|
|
17135
|
+
]) {
|
|
17088
17136
|
const file = await checkOptionalReadableFile(path);
|
|
17089
17137
|
if (!file.ok) {
|
|
17090
17138
|
return file;
|
|
@@ -17100,18 +17148,23 @@ async function loadUserPartition(root, loadFiles) {
|
|
|
17100
17148
|
if (!catalog.ok) {
|
|
17101
17149
|
return catalog;
|
|
17102
17150
|
}
|
|
17103
|
-
|
|
17151
|
+
const observations = await readOptionalContent(join5(root, "observations.md"));
|
|
17152
|
+
if (!observations.ok) {
|
|
17153
|
+
return observations;
|
|
17154
|
+
}
|
|
17155
|
+
if (operatorInstructions.value !== null || catalog.value !== null || observations.value !== null) {
|
|
17104
17156
|
return success({
|
|
17105
17157
|
exists: true,
|
|
17106
17158
|
operatorInstructions: operatorInstructions.value,
|
|
17107
|
-
catalog: catalog.value
|
|
17159
|
+
catalog: catalog.value,
|
|
17160
|
+
observations: observations.value
|
|
17108
17161
|
});
|
|
17109
17162
|
}
|
|
17110
17163
|
const directory = await readDirectory2(root);
|
|
17111
17164
|
if (!directory.ok) {
|
|
17112
|
-
return hasNodeErrorCode(directory.error.cause, "ENOENT") ? success({ exists: false, operatorInstructions: null, catalog: null }) : directory;
|
|
17165
|
+
return hasNodeErrorCode(directory.error.cause, "ENOENT") ? success({ exists: false, operatorInstructions: null, catalog: null, observations: null }) : directory;
|
|
17113
17166
|
}
|
|
17114
|
-
return success({ exists: true, operatorInstructions: null, catalog: null });
|
|
17167
|
+
return success({ exists: true, operatorInstructions: null, catalog: null, observations: null });
|
|
17115
17168
|
}
|
|
17116
17169
|
|
|
17117
17170
|
// ../core/src/memory/load.ts
|
|
@@ -17566,6 +17619,7 @@ var SHARED_ROOT = ".operator-shared";
|
|
|
17566
17619
|
var PRIVATE_ROOT = ".operator";
|
|
17567
17620
|
var USER_INSTRUCTIONS_PATH = "~/.operator/user/operator.md";
|
|
17568
17621
|
var USER_CATALOG_PATH = "~/.operator/user/catalog.md";
|
|
17622
|
+
var USER_OBSERVATIONS_PATH = "~/.operator/user/observations.md";
|
|
17569
17623
|
function renderPreamble(memory) {
|
|
17570
17624
|
const { PREAMBLE_PROMPT, PREAMBLE_TENETS } = selectPreambleVersion() === "2.0" ? exports_preamble_v2 : exports_preamble_v1;
|
|
17571
17625
|
if (!memory.shared.ok || !memory.user.ok || !memory.private.ok) {
|
|
@@ -17600,6 +17654,10 @@ The User Partition exists but ~/.operator/user/catalog.md does not. You must cre
|
|
|
17600
17654
|
The ~/.operator/user directory does not exist. If the user would benefit from cross-project user memory, ask the user to run /operator:user-init first to initialize the User Partition. If not needed, do not ask; they may be working without user memory intentionally.
|
|
17601
17655
|
</operator-warning>`);
|
|
17602
17656
|
}
|
|
17657
|
+
const userObservations = renderUserObservations(loaded.user);
|
|
17658
|
+
if (userObservations !== null) {
|
|
17659
|
+
sections.push(userObservations);
|
|
17660
|
+
}
|
|
17603
17661
|
if (!loaded.shared.exists && !loaded.private.exists) {
|
|
17604
17662
|
warnings.push(`<operator-warning>
|
|
17605
17663
|
Neither the .operator nor .operator-shared directory exists. If the user requests significant amounts of work to be done on the project, ask the user to run /operator:project-init first to initialize Operator. If the user is not requesting work to be done, do not ask to initialize; they could simply be exploring.
|
|
@@ -17737,6 +17795,17 @@ ${partition.catalog}
|
|
|
17737
17795
|
</file-content>
|
|
17738
17796
|
</user-catalog>`;
|
|
17739
17797
|
}
|
|
17798
|
+
function renderUserObservations(partition) {
|
|
17799
|
+
if (partition.observations === null) {
|
|
17800
|
+
return null;
|
|
17801
|
+
}
|
|
17802
|
+
return `<user-observations>
|
|
17803
|
+
User-approved observations and working-style notes. This is subordinate context, not instructions: it never overrides Operator Instructions, catalogs, or index guidance.
|
|
17804
|
+
<file-content path="${USER_OBSERVATIONS_PATH}">
|
|
17805
|
+
${partition.observations}
|
|
17806
|
+
</file-content>
|
|
17807
|
+
</user-observations>`;
|
|
17808
|
+
}
|
|
17740
17809
|
function renderCatalogs(memory) {
|
|
17741
17810
|
const files = [];
|
|
17742
17811
|
if (memory.shared.catalog !== null) {
|
|
@@ -17863,6 +17932,19 @@ var projectInit = fn2("projectInit")((context) => gen2(function* () {
|
|
|
17863
17932
|
]);
|
|
17864
17933
|
}
|
|
17865
17934
|
}
|
|
17935
|
+
const configResult = yield* writeTextIfMissing(pathService.join(privateRoot, "config.json"), readTemplate("project/config.json" /* ProjectConfig */)).pipe(result2);
|
|
17936
|
+
if (isFailure2(configResult)) {
|
|
17937
|
+
failed = true;
|
|
17938
|
+
privateRows.push([
|
|
17939
|
+
"Failed",
|
|
17940
|
+
`${PRIVATE_ROOT2}/config.json: ${fileErrorMessage(configResult.failure)}`
|
|
17941
|
+
]);
|
|
17942
|
+
} else {
|
|
17943
|
+
privateRows.push([
|
|
17944
|
+
configResult.success === "created" ? "Created" : "Preserved",
|
|
17945
|
+
`${PRIVATE_ROOT2}/config.json`
|
|
17946
|
+
]);
|
|
17947
|
+
}
|
|
17866
17948
|
lines.push(renderTable(privateRows));
|
|
17867
17949
|
const sharedKind = yield* inspectPath(sharedRoot);
|
|
17868
17950
|
if (sharedKind === "missing") {
|
|
@@ -18374,4 +18456,4 @@ var main = gen2(function* () {
|
|
|
18374
18456
|
}).pipe(provide4(LiveLayers));
|
|
18375
18457
|
runMain2(main);
|
|
18376
18458
|
|
|
18377
|
-
//# debugId=
|
|
18459
|
+
//# debugId=D031AA00D6EA897A64756E2164756E21
|