# Lifecycle Sidecar

A lightweight Kubernetes sidecar that monitors the main agent container and handles cleanup when the container exits with a specific exit code indicating idle shutdown.

## Purpose

User agent containers self-manage their lifecycle by:
1. Tracking their own activity (MCP calls, trigger status)
2. Exiting with code `42` when idle (no triggers + no recent activity)
3. Delegating deployment cleanup to this sidecar

The sidecar watches the main container and:
- On exit code `42`: Deletes the deployment (and optionally PVC)
- On any other exit code: Allows Kubernetes restart policy to handle it

## Architecture

```
┌─────────────────────────────────────────────────┐
│                    Pod                          │
│  ┌────────────────┐      ┌──────────────────┐  │
│  │ Agent Container│      │ Lifecycle Sidecar│  │
│  │                │      │                  │  │
│  │ - Track activity     │ - Monitor agent  │  │
│  │ - Track triggers     │ - Watch exit code│  │
│  │ - Exit 42 if idle    │ - Delete if 42   │  │
│  └────────────────┘      └──────────────────┘  │
│         │                         │             │
│         │ writes exit_code        │             │
│         └─────────►/var/run/agent/exit_code    │
│                                   │             │
└───────────────────────────────────┼─────────────┘
                                    │
                                    ▼ k8s API
                         ┌──────────────────────┐
                         │  Delete Deployment   │
                         │  (+ PVC if anonymous)│
                         └──────────────────────┘
```

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `NAMESPACE` | Yes | Kubernetes namespace (injected via downward API) |
| `DEPLOYMENT_NAME` | Yes | Name of the deployment to delete (from pod label) |
| `USER_TYPE` | No | User license tier: `anonymous`, `free`, `paid`, `enterprise` |
| `MAIN_CONTAINER_PID` | No | PID of main container (for precise monitoring) |

## Exit Code Contract

The agent container uses exit codes to signal intent:

| Exit Code | Meaning | Sidecar Action |
|-----------|---------|----------------|
| `42` | Clean idle shutdown | Delete deployment + optional PVC |
| Any other | Error or normal restart | Allow Kubernetes to restart |

## RBAC Requirements

The sidecar requires a ServiceAccount with permission to delete its own deployment:

```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
rules:
  - apiGroups: ["apps"]
    resources: ["deployments"]
    verbs: ["get", "delete"]
  - apiGroups: [""]
    resources: ["persistentvolumeclaims"]
    verbs: ["get", "delete"]
```

See `deploy/k8s/base/lifecycle-sidecar-rbac.yaml` for the full RBAC configuration.

## Building

```bash
docker build -t ghcr.io/dexorder/lifecycle-sidecar:latest .
docker push ghcr.io/dexorder/lifecycle-sidecar:latest
```

## Example Usage

See `deploy/k8s/base/agent-deployment-example.yaml` for a complete example of how to configure an agent deployment with the lifecycle sidecar.

## Security Considerations

1. **Self-delete only**: The sidecar can only delete the deployment it's part of (enforced by label matching in admission policy)
2. **Non-privileged**: Runs as non-root user (UID 1000)
3. **Minimal permissions**: Only has `get` and `delete` on deployments/PVCs in the agents namespace
4. **No cross-namespace access**: Scoped to `dexorder-agents` namespace only
5. **Crash-safe**: Only triggers cleanup on exit code 42, never on crashes