Metadata-Version: 2.4
Name: infinium-copilot-cli-connector
Version: 1.0.0
Summary: Bridge between GitHub Copilot CLI hooks and Infinium agent tracing
Project-URL: Homepage, https://github.com/xyendigital/infinium-copilot-cli-connector
Project-URL: Repository, https://github.com/xyendigital/infinium-copilot-cli-connector
Project-URL: Documentation, https://i42m.ai/docs/copilot-cli/index
Project-URL: Bug Tracker, https://github.com/xyendigital/infinium-copilot-cli-connector/issues
Author-email: Infinium <support@i42m.ai>
License: MIT License
        
        Copyright (c) 2026 Infinium
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agent,copilot,github,hooks,infinium,observability,tracing
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: click>=8.0.0
Requires-Dist: infinium-o2<2.0.0,>=1.0.0
Requires-Dist: keyring>=24.0.0
Provides-Extra: dev
Requires-Dist: black>=23.7.0; extra == 'dev'
Requires-Dist: isort>=5.12.0; extra == 'dev'
Requires-Dist: mypy>=1.5.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.11.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Provides-Extra: server
Requires-Dist: starlette>=0.27.0; extra == 'server'
Requires-Dist: uvicorn[standard]>=0.23.0; extra == 'server'
Description-Content-Type: text/markdown

# Infinium Copilot CLI Connector

