@jetrabbits/agentic 0.2.0 → 0.3.1

package/docs/agentic-stabilization/README.md

@@ -0,0 +1,37 @@
+# Agentic Stabilization v0.3.0
+
+## User-Facing Behavior
+
+- Post-install doctor checks run independently for `codex`, `opencode`, `claude`, and `gemini`.
+- `AGENTIC_DOCTOR_TIMEOUT_SECONDS` defaults to `10`; a timeout is reported as a doctor failure and install continues.
+- Codex doctor runs non-interactively with `--ephemeral`, `--sandbox workspace-write`, and the same lightweight smoke prompt as other supported doctor targets.
+- OpenCode uses `agent-model-mapper` instead of the removed `model-checker` artifacts.
+- `agent-model-mapper` writes `.opencode/opencode.json` during interactive install only after confirmation.
+- `agent-model-mapper` uses `fzf` for install-time model dropdowns when available and OpenCode startup skips once all roles are mapped.
+- The runtime OpenCode plugin never opens `fzf`, asks questions, or writes project files.
+- Context7 offers an interactive key mode: configure without a key or enter `CONTEXT7_API_KEY` for the selected target configs.
+- OpenCode MemPalace setup writes `mempalace-mcp` config and initializes/mines project memory into a project-specific wing without LLM calls.
+- Telegram notification credentials are read from project `.agentic.json` when the plugin is enabled.
+- MemPalace-enabled installs create a managed `.mempalaceignore` unless the target project already has one.
+- `make test` runs the fast deterministic e2e suite; longer deterministic checks, real blackbox, and coverage checks are explicit targets.
+- `make test-all` runs the full local suite including longer deterministic checks, install/evidence blackbox, and coverage.
+- Real Codex, OpenCode, and Telegram blackbox install/evidence scenarios run through `make test-real-blackbox`.
+- Live Codex/OpenCode/Telegram blackbox sessions require `AGENTIC_REAL_BLACKBOX_LIVE=1`.
+- `make test-coverage` traces `agentic` through e2e runs and fails below 90% line coverage.
+
+## Acceptance Criteria
+
+- Hung agent doctor commands time out and do not stop remaining selected agents from running.
+- Doctor output includes timeout duration, exit status, and per-agent elapsed time.
+- `extensions/opencode/plugins/model-checker.ts` and `model-checker.json` are absent.
+- `extensions/opencode/opencode.json` lists `agent-model-mapper`.
+- Runtime model mapper execution does not prompt or modify project files.
+- Telegram plugin tests prove environment-only credentials and no secret output.
+- Real blackbox tests print created files, managed guidance sources, and MCP config evidence, then save instruction evidence to a temp file without printing Telegram secrets.
+
+## Operational Constraints
+
+- `make test` is deterministic, designed for a sub-minute local loop, and does not require real agent binaries, model auth, network access, Context7/MemPalace access, or Telegram credentials.
+- `AGENTIC_REAL_BLACKBOX_LIVE=1 make test-real-blackbox` requires real `codex` and `opencode` binaries, working model auth, network access, Context7/MemPalace access, and Telegram credentials for the Telegram case.
+- Telegram credentials must never be committed or written to Agentic config.
+- Coverage is line-based Bash trace coverage for the `agentic` script, not branch coverage.

package/docs/agentic-token-minimization/README.md

@@ -32,15 +32,17 @@ When installing for OpenCode, `agentic` writes optional plugin state to:
 ~/.config/agentic/opencode-plugins.json
 ```
 
-Interactive installs ask whether to enable Telegram notifications and model checking. Non-interactive installs default optional plugins to disabled when no config exists.
+Interactive installs ask whether to enable Telegram notifications and model mapping. Non-interactive installs default optional plugins to disabled when no config exists.
 
-The OpenCode plugins read this config at startup and return no hooks when disabled. Telegram credentials can also be supplied through:
+The OpenCode plugins read project `.agentic.json` at startup and return no hooks when disabled. When Telegram is enabled, credentials are stored in plaintext at:
 
 ```text
