pi-beyin 0.1.7 → 0.1.9

package/README.md

@@ -26,6 +26,26 @@ text found in notes, imported transcripts or tool output.
 
 The extensions without a vault are no-ops; `context` and `damitma` have nothing to read.
 
+## Who this is for
+
+- You already use a **beyin vault** — a directory with `beyin.py` that brings its own installer and updater.
+- You run **pi** and want that vault wired into pi.
+- You have **CommandCode** access if you want Jev and the advisor tools. Without it, context injection,
+  the receipt reminder and the distillation offer still work; only scoring and the `beyin_jev_*` tools
+  stay inert.
+
+With CommandCode, install the official provider so Jev can reuse its key instead of a separate secret:
+
+```bash
+pi install npm:@commandcode/pi-commandcode-provider
+```
+
+Otherwise put `CMD_API_KEY=...` in `~/.config/beyin/jev-commandcode.env` (or export it).
+
+The harness patch only knows the code shapes it was written against. On an unfamiliar vault it prints
+warnings, leaves the files untouched (fail-soft) and `receipt --harness pi` stays unavailable until the
+patterns match — nothing breaks, the work is just labelled with another harness.
+
 ## Install
 
 ```bash
@@ -50,7 +70,9 @@ the context twice.
 
 Environment: `BEYIN_VAULT`, `BEYIN_PYTHON`, `BEYIN_HOOK_CONFIG`, `BEYIN_DAMITMA_CONFIG`,
 `BEYIN_JEV_CONFIG`, `BEYIN_CONTEXT_CHARS`, `BEYIN_REMINDERS=0`, `BEYIN_INCLUDE_VAULT=1`,
-`BEYIN_DAMITMA=0`, `BEYIN_JEV=0`, `BEYIN_DISABLE=1`, `BEYIN_DEBUG=1`, `BEYIN_PI_PATCH`,
+`BEYIN_DAMITMA=0`, `BEYIN_JEV=0`, `BEYIN_DISABLE=1`, `BEYIN_DEBUG=1`, `BEYIN_PI_PATCH`, `BEYIN_LANG` (`tr`
+by default; `en` switches the injected notices and command descriptions to English — the
+`beyin_jev_*` tool schema text is still Turkish),
 `BEYIN_JEV_MODEL`, `BEYIN_JEV_API_KEY` / `CMD_API_KEY` / `COMMAND_CODE_API_KEY`,
 `BEYIN_FORCE_REMINDER=1`.
 
@@ -77,20 +99,20 @@ The extensions call `beyin.py` (read-only unless the agent runs a write command)
 A vault whose `beyin.py` does not accept `--harness pi` needs `tools/pi-harness-patch.py ensure
 --vault <vault>` (the extension does this on session start).
 
-## Relationship to beyin v3
+## Scope
 
-`pi-beyin` is the **pi-side** adapter; the vault, `beyin.py` and the canonical skill templates belong to
-beyin v3 and keep their own release cycle.
+This package is the **pi side**: extensions, skills and the harness patch. The vault and its `beyin.py`
+CLI are yours to install and update separately; this package never needs to know their version.
 
-- `tools/pi-harness-patch.py` is the only thing that touches beyin's files: it adds `pi` to the harness
-  list in two managed modules (plus three pi-specific fixes) and re-syncs the install manifest so
-  `beyin.py update` plans cleanly. **A beyin update reverts these edits**; the extension calls `ensure`
-  on session start, so they come back by themselves. `status` is read-only.
-- The skills here are **copies for pi**, not links into the vault. beyin still installs its own copies
-  under `.claude/skills/` for the other harnesses; pi does not read that directory.
-- Notifications stay in the adapter: the injected context, the receipt reminder, the distillation
-  suggestion and the `beyin_jev_*` tool descriptions ship with this package. They are written in Turkish
-  today (the author's language); anything a *skill* writes follows the user's language.
+- `tools/pi-harness-patch.py` is the only piece that touches the vault's Python: it adds `pi` to the
+  harness list in five managed modules and re-syncs the install manifest so updates plan cleanly.
+  An update of the vault reverts those edits; the extension calls `ensure` on session start, so they
+  come back by themselves. `status` is read-only.
+- The skills here are **copies for pi**, not links into the vault. Other harnesses keep their own copies
+  under `.claude/skills/`; pi does not read that directory.
+- Notifications live in the adapter: the injected context, the receipt reminder, the distillation
+  suggestion and the `beyin_jev_*` tool descriptions ship here. They are written in Turkish today (the
+  author's language); anything a *skill* writes follows the user's language.
 
 ## Project memory skills
 

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,33 @@
+# Third-party notices
+
+## beyin
+
+`tools/pi-harness-patch.py` contains short source excerpts from the beyin vault code that it patches
+(the harness tuples, the Jev request headers and the assessment entry point). Those excerpts remain
+under beyin's license:
+
+```
+MIT License
+
+Copyright (c) 2026 Forn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+Everything else in this repository is MIT, see [LICENSE](LICENSE).

