thoth-agents 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+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.

package/README.md

@@ -0,0 +1,339 @@
+<div align="center">
+  <img src="img/team.png" alt="thoth-agents agents" width="420">
+  <p><i>Seven specialized agents, one delegate-first workflow across supported harnesses.</i></p>
+  <p><b>thoth-agents</b> - Multi-harness orchestration - Thoth-mem persistence - Bundled SDD pipeline</p>
+</div>
+
+---
+
+thoth-agents is a delegate-first agent system for coding harnesses. It started
+as an OpenCode plugin and now provides a shared seven-agent workflow for
+OpenCode and Codex, with each harness getting the integration surface that fits
+it best.
+
+OpenCode remains the stable default path: native plugin install, native `task`
+delegation, optional tmux monitoring, and generated config. Codex is supported
+through an explicit agent-pack and Personal plugin setup path, with documented
+trust review and instruction-level governance caveats where Codex does not
+provide the same hard runtime controls.
+
+## What It Is
+
+- A canonical seven-agent roster: `orchestrator`, `explorer`, `librarian`,
+  `oracle`, `designer`, `quick`, and `deep`.
+- A delegate-first operating model that keeps the root coordinator focused on
+  decisions while specialists gather evidence, implement, review, and verify.
+- A bundled requirements interview and SDD pipeline for moving from ambiguous
+  requests to planned, verified implementation.
+- A thoth-mem integration for durable project memory, SDD artifacts, and
+  cross-session recovery.
+- A multi-harness package that preserves OpenCode defaults while adding a
+  Codex setup path.
+
+## What It Is Not
+
+- It is not a claim that every harness has identical runtime behavior.
+- It is not a replacement for each harness's security, trust, sandbox, or
+  approval model.
+- It does not rename the seven roles or require new visual assets.
+- It does not make Codex tmux-aware; tmux integration is scoped to OpenCode
+  child `task` sessions.
+
+## Harness Support
+
+| Harness | Status | Setup path | Notes |
+| --- | --- | --- | --- |
+| OpenCode | Stable default | `pnpm dlx thoth-agents@latest install` or `install --agent=opencode` | Native plugin config, native `task` delegation, optional tmux panes, OpenCode provider auth. |
+| Codex | Supported explicit path | `pnpm dlx thoth-agents@latest install --agent=codex` | Installs ambient/root guidance, six role subagents, and a Personal plugin source. Requires `/plugins` and `/hooks` trust review. Some governance remains instruction-level. |
+
+## Quick Start
+
+### OpenCode
+
+```bash
+pnpm dlx thoth-agents@latest install
+pnpm dlx thoth-agents@latest install --agent=opencode
+opencode auth login
+opencode
+```
+
+Then ask OpenCode to verify the roster:
+
+```text
+ping all agents
+```
+
+For non-interactive setup:
+
+```bash
+pnpm dlx thoth-agents@latest install --no-tui --tmux=no --skills=yes
+```
+
+### Codex
+
+Review the plan first, then install explicitly:
+
+```bash
+pnpm dlx thoth-agents@latest install --agent=codex --dry-run
+pnpm dlx thoth-agents@latest install --agent=codex
+```
+
+Restart Codex and review plugin/hook trust:
+
+```text
+/plugins
+/hooks
+```
+
+Codex install does not create a selectable orchestrator TOML, does not bypass
+trust review, and does not make role permissions or memory governance hard
+runtime guarantees unless Codex exposes those controls.
+
+### Reset Generated Config
+
+```bash
+pnpm dlx thoth-agents@latest install --reset
+```
+
+## Seven-Agent Roster
+
+The delegate-first philosophy is simple: the `orchestrator` coordinates while
+specialists execute. Shared concepts are the same across harnesses, but the
+dispatch mechanism is harness-bound. In OpenCode, specialists are launched with
+the native `task` tool. In Codex, the installed role agents and plugin-bundled
+skills provide the closest supported workflow, with some behavior enforced by
+instructions rather than hard runtime APIs.
+
+### Primary Agent
+
+<table width="100%">
+  <tr>
+    <td width="100%" valign="top">
+      <img src="img/orchestrator.png" width="100%" alt="Orchestrator">
+      <br>
+      <b>Orchestrator</b>
+      <br>
+      <i>Root coordinator and sole primary agent.</i>
+      <br><br>
+      <b>Role:</b> The root coordinator. Handles delegation, sequencing, memory ownership, requirements routing, and SDD progress tracking. Does not read or modify source files directly when running as the root coordinator.
+      <br>
+      <b>Mode:</b> primary, non-mutating
+      <br>
+      <b>Dispatch:</b> sync coordinator
+      <br>
+      <b>Recommended:</b>
+      <br>
+      <code>anthropic/claude-opus-4-6</code> - <code>openai/gpt-5.4</code> - <code>kimi-for-coding/k2p5</code>
+      <br>
+      <b>Personality:</b> Autonomous deep coordinator; owns decisions and works through specialists.
+    </td>
+  </tr>
+</table>
+
+### Specialist Subagents
+
+<table width="100%">
+  <tr>
+    <td width="33%" valign="top">
+      <img src="img/explorer.png" width="100%" alt="Explorer">
+      <br>
+      <b>Explorer</b>
+      <br>
+      <i>Fast local discovery.</i>
+      <br><br>
+      <b>Role:</b> Local codebase discovery and navigation. Finds files, symbols, references, constraints, and verification targets.
+      <br>
+      <b>Mode:</b> read-only
+      <br>
+      <b>Dispatch:</b> harness-bound specialist dispatch
+      <br>
+      <b>Recommended:</b>
+      <br>
+      <code>Grok Code Fast</code> - <code>openai/gpt-5.4-nano</code> - <code>anthropic/claude-haiku-4-5</code>
+    </td>
+    <td width="33%" valign="top">
+      <img src="img/librarian.png" width="100%" alt="Librarian">
+      <br>
+      <b>Librarian</b>
+      <br>
+      <i>External docs and examples.</i>
+      <br><br>
+      <b>Role:</b> External docs and API research. Validates version-specific behavior with official docs or public examples.
+      <br>
+      <b>Mode:</b> read-only
+      <br>
+      <b>Dispatch:</b> harness-bound specialist dispatch
+      <br>
+      <b>Recommended:</b>
+      <br>
+      <code>openai/gpt-5.4</code> - <code>anthropic/claude-sonnet-4-6</code> - <code>google/gemini-3.1-pro-preview</code>
+    </td>
+    <td width="33%" valign="top">
+      <img src="img/oracle.png" width="100%" alt="Oracle">
+      <br>
+      <b>Oracle</b>
+      <br>
+      <i>Deep review and diagnosis.</i>
+      <br><br>
+      <b>Role:</b> Strategic advisor for debugging, architecture review, code review, security/correctness risk, and SDD plan review.
+      <br>
+      <b>Mode:</b> read-only
+      <br>
+      <b>Dispatch:</b> synchronous advisory specialist
+      <br>
+      <b>Recommended:</b>
+      <br>
+      <code>openai/gpt-5.4</code> - <code>anthropic/claude-opus-4-6</code> - <code>opencode-go/glm-5</code>
+    </td>
+  </tr>
+  <tr>
+    <td width="33%" valign="top">
+      <img src="img/designer.png" width="100%" alt="Designer">
+      <br>
+      <b>Designer</b>
+      <br>
+      <i>UI, UX, frontend, and visual QA.</i>
+      <br><br>
+      <b>Role:</b> User-facing design and implementation. Owns visual decisions, browser checks, screenshots, and UX quality.
+      <br>
+      <b>Mode:</b> write-capable
+      <br>
+      <b>Dispatch:</b> synchronous implementation specialist
+      <br>
+      <b>Recommended:</b>
+      <br>
+      <code>google/gemini-3.1-pro-preview</code> - <code>opencode-go/glm-5</code> - <code>kimi-for-coding/k2p5</code>
+    </td>
+    <td width="33%" valign="top">
+      <img src="img/quick.png" width="100%" alt="Quick">
+      <br>
+      <b>Quick</b>
+      <br>
+      <i>Fast bounded implementation.</i>
+      <br><br>
+      <b>Role:</b> Narrow, mechanical, low-risk edits where the approach is already clear.
+      <br>
+      <b>Mode:</b> write-capable
+      <br>
+      <b>Dispatch:</b> synchronous implementation specialist
+      <br>
+      <b>Recommended:</b>
+      <br>
+      <code>openai/gpt-5.4-mini</code> - <code>anthropic/claude-haiku-4-5</code> - <code>google/gemini-3-flash-preview</code>
+    </td>
+    <td width="33%" valign="top">
+      <img src="img/deep.png" width="100%" alt="Deep">
+      <br>
+      <b>Deep</b>
+      <br>
+      <i>Thorough implementation and verification.</i>
+      <br><br>
+      <b>Role:</b> Correctness-critical, multi-file, edge-case-heavy implementation and verification.
+      <br>
+      <b>Mode:</b> write-capable
+      <br>
+      <b>Dispatch:</b> synchronous implementation specialist
+      <br>
+      <b>Recommended:</b>
+      <br>
+      <code>openai/gpt-5.4</code> - <code>anthropic/claude-opus-4-6</code> - <code>google/gemini-3.1-pro-preview</code>
+    </td>
+  </tr>
+</table>
+
+## SDD And Memory
+
+The bundled requirements interview is the front door for open-ended work. It
+clarifies intent, assesses scope, asks for user approval when needed, and routes
+work into direct implementation, accelerated SDD, or full SDD.
+
+```text
+propose -> [spec || design] -> tasks -> apply -> verify -> archive
+```
+
+For moderate work, the accelerated path usually runs `propose -> tasks`. For
+high-risk or high-complexity work, the full path adds specification and design
+artifacts before task execution.
+
+Artifacts can be persisted in four modes:
+
+| Mode | Writes to | Cost | Use when |
+| --- | --- | --- | --- |
+| `thoth-mem` | Memory only | Low | Fast iteration without repo planning files |
+| `openspec` | `openspec/` files only | Medium | Reviewable planning artifacts in the repo |
+| `hybrid` | Both | High | Maximum durability; default |
+| `none` | Neither | Lowest | Ephemeral iterations, no persistence |
+
+Thoth-mem is the local memory MCP used for durable observations, architectural
+decisions, SDD artifacts, and session summaries. The core retrieval pattern is:
+
+1. `mem_search` for compact candidate records
+2. `mem_timeline` for chronological context
+3. `mem_get_observation` for the full selected record
+
+## Skills And MCPs
+
+thoth-agents ships bundled skills for requirements discovery, plan review, SDD
+planning/execution, verification, and archiving. It also registers MCP servers
+for docs research, public code search, and local memory where the harness
+supports that delivery surface.
+
+| Surface | Shared concept | OpenCode binding | Codex binding |
+| --- | --- | --- | --- |
+| Skills | Requirements, SDD, review, execution workflows | Copied into the OpenCode skills directory when `--skills=yes` | Packaged as plugin-bundled skills for the Personal plugin source |
+| MCPs | `exa`, `context7`, `grep_app`, `thoth_mem` | Registered by generated OpenCode plugin config | Packaged/configured only on validated Codex surfaces |
+| Delegation | Seven-role specialist workflow | Native `task` tool | Custom agents plus prompt/plugin guidance |
+| Blocking choices | Use a structured question surface | OpenCode `question` tool | `request_user_input` when enabled and available |
+
+See [docs/skills-and-mcps.md](docs/skills-and-mcps.md) for the detailed matrix.
+
+## Documentation
+
+- [Installation](docs/installation.md): OpenCode default setup, explicit Codex
+  setup, non-interactive installs, reset behavior, and troubleshooting.
+- [Codex Install](docs/codex-install.md): Codex targets, backups, dry-run
+  behavior, trust review, and limitations.
+- [Quick Reference](docs/quick-reference.md): Agent roster, SDD flow, memory,
+  delegation, tmux, and key config fields.
+- [Skills and MCPs](docs/skills-and-mcps.md): Bundled skills, MCP servers, and
+  harness delivery surfaces.
+- [Provider Configurations](docs/provider-configurations.md): OpenCode provider
+  presets, fallback chains, and Codex customization cross-links.
+- [Tmux Integration](docs/tmux-integration.md): OpenCode-scoped live pane
+  monitoring for delegated `task` sessions.
+- [SDD Pipeline](docs/sdd-pipeline.md): Planning and execution workflow details.
+- [Codex Plugin Packaging](docs/codex-plugin-packaging.md): Codex plugin package
+  layout and packaging boundaries.
+- [Codex Surface Validation](docs/codex-surface-validation.md): Validated,
+  unknown, and unsupported Codex generation surfaces.
+- [Codex Model Customization](docs/codex-model-customization.md): Codex role
+  model defaults and customization limits.
+
+## Development
+
+The OpenCode integration targets `@opencode-ai/plugin` and
+`@opencode-ai/sdk` v1.4.7. The repository also contains Codex adapter and
+packaging code for the multi-harness install path.
+
+Use Node.js `>=22.13` with Corepack-managed `pnpm@11.2.2`:
+
+```bash
+corepack enable
+corepack prepare pnpm@11.2.2 --activate
+pnpm install
+```
+
+| Command | Purpose |
+| --- | --- |
+| `pnpm run build` | Build TypeScript into `dist/` and generate declarations/schema |
+| `pnpm run typecheck` | Run TypeScript type checking without emit |
+| `pnpm test` | Run the Vitest suite |
+| `pnpm run lint` | Run Biome linter |
+| `pnpm run format` | Run Biome formatter |
+| `pnpm run check` | Run Biome check with auto-fix |
+| `pnpm run check:ci` | Run Biome check without writes |
+| `pnpm run dev` | Build and launch the OpenCode plugin in local dev mode |
+
+## License
+
+MIT