-OPENCODE_TELEGRAM_BOT_TOKEN
-OPENCODE_TELEGRAM_CHAT_ID
+settings.opencode_plugins.telegram.botToken
+settings.opencode_plugins.telegram.chatId
 ```
 
+Do not commit a Telegram-enabled `.agentic.json` to public repositories.
+
 ## Context7
 
 `agentic` adds Context7 MCP configuration for known project-level formats:
@@ -54,7 +56,7 @@ OPENCODE_TELEGRAM_CHAT_ID
 - `.kilocode/mcp.json` for `kilocode`
 - `~/.gemini/antigravity/mcp_config.json` for `antigravity` (global user config)
 
-Interactive installs ask whether to enable Context7. If enabled, the Context7 API key is optional. Empty keys keep the install usable with default Context7 limits or rule-only fallback behavior. Non-interactive installs enable Context7 only when `CONTEXT7_API_KEY` is already set. Generated guidance requires agents to use Context7 for framework, SDK, library, and API documentation before relying on model memory when the project config is present.
+Interactive installs ask whether to enable Context7. If enabled, Context7 can be configured without a key or with a `CONTEXT7_API_KEY` entered during setup. Non-interactive installs enable Context7 when either `AGENTIC_ENABLE_CONTEXT7=y` or `CONTEXT7_API_KEY` is set. Generated guidance requires agents to use Context7 for framework, SDK, library, and API documentation before relying on model memory when the project config is present.
 
 Directory copies are processed in batches so large specialization installs avoid spawning a separate marker/manifest process for every copied file. Manifest protection still applies: existing unmanaged files are skipped on rerun, user-modified managed files are skipped, and new generated files can be added by newer `agentic` versions.
 

package/docs/agentic-usage.md

@@ -104,7 +104,7 @@ The final install line prints the exact path:
 Agentic log file: /tmp/agentic-20260512-114203.ABC123
 ```
 
