priiisk 0.22.0-linux-x64 → 0.22.0

package/README.md

@@ -1,3 +1,170 @@
-# priiisk for linux x64
+# priiisk
 
-Platform build of priiisk, installed automatically as an optional dependency of the `priiisk` command. There is nothing to run here directly.
+[Русская версия](./README.ru.md)
+
+A camp of long-lived worker agents. An orchestrator hires them, assigns work,
+and keeps control; a human watches through the cabin and steps in only when
+needed.
+
+A worker is a live session, not a one-shot process: it keeps a role, a model, a
+thinking level, a tool set, and a transcript that survives a restart.
+
+**Under active development.** Commands, configuration and stored state change
+between releases, sometimes without a transition path: a camp started by an
+older build may refuse to resume, and a config that worked yesterday may be
+rejected as a whole. Expect breakage and read the release you install.
+
+## Install
+
+```sh
+npm install -g priiisk
+priiisk --version
+```
+
+No separate runtime: the camp lives inside the executable. linux and macOS, x64
+and arm64.
+
+## After install
+
+`priiisk` with no arguments — the same as `priiisk status` — is the camp
+state: whether a camp is up, the roster, pending questions and elevation
+requests. `priiisk survey` is the command map and the usual order of work.
+When nothing is running, start with `camp up`.
+
+Commands that report state accept `--json`. The camp is polled by request, not
+by reading a screen. `priiisk --help` lists the rest; `priiisk <command> --help`
+lists the arguments of one command.
+
+## Quick start
+
+`camp up` starts the camp as a detached process and, when the terminal it was
+typed in can draw, opens the cabin there. The camp keeps running when the cabin
+closes; `camp open` brings it back. Hire needs at least one model alias in the
+config; see [Configuration](#configuration).
+
+```sh
+priiisk camp up
+priiisk hire "Look into the failing tests" --role prospector
+priiisk status prospector-quiet-harbor
+priiisk asks
+priiisk answer prospector-quiet-harbor
+priiisk camp down
+```
+
+Hire generates an alias (`<role>-<adjective>-<noun>`) unless you pass `--alias`.
+Use the name hire printed — `prospector-quiet-harbor` above is only an example.
+The first assignment is optional: omit it and the worker waits in `idle` for
+`priiisk send`.
+
+One project root is one camp, one socket, and one orchestrator.
+
+## Access modes
+
+Access mode is a set of operation classes the worker may receive. It is chosen
+at hire and does not change on a live worker. `equip` may narrow what is
+handed out, but it cannot raise this ceiling.
+
+| mode | classes | in practice |
+| --- | --- | --- |
+| `read-only` | read | files, search, read-only catalog binaries; no shell |
+| `execute` | read, execute | plus a shell for checks; `edit` and `write` are not handed out |
+| `read-write` | read, write | file edits through tools; no shell |
+| `all` | all three | the full set |
+
+The tool itself declares its class. Built-in roles: `prospector` is
+`read-only`, `assayer` is `execute`, `wright` is `all`.
+
+`execute` does not forbid writes. A started command writes everything the
+process user can write. That is role discipline, not isolation.
+
+## Elevation
+
+A one-off step outside the hired mode is a grant, not a question. The worker
+names the class it lacks (`read`, `write`, or `execute`) and a reason. The
+orchestrator answers with `priiisk grant <id>` or `priiisk grant <id> --deny`.
+An allow opens a window until the worker finishes the turn by returning a
+result; interrupt, error, and retry do not close it. The next need is a new
+request. The hired mode does not change.
+
+## Worker workspace
+
+`priiisk hire --workspace worktree` creates a named workspace with its own
+working tree and branch. Hire a second worker into it by name:
+`priiisk hire --workspace <name>`. A reviewer can then read the writer's work
+before any merge. It is not a sandbox: the object database, refs, repository
+config, hooks, and the user permissions of the same repository stay shared.
+Dismissal is cooperative. Take the finished work with an ordinary `git merge`.
+
+`priiisk workspace list` shows who lives in which workspace.
+`priiisk workspace forget <name>` removes an empty named workspace.
+`priiisk workspace sweep` lists orphan trees left after a crash: an empty named
+workspace is not an orphan. `--confirm` deletes only trees that are clean and
+whose branch is already reachable from another ref. A dirty tree and a tree
+with an unmerged branch stay put.
+
+## Configuration
+
+The camp reads one user TOML file: `$XDG_CONFIG_HOME/priiisk/config.toml`, or
+`~/.config/priiisk/config.toml` when `XDG_CONFIG_HOME` is unset.
+
+The file is checked as a whole. An unknown field is rejected. There are no
+silently ignored settings.
+
+### Before the first camp: the agent runtime comes first
+
+priiisk runs workers on the pi agent runtime and **inherits its providers,
+models and authentication**. It stores no tokens and copies no model registry,
+so a model exists for the camp only if it already exists there.
+
+That makes the order fixed, and it is easy to get wrong:
+
+1. Sign in to pi and connect the providers you intend to use. Adding a provider
+   or renewing its authentication is done with pi, not here.
+2. Ask pi which `provider/model` references are actually available to you. The
+   camp accepts an exact reference, not a family or a display name.
+3. Map those references to short aliases in the priiisk config below, and use
+   the aliases in roles and presets.
+4. Run `priiisk doctor`. It confirms that every configured alias resolves in the
+   pi catalog and that authentication for it is available — by reading the
+   catalog, without sending a prompt or spending anything.
+
+Skipping the first two steps is the usual first failure: the config is valid
+TOML, the camp starts, and the first hire dies because the model reference
+belongs to no one.
+
+A minimal file. Replace both `id` values before `camp up`; the placeholders below are only the required `provider/model` shape:
+
+```toml
+schemaVersion = 2
+
+[defaults]
+model = "strong"
+thinking = "medium"
+
+[models.strong]
+id = "provider/model"
+
+[models.fast]
+id = "provider/model"
+
+[roles.assayer]
+description = "Review worker"
+model = "strong"
+thinking = "high"
+access = "execute"
+
+[hirePresets.safe-review]
+description = "Review without a shell"
+role = "assayer"
+access = "read-only"
+```
+
+Replace both `id` values with models from your agent runtime. `defaults.model`
+and `defaults.thinking` are required. A hire preset may name a built-in role
+(`wright`, `assayer`, `prospector`) and then tighten access.
+
+A repository may keep `.priiisk/config.toml` and override policy from the user
+file: models, roles, hire presets, skill groups, defaults, and workspace. It
+does not read MCP server definitions or the external-binary catalog from the
+repository: those fields name what the camp will start, so taking them from a
+clone would run someone else's code on the first hire.

package/README.ru.md

@@ -0,0 +1,174 @@
+# priiisk
+
+[English version](./README.md)
+
+Управляемый лагерь долгоживущих worker-агентов. Оркестратор нанимает воркеров,
+дает им задания и держит управление; человек наблюдает через кабину и
+вмешивается только когда нужно.
+
+Воркер — не одноразовый процесс, а живая session: у него есть роль, модель,
+уровень мышления, свой набор инструментов и transcript, который переживает
+перезапуск.
+
+**Идет активная разработка.** Команды, конфигурация и сохраненное состояние
+меняются между выпусками, иногда без переходного пути: лагерь, поднятый прежней
+сборкой, может отказаться восстанавливаться, а вчерашний конфиг — быть
+отклоненным целиком. Ломаться будет; читайте тот выпуск, который ставите.
+
+## Установка
+
+```sh
+npm install -g priiisk
+priiisk --version
+```
+
+Отдельный рантайм ставить не нужно: лагерь целиком лежит внутри исполняемого
+файла. Поддержаны linux и macOS, x64 и arm64.
+
+## После установки
+
+`priiisk` без аргументов — то же, что `priiisk status` — это состояние лагеря:
+поднят ли он, кто в ростере, какие вопросы и просьбы о повышении ждут ответа.
+`priiisk survey` — карта команд и обычный порядок работы. Если лагеря нет,
+его поднимают `camp up`.
+
+Команды, отвечающие состоянием, понимают `--json`. Лагерь опрашивается
+запросом, а не чтением экрана. `priiisk --help` перечисляет остальные команды,
+`priiisk <команда> --help` — аргументы каждой.
+
+## Быстрый старт
+
+`camp up` поднимает лагерь отсоединенным процессом и, если терминал вызова
+умеет рисовать, открывает в нем кабину. Закрытие кабины лагеря не касается,
+вернуть вид — `camp open`. Для найма в конфиге нужна хотя бы одна модель; см.
+[Настройка](#настройка).
+
+```sh
+priiisk camp up
+priiisk hire "Разбери падение тестов" --role prospector
+priiisk status prospector-quiet-harbor
+priiisk asks
+priiisk answer prospector-quiet-harbor
+priiisk camp down
+```
+
+Hire сам генерирует алиас (`<роль>-<прилагательное>-<существительное>`), если не
+передан `--alias`. Дальше используйте имя, которое напечатал hire —
+`prospector-quiet-harbor` здесь только пример. Первое задание необязательно:
+без него воркер ждет в `idle` команды `priiisk send`.
+
+Лагерь привязан к каноническому корню репозитория: один проект — один лагерь,
+один сокет, один управляющий оркестратор.
+
+## Режимы доступа
+
+Режим доступа — множество классов операций, которые воркер может получить. Он
+задается при найме и на живом воркере не меняется. `equip` сужает выдачу
+внутри потолка режима и никогда его не поднимает.
+
+| режим | классы | на практике |
+| --- | --- | --- |
+| `read-only` | чтение | файлы, поиск, читающие бинари каталога; оболочки нет |
+| `execute` | чтение, исполнение | плюс оболочка для проверок; `edit` и `write` не выданы |
+| `read-write` | чтение, запись | правка файлов инструментами; оболочки нет |
+| `all` | все три | полный набор |
+
+Класс объявляет сам инструмент. Встроенные роли: `prospector` — `read-only`,
+`assayer` — `execute`, `wright` — `all`.
+
+`execute` не запрещает запись. Запущенная команда пишет все, что доступно
+пользователю процесса. Это дисциплина роли, а не изоляция.
+
+## Повышение полномочий
+
+Разовый выход за нанятый режим — это просьба о повышении, а не вопрос. Воркер
+называет недостающий класс (`read`, `write` или `execute`) и обоснование.
+Оркестратор отвечает `priiisk grant <id>` или `priiisk grant <id> --deny`.
+Разрешение открывает окно до конца хода, пока воркер не вернет результат;
+прерывание, ошибка и повтор окно не закрывают. Следующая надобность — новая
+просьба. Нанятый режим при этом не меняется.
+
+## Рабочее пространство воркера
+
+`priiisk hire --workspace worktree` создает именованное пространство с
+собственным деревом и веткой. Второго воркера сажают туда по имени:
+`priiisk hire --workspace <name>`. Так проверяющий читает работу пишущего до
+слияния. Это не песочница: object database, refs, конфигурация репозитория,
+hooks и права пользователя того же репозитория остаются общими. Закрытие
+кооперативное. Готовую работу забирают обычным `git merge`.
+
+`priiisk workspace list` показывает, кто в каком пространстве живет.
+`priiisk workspace forget <name>` убирает пустое именованное пространство.
+`priiisk workspace sweep` показывает осиротевшие деревья после сбоя: пустое
+именованное пространство сиротой не считается. `--confirm` удаляет только
+чистые деревья, чья ветка уже достижима из другой ссылки. Грязное дерево и
+дерево с невлитой веткой команда оставляет на месте.
+
+## Настройка
+
+Лагерь читает один пользовательский TOML-файл:
+`$XDG_CONFIG_HOME/priiisk/config.toml`, а если `XDG_CONFIG_HOME` не задан —
+`~/.config/priiisk/config.toml`.
+
+Файл проходит строгую проверку целиком. Неизвестное поле отклоняется.
+Молчаливо игнорируемых настроек нет.
+
+### Перед первым лагерем: сначала агент-рантайм
+
+priiisk исполняет воркеров рантаймом pi и **наследует его провайдеров, модели и
+авторизацию**. Своих токенов он не хранит и чужой реестр моделей не копирует:
+модель существует для лагеря только если она уже существует там.
+
+Отсюда жесткий порядок, который легко нарушить:
+
+1. Войти в pi и подключить провайдеров, которыми собираетесь пользоваться.
+   Добавление провайдера и продление авторизации делаются средствами pi, а не
+   отсюда.
+2. Узнать у pi, какие ссылки `provider/model` вам действительно доступны.
+   Лагерь принимает точную ссылку, а не семейство и не отображаемое имя.
+3. Связать эти ссылки короткими алиасами в конфиге ниже и пользоваться в ролях
+   и пресетах алиасами.
+4. Выполнить `priiisk doctor`. Он подтверждает, что каждый алиас резолвится в
+   каталоге pi и что авторизация для него есть, — чтением каталога, без отправки
+   запроса и без трат.
+
+Пропуск первых двух шагов — обычный первый отказ: конфиг проходит проверку,
+лагерь поднимается, а первый наем умирает, потому что ссылка на модель никому
+не принадлежит.
+
+Минимальный файл. Перед `camp up` подставьте оба `id`; плейсхолдеры ниже — только обязательная форма `provider/model`:
+
+```toml
+schemaVersion = 2
+
+[defaults]
+model = "strong"
+thinking = "medium"
+
+[models.strong]
+id = "provider/model"
+
+[models.fast]
+id = "provider/model"
+
+[roles.assayer]
+description = "Review worker"
+model = "strong"
+thinking = "high"
+access = "execute"
+
+[hirePresets.safe-review]
+description = "Review without a shell"
+role = "assayer"
+access = "read-only"
+```
+
+Подставьте в оба `id` модели из своего агент-рантайма. `defaults.model` и
+`defaults.thinking` обязательны. Пресет найма может назвать встроенную роль
+(`wright`, `assayer`, `prospector`) и сузить доступ.
+
+Репозиторий может держать `.priiisk/config.toml` и переопределять им политику
+из пользовательского файла: модели, роли, пресеты найма, группы навыков,
+defaults и workspace. Определения MCP-серверов и каталог внешних бинарей из
+репозитория не читаются: эти поля задают то, что лагерь запустит, и чтение их
+из клона означало бы исполнение чужого кода при первом же `hire`.

package/bin/priiisk.mjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+/*
+ * The installed `priiisk` command. npm cannot choose a `bin` per platform, so the
+ * entry package ships this shim and the executable travels in a platform build
+ * that npm installs only where its `os`/`cpu` match.
+ *
+ * The shim hands the terminal over untouched — the cabin is a full-screen TUI and
+ * a pipe in place of the terminal would break it — and it does not interpret
+ * signals: the terminal delivers them to the whole process group, so the binary
+ * decides when to stop and this process only reports how it ended.
+ */
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+
+/*
+ * An alias, not a registry name: the entry package installs the platform build
+ * under this name from a version of `priiisk` itself. The manifest is what gets
+ * resolved rather than the executable, because a package is always allowed to
+ * answer for its own manifest.
+ */
+const platformPackage = `priiisk-${process.platform}-${process.arch}`;
+
+let binaryPath;
+try {
+  const manifest = createRequire(import.meta.url).resolve(`${platformPackage}/package.json`);
+  binaryPath = join(dirname(manifest), "bin", "priiisk");
+} catch {
+  binaryPath = undefined;
+}
+
+if (binaryPath === undefined || !existsSync(binaryPath)) {
+  process.stderr.write(
+    `priiisk: no executable for ${process.platform} ${process.arch}.\n` +
+      `The platform build ${platformPackage} is missing. It is an optional dependency, so an\n` +
+      `install run with optional dependencies disabled leaves it out; reinstall with\n` +
+      `npm install -g priiisk@latest. If nothing exists for this platform, it is not published.\n`,
+  );
+  process.exit(1);
+}
+
+const child = spawn(binaryPath, process.argv.slice(2), { stdio: "inherit" });
+
+/*
+ * Signals reach the binary through the process group. Ignoring them here keeps
+ * this process alive until the binary has finished handling its own shutdown,
+ * instead of leaving it orphaned mid-stop.
+ */
+for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) process.on(signal, () => {});
+
+child.on("error", (error) => {
+  process.stderr.write(`priiisk: cannot start ${binaryPath}: ${error.message}\n`);
+  process.exit(1);
+});
+
+child.on("exit", (code, signal) => {
+  if (signal !== null) {
+    // Die the same way the binary died, so a caller reading the status sees the signal.
+    process.removeAllListeners(signal);
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 0);
+});

package/package.json

@@ -1,15 +1,23 @@
 {
   "name": "priiisk",
-  "version": "0.22.0-linux-x64",
-  "description": "priiisk executable for linux x64",
-  "os": [
-    "linux"
-  ],
-  "cpu": [
-    "x64"
-  ],
+  "version": "0.22.0",
+  "description": "CLI for running and observing a camp of collaborating agents",
+  "type": "module",
+  "bin": {
+    "priiisk": "./bin/priiisk.mjs"
+  },
   "files": [
-    "bin/priiisk",
-    "README.md"
-  ]
+    "bin/priiisk.mjs",
+    "README.md",
+    "README.ru.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "optionalDependencies": {
+    "priiisk-linux-x64": "npm:priiisk@0.22.0-linux-x64",
+    "priiisk-linux-arm64": "npm:priiisk@0.22.0-linux-arm64",
+    "priiisk-darwin-x64": "npm:priiisk@0.22.0-darwin-x64",
+    "priiisk-darwin-arm64": "npm:priiisk@0.22.0-darwin-arm64"
+  }
 }