Agent Management

# Option A: CLI (recommended)

# STEP 0 — REQUIRED BEFORE SCAFFOLDING — Ask the user which runtime:
#   "Should this agent run on Claude Code (Anthropic), Codex (OpenAI gpt-5-codex),
#    or OpenCode (provider-agnostic TUI, default model openai/gpt-4.1-nano)?"
# Default to claude-code if the user has no preference. Never silently pick.
# Codex agents MUST use the agent-codex template; OpenCode agents MUST use the
# agent-opencode template. Passing --template agent auto-maps to the runtime's
# native bootstrap (agent-codex for codex, agent-opencode for opencode).
# orchestrator/analyst/m2c1-worker have no codex/opencode variant: codex is
# rejected outright with those templates; opencode is not blocked but would
# scaffold a Claude-oriented bootstrap under an opencode runtime, so avoid it.

# claude-code path (the common one):
cortextos add-agent <name> --template agent --org <org> --runtime claude-code

# codex-app-server path (gpt-5-codex via codex CLI app-server JSONRPC):
cortextos add-agent <name> --template agent-codex --org <org> --runtime codex-app-server

# opencode path (provider-agnostic OpenCode TUI; ships the context-handoff
# lifecycle, default-on at 60% of the context window; model set in config.json,
# default openai/gpt-4.1-nano). --template agent auto-maps to agent-opencode:
cortextos add-agent <name> --template agent-opencode --org <org> --runtime opencode

# Option B: Manual
TEMPLATE="agent"  # or "orchestrator" or "analyst"
AGENT_NAME="myagent"
ORG="myorg"

# Step 1: Copy template
cp -r "$CTX_FRAMEWORK_ROOT/templates/$TEMPLATE" \
      "$CTX_FRAMEWORK_ROOT/orgs/$ORG/agents/$AGENT_NAME"

# Step 2: Create Telegram bot
# Tell the user:
# 1. Open Telegram, message @BotFather
# 2. Send /newbot
# 3. Choose a name (e.g., "My Agent")
# 4. Choose a username (e.g., myagent_cortextos_bot)
# 5. Copy the bot token

# Step 3: Get chat ID
# Tell the user:
# 1. Send any message to the new bot
# 2. Run: curl -s "https://api.telegram.org/bot<TOKEN>/getUpdates" | jq '.result[0].message.chat.id'
# 3. That number is the chat_id

# Step 4: Get user ID (for ALLOWED_USER security)
# Same getUpdates response: .result[0].message.from.id

# Step 5: Write .env (CRITICAL - do this BEFORE cortextos enable)
cat > "$CTX_FRAMEWORK_ROOT/orgs/$ORG/agents/$AGENT_NAME/.env" << EOF
BOT_TOKEN=<token from BotFather>
CHAT_ID=<chat_id from getUpdates>
ALLOWED_USER=<user_id from getUpdates>
EOF
chmod 600 "$CTX_FRAMEWORK_ROOT/orgs/$ORG/agents/$AGENT_NAME/.env"

# Step 6: Update config.json
node -e "
const fs = require('fs');
const path = '$CTX_FRAMEWORK_ROOT/orgs/$ORG/agents/$AGENT_NAME/config.json';
const c = JSON.parse(fs.readFileSync(path));
c.agent_name = '$AGENT_NAME';
c.enabled = true;
fs.writeFileSync(path, JSON.stringify(c, null, 2));
"

# Step 7: Enable agent (registers with daemon)
cortextos enable "$AGENT_NAME" --org "$ORG"

# Step 8: Verify
cortextos status

AGENT_NAME="theiragent"
ORG="myorg"
THEIR_BOT_TOKEN="<token from THEIR BotFather bot>"
THEIR_CHAT_ID="<THEIR chat_id, NOT yours>"
THEIR_USER_ID="<THEIR user_id>"

# Step 1: Add agent via CLI
cortextos add-agent "$AGENT_NAME" --template agent --org "$ORG"

# Step 2: Write THEIR .env (CRITICAL - must be THEIR credentials)
cat > "$CTX_FRAMEWORK_ROOT/orgs/$ORG/agents/$AGENT_NAME/.env" << EOF
BOT_TOKEN=$THEIR_BOT_TOKEN
CHAT_ID=$THEIR_CHAT_ID
ALLOWED_USER=$THEIR_USER_ID
EOF
chmod 600 "$CTX_FRAMEWORK_ROOT/orgs/$ORG/agents/$AGENT_NAME/.env"

# Step 3: Enable
cortextos enable "$AGENT_NAME" --org "$ORG"

# VERIFY: The new agent messages THEM, not you
# If messages come to you instead of them, the .env has wrong CHAT_ID