package/dist/agents/deep.d.ts

@@ -0,0 +1,2 @@
+import type { AgentDefinition } from './orchestrator';
+export declare function createDeepAgent(model: string, customPrompt?: string, customAppendPrompt?: string): AgentDefinition;

package/dist/agents/designer.d.ts

@@ -0,0 +1,2 @@
+import type { AgentDefinition } from './orchestrator';
+export declare function createDesignerAgent(model: string, customPrompt?: string, customAppendPrompt?: string): AgentDefinition;

package/dist/agents/explorer.d.ts

@@ -0,0 +1,2 @@
+import type { AgentDefinition } from './orchestrator';
+export declare function createExplorerAgent(model: string, customPrompt?: string, customAppendPrompt?: string): AgentDefinition;

package/dist/agents/index.d.ts

@@ -0,0 +1,8 @@
+import type { AgentConfig as SDKAgentConfig } from '@opencode-ai/sdk/v2';
+import { type PluginConfig, SUBAGENT_NAMES } from '../config';
+import { type AgentDefinition } from './orchestrator';
+export type { AgentDefinition } from './orchestrator';
+export type SubagentName = (typeof SUBAGENT_NAMES)[number];
+export declare function isSubagent(name: string): name is SubagentName;
+export declare function createAgents(config?: PluginConfig): AgentDefinition[];
+export declare function getAgentConfigs(config?: PluginConfig): Record<string, SDKAgentConfig>;

