# KinSwitch

KinSwitch is a consent-aware Alexa+ household coordination agent. When a routine breaks, it checks the household schedule, finds capable coverage, proposes the smallest safe change, and waits for human approval before acting.

Built for the Alexa+ track and AWS Builder mini-challenge of the 2026 Build, Ship, Shape Amazon Developer Hackathon.

## Judge demo

Use the seeded prompt:

> Asha can't make the pharmacy pickup or dinner check-in tonight. Replan the evening without moving the family call.

KinSwitch identifies the two at-risk tasks, matches each task's requirements to an available household member, shows the evidence behind each recommendation, and pauses at an explicit approval gate. Approval updates the household runway and creates an audit entry.

The demo uses fictional household data. KinSwitch does not provide medical advice, alter medication instructions, contact emergency services, or execute financial or legal actions.

## Architecture

- React and Vite provide the responsive Alexa+ simulation.
- Express hosts the web app, product API, and MCP endpoint.
- The official Model Context Protocol TypeScript SDK exposes a stateless Streamable HTTP server at `POST /mcp`.
- Amazon Bedrock can generate constrained recovery plans in `AGENT_MODE=bedrock`.
- DynamoDB can persist the demo household when `KIN_SWITCH_TABLE` is set.
- A deterministic local agent keeps development, tests, and judge fallback behavior reliable without cloud credentials.

```mermaid
flowchart LR
  A[Alexa+ or web demo] --> B[Express API + MCP]
  B --> C[Household planner]
  C --> D[Amazon Nova on Bedrock]
  C --> E[Constraint validator]
  E --> F[Human approval gate]
  F --> G[DynamoDB state + audit]
```

## Run locally

Requires Node.js 22 or later.

```bash
npm install
npm run dev
```

Open `http://127.0.0.1:8787`.

```bash
npm test
npm run lint
npm run build
npm start
```

## Verified

- 12 domain and safety tests pass.
- TypeScript, ESLint, and the production Vite build pass.
- `npm audit` reports zero known vulnerabilities.
- The Linux production container builds, starts, serves the app, and answers its health endpoint.
- An official MCP client negotiates Streamable HTTP, lists all three tools, invokes them, and confirms replayed approval is rejected.
- [GitHub Actions runs the complete quality gate](https://github.com/singh-himanshu3/kinswitch/actions/workflows/ci.yml) on every push and pull request.

## AWS mode

Set `AGENT_MODE=bedrock`, `AWS_REGION`, `BEDROCK_MODEL_ID`, and `KIN_SWITCH_TABLE`. The runtime identity needs only `bedrock:InvokeModel` for the selected model and read/write access to the single DynamoDB table. Do not commit AWS credentials; use the workload role supplied by the deployment platform.

Reproducible App Runner, ECR, DynamoDB, IAM, and Bedrock configuration lives in [`infra`](./infra). See [`docs/DEPLOYMENT.md`](./docs/DEPLOYMENT.md) for the two-stage deployment command and cost boundary.

## MCP tools

- `household_context`: read synthetic schedule, availability, and risk context.
- `propose_handoff`: create an evidence-backed proposal without executing it.
- `approve_handoff`: execute only a specifically identified pending plan.

The endpoint intentionally rejects non-POST requests and keeps no MCP session state, making it suitable for a horizontally scaled demo deployment.

## Submission kit

- [`docs/DEVPOST_SUBMISSION.md`](./docs/DEVPOST_SUBMISSION.md): judge-facing story and final-link checklist
- [`docs/DEMO_SCRIPT.md`](./docs/DEMO_SCRIPT.md): timed script and capture checklist for the required video
- [`docs/PRODUCT_FEEDBACK.md`](./docs/PRODUCT_FEEDBACK.md): implementation friction log for the product-feedback bonus
- [`docs/SECURITY_AND_PRIVACY.md`](./docs/SECURITY_AND_PRIVACY.md): current guarantees and honest prototype limits

## Development disclosure

KinSwitch was created during the hackathon submission period with Codex as a technical development assistant. Product decisions, evaluation claims, limitations, and the final submission remain the entrant's responsibility. The hackathon rules permit third-party technical assistance when the entrant owns the result.