# Via bus command (preferred — writes marker file automatically)
cortextos bus self-restart --reason "<reason>"

# Restart a DIFFERENT agent
cortextos bus send-message <agent_name> high "soft-restart" "<reason>"

cortextos bus hard-restart --reason "context exhaustion"

# From inside the agent itself, or from another agent/terminal:
cortextos bus hard-restart --reason "loading new hook"

# Equivalent ops-side path:
cortextos stop <agent> && cortextos start <agent>

# Soft restart another agent via message bus
cortextos bus send-message assistant high "soft-restart" "goal refresh"

# Check status after restart
cortextos status

AGENT="sentinel"
ORG="myorg"
NEW_MODEL="claude-sonnet-4-6"  # or "claude-opus-4-6" or "claude-haiku-4-5-20251001"

# Step 1: Update config.json
node -e "
const fs = require('fs');
const path = '$CTX_FRAMEWORK_ROOT/orgs/$ORG/agents/$AGENT/config.json';
const c = JSON.parse(fs.readFileSync(path));
c.model = '$NEW_MODEL';
fs.writeFileSync(path, JSON.stringify(c, null, 2));
"

# Step 2: Soft restart to pick up new model
cortextos bus send-message "$AGENT" high "soft-restart" "model change to $NEW_MODEL"

BOT_TOKEN="<the token>"
curl -s "https://api.telegram.org/bot${BOT_TOKEN}/getUpdates" | \
  node -e "const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')); console.log(d.result[0].message.chat.id)"

AGENT="assistant"
ORG="myorg"

# Edit .env (replace BOT_TOKEN line)
sed -i '' "s/^BOT_TOKEN=.*/BOT_TOKEN=<new_token>/" \
  "$CTX_FRAMEWORK_ROOT/orgs/$ORG/agents/$AGENT/.env"

# Restart to pick up new token
cortextos bus send-message "$AGENT" high "soft-restart" "bot token updated"

BOT_TOKEN=<telegram bot token>
CHAT_ID=<telegram chat id for the user>
ALLOWED_USER=<telegram user id for security filtering>

chmod 600 "$CTX_FRAMEWORK_ROOT/orgs/$ORG/agents/$AGENT/.env"

AGENT_ENV="$CTX_FRAMEWORK_ROOT/orgs/$ORG/agents/$AGENT/.env"
if [[ ! -f "$AGENT_ENV" ]]; then
    echo "ERROR: No .env file for $AGENT!"
elif ! grep -q "BOT_TOKEN=" "$AGENT_ENV"; then
    echo "ERROR: Missing BOT_TOKEN in $AGENT .env"
elif ! grep -q "CHAT_ID=" "$AGENT_ENV"; then
    echo "ERROR: Missing CHAT_ID in $AGENT .env"
elif ! grep -q "ALLOWED_USER=" "$AGENT_ENV"; then
    echo "WARNING: Missing ALLOWED_USER - agent will reject all Telegram messages"
fi

AGENT="sentinel"
ORG="myorg"

node -e "
const fs = require('fs');
const path = '$CTX_FRAMEWORK_ROOT/orgs/$ORG/agents/$AGENT/config.json';
const c = JSON.parse(fs.readFileSync(path));
if (!c.crons) c.crons = [];
c.crons.push({ name: 'new-cron', interval: '2h', prompt: 'Do the thing' });
fs.writeFileSync(path, JSON.stringify(c, null, 2));
"

# Notify agent that crons have been updated
cortextos bus send-message "$AGENT" normal \
  'Crons updated in crons.json. The daemon scheduler will pick up the change automatically. To verify: cortextos bus list-crons '"$AGENT"

node -e "
const fs = require('fs');
const path = '$CTX_FRAMEWORK_ROOT/orgs/$ORG/agents/$AGENT/config.json';
const c = JSON.parse(fs.readFileSync(path));
c.crons = (c.crons || []).filter(cr => cr.name !== 'cron-to-remove');
fs.writeFileSync(path, JSON.stringify(c, null, 2));
"
cortextos bus send-message "$AGENT" normal 'Cron removed from config.json. Recreate your crons on next restart.'

cortextos enable <agent> --org <org>

cortextos disable <agent> --org <org>

cortextos status
cortextos bus read-all-heartbeats

cat "$HOME/.cortextos/default/state/$AGENT/heartbeat.json"

cortextos bus list-agents --format json

pm2 list
pm2 jlist | node -e "
const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));
d.forEach(p => console.log(p.name, p.pm2_env.status));
"

rm -f "$HOME/.cortextos/default/state/$AGENT/.crash_count_today"

echo "" > "$HOME/.cortextos/default/state/$AGENT/.force-fresh"
cortextos enable "$AGENT" --org "$ORG" --restart