pantheon-opencode 1.6.0-beta.9 → 1.6.1

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 (140) hide show
  1. package/AGENTS.global.md +118 -0
  2. package/AGENTS.md +18 -168
  3. package/CHANGELOG.md +144 -365
  4. package/README.md +124 -607
  5. package/README.pt-BR.md +120 -345
  6. package/bin/pantheon-init.mjs +504 -141
  7. package/commands/pantheon-deepwork.md +14 -3
  8. package/commands/pantheon-vision.md +61 -12
  9. package/package.json +22 -13
  10. package/plugin.json +1 -1
  11. package/pyproject.toml +6 -2
  12. package/scripts/_pantheon_paths.py +24 -0
  13. package/scripts/build-agents-md.mjs +368 -69
  14. package/scripts/changelog-merge.mjs +161 -0
  15. package/scripts/check-plugin-v2-coverage.mjs +11 -8
  16. package/scripts/docs-check-changelog.mjs +204 -0
  17. package/scripts/docs-link-check.mjs +314 -0
  18. package/scripts/docs-media.mjs +157 -0
  19. package/scripts/doctor.mjs +850 -45
  20. package/scripts/install/agents-md.mjs +2 -2
  21. package/scripts/install/backup.mjs +648 -0
  22. package/scripts/install/cli-ui.mjs +303 -72
  23. package/scripts/install/component-selection.mjs +61 -0
  24. package/scripts/install/config-migration.mjs +583 -27
  25. package/scripts/install/exit-codes.mjs +26 -0
  26. package/scripts/install/file-inventory.mjs +555 -0
  27. package/scripts/install/health-check.mjs +31 -25
  28. package/scripts/install/interactive.mjs +99 -383
  29. package/scripts/install/interrupt.mjs +78 -0
  30. package/scripts/install/migrate.mjs +49 -25
  31. package/scripts/install/model-picker.mjs +218 -250
  32. package/scripts/install/opencode-state.mjs +91 -0
  33. package/scripts/install/opencode-version.mjs +83 -21
  34. package/scripts/install/opencode.mjs +1675 -187
  35. package/scripts/install/plan-artifact.mjs +517 -0
  36. package/scripts/install/plan.mjs +475 -0
  37. package/scripts/install/plugin.mjs +214 -27
  38. package/scripts/install/prompt-result.mjs +2 -0
  39. package/scripts/install/run-record.mjs +115 -0
  40. package/scripts/install/shared.mjs +256 -99
  41. package/scripts/install/state.mjs +63 -8
  42. package/scripts/install/strings.mjs +93 -8
  43. package/scripts/install/v2-capabilities.mjs +205 -0
  44. package/scripts/install/venv.mjs +90 -47
  45. package/scripts/install/verify.mjs +128 -0
  46. package/scripts/install/vision-prompt.mjs +173 -0
  47. package/scripts/install-mcp.mjs +2 -2
  48. package/scripts/manifest-inventory.mjs +49 -3
  49. package/scripts/mcp_persistence.py +1535 -1050
  50. package/scripts/memory_mcp.py +12 -843
  51. package/scripts/node-engine-policy.mjs +85 -0
  52. package/scripts/package-evidence.mjs +10 -2
  53. package/scripts/postinstall.mjs +26 -26
  54. package/scripts/probe-pantheon-cost.mjs +118 -19
  55. package/scripts/prune.mjs +9 -3
  56. package/scripts/reconcile.mjs +325 -0
  57. package/scripts/release-gates.mjs +687 -0
  58. package/scripts/restore.mjs +222 -0
  59. package/scripts/run-node-tests.mjs +24 -8
  60. package/scripts/sync-artifacts.mjs +19 -7
  61. package/scripts/sync-tui.mjs +5 -1
  62. package/scripts/test-opencode-v2-sandbox.sh +36 -123
  63. package/scripts/uninstall.mjs +369 -34
  64. package/scripts/update.mjs +164 -0
  65. package/scripts/validate-node-engine-policy.mjs +13 -0
  66. package/scripts/version-check.mjs +34 -1
  67. package/scripts/versioning.mjs +23 -3
  68. package/scripts/vision-status.mjs +682 -0
  69. package/skills-lock.json +8 -8
  70. package/src/agents/aphrodite.md +13 -10
  71. package/src/agents/apollo.md +4 -5
  72. package/src/agents/athena.md +74 -46
  73. package/src/agents/demeter.md +10 -7
  74. package/src/agents/gaia.md +0 -1
  75. package/src/agents/hephaestus.md +4 -3
  76. package/src/agents/hermes.md +10 -9
  77. package/src/agents/iris.md +6 -1
  78. package/src/agents/mnemosyne.md +10 -4
  79. package/src/agents/nyx.md +4 -4
  80. package/src/agents/prometheus.md +12 -11
  81. package/src/agents/talos.md +6 -0
  82. package/src/agents/zeus.md +84 -56
  83. package/src/instructions/agent-return-format.instructions.md +12 -41
  84. package/src/instructions/memory-protocol.instructions.md +5 -11
  85. package/src/instructions/test-economy.instructions.md +12 -0
  86. package/src/instructions/yagni.instructions.md +6 -15
  87. package/src/instructions/zeus-anti-stall.instructions.md +6 -6
  88. package/src/instructions/zeus-communication-rules.instructions.md +6 -6
  89. package/src/instructions/zeus-council-synthesis.instructions.md +11 -12
  90. package/src/instructions/zeus-memory-operations.instructions.md +13 -7
  91. package/src/instructions/zeus-timeout-retry.instructions.md +36 -10
  92. package/src/mcp/_pantheon_paths.py +24 -0
  93. package/src/mcp/mcp_codemap_module.py +86 -18
  94. package/src/mcp/mcp_persistence.py +1535 -1050
  95. package/src/mcp/memory_mcp.py +444 -94
  96. package/src/mcp/pantheon_vision.py +285 -41
  97. package/src/mcp/requirements-mcp.txt +6 -1
  98. package/src/mcp/requirements-vision.txt +1 -1
  99. package/src/pantheon/context-pruner.ts +541 -0
  100. package/src/pantheon/cost-command.ts +901 -60
  101. package/src/pantheon/delegation-enforce.ts +160 -23
  102. package/src/pantheon/goal-loop.ts +11 -8
  103. package/src/pantheon/guard-path.ts +162 -0
  104. package/src/pantheon/memory-context.ts +1017 -0
  105. package/src/pantheon/model-agents.ts +19 -0
  106. package/src/pantheon/model-command.ts +218 -56
  107. package/src/pantheon/model-pricing.ts +536 -0
  108. package/src/pantheon/presets.mjs +2 -0
  109. package/src/pantheon/task-result-guard.ts +50 -14
  110. package/src/pantheon/v2-bounded-read.ts +654 -0
  111. package/src/pantheon/v2-bridge.ts +27 -0
  112. package/src/pantheon/v2-delegation-enforce.ts +133 -6
  113. package/src/pantheon/v2-execute-after.ts +135 -24
  114. package/src/pantheon/v2-model-overrides.ts +275 -0
  115. package/src/pantheon/v2-shell-hooks.ts +260 -0
  116. package/src/pantheon/v2-tools.ts +89 -35
  117. package/src/pantheon/v2-unsupported.mjs +34 -7
  118. package/src/pantheon/v2-vision.ts +622 -0
  119. package/src/pantheon/vision-local.ts +531 -0
  120. package/src/pantheon/vision.ts +1166 -116
  121. package/src/plugin-v2.ts +1039 -171
  122. package/src/plugin.ts +37 -13
  123. package/src/plugins/tui/dist/tui-v2.d.ts +1029 -2
  124. package/src/plugins/tui/dist/tui-v2.d.ts.map +1 -1
  125. package/src/plugins/tui/dist/tui-v2.js +3742 -85
  126. package/src/plugins/tui/dist/tui.js +1 -1
  127. package/src/plugins/tui/package-lock.json +15 -15
  128. package/src/plugins/tui/package.json +7 -5
  129. package/src/plugins/tui/src/index-v2.tsx +4314 -50
  130. package/src/plugins/tui/tsconfig.typecheck.json +5 -0
  131. package/src/routing.yml +50 -5
  132. package/src/skills/agent-coordination/SKILL.md +7 -2
  133. package/src/skills/artifact-management/SKILL.md +5 -1
  134. package/src/skills/auto-continue/SKILL.md +14 -6
  135. package/src/skills/codemap/SKILL.md +1 -1
  136. package/src/skills/memory-bank/SKILL.md +21 -13
  137. package/src/skills/session-goal/SKILL.md +12 -22
  138. package/src/skills/spec-driven-development/SKILL.md +3 -1
  139. package/src/skills/worktrees/SKILL.md +30 -11
  140. package/scripts/probe-context-rehydrate.mjs +0 -263
