Metadata-Version: 2.4
Name: jupyter-agent-runner
Version: 0.1.3
Summary: Project-centered Pi coding agent and persistent Chatrooms for JupyterLab
License: BSD 3-Clause License
        
        Copyright (c) 2026, Agent Runner contributors
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice,
           this list of conditions and the following disclaimer.
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        3. Neither the name of the copyright holder nor the names of its contributors
           may be used to endorse or promote products derived from this software
           without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES ARE DISCLAIMED.
        
License-File: LICENSE
Classifier: Framework :: Jupyter
Classifier: Framework :: Jupyter :: JupyterLab :: 4
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.11
Requires-Dist: filelock<4,>=3.16
Requires-Dist: jupyter-server<3,>=2.14
Requires-Dist: jupyterlab<5,>=4.4
Requires-Dist: tornado<7,>=6.4
Description-Content-Type: text/markdown

# Jupyter Agent Runner

Project-centered AI coding assistance inside JupyterLab.

Jupyter Agent Runner adds a Project Center and persistent Chatrooms to
JupyterLab 4. Open a workspace, talk to the built-in Pi Manager, attach files,
and keep each project's conversation and activity separate.

> **Not sure what to do next? Ask the Manager in Chatroom.**

## Highlights

- **Works without VS Code.** The package includes its own Pi coding-agent
  runtime and starts it automatically with JupyterLab.
- **Project-bound Chatrooms.** Every conversation belongs to one workspace, so
  messages and replies from different projects do not get mixed together.
- **Persistent history.** Conversations survive JupyterLab and browser
  restarts.
- **Built-in project context.** The Manager receives the selected project
  directory and can inspect or modify files there when asked.
- **File attachments.** Attach a file and reference it from your prompt without
  exposing the Agent Runner data directory to the browser.
- **Compatible with Agent Runner for VS Code.** Both interfaces use the same
  projects, Manager session, authentication, and Chatroom history when they run
  as the same operating-system user.

## Requirements

- Python 3.11 or newer
- JupyterLab 4.4 or newer
- Node.js 22.19 or newer for the bundled Pi runtime
- An OpenAI Codex account for the built-in Manager

You do not need a global Pi installation or the Agent Runner VS Code extension.

## Install

Install the package in the same Python environment as JupyterLab:

```sh
pip install jupyter-agent-runner
```

Then start or restart JupyterLab:

```sh
jupyter lab
```

The Python package includes both the JupyterLab frontend and its authenticated
Jupyter Server extension. No separate npm installation is required.

## First Run

1. Open the **Agent Runner** icon in JupyterLab's left sidebar.
2. Choose **townhall** for general conversation, or open the project created
   for your Jupyter Server root directory.
3. Open that project's Chatroom.
4. If prompted, click **Sign in to Pi**, open the displayed sign-in page, and
   enter the device code.
5. Ask the Manager to explain the workspace, inspect a notebook, fix code, add
   tests, or implement a change.

For example:

```text
Review this project and explain how its main components fit together.
```

```text
Find why the current tests fail, fix the issue, and summarize the change.
```

```text
Create a notebook that explores the CSV file I attached.
```

In the composer, `Enter` adds a line break and `Shift+Enter` sends the message.

## Project Center

The Project Center is the entry point for your Agent Runner workspace:

- **TOWNHALL** is the default space for general coordination and work that is
  not tied to a repository.
- **PROJECTS** lists known work directories. Selecting one opens or reveals its
  persistent Chatroom in JupyterLab's main area.
- **AGENTS** shows the built-in Manager and any Agent Runner agents already
  present in the shared workspace.
- **ISSUES** summarizes the selected project's current and completed work.
- **AGENDA** summarizes scheduled and recently dispatched tasks when that state
  exists.

Each project has its own `workdir` and stable project identity. Live replies
and stored history are filtered to that project before they appear in its
Chatroom.

## Using Chatroom

Unaddressed messages go to the built-in Manager. The Manager runs as a
long-lived Pi coding session and continues its most recent session after a
restart.

Messages go to the built-in Manager by default. Agent Runner routing mentions
such as `@manager`, `@agent`, or `@channel` remain available when connected to
a full Agent Runner backend.

Attached files are stored as Agent Runner resources and inserted into the
composer as `#filename` references. The browser communicates only with the
authenticated Jupyter Server; it never reads `~/.agent-runner` directly.

## Standalone and Shared Use

Jupyter Agent Runner can run by itself. When no Agent Runner backend is active,
JupyterLab starts the bundled backend and Pi Manager.

If Agent Runner for VS Code is already running for the same user, the
JupyterLab package reuses that healthy backend instead of starting a competing
owner. The two products have different browser-facing WebSocket connections,
but share the durable Agent Runner state and Manager session.

## Data Location

Agent Runner keeps local state under:

```text
~/.agent-runner
```

This includes project descriptors, project-scoped Chatroom history, uploaded
resources, Agent Runner status, and the resumable Manager session. Pi
credentials are stored separately under `~/.pi/agent/`.

## Troubleshooting

If Agent Runner does not appear after installation, confirm that the package is
installed in the environment used to launch JupyterLab, then restart the
Jupyter Server:

```sh
python -m pip show jupyter-agent-runner
jupyter server extension list
jupyter labextension list
```

If the built-in Manager cannot start, check `node --version`. Node.js 22.19 or
newer is required. If sending is unavailable, open a Chatroom and complete the
**Sign in to Pi** flow.

## Development

Contributor setup, architecture, contracts, and build commands are documented
in [JUPYTERLAB.md](JUPYTERLAB.md).
