@mirego/pi-forra-attribution0.1.0

@mirego/pi-forra-attribution

Pi extension that adds Forra usage-attribution headers to each outbound LLM request. The headers come from the local git context. With this extension, Forra attributes compatible-API usage to the current repository and branch. You do not have to configure each session.

Requirements

• Pi (@earendil-works/pi-coding-agent) with the before_provider_headers extension event
• git available on PATH
• A Forra-compatible provider in your Pi configuration (~/.pi/agent/models.json or an extension provider)

Installation

Install the package for all projects:

pi install npm:@mirego/pi-forra-attribution

Install the package for the current project only (Pi writes it to .pi/settings.json):

pi install -l npm:@mirego/pi-forra-attribution

Pin a version if necessary:

pi install npm:@mirego/pi-forra-attribution@0.1.0

Restart Pi or run /reload after you install the package.

Local development (from this monorepo)

From the monorepo root:

./tools/pi-forra-attribution/install.sh

This command links the package directory into .pi/extensions/forra-attribution. Pi reads the pi.extensions entry in package.json. Do not link src/index.ts alone: Pi resolves relative imports from the link location, so it cannot find the other source files.

Pi loads project extensions only after you trust the project. Use /reload to load changes. Remove the npm package temporarily, so that Pi does not load the extension two times.

To test the extension for one run only:

pi -e ./tools/pi-forra-attribution/src/index.ts

To install the development version for all projects:

mkdir -p ~/.pi/agent/extensions
ln -sfn "$(pwd)/tools/pi-forra-attribution" \
  ~/.pi/agent/extensions/forra-attribution

Headers sent

Header	Source
x-git-project	Normalized owner/repo from git remote get-url origin
x-git-branch	Current branch from git branch --show-current
x-api-session-id	Pi session ID (ctx.sessionManager.getSessionId())

Pi does not have named agents, so the extension does not send an agent header.

The extension adds headers only when the base URL of the active model is a Forra URL. A Forra URL contains mirego.com, forra-ai.com, or localhost:8000. The extension does not change requests to other providers (for example, public OpenAI or Anthropic).

The extension reads the git context on each matching request. Thus, the headers show a branch change in a session immediately.

Project label normalization

The extension changes remote URLs to a stable owner/repo label (lowercase, without .git). SSH and HTTPS clones of the same repository thus share one report entry:

Remote	Label
git@github.com:mirego/mirego-scout.git	mirego/mirego-scout
https://github.com/mirego/mirego-scout.git	mirego/mirego-scout
https://gitlab.com/mirego/mirego-scout.git	mirego/mirego-scout

Override and disable

Variable	Effect
FORRA_GIT_PROJECT	Sets the x-git-project value
FORRA_GIT_BRANCH	Sets the x-git-branch value
FORRA_GIT_ATTRIBUTION=off (or 0 / false / no)	Stops all header injection

The extension reads the environment variables at request time.

Graceful degradation

Outside a git repository, or when origin does not exist, the extension does not send the git headers. The session continues normally. The extension still sends the session header when it is available. The extension never throws an error in the request path.

Known limits

• The extension uses the base URL of the selected model (ctx.model.baseUrl). If you select a virtual (router) model, this base URL can be different from the endpoint that receives the request.
• Pi reuses the headers of the first attempt when it retries a request.

Development

cd tools/pi-forra-attribution
npm install
npm test
npm run type-check