# Codex integration

## Source-checkout installation

```bash
git clone https://github.com/cyanseek/dsh-tool-chaos.git
cd dsh-tool-chaos
npm ci
npm run build
npm pack --silent
node bin/dsh-tool-chaos.mjs setup \
  --profile chaos-demo \
  --source ./dsh-tool-chaos-0.1.0-next.0.tgz \
  --codex \
  --json
```

This installs both:

- a Codex marketplace plugin named `dsh-tool-chaos@dsh-tool-chaos`;
- an independent Agent Skill fallback at `~/.agents/skills/dsh-chaos-test`.

Restart or start a new Codex thread in the checkout, then invoke:

```text
$dsh-chaos-test Prove that this workflow retries once after a transient web tool failure.
```

The command installs both discovery surfaces. Until the first npm prerelease is published, execute the CLI from this checkout; an out-of-tree Skill fallback cannot fetch `dsh-tool-chaos` from npm yet.

After npm publication, the equivalent setup command will be:

```bash
npx -y dsh-tool-chaos setup --codex --json
```

## Repository-development installation

The repository follows the official multi-plugin marketplace shape:

```text
.agents/plugins/marketplace.json
plugins/dsh-tool-chaos/.codex-plugin/plugin.json
plugins/dsh-tool-chaos/skills/dsh-chaos-test/SKILL.md
```

Install from a checkout:

```bash
codex plugin marketplace add /absolute/path/to/dsh-tool-chaos
codex plugin add dsh-tool-chaos@dsh-tool-chaos
```

Do not point a marketplace entry at the repository root. The plugin lives in `plugins/dsh-tool-chaos` so its local source path is explicit and contained.

## Direct `codex exec`

```bash
node bin/dsh-tool-chaos.mjs codex \
  "Test Code Mode nested-call recovery when the first web sub-call fails"
```

The command uses:

- ephemeral Codex execution;
- workspace-write sandbox;
- the selected workspace as `--cd`;
- a full execution prompt from `prompts/run-experiment.md`;
- `.dsh-chaos/last-codex-message.md` for the final Agent response.

It does not bypass Codex or DSH approval mechanisms.

## Skill design

The Skill uses progressive disclosure:

- `SKILL.md` contains triggers, defaults, workflow, and hard stops;
- `references/scenario-design.md` is read only when rule/oracle selection is unclear;
- `references/cli-contract.md` defines commands and exit codes;
- `references/report-contract.md` defines evidence and verdicts;
- `references/safety-policy.md` is read before risky targeting;
- one wrapper script starts the local or npm CLI.

## Authentication

The plugin itself needs no OpenAI API key. Codex CLI uses the user's existing Codex authentication. DSH headless experiments use the model credentials configured for the selected DSH profile. Authentication is one of the few valid reasons for the Agent to ask the user for action.

## OpenAI API use

The most reliable local execution surface is Codex CLI because it already supplies a repository-aware shell sandbox. For custom API orchestration, obtain the autonomous prompt with:

```bash
node bin/dsh-tool-chaos.mjs prompt --lang en "your requirement"
```

Send that prompt to a coding-agent runtime that has an authorized local shell, then let it call the CLI JSON API. A plain text-only Responses API call cannot run local DSH commands by itself; the host application must provide the tool loop and sandbox.