kushagrasaxena28/crator-assignment

Purpose and topology

This repository implements a local permissions, approval, and audit gateway for AI-agent calls to external services. It has two independently run Python processes: a Django/DRF backend and a Claude Agent SDK CLI. The CLI intentionally routes external operations through backend HTTP endpoints, making the backend the enforcement boundary.

• Backend entry points: backend/manage.py, backend/config/urls.py, backend/config/settings.py

• Agent entry points: agent-cli/agent_cli_script/__main__.py, agent-cli/agent_cli_script/session.py

Backend API and trust boundary

Django exposes token issuance plus /api/external-services/ APIs for toolkit discovery, schemas, action calls, approval polling/resolution, permission administration, and audit queries. JWT authentication identifies agents for normal calls; Basic auth protects human-only approval and permission-management operations.

• Routing/configuration: backend/config/urls.py, backend/external_services/urls.py

• Auth/token enforcement: backend/external_services/authentication.py, backend/external_services/tokens.py

• Endpoint handlers: backend/external_services/views/toolkits.py, backend/external_services/views/approvals.py, backend/external_services/views/permissions.py

Permission and validation pipeline

An action call resolves the caller’s effective policy from a sparse (agent, action) override, otherwise using the cataloged action default. Policies branch into immediate execution, approval-ticket creation, or denial. Request parameters are checked against the action’s persisted JSON schema before execution, preventing separate runtime validators from drifting.

• Core policy: backend/external_services/permissions.py

• Persistent domain/schema: backend/external_services/models.py

• Validation: backend/external_services/validation.py

Approval and immutable audit flow

Approval-required calls return a ticket and create a pending_approval audit event. A human resolves the ticket; resolution executes or rejects the action and emits a separate terminal audit event. Expiration is handled lazily during ticket reads/resolution. Audit identity is snapshot-based rather than an agent foreign key, preserving history after agent deletion.

• Approval API: backend/external_services/views/approvals.py

• Audit write/mirroring path: backend/external_services/audit.py

• Models/admin controls: backend/external_services/models.py, backend/external_services/admin.py

Toolkit abstraction and external boundaries

Toolkit-aware code is isolated from the generic auth, permissions, approvals, and audit pipeline. Catalogs define actions and defaults; a registry dispatches to toolkit executors. items and github mutate process-local in-memory stores, while Notion uses its live REST API and environment-provided credentials.

• Registry/dispatch: backend/external_services/toolkits/__init__.py

• Mock toolkit example: backend/external_services/toolkits/items/catalog.py, backend/external_services/toolkits/items/executors.py, backend/external_services/toolkits/items/store.py

• Live integration: backend/external_services/toolkits/notion/client.py, backend/external_services/toolkits/notion/executors.py

Provisioning and persistence

SQLite persists only gateway metadata: agents, toolkit/action catalog, sparse overrides, tickets, and audit history. The idempotent seed command provisions the demo agent and action catalog. Django ORM is the persistence boundary, so database replacement is configuration-led.

• Schema/migrations: backend/external_services/models.py, backend/external_services/migrations/0001_initial.py

• Catalog provisioning: backend/external_services/management/commands/seed.py

• Runtime settings: backend/config/settings.py

Agent CLI control flow

The CLI hosts an interactive Claude session. Its sole custom tool obtains JWTs; session code caches and refreshes them. The model uses Bash/curl to invoke backend APIs, while a background watcher independently polls pending ticket statuses and emits approval notifications. It requires Anthropic’s API; the backend itself does not.

• CLI/session orchestration: agent-cli/agent_cli_script/__main__.py, agent-cli/agent_cli_script/session.py

• Model instructions and JWT tool: agent-cli/agent_cli_script/system_prompt.py, agent-cli/agent_cli_script/tools/generate_jwt.py

• Async approval notifications: agent-cli/agent_cli_script/ticket_watcher.py