@@ -20,27 +20,57 @@
20
20
  * "skills": { "version": 1, "status": "installed" },
21
21
  * "plugins": { "version": 1, "status": "installed" },
22
22
  * "runtime": { "version": 1, "status": "installed" }
23
+ * },
24
+ * "file_inventory": {
25
+ * "schema_version": 1, "target_root": "/absolute/target",
26
+ * "legacy_unknown": false, "entries": []
23
27
  * }
24
28
  * }
25
29
  */
26
30
 
27
- import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
28
- import { join } from 'node:path'
31
+ import { existsSync, mkdirSync, readFileSync } from 'node:fs'
32
+ import { join, resolve } from 'node:path'
33
+ import { assertNoSymlinkAncestors, writeFileAtomically } from './verify.mjs'
29
34
 
30
35
  const STATE_FILE = 'install-state.json'
31
36
  const STATE_DIR = '.pantheon'
32
37
 
38
+ function emptyFileInventory(legacyUnknown = true) {
39
+ return {
40
+ schema_version: 1,
41
+ target_root: null,
42
+ legacy_unknown: legacyUnknown,
43
+ entries: [],
44
+ }
45
+ }
46
+
47
+ function invalidFileInventory() {
48
+ return { schema_version: 0, target_root: null, legacy_unknown: true, entries: [] }
49
+ }
50
+
51
+ function normalizeFileInventory(state) {
52
+ if (!Object.hasOwn(state, 'file_inventory')) return emptyFileInventory(true)
53
+ if (
54
+ !state.file_inventory ||
55
+ typeof state.file_inventory !== 'object' ||
56
+ Array.isArray(state.file_inventory)
57
+ ) {
58
+ return invalidFileInventory()
59
+ }
60
+ return state.file_inventory
61
+ }
62
+
33
63
  /**
34
64
  * Create a fresh v2 state object for a new install.
35
65
  * @param {string} version - Pantheon version string
36
66
  * @returns {object} v2 state
37
67
  */
