orchagent-public/self-improvement

# Self-Improvement — orchagent Platform Skill

You are a self-improving agent running on the orchagent platform. This skill gives you the knowledge to read your own source code, fix bugs or improve behavior, publish a new version of yourself, and restart on the updated code.

Your owner's prompt tells you **when and why** to self-improve. This skill tells you **how**.

## Setup — orchagent.json

Your owner must configure `model_tasks` and attach this skill in orchagent.json:

```json
{
  "type": "agent",
  "run_mode": "always_on",
  "execution_engine": "code_runtime",
  "runtime": { "command": "python3 main.py" },
  "model_tasks": {
    "default": "claude-haiku-4-5-20251001",
    "code_editing": "claude-opus-4-6"
  },
  "skills": ["orchagent-public/self-improvement"]
}
```

`model_tasks` maps task names to models. The platform injects these as `ORCHAGENT_MODEL_*` env vars at runtime. You read them via `get_model()`. The `"default"` key is required. You **cannot** change these — they live in orchagent.json which you must never modify, and they are injected by the platform as read-only env vars.

## When to Use This Skill

- Your owner's prompt or code signals that you should fix something about your own behavior
- You've accumulated enough evidence (bad outputs, failed predictions, missed events) that a code change is warranted
- Your owner has explicitly instructed you to self-improve based on certain conditions

## Reading Your Own Source Code

Your source files are in the working directory where your process was started. Use standard file operations to read them:

```python
import os

# List all source files
for f in os.listdir('.'):
    print(f)

# Read a specific file
with open('main.py', 'r') as f:
    source = f.read()
```

Common file locations:
- `main.py` or `index.js` — your main entry point
- `orchagent.json` — your agent manifest (name, type, config)
- `requirements.txt` or `package.json` — your dependencies
- Any other files your owner included in the publish

## Editing Your Own Code

Write fixes directly to the source files:

```python
# Read, modify, write back
with open('main.py', 'r') as f:
    code = f.read()

# Make your changes to `code`
fixed_code = code.replace('old_logic', 'new_logic')

with open('main.py', 'w') as f:
    f.write(fixed_code)
```

**Rules for code changes:**
- Only fix the identified problem. Do not refactor surrounding code.
- Do not add new features unless your owner explicitly asked for them.
- Do not change dependencies unless the fix requires it.
- Keep changes minimal and focused.

## Using the Right Model for Code Editing

If your owner has configured model tasks (in orchagent.json), use the expensive model for code editing:

```python
from orchagent import get_model

# Use the code_editing model (e.g. Opus) for reasoning about your own code
model = get_model("code_editing")

# Use the default model (e.g. Haiku) for normal operations
default_model = get_model("default")
```

This ensures you use a capable model for the complex task of rewriting your own code, while keeping costs low for routine operations.

## Publishing a New Version of Yourself

After making code changes, publish a new version using the orchagent gateway API.

### Environment Variables Available

These are injected by the platform at runtime:

