robert-github-agent 0.1.0b1__py3-none-any.whl

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.
Files changed (111) hide show
  1. robert_agent/__init__.py +1 -0
  2. robert_agent/acceptance.py +394 -0
  3. robert_agent/acceptance_suite.py +287 -0
  4. robert_agent/audit_result.py +501 -0
  5. robert_agent/authorize.py +117 -0
  6. robert_agent/board.py +538 -0
  7. robert_agent/chat_status.py +338 -0
  8. robert_agent/cli/__init__.py +1 -0
  9. robert_agent/cli/exit_codes.py +5 -0
  10. robert_agent/cli/main.py +535 -0
  11. robert_agent/cli/output.py +20 -0
  12. robert_agent/common.py +6 -0
  13. robert_agent/controlled_e2e_acceptance.py +394 -0
  14. robert_agent/daemon.py +607 -0
  15. robert_agent/daemon_state.py +319 -0
  16. robert_agent/diagnostics.py +119 -0
  17. robert_agent/discover.py +775 -0
  18. robert_agent/dispatch.py +217 -0
  19. robert_agent/doctor.py +94 -0
  20. robert_agent/github_api.py +12 -0
  21. robert_agent/init_config.py +126 -0
  22. robert_agent/integrations/__init__.py +1 -0
  23. robert_agent/integrations/openclaw.py +285 -0
  24. robert_agent/live_discovery_acceptance.py +70 -0
  25. robert_agent/live_worker_acceptance.py +363 -0
  26. robert_agent/live_worktree_acceptance.py +344 -0
  27. robert_agent/loop_engine.py +285 -0
  28. robert_agent/memory_curator.py +105 -0
  29. robert_agent/migrate.py +157 -0
  30. robert_agent/notify.py +74 -0
  31. robert_agent/paths.py +16 -0
  32. robert_agent/production_write_canary.py +254 -0
  33. robert_agent/project_memory.py +503 -0
  34. robert_agent/publish.py +743 -0
  35. robert_agent/publish_dedupe_acceptance.py +270 -0
  36. robert_agent/redaction.py +41 -0
  37. robert_agent/render_prompt.py +544 -0
  38. robert_agent/resource_files.py +8 -0
  39. robert_agent/resources/__init__.py +1 -0
  40. robert_agent/resources/acceptance-matrix.md +120 -0
  41. robert_agent/resources/classifier.md +19 -0
  42. robert_agent/resources/command-matrix.md +38 -0
  43. robert_agent/resources/config.example.yml +20 -0
  44. robert_agent/resources/db/migrations/001_legacy_dd_to_robert.sql +14 -0
  45. robert_agent/resources/db/schema.sql +479 -0
  46. robert_agent/resources/failure-modes.md +36 -0
  47. robert_agent/resources/fixtures/actor-permission.json +1 -0
  48. robert_agent/resources/fixtures/discovery.json +1 -0
  49. robert_agent/resources/fixtures/redaction.json +1 -0
  50. robert_agent/resources/fixtures/review-followup.json +1 -0
  51. robert_agent/resources/fixtures/worker-results.json +1 -0
  52. robert_agent/resources/fixtures/workstreams.json +1 -0
  53. robert_agent/resources/github-events.md +77 -0
  54. robert_agent/resources/kanban-control.md +165 -0
  55. robert_agent/resources/redaction.md +29 -0
  56. robert_agent/resources/result-contract.md +56 -0
  57. robert_agent/resources/routes.yml +82 -0
  58. robert_agent/resources/schemas/config.schema.json +123 -0
  59. robert_agent/resources/schemas/event.schema.json +18 -0
  60. robert_agent/resources/schemas/result.schema.json +99 -0
  61. robert_agent/resources/schemas/route.schema.json +23 -0
  62. robert_agent/resources/schemas/snapshot.schema.json +17 -0
  63. robert_agent/resources/schemas/task.schema.json +15 -0
  64. robert_agent/resources/trust-model.md +16 -0
  65. robert_agent/resources/worker-prompt.md +121 -0
  66. robert_agent/resources/worker-protocol.md +47 -0
  67. robert_agent/resources/workflow.yml +50 -0
  68. robert_agent/resources/workstream-model.md +17 -0
  69. robert_agent/route.py +232 -0
  70. robert_agent/route_config.py +64 -0
  71. robert_agent/run_once.py +5375 -0
  72. robert_agent/runtime_knowledge.py +392 -0
  73. robert_agent/service.py +161 -0
  74. robert_agent/skills.py +28 -0
  75. robert_agent/status.py +1051 -0
  76. robert_agent/storage.py +376 -0
  77. robert_agent/summarize.py +100 -0
  78. robert_agent/supervise.py +72 -0
  79. robert_agent/usage.py +192 -0
  80. robert_agent/validate_config.py +616 -0
  81. robert_agent/wakeup.py +261 -0
  82. robert_agent/web.py +2893 -0
  83. robert_agent/web_assets/board.css +255 -0
  84. robert_agent/web_assets/board.html +165 -0
  85. robert_agent/web_assets/board.js +660 -0
  86. robert_agent/web_assets/github-shell.css +122 -0
  87. robert_agent/web_assets/index.html +103 -0
  88. robert_agent/web_assets/operations.css +168 -0
  89. robert_agent/web_assets/workbench.css +131 -0
  90. robert_agent/web_assets/workbench.js +581 -0
  91. robert_agent/work_items.py +1016 -0
  92. robert_agent/workbench.py +701 -0
  93. robert_agent/worker/__init__.py +1 -0
  94. robert_agent/worker/heartbeat.py +190 -0
  95. robert_agent/worker/result.py +321 -0
  96. robert_agent/worker/snapshot.py +98 -0
  97. robert_agent/worker_adapters/__init__.py +138 -0
  98. robert_agent/worker_adapters/cbc.py +68 -0
  99. robert_agent/worker_adapters/codex.py +56 -0
  100. robert_agent/worker_adapters/command.py +33 -0
  101. robert_agent/worker_adapters/tcodex.py +56 -0
  102. robert_agent/worker_heartbeat.py +6 -0
  103. robert_agent/worker_result.py +6 -0
  104. robert_agent/worker_snapshot.py +6 -0
  105. robert_agent/workstream.py +55 -0
  106. robert_agent/worktree.py +297 -0
  107. robert_github_agent-0.1.0b1.dist-info/METADATA +217 -0
  108. robert_github_agent-0.1.0b1.dist-info/RECORD +111 -0
  109. robert_github_agent-0.1.0b1.dist-info/WHEEL +4 -0
  110. robert_github_agent-0.1.0b1.dist-info/entry_points.txt +2 -0
  111. robert_github_agent-0.1.0b1.dist-info/licenses/LICENSE +201 -0