package/dist/agents/librarian.d.ts

@@ -0,0 +1,2 @@
+import type { AgentDefinition } from './orchestrator';
+export declare function createLibrarianAgent(model: string, customPrompt?: string, customAppendPrompt?: string): AgentDefinition;

package/dist/agents/oracle.d.ts

@@ -0,0 +1,2 @@
+import type { AgentDefinition } from './orchestrator';
+export declare function createOracleAgent(model: string, customPrompt?: string, customAppendPrompt?: string): AgentDefinition;

package/dist/agents/orchestrator.d.ts

@@ -0,0 +1,15 @@
+import type { AgentConfig } from '@opencode-ai/sdk/v2';
+export interface AgentDefinition {
+    name: string;
+    description?: string;
+    config: AgentConfig;
+    /** Priority-ordered model entries for runtime fallback resolution. */
+    _modelArray?: Array<{
+        id: string;
+        variant?: string;
+    }>;
+}
+export declare function createOrchestratorAgent(model?: string | Array<string | {
+    id: string;
+    variant?: string;
+}>, customPrompt?: string, customAppendPrompt?: string): AgentDefinition;

package/dist/agents/prompt-dialects.d.ts

@@ -0,0 +1,28 @@
+import type { AgentDispatchMethod, AgentRoleName } from '../harness/core/agent-pack';
+import type { HarnessCapabilities, HarnessId } from '../harness/types';
+export type AgentPromptRole = AgentRoleName;
+export interface ToolNomenclature {
+    delegationTool: string;
+    backgroundDelegationTool?: string;
+    backgroundStatusTool?: string;
+    userQuestionTool: string;
+    progressTool: string;
+    hostStatusSurface?: string;
+    roleReference(role: AgentPromptRole): string;
+}
+export interface CapabilityProfile {
+    capabilities: HarnessCapabilities;
+    renderCapabilityDisclosure(capability: keyof HarnessCapabilities): string | undefined;
+}
+export interface HarnessPromptDialect {
+    harness: HarnessId;
+    tools: ToolNomenclature;
+    capabilities: CapabilityProfile;
+    dispatchLabel(method: AgentDispatchMethod): string;
+    renderRoleInvocation(role: AgentPromptRole): string;
+}
+export declare const CODEX_PROMPT_CAPABILITIES: HarnessCapabilities;
+export declare const OPENCODE_PROMPT_DIALECT: HarnessPromptDialect;
+export declare const CODEX_PROMPT_DIALECT: HarnessPromptDialect;
+export declare function getPromptDialect(harness: HarnessId): HarnessPromptDialect;
+export declare function getPromptDialect(harness: string): HarnessPromptDialect;