38
- export function createInitialState(version) {
68
+ export function createInitialState(version, updatedAt = new Date().toISOString()) {
39
69
  return {
40
70
  schema_version: 2,
41
71
  pantheon_version: version || '0.0.0',
42
72
  previous_version: null,
43
- updated_at: new Date().toISOString(),
73
+ updated_at: updatedAt,
44
74
  migration_checkpoint: null,
45
75
  applied_migrations: [],
46
76
  components: {
@@ -49,6 +79,7 @@ export function createInitialState(version) {
49
79
  plugins: { version: 1, status: 'pending' },
50
80
  runtime: { version: 1, status: 'pending' },
51
81
  },
82
+ file_inventory: emptyFileInventory(false),
52
83
  }
53
84
  }
54
85
 
@@ -104,6 +135,7 @@ export function upgradeStateV1toV2(state) {
104
135
  plugins: { version: 1, status: 'unknown' },
105
136
  runtime: { version: 1, status: 'unknown' },
106
137
  },
138
+ file_inventory: normalizeFileInventory(state),
107
139
  }
108
140
  }
109
141
 
@@ -129,6 +161,14 @@ function ensureV2Shape(state) {
129
161
  ) {
130
162
  state.components = upgradeStateV1toV2(state).components
131
163
  }
164
+ if (!Object.hasOwn(state, 'file_inventory')) state.file_inventory = emptyFileInventory(true)
165
+ else if (
166
+ !state.file_inventory ||
167
+ typeof state.file_inventory !== 'object' ||
168
+ Array.isArray(state.file_inventory)
169
+ ) {
170
+ state.file_inventory = invalidFileInventory()
171
+ }
132
172
  return state
133
173
  }
134
174
 
