fix(cp): credential rolebinding and project delete (#1203)

## Summary

- Seeds `credential:token-reader` and `credential:reader` roles via
migration `202603311216`
- Mounts runner BOT_TOKEN as file with 10-min background refresh loop in
control-plane
- Authorizes runner OIDC service account in `WatchSessionMessages`
- Adds exponential backoff retry in informer error handler
- Adds `acpctl apply -f` credential manifest support and role-binding
commands to CLI

## Test plan

- [ ] Deploy to OSD `ambient-s0` via ArgoCD (gitops MR \!94 already
merged)
- [ ] Verify `credential:token-reader` and `credential:reader` appear in
`acpctl get roles`
- [ ] Create role binding for `github-agent` in `credential-test`
project
- [ ] Start agent session and confirm runner pod retrieves token via
`GET /credentials/{id}/token`

🤖 Generated with [Claude Code](https://claude.ai/code)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

## Release Notes

* **New Features**
* Added role seeding and management capabilities to credentials system.
* Enhanced CLI with updated login, project context, and resource
management commands.
  * Introduced declarative manifest application via `acpctl apply`.
  * Added agent creation and session messaging commands.

* **Bug Fixes**
  * Strengthened authorization validation for session message access.

* **Documentation**
* Expanded CLI reference with comprehensive command examples and usage
patterns.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Ambient Code Bot <bot@ambient-code.local>
Co-authored-by: Claude <noreply@anthropic.com>

Author: 3 people

components/ambient-api-server/plugins/credentials/migration.go

@@ -1,9 +1,12 @@
 package credentials
 
 import (
+	"encoding/json"
+
 	"gorm.io/gorm"
 
 	"github.com/go-gormigrate/gormigrate/v2"
+	"github.com/openshift-online/rh-trex-ai/pkg/api"
 	"github.com/openshift-online/rh-trex-ai/pkg/db"
 )
 
@@ -30,3 +33,67 @@ func migration() *gormigrate.Migration {
 		},
 	}
 }
+
+func rolesMigration() *gormigrate.Migration {
+	type roleRow struct {
+		ID          string
+		Name        string
+		DisplayName string
+		Description string
+		Permissions string
+		BuiltIn     bool
+	}
+
+	seed := []struct {
+		name        string
+		displayName string
+		description string
+		permissions []string
+	}{
+		{
+			name:        "credential:token-reader",
+			displayName: "Credential Token Reader",
+			description: "Retrieve the raw token value for a credential",
+			permissions: []string{"credential:token"},
+		},
+		{
+			name:        "credential:reader",
+			displayName: "Credential Reader",
+			description: "Read credential metadata (name, provider, description)",
+			permissions: []string{"credential:read", "credential:list"},
+		},
+	}
+
+	return &gormigrate.Migration{
+		ID: "202603311216",
+		Migrate: func(tx *gorm.DB) error {
+			for _, r := range seed {
+				permsJSON, err := json.Marshal(r.permissions)
+				if err != nil {
+					return err
+				}
+				row := roleRow{
+					ID:          api.NewID(),
+					Name:        r.name,
+					DisplayName: r.displayName,
+					Description: r.description,
+					Permissions: string(permsJSON),
+					BuiltIn:     true,
+				}
+				if err := tx.Table("roles").
+					Where("name = ?", r.name).
+					FirstOrCreate(&row).Error; err != nil {
+					return err
+				}
+			}
+			return nil
+		},
+		Rollback: func(tx *gorm.DB) error {
+			names := make([]string, len(seed))
+			for i, r := range seed {
+				names[i] = r.name
+			}
+			return tx.Table("roles").Where("name IN ?", names).Delete(&roleRow{}).Error
+		},
+	}
+}

components/ambient-api-server/plugins/credentials/plugin.go

@@ -82,4 +82,5 @@ func init() {
 	presenters.RegisterKind(&Credential{}, "Credential")
 
 	db.RegisterMigration(migration())
+	db.RegisterMigration(rolesMigration())
 }

components/ambient-api-server/plugins/credentials/testmain_test.go

