@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.
Files changed (2) hide show
  1. package/dist/index.js +92 -10
  2. 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.10.0",
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 7.
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: Confirm
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 7: Offer Indexing
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 [join5(root, "operator.md"), join5(root, "catalog.md")]) {
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
- if (operatorInstructions.value !== null || catalog.value !== null) {
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=08FD58CA67454AC564756E2164756E21
18459
+ //# debugId=D031AA00D6EA897A64756E2164756E21
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jwitmann/operator-helper",
3
- "version": "1.10.0",
3
+ "version": "1.11.0",
4
4
  "description": "Installation and setup CLI for Operator Memory",
5
5
  "license": "BSD-3-Clause",
6
6
  "author": "jwitmann",