package/dist/agents/prompt-sections.d.ts

@@ -0,0 +1,47 @@
+import type { AgentPromptRole, HarnessPromptDialect } from './prompt-dialects';
+import type { ModelEntry } from './prompt-utils';
+type ModelFamily = 'openai' | 'claude' | 'gemini' | 'kimi' | 'glm';
+export type SemanticMemoryAccess = 'base' | 'readonly' | 'writable';
+export interface QuestionProtocolSection {
+    kind: 'question-protocol';
+    toolConcept: 'userQuestion';
+}
+export interface SubagentRulesSection {
+    kind: 'subagent-rules';
+    memoryAccess: SemanticMemoryAccess;
+    progressConcept: 'progress';
+    userQuestionConcept: 'userQuestion';
+}
+export interface ResponseBudgetSection {
+    kind: 'response-budget';
+}
+export interface StepBudgetSection {
+    kind: 'step-budget';
+    steps: number;
+}
+export interface ModelFamilySection {
+    kind: 'model-family';
+    role: AgentPromptRole;
+    family: ModelFamily;
+}
+export interface RoleTextSection {
+    kind: 'role-text';
+    template: string;
+}
+export type PromptSection = QuestionProtocolSection | SubagentRulesSection | ResponseBudgetSection | StepBudgetSection | ModelFamilySection | RoleTextSection;
+export type RolePromptSection = PromptSection;
+export interface PromptSectionRenderer<TSection extends PromptSection> {
+    render(section: TSection, dialect: HarnessPromptDialect): string;
+}
+export declare function createQuestionProtocolSection(): QuestionProtocolSection;
+export declare function createSubagentRulesSection(memoryAccess?: SemanticMemoryAccess): SubagentRulesSection;
+export declare function createResponseBudgetSection(): ResponseBudgetSection;
+export declare function createStepBudgetSection(steps?: number): StepBudgetSection | undefined;
+export declare function detectModelFamilyFromModel(model?: string | ModelEntry[]): ModelFamily | undefined;
+export declare function createModelFamilySection(role: AgentPromptRole, model?: string | ModelEntry[]): ModelFamilySection | undefined;
+export declare function createOrchestratorPromptSections(): RolePromptSection[];
+export declare function createReadOnlySpecialistPromptSections(role: Extract<AgentPromptRole, 'explorer' | 'librarian' | 'oracle'>): RolePromptSection[];
+export declare function createWriteCapableSpecialistPromptSections(role: Extract<AgentPromptRole, 'designer' | 'quick' | 'deep'>): RolePromptSection[];
+export declare function renderPromptSection(section: PromptSection, dialect: HarnessPromptDialect): string;
+export declare function renderRolePrompt(sections: RolePromptSection[], dialect: HarnessPromptDialect): string;
+export {};

