# Smart Deploy Agent Demo Backend

## Setup

```bash
python -m venv .venv
.venv\\Scripts\\python -m pip install -e backend
```

## Run

```bash
.venv\\Scripts\\python -m uvicorn app.main:app --reload --app-dir backend
```

## Demo UI

After startup, open:

`http://127.0.0.1:8000/demo/chat`

## Test

The lightweight API verification can run with in-memory SQLite:

```bash
set PYTHONPATH=backend
set DATABASE_URL=sqlite:///:memory:
.venv\\Scripts\\python -m pytest backend/tests -q -p no:cacheprovider
```

## Runtime Notes

This repo currently defaults to:

1. database: `sqlite:///./data/agent_demo.db`
2. demo cache / queue: no Redis dependency
3. edge defaults:
   `edge_id=edge-shanghai-001`
   `tool_name=http_health_check`
4. demo operator defaults:
   `alice(u1001)` for task execution
   `bob(u2001)` for approval
5. optional sample app bridge:
   `ENABLE_SAMPLE_APP_BRIDGE=true`
   `SAMPLE_APP_ROOT=sample-apps/order-service`

In the current sandbox, file-based SQLite may fail with `disk I/O error`.
For tests and local verification here, use:

```bash
set DATABASE_URL=sqlite:///:memory:
```

## Implemented API Scope

Current backend includes:

1. agent task
   `POST /api/agent/tasks`
   `POST /api/agent/tasks/{task_id}/confirm`
   `POST /api/agent/tasks/{task_id}/cancel`
   `GET /api/agent/tasks/{task_id}`
   `GET /api/agent/tasks/{task_id}/report`
2. demo chat
   `POST /api/demo/chat/sessions`
   `GET /api/demo/chat/sessions/{session_id}`
   `POST /api/demo/chat/sessions/{session_id}/messages`
   `POST /api/demo/chat/sessions/{session_id}/tasks/{task_id}/confirm`
3. demo web
   `GET /`
   `GET /demo/chat`
4. demo identity
   `POST /api/demo/identity/login`
   `GET /api/demo/identity/me`
   `GET /api/demo/identity/users/{user_id}/permissions`
   `POST /api/demo/identity/token/introspect`
5. demo approval
   `POST /api/demo/approval/requests`
   `GET /api/demo/approval/requests/{approval_id}`
   `POST /api/demo/approval/requests/{approval_id}/decision`
   `GET /api/demo/approval/requests`
6. software-a minimal implementation
   `POST /api/demo/software-a/deploy-tasks`
   `GET /api/demo/software-a/deploy-tasks/{software_a_task_id}`
   `POST /api/demo/software-a/permissions/check`
7. edge
   `POST /api/agent/edge/heartbeat`
   `POST /api/agent/edge/tasks/pull`
   `POST /api/agent/edge/tasks/report`
   `POST /api/agent/edge/events`

Current execution flow:

1. create chat session or open web demo
2. send one natural-language message
3. create task
4. confirm task
5. high-risk task enters approval flow
6. check `software-a` minimal implementation permission
7. create `software-a` minimal implementation deploy task
8. build metadata-driven multi-step edge verification plan:
   `check_process`
   `check_port`
   `tcp_probe`
   `http_health_check`
   `grep_log`
9. edge pulls and reports verification results
10. task reaches `SUCCEEDED` / `FAILED` / `CANCELLED`
11. task detail/report returns software-a status, approval trace, tool trace, verification trace and audit trace

## Real Java Sample App

The repo now includes a real Java sample app:

`sample-apps/order-service`

When `ENABLE_SAMPLE_APP_BRIDGE=true`, `software-a` minimal implementation can bridge the `order-service test` deploy action to the local sample app startup flow.

Current execution metrics:

1. `tool_call.duration_ms` is persisted from `started_at` / `finished_at`
2. `verification_trace.duration_ms` is persisted for edge task reports
3. `task_report.task_metrics` returns task-level aggregate durations and counts
4. current aggregate metrics include:
   `total_duration_ms`
   `confirm_wait_duration_ms`
   `approval_duration_ms`
   `execution_duration_ms`
   `software_a_duration_ms_total`
   `tool_call_duration_ms_total`
   `verification_duration_ms_total`
   `verification_queue_wait_duration_ms_total`
   `verification_end_to_end_duration_ms_total`
5. `task_report.audit_summary` returns audit result counts, action types and operator summary

Current result summary capabilities:

1. task detail/report returns `result_summary_detail`
2. summary includes final status, final reason, software-a result, approval result and verification result
3. demo chat API returns assistant-style parse/confirm messages
4. demo web page provides a visual conversation -> confirm -> execute -> report flow

Demo failure semantics currently include:

1. if `app_code` or `version` contains `fail`, the `software-a` minimal implementation returns a failed deploy task
2. approval rejection moves task to `CANCELLED`
3. failed edge report moves task to `FAILED`

## Current Verification Baseline

Automated tests currently cover:

1. create / confirm / get task
2. high-risk approval path
3. identity and software-a minimal implementation APIs
4. edge heartbeat / pull / report
5. edge event report
6. task report trace aggregation
7. cancel running task

Current baseline: `24 passed`
Current baseline: `23 passed`

## Next Focus

Recommended next implementation steps:

1. continue enriching app-metadata-driven verification templates
2. continue polishing the demo UI and session flow
3. validate native Linux packaging in a real bash/Linux environment
4. then continue with second-batch OpenAPI