@jetrabbits/agentic 0.1.0 → 0.3.0

package/docs/agentic-lifecycle.md

@@ -104,11 +104,11 @@ Every copied or generated file carries an internal marker. Markdown uses YAML fr
 
 ## MemPalace install and validation logs
 
-When MemPalace MCP is enabled during interactive install, `agentic` now reports setup progress in explicit steps so users can see what succeeded or failed:
+When MemPalace MCP is enabled during interactive install, TUI install, or through `AGENTIC_ENABLE_MEMPALACE=y`, `agentic` now reports setup progress in explicit steps so users can see what succeeded or failed:
 
 1. Python availability check
 2. pip availability check
 3. `pip install mempalace`
-4. Project initialization (`mempalace init` and `mempalace mine`)
+4. Explicit skip log for automatic project initialization, plus optional manual `mempalace init`/`mempalace mine` instructions
 
-After setup, runtime validation uses `mempalace-mcp --help` (the MCP entrypoint) instead of validating only the Python module import path. This avoids false warnings where the package is installed successfully but a pre-install runtime probe ran too early.
+If auto-install or runtime checks fail, `agentic` prints manual setup instructions and continues. After setup, install checks that `mempalace-mcp` is present and leaves runtime startup/tool validation to the post-install doctor smoke check. Generated MCP configs invoke `mempalace-mcp` without arguments for all supported agent targets.

package/docs/agentic-stabilization/README.md

@@ -0,0 +1,33 @@
+# 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` and `--sandbox workspace-write`.
+- 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 no longer asks for an API key; it uses `CONTEXT7_API_KEY` when set and otherwise prints config-path guidance for adding one later.
+- OpenCode MemPalace setup writes `mempalace-mcp` config without running `mempalace init` automatically.
+- Telegram notification credentials are read only from `OPENCODE_TELEGRAM_BOT_TOKEN` and `OPENCODE_TELEGRAM_CHAT_ID`.
+- MemPalace-enabled installs create a managed `.mempalaceignore` unless the target project already has one.
+- Real Codex, OpenCode, and Telegram blackbox scenarios are part of `make test`.
+- `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, instruction evidence, MCP usage prompts, and MemPalace fact prompts without printing Telegram secrets.
+
+## Operational Constraints
+
+- `make test` now requires real `codex` and `opencode` binaries, working model auth, network access, Context7/MemPalace access, and Telegram credentials.
+- 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

@@ -54,7 +54,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 is configured without a key unless `CONTEXT7_API_KEY` is already set; the install output prints the config path(s) and an example key placement. 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

@@ -30,6 +30,23 @@ Default behavior:
 - In non-interactive mode (CI/pipe): prints usage and exits with code `1`
 - For CI one-off execution, prefer `npx @jetrabbits/agentic@latest <command>`
 
+## Requirements
+
+`agentic install` and `agentic tui` fail fast when required local tools are missing:
+
+- Bash 3.2+.
+- Python 3 as `python3`.
+- pip as `pip3`, `pip`, or `python3 -m pip`.
+- `shasum` or `sha256sum` for managed-file hashes.
+- Git when installed mode needs to bootstrap or upgrade `~/.local/share/agentic/repo`.
+
+Optional tools:
+
+- `fzf` for interactive picker UI; index-based menus are used when it is unavailable.
+- Node.js/npm only for the `npx @jetrabbits/agentic@latest` entrypoint.
+- `curl` only for the bootstrap installer.
+- Real agent binaries only for selected target recommendations and doctor checks.
+
 Install the standalone binary:
 
 ```bash
@@ -75,6 +92,26 @@ agentic install \
 
 After install, `agentic` writes `.agentic.json` in the target project. It records copied/generated files and their hashes. A later install rerun updates only manifest-managed files and skips files changed by the user. Generated guidance is written to root `AGENTS.md` for most agents and to `.opencode/AGENTS.md` when OpenCode is selected; multi-target installs that include OpenCode and another agent write both files.
 