Bridge between [GitHub Copilot CLI](https://github.com/github/copilot-cli) hooks and [Infinium](https://i42m.ai) agent tracing. Automatically captures Copilot CLI sessions — tool calls, prompts, errors — and sends structured traces to the Infinium platform for Maestro analysis.

## Quick Start

Navigate to your project, install, and set up:

```bash
cd /path/to/your/project
pip install infinium-copilot-cli-connector
infinium-copilot init
infinium-copilot test       # verify credentials + network
```

That's it. Now just use Copilot CLI as you normally would — every session is automatically traced to Infinium. Copilot CLI auto-discovers `hooks.json` in your working directory.

> If `infinium-copilot` is not on your PATH, use `python -m infinium_copilot_cli_connector` as a drop-in replacement.

## Requirements

- Python 3.9+
- [GitHub Copilot CLI](https://github.com/github/copilot-cli) (GA as of Feb 2026)
- An Infinium agent ID and secret

## How It Works

After `infinium-copilot init`, everything is automatic. Copilot CLI loads `./hooks.json` and fires the connector for each event.

```
Copilot CLI ──./hooks.json──> python -m infinium_copilot_cli_connector.hook
                                 │
                                 ├─ converts Unix-ms timestamps to ISO 8601
                                 ├─ normalizes camelCase / PascalCase event names
                                 ├─ synthesizes sessionId from parent PID if absent
                                 ├─ append event to session JSONL file
                                 │
                                 └─ on sessionEnd (or postToolUse for per-turn):
                                      spawn detached background worker
                                      → replay events → aggregate → send trace
                                                                       │
                                                                       ▼
                                                               Infinium API
                                                           POST /agents/{id}/trace
```

1. Copilot CLI fires a hook for each event (sessionStart, preToolUse, postToolUse, userPromptSubmitted, sessionEnd, errorOccurred).
2. The hook normalizes the payload (Unix-ms → ISO 8601, camelCase canonicalization), appends to a session JSONL file, and returns instantly.
3. On `sessionEnd` (or `postToolUse` for per-turn traces), a detached worker replays, aggregates, and sends to Infinium.

## CLI Reference

### `infinium-copilot init`

Interactive setup wizard. Writes `./hooks.json` that points at the connector.

```
Options:
  --agent-id TEXT        Agent ID (skip prompt)
  --agent-secret TEXT    Agent Secret (skip prompt)
  --base-url TEXT        API base URL
  --no-interactive       Use flags only, no prompts (for CI/scripting)
```

### `infinium-copilot test`

Send a minimal test trace to verify credentials + network.

```
Options:
  -v, --verbose    Show the full trace payload before sending
```

### `infinium-copilot status`

Show current configuration: tracing state, credentials, config source, hook locations, pending retries.

### `infinium-copilot pause` / `infinium-copilot resume`

Temporarily stop or restart tracing. Hooks stay installed — events are silently skipped while paused.

### `infinium-copilot history`

View recently sent traces.

```
Options:
  -n, --limit N    Number of entries (default: 10)
  --json           Output raw JSON lines
  --clear          Delete all history
```

### `infinium-copilot errors`

View the connector error log (network failures, bad payloads, keyring issues).

### `infinium-copilot retry`

Resend traces that failed due to network issues.

### `infinium-copilot update-credentials`

Update your Agent ID or Secret.

### `infinium-copilot uninstall`

Remove the connector completely — hook entries from `hooks.json`, config file, and keyring secret.

### `infinium-copilot cleanup`

Remove stale session files (housekeeping).

### `infinium-copilot start`

Start HTTP server mode (requires `pip install infinium-copilot-cli-connector[server]`).

## Per-Project Configuration

Each project traces to its own Infinium agent:

```bash
cd /path/to/project-a
infinium-copilot init    # Agent A credentials

cd /path/to/project-b
infinium-copilot init    # Agent B credentials
```

Config resolution order:
1. **Project config** (`.infinium/config.json` at or above the working directory)
2. **Environment variables** (`INFINIUM_AGENT_ID`, `INFINIUM_AGENT_SECRET` — override for CI/Docker)

Add `.infinium/` to your `.gitignore`.

## Credential Storage

- **Agent ID** and **API URL** are stored in the project config file (`.infinium/config.json`)
- **Agent Secret** is stored in your **OS keyring**:
  - Windows: Credential Manager
  - macOS: Keychain
  - Linux: Secret Service (GNOME Keyring / KWallet)
- Environment variables (`INFINIUM_AGENT_ID`, `INFINIUM_AGENT_SECRET`) override stored values — useful for CI/Docker

## What Gets Traced

| Field | Source |
|-------|--------|
| **name** | Initial or first user prompt, truncated |
| **description** | Initial or first user prompt (full) |
| **duration** | Total session duration in seconds |
| **steps** | Ordered list: user prompts, tool calls |
| **errors** | Tool failures + `errorOccurred` events |
| **environment** | Working directory, session source, end reason |

### Captured Events

| Event | What It Captures |
|-------|-----------------|
| `sessionStart` | Source (`new`/`resume`/`startup`), initial prompt |
| `userPromptSubmitted` | User prompt text (truncated) |
| `preToolUse` / `postToolUse` | Tool name, parsed args, result type, LLM text |
| `errorOccurred` | Error message, name, stack |
| `sessionEnd` | Reason (`complete`/`error`/`abort`/`timeout`/`user_exit`) — triggers trace flush |

## Trace Granularity

Choose during `init` or via `CONNECTOR_FLUSH_ON_STOP`:

- **Per-session (default)** — one summary trace per session (on `sessionEnd`)
- **Per-turn** — a trace after every `postToolUse` (noisy but detailed)
- **Both** — per-turn traces plus a final session summary

## Configuration

Environment variables (all optional — `init` handles the common case):

```bash
# Credentials (override config file + keyring)
INFINIUM_AGENT_ID=...
INFINIUM_AGENT_SECRET=...
INFINIUM_BASE_URL=...

# Connector behavior
CONNECTOR_QUIET=false                  # Suppress output
CONNECTOR_FLUSH_ON_STOP=false          # Per-turn flush on postToolUse
CONNECTOR_FLUSH_ON_SESSION_END=true    # Summary flush on sessionEnd
CONNECTOR_SESSION_TTL=1800             # Stale session cleanup threshold (seconds)
CONNECTOR_SESSION_DIR=...              # Override temp directory for session files
```

## Documentation

Full documentation: [i42m.ai/docs/copilot-cli](https://i42m.ai/docs/copilot-cli/index)

## License

MIT