package/extensions/context.ts

@@ -1,5 +1,5 @@
 /**
- * Beyin V3 — pi-native bridge (the pi equivalent of the beyin hook).
+ * pi-native bridge for the beyin vault (the pi equivalent of the beyin hook).
  *
  * Beyin's OMP/OpenCode/Claude/Codex hooks do not run in pi. This extension pulls
  * relevant notes from the local second brain on every user prompt and injects them
@@ -43,6 +43,8 @@ const REMINDERS = process.env.BEYIN_REMINDERS !== "0";
 const INCLUDE_VAULT = process.env.BEYIN_INCLUDE_VAULT === "1";
 const DISABLED = process.env.BEYIN_DISABLE === "1";
 const DEBUG = process.env.BEYIN_DEBUG === "1";
+/** Model-facing fixed texts: "tr" (default) or "en" via BEYIN_LANG. */
+const LANG = /^en/i.test(process.env.BEYIN_LANG || "") ? "en" : "tr";
 
 const SYNTHETIC_PREFIXES = [
 	"<task-notification>",
@@ -647,13 +649,21 @@ export default function beyinContext(pi: ExtensionAPI) {
 		// Receipt reminder from the previous turn (full mode only); then reset the flags for the new turn.
 		let reminder: string | undefined;
 		if (REMINDERS && mode === "full" && prevEdited && !prevRecorded) {
+			const receiptCmd = `python3 ${path.join(VAULT, "beyin.py")} receipt --harness pi --event-id EVENT_ID --summary "..." --ref <vault-relative-path>`;
 			reminder =
-				"## İkinci beyin — kayıt gerekli\n" +
-				"Önceki turda dosya düzenlendi ve ikinci beyne kayıt düşülmedi. " +
-				"Bu mesajı yanıtlamadan ÖNCE kaydet: vault dosyasıysa " +
-				`\`python3 ${path.join(VAULT, "beyin.py")} receipt --harness pi --event-id EVENT_ID --summary "..." --ref <vault-goreli-yol>\`; ` +
-				"vault dışı bir işse `note-create`/`task-create` ile vault'a kısa bir sonuç/görev notu yaz. " +
-				"Kalıcı bir öğrenim varsa `knowledge/` altına damıt. Sonra normal yanıtı ver.";
+				LANG === "en"
+					? "## Second brain — record required\n" +
+						"The previous turn edited files without recording anything in the second brain. " +
+						"Record BEFORE answering this message: for a vault file run " +
+						`\`${receiptCmd}\`; ` +
+						"for work outside the vault write a short result/task note with `note-create`/`task-create`. " +
+						"If there is a durable lesson, distill it under `knowledge/`. Then answer normally."
+					: "## İkinci beyin — kayıt gerekli\n" +
+						"Önceki turda dosya düzenlendi ve ikinci beyne kayıt düşülmedi. " +
+						"Bu mesajı yanıtlamadan ÖNCE kaydet: vault dosyasıysa " +
+						`\`${receiptCmd}\`; ` +
+						"vault dışı bir işse `note-create`/`task-create` ile vault'a kısa bir sonuç/görev notu yaz. " +
+						"Kalıcı bir öğrenim varsa `knowledge/` altına damıt. Sonra normal yanıtı ver.";
 		}
 		prevEdited = false;
 		prevRecorded = false;

package/extensions/damitma.ts

@@ -2,7 +2,7 @@
  * Beyin distillation — a knowledge-distillation SUGGESTION at turn/session end.
  *
  * Why: in beyin's bare form the concept/distillation work is done by the active
- * agent, not a background model (the V2 background compiler is retired). But the
+ * agent, not a background model. But the
  * "was the lesson distilled" step could be skipped silently. If a turn wrote a record
  * to the second brain without distilling under `knowledge/`, this extension injects a
  * short "offer distillation candidates" instruction at the end of the turn.
@@ -43,6 +43,8 @@ const HOOK_CONFIG_FILE = process.env.BEYIN_HOOK_CONFIG || path.join(HOME, ".conf
 const DEFAULT_EXCLUDES: string[] = [];
 const DISABLED = process.env.BEYIN_DAMITMA === "0" || process.env.BEYIN_DISABLE === "1";
 const DEBUG = process.env.BEYIN_DEBUG === "1";
+/** Model-facing fixed texts: "tr" (default) or "en" via BEYIN_LANG. */
+const LANG = /^en/i.test(process.env.BEYIN_LANG || "") ? "en" : "tr";
 
 const RECEIPT_RE = /(?:^|\s)beyin\.py\s+(?:receipt|note-create|task-create|task-update)\b/;
 const KNOWLEDGE_RE = /(^|[\\/])knowledge[\\/]/;
@@ -127,6 +129,18 @@ function insideVault(p: string): boolean {
 }
 
 function instruction(maxCandidates: number): string {
+	if (LANG === "en") {
+		return [
+			"## Second brain — distillation offer",
+			"This turn wrote to the second brain but nothing was distilled under `knowledge/`.",
+			"Now give the user a SHORT distillation offer (a short visible list):",
+			`- At most ${maxCandidates} candidates. One line each: **title** — one sentence — source (file/receipt path).`,
+			"- Offer only reusable lessons/decisions/concepts/methods; never invent candidates to fill a quota, never offer transient detail.",
+			'- If there is no durable lesson, skip the offer and say "nothing durable to distill" in one sentence.',
+			"- Write nothing under `knowledge/` before the user approves. After approval, write it with `beyin.py note-create` and add it to the receipt refs.",
+			"- If improving an existing knowledge note is enough, say so; do not open a new file.",
+		].join("\n");
+	}
 	return [
 		"## İkinci beyin — damıtma önerisi",
 		"Bu turda ikinci beyne kayıt düşüldü ama kalıcı bilgi `knowledge/` altına damıtılmadı.",
@@ -226,13 +240,13 @@ export default function beyinDamitma(pi: ExtensionAPI) {
 
 	// Manual trigger: /damitma — asks for the same suggestion right now.
 	pi.registerCommand("damitma", {
-		description: "İkinci beyin damıtma önerisini şimdi iste",
+		description: LANG === "en" ? "Ask for the second-brain distillation offer now" : "İkinci beyin damıtma önerisini şimdi iste",
 		handler: async (_args, ctx: ExtensionContext) => {
 			pi.sendMessage(
 				{ customType: "beyin-damitma", display: false, content: instruction(config.maxCandidates) },
 				{ triggerTurn: true },
 			);
-			ctx.ui.notify("Damıtma önerisi istendi", "info");
+			ctx.ui.notify(LANG === "en" ? "Distillation offer requested" : "Damıtma önerisi istendi", "info");
 		},
 	});
 }

package/extensions/jev.ts

@@ -40,6 +40,8 @@ const DEFAULT_MODEL = "typesafe/jev";
 const KEY_FILE = path.join(HOME, ".config", "beyin", "jev-commandcode.env");
 const CONFIG_FILE = path.join(HOME, ".config", "beyin", "jev.json");
 const DEBUG = process.env.BEYIN_DEBUG === "1";
+/** User-facing fixed texts: "tr" (default) or "en" via BEYIN_LANG. */
+const LANG = /^en/i.test(process.env.BEYIN_LANG || "") ? "en" : "tr";
 
 // Latest session context, needed to use pi's auth API (without touching auth.json directly).
 let latestContext: ExtensionContext | undefined;
@@ -279,7 +281,7 @@ export default function beyinJev(pi: ExtensionAPI) {
 	});
 
 	pi.registerCommand("jev-test", {
-		description: "CommandCode destekli Jev (typesafe/jev) classifier'ını dene",
+		description: LANG === "en" ? "Try the CommandCode-backed Jev (typesafe/jev) classifier" : "CommandCode destekli Jev (typesafe/jev) classifier'ını dene",
 		handler: async (args, ctx: ExtensionContext) => {
 			const model = ctx.modelRegistry.findOfType("classifier", PROVIDER, MODEL_ID);
 			if (!model) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-beyin",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "pi-native bridge for the beyin second brain: context injection, distillation reminders, and Jev advisor tools.",
   "keywords": [
     "pi-package",
@@ -34,7 +34,8 @@
     "skills",
     "tools",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "THIRD-PARTY-NOTICES.md"
   ],
   "scripts": {
     "test": "bash test/run.sh",

package/skills/brain/SKILL.md

@@ -70,7 +70,7 @@ your behalf.
 
 ## Turning results into permanent knowledge
 
-The active agent continues V2's concept and link production. If a result contains reusable knowledge, first read
+The active agent produces the concept and link notes. If a result contains reusable knowledge, first read
 `knowledge/index.md` and only the relevant concept. Improve the existing note with its sources, or create
 `knowledge/concepts/<topic>.md`: short description, key points, reasoning/limits and sources. If the source is
 the user's own statement, say so explicitly. If two topics have a real relationship, create a reasoned connection
@@ -236,14 +236,14 @@ the applications are closed. In sparse-check or manual mode, refresh the source
 information is needed; don't assume an old session context is current. Work started earlier may have finished;
 turning it off stops the next jobs.
 
-The default V3 engine makes no automatic call to Luna, Sonnet or any other model. The Jev auto_context feature,
+The default engine makes no automatic call to Luna, Sonnet or any other model. The Jev auto_context feature,
 which the user enables explicitly and separately, is a limited, optional remote consultation outside that rule.
 Local checks consume no tokens; the results the agent writes and the context it reads or adds count toward the
 client's usage. A character limit is not a guarantee of token count or cost. A 15-minute agent automation the
 user installed separately is not governed by this setting; examine it separately. Don't add a paid scheduler, a
 model runner or a new dependency without being asked.
 
-V3.1: the `updates` section inside `doctor` shows the latest version check; a network error does not prove being
+The `updates` section inside `doctor` shows the latest version check; a network error does not prove being
 up to date. Use `beyin.py update --check --metadata-only` only for a version question. Route an update request to
 the `brain-update` skill.
 

package/skills/brain-doctor/SKILL.md

@@ -64,7 +64,7 @@ Tell the user three things: the part that works, the unverified/broken part, and
 one. Give a short, concrete result instead of raw JSON. If the user's existing approval covers the safe fix, don't
 ask again for nothing.
 
-V3.1: the `updates` section inside `doctor` shows the latest version check; a network error does not prove being up
+The `updates` section inside `doctor` shows the latest version check; a network error does not prove being up
 to date. Use `beyin.py update --check --metadata-only` only for a version question. Route an update request to the
 `brain-update` skill.
 

package/skills/brain-update/SKILL.md

@@ -33,7 +33,7 @@ user step.
 In the result message give the previous→new version, the verification result and any step left open. Don't share
 tokens, local user paths, personal settings dumps or raw logs.
 
-If `--metadata-only` is not recognized (a version before V3.1), fall back to the existing `update --check`. Version
+If `--metadata-only` is not recognized (older beyin), fall back to the existing `update --check`. Version
 notifications are an on-by-default daily GitHub metadata check; they post no notes. Apply an off/on request with
 `preferences --update-notifications off/on`. To silence one version use `update --dismiss X.Y.Z`. A metadata-only
 result is not proof that the package can be installed.

package/tools/pi-harness-patch.py

@@ -1,11 +1,11 @@
 #!/usr/bin/env python3
-"""Add "pi" as a first-class Beyin V3 harness, update-safely.
+"""Add "pi" as a first-class beyin harness, update-safely.
 
 Why this exists
 ---------------
-Beyin V3 knows the harnesses codex/claude/antigravity/hermes/opencode/omp, but not
+beyin knows the harnesses codex/claude/antigravity/hermes/opencode/omp, but not
 pi. That blocks `beyin.py receipt --harness pi` and `context --harness pi`, so pi
-work is mislabeled. Pi runs outside Beyin's own hooks, so the fix has to live here.
+work is mislabeled. pi runs outside beyin's own hooks, so the fix has to live here.
 
 How it stays update-safe
 ------------------------