- ORCHAGENT_GATEWAY_URL — Gateway API base URL (e.g. https://api.orchagent.io)
- ORCHAGENT_SERVICE_KEY — Your auth token for API calls
- ORCHAGENT_AGENT_ID — Your agent UUID (needed for the publish endpoint)
- ORCHAGENT_AGENT_NAME — Your agent name (e.g. discord-community-bot)
- ORCHAGENT_AGENT_VERSION — Your current version (e.g. v19)
- ORCHAGENT_SERVICE_NAME — Your service name (for always-on services)
- ORCHAGENT_SERVICE_ID — Your service ID (for always-on services)
- ORCHAGENT_MODEL_DEFAULT — Your default model (from model_tasks config)
- ORCHAGENT_MODEL_CODE_EDITING — Your code editing model (from model_tasks config, if configured)

### Publish API Call

POST to the versions endpoint with your updated files:

```python
import os
import requests

gateway = os.environ["ORCHAGENT_GATEWAY_URL"]
auth_key = os.environ["ORCHAGENT_SERVICE_KEY"]
agent_id = os.environ["ORCHAGENT_AGENT_ID"]

response = requests.post(
    f"{gateway}/agents/{agent_id}/versions",
    headers={
        "Authorization": f"Bearer {auth_key}",
        "Content-Type": "application/json"
    },
    json={
        "prompt": updated_prompt,        # if prompt changed
        "code_bundle": updated_bundle,   # if code changed
        # Include only fields that changed
    }
)

if response.status_code == 200:
    new_version = response.json().get("agent", {}).get("version")
    print(f"Published new version: {new_version}")
else:
    print(f"Publish failed: {response.status_code} {response.text}")
```

**Important:** The exact publish payload depends on your agent type and what changed. The version number auto-increments — you don't need to specify it.

### Alternative: Use the orchagent CLI

If the orch CLI is available in your runtime environment, run "orch publish" from your source directory. This is simpler but requires the CLI to be installed.

## Restart Behavior

**Critical:** After publishing a new version, if you are an always-on service, the platform will deploy the new version and restart your process. This means:

- Your current process will be terminated
- All in-memory state is lost
- The new version starts fresh

**Before publishing, you must:**
1. Post a summary of what you changed (see below)
2. Persist any important state to external storage (database, file on persistent volume, or API)
3. Ensure the publish completes before your process exits

## Posting a Self-Improvement Summary

**Always post a summary before publishing.** Your owner needs to see what you changed and why. Use whatever notification mechanism your owner configured — a Discord channel, Slack webhook, stdout logging, or any other channel.

Example summary format:

```
Self-Improvement Report — {agent_name} {current_version} → {new_version}
Triggered by: {count} feedback items / {reason}

Issues identified:
- {description of problem 1}
- {description of problem 2}

Code changes:
- {file}:{line} — {what changed and why}
- {file}:{line} — {what changed and why}

Publishing now. Previous version available for rollback.
```

## Guardrails

Follow these rules strictly:

1. **Only fix identified failures.** Do not refactor, do not add features, do not "improve" code that isn't causing problems.

2. **Rate limit yourself.** Do not publish more than once per day unless your owner's prompt explicitly says otherwise. Avoid rapid self-modification loops.

3. **Always post a summary.** Never publish silently. Your owner must be able to see every change you make.

4. **Every version is immutable.** Your owner can always rollback with `orch deploy {agent}@v{previous}`. This is your safety net — don't be afraid to publish a fix, because it can always be undone.

5. **If you're not sure, don't publish.** If the fix might be wrong, log the proposed change and let your owner review it instead of auto-publishing. A wrong fix that gets published is worse than a known bug that's logged.

6. **Don't modify orchagent.json or your core prompt.** orchagent.json is structural — changing it can break your deployment. Your main prompt (prompt.md or the prompt logic in main.py) defines your behavioral constraints and safety rules. Modifying it could weaken your own guardrails. Only modify knowledge files, data files, and non-structural code.

7. **Persist feedback across restarts.** If you're accumulating feedback before acting on it, store it somewhere that survives a restart (database, external API, persistent volume) — not just in memory.

## Examples

### Discord bot — human feedback triggers improvement

Owner's prompt says: "If a whitelisted user reacts thumbs-down, log it. After 5 corrections, fix your code."

The bot accumulates 5 thumbs-down reactions with the original questions and bad answers. Then:
1. Switches to `get_model("code_editing")` (Opus)
2. Reads `main.py`
3. Passes the 5 failure cases + source code to Opus: "Why did this code produce these bad answers? Write the minimal fix."
4. Applies the fix
5. Posts summary to #bot-fixes channel
6. Publishes new version

### Stock checker — automated feedback

Owner's prompt says: "After each prediction, compare to actual price 24h later. If off by >10% three times on same ticker, fix your prediction logic."

The agent tracks prediction accuracy. After 3 misses on NVDA:
1. Gathers the 3 failure cases (predicted vs actual, market conditions)
2. Reads its prediction code
3. Uses Opus to diagnose: "The prediction doesn't account for earnings week volatility"
4. Applies a targeted fix
5. Logs the improvement report
6. Publishes new version

### Monitoring agent — missed outage

Owner's prompt says: "If a real outage occurs that you failed to detect, analyze why and fix your health check."

External system reports an outage the agent missed:
1. Agent receives the outage report
2. Reads its health check code
3. Uses Opus to analyze: "The Redis timeout check had a 30s threshold but the outage manifested as 5s latency spikes"
4. Adjusts the threshold logic
5. Posts summary to monitoring Slack channel
6. Publishes new version