@@ -149,15 +189,30 @@ function normalizeState(state) {
149
189
  * @param {string} target - Installation directory
150
190
  * @param {object} state - v2 state object
151
191
  */
152
- export function writeState(target, state) {
192
+ export function writeState(target, state, options = {}) {
153
193
  const stateDir = join(target, STATE_DIR)
194
+ const stateFile = join(stateDir, STATE_FILE)
195
+ assertNoSymlinkAncestors(stateFile)
154
196
  if (!existsSync(stateDir)) {
155
197
  mkdirSync(stateDir, { recursive: true })
156
198
  }
157
- const stateFile = join(stateDir, STATE_FILE)
158
- state.updated_at = new Date().toISOString()
199
+ assertNoSymlinkAncestors(stateFile)
200
+ state.updated_at = options.updatedAt ?? new Date().toISOString()
159
201
  state.schema_version = 2
160
- writeFileSync(stateFile, `${JSON.stringify(state, null, 2)}\n`, 'utf8')
202
+ if (!Object.hasOwn(state, 'file_inventory')) {
203
+ state.file_inventory = emptyFileInventory(true)
204
+ } else if (
205
+ !state.file_inventory ||
206
+ typeof state.file_inventory !== 'object' ||
207
+ Array.isArray(state.file_inventory)
208
+ ) {
209
+ state.file_inventory = invalidFileInventory()
210
+ }
211
+ if (state.file_inventory.target_root == null) {
212
+ state.file_inventory.target_root = resolve(target)
213
+ }
214
+ const content = `${JSON.stringify(state, null, 2)}\n`
215
+ writeFileAtomically(stateFile, content)
161
216
  }
162
217
 
163
218
  /**
@@ -14,15 +14,38 @@ const TABLE = {
14
14
  en: {
15
15
  installing: 'Installing...',
16
16
  dryRun: 'DRY RUN',
17
- canceled: 'Installation canceled — nothing was broken; run init again anytime.',
18
- canceledShort: 'Installation canceled.',
19
- installFailed: (msg) => `❌ Installation failed: ${msg}`,
17
+ // Every termination that applies nothing names WHERE it stopped and WHAT
18
+ // the consequence is. `cancelPoints` are stable machine keys: the same key
19
+ // goes into the on-disk run record, so a re-run can report the point
20
+ // without parsing prose.
21
+ cancelPoints: {
22
+ components: 'component selection',
23
+ target: 'install location',
24
+ confirmation: 'pre-install confirmation',
25
+ review: 'review prompt',
26
+ interrupt: 'interrupt (Ctrl-C)',
27
+ },
28
+ // "no configuration was changed", not "no files were written": a cancel
29
+ // does write `.pantheon/last-run.json` (that is the point of #262), so the
30
+ // stronger claim would be false.
31
+ canceledAt: (point) =>
32
+ `Installation canceled at ${point} — nothing was applied; no configuration was changed.`,
33
+ declinedAt: (point) =>
34
+ `Installation declined at ${point} — nothing was applied; no configuration was changed; ` +
35
+ 're-run init to review the plan again.',
36
+ previousRun: (summary) => `Previous run recorded on disk: ${summary}`,
37
+ runRecordFailed: (msg) => `Could not write the run record: ${msg}`,
38
+ installFailed: (msg) => `Installation failed: ${msg}`,
20
39
  failHintNoMcp:
21
40
  ' Run with --no-mcp to skip Python dependencies:\n npx pantheon-opencode init --no-mcp',
22
41
  failHintForce:
23
42
  ' Or retry with --force to recreate the venv:\n npx pantheon-opencode init --force',
24
43
  runningHealthCheck: 'Running health check...',
25
- installedTitle: (v) => `✅ Pantheon OpenCode v${v} installed!`,
44
+ healthCheckFinished: (seconds, status) =>
45
+ `Health check finished in ${seconds}s (exit ${status})`,
46
+ healthCheckExit: (seconds, status) =>
47
+ `Health check finished in ${seconds}s and reported problems (exit ${status}); the installation itself completed`,
48
+ installedTitle: (v) => `Pantheon OpenCode v${v} installed.`,
26
49
  nextSteps: 'Next steps:',
27
50
  nextVerify: '1. Verify installation:\n npx pantheon-opencode doctor',
28
51
  nextLaunch: '2. Launch OpenCode',
@@ -37,7 +60,17 @@ const TABLE = {
37
60
  installingPrompts: 'Installing prompts',
38
61
  installingCommands: 'Installing commands',
39
62
  installingPlugins: 'Installing plugins',
63
+ installingTuiDeps: 'Installing TUI dependencies',
64
+ creatingBackup: 'Creating exact backup set',
65
+ planningBackup: 'Planning backup set',
66
+ checkingPrerequisites: 'Checking prerequisites',
67
+ installingRuntime: 'Installing runtime',
68
+ writingConfiguration: 'Writing configuration',
69
+ writingConfig: 'Writing opencode.json',
70
+ runningMigrations: 'Running migrations',
71
+ recordingState: 'Recording install state',
40
72
  settingUpRuntime: 'Setting up Python virtual environment',
73
+ runtimeVerifiedAfterApply: 'Python runtime will be verified after apply',
41
74
  healthSection: 'Health Check',
42
75
  runningHealthChecks: 'Running health checks',
43
76
  runtimeFailed: (msg) => `Python runtime setup failed: ${msg}`,
@@ -46,7 +79,20 @@ const TABLE = {
46
79
  'Fix python3 (or free disk space) and re-run init to add them; everything else was installed.',
47
80
  prereqMissing:
48
81
  'runtime prerequisites missing — install the tools above, or re-run with --no-mcp to install without Python MCP servers',
82
+ mcpAskNotEnforceable: (server) =>
83
+ `MCP permission "permission.mcp.${server} = ask" is not enforceable on OpenCode 2.x: ` +
84
+ `the server's tools remain available and no permission prompt is shown. ` +
85
+ `Use "deny" with action "${server}_*" in "permissions", or disable the server in the host MCP config.`,
49
86
  v2Migrating: 'Migrating config to V2 native format...',
87
+ planOnlyNoYes: 'Plan only — re-run with --yes to apply.',
88
+ driftHeader: 'State changed since preview — aborting before any write:',
89
+ driftAbort: 'No files were written. Re-run to re-review.',
90
+ applyFailed: (msg) => `Apply failed: ${msg}`,
91
+ alreadyApplied: 'Paths already applied — no automatic rollback:',
92
+ restoreRecoveryHint: (dir) => `Recover with: pantheon-opencode restore (backup at ${dir})`,
93
+ restoreNoBackup:
94
+ 'No backup was created (the failure occurred before the first write); the target is unchanged.',
95
+ dryRunNothingWritten: 'Preview only — no files were written.',
50
96
  // summary (printSummary)
51
97
  summaryInstalled: (target) => `OpenCode installed in ${target}`,
52
98
  summaryWithErrors: (target) => `Installation finished WITH ERRORS in ${target}`,
@@ -62,15 +108,31 @@ const TABLE = {
62
108
  pt: {
63
109
  installing: 'Instalando...',
64
110
  dryRun: 'SIMULAÇÃO',
65
- canceled: 'Instalação cancelada — nada foi quebrado; rode init de novo quando quiser.',
66
- canceledShort: 'Instalação cancelada.',
67
- installFailed: (msg) => `❌ Instalação falhou: ${msg}`,
111
+ cancelPoints: {
112
+ components: 'seleção de componentes',
113
+ target: 'local da instalação',
114
+ confirmation: 'confirmação antes de instalar',
115
+ review: 'prompt de revisão',
116
+ interrupt: 'interrupção (Ctrl-C)',
117
+ },
118
+ canceledAt: (point) =>
119
+ `Instalação cancelada em ${point} — nada foi aplicado; nenhuma configuração foi alterada.`,
120
+ declinedAt: (point) =>
121
+ `Instalação recusada em ${point} — nada foi aplicado; nenhuma configuração foi alterada; ` +
122
+ 'rode init de novo para revisar o plano.',
123
+ previousRun: (summary) => `Execução anterior registrada em disco: ${summary}`,
124
+ runRecordFailed: (msg) => `Não foi possível gravar o registro da execução: ${msg}`,
125
+ installFailed: (msg) => `Instalação falhou: ${msg}`,
68
126
  failHintNoMcp:
69
127
  ' Rode com --no-mcp para pular dependências Python:\n npx pantheon-opencode init --no-mcp',
70
128
  failHintForce:
71
129
  ' Ou tente de novo com --force para recriar a venv:\n npx pantheon-opencode init --force',
72
130
  runningHealthCheck: 'Rodando verificação de saúde...',
73
- installedTitle: (v) => `✅ Pantheon OpenCode v${v} instalado!`,
131
+ healthCheckFinished: (seconds, status) =>
132
+ `Verificação de saúde concluída em ${seconds}s (exit ${status})`,
133
+ healthCheckExit: (seconds, status) =>
134
+ `Verificação de saúde concluída em ${seconds}s e reportou problemas (exit ${status}); a instalação em si foi concluída`,
135
+ installedTitle: (v) => `Pantheon OpenCode v${v} instalado.`,
74
136
  nextSteps: 'Próximos passos:',
75
137
  nextVerify: '1. Verifique a instalação:\n npx pantheon-opencode doctor',
76
138
  nextLaunch: '2. Abra o OpenCode',
@@ -85,7 +147,17 @@ const TABLE = {
85
147
  installingPrompts: 'Instalando prompts',
86
148
  installingCommands: 'Instalando comandos',
87
149
  installingPlugins: 'Instalando plugins',
150
+ installingTuiDeps: 'Instalando dependências da TUI',
151
+ creatingBackup: 'Criando conjunto de backup exato',
152
+ planningBackup: 'Planejando conjunto de backup',
153
+ checkingPrerequisites: 'Verificando pré-requisitos',
154
+ installingRuntime: 'Instalando runtime',
155
+ writingConfiguration: 'Escrevendo configuração',
156
+ writingConfig: 'Escrevendo opencode.json',
157
+ runningMigrations: 'Executando migrações',
158
+ recordingState: 'Registrando estado da instalação',
88
159
  settingUpRuntime: 'Configurando ambiente virtual Python',
160
+ runtimeVerifiedAfterApply: 'O runtime Python será verificado após a aplicação',
89
161
  healthSection: 'Verificação de saúde',
90
162
  runningHealthChecks: 'Rodando verificações de saúde',
91
163
  runtimeFailed: (msg) => `Falha ao configurar o runtime Python: ${msg}`,
@@ -94,7 +166,20 @@ const TABLE = {
94
166
  'Corrija o python3 (ou libere espaço em disco) e rode init de novo para adicioná-los; todo o resto foi instalado.',
95
167
  prereqMissing:
96
168
  'pré-requisitos do runtime ausentes — instale as ferramentas acima, ou rode de novo com --no-mcp para instalar sem os MCPs Python',
169
+ mcpAskNotEnforceable: (server) =>
170
+ `A permissão MCP "permission.mcp.${server} = ask" não é aplicável no OpenCode 2.x: ` +
171
+ `as tools do servidor continuam disponíveis e nenhum prompt de permissão é exibido. ` +
172
+ `Use "deny" com a action "${server}_*" em "permissions", ou desative o servidor na config de MCP do host.`,
97
173
  v2Migrating: 'Migrando config para o formato nativo V2...',
174
+ planOnlyNoYes: 'Apenas o plano — rode de novo com --yes para aplicar.',
175
+ driftHeader: 'O estado mudou desde o preview — abortando antes de qualquer escrita:',
176
+ driftAbort: 'Nenhum arquivo foi escrito. Rode de novo para revisar.',
177
+ applyFailed: (msg) => `Falha ao aplicar: ${msg}`,
178
+ alreadyApplied: 'Caminhos já aplicados — sem rollback automático:',
179
+ restoreRecoveryHint: (dir) => `Recupere com: pantheon-opencode restore (backup em ${dir})`,
180
+ restoreNoBackup:
181
+ 'Nenhum backup foi criado (a falha ocorreu antes da primeira escrita); o alvo está intacto.',
182
+ dryRunNothingWritten: 'Somente prévia — nenhum arquivo foi escrito.',
98
183
  // summary (printSummary)
99
184
  summaryInstalled: (target) => `OpenCode instalado em ${target}`,
100
185
  summaryWithErrors: (target) => `Instalação concluída COM ERROS em ${target}`,
@@ -0,0 +1,205 @@
1
+ /**
2
+ * v2-capabilities.mjs — what the OpenCode V2 plugin surface ACTUALLY is.
3
+ *
4
+ * Two reporting defects this module exists to prevent, both of them statements
5
+ * that were narrower than the truth:
6
+ *
7
+ * 1. The installer printed `listV2UnsupportedFeatures()` under the heading
8
+ * "Unsupported features", which reads like the complete list of what V2
9
+ * does. That list is a SEED: the live set is this seed PLUS markers the
10
+ * plugin appends at runtime when a host API turns out to be missing
11
+ * (`tool-transform`, `event-stream`, …), which cannot be known at install
12
+ * time. So the printed list must say what it is.
13
+ * 2. "Reduced surface" alone is misleading in the other direction: V2 is not
14
+ * a stub. It registers session `context`/`prompt`/`compaction` hooks, tool
15
+ * `execute.before`/`execute.after` hooks, a permission `evaluate` hook,
16
+ * `tool`/`agent`/`command`/`reference` transforms and five session events.
17
+ * A user deciding between generations is entitled to both halves.
18
+ *
19
+ * The registered surface below is derived from `src/plugin-v2.ts` (the
20
+ * registration sites, not the module header: the header still claims the
21
+ * caller/target matrix is enforced, while the enforcement guard's own docstring
22
+ * records that omitting the hierarchy wiring skips that branch — the gap is
23
+ * stated here as a gap).
24
+ *
25
+ * The seed itself is IMPORTED, never copied: an installer that restated these
26
+ * strings could drift from `src/pantheon/v2-unsupported.mjs`, and a test pins
27
+ * the two together.
28
+ *
29
+ * @module v2-capabilities
30
+ */
31
+
32
+ import { listV2UnsupportedFeatures } from '../../src/pantheon/v2-unsupported.mjs'
33
+
34
+ /** Tools registered unconditionally through `ctx.tool.transform`. */
35
+ export const V2_REGISTERED_TOOLS = Object.freeze([
36
+ 'hashline_edit',
37
+ 'pantheon_cost',
38
+ 'pantheon_model',
39
+ ])
40
+
41
+ /** Tools registered only when the host exposes the API they need. */
42
+ export const V2_HOST_DEPENDENT_TOOLS = Object.freeze(['vision_describe', 'pantheon_bounded_read'])
43
+
44
+ /** Session hooks V2 registers. */
45
+ export const V2_SESSION_HOOKS = Object.freeze(['context', 'prompt', 'compaction'])
46
+
47
+ /** Tool hooks V2 registers. */
48
+ export const V2_TOOL_HOOKS = Object.freeze(['execute.before', 'execute.after'])
49
+
50
+ /** Permission hooks V2 registers. */
51
+ export const V2_PERMISSION_HOOKS = Object.freeze(['evaluate'])
52
+
53
+ /** Transform domains V2 registers. */
54
+ export const V2_TRANSFORMS = Object.freeze(['tool', 'agent', 'command', 'reference'])
55
+
56
+ /** Host events V2 subscribes to. */
57
+ export const V2_EVENTS = Object.freeze([
58
+ 'session.created',
59
+ 'session.idle',
60
+ 'session.deleted',
61
+ 'session.error',
62
+ 'session.compacted',
63
+ ])
64
+
65
+ /** Scope line that keeps the seed from reading as the complete list. */
66
+ export const V2_NOT_REGISTERED_SCOPE =
67
+ 'statically known seed; the live plugin adds further markers at runtime when a host API is missing'
68
+
69
+ /**
70
+ * Machine-readable capability description for the V2 generation.
71
+ *
72
+ * JSON-safe by construction: `--json` carries this object, so the same facts
73
+ * are available to a machine as to a reader.
74
+ *
75
+ * @returns {{
76
+ * generation: 'v2',
77
+ * registered: {
78
+ * tools: string[],
79
+ * host_dependent_tools: string[],
80
+ * session_hooks: string[],
81
+ * tool_hooks: string[],
82
+ * permission_hooks: string[],
83
+ * transforms: string[],
84
+ * events: string[],
85
+ * },
86
+ * not_registered: string[],
87
+ * not_registered_scope: string,
88
+ * }}
89
+ */
90
+ export function v2Capabilities() {
91
+ return {
92
+ generation: 'v2',
93
+ registered: {
94
+ tools: [...V2_REGISTERED_TOOLS],
95
+ host_dependent_tools: [...V2_HOST_DEPENDENT_TOOLS],
96
+ session_hooks: [...V2_SESSION_HOOKS],
97
+ tool_hooks: [...V2_TOOL_HOOKS],
98
+ permission_hooks: [...V2_PERMISSION_HOOKS],
99
+ transforms: [...V2_TRANSFORMS],
100
+ events: [...V2_EVENTS],
101
+ },
102
+ not_registered: listV2UnsupportedFeatures(),
103
+ not_registered_scope: V2_NOT_REGISTERED_SCOPE,
104
+ }
105
+ }
106
+
107
+ /**
108
+ * The human-readable capability notice.
109
+ *
110
+ * Deliberately multi-line: one wrapped paragraph of eleven facts is unreadable
111
+ * on a 60-column terminal. `notice()` prefixes only the first line, so the
112
+ * continuation lines are indented to align under the marker.
113
+ *
114
+ * @param {ReturnType<typeof v2Capabilities>} [capabilities]
115
+ * @returns {string}
116
+ */
117
+ export function formatV2CapabilityNotice(capabilities = v2Capabilities()) {
118
+ const { registered, not_registered, not_registered_scope } = capabilities
119
+ const indent = ' '.repeat(7) // aligns under the `[INFO] ` prefix notice() adds
120
+ return [
121
+ 'V2 plugin generation — what this install registers:',
122
+ `${indent}tools: ${registered.tools.join(', ')} (plus ${registered.host_dependent_tools.join(', ')} when the host exposes them)`,
123
+ `${indent}hooks: session ${registered.session_hooks.join('/')}; tool ${registered.tool_hooks.join('/')}; permission ${registered.permission_hooks.join('/')}`,
124
+ `${indent}transforms: ${registered.transforms.join(', ')}; events: ${registered.events.join(', ')}`,
125
+ `${indent}not registered (${not_registered_scope}): ${not_registered.join(', ')}`,
126
+ ].join('\n')
127
+ }
128
+
129
+ /**
130
+ * Whether a `plugins` list registers the Pantheon V2 entry.
131
+ *
132
+ * Matched on the `plugin-v2` marker so every real spelling counts: the
133
+ * canonical directory, an absolute path to it, and the package export.
134
+ *
135
+ * @param {unknown} ref
136
+ * @returns {boolean}
137
+ */
138
+ export function isPantheonV2Reference(ref) {
139
+ const candidate =
140
+ typeof ref === 'string'
141
+ ? ref
142
+ : ref && typeof ref === 'object'
143
+ ? (ref.package ?? ref.path ?? ref.source ?? ref.id ?? ref.name)
144
+ : undefined
145
+ return typeof candidate === 'string' && candidate.includes('plugin-v2')
146
+ }
147
+
148
+ /**
149
+ * Whether the installed Pantheon V2 entry can receive plugin `options`.
150
+ *
151
+ * The host hands a plugin its `options` only from the OBJECT form
152
+ * (`{ package, options }`); a bare string entry leaves `ctx.options` empty, and
153
+ * `context_pruner` / `memory_injection` read exactly that object. A fresh
154
+ * install that emitted a bare string therefore had no reachable opt-in switch
155
+ * at all — this is the check that reports it after install.
156
+ *
157
+ * @param {unknown} plugins the `plugins` array from the config
158
+ * @returns {{registered: boolean, reachable: boolean, form: 'object'|'string'|'absent', detail: string}}
159
+ */
160
+ export function describePluginOptionsReachability(plugins) {
161
+ const list = Array.isArray(plugins) ? plugins : []
162
+ const entries = list.filter((ref) => isPantheonV2Reference(ref))
163
+ if (entries.length === 0) {
164
+ return {
165
+ registered: false,
166
+ reachable: false,
167
+ form: 'absent',
168
+ detail: 'no Pantheon V2 entry is registered, so plugin options are not read at all',
169
+ }
170
+ }
171
+ const forms = entries.map((entry) => {
172
+ if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) return 'string'
173
+ const options = entry.options
174
+ return typeof options === 'object' && options !== null && !Array.isArray(options)
175
+ ? 'object-with-options'
176
+ : 'object-without-options'
177
+ })
178
+ const reachable = forms.includes('object-with-options')
179
+ if (reachable) {
180
+ const extra = forms.filter((form) => form !== 'object-with-options')
181
+ return {
182
+ registered: true,
183
+ reachable: true,
184
+ form: 'object',
185
+ detail:
186
+ 'at least one Pantheon V2 entry carries an "options" object, so context_pruner and ' +
187
+ 'memory_injection can be configured there' +
188
+ (extra.length === 0
189
+ ? ''
190
+ : `; ${extra.length} other Pantheon entr${extra.length === 1 ? 'y' : 'ies'} in the same list cannot carry options`),
191
+ }
192
+ }
193
+ const stringOnly = forms.every((form) => form === 'string')
194
+ return {
195
+ registered: true,
196
+ reachable: false,
197
+ form: stringOnly ? 'string' : 'object',
198
+ detail: stringOnly
199
+ ? 'the Pantheon V2 entry is a bare string, so the host passes no options and ' +
200
+ 'context_pruner/memory_injection cannot be enabled; the object form ' +
201
+ '{"package": …, "options": {…}} makes them reachable'
202
+ : 'the Pantheon V2 entry has no "options" object, so the host passes an empty ' +
203
+ 'options bag and context_pruner/memory_injection stay at their defaults',
204
+ }
205
+ }