package/dist/agents/prompt-utils.d.ts

@@ -0,0 +1,25 @@
+import { type AgentPromptRole } from './prompt-dialects';
+export type { AgentPromptRole, CapabilityProfile, HarnessPromptDialect, ToolNomenclature, } from './prompt-dialects';
+export type { ModelFamilySection, PromptSection, PromptSectionRenderer, QuestionProtocolSection, ResponseBudgetSection, RolePromptSection, RoleTextSection, SemanticMemoryAccess, StepBudgetSection, SubagentRulesSection, } from './prompt-sections';
+interface ComposeAgentPromptOptions {
+    basePrompt: string;
+    customPrompt?: string;
+    customAppendPrompt?: string;
+    placeholders?: Record<string, string | number | undefined>;
+}
+type ModelFamily = 'openai' | 'claude' | 'gemini' | 'kimi' | 'glm';
+export type ModelEntry = string | {
+    id: string;
+    variant?: string;
+};
+export declare const QUESTION_PROTOCOL: string;
+export declare const SUBAGENT_RULES: string;
+export declare const SUBAGENT_RULES_READONLY: string;
+export declare const SUBAGENT_RULES_WRITABLE: string;
+export declare const RESPONSE_BUDGET: string;
+export declare function appendPromptSections(...sections: Array<string | undefined>): string;
+export declare function detectModelFamily(model?: string | ModelEntry[]): ModelFamily | undefined;
+export declare function getStepBudgetPromptSection(steps?: number): string | undefined;
+export declare function getModelFamilyPromptSection(role: AgentPromptRole, model?: string | ModelEntry[]): string | undefined;
+export declare function replacePromptPlaceholders(template: string, placeholders?: Record<string, string | number | undefined>): string;
+export declare function composeAgentPrompt({ basePrompt, customPrompt, customAppendPrompt, placeholders, }: ComposeAgentPromptOptions): string;