@@ -9,6 +9,18 @@ import (
 	"github.com/golang/glog"
 
 	"github.com/ambient-code/platform/components/ambient-api-server/test"
+
+	_ "github.com/ambient-code/platform/components/ambient-api-server/plugins/agents"
+	_ "github.com/ambient-code/platform/components/ambient-api-server/plugins/inbox"
+	_ "github.com/ambient-code/platform/components/ambient-api-server/plugins/projectSettings"
+	_ "github.com/ambient-code/platform/components/ambient-api-server/plugins/projects"
+	_ "github.com/ambient-code/platform/components/ambient-api-server/plugins/rbac"
+	_ "github.com/ambient-code/platform/components/ambient-api-server/plugins/roleBindings"
+	_ "github.com/ambient-code/platform/components/ambient-api-server/plugins/roles"
+	_ "github.com/ambient-code/platform/components/ambient-api-server/plugins/sessions"
+	_ "github.com/ambient-code/platform/components/ambient-api-server/plugins/users"
+	_ "github.com/openshift-online/rh-trex-ai/plugins/events"
+	_ "github.com/openshift-online/rh-trex-ai/plugins/generic"
 )
 
 func TestMain(m *testing.M) {

components/ambient-api-server/plugins/sessions/grpc_handler.go

@@ -288,7 +288,10 @@ func (h *sessionGRPCHandler) WatchSessionMessages(req *pb.WatchSessionMessagesRe
 
 	if !middleware.IsServiceCaller(ctx) {
 		username := auth.GetUsernameFromContext(ctx)
-		if username != "" && (h.grpcServiceAccount == "" || username != h.grpcServiceAccount) {
+		if username == "" {
+			return status.Error(codes.PermissionDenied, "not authorized to watch this session")
+		}
+		if h.grpcServiceAccount == "" || username != h.grpcServiceAccount {
 			session, svcErr := h.service.Get(ctx, req.GetSessionId())
 			if svcErr != nil {
 				return grpcutil.ServiceErrorToGRPC(svcErr)

components/ambient-cli/README.md

@@ -21,91 +21,231 @@ This produces an `acpctl` binary in the current directory with embedded version
 
 ```bash
 # With a token and API server URL
-./acpctl login --token <your-token> --url http://localhost:8000 --project myproject
+acpctl login <api-url> --token <your-token>
+
+# Skip TLS verification (e.g. local Kind cluster)
+acpctl login <api-url> --token <your-token> --insecure-skip-tls-verify
+
+# Use RH SSO
+acpctl login --use-auth-code --url https://ambient-api-server-ambient-code--ambient-s0.apps.int.spoke.dev.us-east-1.aws.paas.redhat.com
 
 # Verify
-./acpctl whoami
+acpctl whoami
+# User: service-account-bob
+# Project: myproject
 ```
 
 ### 2. Configure defaults
 
 ```bash
 # Set or change the default project
-./acpctl config set project myproject
+acpctl config set project myproject
+
+# Switch active project context (shorthand)
+acpctl project myproject
+
+# Show the currently active project
+acpctl project current
 
 # View current settings
-./acpctl config get api_url
-./acpctl config get project
+acpctl config get api_url
+acpctl config get project
 ```
 
 ### 3. List resources
 
 ```bash
-# List sessions (table format)
-./acpctl get sessions
+# Sessions
+acpctl get sessions
+acpctl get sessions -o json
 
-# List projects
-./acpctl get projects
+# Single session by ID
+acpctl get session <session-id>
+acpctl get session <session-id> -o json
 
-# JSON output
-./acpctl get sessions -o json
+# Projects
+acpctl get projects
+
+# Agents
+acpctl get agents
+acpctl get agents -o json
 
-# Single resource by ID
-./acpctl get session <session-id>
+# Credentials
+acpctl get credentials
+acpctl get credentials -o json
+
+# Roles
+acpctl get roles
+acpctl get roles -o json
 ```
 
 ### 4. Create resources
 
 ```bash
 # Create a project
-./acpctl create project --name my-project --display-name "My Project"
+acpctl create project --name my-project --display-name "My Project" --description "Demo project"
 
 # Create a session
-./acpctl create session --name fix-bug-123 \
+acpctl create session --name fix-bug-123 \
   --prompt "Fix the null pointer in handler.go" \
   --repo-url https://github.com/org/repo \
   --model sonnet
 
 # Create with all options
-./acpctl create session --name refactor-auth \
+acpctl create session --name refactor-auth \
   --prompt "Refactor the auth middleware" \
   --model sonnet \
   --max-tokens 4000 \
   --temperature 0.7 \
   --timeout 3600
+
+# Create an agent
+acpctl agent create \
+  --project-id my-project \
+  --name my-agent \
+  --prompt "You are a GitHub automation agent."
+
+# Create a role binding (bind a credential role to an agent)
+acpctl create role-binding \
+  --user-id <user-id> \
+  --role-id <role-id> \
+  --scope agent \
+  --scope-id <agent-id>
 ```
 
-### 5. Session lifecycle
+### 5. Apply declarative manifests
+
+`acpctl apply` creates or updates resources from YAML files. Token values can be
+injected via environment variables referenced in the manifest.
+
+```bash
+# Apply a credential manifest
+cat > credential.yaml <<'EOF'
+kind: Credential
+name: my-github-pat
+provider: github
+token: $GITHUB_TOKEN
+description: GitHub PAT for CI
+EOF
+
+GITHUB_TOKEN="ghp_..." acpctl apply -f credential.yaml
+```
+
+Supported `kind` values: `Credential` (additional kinds vary by deployment).
+
+### 6. Agent sessions
+
+```bash
+# Start a session for a named agent with an initial prompt
+acpctl agent start <agent-name> \
+  --project-id <project-name> \
+  --prompt "Open a test issue in org/repo"
+
+# Start and capture the session ID
+SESSION_JSON=$(acpctl agent start my-agent --project-id my-project --prompt "..." -o json)
+SESSION_ID=$(echo "$SESSION_JSON" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
+```
+
+### 7. Session lifecycle
 
 ```bash
 # Start a session
-./acpctl start <session-id>
+acpctl start <session-id>
 
 # Stop a session
-./acpctl stop <session-id>
+acpctl stop <session-id>
+```
+
+### 8. Session messages
+
+```bash
+# List all messages for a session (table format)
+acpctl session messages <session-id>
+
+# JSON output
+acpctl session messages <session-id> -o json
+
+# Stream new messages live (follow mode)
+acpctl session messages <session-id> -f
+
+# Stream only messages after a known sequence number
+acpctl session messages <session-id> -f --after 42
+
+# Send a user message to a running session (multi-turn)
+acpctl session send <session-id> "Please also update the test file."
 ```
 
-### 6. Inspect resources
+### 9. Inspect resources
 
 ```bash
-# Full JSON detail of a session
-./acpctl describe session <session-id>
+# Full detail of a session
+acpctl describe session <session-id>
 
-# Full JSON detail of a project
-./acpctl describe project <project-id>
+# Full detail of a project
+acpctl describe project <project-id>
 ```
 
-### 7. Delete resources
+### 10. Delete resources
 
 ```bash
-./acpctl delete project <project-id>
-./acpctl delete project-settings <id>
+acpctl delete session <session-id> -y
+acpctl delete project <project-id> -y
+acpctl delete project-settings <id>
+acpctl credential delete <credential-id> --confirm
 ```
 
-### 8. Log out
+### 11. Log out
 
 ```bash
-./acpctl logout
+acpctl logout
+```
+
+## Credentials
+
+Credentials store secrets (e.g. GitHub PATs, API keys) that are injected into
+agent sessions at runtime. The runner retrieves the raw token via the
+credentials API, so the secret is never embedded in session configuration.
+
+```bash
+# List credentials
+acpctl get credentials
+
+# Create via apply (token injected from env var — never passed as a flag)
+GITHUB_TOKEN="ghp_..." acpctl apply -f credential.yaml
+
+# Delete
+acpctl credential delete <credential-id> --confirm
+```
+
+### Role bindings
+
+Access to credentials is controlled by role bindings. The relevant roles are:
+
+| Role | Permission |
+|---|---|
+| `credential:token-reader` | Retrieve the raw credential token via `GET /credentials/{id}/token` |
+| `credential:reader` | Read credential metadata (name, provider, description) |
+
+```bash
+# Look up a role ID
+ROLE_ID=$(acpctl get roles -o json | python3 -c "
+import sys, json
+data = json.load(sys.stdin)
+items = data.get('items', []) if isinstance(data, dict) else data
+for r in items:
+    if r.get('name') == 'credential:token-reader':
+        print(r['id']); break
+")
+
+# Get your user ID
+MY_USER_ID=$(acpctl whoami | awk '/^User:/{print $2}')
+
+# Bind the role to an agent (agent can now retrieve the token)
+acpctl create role-binding \
+  --user-id "${MY_USER_ID}" \
+  --role-id "${ROLE_ID}" \
+  --scope agent \
+  --scope-id <agent-id>
 ```
 
 ## Try It Now (No Server Required)
@@ -122,12 +262,12 @@ make build
 ./acpctl create --help
 
 # Login and config flow
-./acpctl login --token test-token --url http://localhost:8000 --project demo
+./acpctl login http://localhost:8000 --token test-token
 ./acpctl whoami
 ./acpctl config get api_url
 ./acpctl config get project
 ./acpctl config set project other-project
-./acpctl config get project
+./acpctl project current
 
 # Shell completion
 ./acpctl completion bash