+After the project files are generated, `agentic` starts timestamped operational logging and mirrors install output to a temporary log file such as:
+
+```text
+/tmp/agentic-20260512-114203.ABC123
+```
+
+The final install line prints the exact path:
+
+```text
+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 in a temporary copy of the project and prints one status row per selected agent. OpenCode uses a lightweight pure smoke prompt instead of the full `develop-feature` command, 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 ...
+# or
+agentic install ... --no-doctor
+```
+
 List available options:
 
 ```bash
@@ -126,31 +163,35 @@ 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. Telegram reads `OPENCODE_TELEGRAM_BOT_TOKEN` and `OPENCODE_TELEGRAM_CHAT_ID` from the environment only; tokens are not written to `~/.config/agentic/opencode-plugins.json`. 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 confirmation. 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, Context7 is configured without a key unless `CONTEXT7_API_KEY` is already set in the environment. The install output prints the generated config path(s) and an example showing where to add the key later. 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:
+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`.
 
-```bash
-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` writes a managed `.mempalaceignore` when the target project does not already have one. OpenCode installs do not run `mempalace init` automatically; project indexing is optional and printed as a manual follow-up. If auto-install or runtime checks fail, install continues, manual setup instructions are printed, and agents fall back to standard context discovery.
 
-Generated configs run `mempalace-mcp --palace .mempalace` (or equivalent `command`/`args` format per IDE) so each project uses its local `.mempalace` directory.
+## Real agent blackbox E2E
 
-During install, if MemPalace is enabled, `agentic` also runs a runtime check using `python3 -m mempalace --help`. For OpenCode installs, `agentic` creates `<project>/.mempalace` and runs `mempalace init "<project>/.mempalace" --yes --auto-mine`. If checks fail (for example, package not installed yet), install continues and agents fall back to standard context discovery.
+`make test` includes real Codex, OpenCode, and Telegram blackbox scenarios. The local environment must provide working `codex`, `opencode`, Context7/MemPalace access, network access, valid auth, and Telegram credentials in `OPENCODE_TELEGRAM_BOT_TOKEN` and `OPENCODE_TELEGRAM_CHAT_ID`. Secrets are redacted from test output.
+
+```bash
+make test-real-blackbox
+```
 
 ## Deprecated wrapper
 

package/docs/opencode_setup.md

@@ -33,9 +33,9 @@ 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. 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:
+Telegram notifications read credentials from environment variables only:
 
 ```text
 OPENCODE_TELEGRAM_BOT_TOKEN
@@ -44,5 +44,7 @@ OPENCODE_TELEGRAM_CHAT_ID
 
 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`, falling back to a built-in list only when that file has no model names. 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 confirmation. 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,106 @@
+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
+  }
+}
+
+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 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 config = readAgenticConfig()
+  if (!config.agentModelMapper?.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

@@ -5,11 +5,24 @@ import { join } from "node:path"
 type AgenticPluginConfig = {
   telegram?: {
     enabled?: boolean
-    botToken?: string
-    chatId?: string
   }
 }
 
+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 redactSecret(value: unknown): string {
+  const text = String(value)
+  const token = process.env.OPENCODE_TELEGRAM_BOT_TOKEN
+  const chatId = process.env.OPENCODE_TELEGRAM_CHAT_ID
+  return [token, chatId].filter(Boolean).reduce((output, secret) => output.split(secret as string).join("[redacted]"), text)
+}
+
 function readAgenticConfig(): AgenticPluginConfig {
   const configHome = process.env.XDG_CONFIG_HOME || join(process.env.HOME || "", ".config")
   const configPath = join(configHome, "agentic", "opencode-plugins.json")
@@ -24,16 +37,13 @@ function readAgenticConfig(): AgenticPluginConfig {
 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 botToken = process.env.OPENCODE_TELEGRAM_BOT_TOKEN
+  const chatId = process.env.OPENCODE_TELEGRAM_CHAT_ID
 
   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,13 +84,13 @@ 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" },
@@ -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.1.0",
+  "version": "0.3.0",
   "description": "Agent Intelligence Configuration CLI",
   "bin": {
     "agentic": "bin/agentic.js"
@@ -11,6 +11,8 @@
   },
   "files": [
     "AGENTS.md",
+    "MEMORY.md",
+    "CHANGELOG.md",
     "UPGRADE.md",
     "LICENSE",
     "Makefile",

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
-}