package/dist/agents/quick.d.ts

@@ -0,0 +1,2 @@
+import type { AgentDefinition } from './orchestrator';
+export declare function createQuickAgent(model: string, customPrompt?: string, customAppendPrompt?: string): AgentDefinition;

package/dist/cli/codex-config-io.d.ts

@@ -0,0 +1,31 @@
+type TomlScalar = string | boolean | number;
+type TomlArray = TomlScalar[];
+interface TomlTable {
+    [key: string]: TomlValue;
+}
+type TomlValue = TomlScalar | TomlArray | TomlTable;
+export type CodexTomlDocument = TomlTable;
+export interface CodexConfigMergeResult {
+    success: boolean;
+    configPath: string;
+    backupPath?: string;
+    changed: boolean;
+    diffSummary: string[];
+    warnings: string[];
+    error?: string;
+}
+export declare function parseCodexToml(content: string): CodexTomlDocument;
+export declare function renderCodexTomlDocument(document: CodexTomlDocument): string;
+export declare function mergeCodexManagedConfig(document: CodexTomlDocument, options: {
+    pluginId?: string;
+}): {
+    content: string;
+    diffSummary: string[];
+    warnings: string[];
+};
+export declare function writeCodexConfigMerge(options: {
+    configPath: string;
+    dryRun?: boolean;
+    pluginId?: string;
+}): CodexConfigMergeResult;
+export {};

package/dist/cli/codex-install.d.ts

