ifuri-todo-agent 0.6.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- ifuri_todo_agent-0.6.0/LICENSE +21 -0
- ifuri_todo_agent-0.6.0/PKG-INFO +233 -0
- ifuri_todo_agent-0.6.0/README.md +212 -0
- ifuri_todo_agent-0.6.0/pyproject.toml +49 -0
- ifuri_todo_agent-0.6.0/setup.cfg +4 -0
- ifuri_todo_agent-0.6.0/src/ifuri_todo_agent.egg-info/PKG-INFO +233 -0
- ifuri_todo_agent-0.6.0/src/ifuri_todo_agent.egg-info/SOURCES.txt +32 -0
- ifuri_todo_agent-0.6.0/src/ifuri_todo_agent.egg-info/dependency_links.txt +1 -0
- ifuri_todo_agent-0.6.0/src/ifuri_todo_agent.egg-info/entry_points.txt +2 -0
- ifuri_todo_agent-0.6.0/src/ifuri_todo_agent.egg-info/requires.txt +13 -0
- ifuri_todo_agent-0.6.0/src/ifuri_todo_agent.egg-info/top_level.txt +1 -0
- ifuri_todo_agent-0.6.0/src/todo_agent/__init__.py +12 -0
- ifuri_todo_agent-0.6.0/src/todo_agent/__main__.py +3 -0
- ifuri_todo_agent-0.6.0/src/todo_agent/bootstrap.py +114 -0
- ifuri_todo_agent-0.6.0/src/todo_agent/cli.py +247 -0
- ifuri_todo_agent-0.6.0/src/todo_agent/config.py +54 -0
- ifuri_todo_agent-0.6.0/src/todo_agent/cron.py +99 -0
- ifuri_todo_agent-0.6.0/src/todo_agent/discovery.py +61 -0
- ifuri_todo_agent-0.6.0/src/todo_agent/planfile_backend.py +175 -0
- ifuri_todo_agent-0.6.0/src/todo_agent/process.py +187 -0
- ifuri_todo_agent-0.6.0/src/todo_agent/reporting.py +47 -0
- ifuri_todo_agent-0.6.0/src/todo_agent/runner.py +482 -0
- ifuri_todo_agent-0.6.0/src/todo_agent/scaffold.py +219 -0
- ifuri_todo_agent-0.6.0/src/todo_agent/schema.py +219 -0
- ifuri_todo_agent-0.6.0/src/todo_agent/security.py +83 -0
- ifuri_todo_agent-0.6.0/src/todo_agent/target.py +78 -0
- ifuri_todo_agent-0.6.0/tests/test_bootstrap_target.py +26 -0
- ifuri_todo_agent-0.6.0/tests/test_cron.py +44 -0
- ifuri_todo_agent-0.6.0/tests/test_planfile_backend.py +65 -0
- ifuri_todo_agent-0.6.0/tests/test_process.py +73 -0
- ifuri_todo_agent-0.6.0/tests/test_runner.py +37 -0
- ifuri_todo_agent-0.6.0/tests/test_scaffold.py +52 -0
- ifuri_todo_agent-0.6.0/tests/test_schema_and_discovery.py +43 -0
- ifuri_todo_agent-0.6.0/tests/test_security.py +39 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 todo-agent maintainers
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,233 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: ifuri-todo-agent
|
|
3
|
+
Version: 0.6.0
|
|
4
|
+
Summary: Central task registry and deterministic three-agent orchestrator for doctor-agent, repair-agent and validator-agent.
|
|
5
|
+
Author: todo-agent maintainers
|
|
6
|
+
License: MIT
|
|
7
|
+
Requires-Python: >=3.11
|
|
8
|
+
Description-Content-Type: text/markdown
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Requires-Dist: jsonschema<5,>=4.23
|
|
11
|
+
Requires-Dist: PyYAML<7,>=6.0.2
|
|
12
|
+
Provides-Extra: dev
|
|
13
|
+
Requires-Dist: pytest<10,>=8.3; extra == "dev"
|
|
14
|
+
Requires-Dist: pytest-cov<7,>=6; extra == "dev"
|
|
15
|
+
Requires-Dist: ruff<1,>=0.12; extra == "dev"
|
|
16
|
+
Provides-Extra: planfile
|
|
17
|
+
Requires-Dist: planfile>=0.1.111; extra == "planfile"
|
|
18
|
+
Provides-Extra: urirun
|
|
19
|
+
Requires-Dist: urirun>=0.4.190; extra == "urirun"
|
|
20
|
+
Dynamic: license-file
|
|
21
|
+
|
|
22
|
+
# todo-agent
|
|
23
|
+
|
|
24
|
+
`todo-agent` jest centralnym rejestrem pakietów zadań i deterministyczną warstwą orkiestracji dla trzech istniejących wykonawców:
|
|
25
|
+
|
|
26
|
+
- **doctor-agent** — diagnoza i dowody, bez naprawiania systemu,
|
|
27
|
+
- **repair-agent** — plan lub kontrolowana zmiana przez pull request,
|
|
28
|
+
- **validator-agent** — niezależna walidacja diagnozy, planu i rezultatów.
|
|
29
|
+
|
|
30
|
+
Repozytorium nie zastępuje tych agentów. Stanowi **control plane**:
|
|
31
|
+
przechowuje kontrakty zadań, wybiera zadania gotowe do wykonania, uruchamia etapy w stałej kolejności i waliduje hand-offy JSON. Agenci pozostają osobnymi **execution planes** z własną logiką domenową.
|
|
32
|
+
|
|
33
|
+
## Najważniejsze właściwości
|
|
34
|
+
|
|
35
|
+
- jedna, walidowana definicja `task.yaml`,
|
|
36
|
+
- katalog per zadanie i per agent: `TODO/<id>/<agent>/...`,
|
|
37
|
+
- sekwencja `doctor → repair → validator`,
|
|
38
|
+
- izolowany katalog każdego uruchomienia,
|
|
39
|
+
- ścisłe kontrakty JSON Schema dla wyników agentów,
|
|
40
|
+
- planowanie harmonogramu z timezone zapisanym w zadaniu,
|
|
41
|
+
- domyślny tryb bez zapisu; mutacje wyłącznie jako pull request po zatwierdzeniu środowiska,
|
|
42
|
+
- uwierzytelnianie między repozytoriami krótkotrwałym tokenem GitHub App,
|
|
43
|
+
- deterministyczne generowanie scaffoldów oraz opcjonalne wejście NL przez GitHub Models,
|
|
44
|
+
- brak obowiązkowej zależności od płatnego GitHub Copilot/Codex,
|
|
45
|
+
- opcjonalny rejestr zadań na `planfile` (`todo-agent tickets`),
|
|
46
|
+
- opcjonalne monitorowanie procesów na `urirun` (`todo-agent process`).
|
|
47
|
+
|
|
48
|
+
## Struktura repozytorium
|
|
49
|
+
|
|
50
|
+
```text
|
|
51
|
+
.
|
|
52
|
+
├── TODO/
|
|
53
|
+
│ └── 0001_org-repo-audit/
|
|
54
|
+
│ ├── task.yaml
|
|
55
|
+
│ ├── README.md
|
|
56
|
+
│ ├── doctor-agent/{README.md,run.py,input/,output/,logs/}
|
|
57
|
+
│ ├── repair-agent/{README.md,run.py,input/,output/,logs/}
|
|
58
|
+
│ └── validator-agent/{README.md,run.py,input/,output/,logs/}
|
|
59
|
+
├── schemas/ # kontrakty zadań, agentów i repo docelowych
|
|
60
|
+
├── src/todo_agent/ # discovery, walidacja, runner, scaffold i bootstrap
|
|
61
|
+
├── scripts/ # cienkie entrypointy do CI
|
|
62
|
+
├── templates/ # czytelne szablony dla ludzi
|
|
63
|
+
├── docs/ # architektura, bezpieczeństwo i plan wdrożenia
|
|
64
|
+
└── .github/workflows/ # CI, orkiestrator, ręczne uruchomienie i generator NL
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
## Pakiet zadania
|
|
68
|
+
|
|
69
|
+
`task.yaml` jest źródłem prawdy dla automatu. `README.md` zawiera kontekst dla człowieka. Każdy agent ma własny entrypoint i katalogi runtime.
|
|
70
|
+
|
|
71
|
+
```text
|
|
72
|
+
TODO/0042_customer-mail-triage/
|
|
73
|
+
├── task.yaml
|
|
74
|
+
├── README.md
|
|
75
|
+
├── doctor-agent/
|
|
76
|
+
│ ├── README.md
|
|
77
|
+
│ ├── run.py
|
|
78
|
+
│ ├── input/
|
|
79
|
+
│ ├── output/
|
|
80
|
+
│ └── logs/
|
|
81
|
+
├── repair-agent/
|
|
82
|
+
└── validator-agent/
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Status `ready` oznacza, że kod zadania, kontrakty i kryteria akceptacji są gotowe do uruchomienia. Generator zawsze tworzy task ze statusem `todo`, aby wygenerowana treść nie została wykonana bez przeglądu.
|
|
86
|
+
|
|
87
|
+
## Rejestr zadań (planfile) i procesy (urirun)
|
|
88
|
+
|
|
89
|
+
todo-agent działa w oparciu o **listę zadań** i **monitorowanie procesów**, ale
|
|
90
|
+
oba filary są od siebie oddzielone i obie zależności są opcjonalne:
|
|
91
|
+
|
|
92
|
+
- **Lista zadań — `planfile`.** Kontraktem wykonania pozostaje
|
|
93
|
+
`TODO/<id>/task.yaml`, natomiast rejestrem/backlogiem jest store `planfile`.
|
|
94
|
+
Każde zadanie jest rzutowane na bilet planfile (dopasowanie po etykiecie
|
|
95
|
+
`task:<id>`, idempotentnie), więc wybór następnego zadania korzysta z
|
|
96
|
+
kontraktu runnability planfile, a backlog jest wspólny z resztą toolchainu.
|
|
97
|
+
- **Procesy — `urirun`.** Uruchomienie zadania może działać jako proces
|
|
98
|
+
adresowany URI `agent://todo/<task>/run` z trwałym rekordem (pid, log, kod
|
|
99
|
+
wyjścia) i podglądem stanu running/exit przez `urirun.host.work_runs`.
|
|
100
|
+
Domyślny izolowany runner (`todo-agent run`) pozostaje synchroniczny; warstwa
|
|
101
|
+
`todo-agent process` dokłada uruchamianie w tle z monitoringiem.
|
|
102
|
+
|
|
103
|
+
Instalacja z warstwami opcjonalnymi:
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
python -m pip install -e '.[dev,planfile,urirun]'
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Rejestr zadań (planfile):
|
|
110
|
+
|
|
111
|
+
```bash
|
|
112
|
+
todo-agent tickets sync . # rzutuj TODO/*/task.yaml na bilety planfile
|
|
113
|
+
todo-agent tickets list . --status open
|
|
114
|
+
todo-agent tickets next . # następny bilet zgodny z kontraktem runnability
|
|
115
|
+
todo-agent tickets status . PLF-001 in_progress
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
Monitorowanie procesów (urirun):
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
todo-agent process launch . 0001_org-repo-audit --wait # uruchom jako proces URI
|
|
122
|
+
todo-agent process list . # stan running/exit + tail logów
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
Bez zainstalowanych warstw polecenia zwracają czytelny błąd z podpowiedzią
|
|
126
|
+
instalacji; rdzeń (`validate`, `discover`, `run`, `scaffold`) nie wymaga żadnej
|
|
127
|
+
z nich. Szczegóły: `docs/integrations/planfile.md`, `docs/integrations/urirun.md`.
|
|
128
|
+
|
|
129
|
+
## Uruchomienie lokalne
|
|
130
|
+
|
|
131
|
+
Wymagany jest Python 3.11+.
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
python -m venv .venv
|
|
135
|
+
. .venv/bin/activate
|
|
136
|
+
python -m pip install -e '.[dev]'
|
|
137
|
+
make check
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Walidacja i discovery:
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
todo-agent validate .
|
|
144
|
+
todo-agent discover . --event manual
|
|
145
|
+
todo-agent discover . --event schedule --now 2026-07-15T00:15:00Z
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
Test zadania audytowego bez połączenia z GitHubem:
|
|
149
|
+
|
|
150
|
+
```bash
|
|
151
|
+
GITHUB_ORG=example-org \
|
|
152
|
+
TODO_AGENT_AUDIT_FIXTURE="$PWD/TODO/0001_org-repo-audit/doctor-agent/input/sample-organization.json" \
|
|
153
|
+
todo-agent run . 0001_org-repo-audit
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
Wynik pojawi się w `.todo-agent-runs/<task-id>/<run-id>/` i zawiera manifest, raport zbiorczy oraz artefakty każdego agenta.
|
|
157
|
+
|
|
158
|
+
## Generowanie kompletnego zadania
|
|
159
|
+
|
|
160
|
+
Generator deterministyczny nie używa modelu:
|
|
161
|
+
|
|
162
|
+
```bash
|
|
163
|
+
todo-agent scaffold . \
|
|
164
|
+
--title "Analiza nieodebranych wiadomości klientów" \
|
|
165
|
+
--description "Zidentyfikuj wiadomości bez odpowiedzi, przygotuj szkice i zweryfikuj politykę komunikacji." \
|
|
166
|
+
--type customer-support \
|
|
167
|
+
--priority high \
|
|
168
|
+
--scope-level external
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
Można również przekazać JSON zgodny z `schemas/task-spec.schema.json`:
|
|
172
|
+
|
|
173
|
+
```bash
|
|
174
|
+
todo-agent scaffold . --spec-file task-spec.json
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
Workflow `generate-task-from-nl.yml` jest opcjonalnym front-endem: GitHub Models zamienia opis na mały JSON, a ten sam deterministyczny generator tworzy pliki i otwiera draft pull request. Odpowiedź modelu nigdy nie jest wykonywana bezpośrednio.
|
|
178
|
+
|
|
179
|
+
## GitHub Actions i dostęp do organizacji
|
|
180
|
+
|
|
181
|
+
Do audytu wielu repozytoriów skonfiguruj:
|
|
182
|
+
|
|
183
|
+
- variable `GITHUB_ORG`,
|
|
184
|
+
- variable `TODO_AGENT_APP_CLIENT_ID`,
|
|
185
|
+
- secret `TODO_AGENT_APP_PRIVATE_KEY`,
|
|
186
|
+
- środowisko `todo-agent-apply` z wymaganymi reviewerami dla tasków `pull-request`.
|
|
187
|
+
|
|
188
|
+
Wbudowany `GITHUB_TOKEN` pozostaje wystarczający dla samego repo `todo-agent`. Odczyt lub zapis w innych repozytoriach wykorzystuje token instalacyjny GitHub App. Minimalne uprawnienia są opisane w `docs/github-app.md`.
|
|
189
|
+
|
|
190
|
+
## Standard repozytorium docelowego
|
|
191
|
+
|
|
192
|
+
Każdy projekt powinien zawierać co najmniej:
|
|
193
|
+
|
|
194
|
+
- `README.md` — cel, instalacja, użycie i utrzymanie,
|
|
195
|
+
- `TODO.md` — wyłącznie aktywne zadania,
|
|
196
|
+
- `CHANGELOG.md` — `[Unreleased]` oraz wpis bieżącej wersji,
|
|
197
|
+
- `VERSION` — pojedyncza wartość SemVer,
|
|
198
|
+
- `AGENTS.md` — wskazówki dla agentów i LLM,
|
|
199
|
+
- `PROJECT_NOTES.md` — robocze przemyślenia człowieka,
|
|
200
|
+
- `DECISIONS.md` lub ADR — trwałe decyzje,
|
|
201
|
+
- `.github/todo-agent.yml` — maszynowa konfiguracja build/test/release.
|
|
202
|
+
|
|
203
|
+
Plan bezpiecznego utworzenia brakujących plików:
|
|
204
|
+
|
|
205
|
+
```bash
|
|
206
|
+
todo-agent bootstrap-target /path/to/repository
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
Zapis, bez nadpisywania istniejących plików:
|
|
210
|
+
|
|
211
|
+
```bash
|
|
212
|
+
todo-agent bootstrap-target /path/to/repository --apply
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
Szczegółowa kolejność prac dla `doctor-agent`, `repair-agent`, `validator-agent` i pozostałych repozytoriów znajduje się w `docs/rollout.md`.
|
|
216
|
+
|
|
217
|
+
## Model bezpieczeństwa
|
|
218
|
+
|
|
219
|
+
1. Workflow z pull requesta tylko waliduje — nie uruchamia tasków ani nie otrzymuje tokenu organizacyjnego.
|
|
220
|
+
2. Harmonogram działa z domyślnej gałęzi i wykonuje tylko taski `ready`.
|
|
221
|
+
3. Kod taska jest kopiowany do izolowanego workspace; ścieżki wychodzące poza pakiet i symlinkowane entrypointy są odrzucane.
|
|
222
|
+
4. Repair-agent nie może pisać, dopóki task nie ma `mutation_mode: pull-request`, workflow nie otrzyma `apply_changes: true`, a chronione środowisko nie zostanie zatwierdzone.
|
|
223
|
+
5. Validator-agent nie współdzieli implementacji naprawy i nie poprawia wyników poprzednich agentów.
|
|
224
|
+
6. Sekrety są filtrowane przez allowlistę zmiennych środowiskowych i nie trafiają do artefaktów.
|
|
225
|
+
|
|
226
|
+
Więcej: `docs/security.md`.
|
|
227
|
+
|
|
228
|
+
## Cykl TODO / CHANGELOG / VERSION
|
|
229
|
+
|
|
230
|
+
- `TODO.md` pokazuje tylko aktualne działania.
|
|
231
|
+
- Po wykonaniu pozycja jest usuwana z aktywnego TODO i opisywana pod `[Unreleased]` w `CHANGELOG.md`.
|
|
232
|
+
- Przy wydaniu `[Unreleased]` staje się sekcją wersji, następnie aktualizowany jest `VERSION` i tworzona jest nowa pusta sekcja `[Unreleased]`.
|
|
233
|
+
- Nie zwiększaj wersji tylko dlatego, że LLM zmienił dokumentację; decyzja wersjonowania należy do właściciela wydania.
|
|
@@ -0,0 +1,212 @@
|
|
|
1
|
+
# todo-agent
|
|
2
|
+
|
|
3
|
+
`todo-agent` jest centralnym rejestrem pakietów zadań i deterministyczną warstwą orkiestracji dla trzech istniejących wykonawców:
|
|
4
|
+
|
|
5
|
+
- **doctor-agent** — diagnoza i dowody, bez naprawiania systemu,
|
|
6
|
+
- **repair-agent** — plan lub kontrolowana zmiana przez pull request,
|
|
7
|
+
- **validator-agent** — niezależna walidacja diagnozy, planu i rezultatów.
|
|
8
|
+
|
|
9
|
+
Repozytorium nie zastępuje tych agentów. Stanowi **control plane**:
|
|
10
|
+
przechowuje kontrakty zadań, wybiera zadania gotowe do wykonania, uruchamia etapy w stałej kolejności i waliduje hand-offy JSON. Agenci pozostają osobnymi **execution planes** z własną logiką domenową.
|
|
11
|
+
|
|
12
|
+
## Najważniejsze właściwości
|
|
13
|
+
|
|
14
|
+
- jedna, walidowana definicja `task.yaml`,
|
|
15
|
+
- katalog per zadanie i per agent: `TODO/<id>/<agent>/...`,
|
|
16
|
+
- sekwencja `doctor → repair → validator`,
|
|
17
|
+
- izolowany katalog każdego uruchomienia,
|
|
18
|
+
- ścisłe kontrakty JSON Schema dla wyników agentów,
|
|
19
|
+
- planowanie harmonogramu z timezone zapisanym w zadaniu,
|
|
20
|
+
- domyślny tryb bez zapisu; mutacje wyłącznie jako pull request po zatwierdzeniu środowiska,
|
|
21
|
+
- uwierzytelnianie między repozytoriami krótkotrwałym tokenem GitHub App,
|
|
22
|
+
- deterministyczne generowanie scaffoldów oraz opcjonalne wejście NL przez GitHub Models,
|
|
23
|
+
- brak obowiązkowej zależności od płatnego GitHub Copilot/Codex,
|
|
24
|
+
- opcjonalny rejestr zadań na `planfile` (`todo-agent tickets`),
|
|
25
|
+
- opcjonalne monitorowanie procesów na `urirun` (`todo-agent process`).
|
|
26
|
+
|
|
27
|
+
## Struktura repozytorium
|
|
28
|
+
|
|
29
|
+
```text
|
|
30
|
+
.
|
|
31
|
+
├── TODO/
|
|
32
|
+
│ └── 0001_org-repo-audit/
|
|
33
|
+
│ ├── task.yaml
|
|
34
|
+
│ ├── README.md
|
|
35
|
+
│ ├── doctor-agent/{README.md,run.py,input/,output/,logs/}
|
|
36
|
+
│ ├── repair-agent/{README.md,run.py,input/,output/,logs/}
|
|
37
|
+
│ └── validator-agent/{README.md,run.py,input/,output/,logs/}
|
|
38
|
+
├── schemas/ # kontrakty zadań, agentów i repo docelowych
|
|
39
|
+
├── src/todo_agent/ # discovery, walidacja, runner, scaffold i bootstrap
|
|
40
|
+
├── scripts/ # cienkie entrypointy do CI
|
|
41
|
+
├── templates/ # czytelne szablony dla ludzi
|
|
42
|
+
├── docs/ # architektura, bezpieczeństwo i plan wdrożenia
|
|
43
|
+
└── .github/workflows/ # CI, orkiestrator, ręczne uruchomienie i generator NL
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## Pakiet zadania
|
|
47
|
+
|
|
48
|
+
`task.yaml` jest źródłem prawdy dla automatu. `README.md` zawiera kontekst dla człowieka. Każdy agent ma własny entrypoint i katalogi runtime.
|
|
49
|
+
|
|
50
|
+
```text
|
|
51
|
+
TODO/0042_customer-mail-triage/
|
|
52
|
+
├── task.yaml
|
|
53
|
+
├── README.md
|
|
54
|
+
├── doctor-agent/
|
|
55
|
+
│ ├── README.md
|
|
56
|
+
│ ├── run.py
|
|
57
|
+
│ ├── input/
|
|
58
|
+
│ ├── output/
|
|
59
|
+
│ └── logs/
|
|
60
|
+
├── repair-agent/
|
|
61
|
+
└── validator-agent/
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Status `ready` oznacza, że kod zadania, kontrakty i kryteria akceptacji są gotowe do uruchomienia. Generator zawsze tworzy task ze statusem `todo`, aby wygenerowana treść nie została wykonana bez przeglądu.
|
|
65
|
+
|
|
66
|
+
## Rejestr zadań (planfile) i procesy (urirun)
|
|
67
|
+
|
|
68
|
+
todo-agent działa w oparciu o **listę zadań** i **monitorowanie procesów**, ale
|
|
69
|
+
oba filary są od siebie oddzielone i obie zależności są opcjonalne:
|
|
70
|
+
|
|
71
|
+
- **Lista zadań — `planfile`.** Kontraktem wykonania pozostaje
|
|
72
|
+
`TODO/<id>/task.yaml`, natomiast rejestrem/backlogiem jest store `planfile`.
|
|
73
|
+
Każde zadanie jest rzutowane na bilet planfile (dopasowanie po etykiecie
|
|
74
|
+
`task:<id>`, idempotentnie), więc wybór następnego zadania korzysta z
|
|
75
|
+
kontraktu runnability planfile, a backlog jest wspólny z resztą toolchainu.
|
|
76
|
+
- **Procesy — `urirun`.** Uruchomienie zadania może działać jako proces
|
|
77
|
+
adresowany URI `agent://todo/<task>/run` z trwałym rekordem (pid, log, kod
|
|
78
|
+
wyjścia) i podglądem stanu running/exit przez `urirun.host.work_runs`.
|
|
79
|
+
Domyślny izolowany runner (`todo-agent run`) pozostaje synchroniczny; warstwa
|
|
80
|
+
`todo-agent process` dokłada uruchamianie w tle z monitoringiem.
|
|
81
|
+
|
|
82
|
+
Instalacja z warstwami opcjonalnymi:
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
python -m pip install -e '.[dev,planfile,urirun]'
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Rejestr zadań (planfile):
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
todo-agent tickets sync . # rzutuj TODO/*/task.yaml na bilety planfile
|
|
92
|
+
todo-agent tickets list . --status open
|
|
93
|
+
todo-agent tickets next . # następny bilet zgodny z kontraktem runnability
|
|
94
|
+
todo-agent tickets status . PLF-001 in_progress
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Monitorowanie procesów (urirun):
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
todo-agent process launch . 0001_org-repo-audit --wait # uruchom jako proces URI
|
|
101
|
+
todo-agent process list . # stan running/exit + tail logów
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
Bez zainstalowanych warstw polecenia zwracają czytelny błąd z podpowiedzią
|
|
105
|
+
instalacji; rdzeń (`validate`, `discover`, `run`, `scaffold`) nie wymaga żadnej
|
|
106
|
+
z nich. Szczegóły: `docs/integrations/planfile.md`, `docs/integrations/urirun.md`.
|
|
107
|
+
|
|
108
|
+
## Uruchomienie lokalne
|
|
109
|
+
|
|
110
|
+
Wymagany jest Python 3.11+.
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
python -m venv .venv
|
|
114
|
+
. .venv/bin/activate
|
|
115
|
+
python -m pip install -e '.[dev]'
|
|
116
|
+
make check
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
Walidacja i discovery:
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
todo-agent validate .
|
|
123
|
+
todo-agent discover . --event manual
|
|
124
|
+
todo-agent discover . --event schedule --now 2026-07-15T00:15:00Z
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Test zadania audytowego bez połączenia z GitHubem:
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
GITHUB_ORG=example-org \
|
|
131
|
+
TODO_AGENT_AUDIT_FIXTURE="$PWD/TODO/0001_org-repo-audit/doctor-agent/input/sample-organization.json" \
|
|
132
|
+
todo-agent run . 0001_org-repo-audit
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
Wynik pojawi się w `.todo-agent-runs/<task-id>/<run-id>/` i zawiera manifest, raport zbiorczy oraz artefakty każdego agenta.
|
|
136
|
+
|
|
137
|
+
## Generowanie kompletnego zadania
|
|
138
|
+
|
|
139
|
+
Generator deterministyczny nie używa modelu:
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
todo-agent scaffold . \
|
|
143
|
+
--title "Analiza nieodebranych wiadomości klientów" \
|
|
144
|
+
--description "Zidentyfikuj wiadomości bez odpowiedzi, przygotuj szkice i zweryfikuj politykę komunikacji." \
|
|
145
|
+
--type customer-support \
|
|
146
|
+
--priority high \
|
|
147
|
+
--scope-level external
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
Można również przekazać JSON zgodny z `schemas/task-spec.schema.json`:
|
|
151
|
+
|
|
152
|
+
```bash
|
|
153
|
+
todo-agent scaffold . --spec-file task-spec.json
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
Workflow `generate-task-from-nl.yml` jest opcjonalnym front-endem: GitHub Models zamienia opis na mały JSON, a ten sam deterministyczny generator tworzy pliki i otwiera draft pull request. Odpowiedź modelu nigdy nie jest wykonywana bezpośrednio.
|
|
157
|
+
|
|
158
|
+
## GitHub Actions i dostęp do organizacji
|
|
159
|
+
|
|
160
|
+
Do audytu wielu repozytoriów skonfiguruj:
|
|
161
|
+
|
|
162
|
+
- variable `GITHUB_ORG`,
|
|
163
|
+
- variable `TODO_AGENT_APP_CLIENT_ID`,
|
|
164
|
+
- secret `TODO_AGENT_APP_PRIVATE_KEY`,
|
|
165
|
+
- środowisko `todo-agent-apply` z wymaganymi reviewerami dla tasków `pull-request`.
|
|
166
|
+
|
|
167
|
+
Wbudowany `GITHUB_TOKEN` pozostaje wystarczający dla samego repo `todo-agent`. Odczyt lub zapis w innych repozytoriach wykorzystuje token instalacyjny GitHub App. Minimalne uprawnienia są opisane w `docs/github-app.md`.
|
|
168
|
+
|
|
169
|
+
## Standard repozytorium docelowego
|
|
170
|
+
|
|
171
|
+
Każdy projekt powinien zawierać co najmniej:
|
|
172
|
+
|
|
173
|
+
- `README.md` — cel, instalacja, użycie i utrzymanie,
|
|
174
|
+
- `TODO.md` — wyłącznie aktywne zadania,
|
|
175
|
+
- `CHANGELOG.md` — `[Unreleased]` oraz wpis bieżącej wersji,
|
|
176
|
+
- `VERSION` — pojedyncza wartość SemVer,
|
|
177
|
+
- `AGENTS.md` — wskazówki dla agentów i LLM,
|
|
178
|
+
- `PROJECT_NOTES.md` — robocze przemyślenia człowieka,
|
|
179
|
+
- `DECISIONS.md` lub ADR — trwałe decyzje,
|
|
180
|
+
- `.github/todo-agent.yml` — maszynowa konfiguracja build/test/release.
|
|
181
|
+
|
|
182
|
+
Plan bezpiecznego utworzenia brakujących plików:
|
|
183
|
+
|
|
184
|
+
```bash
|
|
185
|
+
todo-agent bootstrap-target /path/to/repository
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
Zapis, bez nadpisywania istniejących plików:
|
|
189
|
+
|
|
190
|
+
```bash
|
|
191
|
+
todo-agent bootstrap-target /path/to/repository --apply
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
Szczegółowa kolejność prac dla `doctor-agent`, `repair-agent`, `validator-agent` i pozostałych repozytoriów znajduje się w `docs/rollout.md`.
|
|
195
|
+
|
|
196
|
+
## Model bezpieczeństwa
|
|
197
|
+
|
|
198
|
+
1. Workflow z pull requesta tylko waliduje — nie uruchamia tasków ani nie otrzymuje tokenu organizacyjnego.
|
|
199
|
+
2. Harmonogram działa z domyślnej gałęzi i wykonuje tylko taski `ready`.
|
|
200
|
+
3. Kod taska jest kopiowany do izolowanego workspace; ścieżki wychodzące poza pakiet i symlinkowane entrypointy są odrzucane.
|
|
201
|
+
4. Repair-agent nie może pisać, dopóki task nie ma `mutation_mode: pull-request`, workflow nie otrzyma `apply_changes: true`, a chronione środowisko nie zostanie zatwierdzone.
|
|
202
|
+
5. Validator-agent nie współdzieli implementacji naprawy i nie poprawia wyników poprzednich agentów.
|
|
203
|
+
6. Sekrety są filtrowane przez allowlistę zmiennych środowiskowych i nie trafiają do artefaktów.
|
|
204
|
+
|
|
205
|
+
Więcej: `docs/security.md`.
|
|
206
|
+
|
|
207
|
+
## Cykl TODO / CHANGELOG / VERSION
|
|
208
|
+
|
|
209
|
+
- `TODO.md` pokazuje tylko aktualne działania.
|
|
210
|
+
- Po wykonaniu pozycja jest usuwana z aktywnego TODO i opisywana pod `[Unreleased]` w `CHANGELOG.md`.
|
|
211
|
+
- Przy wydaniu `[Unreleased]` staje się sekcją wersji, następnie aktualizowany jest `VERSION` i tworzona jest nowa pusta sekcja `[Unreleased]`.
|
|
212
|
+
- Nie zwiększaj wersji tylko dlatego, że LLM zmienił dokumentację; decyzja wersjonowania należy do właściciela wydania.
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=77", "wheel"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "ifuri-todo-agent"
|
|
7
|
+
version = "0.6.0"
|
|
8
|
+
description = "Central task registry and deterministic three-agent orchestrator for doctor-agent, repair-agent and validator-agent."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.11"
|
|
11
|
+
license = {text = "MIT"}
|
|
12
|
+
authors = [{name = "todo-agent maintainers"}]
|
|
13
|
+
dependencies = [
|
|
14
|
+
"jsonschema>=4.23,<5",
|
|
15
|
+
"PyYAML>=6.0.2,<7"
|
|
16
|
+
]
|
|
17
|
+
|
|
18
|
+
[project.optional-dependencies]
|
|
19
|
+
dev = [
|
|
20
|
+
"pytest>=8.3,<10",
|
|
21
|
+
"pytest-cov>=6,<7",
|
|
22
|
+
"ruff>=0.12,<1"
|
|
23
|
+
]
|
|
24
|
+
# planfile-backed task registry (todo-agent tickets ...)
|
|
25
|
+
planfile = [
|
|
26
|
+
"planfile>=0.1.111"
|
|
27
|
+
]
|
|
28
|
+
# urirun-backed process monitoring (todo-agent process ...)
|
|
29
|
+
urirun = [
|
|
30
|
+
"urirun>=0.4.190"
|
|
31
|
+
]
|
|
32
|
+
|
|
33
|
+
[project.scripts]
|
|
34
|
+
todo-agent = "todo_agent.cli:main"
|
|
35
|
+
|
|
36
|
+
[tool.setuptools.packages.find]
|
|
37
|
+
where = ["src"]
|
|
38
|
+
|
|
39
|
+
[tool.pytest.ini_options]
|
|
40
|
+
testpaths = ["tests"]
|
|
41
|
+
addopts = "-ra --strict-markers"
|
|
42
|
+
|
|
43
|
+
[tool.ruff]
|
|
44
|
+
target-version = "py311"
|
|
45
|
+
line-length = 120
|
|
46
|
+
|
|
47
|
+
[tool.ruff.lint]
|
|
48
|
+
select = ["E", "F", "I", "B", "UP", "SIM"]
|
|
49
|
+
ignore = ["E501"]
|