-`agentic` also runs a final doctor smoke check for selected real agent targets (`codex`, `opencode`, `claude`, `gemini`). The doctor runs `/develop-feature напиши hello world python` in a temporary copy of the project and prints one status row per selected agent. Doctor failures are reported but do not roll back or fail the install. Disable doctor for CI or cheap checks with:
+`agentic` also runs a final doctor smoke check for selected real agent targets (`codex`, `opencode`, `claude`, `gemini`). The doctor runs in a temporary copy of the project and prints one status row per selected agent. All supported doctor targets use a lightweight pure smoke prompt, so install-time doctor checks do not start a long SDLC workflow. Each agent has an independent timeout controlled by `AGENTIC_DOCTOR_TIMEOUT_SECONDS` and defaults to `10` seconds. Doctor failures and timeouts are reported but do not roll back or fail the install. Disable doctor for cheap checks with:
 
 ```bash
 AGENTIC_DOCTOR=0 agentic install ...
@@ -163,38 +163,41 @@ scoop install fzf
 
 ## OpenCode optional plugins
 
-When `opencode` is selected, interactive installs ask whether to enable Telegram notifications and the model checker. The answer is stored globally in:
+When `opencode` is selected, interactive installs ask whether to enable Telegram notifications and `agent-model-mapper`. The answer is stored globally in:
 
 ```text
 ~/.config/agentic/opencode-plugins.json
 ```
 
-Non-interactive installs create a disabled config when no config exists. Telegram can also read `OPENCODE_TELEGRAM_BOT_TOKEN` and `OPENCODE_TELEGRAM_CHAT_ID`.
+Non-interactive installs create a disabled config when no config exists. Interactive installs ask for Telegram `botToken` and `chatId` when `telegram-notification` is selected. Those credentials are written to the target project `.agentic.json` under `settings.opencode_plugins.telegram`, not to `~/.config/agentic/opencode-plugins.json`. Treat `.agentic.json` as plaintext secret-bearing project config when Telegram is enabled and do not commit it to public repositories. When enabled, `agent-model-mapper` runs during interactive `agentic install`/`agentic tui`, uses `fzf` as a dropdown picker when available, and writes `.opencode/opencode.json` only after a Confirm action. OpenCode startup never prompts for model mapping; the runtime plugin only reports whether install-time mapping is already complete.
 
 ## Context7
 
-For `opencode`, `codex`, `claude`, `cursor`, `gemini`, `kilocode`, and `antigravity`, interactive installs ask whether to add Context7 MCP configuration. If enabled, the Context7 API key prompt is optional; leave it empty to configure Context7 without a key. Most targets use project-level files, while `antigravity` is written to the global user path `~/.gemini/antigravity/mcp_config.json`.
+For `opencode`, `codex`, `claude`, `cursor`, `gemini`, `kilocode`, and `antigravity`, interactive installs ask whether to add Context7 MCP configuration. If enabled, a follow-up menu chooses either keyless mode or entering `CONTEXT7_API_KEY`. The selected key is written to all selected target configs for the current project. Most targets use project-level files, while `antigravity` is written to the global user path `~/.gemini/antigravity/mcp_config.json`.
 
-Non-interactive installs skip Context7 unless `CONTEXT7_API_KEY` is set in the environment. Agents are instructed to use Context7 for framework, library, SDK, API, and setup documentation when the project config is present.
+Non-interactive installs enable Context7 when either `AGENTIC_ENABLE_CONTEXT7=y` or `CONTEXT7_API_KEY` is set. Agents are instructed to use Context7 for framework, library, SDK, API, and setup documentation when the project config is present.
 
 ## MemPalace
 
-For `opencode`, `codex`, `claude`, `cursor`, `gemini`, and `antigravity`, MemPalace MCP is configured as a local Python module instead of a hosted MCP URL. Install it first:
-
-```bash
-pip install mempalace
-```
+For `opencode`, `codex`, `claude`, `cursor`, `gemini`, `kilocode`, and `antigravity`, MemPalace MCP is configured as a local Python module instead of a hosted MCP URL. When MemPalace is enabled, `agentic` attempts to install it automatically with `pip install mempalace`.
 
 Generated configs run `mempalace-mcp` without arguments for all supported agent targets. Runtime startup and MCP tool errors are checked by the post-install doctor stage.
 
-During install, if MemPalace is enabled, `agentic` checks whether `mempalace-mcp` is available. For OpenCode installs, `agentic` creates `<project>` and runs `mempalace init "<project>" --yes --auto-mine`. If checks fail (for example, package not installed yet), install continues and agents fall back to standard context discovery.
+During install, if MemPalace is enabled, `agentic` writes a managed `.mempalaceignore` when the target project does not already have one. It initializes the project with `mempalace init --yes --no-llm`, then mines project knowledge into a wing named from the target project basename. If `docs/` exists, those files are also mined into the shared `shared_docs` wing for cross-project Markdown knowledge. MemPalace commands time out after `60` seconds by default; override with `AGENTIC_MEMPALACE_TIMEOUT_SECONDS`. If auto-install, initialization, mining, timeout, or runtime checks fail, install continues, manual setup instructions are printed, and agents fall back to standard context discovery. If `pip install mempalace` fails, `agentic` prints the pip exit status, a temporary pip output log path, and the first non-empty pip output line as the likely reason; the full pip output is also copied into the main Agentic run log.
+
+For environments that already provide `mempalace-mcp` and need a fast install path, set `AGENTIC_MEMPALACE_SETUP=skip`. This writes the same MCP configuration and `.mempalaceignore` but skips Python package installation and project indexing.
+
+## Real agent blackbox E2E
+
+`make test` runs the fast deterministic e2e suite and is intended to finish in under a minute on a normal local machine. Longer deterministic checks (`test-doctor`, `test-markers`), real-agent blackbox, and coverage checks are explicit targets so the default local loop stays short.
 
-## Real agent doctor E2E
+`make test-real-blackbox` validates real Codex/OpenCode install artifacts, generated guidance, MCP config, and manifest evidence without starting live LLM sessions by default. Set `AGENTIC_REAL_BLACKBOX_LIVE=1` to execute live `codex`/`opencode` runs. Live Telegram checks require Telegram credentials to be present in the target project `.agentic.json`; secrets are redacted from test output.
 
-The deterministic e2e suite uses fake agent binaries and does not call models. Real agent doctor checks are opt-in because they may use network access, credentials, and model credits:
+Makefile test targets print timestamped `[make-timing]` start, success/failure, exit status, and elapsed seconds for every top-level test step. `test-real-blackbox` is split into separate Codex, OpenCode, OpenCode mapper, and Telegram timed steps. Blackbox instruction evidence is saved to a `/tmp/agentic-instruction-evidence.*` file and the path is printed. `test-coverage` also prints timing for each traced coverage scenario before the final coverage parser. Use `make test-all` when you want the fast suite, longer deterministic checks, install/evidence blackbox, and coverage in one command.
 
 ```bash