@@ -0,0 +1,41 @@
+import type { CodexInstallScope, CodexRoleName } from './codex-paths';
+export { CODEX_ROLE_NAMES } from './codex-paths';
+export type CodexSetupAction = 'merge-managed-block' | 'write-role-toml' | 'write-managed-model-state' | 'refresh-package' | 'merge-marketplace' | 'merge-toml' | 'diagnose-only';
+export type CodexTargetKind = 'root-instructions' | 'role-subagent-toml' | 'managed-model-state' | 'user-config' | 'plugin-package' | 'personal-plugin-source' | 'personal-marketplace' | 'diagnostic';
+export interface CodexInstallConfig {
+    dryRun?: boolean;
+    reset: boolean;
+    scope: CodexInstallScope;
+    projectRoot: string;
+    homeDir?: string;
+    codexHome?: string;
+    packageRoot?: string;
+    pluginId?: string;
+}
+export interface CodexSetupPlanItem {
+    kind: CodexTargetKind;
+    action: CodexSetupAction;
+    targetPath: string;
+    description: string;
+    requiresBackup: boolean;
+    content?: string;
+    role?: CodexRoleName;
+}
+export interface CodexSetupPlan {
+    dryRun: boolean;
+    reset: boolean;
+    items: CodexSetupPlanItem[];
+    diagnostics: string[];
+    disclaimers: string[];
+    configPath: string;
+    pluginId?: string;
+}
+export interface CodexApplyResult {
+    success: boolean;
+    changed: string[];
+    diagnostics: string[];
+    error?: string;
+}
+export declare function buildCodexSetupPlan(config: CodexInstallConfig): CodexSetupPlan;
+export declare function formatCodexSetupPlan(plan: CodexSetupPlan): string;
+export declare function applyCodexSetup(plan: CodexSetupPlan): CodexApplyResult;

package/dist/cli/codex-paths.d.ts

@@ -0,0 +1,29 @@
+export type CodexInstallScope = 'project' | 'user';
+export type CodexRoleName = 'explorer' | 'librarian' | 'oracle' | 'designer' | 'quick' | 'deep';
+export declare const CODEX_ROLE_NAMES: readonly ["explorer", "librarian", "oracle", "designer", "quick", "deep"];
+export interface CodexTargetResolverOptions {
+    scope: CodexInstallScope;
+    projectRoot: string;
+    homeDir?: string;
+    codexHome?: string;
+}
+export interface CodexResolvedTargets {
+    scope: CodexInstallScope;
+    codexHome: string;
+    configPath: string;
+    rootInstructionsPath: string;
+    roleAgentPaths: {
+        role: CodexRoleName;
+        path: string;
+    }[];
+    managedModelsPath: string;
+    skillsDir: string;
+    packageRoot: string;
+    personalPluginRoot: string;
+    personalMarketplacePath: string;
+}
+export declare function getCodexHome(options?: {
+    homeDir?: string;
+    codexHome?: string;
+}): string;
+export declare function resolveCodexTargets(options: CodexTargetResolverOptions): CodexResolvedTargets;

package/dist/cli/config-io.d.ts

@@ -0,0 +1,22 @@
+import type { ConfigMergeResult, DetectedConfig, InstallConfig, OpenCodeConfig } from './types';
+/**
+ * Strip JSON comments (single-line // and multi-line) and trailing commas for JSONC support.
+ */
+export declare function stripJsonComments(json: string): string;
+export declare function parseConfigFile(path: string): {
+    config: OpenCodeConfig | null;
+    error?: string;
+};
+export declare function parseConfig(path: string): {
+    config: OpenCodeConfig | null;
+    error?: string;
+};
+/**
+ * Write config to file atomically.
+ */
+export declare function writeConfig(configPath: string, config: OpenCodeConfig): void;
+export declare function addPluginToOpenCodeConfig(): Promise<ConfigMergeResult>;
+export declare function writeLiteConfig(installConfig: InstallConfig, targetPath?: string): ConfigMergeResult;
+export declare function disableDefaultAgents(): ConfigMergeResult;
+export declare function canModifyOpenCodeConfig(): boolean;
+export declare function detectCurrentConfig(): DetectedConfig;

package/dist/cli/config-manager.d.ts

@@ -0,0 +1,4 @@
+export * from './config-io';
+export * from './paths';
+export * from './providers';
+export * from './system';