# Pi COROS Running Agent

A Pi package that connects [Pi](https://github.com/earendil-works/pi-mono) to a COROS Running Agent backend.

This repo follows the same style as many Pi integration packages: it contains a small extension plus a skill, while the actual service runs separately.

```text
Pi TUI
  -> pi-coros-running-agent package
     -> extension: registers the coros_running_agent tool
     -> skill: teaches Pi when to use the tool
  -> COROS Running Agent HTTP API
  -> COROS MCP + RAG + memory + workout report workflow
```

## What This Package Does

- Adds a `coros_running_agent` tool to Pi.
- Adds a `/coros` command for direct questions.
- Adds a `coros-running-agent` skill for better natural-language routing.
- Keeps COROS OAuth tokens, FIT files, RAG sources, personal memory, and private data in your own backend.

This package does not talk to COROS directly. It calls a backend that exposes `POST /api/chat`.

## Package Structure

```text
pi-coros-running-agent/
├── extensions/
│   └── pi/
│       └── index.ts
├── skills/
│   └── coros-running-agent/
│       └── SKILL.md
├── .env.example
├── package.json
├── tsconfig.json
└── README.md
```

## Requirements

- Pi Agent
- Node.js 20+
- A running COROS Running Agent backend

The backend should support:

```http
POST /api/chat
content-type: application/json

{
  "message": "Analyze my latest workout",
  "session_id": "pi-coros"
}
```

Minimum response:

```json
{
  "message": "..."
}
```

Optional response fields such as `capability`, `confidence`, `tools`, `graph_steps`, `citations`, and `memory` are shown as metadata.

## Install

From GitHub:

```bash
pi install git:github.com/Noah-wang/pi-coros-running-agent
```

Then start Pi normally.

From npm, after the package is published:

```bash
pi install npm:pi-coros-running-agent
```

For local development:

```bash
git clone https://github.com/Noah-wang/pi-coros-running-agent.git
cd pi-coros-running-agent
npm install
npm run check
```

Run directly without installing:

```bash
COROS_RUNNING_AGENT_URL=http://127.0.0.1:8787 \
pi -e ./extensions/pi/index.ts
```

## Configuration

```bash
COROS_RUNNING_AGENT_URL=http://127.0.0.1:8787
COROS_RUNNING_AGENT_TOKEN=
COROS_RUNNING_AGENT_SESSION_ID=pi-coros
```

`COROS_RUNNING_AGENT_TOKEN` is optional. If set, the extension sends:

```http
Authorization: Bearer <token>
```

## Usage

Ask naturally:

```text
Analyze my latest workout and tell me what I should do next.
```

Or use the direct command:

```text
/coros Analyze my latest workout
```

Other examples:

```text
List my recent COROS activities.
Show my personal bests.
Use my running knowledge base to explain why my marathon is much slower than my half marathon.
Find my Los Angeles Marathon photos.
Build a training plan for my next marathon goal.
```

## Why It Is Split This Way

`pi-coros-running-agent` is the Pi integration package.

`coros-running-agent` is the backend that owns:

- COROS MCP access
- LLM configuration
- RAG and embeddings
- long-term memory
- FIT archive
- race photos
- report workflow

This split keeps the Pi package easy to review and install, while private data stays outside the package.

## Security

Do not commit:

- `.env`
- COROS OAuth tokens
- API keys
- FIT files
- RAG source PDFs
- personal memory files
- race photos

Only configure backend URLs and tokens through environment variables.

## Publish to npm and pi.dev

`pi.dev/packages` discovers Pi packages from npm. There is no separate manual upload form.

To make this package appear in the Pi package gallery:

1. Keep `pi-package` in `package.json` keywords.
2. Keep the `pi` manifest in `package.json`:

```json
{
  "pi": {
    "extensions": ["./extensions/pi/index.ts"],
    "skills": ["./skills"]
  }
}
```

3. Verify the package:

```bash
npm install --ignore-scripts
npm run check
npm pack --dry-run
```

4. Publish to npm:

```bash
npm login
npm publish --access public
```

5. Test install from Pi:

```bash
pi install npm:pi-coros-running-agent
```

The Pi gallery may take some time to index the npm package.

For later updates:

```bash
npm version patch
git push --follow-tags
npm publish --access public
```