Metadata-Version: 2.4
Name: gigaloom
Version: 0.9.0
Summary: GigaLoom local, provider-neutral control plane for coding agents
Project-URL: Homepage, https://krakenalt.github.io/gigaloom/
Project-URL: Repository, https://github.com/krakenalt/gigaloom
Project-URL: Documentation, https://krakenalt.github.io/gigaloom/
Project-URL: Issues, https://github.com/krakenalt/gigaloom/issues
Project-URL: Changelog, https://github.com/krakenalt/gigaloom/blob/main/CHANGELOG_en.md
Author-email: Ruslan Yakupov <rusyak1999@gmail.com>
License-Expression: MIT
License-File: LICENSE
Requires-Python: <3.15,>=3.11
Requires-Dist: agent-client-protocol==0.11.1
Requires-Dist: anyio<5,>=4.10
Requires-Dist: cryptography<50,>=46
Requires-Dist: fastapi<1,>=0.133.0
Requires-Dist: pydantic<3,>=2.12.0
Requires-Dist: pyjwt[crypto]<3,>=2.12.0
Requires-Dist: python-dateutil<3,>=2.9.0
Requires-Dist: pyyaml<7,>=6.0
Requires-Dist: starlette<2,>=1.1
Requires-Dist: uvicorn<1,>=0.41.0
Provides-Extra: claude-sdk
Requires-Dist: claude-agent-sdk<0.3,>=0.2.122; extra == 'claude-sdk'
Provides-Extra: gpt2giga
Requires-Dist: gpt2giga<0.4.0,>=0.3.0; extra == 'gpt2giga'
Description-Content-Type: text/markdown

# GigaLoom

<!-- Release-version snippets in this file are generated by scripts/release.py. -->