-AGENTIC_RUN_REAL_AGENT_E2E=1 make test-real-agent-doctor
+make test-real-blackbox
+AGENTIC_REAL_BLACKBOX_LIVE=1 make test-real-blackbox
 ```
 
 ## Deprecated wrapper

package/docs/opencode_setup.md

@@ -33,16 +33,20 @@ When `agentic` installs the OpenCode extension, it configures optional plugins i
 ~/.config/agentic/opencode-plugins.json
 ```
 
-Telegram notifications and model checking are opt-in. If the config is absent or a plugin is disabled, the plugin returns no hooks and OpenCode continues without that behavior.
+Telegram notifications and agent model mapping are opt-in. Interactive `agentic install` and `agentic tui` ask for OpenCode plugin selection whenever `opencode` is selected; the answer rewrites this config. During manifest-based upgrade/re-install sync, existing plugin settings are kept so automated refreshes do not open prompts. If the config is absent or a plugin is disabled, the plugin returns no hooks and OpenCode continues without that behavior.
 
-Telegram notifications use either the stored config values or these environment variables:
+When `telegram-notification` is selected interactively, `agentic` asks for `botToken` and `chatId` and stores them in the target project's `.agentic.json`:
 
 ```text
-OPENCODE_TELEGRAM_BOT_TOKEN
-OPENCODE_TELEGRAM_CHAT_ID
+settings.opencode_plugins.telegram.botToken
+settings.opencode_plugins.telegram.chatId
 ```
 
+The runtime plugin reads credentials from the project `.agentic.json`; it does not read Telegram credentials from environment variables. This file stores credentials in plaintext, so do not commit a Telegram-enabled `.agentic.json` to public repositories.
+
 Non-interactive `agentic install` defaults optional plugins to disabled when no config exists.
 
+`agent-model-mapper` reads roles from target `.opencode/agents/*.md` and discovers model names from `~/.config/opencode/opencode.json`, then adds models from active providers in `~/.local/share/opencode/auth.json` using non-deprecated entries in `~/.cache/opencode/models.json`. When enabled, interactive `agentic install`/`agentic tui` prompts for a main and fallback model per role, using `fzf` as a dropdown picker when available, and writes `.opencode/opencode.json` only after a Confirm action. OpenCode startup never opens `fzf` or waits for model input; the runtime plugin only reports whether install-time mapping is complete.
+
 For OpenCode targets, `agentic` writes generated operating guidance to `.opencode/AGENTS.md`. If OpenCode is installed
 alongside another agent target, root `AGENTS.md` is generated as well for the non-OpenCode target.

package/extensions/opencode/opencode.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://opencode.ai/config.json",
   "plugin": [
-    "model-checker",
+    "agent-model-mapper",
     "sound-notification",
     "telegram-notification"
   ],

package/extensions/opencode/plugins/agent-model-mapper.ts