@@ -0,0 +1,120 @@
1
+ # Acceptance Matrix
2
+
3
+ This matrix is the operator-facing checklist for whether the Robert can
4
+ collaborate with ordinary human developers across GitHub issues, DD-created PRs,
5
+ and third-party PRs.
6
+
7
+ Current scope: these rows are fixture-backed control-plane acceptance tests.
8
+ They prove event normalization, authorization, routing, workstream/task state,
9
+ prompt shape, result audit, publication gating, and operator evidence. This is
10
+ not yet a live GitHub/worker acceptance test; live credentials, real
11
+ repositories, real checkouts, real worktrees, and real worker execution must be proven separately
12
+ before claiming production readiness.
13
+
14
+ | Scenario ID | Human workflow | Expected agent behavior | Proof |
15
+ | --- | --- | --- | --- |
16
+ | issue-assignment-analysis | A trusted user assigns an issue or mentions the DD account for analysis. | Create an issue workstream, route to `comment-analysis`, avoid a worktree, and render the accepted event into the worker prompt. | `tests/dd_github_agent/test_workflow_matrix.py::WorkflowMatrixTests.test_issue_assignment_for_analysis_creates_comment_workflow` |
17
+ | issue-assignment-new-pr | A trusted user asks the DD account to fix an issue. | Create a `new-pr` task, accept worker results with `push_existing_pr` then `open_pr` only after audit, publish-gated completion, and materialize a DD PR workstream linked back to the issue. | `tests/dd_github_agent/test_workflow_matrix.py::WorkflowMatrixTests.test_issue_assignment_bugfix_result_materializes_dd_pr_workflow` |
18
+ | issue-active-followup-context | A repository member comments with extra context while an issue task is active. | Do not start a second active task; attach the event as context on the existing workstream. | `tests/dd_github_agent/test_workflow_matrix.py::WorkflowMatrixTests.test_issue_followup_comment_stays_on_existing_workflow_context` |
19
+ | dd-created-pr-review-followup | A reviewer comments on a DD-created PR and asks for follow-up fixes. | Route to `update-existing-pr`, keep the PR on its own mainline, reuse the existing PR branch, include the review event in the prompt, and require a response comment for the review report. | `tests/dd_github_agent/test_workflow_matrix.py::WorkflowMatrixTests.test_dd_pr_followup_routes_to_existing_pr_workflow` |
20
+ | multi-repo-account-cycle | One GitHub account receives actionable events from two configured repos with different trusted actors. | One `run_once` attributes notifications by `repository.full_name`, applies each repo's trust policy, prepares work in the matching local checkout, and reports repo-level partial failures without blocking other repos. | `tests/dd_github_agent/test_run_once.py::RunOnceDryRunTests.test_run_once_processes_two_repos_with_repo_specific_trust` |
21
+ | pr-reviewer-assignment | A trusted user requests DD review on a PR through GitHub reviewer assignment. | Resolve the notification through the PR timeline, route to `review-pr`, create a PR source review worktree from `pull/<number>/head`, require `fast-review-github-pr`, and allow only a planned comment action. | `tests/dd_github_agent/test_workflow_matrix.py::WorkflowMatrixTests.test_review_request_creates_source_review_worktree` |
22
+ | third-party-pr-question | A trusted user asks the DD account a question on someone else's PR. | Route to `review-comment`, allow comments only, and avoid opening or updating a DD PR. | `tests/dd_github_agent/test_workflow_matrix.py::WorkflowMatrixTests.test_third_party_pr_question_routes_to_review_comment_workflow` |
23
+ | third-party-pr-fix-request | A trusted user asks the DD account to fix someone else's PR. | Route to `review-comment`, allow comments only, avoid preparing a worktree, and avoid opening or updating a DD PR. | `tests/dd_github_agent/test_workflow_matrix.py::WorkflowMatrixTests.test_third_party_pr_fix_request_stays_comment_only` |
24
+ | trusted-waiting-user-resume | The agent asks a clarifying question, members add context, then a trusted actor confirms implementation. | Keep the original task waiting only after the question is published, collect member context without resuming, then create a child implementation task when a trusted actor replies. | `tests/dd_github_agent/test_workflow_matrix.py::WorkflowMatrixTests.test_trusted_reply_resumes_waiting_for_user_workflow` |
25
+
26
+ ## Operator Evidence
27
+
28
+ The workflow matrix proves behavior; operator evidence proves a stuck run can be
29
+ followed without manual SQLite archaeology. These checks live mostly in
30
+ `tests/dd_github_agent/test_operational_commands.py` and cover:
31
+
32
+ - `operator_alerts` and `operator_next_steps` for attention tasks, stale workers,
33
+ publish waits, publish failures, skipped publication, pending actor permission,
34
+ and pending authorization lookup.
35
+ - Summary counters for rejected worker results, publish backlog, skipped publish
36
+ actions, pending actor-permission events, and pending authorization events.
37
+ - Recent route decisions, worker results, used skills, event-flow counts, run
38
+ steps, notifications, and artifact paths.
39
+ - Non-trusted owner/member/collaborator context on an inactive known non-DD-PR
40
+ workstream is recorded as evidence. Trusted actor context can reopen the
41
+ workstream, and DD-derived PR follow-up with origin metadata can create a
42
+ constrained update task for that PR.
43
+
44
+ ## Remaining Live Acceptance
45
+
46
+ Before calling the full GitHub collaboration goal complete, run and document a
47
+ live acceptance pass that covers at least:
48
+
49
+ 1. Real GitHub discovery with `gh` authentication.
50
+ 2. Real worktree preparation against a local checkout.
51
+ 3. Real worker launch through each configured named worker's adapter and
52
+ command, including at least one route-selected non-default worker.
53
+ 4. Real publication or explicitly dry-run-safe publication of comments/PRs.
54
+ 5. Retry/dedupe behavior against existing `robert-comment` and `robert-workstream`
55
+ markers.
56
+
57
+ Use `scripts/acceptance.py --config <config>` as the first live-readiness
58
+ preflight. It is read-only: it checks the config, repo checkout, worktree root,
59
+ current control-plane dispatch state, `gh` availability/authentication, and the
60
+ configured worker command without publishing GitHub content or launching a
61
+ worker. A passing preflight only proves the local prerequisites are ready.
62
+
63
+ Use `scripts/acceptance_suite.py --config <config>` as the operator-facing
64
+ summary. It runs the safe acceptance checks, aggregates their evidence, and
65
+ keeps the overall status `incomplete` until an explicitly approved production
66
+ GitHub write canary has been run. Add `--include-live-worker` when the configured
67
+ worker command should be exercised as part of the suite.
68
+ Add `--production-canary-target-url <github-issue-or-pr-url>` to have the suite
69
+ prepare a no-write canary plan and exact follow-up command; this still does not
70
+ write GitHub content.
71
+ After an approved canary has published a comment, add
72
+ `--production-canary-evidence-url <github-comment-url>` plus the same
73
+ `--production-canary-marker-id` to verify the live comment by read-only `gh api`
74
+ lookup and let the suite report `completed`.
75
+
76
+ Use `scripts/controlled_e2e_acceptance.py --config <config>` to prove a
77
+ controlled issue-to-PR workflow can complete through the real `run_once`
78
+ orchestrator. It uses an isolated local checkout, fixture discovery, real git
79
+ worktree creation, a mock worker that records a structured `open_pr` result,
80
+ normal audit, fake GitHub PR publication, and final task/workstream
81
+ finalization. It does not write production GitHub content, but it is the closest
82
+ safe end-to-end acceptance pass for the full local control plane.
83
+
84
+ Use `scripts/live_discovery_acceptance.py --config <config>` to prove real
85
+ GitHub discovery can run through `gh` without mutating the control-plane
86
+ database. It runs the live assigned issue search, mention search, notification
87
+ lookup, and event normalization path, then reports counts and sample normalized
88
+ events without authorizing, routing, or dispatching work.
89
+
90
+ Use `scripts/live_worker_acceptance.py --config <config>` after preflight to
91
+ prove the configured worker command can run against an isolated control-plane
92
+ database. The script creates a temporary config/data directory, dispatches a
93
+ safe analysis fixture through the real worker command, waits for a structured
94
+ worker result, then runs audit and publication in dry-run mode. This covers live
95
+ worker launch plus dry-run-safe publication evidence without modifying the
96
+ operator's production `dd.sqlite3` or writing GitHub content. It still does not
97
+ replace a real GitHub discovery/worktree/publication pass for rows 1, 2, and 5.
98
+
99
+ Use `scripts/live_worktree_acceptance.py --config <config>` to prove the
100
+ worktree path with real git commands. The script creates an isolated bare
101
+ upstream and local checkout, routes a safe `new-pr` fixture, runs
102
+ `git fetch upstream <base>` and `git worktree add`, verifies the resulting
103
+ branch/worktree, and terminates its mock worker. It does not touch the
104
+ operator's production checkout or write GitHub content, so it proves row 2 as a
105
+ controlled local-git acceptance pass.
106
+
107
+ Use `scripts/publish_dedupe_acceptance.py` to prove retry-safe publication
108
+ dedupe without writing GitHub content. It creates an isolated control-plane
109
+ database with accepted comment and open-PR actions, simulates GitHub lookup
110
+ responses that already contain matching `robert-comment` and `robert-workstream`
111
+ markers, and verifies the publisher marks both actions published/deduplicated
112
+ without issuing create-comment or create-PR commands.
113
+
114
+ Use `scripts/production_write_canary.py --target-url <github-issue-or-pr-url>`
115
+ to prepare an isolated canary database and dry-run publication plan. It exits
116
+ without calling `gh` unless `--confirm-github-write` is present. With explicit
117
+ confirmation, it publishes exactly one `robert-comment` marker-protected comment, or
118
+ deduplicates an existing comment with the same marker, through the normal
119
+ `publish.py` audited action path. Run this only against an explicitly approved
120
+ target issue or PR.
@@ -0,0 +1,19 @@
1
+ # Classifier
2
+
3
+ Classification turns authorized GitHub events into one of the fixed output types:
4
+
5
+ - `comment_analysis`
6
+ - `new_pr`
7
+ - `update_existing_pr`
8
+ - `review_comment`
9
+ - `classification_result`
10
+ - `waiting_for_user`
11
+
12
+ High-confidence bug fixes and small changes can route directly to implementation. Requirement analysis and broad design discussion should route to `comment_analysis` unless a trusted actor clearly approves implementation. Low-confidence inputs must route to a lightweight classification worker or to `waiting_for_user`.
13
+
14
+ When a `classification_result` decides that work should continue, it must
15
+ return a structured `recommended_route` such as `new-pr`. The agent uses that
16
+ field to create the follow-up task; free-form handoff text is not a routing
17
+ signal.
18
+
19
+ Routes are data, not dispatcher code. Add or reorder route entries in `routes.yml`; keep the agent orchestration independent from route-specific keywords.
@@ -0,0 +1,38 @@
1
+ # Command Matrix
2
+
3
+ All commands print one JSON object to stdout. Exit code `0` means success, `2` means retryable failure, `3` means config or input failure, `4` means security refusal, and other non-zero exits mean unclassified failure.
4
+
5
+ | Command | Purpose |
6
+ | --- | --- |
7
+ | `acceptance.py` | Check live GitHub collaboration readiness gates without writing to GitHub or launching workers. |
8
+ | `acceptance_suite.py` | Aggregate safe acceptance checks and explicitly report the remaining production GitHub write canary gap. |
9
+ | `controlled_e2e_acceptance.py` | Run a fully isolated issue-to-PR workflow through real `run_once`, real git worktree creation, mock worker result recording, audit, fake GitHub PR publication, and finalization. |
10
+ | `live_discovery_acceptance.py` | Run read-only live GitHub discovery through `gh` without writing the control-plane database or dispatching workers. |
11
+ | `live_worker_acceptance.py` | Run an isolated fixture-backed live worker dispatch, then audit and dry-run publication without writing GitHub content. |
12
+ | `live_worktree_acceptance.py` | Run real git worktree preparation in an isolated local checkout without touching the operator repository or GitHub. |
13
+ | `production_write_canary.py` | Plan or, with explicit `--confirm-github-write`, publish one marker-protected canary comment to a specified GitHub issue or PR through the normal audited publisher path. |
14
+ | `init_config.py` | Create a missing runtime config from `references/config.example.yml` without overwriting an existing config. |
15
+ | `run_once.py` | Execute one agent cycle from `workflow.yml`. |
16
+ | `loop_engine.py` | Execute bounded repeated `run_once.py` cycles while durable local work remains, then stop with a structured reason. |
17
+ | `daemon.py` | Run the foreground resident Robert daemon. It owns a daemon lease, drains local runnable work through `loop_engine.py --skip-external`, and runs conservative rate-limit-aware live `run_once.py` polls. Use the native user-service commands for unattended operation. |
18
+ | `status.py` | Print compact read-only JSON for global status, recent/latest runs, a task, attempt, workstream, event/comment lookup, event search, source task view, or artifact tail so agents do not need ad hoc SQLite queries. |
19
+ | `chat_status.py` | Format the read-only dashboard payload as chat-ready Markdown inside a JSON envelope for OpenClaw slash commands or keyword triggers. |
20
+ | `validate_config.py` | Validate config, repo entries, skill index, and local command availability. |
21
+ | `discover.py` | Collect GitHub issue, PR, review, assignment, mention, and notification events. |
22
+ | `authorize.py` | Apply trusted trigger and accepted context actor gates. |
23
+ | `route.py` | Convert authorized events into task routes and expected outputs. |
24
+ | `workstream.py` | Attach sources and events to serial workstreams. |
25
+ | `worktree.py` | Prepare or reuse worktrees and branches. New branches assume an `upstream` remote and `upstream/<base_branch>` start point; existing PR updates reuse the discovered head branch; reviewer-assignment source reviews fetch `pull/<number>/head` into a local `review/pr-...` branch. |
26
+ | `render_prompt.py` | Render worker prompt artifacts. |
27
+ | `memory_curator.py` | Propose, list, show, approve, and reject human-reviewed runtime knowledge candidates from project memory. |
28
+ | `dispatch.py` | Start or dry-run worker attempts with the configured worker command. |
29
+ | `worker_snapshot.py` | Record a worker phase, status, summary, and next step through the internal worker runtime. |
30
+ | `worker_heartbeat.py` | Run a long worker command while recording heartbeat snapshots. |
31
+ | `worker_result.py` | Record a worker's structured final result and planned GitHub actions. |
32
+ | `supervise.py` | Inspect active attempts, stale workers, timeouts, and cancel events. |
33
+ | `audit_result.py` | Audit worker-planned GitHub actions against allowed actions before publication. |
34
+ | `publish.py` | Publish audited GitHub actions and record publish status. |
35
+ | `notify.py` | Record and send local notifications. |
36
+ | `publish_dedupe_acceptance.py` | Verify comment and PR idempotency marker dedupe with an isolated database and simulated GitHub lookup responses. |
37
+ | `summarize.py` | Summarize one cycle and recent workstreams. |
38
+ | `web.py` | Serve the read-only HTML dashboard from `dd.sqlite3`; `/data.json`, `/history`, and `--json` expose the raw status payload, and `/artifact.txt` previews registered text artifacts. |
@@ -0,0 +1,20 @@
1
+ version: 1
2
+ data_dir: ~/.local/share/robert
3
+ database: robert.sqlite3
4
+
5
+ github:
6
+ account: robert-bot
7
+ poll_seconds: 300
8
+
9
+ skills:
10
+ search_paths: []
11
+
12
+ workers:
13
+ default:
14
+ adapter: codex
15
+ command: codex
16
+ model: default
17
+ effort: default
18
+
19
+ routes: {}
20
+ repos: []
@@ -0,0 +1,14 @@
1
+ CREATE TABLE IF NOT EXISTS schema_migrations (
2
+ version INTEGER PRIMARY KEY,
3
+ name TEXT NOT NULL,
4
+ checksum TEXT NOT NULL,
5
+ applied_at TEXT NOT NULL
6
+ );
7
+
8
+ INSERT INTO schema_migrations(version, name, checksum, applied_at)
9
+ VALUES (
10
+ 2,
11
+ 'legacy-dd-to-robert',
12
+ 'legacy-dd-to-robert-v1',
13
+ datetime('now')
14
+ );