[![Качество](https://img.shields.io/github/actions/workflow/status/krakenalt/gigaloom/ci.yaml?branch=main&style=flat-square&label=quality)](https://github.com/krakenalt/gigaloom/actions/workflows/ci.yaml)
[![Документация](https://img.shields.io/github/actions/workflow/status/krakenalt/gigaloom/docs-pages.yaml?branch=main&style=flat-square&label=docs)](https://github.com/krakenalt/gigaloom/actions/workflows/docs-pages.yaml)
[![PyPI](https://img.shields.io/pypi/v/gigaloom?style=flat-square&label=PyPI)](https://pypi.org/project/gigaloom/)
[![Python](https://img.shields.io/pypi/pyversions/gigaloom?style=flat-square)](https://pypi.org/project/gigaloom/)
[![npm](https://img.shields.io/npm/v/%40gigaloom%2Fweb?style=flat-square&label=npm)](https://www.npmjs.com/package/@gigaloom/web)
[![Лицензия](https://img.shields.io/github/license/krakenalt/gigaloom?style=flat-square)](LICENSE)
[![Базовое покрытие GigaLoom](./badges/gigaloom-coverage.svg)](./docs/operations.md#quality-baseline)

GigaLoom — локальная панель управления для кодинг-агентов, не привязанная к
одному провайдеру. Она объединяет нативные команды вида `giga <агент>` и
браузерный интерфейс для сессий, подтверждений, worktree, расписаний, оценок и
мультиагентных сценариев.

В GigaLoom 0.9 основной рабочий путь выглядит так:
`Проект → Тред → Запуск → Результаты → Действие`. Также появились ограниченный
Thread Relay, схемы для редакторов, безопасные для разных кодировок вложения,
read-only просмотр Effective Instructions, локальные продуктовые отчёты и
точные маршруты запуска агентов через `gpt2giga`. Состояние пользователя
хранится локально, чувствительные значения скрываются при сохранении и выводе
в UI, а при неполных правах или данных о совместимости запуск блокируется.

GigaLoom позволяет:

- запускать Codex, Claude, Gemini, Pi и совместимые агенты из одной локальной
  точки, не заменяя их нативные CLI;
- изолировать работу в привязанных к проекту worktree и сохранять подтверждения,
  результаты проверок, оценки и данные для повторного анализа;
- подключать проверенные MCP-приложения и ACP-агенты по планам установки,
  привязанным к digest;
- просматривать и обрабатывать поддерживаемые треды без копирования приватного
  состояния провайдера;
- запускать один явно выбранный маршрут через gateway, не меняя домашние
  конфиги Codex, Claude или Gemini;
- автоматизировать headless-запуски через детерминированный JSONL-контракт и
  опциональные адаптеры без неявной передачи учётных данных или прав на проект.

## Быстрый старт

Нужны Python 3.11–3.14 и установленный CLI хотя бы одного провайдера, например
Codex CLI. Управляемые терминальные сессии на Linux и macOS также используют
`tmux`; без него останется обычный нативный запуск провайдерского CLI.

Установите GigaLoom и проверьте окружение:

```sh
uv tool install 'gigaloom==0.9.0'
giga doctor
giga --version
```

Запустите браузерный интерфейс:

```sh
giga ui
```

Откройте <http://127.0.0.1:8091/>. Для обычного запуска нативного CLI достаточно
добавить префикс `giga`; остальные аргументы передаются без изменений:

```sh
giga codex exec --json "проверь этот репозиторий"
giga claude -p "проверь этот репозиторий"
giga gemini -p "проверь этот репозиторий"
giga pi
```

Предпросмотр доставки сообщения через Thread Relay без изменения целевого
треда и без запроса к провайдеру:

```sh
giga session send THREAD_ID --text "проверь падающие тесты" --dry-run --json
```

## Codex через gpt2giga в терминале

Этот вариант подходит для интерактивного Codex и для `codex exec`. Для
проверенного маршрута `GigaChat-2-Max` GigaLoom сам запустит локальный
`gpt2giga 0.3.0`, передаст ему учётные данные GigaChat и остановит принадлежащий
этому запуску процесс после выхода из Codex.

### 1. Установите интеграцию

```sh
uv tool install --force \
  --with 'gpt2giga==0.3.0' \
  'gigaloom[gpt2giga]==0.9.0'
```

Codex CLI устанавливается отдельно. Для маршрута GigaLoom 0.9 проверялся Codex
CLI `0.146.0`; другая версия может быть заблокирована до запуска процесса.

### 2. Передайте учётные данные GigaChat

Выберите **один** способ авторизации и экспортируйте переменные в том же
терминале, из которого будет запущена команда `giga`:

```sh
# Вариант 1: OAuth credentials
export GIGACHAT_CREDENTIALS='<ваши-credentials>'
export GIGACHAT_SCOPE='GIGACHAT_API_PERS'

# Вариант 2: уже полученный access token
# export GIGACHAT_ACCESS_TOKEN='<ваш-access-token>'

# Вариант 3: логин и пароль для соответствующего GigaChat endpoint
# export GIGACHAT_USER='<логин>'
# export GIGACHAT_PASSWORD='<пароль>'
# export GIGACHAT_BASE_URL='<адрес-api>'
```

Не сохраняйте секреты в README, репозитории или отслеживаемом `.env`-файле.
Значение `GIGACHAT_SCOPE` должно соответствовать вашим учётным данным.

### 3. Запустите Codex

Интерактивный режим:

```sh
giga --with gpt2giga --model GigaChat-2-Max codex
```

Одноразовая задача без интерактивного интерфейса:

```sh
giga --with gpt2giga --model GigaChat-2-Max \
  codex exec --json "проверь падающие тесты"
```

Однокомандный managed-маршрут релиза 0.9 проверен с `GigaChat-2-Max`. Для
`GigaChat-3-Ultra` сначала запустите постоянный внешний gateway по инструкции
ниже, а затем подключите к нему Codex из второго терминала. Модель в любом
случае должна присутствовать в `/models` вашего GigaChat endpoint.

### Что означает `gateway_upstream_credentials_unavailable`

Сообщение

```json
{"reason_ids":["gateway_upstream_credentials_unavailable"],"status":"blocked"}
```

означает, что GigaLoom не увидел ни `GIGACHAT_CREDENTIALS`, ни
`GIGACHAT_ACCESS_TOKEN`, ни `GIGACHAT_USER`. Gateway и Codex при этом не
запускаются, запрос к провайдеру не отправляется. Экспортируйте переменные в
**том же процессе shell** и повторите команду. Быстрая проверка без вывода
самого секрета:

```sh
test -n "$GIGACHAT_CREDENTIALS" || \
test -n "$GIGACHAT_ACCESS_TOKEN" || \
test -n "$GIGACHAT_USER"
```

## gpt2giga и Codex в одном терминале

Этот сценарий нужен для `GigaChat-3-Ultra`, браузерного UI и долгоживущих
запусков через внешний gateway. `gpt2giga` работает в фоне того же терминала,
а после выхода из Codex или UI автоматически останавливается.

### 1. Подготовьте `.env`

Если команда `gpt2giga` не появилась в `PATH` после установки интеграции,
установите публичный gateway CLI отдельно:

```sh
uv tool install 'gpt2giga==0.3.0'
```

Создайте локальный конфиг и замените в нём значения `REPLACE_WITH_...`:

```sh
cp .env.example .env
$EDITOR .env
```

`gpt2giga` сам читает `.env`, но `giga` этого не делает: GigaLoom читает только
переменные текущего процесса. Поэтому перед `giga` файл нужно экспортировать
через `source`. В `.env.example` значение `GIGALOOM_API_KEY` берётся из
`GPT2GIGA_API_KEY`; не заменяйте его на `0`.

Если gateway уже запущен, исправление для текущего терминала выглядит так:

```sh
set -a
source .env
set +a

test "$GIGALOOM_API_KEY" = "$GPT2GIGA_API_KEY"
giga --with gpt2giga --model GigaChat-3-Ultra codex
```

### 2. Запустите gateway и Codex одной вставкой

Следующий блок загружает `.env`, запускает `gpt2giga` в фоне, ждёт
авторизованный `/models`, запускает Codex и гарантированно останавливает gateway
при выходе. Перед выполнением остановите ранее запущенный процесс на порту
`8090`, иначе новый gateway не сможет занять порт:

```zsh
(
  set -a
  source .env
  set +a

  if [[ -z "$GPT2GIGA_API_KEY" || "$GIGALOOM_API_KEY" != "$GPT2GIGA_API_KEY" ]]; then
    echo "GIGALOOM_API_KEY должен совпадать с GPT2GIGA_API_KEY и не быть пустым" >&2
    exit 2
  fi

  gpt2giga --env-path .env >/tmp/gpt2giga-gigaloom.log 2>&1 &
  gpt2giga_pid=$!
  cleanup_gpt2giga() {
    kill "$gpt2giga_pid" 2>/dev/null || true
    wait "$gpt2giga_pid" 2>/dev/null || true
  }
  trap cleanup_gpt2giga EXIT
  trap 'exit 130' INT TERM

  gateway_ready=false
  for gateway_attempt in {1..50}; do
    if curl -fsS \
      -H "x-api-key: $GIGALOOM_API_KEY" \
      "$GIGALOOM_PROXY_URL/models" >/dev/null; then
      gateway_ready=true
      break
    fi
    kill -0 "$gpt2giga_pid" 2>/dev/null || break
    sleep 0.2
  done

  if [[ "$gateway_ready" != true ]]; then
    tail -n 50 /tmp/gpt2giga-gigaloom.log
    exit 1
  fi

  giga --with gpt2giga --model GigaChat-3-Ultra codex
)
```

Для одноразовой задачи замените последнюю команду внутри блока на:

```sh
giga --with gpt2giga --model GigaChat-3-Ultra \
  codex exec --json "проверь падающие тесты"
```

### 3. Запустите gateway и UI в одном терминале

Используйте тот же блок, но замените последнюю команду на
`giga ui --no-start-proxy`. Пока UI открыт, gateway работает в фоне; после
`Ctrl+C` оба процесса завершаются.

Откройте <http://127.0.0.1:8091/web/work> и выполните следующие шаги:

1. Выберите или зарегистрируйте локальный проект.
2. Нажмите **«Новая сессия»**.
3. Для работы с репозиторием выберите **«Тип задачи → Агент разработки»** и
   **«Harness → Codex CLI»**. Для обычного разговора без агентного цикла
   выберите **«Прямой чат»** и harness `direct-chat`.
4. В поле **«Модель»** выберите `GigaChat-3-Ultra` или другую модель из
   `/models`.
5. Если показан блок reviewed gateway route, выберите маршрут `gpt2giga` и
   нажмите **«Preflight exact route»**.
6. Введите задачу и нажмите **«Запустить задачу»**.

Если список моделей или маршрутов пуст, сначала проверьте `/health`, `/models`,
совпадение `GPT2GIGA_API_KEY` и `GIGALOOM_API_KEY`, а также то, что UI запущен с
`--no-start-proxy` и правильным `--proxy-url`/`GIGALOOM_PROXY_URL`. Значение
`GIGALOOM_API_KEY=0` отключает auth-заголовок и приводит к `401 Unauthorized`,
который GigaLoom отображает как `models_unavailable`.

## Документация

| Тема | Руководство |
|---|---|
| Обзор продукта | [Главная страница документации](./docs/index.md) |
| Установка, обновление и первый запуск | [Установка](./docs/installation.md) · [Быстрый старт](./docs/quickstart.md) |
| Работа, Thread Relay, схемы и контекст | [Работа, треды и контекст](./docs/work-threads-and-context.md) |
| Архитектура и границы безопасности | [Архитектура](./docs/architecture.md) · [Надёжность и производительность](./docs/architecture/reliability-and-performance.md) · [Безопасность](./docs/security.md) |
| Работа сервиса, резервные копии и диагностика | [Эксплуатация](./docs/operations.md) |
| Опциональный gateway gpt2giga | [Интеграция с gateway](./docs/gateway-integration.md) |
| npm-пакет Web UI | [Web-пакет](./web/README.md) |
| Разработка, теги и восстановление релиза | [Участие в разработке](./docs/contributing.md) · [Релиз](./docs/release.md) |
| История переноса репозитория | [История исходного кода](./docs/source-history.md) |

Опубликованная документация на английском и русском языках доступна по адресу
<https://krakenalt.github.io/gigaloom/>.

## Интеграция с gateway

Базовый пакет `gigaloom` устанавливается независимо и не требует checkout
исходного кода gateway. Direct Chat и старый preset локального gateway являются
опциональными:

```sh
uv tool install 'gigaloom[gpt2giga]==0.9.0'
```

Опциональная зависимость использует опубликованный пакет `gpt2giga`. Контракты
нормализации протоколов и совместимости принадлежат отдельному проекту
[gpt2giga](https://github.com/ai-forever/gpt2giga). Точные маршруты,
проверенные версии клиентов, статус поддержки и канонические ссылки приведены
в [руководстве по интеграции](./docs/gateway-integration.md).

## Разработка

```sh
npm --prefix web ci --ignore-scripts
npm --prefix web run build
./scripts/ci-base.sh sync
./scripts/ci-base.sh ruff-check
./scripts/ci-base.sh pytest tests/harness -q
```

Сборка самостоятельного дистрибутива:

```sh
uv build --no-sources
```

Перед отправкой изменений прочитайте [CONTRIBUTING.md](./CONTRIBUTING.md), а
правила владения кодом и восстановления описаны в
[GOVERNANCE.md](./GOVERNANCE.md). Об ошибках сообщайте через
[GitHub Issues](https://github.com/krakenalt/gigaloom/issues), а о возможных
уязвимостях — только по приватному каналу из [SECURITY.md](./SECURITY.md).

## История исходного кода

GigaLoom был выделен из объединённого репозитория `ai-forever/gpt2giga`.
Ссылки на него в старых changelog и инструкциях по миграции являются
историческими. Текущая разработка, issues, документация и релизы находятся в
`krakenalt/gigaloom`.

Проект распространяется по [лицензии MIT](LICENSE).