@@ -0,0 +1,117 @@
+import type { Plugin } from "@opencode-ai/plugin"
+import { existsSync, readFileSync } from "node:fs"
+import { readdir, readFile } from "node:fs/promises"
+import { basename, join } from "node:path"
+
+type AgenticPluginConfig = {
+  agentModelMapper?: {
+    enabled?: boolean
+  }
+  settings?: any
+}
+
+type Role = {
+  name: string
+  description: string
+  mode: string
+}
+
+function readAgenticConfig(): AgenticPluginConfig {
+  const configHome = process.env.XDG_CONFIG_HOME || join(process.env.HOME || "", ".config")
+  const configPath = join(configHome, "agentic", "opencode-plugins.json")
+
+  try {
+    return JSON.parse(readFileSync(configPath, "utf-8")) as AgenticPluginConfig
+  } catch {
+    return {}
+  }
+}
+
+function readProjectAgenticConfig(directory: string): AgenticPluginConfig {
+  try {
+    return JSON.parse(readFileSync(join(directory, ".agentic.json"), "utf-8")) as AgenticPluginConfig
+  } catch {
+    return {}
+  }
+}
+
+function parseFrontmatter(text: string): Record<string, string> {
+  if (!text.startsWith("---\n")) return {}
+  const end = text.indexOf("\n---", 4)
+  if (end === -1) return {}
+
+  const result: Record<string, string> = {}
+  for (const line of text.slice(4, end).split("\n")) {
+    const index = line.indexOf(":")
+    if (index === -1) continue
+    result[line.slice(0, index).trim()] = line.slice(index + 1).trim().replace(/^['"]|['"]$/g, "")
+  }
+  return result
+}
+
+async function readRoles(directory: string): Promise<Role[]> {
+  const agentsDir = join(directory, ".opencode", "agents")
+  let entries: string[]
+  try {
+    entries = await readdir(agentsDir)
+  } catch {
+    return []
+  }
+
+  const roles: Role[] = []
+  for (const entry of entries.sort()) {
+    if (!entry.endsWith(".md")) continue
+    const path = join(agentsDir, entry)
+    const text = await readFile(path, "utf-8")
+    const frontmatter = parseFrontmatter(text)
+    roles.push({
+      name: basename(entry, ".md"),
+      description: frontmatter.description || "OpenCode agent",
+      mode: frontmatter.mode || "subagent",
+    })
+  }
+  return roles
+}
+
+function readJsonIfExists(path: string): unknown {
+  if (!existsSync(path)) return undefined
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"))
+  } catch {
+    return undefined
+  }
+}
+
+function hasCompleteAgentModelMapping(directory: string, roles: Role[]): boolean {
+  const state = readJsonIfExists(join(directory, ".opencode", "agent-model-mapper.state.json")) as Record<string, any> | undefined
+  if (!state?.configured) return false
+
+  const config = readJsonIfExists(join(directory, ".opencode", "opencode.json")) as Record<string, any> | undefined
+  const agents = config?.agent
+  if (!agents || typeof agents !== "object") return false
+  return roles.every((role) => {
+    const agent = agents[role.name]
+    return agent && typeof agent === "object" && typeof agent.model === "string" && agent.model.trim().length > 0
+  })
+}
+
+export const AgentModelMapperPlugin: Plugin = async ({ directory }) => {
+  const projectConfig = readProjectAgenticConfig(directory)
+  const globalConfig = readAgenticConfig()
+  const enabled = projectConfig.settings?.opencode_plugins?.agentModelMapper?.enabled ?? globalConfig.agentModelMapper?.enabled
+  if (!enabled) return {}
+
+  const roles = await readRoles(directory)
+  if (!roles.length) {
+    console.log("agent-model-mapper: skipped because .opencode/agents/*.md was not found")
+    return {}
+  }
+
+  if (hasCompleteAgentModelMapping(directory, roles)) {
+    console.log("agent-model-mapper: skipped because all Agentic roles already have model mappings")
+    return {}
+  }
+
+  console.log("agent-model-mapper: install-time model mapping is required; run agentic install or agentic tui")
+  return {}
+}

package/extensions/opencode/plugins/telegram-notification.ts

@@ -3,17 +3,27 @@ import { readFileSync } from "node:fs"
 import { join } from "node:path"
 
 type AgenticPluginConfig = {
-  telegram?: {
-    enabled?: boolean
-    botToken?: string
-    chatId?: string
-  }
+  settings?: any
+}
+
+function telegramApiBaseUrl(): string {
+  return process.env.OPENCODE_TELEGRAM_API_BASE_URL || "https://api.telegram.org"
+}
+
+function telegramUrl(botToken: string, method: string): string {
+  return `${telegramApiBaseUrl()}/bot${botToken}/${method}`
 }
 
-function readAgenticConfig(): AgenticPluginConfig {
-  const configHome = process.env.XDG_CONFIG_HOME || join(process.env.HOME || "", ".config")
-  const configPath = join(configHome, "agentic", "opencode-plugins.json")
+function redactSecret(value: unknown): string {
+  const text = String(value)
+  const telegram = currentTelegramConfig
+  const token = telegram?.botToken
+  const chatId = telegram?.chatId
+  return [token, chatId].filter(Boolean).reduce((output, secret) => output.split(secret as string).join("[redacted]"), text)
+}
 
+function readAgenticConfig(directory: string): AgenticPluginConfig {
+  const configPath = join(directory, ".agentic.json")
   try {
     return JSON.parse(readFileSync(configPath, "utf-8")) as AgenticPluginConfig
   } catch {
@@ -21,19 +31,19 @@ function readAgenticConfig(): AgenticPluginConfig {
   }
 }
 
+let currentTelegramConfig
+
 export const TelegramNotificationPlugin: Plugin = async ({ $, client, directory }) => {
-  const config = readAgenticConfig()
-  const telegram = config.telegram
-  const botToken = process.env.OPENCODE_TELEGRAM_BOT_TOKEN || telegram?.botToken
-  const chatId = process.env.OPENCODE_TELEGRAM_CHAT_ID || telegram?.chatId
+  const config = readAgenticConfig(directory)
+  const telegram = config.settings?.opencode_plugins?.telegram
+  currentTelegramConfig = telegram
+  const botToken = telegram?.botToken
+  const chatId = telegram?.chatId
 
   if (!telegram?.enabled || !botToken || !chatId) {
     return {}
   }
 
-  process.env.OPENCODE_TELEGRAM_BOT_TOKEN = botToken
-  process.env.OPENCODE_TELEGRAM_CHAT_ID = chatId
-
   return {
     event: async ({ event }) => {
       if (event.type === "session.idle") {
@@ -60,7 +70,7 @@ export const TelegramNotificationPlugin: Plugin = async ({ $, client, directory
             }
           }
         } catch (e) {
-          await $`echo "Error: ${e}" >> ${directory}/.opencode/telegram-debug.log`
+          await $`echo "Error: ${redactSecret(e)}" >> ${directory}/.opencode/telegram-debug.log`
         }
 
         try {
@@ -74,19 +84,19 @@ export const TelegramNotificationPlugin: Plugin = async ({ $, client, directory
             )
 
             await fetch(
-              `https://api.telegram.org/bot${botToken}/sendDocument`,
+              telegramUrl(botToken, "sendDocument"),
               { method: "POST", body: formData }
             )
 
             const shortText = fullText.slice(0, 3000)
             await fetch(
-              `https://api.telegram.org/bot${botToken}/sendMessage`,
+              telegramUrl(botToken, "sendMessage"),
               {
                 method: "POST",
                 headers: { "Content-Type": "application/json" },
                 body: JSON.stringify({
                   chat_id: chatId,
-                  text: `${messageText}\n\n📎 Полный ответ в attachment (${fullText.length} символов):\n\n${shortText}...`
+                  text: `${messageText}\n\nПолный ответ в attachment (${fullText.length} символов):\n\n${shortText}...`
                 })
               }
             )
@@ -96,7 +106,7 @@ export const TelegramNotificationPlugin: Plugin = async ({ $, client, directory
               : messageText
 
             await fetch(
-              `https://api.telegram.org/bot${botToken}/sendMessage`,
+              telegramUrl(botToken, "sendMessage"),
               {
                 method: "POST",
                 headers: { "Content-Type": "application/json" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jetrabbits/agentic",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Agent Intelligence Configuration CLI",
   "bin": {
     "agentic": "bin/agentic.js"
@@ -11,6 +11,7 @@
   },
   "files": [
     "AGENTS.md",
+    "MEMORY.md",
     "CHANGELOG.md",
     "UPGRADE.md",
     "LICENSE",

package/extensions/opencode/plugins/model-checker.json

@@ -1,13 +0,0 @@
-{
-  "models": [
-    "openai/gpt-5.5",
-    "opencode/big-pickle",
-    "opencode/minimax-m2.5-free",
-    "google/antigravity-claude-opus-4-6-thinking",
-    "google/antigravity-claude-sonnet-4-6",
-    "google/antigravity-gemini-3-flash",
-    "google/antigravity-gemini-3.1-pro"
-  ],
-  "timeoutMs": 2000,
-  "concurrency": 10
-}